Jira
    • 07 Jun 2022
    • PDF

    Jira

    • PDF

    Article summary

    The Jira integration allows you to sync information between Jira and SysAid.

    Once the integration is set up, you'll be able to:

    • View Jira information in SysAid SRs
    • Generate Jira issues from SysAid SRs
    • Configure email and escalation rules to generate Jira issues
    • Map fields and sync statuses between Jira and SysAid
    • Set up multiple integration configurations to support multiple Jira projects

    jiraEmbeddedSettingsfilesToolTip.png

    This can contribute to streamlined collaboration between the service desk, DevOps, and operations, slashing IT response and handle times.

    Licensing

    You can contact your account manager to purchase an account. If you want to set up a trial account, enter your Jira credentials in the setup page, enable the addon. This will initiate a 10-day trial license for you to try out SysAid's Jira addon.

    Requirements

    For the integration to work properly you must have a Jira Software account and be running SysAid version 19.2 or higher. For Jira On Premise, this integration is compatible with Jira 8.12.3 or above.

    Note that regular Jira users can set up this integration. The user does not need to be an 'Org and Site' admin in Jira.

    Setup the Integration

    1. Obtain the Jira add-on from the SysAid Marketplace
    2. On the main My Apps page, in the Jira icon, click IntegrationsfilesGreenCog8.jpg.

    Connect Jira and SysAid

    Please note that the step for obtaining the API token is different for Jira Cloud and Jira On Premise accounts.

    1. In the Jira URL field, enter the URL for your Jira account.
    2. Enter your Jira Username and password.
    3. Get a Jira Token (for Jira Cloud accounts):
      1. Login to Jira and click this link.
      2. In the Jira account settings, click API tokens.
      3. Click Create API token.
        jiraEmbeddedSettingsfilesAPIToken.png
      4. Enter a label for the API token.
      5. Click Copy to clipboard.
      6. Back in SysAid, paste the token into the Jira Token field.
    4. Get a Jira Token (for Jira On Premise accounts):
      1. Login to Jira and access the Atlassian Marketplace for JIRA.
      2. Purchase the API Tokens for Jira plugin.
        jiraEmbeddedSettingsfilesMarketplace.png
      3. From the Profile menu, select Profile.
        jiraEmbeddedSettingsfilesProfile.png
      4. In the User Profile page, click Create API Token.
        jiraEmbeddedSettingsfilesCreateAPITokenCreateAPIToken.png
      5. Enter a label for the API token.
      6. Leave the expiration date field empty.
      7. Click Create.
        jiraEmbeddedSettingsfilesCreateAPIToken.PNG
      8. Click Copy to clipboard.
        jiraEmbeddedSettingsfilesCopyAPIToken.PNG
      9. Back in SysAid, paste the token into the Jira Token field.
    5. Click Save Changes.
    6. Authenticate the integration:
      1. In SysAid, in the SysAid Access Token field, click Generate Token.
      2. Copy the token that appears.
      3. In Jira navigate to Settings > System> WebHooks.
      4. Click Edit.
      5. In the URL Field, add the following to the existing text at the end of the existing URL:"&accessToken=<COPIED_ACCESS_TOKEN>"
        The resulting URL should appear as follows:
        https://<ACCOUNT>/addonsConsume/jiraEmbedded?ticket=${issue.key}&accessToken=<COPIED_ACCESS_TOKEN>
    7. Click the slider to enable the integration.
    8. Click Test connection to see if SysAid is successfully communicating with Jira according to the credentials you’ve entered.
      If the connection is successful, a confirmation message is displayed.
      jiraEmbeddedSettingsfilesJiraSetup.png

    Map fields between Jira and SysAid

    Once the integration has been set up you can map fields between SysAid and Jira. This means that values of SysAid SR fields are populated in their corresponding fields in Jira. To map fields you must first create custom fields in SysAid to store Jira information. Then you need to use an existing Jira issue to populate the Jira field drop-downs so you can select which fields to map to SysAid.

    Please note that Jira fields can only be mapped to SysAid custom text or text area fields.

    To map Jira fields to SysAid fields

    1. Setup the webhook in Jira
      1. In your Jira account, click jiraEmbeddedSettingsfilesJiraCogwheel.jpg.
      2. Select System.
      3. Scroll down to the bottom of the side panel, and click Create a WebHook.
      4. Enter a name for your WebHook (e.g. SysAid Webhook).
      5. In the URL field, enter your SysAid URL and append the following URL parameters "/addonsConsume/jiraEmbedded?ticket=${issue.key}".
        jiraEmbeddedSettingsfilesWebhookURL.jpg
      6. In the Issues Related Events area, select Attachment created and Issue updated check boxes.
        jiraEmbeddedSettingsfilesJiraEvents.jpg
      7. On the bottom of the screen, click Create.
    2. Create custom Jira fields. Make sure that the field's DB field name begins with "jira_". For more information about creating custom fields in SysAid, see Create Custom Column.
      jiraEmbeddedSettingsfilesCustomField.png
    3. Populate the Jira field drop-downs:
      1. In the Mapping tab, select a project from the Jira project drop-down list.
      2. Select an issue from the Jira issue drop-down list.
    4. In the Jira field column, select the Jira field you want to map from.
    5. In the SysAid fields column, select the SysAid field you want to map to.
    6. To change the direction of the mapping, click the arrow. The arrow changes from green to red when it is mapping from SysAid to Jira.
    7. Click the check box to display the field in the Jira tooltip in the SysAid SR.
    8. (Optional) To map more fields, click Add New Field.
    9. (Optional) To delete a field mapping, click jiraEmbeddedSettingsfilesDelete.png.
    10. Click Save Changes.
      jiraEmbeddedSettingsfilesMapping.png

    Map Statuses Between Jira and SysAid

    The Status Mapping area allows you to connect a Jira status with a status in SysAid. This way, when a status is updated in a Jira issue, the update is reflected in the connected SysAid SR.

    To map statuses:

    1. In the Mapping tab, select a status from the Jira status drop-down.
    2. Select a corresponding status from the SysAid status drop-down.
    3. (Optional) To map more more statuses, click Add New Status.
    4. (Optional) To delete a status mapping, click jiraEmbeddedSettingsfilesDelete1.png.
    5. (Optional) To also update Jira issue statuses, based on changes to SysAid SR statuses, select this check box.

    SR Configuration

    The SR Configuration tab allows you to determine what the contents of the description fields for Jira issues generated from SysAid tickets. It also allows you to create a field in Jira issues to display the corresponding SysAid ticket, and to generate an SR activity whenever a Jira issue is generated from, linked to, or removed from the ticket.

    1. In the SR Configuration tab, you can copy any of the SR data from SysAid to Jira using the Description field. You can manually edit the description templates for the Jira issues that are automatically created by this SysAid-Jira integration to add or remove SR information that will appear in the Jira issue.
    2. (Optional ) To generate a SysAid SR activity for every time the integration creates, links to, or removes a Jira issue, select the "Add SR activity when creating/linking/removing a Jira issue " check box.
    3. (Optional) In the "Display SysAid SR ID in this field" field, enter the ID of the custom field that Jira will use for displaying the ID of the SR connected to the automatically-generated Jira issue:
      1. In Jira, click jiraEmbeddedSettingsfilesJiraCogwheel1.jpg.
      2. Select Issues.
      3. Select Custom fields.
      4. Search for the field you created in Jira for this purpose.
      5. On the field record, click jiraEmbeddedSettingsfilesElipses.jpg.
      6. Select Configure.
        jiraEmbeddedSettingsfilesConfigure.jpg
      7. Copy the ID at the end of the URL.
        jiraEmbeddedSettingsfilesURLID.jpg
      8. Back in SysAid, in the SR Configuration tab, enter "customfield_" and paste the copied ID after the underscore in the "Display SysAid SR ID in this field" field.
      9. Click Save Changes.

    Projects Profile

    In Jira, an issue's fields may differ based on what project that it belongs to. That's why you may want to configure setup different configurations to apply to different projects, in addition to your default configuration.

    To add a new designated Jira project configuration

    1. In the Projects Profile tab, click Add Jira Project.
    2. Set up the field mapping, status mapping, and SR configuration, according to the procedures detailed above.
    3. Click Add to Projects List.
    4. (Optional) To delete a project configuration, click jiraEmbeddedSettingsfilesDeleteButton.png
      next to that project.

    jiraEmbeddedSettingsfilesProjectProfile.png

    Using the Jira integration

    Now that you've set up the integration, you can create a jira issue from a SysAid SR, or link an existing Jira issue to a SysAid SR.

    To create a Jira issue from a SysAid SR

    1. In the SR form, from the Jira Issue drop-down, select Create.
    2. Select which Jira project you want the issue to be included in.
    3. Select a Jira type for the issue.
    4. If you select Sub-Task as the Jira type, enter the parent ID in the Jira Parent Issue field.
    5. Select who should be assigned to the issue in Jira.
    6. Click Apply.
      SysAid generates an activity in the service record corresponding to the creation and linking of the new Jira issue.
      jiraEmbeddedSettingsfilesJiraActivity.png
      The Jira issue information is displayed in the Jira Issue field.
      jiraEmbeddedSettingsfilesJiraIssueField.png
    7. (Optional) To remove the issue or relink the SR to another Jira issue click jiraEmbeddedSettingsfiles3dots.png.
    8. (Optional) To view more of the issues information click the link in the Jira issue field.
      • To open the issue in Jira, click the link in the tooltip.
        jiraEmbeddedSettingsfilesToolTip1.png
        The Jira issue contains all the information you defined when you set up the SysAid-Jira integration.
        jiraEmbeddedSettingsfilesJiraIssuue.png
        When you change the status of the issue in Jira, the status is automatically updated in SysAid and in the Jira issue field.

    Set a Jira action in an escalation or email rule

    You can also set escalation rules and email rules to create Jira issues.

    To set an escalation rule or email rule to create a Jira issue based on a SysAid SR

    1. Set the criteria for the rule. For more information, see Escalation Rules or Email Rules.
    2. In the Action Builder, select the Jira-related fields you want the escalation rule to affect:
      1. For the Jira Issue field, select Create.
        jiraEmbeddedSettingsfilesJiraEscalationRules.jpg
      2. Select the Jira Project field and enter the project ID that you can locate in the URL of the project's page.
        jiraEmbeddedSettingsfilesProjectURL.jpg
      3. Click Create Filter.
    3. In the rule form, click Save.

    What's Next