Jira Integration Setup

Updated 1 day ago by Copado Solutions

The instructions provided in this article are for the new unlocked package. If you are working with the old Change Management Integrations unmanaged package, follow the instructions provided in this other article.

Introduction

If you work with external project management systems, such as Jira or Azure DevOps, you can integrate them with Copado. To do that, you need to:

In this article we will show you how to configure the Jira integration step by step.

Considerations

  • Once you are done configuring the new package, don’t forget to uninstall the old one.
  • If you are using Jira on-premise, you must follow additional steps to grant Jira access to your servers. For more information about this, check out the article Jira on Premise.

Setup

The first thing you need to do is log in to our Success community and install the package. You can install the package in a sandbox or a production/developer org and install it for admins only, which is the recommended option for all users or specific profiles.

Configuring the Named Credential

Once the package has been successfully installed, you need to configure a named credential. According to Salesforce, a named credential specifies the URL of a callout endpoint and its required authentication parameters. To configure a named credential, follow the steps below:

  1. Go to Setup > Named Credentials and click on New Named Credential:

  1. Give your named credential a name, e.g., Jira Integration.
  2. Enter a URL. There are two URLs available for Jira: jira.<CompanyName>.com (if you are using Jira on-premise) and  <CompanyName>.atlassian.net. Regardless of the URL you are using, make sure you add the https:// prefix and the /rest/ suffix. The final URLs would look like this:
    E.g., https://copadoacademy.atlassian.net/rest/
    E.g., https://jira.copadoacademy.com/rest/
  3. In the Identify Type field, select Named Principal. This means that one user will provide the authentication for all callouts from Salesforce to the external application.
  4. Select Password Authentication from the Authentication Protocol drop-down menu. Since Jira deprecated basic password authentication a while ago, you need to provide a username and an API token instead of a password.
  5. Set the Generate Authentication Header checkbox to True.
  6. Click on Save. Your named credential would look like this:

Creating the Copado Integration Setting Record

The next step is creating a new Copado integration setting to link your named credential with the project you will use to import your user stories. To do this, follow the steps below:

  1. Navigate to the Copado Integration Settings tab and click on New.
  2. Give your integration a name, e.g. Copado <> Jira.
  3. Select JIRA from the External System drop-down menu.
  4. In the Name Credential field, provide the same name of the named credential you created in the previous step (API name).
  5. Click on Save. Your record should look like this:

Updating the Project Layout

Once you have configured the name credential and the Copado integration setting, you must adjust the Project layout and reference the Copado integration settings.

To update the layout, follow these steps:

  1. Go to Setup > Object Manager > Project.
  2. Click on Project Layout to adjust the layout.
  3. Add a new section named Jira Integration with the following fields to the layout:
    1. JQL Extended Filter
    2. Project External Id
    3. Copado Integration Setting
    4. Enable Logs
    5. Team Info
    6. Enable Community Users
In the Team Info field, you can specify the teams whose sprints should be fetched. If you don't specify anything, sprints from all teams will be fetched.
  1. Add the following buttons to the layout:
    1. Sync External User Stories
    2. Sync User Stories with Sprints
  2. Add the Field Mappings related list and include the following fields in it:
    1. Field Mapping Name
    2. Salesforce Field Name
    3. Exclude from Salesforce update
    4. Third Party Field Name
    5. Exclude from Third Party update
    6. Created by
    7. Last Modified by
  3. Add the Record Type Mappings related list and include the following fields:
    1. Salesforce Record Type Name 
    2. Third Party Record Type Name
  4. Add the Callout Logs related list.

Make sure the relevant profiles or permission sets have the right field-level and object-level security settings. 

Updating the User Story Object

Once you have updated the Project layout, it is time to update the Status field picklist to reflect the picklist options for this field within Jira. This is to ensure the seamless bidirectional update of the status field.

To update it, follow these steps:

  1. Go to Setup > Object Manager > User Story.
  2. Click on Fields and Relationships and find the Status field.
  3. Edit the picklist values to reflect the available values for the Status field in Jira.
If you use a workflow to change the status in Jira, you have to use a transition value (case sensitive) in the Status field of the user story. API and Label Name of this field should match exactly with the transition value you have in Jira.
Setting Up Your Project

It is time now to set up your project or, if you already have one, to update it.

  1. Navigate to the Projects tab and create a new project or edit your existing project.
  2. Update the Copado Integration Setting field and select the Copado Integration Setting record you created in a previous step.
  3. Set the Enable Logs checkbox to True.
  4. If you want to include any active community users for user field mapping in the sync, you need to flag the Enable Community Users field. 
    1. This allows you to include or exclude community users in the Jira sync with Copado. The default value is unchecked, so if you want to include any active community users for user field mapping, such as Assignee to Developer, you can check this field to enable them.
  5. Paste your Jira external Id in the Project External Id field. You will find this Id in Jira in the Key field under Project Settings:

Configuring the Field Mapping

Configure the Field Mapping object by inserting the default mapping file, which can be downloaded using the following link: Jira Field Mappings. The insert can be done using any Salesforce data upload tools such as a data loader or metadata inspector. Before importing the file, you need to enter the corresponding Project__c record id in the CSV file.

Custom field mappings can be created manually from the Field Mapping related list or by uploading a CSV file.  To do so, you will need the Salesforce API name of the field that you are mapping to and the key for the field in Jira.  The Jira field key can be found by appending the following to the URL of your project in Jira: rest/api/latest/field/

The results can be reformatted in a more palatable manner using a JSON formatter like: https://jsonformatter.curiousconcept.com/#

If you want to map a number field (e.g., user story points), all you need to do is to select integer in the Target Field Type picklist field and leave the Exclude from Third Party update and Exclude from Salesforce update checkboxes deselected.

Copado supports integration for label, dropdown, checkbox, and people type custom fields for Jira. For custom field mapping to be successful, you need to:

  • Enable Exclude from Third Party update in Project.
  • Fields getting mapped on the Salesforce side should be either multi-select (unrestricted) or text with maximum length, as there can be multiple values selected at the Jira end for these fields.

Jira does not accept fields that are not displayed on the page layout, so they need to be on the page layout in Salesforce for the fields to sync.

The integration is not compatible with mismatched field types between Salesforce and Jira.

Copado can match any user field included in the mappings. The matching value used in the mapping will always be an email address. For example, if you want to map the Assignee field in Jira to the Developer field in Copado, this will only work if the user(s)' email address matches both Jira and Copado. The email address must only match characters, case sensitivity has no impact.  

  • Example:
    • The following will match on sync:
      • Email address for Debbie Smith in Jira: DSmith@copado.com
      • Email address for Debbie Smith in Copado: dsmith@copado.com
    • The following will not match on sync:
      • Email address for Debbie Smith in Jira: DSmith@copado.com
      • Email address for Debbie Smith in Copado: debbie.smith@copado.com

To map both fields, Assignee, and Developer, you first need to create a new record field mapping.

If you've restricted the visibility of users' email in Jira, Copado cannot bring that email address, and the sync will not be successful. For further understanding of this approach, please review the Troubleshooting section. 
Configuring the Record Type Mapping

Mapping Issue Types with Record Types in the Field Mapping object is supported in the JIRA integration. 

You need to manually configure the Record Type Mapping records for the following record types:

Record Type Mapping records for Jira

To do that, follow the steps below: 

  1. Navigate to the Projects tab.
  2. Select the project you want to map.
  3. On the Record Type Mapping related list click on New:
Create a New Record Type Mapping

  1. Fill in the data as required and click on Save
    1. Example for Bug record type:
      1. Salesforce Record Type Name: Bug.
      2. Third Party Record Type Name: Bug.
      3. Click on Save.
      Data required for creating a new record type mapping

Repeat the process for all the other record types. 

Optional Steps

Schedule User Stories Retrieve

You can schedule an Apex job to retrieve the user stories from Jira based on your preferred frequency.

The class ScheduleUserStoryFetch has been created to perform a bulk import of User Story records from the external provider to Salesforce. Depending on the configuration of its cron expression, it will carry out the bulk operation periodically. It will retrieve all the mapped fields and will update the Salesforce fields with the external data.

Find below a sample script on how to schedule the fetch process:

//Parameters to use on schedule job 
String myProjectRecordId = 'your_project_id'; Boolean withSprint = true/false; 

//Now let's schedule the project sync for everyday at 12:00
copadoccmint.ScheduleUserStoryFetch scheduledClass = new copadoccmint.ScheduleUserStoryFetch (myProjectRecordId, withSprint);
String scheduleJobId = system.schedule('UserStoryFetch - DailyJob', '0 0 12 1/1 * ? *', scheduledClass);

A process builder flow called SendUpdatedValues2TP has been created to update changes in user stories on the external provider. It is executed every time a change in a user story is detected and will send the modified fields to the external object fields. You can change the criteria of this process builder to update it to your needs/process.

Troubleshooting

You can check for errors in Salesforce Setup > Apex Jobs. Errors are most likely related to the named credential:

  • First error: The URI is invalid:
    It is most likely that the name in the Named Credential field in the Copado Integration Settings record is not an exact match of the name in the Named Credential record that you set up. Make sure that the API name and the name of the named credential in the settings are the same:

  • First error: Unexpected character ('<' (code 60)): expected a valid value (number, String, array, object, 'true', 'false' or 'null') at input location [10,2]:
    It’s likely that the user is incorrect in the Named Credential. Check your username. Depending on your organization's configuration, your username can have an email format such as John.Doe@company.com or a non-email format like john.doe.

If both Apex jobs are successful but no user stories are inserted into the Copado project, put a debug trace on the user running the sync (Salesforce Setup > Debug Logs. Using the dev console debug level is fine). Review the logs as these can give you an idea of what is causing the records to fail upon insert.

  • Mapping Jira Assignee to Copado Developer is not getting synched: If the email address of the user is set to private in Jira,  no email address is sent to the integration and the result will be:
    • NO match on sync
      • Email address for Debbie Smith in Jira: dsmith@copado.com, but no email address {NULL} is sent in the integration since the user has their email set to private in Jira.
      • Email address for Debbie Smith in Copado: dsmith@copado.com

You can review the GDPR security settings for users' email addresses in the Atlassian article to understand why some of your Jira user story assignees are synched to Copado as user story developers and others are not.


How did we do?