Atlassian Jira

This Integration allows full access to the Jira Rest API from your application. Fusebit's multi-tenant approach makes it easy for you to manage multiple Jira connections on behalf of your app's users. Our Node.js-based programming model and lightweight deployment story make it easy to customize the Integration with any necessary business logic.

Getting Started

  1. Use the Fusebit Management PortalFusebit Management Portal - The Fusebit Management Portal enables you to easily setup and manage all your integrations in one place. Link: https://manage.fusebit.io to create an account and log in.
  2. Create a new Integration using one of our Atlassian Jira templates
  1. You will then be able to run the Integration, download it's code, modify it, and deploy your changes. Detailed instructions on how to get started with an Integration are available here.

Invoking the Jira API

The Integration template comes pre-configured with some example calls that invoke Jira's API, for example:

const resources = await atlassianClient.getAccessibleResources();

const jiraCloud = resources.find((resource) => resource.scopes.includes('read:jira-user'));
const jira = atlassianClient.jira(jiraCloud.id);

const result = await jira.get('/search');

ctx.body = {
  message: `Found ${result.total} issues in Jira Cloud ${resources[0].id}`,
};

Since the official Atlassian Jira SDK has not been updated in some time, Fusebit provides one for you. The atlassianClient object provided by Fusebit is essentially a thin client that sits on top of the Atlassian REST API. Here is the reference documentation for Jira.

Fusebit ensures the above SDK object is already bootstrapped with the Jira credentials of the user invoking the integration. You do not need to worry about obtaining an access token or refresh token for them -- Fusebit does that for you automatically.

Creating your own Jira App

Out of the box, Fusebit's Jira Integration uses our own demonstration application from Atlassian. This is only done to make it easier for you to get started, however you will need to register your own App for use in Production. Before you can distribute your App, you need to go through Atlassian's manual review process. Read through this guide to learn more about the process and to stay on top of any approval requirements.

  1. Go to your Atlassian Developer Console and create a Developer Account. Once created, select Create app > OAuth 2.0 Integration. You will be taken to the main Overview screen for your app
  1. If the method(s) you want to invoke against the Jira API require certain permissions see here, add the appropriate scopes under Permissions.

The User REST API and Jira platform REST API products are necessary to run the Fusebit provided example.

🚧

When switching a Connector to a different Atlassian App, all IdentityIdentity - An identity is a unique relationship one of your customers has with a service. An identity can be used by multiple integrations to act on that service on behalf of your customer. objects associated with that Connector will be deleted. Your users will need to re-authenticate against Atlassian after you make the change.

  1. Back in the Fusebit Portal, find the Integration you would like to connect to the new Jira App you just created. Select the ConnectorConnector - A connector is the package from Fusebit that manages the relationship between one or more integrations and a specific service. One of the most common types of connector is an OAuth connector, which takes care of the OAuth negotiation between your customers and the service you're integrating, so that you don't have to! tied to that integration. Select Enable Production Credentials in the Connector Configuration and then paste in the app scopes you just created.
  1. Next, from the App Details > Authentication Details section for your Jira app, retrieve the Client ID and Client Secret and paste them into the respective fields in the Fusebit Connector.
  1. Next, retrieve the URL provided by Fusebit under OAuth2 Redirect URL and paste it into your Jira App under Authorization > *Callback URL.
  1. Finally, enable your app for public distribution by navigating to Distribution. You may have to raise a ticket to their Marketplace Support Service Desk to get the review process started.

πŸ‘

Good Job!

Now, any time a new user installs your Integration, you should now see your Atlassian App information displayed during the authorization step.

Also, now that you've configured your own app, you can also leverage our Webhooks SDK to receive events from Jira!

Receiving events from Jira

With this Jira App configuration, your Fusebit Integration will be able to sync any updates directly with/from
Jira. But you will likely also want to have your application respond to events from Jira (on behalf of your users) without having to poll for changes first.

We can achieve that by leveraging Atlassian's Dynamic Webhooks API.

To set this up, you will need do to the following in your integration:

  1. Create an endpoint for your app where your tenants can choose which project and events they want to be notified for. This will automatically register a webhook with Fusebit on behalf of your tenant for your app.
router.post('/api/tenant/:tenantId/webhooks', integration.middleware.authorizeUser('install:get'), async (ctx) => {

  const atlassianClient = await integration.tenant.getSdkByTenant(ctx, connectorName, ctx.params.tenantId);
  const resources = await atlassianClient.getAccessibleResources();
  const jiraCloud = resources.find((resource) => resource.scopes.includes('read:jira-user'));
  
  // Define which project and what events you are interested in
  // https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-webhooks/#api-rest-api-3-webhook-post
  const webhookDetails = [ { 
    "jqlFilter": "project = demo",
    "events": [ "jira:issue_created", "jira:issue_updated" ] } ];
  
  // Use our Fusebit Webhook SDK to register webhooks, we will automatically configure the Webhook URL for you
  const postWebhook = await atlassianClient.webhook.register(jiraCloud.id, webhookDetails);
  console.log(postWebhook);
});
  1. Set up a listener in your integration.
integration.event.on('/:componentName/webhook/:eventtype', async (ctx) => {

  console.log ('There is a new update to your Jira Issue!)
  
  // Insert your code here and invoke your backend to perform an action using
  // the event information provided in `ctx.req.body`
           
});

Helpful References

Want to learn more about how to work with Jira Cloud REST API? Here's some helpful references:


Did this page help you?