HaloCRM

HaloCRM Guides

Guides > Jira Integration

Jira Integration

In this guide we will cover:

- What is the Jira Integration?

- Pre-requisites-Jira side

- Connecting Halo to Jira

- Pre-requisites-Jira side

- Syncing To Jira

- Manually linking a ticket to an existing Jira issue

- Send a Ticket to Jira

- Managing linked issues

- Syncing Updates back to Halo

- Monitoring Sync



Related Guides:


What is the Jira Integration? 

The Jira Software integration allows you to sync tickets in Halo with issues in Jira, this is a two way sync, so creation of a ticket or issue and updates on either end will sync over to the other application. Various details against the Halo ticket can be synced to Jira including priority, estimated time, product version and custom fields. This allows you to track software changes in both applications. 


This assists you in optimising software management as changes can be monitored in both applications, and time spent on these changes can be tracked in both applications, allowing you to leverage the capabilities of both Jira and Halo. 


If you are using this integration you may want to check out our Software Releases functionality, which allows you to track and manage products, releases and release emails within Halo, which can be supported by the Jira integration. 


Pre-requisites-Jira side

Projects

You must ensure that you have a project setup in Jira to create issues for. Jira projects are the equivalent to Halo products, therefore when an issue is synced to Jira it will need to be created against the relevant project. 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.


Connecting Halo to Jira

First, you will need to enable the Jira integration module in Halo. Head to configuration > integrations and enable the Jira Software module using the '+' icon. 

Fig 1. Enable integration module


Click into the module to begin configuration, to configure a connection click 'Add/Edit Connections' and hit 'New'. 



Fig 2. Jira setup


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, if using the Cloud instance type a link will be provided on the integration setup page, where an API token can be generated. 


Once you have selected your instance type enter the URL used to access your Jira instance as well as a username and password/API key. If generating an API key, this key will take the permissions of the user that generates it, therefore ensure the agent generating this key has admin-level access in Jira. 


Once you have entered your credentials hit 'Test Connection' to verify Halo is able to connect to your Jira instance successfully. 


Now navigate back to configuration > integrations > Jira Software and set 'Default Jira Connection to use when searching for Issues on Tickets with no Product set'. This will determine which Jira connection (instance) will be used by default. Otherwise, the Jira connection used will be determined by the product assigned to the ticket. 


Link Halo Products to Jira Projects

A project in Jira is the equivalent of a (software) product in Halo, therefore you will need to link Halo products and Jira projects to ensure when an issue is sent to Jira it is created under the correct project in line with the product that is associated with the ticket in Halo. 


Import Jira Projects as Products

If you do not yet have your (software) products setup in Halo you can import these Jira. To import products head to the 'Projects' tab under the Jira software setup page in Halo and hit 'Import projects'. 

Fig 3. Import Projects


To see the products that have been imported select 'Product and release setup > Products. 


Link existing Halo Products to Jira Projects

If you already have your Halo products created and configured in your Instance, you can link each one to the associated project in Jira. 


To do this select 'Product and release setup > Products > select a product > Jira tab. Here, select the Jira instance the linked project is in, then in the 'Jira Project' field choose the project that should be linked to this product. 

Fig 4. Link product to Jira project 


Custom field mappings

Once a product is linked to a project you can configure custom field mappings, to map Halo ticket fields to Jira project fields. These mappings can also be configured under the integration setup, this just provides an alternative place to map. 


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.


Fig 5. Default Jira connection


Once this is set when an Issue is selected, the Ticket will have the Halo Product linked to the Jira Project set. You can also link multiple Jira issues to a Halo ticket.


Syncing To Jira

Issues can be created in Jira from tickets in Halo using actions. The creation of an issue will be triggered by an action in Halo. When syncing, ticket data from ticket fields in Halo can be synced over to Jira. Field mappings will need to be completed to determine how data is synced. 


Field mappings

Field mappings will need to be completed to determine how data is synced from Halo to Jira. The following data can be synced to Jira.

  • Issue type 
  • Project custom fields
  • Issue Priority 
  • Components 

To setup field mappings head to the 'Syncing to Jira' tab under the Jira integration setup page. 


Issue Type mappings

Here, map Jira issue types to Halo ticket types (and categories), this will determine what issue type is created in Jira based on the ticket type in Halo. 

Fig 6. Issue type mappings


You can also add category criteria here, if set only tickets of the chosen Halo ticket type and the selected category will be created as this issue type in Jira. 


In the figure x example when tickets with the type 'Change - Software' are sent to Jira they will be created as issue type 'Bug' unless they have the category 'Software>Feature' in which case they will be created with issue type 'Task'. 

Fig 7. Issue type mappings example


Custom Field mappings

Here, map Halo ticket custom fields to Jira project custom fields. This will determine what fields data from ticket custom fields in Halo are synced into in Jira.


These mappings are product/project specific, so you will need to map fields for each product/project you have. Additionally, you will need to ensure the Jira field you are mapping on is assigned to the work item in Jira and this field available on the new issue screen when creating new issues in Jira. As shown in figure x. 

Fig 8. Custom field mappings example


Priority Mappings

Here, map Halo priorities to Jira Priorities, this will determine what priority the issue has when created in Jira. 

Fig 9. Priority mappings example


Component mappings

Components can be selected against the ticket raised in Halo using a system field in Halo. The components selected here will then be synced to the project in Jira in line with the component mappings. 


Note: You will need to be using Jira components (not Compass) in your Jira project to use component syncing. 


To map components you will first need to enable syncing of components to Jira in Halo using the 'Sync the components field to Jira' under the 'Syncing to Jira' tab. 

Fig 10. Enable component syncing


Once enabled, hit 'Jira Component mappings' to begin mapping. Here, you will need to create each of your Jira components in Halo, all the components listed here will be available when selecting a component in the 'Jira component' field. 

Fig 11. Add new component in Halo


When creating the component you will need to enter the component ID of this component in Jira and choose which Jira instance this component is stored in. 

Fig 12. Mapping component to Jira component


Defaults for New issues created from Halo

You can choose various default values that will be used for new issues created in Jira by Halo. To set these values head to the Miscellaneous section under 'Syncing to Jira' tab under the integration setup page. 

Fig 13. Defaults for new issues


Description for new Issues - Here enter the description you would like to be used for new issues. This will only be used if the ticket details field is not populated. 

Default value for Reporter - Here, choose the reporter you would like to be assigned to new issues in Jira. This will only be used if the reporter field is not populated/used. 

Default value for Send Attachments to Jira - Here, choose whether you would like attachments against the ticket in Halo to be sent to Jira when syncing, by default. This will only be used if the field 'send attachments to Jira' is not populated/used.

Name of Jira Issue Type to use by default - Here, enter the name you would like all new issues in Jira created by Halo, to have. This will only be used if the ticket summary is not populated. 


Determine how many Jira issues can be linked to a single Halo ticket (and vice versa)

Halo supports the functionality to either have many tickets in Halo linked to a single issue in Jira or have a single Halo ticket linked to multiple Jira issues. 


The way in which tickets can be linked is set globally for the integration. To choose your ticket linking type head to configuration > integrations > Jira Software > Syncing to Jira > see 'Ticket linking type'. Here you can choose how tickets are linked to Jira issues. 

Fig 14. Set ticket linking type


Important: Changing the ticket linking type will remove all existing links between Halo tickets and Jira issues. If this setting is changed, you will need to re-link any tickets/issues using your configured action. 


Now we have configured how tickets are synced to Jira we can configure the action to trigger the sync. 


Sync Jira Version

If you have configured software releases in Halo, including releases, you can sync the release information over to Jira so the issue created in Jira has the version information. 


To do this first ensure you have enabled versions (releases) against your Jira project(s). Then you will need to map each release in Halo to a version in Jira. 


Head to Software releases > select a product > select a release > under the details set the 'Jira Version Name', here you will need to enter the Jira version the release relates to. 

Fig 15. Set Jira version against release


Once you have mapped your releases you will need to ensure your ticket type in Halo has the 'version' field against it. 

Fig 16. Version field against ticket type


Note: The version that is synced to Jira is determined by the version selected in the 'version' field, not the 'release' fields. 


Now, when the ticket is raised in Halo, if the version is chosen against the ticket, this will populate the 'Fix version' field against the issue that is created in Jira. 


Send a Ticket to Jira

Tickets in Halo are synced to Jira using an action with system, use 'Create Bug/Issue/Work Item', however, additional fields can be added to the action to determine what data is synced across. 


Head to configuration > tickets > actions > new, name the action and set system use 'Create Bug/Issue/Work Item'.

Fig 17. Action to send ticket to Jira 


Figure 18 shows all the Jira-relevant fields that can be added to the action to improve/control what data is sent to Jira. The field 'Send to Jira' must be added as this triggers the sync to Jira. 

Fig 18. Fields used when sending a ticket to Jira


Red Fields= Mandatory for sync. 

Blue Fields= Not Mandatory but good to have. Remaining estimate will populate the 'time tracking' field in Jira. Original Estimate will populate the original estimate field in Jira. 

Yellow Fields = Only needed if using these entities in Jira.

Green = Any custom fields, custom fields that are being synced can either be completed against this action or against the ticket type. It is your preference whether to set these here or on the ticket type. 


Note: These fields will only be available to add to the action once the integration module is enabled and the system use for the action has been selected. 


Once this action is configured ensure it is added to the relevant workflows.


When syncing the ticket first ensure you have set the relevant fields against the ticket, such as the priority and product. Then you can use the action created to trigger the sync.

Fig 19. Action to sync ticket to Jira in use


You must ensure the field 'Send to Jira' is checked for the sync to occur. 


A pop-up message will occur after sync to confirm the ID of the work item that was created in Jira. 


Syncing The Reporter

To have the new issue assigned to the chosen reporter you must assign the ID of the Jira User to their corresponding Agent record. Set this under the 'Integrations' tab of the agent profile, this will become available when the integration is enabled. You can find your Jira ID in the webpage URL when viewing your user profile in Jira. 

Fig 20. Set Jira ID for Halo agent


Send Updates to Jira from Halo

Once an issue has been created in Jira from Halo, further updates to the ticket can be synced over to the Jira issue, including comments, mapped custom fields and any of the Jira fields shown in figure x. 


To do this you will need to configure an action with the following setup:

  • system use = None
  • Send to Jira = True
  • Field list = Note (for comments) plus and other fields you would like to be updated. 

Fig 21. Action to update linked Jira issue


Once this action is configured add it to the relevant workflows to make it available for your agents to use. When used the linked Jira issue will be updated. 


Manually linking a ticket to an existing Jira issue

If you would like to link an existing ticket in Halo to an existing issue in Jira, this can be done using the 'Link to Jira Issue' system action against the Halo ticket. 

Fig 22. Link existing ticket to existing Jira issue


Before this action is used you will need to ensure the ticket has the 'Product' field populated with the correct product, the issues available to link will be determined by the the project linked to this Halo product. 


When used you will be able to search all issues under the Jira project linked to this ticket, when selected the link will be made. When searching you will need to enter at least one word contained in the issue summary, partial word searching is not supported. 


Managing linked issues

Once a Halo ticket has been linked to a Jira issue a 'Jira' tab will appear against the ticket. Here, you can see all the issues the ticket is linked to as well as who the issue is assigned to and the status of the issue in Jira. 

Fig 23. Jira issues linked to ticket


Selecting the line will open the issue in Jira. Right-clicking on the line will allow you to set this as the primary issue and unlink the issue. 


An issue only needs to be linked as the primary issue if you have allowed a single Halo ticket to be linked to multiple Jira issues.


Syncing Updates back to Halo

Updates in Jira can be synced back to Halo for the following events:

  • New issues in Jira will create a ticket in Halo
  • Updates to issues in Jira will sync to the linked Halo ticket (this includes updates to any Jira fields that are mapped to Halo fields). 
  • Comments added to issues in Jira will sync to the linked Halo ticket. 

New issues created in Jira can created tickets in Halo, additionally updates from the issue created in Jira can be synced back to Halo using webhooks. To enable this functionality head to the 'Syncing from Jira' tab under the integration setup page in Halo and enable 'Allow Jira webhooks to be processed by HaloPSA'. 

Fig 24. Enable webhook processing


From v2.192+ you can add a level of authentication to the webhook using the 'authentication' field. 


Signature Validation - When this option is selected you will need to generate a secret for the webhook in Jira. This secret will then need to be added to the integration setup in Halo, this will be checked before the webhook is processed, providing an additional layer of security. 

No authentication - When selected no webhook authentication will take place, this is a less secure method. 


Once this is set head to Jira and create a webhook (https://developer.atlassian.com/server/jira/platform/webhooks/), the URL for the webhook will follow the format:

You can configure a webhook that triggers for one/all of the following events:

  • Issue - Updated
  • Issue - Created
  • Comment - Created

Once configured navigate back to Halo. 


Under the settings section of  'Syncing from Jira' you will need to set what defaults are used for ticket created by Jira as well as some of the update behaviour. 


Fig 25. Settings for updates from Jira


Default Type - Here, choose the default ticket type new issues from Jira will be created as in Halo. 

Default User - Here, choose the default user tickets in Halo, created from Jira, will be assigned to. 

Actions created from Jira updates are private - Here choose whether Jira updates to tickets are created as private actions or not. Private actions will not be visible to end users.

Only update linked Ticket status from the primary issue - When you have your ticket linking type set to allow a single Halo ticket to be linked to multiple Jira issues, the ticket status will only update in line with changes to the primary issue status, rather than when any linked issue's status changes. 

Comment must contain the following text to be added to linked Tickets - Here you can restrict which comments against the issue in Jira are sent to Halo. If a string is entered here the comment in Jira will only sync to the ticket in Halo if the comment contains this string. This can be used to allow agents to choose when comments are synced. 

Remove the text value from the note - If the above field is populated this option can be checked to remove the string (text value) from the comment that is synced to Halo. 


Status mappings

Jira and Halo statuses will need to be mapped together to determine what status the ticket in Halo is updated with when the linked Jira issue's status changes. 


Monitoring Sync

Once setup is complete and you have begun syncing tickets/issues between Halo and Jira you can use the 'Inbound Requests' and 'Outbound Requests' tabs to monitor sync requests and outcomes. This is useful for troubleshooting any issues. 

Fig 26. Tabs contains webhook logs


Each log entry can be clicked into to obtain more information on the request and response. 

Popular Guides

Pin It on Pinterest