Summary
Data you can sync
Jira Issues
Core and Software Projects
Custom field mapping available
Jira Service Management (Jira Service Desk)
Sync direction
Core and Software Projects
Choose the direction of sync
This can be bidirectional, although not all data can sync bidirectionally
Jira Service Desk
Unidirectional into Planhat
Sync frequency
New/updated Jira Issues are automatically synced near instantly
Manual fetch to sync in historical Jira Issues
Data mapping
Issues from Jira Core and Software Projects are mapped to the Planhat Issue data model
Issues from Jira Service Desk are mapped to the Planhat Conversation data model, type "ticket"
Who is this article for?
All Planhat users
It's particularly useful for those setting up the Jira integration
Series
Setting up the Jira integration ⬅️ You are here
Article contents
Setting up the integration 🛠️ Main setup instructions here
Introduction
Planhat's Jira integration enables you to automatically sync your Jira Issues into Planhat - feeding into either Planhat Issues (e.g. feature requests and bug reports) or tickets (End User conversations) depending on the type/location of the Issue in Jira. You can use filtering (by project and JQL query) to specify which Jira Issues sync into Planhat. You're even able to create/update Issues in Planhat and sync some information back to Jira.
In Planhat, you get a complete 360° view of your customers - see their Jira data, together with other types of data (from revenue data, to emails, to Health Scores, etc.), in one place. For example, if you're a CSM / Account Manager, you can quickly and easily review all key data related to a particular Company before a meeting with them - otherwise, you might not have access to all the other systems where relevant data is stored, or even if you did, it could take a long time to search through them all.
You can develop a deeper understanding of your customers by easily performing data analysis, including on combinations of different data types - e.g. compare each Company's number of tickets to their subscription value, to identify who are the most expensive customers to manage.
You can automatically respond to significant events and trends, for maximum productivity - for example, automatically apply a Workflow Project (series of tasks/emails) if there is a significant increase in open Issues associated with a Company; or, you could set up an Automation to send a notification to Followers (you or your colleagues) when an Issue status is updated to "Resolved". Planhat makes it easy for you to display your data in customisable dashboards for even greater insight, and to share your data stories with your colleagues and customers.
Data mapping
Planhat model (1) | Sync direction | Jira Issues from ... |
Issue | Can be partially bidirectional (2) | Core and Software Projects |
Conversation (type "ticket") | One direction: from Jira to Planhat | Jira Service Management (formerly known as Jira Service Desk) |
(1) For more on the distinction between these two models, see below.
(2) When syncing between Jira Core and Software Projects to the Planhat Issues model, you can choose sync direction:
None
Receive from Jira
Send to Jira
Both directions
The Jira integration can sync to two Planhat models
Issue model
Jira Core and Software Projects Issues sync in as Planhat Issues. This is the most common setup / use case we see with the Jira integration.
The Planhat Issue model is used primarily for recording feature/enhancement requests and bug reports etc.
It's typically used by Product Development teams to manage their to-dos, although it's used by other teams to submit requests and keep an eye on what's been reported for their customers. This model is used internally: it's people within your organisation that create or update Issues, rather than Issues representing communication with individual customers.
Because of this use for feature requests and bug reports, the Issue model is unique amongst the Planhat data models in that it does not need to link to one Company - an Issue can relate to one Company, multiple Companies, or even no Companies. This makes sense when you think that a bug could be reported by one Company, multiple Companies, or no Companies (if it's noticed internally by you and your colleagues); it's the same with feature requests too.
Conversation model - tickets
Jira Service Management (Service Desk) Issues sync into Planhat as tickets on the Conversation model.
The Planhat Conversation model is used to store your communications with your customers. There can be various types - emails, Intercom chats, helpdesk tickets, meetings such kick-off calls and QBRs, and so on. The specific Conversation type called "tickets" (with a lowercase "t") are tickets from helpdesk platforms - Zendesk, Freshdesk, Salesforce Cases, and these types of Jira Issues.
Because they represent external conversations with your customers, they always and only apply to one Company in Planhat.
What is included in the bidirectional sync between Jira Issues and Planhat Issues?
📌 Important to note
We are specifically referring to the Issues-to-Issues sync here. Syncing to tickets is always one direction: from Jira to Planhat.
Syncing new Issues
The integration is able to create Issues in both Planhat and Jira.
Whether Issues are synced depends on the sync direction you have selected.
For example, if the sync is set to "Both Directions" ...
... and you create an Issue in Planhat, it will be synced to (created in) Jira
... and you create an Issue in Jira, it will be synced to (created in) Planhat
Syncing Issue deletions
The integration does not sync Issue deletions, so if you delete an Issue in either Planhat or Jira, it will not be automatically deleted in the other system regardless of the sync direction set.
If you want to delete an Issue, make sure you manually do so in both Planhat and Jira, otherwise:
If you delete an Issue in Planhat but not Jira, and then update it in Jira, it will get synced back into Planhat
If you delete an Issue in Jira but not in Planhat, and then update it in Planhat, you can get an error message
Syncing fields
Even if you set the sync to "Both Directions" (or "Send to Jira"), note that only a limited set of standard fields can be synced from Planhat to Jira: "title", "description", "issue type" and "related companies"; the rest (including custom fields) can only be synced from Jira to Planhat.
"Related companies" is only updated in Jira if either "company name" is selected in all cases, or "Company External id" field is selected (only if the company has an External ID).
How does the sync work?
Mapping Issues to customers
As described above, Issues are a special data model in Planhat, in that they don't have to be associated with a Company (whereas most other models do). Therefore, you can sync Issues into Planhat without specifying a way to link them to Companies.
If you would like to sync an association between Issues and Companies, you can configure this within the Jira integration. The matching works via a field in both systems containing the same keyword (e.g. the Company name or ID) - you specify the field details, and it can be either a text field or a (multi)picklist field.
For more detailed instructions, see here.
Mapping tickets to customers
Tickets are mapped in a different way. Like tickets synced in from other integrations, tickets synced in from Jira are linked to End Users via their email address. In Jira, this works via the "Reporter" field on the ticket.
The integration checks whether the ticket Reporter is an End User in Planhat. If the End User doesn't yet exist in your Planhat tenant, but the Company does (as identified by the email domain), Planhat can automatically create the End User on that Company, and then sync in the ticket. It's your choice whether you would like Planhat to create End Users from external conversations like this - it's configured per tenant. You can view your current setting under "Automatic Detection of New Contacts" within "General Settings"; speak to your CSM if you would like to enable or disable this.
Manual sync for historical Jira Issues
There is a button in the integration to manually "Fetch All Issues". This is typically used when you first set up the integration, in order to sync past Issues into Planhat. The historical sync brings in Jira Issues created or updated in the last 3 years. This process can take from a few minutes to hours depending on the number of Issues being synced. You can filter which Issues to fetch by defining a JQL query in the integration.
This manual sync may also be used later on, if you have made changes to configuration in the integration (e.g. changed "Projects to sync"). However, note that if you have made updates to Issues/tickets in Planhat, these changes could be overwritten if they are re-fetched from Jira.
Ongoing sync for new/updated Jira Issues
As part of the integration setup, you create a webhook in Jira.
Going forward, Issues that are new or updated in Jira will automatically sync into Planhat, in near real time.
Depending on the sync direction you set, some specific data can also sync from Planhat to Jira.
Setting up the integration
The Jira integration is easy to set up. Here's an overview of the steps:
Configuration in Jira
Configuration in Planhat
Let's go through these steps in more detail:
Configuration in Jira
Log into Jira and create a token
Log into Jira as an Administrator, and add a new token by clicking "Create API Token" in either location below:
Jira Cloud: https://id.atlassian.com/manage/api-tokens
Jira Data Center: Click on your Avatar > Profile > Personal Access Tokens
In the resulting dialog box, enter a suitable token label, such as "Token for Planhat", and click "Create".
Make sure you uncheck the automatic expiry checkbox if using Jira Data Center
In a later step, you will paste this token into the integration in Planhat
Create a webhook in Jira
Log into Jira as an Administrator (you are likely still logged in from step 1!) and go to either of the locations below:
Jira Cloud: Settings (bottom left corner) > System
Jira Data Center: Settings (top right corner)
Scroll down and open the "Webhooks" tab
Click "Create a Webhook"
Complete the form:
"Name" - give it a suitable name, such as "Webhook for Planhat"
"URL" - the unique URL for your Planhat tenant is shown in the left-hand panel of the Jira integration in your tenant
You navigate to the integration by going to the Operations Module, ensuring the "INTEGRATE" tab is selected, and using the search bar to search for "Jira"
"Issue related events"
Select "Issue (created, updated)"
Select "Comment (created, updated)"
"JQL query filter" - if you only want to sync a subset of Issues with Planhat, you should input the relevant JQL here, to limit the scope of the webhook (e.g. if you only want to sync in Issues with a particular status). Make a note of this, as you should also enter the JQL in Planhat to define the scope of the "Fetch All Issues" process for historical tickets - more on this later
Click "Create"
Configuration in Planhat
Activate the Jira integration in Planhat
If you don't already have it open, navigate to the Jira integration in Planhat
Go to the Operations Module, ensure the "INTEGRATE" tab is selected, and use the search bar to search for "Jira"
Turn the toggle switch at the top to "ON"
Complete the form:
"Jira Administrator Username (your email)" - this is the administrator email address you use to log into Jira
"Your Jira URL (should start with https://)" - this will be of one of these formats:
If you have Jira Cloud: https://[yourJiraDomain].atlassian.net/rest/api/2
If you have Jira Data Center: [yourJiraDataCenterDomain]/rest/api/2
"API Access Token" - copy and paste the token you created in Jira in the first step
Configure JQL query for the historical/manual sync
You can optionally use JQL to set the scope of the "Fetch All Issues" process
Generally you'll want this to match any JQL you have set as part of the webhook in Jira for the ongoing automatic sync
Note that although some information on this is displayed in the integration (shown below), you - as a Planhat user - can't actually set this yourself: a Planhat staff member will need to set this for you. Typically, your TAM will enter your JQL query as part of a setup call with you. If you have any questions, reach out to your TAM or CSM, or our Support team
Choose the sync direction for the Issues model
Select from the dropdown menu, as shown above
Note that this only applies to syncing between Core and Software Projects and Planhat Issues; when syncing between Jira Service Management (Service Desk) and Planhat tickets (Conversations), it's always "Receive from Jira"
Select which project(s) to sync
Click "Fetch projects and fields" (shown above)
Use the toggle switches (example shown below) to specify which of your Jira projects you would like to sync Issues from
Specify how related Companies are matched between Jira and Planhat
If you would like to link Issues with Companies (so this is referring to the Issue model in Planhat), here you can determine how the matching will work
The Jira integration is special in that you can choose how the mapping is done - you specify a field in Jira and a field in Planhat. This could be a text field or (multi)picklist field
For further details, see discussion here
Configure custom field mapping
Here, you can specify which fields in Jira sync with which fields in Planhat
📌 Important to note:
Field mapping is only for syncing Jira Issues with the Planhat Issue model - it does not apply to syncing Jira Issues to Planhat Conversations/tickets
Custom fields can only be synced in the direction of from Jira to Planhat, not from Planhat to Jira
When you select pairs of fields (each consisting of one Planhat field and one Jira field), ensure the field types are the same within each pair
You should include a line of field mapping for the fields you're using to match Issues to Companies (as in step 5)
To set up the custom field mapping:
In the left-hand column, select a Planhat field from the dropdown menu
In the middle column, select the field type (see note above)
In the right-hand column, select a Jira field from the dropdown menu
Click "Add a match" to add a new row (pair of fields)
Click "Save"
If everything is working correctly, Planhat will show you a success message. If you get an error, double check the URL above
Your Jira Issues can now sync automatically into Planhat! You can verify you've set it up correctly by creating or updating an Issue in Jira, and see it appear in Planhat
Initiate the sync of historical Jira Issues
To do this, click "Show Fetch All Section" and then "Fetch All Issues"
This will trigger full historical sync with Jira, syncing Issues from the past 3 years
This process can take from several minutes to multiple hours depending on the number of Issues
Remember you saw how you can filter which Issues to fetch by defining a JQL query
Matching Issues to Companies
As described above, Issues are a special data model in that they don't have to be associated with a Company (whereas most other models do). Therefore, you can sync them into Planhat - creating them in Planhat - without specifying a way to link them to Companies.
If you would like to sync an association between Issues and Companies, you can configure this within the Jira integration. The matching works via a field in both systems containing the same keyword - you specify the field details, as described below.
You can use Planhat system fields or custom fields. Ideally, these fields should have the same type in Planhat and Jira (e.g. text).
If you can't see the relevant field dropdowns, click "Fetch projects and fields".
Text field
If you are using a text field in Jira to record the Companies associated with a Jira Issue, in cases where there are multiple Companies per Issue, you'll typically use a specific punctuation mark (symbol) to separate the keywords (names or IDs) for different Companies in the field, such as a comma (,) or a forward slash (/).
To configure this in the Jira integration:
"Jira Fields" - select the Jira field from the dropdown menu
"Jira Fields Type" - from the dropdown menu, select "String with multiple values (e.g. comma-separated)"
"Separator" - type in the punctuation mark (symbol) you are using to separate the references to the different Companies within the Jira field
"Planhat Field" - use the dropdown menu to select the relevant Planhat field, such as "Company External Id" or "Company Name". (This can be a custom field created for this purpose, e.g. "Jira Mapping Name")
Optionally, you can click "Show more" to open up additional configuration - for example, you can choose whether the matching is case sensitive
If you're using a text field and it only contains a reference to one Company per Issue, you can select "String with single value" from the "Jira Fields Type" dropdown menu. This is simpler to configure - you don't need to select a "Separator" because there aren't multiple values being separated in the field.
Multiple selection field
Alternatively, it may be that you are using a multiple selection (multi-select or multipicklist) field in Jira for associating Companies to Issues in Jira. These types of fields have predefined options for the user in Jira to select, rather than free typing into a text field.
To configure this in the Jira integration:
"Jira Fields" - select the Jira field(s) from the dropdown menu
"Jira Fields Type" - from the dropdown menu, select "Array of strings"
"Planhat Field" - use the dropdown menu to select the relevant Planhat field, such as "Company External Id" or "Company Name"
Optionally, you can click "Show more" to open up additional configuration - for example, you can choose whether the matching is case sensitive, like you saw for text (string) fields above
Issues within Planhat
Okay, so you've synced your Jira Issues into Planhat - what next?
There are two main places to view Issues in Planhat: the Data Module and Company Profiles, as shown below. In both places, click on the symbol of 4 horizontal lines next to an Issue name to open it up to see details, make changes and leave comments etc.
As with other Planhat data models, you can analyse Issues data via the Customer Intelligence Module.
Data Module
If you'd like to view all Issues in Planhat - regardless of which Company they are associated with, or even whether they are associated with a Company at all - you can do this via the "Issues" tab of the Data Module.
This is a particularly useful view if you are in the Product Development team, for example, as you can see all the incoming feature requests and bug reports that your team can work on. As usual with the Data Module, it's easy to create filters (with your choices of conditions and columns) and apply Grouped View if desired, so you can separate bugs from feature requests, or split by Issue status or priority, etc.
Click the image to view it enlarged
Company Profile
If you want to view the view the Issues associated with a particular Company, you can view them via the "Issues" tab on Company Profiles.
The Issues tab of the Company Profile will display all Issues updated or created in the past 3 years related to that Company. The number next to the tab name indicates how many of those Issues are currently "open" - see "Tip" box below to learn how this is defined.
As with other Company Profile tabs, you can modify the columns shown in the data table.
Click the image to view it enlarged
🚀 Tip
You define within your tenant settings how Issues are defined as "open". As a Planhat admin, put your mouse over your initial/photo in the bottom left, and click "Issues". Define a condition (e.g. Status is equal to Open) and then click "Save". If you don't specify a condition here, all Issues will be considered to be open.
📌 Important to note
The Issues tab on a Company Profile:
Only shows on an individual Company Profile if there is at least one Issue to display
May be nested under the "MORE" section (as shown in the earlier screenshot)
May not be part of a Company Profile if a Custom Company Profile Template is applied
Speak with your internal Planhat admin or your Planhat CSM if you have any questions.
Tickets within Planhat
Tickets are stored in Planhat as Conversations of type "ticket".
You can view the tickets themselves on the Company and End User Profiles, as well as in the Conversations Module. It's easy to apply filters - to specifically show tickets (just filter by type is equal to "ticket"), or to look for ticket with a particular tag (e.g. "Tier 1" or "bug"), for example. In the Conversations Module, you can even build more advanced filters based on ticket fields you are syncing in, such as Type or Priority. You can comment on tickets in Planhat, to tag in other colleagues, for instance.
In addition, within the "Metrics" tab of the Data Module, ticket volumes can be saved as time-series data (under the "Conversations" category). You can build on this raw time-series data with Calculated Metrics - for example, tracking trends over time, or comparing a Company's number of ticket with the amount of money they are spending with you. In Pages (in the Customer Intelligence Module), you can create graphs to analyse and visualise ticket data, including field data.
Further reading
If you have any questions about why an Issue hasn't synced into Planhat, check out our troubleshooting tips here.