HaloCRM Guides

Jira Integration

Jira Configuration

This section details the configuration that must be carried out in your Jira instance to make the integration work.

Projects

You must ensure that you have a project setup in Jira to create issues for. When setting up the trial for Jira, you will be taken through steps to create your first project, so you will always have at least one project available for posting.

Time Tracking

It is possible to push initial estimates across to Jira when creating new issues. You can find out how to configure this further on in the guide, however, to use this feature you must ensure that your project uses a “Scrum” board, as Jira does not support time tracking on the new issue screen for a Kanban Board based project. You must also ensure that the original estimate field has been added to your issue type.

Webhooks

https://developer.atlassian.com/server/jira/platform/webhooks/

To sync updates from Jira issues back to Halo, you will need to create webhooks in Jira for the “Issue – Updated” and “Comment – Created“ events. To do this, click the settings icon in Jira, and go to System Settings. Then, scroll down the tree view until you see the advanced options, and there should be an option for webhooks:

The URL for the webhook should be set to your Halo API URL, followed by /notify. For example:

https://support.haloservicedesk.com/api/notify/jira

The exact URL you need to use is outlined in the Jira configuration screen within Halo and is highlighted further in this guide.

Halo Configuration

This section details how to configure the Jira integration in Halo.

General Configuration

To activate the Jira integration, go to Configuration > Integrations and enable the module. Please note that this integration cannot be used in tandem with the Azure DevOps integration. Once enabled, click into the integration to begin configuring it:

Begin by choosing your Jira instance type. Depending on which you choose, a different authentication method is required, and different boxes will be displayed based on this. Each authentication option should be self-explanatory, with links provided if you need to generate any tokens.

To link Halo to multiple Jira projects, you need to create Products in Halo and assign a Jira key to the product. You can configure your products in Configuration > Software Releases > Setup Products. On the details screen, you will see an option for Jira Project Key. You will also need to make sure your Product Names match across Halo and Jira.

As of v2.168.1+ you can link a ticket to a Jira issue without setting a product on the ticket beforehand. To be able to do this you must set the 'Default Jira Connection to use when searching for Issues on Tickets with no Product set' under configuration > integrations > Jira.

Once this is set when an Issue is selected, the Ticket will have the Halo Product linked to the Jira Project set.

Syncing To Jira

Creating Issues

Issues can be created in Jira from tickets in Halo using actions. To do this, create a new action with the system use "Create Bug/Issue/Work Item", and make sure the action is available in your workflow.

The action will create an issue against the default project (using the name and key specified in the above step), unless the ticket is linked to a particular product which has a different Jira Project Key assigned to it. Tickets can be associated with different products by adding the product field to a ticket type.

When creating the issue in Jira, it's possible to send extra information across other than just the basic details.

It is possible to set the original estimate, remaining estimate and reporter fields for a new issue in Jira, as well as sending attachments from your ticket to Jira. To set these fields, you should add the corresponding field to the field list of the new action you have created. These fields will only be selectable once you have chosen the correct system use for the action.

For the reporter field to work, you must assign the ID of the Jira User to their corresponding Agent/User record. This must be done manually, or via a spreadsheet import. The fields can be updated on the details tab of both the User and Agent details screens.

Ticket Type/Issue type mappings

Under the 'syncing to Jira' tab in the integration setup you will see the 'Ticket type/Issue type mappings' table. Here you can map Halo ticket types and categories to a Jira issue type.

Once mappings are added, the ticket type the 'create Jira issue' action is used on will determine the issue type created in Jira. The categories on the mapping will also be synced over.

Custom field Mappings

You can map a Halo field to a Jira field in the 'Custom Field Mappings' table, for each mapping you must select which product this applies to.

Priority Mappings

Halo ticket Priorities can be synced to Jira. Map a Halo priority to a Jira priority in the 'Priority Mappings' table, this will determine what priority is set against the issue in Jira.

Receiving Updates from Jira

It is possible to sync updates made to issues in Jira back to Halo. Following the steps outlined in the Jira Configuration part of this guide, create a webhook in Jira for the events specified on the setup screen:

To change the result of what happens to a Halo ticket when an update is received from Jira, there are some options below this to map statuses and custom fields. Setting up custom field mappings maintains your custom field values between the two systems, whilst status mappings allow you to change the Halo ticket status to a certain value depending on the new status of the Jira ticket. If you are mapping multi-select fields between Jira and Halo, you must ensure that the option list is equal across both systems.

There is also an option to map ticket types. Ticket type mappings are used to determine which type of issue is created in Jira when you use your new system action. For example, if you match your Incident ticket type to the Bug ticket type in Jira, when you perform the action on an Incident, an issue of the type Bug will be created in Jira.

Software Releases

When using software release tracking in Halo as well as Jira integration you can now set the Jira version name on each software release. You'll find the below free-text field on the Details tab of the release.

When creating a new issue from a ticket in Halo, if a software release has been chosen on the ticket, the corresponding Jira version will be linked to the issue in Jira.

Workaround for "Jira Sync Failed" components error

If you are getting the below error, you can work around this whilst we resolve it by adding the components field to the screen in use by your issue type: