@axway-api-builder-ext/api-builder-plugin-fc-jira

API-Builder JIRA Cloud-Platform Connector

Use this connector to communicate with the JIRA Cloud-Platform and make it part of your API-Management platform. It is based on the JIRA Cloud-Platform API (https://developer.atlassian.com/cloud/jira/platform/rest/v2/) and works On-Premise or with the Cloud-Instance.

Configuration

After installing and restarting your API-Builder project you get the following connector:

Which can be used to communicate with your JIRA-Instance to Create, Update issues.

Setup JIRA Cloud Platform Host and Login

In order to use the plugin you need to configure your JIRA-Account details in the configuration file: jira-jira-cp-connector.default.js.
We recommend to setup your configuration in a environmentalized way keeping sensitive information away from the source-code repository..

module.exports = {
	// The configuration settings for the OAS2 flow-node: JIRA Cloud Platform API
	pluginConfig: {
		'@axway-api-builder-ext/api-builder-plugin-fc-jira': {
			'jira-cp-connector': {
				// It is possible to override URI options when constructing
				// outbound requests to this service.
				uri: {
					// protocol: 'https',
					// host: 'hostname',
					// port: 443,
					// basePath: '/api'
				}
			}
		}
	},
	// The following authorization credentials needed to use this service.
	// Please follow this guide to manually configure these credentials:
	// https://docs.axway.com/bundle/api-builder/page/docs/developer_guide/credentials/index.html
	authorization: {
		credentials: {
			'JIRA Cloud Platform API HTTP Basic Authentication': {
				type: 'basic',
				username: null,
				password: null
			}
		}
	}
};

Get JIRA Authentication credentials

At the moment the plugin only supports HTTP-Basic based authentication. How to obtain the required API-Token you can read in the official documentation:
https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/
Details how to setup the HTTP-Basic credentials in API-Builder:
https://docs.axway.com/bundle/api-builder/page/docs/developer_guide/credentials/configuring_credentials/http_basic_credentials/index.html

Once the configuration is complete, the JIRA flow can be used.

Usage

The JIRA-Connector is based on the JIRA REST-API, hence understanding how the API works is a good start. You may install and use the Atlassian Developer Toolbox to learn the how the REST-API works.

A general recommendation during development / integration is to create entities likes issues in JIRA using the UI and read them to understand the structure.

Examples

Method Create issue

Using the project id and issue type id:
Body:

{
    "fields": {
       "project":
       {
          "id": "10000"
       },
       "summary": "No REST for the Wicked.",
       "description": "Creating of an issue using IDs for projects and issue types using the REST API",
       "issuetype": {
          "id": "10005"
       }
   }
}

Using the project key and issue type name:
Body:

{
    "fields": {
       "project":
       {
          "key": "TP"
       },
       "summary": "No REST for the Wicked.",
       "description": "Creating of an issue using IDs for projects and issue types using the REST API",
       "issuetype": {
          "name": "Bug"
       }
   }
}

More examples can be found here: https://developer.atlassian.com/server/jira/platform/jira-rest-api-examples/

Troubleshot

Error: 403 Basic auth with password is not allowed on this instance

This error message is a bit misleading, as HTTP-Basic Auth still works, but you have to use an API-Token instead of your passwrd. Please double check you are using a valid API-Token. This error message appears, when the authentication fails using basic auth.

Compatibility

Tested with JIRA Cloud Platform 8.5.1

Changelog

See Change-Log

Limitations/Caveats

• Currently support for JIRA-Issues only

Contributing

Please read Contributing.md for details on our code of conduct, and the process for submitting pull requests to us.

Team

Axway Team

License

Apache License 2.0