Chapter 14. Connecting to Jira

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 ( ) > 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.

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.

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.

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.

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.

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.

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.

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.

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.