Integrate Jira 编辑

Integrate with Jira to track issues and get automated updates about tasks on any device, intranet, or messenger. Use the following process to enable the integration with Jira. After you complete this process, your existing level of audit logging persists, including any actions carried out by the use of Citrix Microapps.

Note:

We provide two Jira integration templates for your use. We recommend using the newer HTTP integration for most use-cases. The HTTP integration provides more power to configure the cached data structure. For full details of the microapps available in each integration, see Use Jira microapps.

Review prerequisites

All user accounts that you want to use through this integration must have visibility for their email in account settings set to Anyone. This means service accounts as well as the accounts that users log in to Citrix Workspace through OAuth. Navigate to https://id.atlassian.com/manage-profile/profile-and-visibility, log in if necessary, in Contact section and next to the email account select Anyone under the Who can see this? menu.

Note:

Jira no longer supports Internet Explorer 11. Configuring this microapp with Internet Explore 11 will result in errors. Switch to another browser (Chrome, Edge, and so on) to configure correctly.

After you prepare this integration in Jira, you will need these artifacts to add the integration in Citrix Workspace Microapps:

• Base URL: templatebaseurl Replace {cloud-id} with your cloud-ID. If you need to find your cloud-ID, log in as an administrator of your JIRA instance and look at the URL.
• Authorization URL: This is predefined. This is the authorization server URL provided when setting up the target application integration.
• Token URL: This is predefined. This is the URL of the access authorization token.
• Epic-Name-customFieldId: This is found in the Jira admin portal. See Replace Service Action variables.
• Client ID: The client ID is the string representing client registration information unique to the authorization server.
• Client Secret: The client secret is a unique string issued when setting up the target application integration.
• Username: This is your service account username.
• Password: This is your service account password.

Note:

It is recommended that you always use OAuth 2.0 as your service authentication method where available. OAuth 2.0 ensures that your integration meets the maximum security compliance with your configured microapp.

The following prerequisites must be met before you begin the integration process:

• A dedicated user account that has Browse Projects access to the Jira projects that you would like to manage.

  For more information about managing users, see https://www.atlassian.com/software/jira/guides.

  For more information about how to add a user to a permission scheme for a Jira project, see Managing project permissions.

• Configure Citrix Gateway to support single sign-on for Jira so that once users log in they are automatically logged in again without having to enter their credentials a second time. Follow the instructions in Jira Single Sign-on Configuration. For more information about configuring SSO, see Citrix Gateway Service.

Enabling OAuth 2.0 (3LO)

Before you implement OAuth 2.0 (3LO), you need to enable it for your app in Jira app management.

1. Navigate to App management.
2. Create a new app by selecting Create new app, enter a name, agree to the terms, and select Create.
3. Copy the Client ID and Secret for later use
4. In the APIS AND FEATURES section in the side navigation, click +Add
5. In the Features section of the APIs and features page find OAuth 2.0 (3LO), and select Add and then Configure.
6. Enter the Callback URL. Set this URL to any URL that is accessible by the app. When you implement OAuth 2.0 (3LO) in your app (see next section), the redirect_uri must match this URL.
7. Click Save changes.

Your screen looks something like this:

Create API Token

A script or other process can use an API token to perform basic authentication with Jira Cloud applications or Confluence Cloud. You must use an API token if the Atlassian account you authenticate with has had two-step verification enabled.

1. While logged in to the Atlassian account, go to API Tokens.
2. Select Create API token and enter a name for the token in the Label field.
3. Copy to clipboard and save for later use.

You must enter the API token as your Password when you add the integration to Citrix Workspace Microapps.

Add the Jira platform REST API

If you haven’t already added the Jira platform REST API, do this now.

1. In the APIS AND FEATURES section in the side navigation, click +Add.
2. In the APIs section of the APIs and features page find OAuth 2.0 (3LO), and select Add and then Configure.
3. Add the desired scopes for your app.

Add callback URL

Add a custom URL to your instance configuration to grant access to private data and enable OAuth authenticated user actions. To find your microapp server URL, sign in to Citrix Cloud, and select the Microapps tile. In the URL bar, copy the first section of the URL. This is your microapps server URL. The section {yourmicroappserverurl} is composed of a tenant part, a region part, and an environment part: https://{tenantID}.{region(us/eu/ap-s)}.iws.cloud.com.

For the HTTP Jira integration, you must add two different callback URLs. However, a Jira application can have only one callback URL. This means you need to register two applications; one for user actions and the other for synchronisation. They must have different callback URLs.

https://{yourmicroappserverurl}/admin/api/gwsc/auth/serverContext

https://{yourmicroappserverurl}/app/api/auth/serviceAction/callback

Note:

Pay attention to the callback URLs when adding the Jira integration. Service Authentication and Service Action Authentication have different Callback URLs. The Client ID and Secret must be the ones appropriate to either the Service Authentication or Service Action Authentication callback URL.

Add the integration to Citrix Workspace Microapps

Follow these steps to set up the Jira HTTP integration. We recommend using the newer HTTP integration for most use-cases. The authentication options are preselected. Ensure that these options are selected as you complete the process. We recommend using this newer HTTP integration for most use-cases. The HTTP integration provides more power to configure the cached data structure.

Note:

By default, this integration synchronizes data for a six (6) month time period. We recommend that you modify this value based on your needs and usual age of your tickets. The filter is based on last updated, not created. To change this you must modify the timeToSync variable in a data loading endpoint. See Replace Data Loading variable.

Follow these steps:

1. From the Microapp Integrations page, select Add New Integration, and Add a new integration from Citrix-provided templates.
2. Choose the Jira tile under Integrations.
3. Enter an Integration name for the integration.
4. Enter Connector parameters.
   • Enter the instance Base URL or simply replace {cloud-id} in the example with your cloud ID. If you need to find your cloud-ID, log in as an administrator of your JIRA instance and look at the URL. This cloud-ID is a universally unique identifier (UUID), that is an 8-4-4-4-12 digit hexadecimal number which is part of the URL. Alternatively, you can authenticate using admin credentials and send a GET request to https://api.atlassian.com/oauth/token/accessible-resources. The Cloud-ID is part of the response.
   • Select an Icon for the integration from the Icon Library, or leave this as the default Jira icon.
   • Enable the On-premises instance toggle if you are creating an on-premises connection. For more information, see On-premises instance. Due to differences between Jira Cloud API v2 and Jira Server API v2 of your Jira instance, you must also update some parts of the integration manually. Contact support.

   

5. Under Service authentication, select OAuth 2.0 from the Authentication method menu and complete the authentication details. The authentication options are preselected. Ensure that these options are selected as you complete the process. Use the OAuth 2.0 security protocol to generate request/authorization tokens for delegated access. It is recommended that you always use OAuth 2.0 as your service authentication method where available. OAuth 2.0 ensures that your integration meets the maximum security compliance with your configured microapp.

   1. Select Authorization code from the Grant type flow menu. This grants a temporary code that the client exchanges for an access token. The code is obtained from the authorization server where you can see the information the client is requesting. Only this grant type enables secure user impersonation. This displays the Callback URL, which you use when registering your application. Service Authentication and Service Action Authentication have different Callback URLs.
   2. Enter authorization_code in the Grant type value field.
   3. Select Request body from the Token authorization menu.
   4. Select URL encoded form from the Token content type menu.
   5. Your Authorization URL is predefined. This is the authorization server URL provided when setting up the target application integration.
   6. Your Token URL is predefined. This is the URL of the access authorization token.
   7. Ensure the following is entered for Scope. This string is defined by the authorization server when setting up your target integration application. To synchronize other entities, you must add scopes here. Use the following, separated by a space: read:jira-user read:jira-work manage:jira-project manage:jira-configuration write:jira-work manage:jira-data-provider offline_access.
   8. Enter your Client ID. The client ID is the string representing client registration information unique to the authorization server. You collect this and the secret by registering the OAuth client in your Jira account. Client ID and Secret must be the ones appropriate to the Service Authentication callback URL.
   9. Enter your Client secret. The client secret is a unique string issued when setting up the target application integration.
   10. Enter your Header prefix. (optional) Enter the header prefix if your bearer prefix is different from the default header.

   

6. Under Service Action Authentication, enable the Use Separate User Authentication in Actions toggle Service action authentication authenticates at the service action level. The authentication options are preselected. Ensure that these options are selected as you complete the process.

   1. Select OAuth 2.0 from the Authentication method menu and complete the authentication details.
   2. Select Authorization code from the Grant type flow menu. This grants a temporary code that the client exchanges for an access token. The code is obtained from the authorization server where you can see the information the client is requesting. Only this grant type enables secure user impersonation. This displays the Callback URL, which you use when registering your application. Service Authentication and Service Action Authentication have different Callback URLs.
   3. Enter authorization_code in the Grant type value field.
   4. Select Request body from the Token authorization menu.
   5. Select URL encoded form from the Token content type menu.
   6. Your Authorization URL is predefined. This is the authorization server URL provided when setting up the target application integration.
   7. Your Token URL is predefined. This is the URL of the access authorization token.
   8. Ensure the following is entered for Scope. This string is defined by the authorization server when setting up your target integration application. To synchronize other entities, you must add scopes here. Use the following, separated by a space: read:jira-user read:jira-work manage:jira-project manage:jira-configuration write:jira-work manage:jira-data-provider offline_access.
   9. Enter your Client ID. The client ID is the string representing client registration information unique to the authorization server. You collect this and the secret by registering the OAuth client in your Jira account. Client ID and Secret must be the ones appropriate to the Service Action Authentication callback URL.
   10. Enter your Client secret. The client secret is a unique string issued when setting up the target application integration.
   11. Enter your Header prefix. (optional) Enter the header prefix if your bearer prefix is different from the default header.
   12. If you selected OAuth 2.0 authentication method, you can select + Add Parameter to include Access token parameters. Access token parameters define the access token parameters as required by the target application authorization server if necessary.

   

7. (Optional) If you want to activate rate limiting for this integration, enable the Request rate limiting toggle and set the Number of requests per Time interval.
8. (Optional) Enable Logging toggle to keep 24 hours of logging for support purposes.

9. The Request timeout field is set to 120 by default.

   

10. Select Save to proceed.
11. Under OAuth Authorization, select Authorize to log in with your service account. A pop-up appears with a Webex login screen.
    1. Enter your Service Account user name and password and select Log in.
    2. Select Accept.

Continue with the following procedures to finish the set-up process.

Replace Service Action variables

To enable Create Epic page functionality, you must manually modify the Create Epic and Create Epic wo Assignee service actions. Replace the {Epic-Name-customFieldId} value of the EpicFieldId template variable with the id of a custom field that the Epic Name is stored in.

1. In the Jira admin portal, navigate to Issues. Select Custom fields from the left menu. Find the entry Epic Name and select the menu on the other side of the screen. Select View field information.
2. Copy and save the numeric value at the end of the URL.
3. Back in Microapps, select the menu next to the Jira integration, and then Edit. Select Service Actions from the left side navigation column.
4. Select the menu next to one of the service actions and select Edit, or select the name of the service action. Let’s start with the Create Epic service action.

5. In the Edit Service Action screen, under Template variables replace the {Epic-Name-customFieldId} value of the EpicFieldId template variable with the custom field id that you collected earlier in Jira.

   

6. Select Save to finish.
7. Now repeat this for the other service action: Create Epic wo Assignee.

Replace Data Loading variable

This integration synchronizes data for a six (6) month time period by default. We recommend that you modify this value based on your needs and usual age of your tickets. The filter is based on last updated, not created. To change this you must modify the timeToSync variable in the Issues data loading endpoint.

1. From the Microapp Integrations page, select the menu next to the Jira integration, and then Edit. The Data Loading screen opens. If you are in the configuration screen, select Data Loading from the left side navigation column.
2. Select the menu next to the Issues endpoint and then select Edit, or select the name of the endpoint: Issues.
3. In the Edit Data Endpoint screen, under Template variables replace the value for the timeToSync variable with the value that you want.

4. Select Apply at the bottom of the screen and confirm.

   

You are now ready to set and run your first data synchronization. For complete information about synchronization rules, synchronization that does not meet its schedule and veto rules, see Synchronize data.

For more details of API endpoints and table entities, see Jira HTTP connector specifications.

Use Jira microapps

Our Jira HTTP integration comes with the following preconfigured out-of-the-box microapps:

Create Epic: Create a new Jira epic with details.

Note:

To enable Create Epic page functionality, you must modify the Create Epic and Create Epic wo Assignee service actions. See Replace Service Action variables.

Create Ticket: Create a new Jira ticket with details.

Tickets: View tickets, add comments, create subtasks, and change status and assignee.

Add the Legacy Jira integration

Follow these instructions in addition to the steps above to set up the legacy integration.

Prerequisites

For the Legacy integration, you need these values.

• URL
• Username
• Password - You must enter the API token as your Password when you add the integration to Citrix Workspace Microapps
• Authentication Method (either credentials or OAuth2)

For OAuth 2.0 you also need:

• Client ID
• Client Secret

Set duration to retrieve issues

For the Legacy Jira integration, set the duration that you want to retrieve issues in Jira. When you add the integration to Citrix Workspace Microapps, the amount of data the integration retrieves from Jira can be limited by applying a load filter.

1. Log in to Jira with your dedicated user account and password.

   Note:

   If you are using an existing account, the username is not the email of the account. To find the Username of an account, log in to your Jira instance, select the profile thumbnail, select Profile.

2. Enter the number of days of issues to retrieve.

   Default: 90 days.

Add the Jira Legacy integrations

Follow these steps:

1. From the overview page, select Get Started.

   The Manage Integrations page opens.

2. Select Add New Integration, and Add a new integration from Citrix-provided templates.
3. Choose the Jira tile to add.

4. Enter a name for the integration.

   

5. Enter the Connector parameters that you collected as prerequisites.
   • Enter your URL.

   • Enter your Service Authentication Username and Password.

     Note:

     Enter the API token you collected in a previous step as your Password when you add the integration to Citrix Workspace Microapps.

6. Select an Authentication Method. Use the OAuth 2.0 security protocol to generate request/authorization tokens for delegated access.
   • Credentials - Credentials The client’s credentials are used.
   • Oauth 2.0 - Enter the OAuth Client ID and OAuth Client Secret that you collected in the prerequisites procedure.
7. Select the number of Changed Tickets Weeks To Load.
8. Select Add.

The Microapp Integrations page opens with your added integration and its microapps. From here you can add another integration, continue setting up your out-of-the-box microapps, or create a new microapp for this integration.

You are now ready to set and run your first data synchronization. As a large quantity of data can be pulled from your integrated application to the Microapps platform, we recommend you use the Table page to filter entities for your first data synchronization to speed up synchronization. For more information, see Verify needed entities. For complete information about synchronization rules, synchronization that does not meet its schedule and veto rules, see Synchronize data.

For more details of API endpoints and table entities, see Jira connector specifications.

Legacy Jira microapps

Our Jira integration comes with the following preconfigured out-of-the-box microapps:

Create Ticket: Create a new Jira ticket with details.

Tickets: View tickets, add comments, create subtasks, and change status and assignee.