Chapter 14. Connecting to Jira

In an integration, you can connect to a Jira server to obtain, create, or update issues. Jira is a tool for planning, tracking, and managing software development projects. Each Jira environment allows customization of the workflow, which has an effect on the details for connecting to Jira in an integration. Consulting with your Jira administrator should clarify the details.

The following topics provide information and procedures for creating integrations that connect to a Jira server:

14.1. Registering Fuse Online with a Jira server that uses OAuth

An integration can connect to a Jira server that uses the OAuth protocol to authenticate access. To enable this, register your Fuse Online environment as a Jira client application. Jira client applications are also referred to as Jira consumers. In other words, your Fuse Online environment is a Jira consumer.

Note

Registration is not required when a Jira server uses only basic authentication.

Follow the procedure here to obtain the Jira OAuth credentials that you need to create a Fuse Online connection to Jira. For more details about registering Jira consumers, including a tutorial that takes you through the steps with a sample server, see the Jira documentation about OAuth for REST APIs

After you register Fuse Online with a Jira server, you use Fuse Online to create a connection to that Jira server. Any number of integrations can use the same Jira connection. However, if you want to create another Jira connection, you must obtain another set of OAuth credentials by repeating the registration procedure provided here.

Overview of the main steps

The main steps in the registration procedure are:

  • Obtain the Atlassian command line application that enables you to obtain OAuth credentials.
  • Run the downloaded application to create a config.properties file.
  • Create a public/private key pair, which Fuse Online uses to access a Jira server.
  • Edit the config.properties file to update some of its values.
  • Configure your Jira server to recognize your Fuse Online environment as a consumer application.
  • Obtain a Jira access token that Fuse Online needs to access data on your Jira server.

Each of these steps has several substeps and the procedure below provides the details.

Prerequisites

  • Jira server administration permissions.
  • Familiarity with command line interfaces.

Procedure

  1. Obtain the Atlassian command line application that enables you to obtain OAuth credentials:

    1. Go to the atlassian-oauth-examples page.
    2. In the left panel, at the bottom, click Downloads.
    3. On the Downloads page, click Download repository.
    4. Extract the file into a directory that you choose.
  2. Run the downloaded application to create a config.properties file for OAuth credentials:

    1. In a terminal, navigate to the directory that contains the extracted content.
    2. Change to the java directory and build the client:

      cd atlassianlabs-atlassian-oauth-examples-dd0264cad043/java
      mvn clean compile assembly:single
    3. Change to the target directory and generate the config.properties file:

      cd target
      java -jar OAuthTutorialClient-1.0.jar requestToken

    You can ignore the connection exception. In the target directory, there is now a config.properties file that contains some temporary keys.

  3. Generate a public/private key pair that Fuse Online needs for access to a Jira server. While you can run these commands anywhere, the first instruction directs you to a particular directory for convenience:

    1. Navigate to the directory that contains the downloaded application.
    2. Generate a private key:

      openssl genrsa -out jira_privatekey.pem 1024
    3. Obtain a public key:

      openssl req -newkey rsa:1024 -x509 -key jira_privatekey.pem -out jira_publickey.cer -days 365

      This command prompts you to enter information about your Fuse Online environment. Alternatively, to avoid responding to prompts, add the -subj option to the command. For example, at the end of the command line above, add something like this:

      -subj "/C=US/ST=New York/L=New York/O=MyCompany Ltd./OU=IT/CN=mysubdomain.mydomain.com"
    4. Export the keys:

      openssl pkcs8 -topk8 -nocrypt -in jira_privatekey.pem -out jira_privatekey.pcks8
      openssl x509 -pubkey -noout -in jira_publickey.cer  > jira_publickey.pem

      You now have four files:

      jira_privatekey.pcks8
      jira_privatekey.pem
      jira_publickey.cer
      jira_publickey.pem

    5. Obtain the private key, without the header, line breaks, and footer:

      cat jira_privatekey.pcks8 | grep -v 'PRIVATE'|awk '{print}' ORS=''
    6. Copy the private key to the clipboard.
  4. Edit the config.properties file:

    1. Navigate to the java/target directory that contains the config.properties file and open the file for editing.
    2. In the config.properties file, replace the private key with the private key that you copied to the clipboard.
    3. Change the jira_home setting to the URL for your Jira server. Be sure to specify https if your Jira server uses https. Also, you need to escape the colon. For example:

      jira_home=https\://issues.mycompany.org
    4. Change the consumer_key setting to Fuse Online App. For example:

      consumer_key=Fuse Online App
    5. Save and close the config.properties file.
  5. Configure your Jira server to recognize your Fuse Online environment as a consumer application. You must be logged in to the Jira server as an administrative user.

    1. Select Settings ( cog ) > Products > Application links.
    2. In the Create new link input field, enter any URL, for example, enter: https://example.com.

      This displays a dialog that indicates that no response was received, which is okay because only one-way communication is required.

    3. Click Continue to display the Link applications dialog. In this dialog:

      1. In the Consumer Key field, enter Fuse Online App.
      2. At the bottom, select Create incoming link.
      3. In each of the other fields, enter any value. Each field requires a value. The value that you enter does not matter because no response is needed.
      4. Click Continue to display another dialog.
      5. In the Consumer Key field, enter Fuse Online App.
      6. In the Consumer Name field, enter Fuse Online App.
      7. In the Public Key field, paste the public key that is in the jira_publickey.pem file. Be sure to paste only the key without the header and footer. To display the key so that you can copy it, in the directory that contains the jira_publickey.pem file, enter cat jira_publickey.pem.
      8. Click Continue.
  6. Obtain a Jira access token that Fuse Online needs to access data on your Jira server. In the Jira OAuth documentation that is linked to at the beginning of this procedure, this step is referred to as "The Oauth dance" because there are exchanges among Fuse Online, the Jira server, and the Jira administrator.

    1. Navigate to the java/target directory in the directory that contains the command line application that you downloaded in the first step of this whole procedure.
    2. Obtain a request token from your Jira server:

      java -jar OAuthTutorialClient-1.0.jar requestToken

      This displays something like:

      Token:          ec3dj4byySM5ek3XW7gl7f4oc99obAlo
      Token Secret:   OhONj0eF7zhXAMKZLbD2Rd3x7Dmxjy0d
      Retrieved request token. go to https://jira101.atlassian.net/plugins/servlet/oauth/authorize?oauth_token=ec3dj4byySM5ek3XW7gl7f4oc99obAlo to authorize it
    3. In another browser tab, go to the URL provided in that output. That page welcomes you to Jira and prompts you to allow access to the Fuse Online App.
    4. Click Allow, which displays an Access Approved page with a verification code.
    5. Copy the verification code to the clipboard and paste it somewhere so that you can easily retrieve it.
    6. Obtain an access token by invoking a command such as the following. In the following command line example, the last value is a verification code. In the command that you run, replace the example verification code with the verification code that you copied in the previous step. For example:

      java -jar OAuthTutorialClient-1.0.jar accessToken qTJkPi

      The output from this command is the access token that Fuse Online needs to access your Jira server.

Result

The Jira command line application updates the config.properties file so that it contains all values that you need to configure a Jira connection for Fuse Online.

Next step

Create a Jira connection.

14.2. Creating a Jira connection

In an integration, to obtain, create, or update a Jira issue, create a Jira connection, which you then add to an integration. You can add the same connection to any number of integrations.

If the Jira server that you want to connect to uses the OAuth protocol for authenticating access, you must have registered your Fuse Online environment as a client of the Jira server that you want to connect to. See Registering Fuse Online with a Jira server that uses OAuth.

Prerequisites

  • For a Jira server that uses basic authentication, you have a Jira user name and password.
  • For a Jira server that uses OAuth, you have access to the config.properties file that contains values for the Jira access token, consumer key, private key, and verification code.

Procedure

  1. In Fuse Online, in the navigation panel, click Connections to display any available connections.
  2. Click Create Connection to display the available connectors.
  3. Click the Jira connector.
  4. In the Jira URL field, enter the URL for the Jira server that you want an integration to connect to, for example, https://issues.mycompany.org.

    For a connection to a Jira server uses OAuth, the procedure to register your Fuse Online environment as a Jira consumer application resulted in a config.properties file. The URL that you specify here should be the same URL that is in that config.preperties file. For example, you would see a line like this in the config.properties file:

    jira_home=https\:issues.mycompany.org
  5. If this Jira server uses basic authentication:

    1. In the User name field, enter a Jira user name. The connection uses this account to operate on the specified Jira server.
    2. In the Password field, enter the specified user’s password.

    Skip the next step if the Jira server does not use OAuth authentication.

  6. If the Jira server uses OAuth authentication:

    1. Open the config.properties file that contains the OAuth access token, keys, and verification code. This is the file that is the result of the registration procedure. Copy values from that file and paste them into the connection configuration fields.
    2. Copy the access_token value into the Access Token field.
    3. Copy the consumer_key value into the Consumer Key field.
    4. Copy the private_key value into the Private Key field.
    5. Copy the secret value into the Verification Code field.
  7. Click Validate. Fuse Online displays a message that indicates whether it can validate this connection. If validation fails, try again and be sure to enter the correct values.
  8. When validation is successful, click Next.
  9. In the Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter Jira Connect 1.
  10. In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter Sample Jira connection that uses the jkim account.
  11. Click Save to see that the connection you created is now available. If you entered the example name, you would see that Jira Connect 1 appears as a connection that you can choose to add to an integration.

14.3. Obtaining Jira issues or comments to trigger integration execution

To trigger integration execution upon obtaining issues or comments from a Jira server, add a Jira connection as a simple integration’s start connection.

Prerequisites

  • You created a Jira connection.

Procedure

  1. In the Fuse Online panel on the left, click Integrations.
  2. Click Create Integration.
  3. On the Choose a connection page, click the Jira connection that you want to use to start the integration.
  4. On the Choose an action page, select an action:

    • Retrieve New Comments uses a query that you specify to search the Jira server. For each issue that the query returns, the connection checks whether a comment has been added since the previous invocation of the query. The connection returns any new comments.
    • Retrieve New Issues uses a query that you specify to search the Jira server. For each issue that the query returns, the connection checks its creation date. If the issue was created since the previous invocation of the query, the connection returns the issue to the integration. The first time that the connection executes this query, it returns all issues that it finds.
  5. In the Delay field, accept the default of 5000 milliseconds (5 seconds) or enter the number of milliseconds that you want to elapse between query invocations.
  6. In the Jira Query Language field, enter a Jira query. For example:

    project = GATE AND assignee = jkim AND (status = Open OR status = New OR status = Reopened)

    This query finds issues in the Gateway Online project, that are assigned to jkim and that are unresolved. Every Jira project has a short name and a long name. In this example, the short name of the Gateway Online project is GATE. In queries, specify a project’s short name.

    The more specific the query is, the less time it takes to search the Jira server. When a query does not have any results, the connection does not trigger integration execution.

  7. Click Next.

Result

The connection starts a simple integration and Fuse Online prompts you to choose the integration’s finish connection.

14.4. Adding an issue to a Jira server

In the middle of a flow, or to finish a simple integration, you can connect to a Jira server to add an issue.

Prerequisites

  • You created a Jira connection.
  • You are creating or editing a flow and Fuse Online is prompting you to add to the integration. Or, Fuse Online is prompting you to choose a simple integration’s finish connection.

Procedure

  1. On the Add to Integration page, click the plus sign where you want to add a Jira connection. Skip this step if you are adding a simple integration’s finish connection.
  2. Click the Jira connection that you want the integration to use to connect to a Jira server.
  3. On the Choose an action page, select Add Issue.
  4. Configure the action. The required fields are Issue type ID or name and Project key. For the optional fields, you can enter values now, or, after you add this connection to an integration, you can add a data mapper step before this connection. In the data mapper step, map fields from previous steps to the optional fields in this connection.

    1. Optionally, in the Assignee field, enter the Jira user name for the person that you want to assign this issue to.
    2. Optionally, in the Components field, enter the name of one or more components. Separate multiple names with commas. A Jira administrator defines the components that you can specify.
    3. Optionally, in the Priority ID or name field, enter a priority for the new issue. A Jira administrator defines the priority values that you can enter.
    4. Optionally, in the Summary field, enter a brief statement about the issue.
    5. In the Issue type ID or name field, enter a value that describes the type of the issue. For example, this is often something like Story, Epic, Chore, or Bug.

      In Jira, a user with administrator permissions can see a list of valid issue types by selecting Project settings > Issue types. A user without these permissions can click in an issue’s type field and a list of allowable values should display.

    6. Optionally, in the Watchers field, enter a comma-separated list of Jira user names. These people receive notifications when this issue is updated.
    7. In the Project Key field, enter the short name of a Jira project that a Jira administrator has defined. The connection creates the new issue in this project. For example, a project key is something like GATE.
    8. Optionally, in the Description field, enter any information about this issue that it is helpful to capture.
  5. Click Next.

Result

The connection appears in the integration visualization where you added it.

14.5. Adding a comment to a Jira issue

In the middle of a flow, or to finish a simple integration, you can connect to a Jira server to add a comment to an issue.

Prerequisites

  • You created a Jira connection.
  • You are creating or editing a flow and Fuse Online is prompting you to add to the integration. Or, Fuse Online is prompting you to choose a simple integration’s finish connection.

Procedure

  1. On the Add to Integration page, click the plus sign where you want to add a Jira connection. Skip this step if you are adding a simple integration’s finish connection.
  2. Click the Jira connection that you want the integration to use to connect to a Jira server.
  3. On the Choose an action page, select Add Comment.
  4. In the Comment field, enter the comment that you want to add to the issue or plan to add a data mapper step before this connection. In that data mapper step, map the comment from a previous integration step to this connection’s comment field.
  5. In the Issue Key field, enter the Jira identifier for the issue. Examples of issue keys: GATE-1234, Ent-239.
  6. Click Next.

Result

The connection appears in the integration visualization where you added it.

Next steps

To map the comment from a previous integration step to this connection, add the connection that provides the comment content and then add a data mapper step before this Jira connection. For example, suppose a database connection obtains customer records. In the data mapper step, map the collection of customer records to the Jira connection’s comment field.

14.6. Attaching a file to a Jira issue

In the middle of a flow, or to finish a simple integration, you can connect to a Jira server to attach one or more files to an issue. In the integration, there must be a previous step that obtains the file(s) that you want to attach.

Prerequisites

  • You created a Jira connection.
  • You are creating or editing a flow and Fuse Online is prompting you to add to the integration. Or, Fuse Online is prompting you to choose a simple integration’s finish connection.

Procedure

  1. On the Add to Integration page, click the plus sign where you want to add a Jira connection. Skip this step if you are adding a simple integration’s finish connection.
  2. Click the Jira connection that you want the integration to use to connect to the Jira server.
  3. On the Choose an action page, select Attach File.
  4. In the Issue Key field, enter the Jira identifier of the issue that you want to attach a file to. Examples of issue keys: GATE-1234, Ent-239.
  5. Click Next.

Result

The connection appears in the integration visualization where you added it.

Next step

If the integration does not already have an earlier connection that obtains the file(s) that you want to attach to a Jira issue, add that connection to the integration. Make sure that it is before the Jira connection that attaches a file. For example, suppose you add an FTP connection and download one or more files from an FTP server. When the integration executes, the subsequent Jira connection attaches those files to the Jira issue that you specified when you configured the attach file action.

14.7. Adding and removing Jira issue watchers

In the middle of a flow, or to finish a simple integration, you can connect to a Jira server to add watchers to an issue and/or remove watchers from issue.

Prerequisites

  • You created a Jira connection.
  • You are creating or editing a flow and Fuse Online is prompting you to add to the integration. Or, Fuse Online is prompting you to choose a simple integration’s finish connection.

Procedure

  1. On the Add to Integration page, click the plus sign where you want to add a Jira connection. Skip this step if you are adding a simple integration’s finish connection.
  2. Click the Jira connection that you want the integration to use.
  3. On the Choose an action page, select Add Issue.
  4. In the Issue Key field, enter the Jira identifier of the issue that you want to add watchers to or remove watchers from. Examples of issue keys: GATE-1234, Ent-239.
  5. Optionally, in the Add Watchers field, enter a comma-separated list of Jira user names. These people receive notifications when this issue is updated.
  6. Optionally, in the Remove Watchers field, enter a comma-separated list of Jira user names that are already watching this issue. The connection removes these users from the list of watchers.
  7. Click Next.

Result

The connection appears in the integration visualization where you added it.

14.8. Updating an issue on a Jira server

In the middle of a flow, or to finish a simple integration, you can connect to a Jira server to update an issue. The connection can update one or more issue fields. If the issue being updated already has a value for a field, the connection replaces that value with any value you specify for the connection or that you map to a connection field. For example, if the issue already has a description, and you specify text in the Description field when you configure the Update Issue action, the connection replaces the description that was there with this new description.

Prerequisites

  • You created a Jira connection.
  • You are creating or editing a flow and Fuse Online is prompting you to add to the integration. Or, Fuse Online is prompting you to choose a simple integration’s finish connection.

Procedure

  1. On the Add to Integration page, click the plus sign where you want to add a Jira connection. Skip this step if you are adding a simple integration’s finish connection.
  2. Click the Jira connection that you want the integration to use to connect to the Jira server.
  3. On the Choose an action page, select Update Issue.
  4. Configure the action. The only required field is Issue Key. For the optional fields, you can enter values now, or, after you add this connection to an integration, you can add a data mapper step before this connection. In the data mapper step, map fields from previous steps to the optional fields in this connection.

    1. Optionally, in the Assignee field, enter the Jira user name for the person that you want to assign this issue to.
    2. Optionally, in the Components field, enter the name of one or more components. Separate multiple names with commas. A Jira administrator defines the components that you can specify.
    3. In the Issue Key field, enter the Jira identifier for the issue that you want the connection to update. Examples of issue keys: GATE-1234, Ent-239.
    4. Optionally, in the Priority ID or name field, enter a priority for the new issue. A Jira administrator defines the priority values that you can enter.
    5. Optionally, in the Summary field, enter a brief statement about the issue.
    6. In the Issue type ID or name field, enter a value that describes the type of the issue. For example, this is often something like Story, Epic, Chore, or Bug.
    7. Optionally, in the Description field, enter any information about this issue that it is helpful to capture.
  5. Click Next.

Result

The connection appears in the integration visualization where you added it.

14.9. Transitioning a Jira issue to a new status

In the middle of a flow, or to finish a simple integration, you can connect to a Jira server to transition an issue to a new status, or to a new workflow stage. A Jira administrator defines what it means for an issue to transition as well as the values for transition IDs.

Prerequisites

  • You created a Jira connection.
  • You are creating or editing a flow and Fuse Online is prompting you to add to the integration. Or, Fuse Online is prompting you to choose a simple integration’s finish connection.

Procedure

  1. On the Add to Integration page, click the plus sign where you want to add a Jira connection. Skip this step if you are adding a simple integration’s finish connection.
  2. Click the Jira connection that you want the integration to use to connect to the Jira server.
  3. On the Choose an action page, select Transition Issue.

    You do not need to specify any values to configure the transition issue action. Instead, you can map values from previous integration steps to the fields in the this connection.

  4. Optionally, in the Comment field, enter a comment that you want to add to the issue.
  5. Optionally, in the Issue Key field, enter the Jira identifier for the issue that is transitioning. Examples of issue keys: GATE-1234, Ent-239.
  6. Optionally, in the ID of the transition field, enter an integer that a Jira administrator has associated with a particular transition, such as when a Jira moves from being new to being worked on, or when it moves from being worked on to being tested.

    A Jira administrator can view transition IDs in a project’s workflow display. If you do not have administration permissions, obtain the allowed transition IDs from a Jira administrator.

  7. Click Next.

Result

The connection appears in the integration visualization where you added it.

Next steps

If you did not specify a value in each Transition Issue field, ensure that the integration has a step that obtains the value for each field. After the integration has all required connections, add a data mapper step before the Jira connection that transitions an issue. In the data mapper step, map fields from previous steps to the fields in the Jira connection that transitions an issue.