Jira Integration Setup

Updated 1 hour 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 are working with external project management systems, such as Jira or Azure DevOps, you can integrate them with Copado. In order to do that, you need to:

  • Install Copado’s Change Management Integrations unlocked package, which is available for download in the Copado Labs section in our Success community.
  • Follow the steps to configure the relevant integration. 

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

Considerations

  • If you are migrating from the unmanaged package and have made any customizations, it is recommended that you save your custom code and do not uninstall the old package until you have successfully configured the new package.
  • Once you are done configuring the new package, don’t forget to uninstall the old one.
  • If you are using Jira on premise, you will need to follow some 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 in a production/developer org, and choose to install it for admins only, which is the recommended option, for all users or for 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 exact 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 need to adjust the Project layout and reference the Copado integration settings there.

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 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. 
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 doing an insert of the default mapping file which can be downloaded from Copado Labs. The insert can be done by means of any of the Salesforce data upload tools such as data loader or metadata inspector.

Before importing the file, you need to enter the corresponding Project__c record id in the CSV file.

If you have custom fields that you want to use as part of the integration, you can get the field name as follows:

  1. Append rest/api/latest/field/ to your URL and you will get a JSON that describes all the fields of your Jira implementation (example with our account: https://copadoacademy.atlassian.net/rest/api/latest/field/).
  2. Copy the content and paste it in a JSON formatter tool like https://jsonformatter.curiousconcept.com/.
  3. Get the custom field name from the key attribute:
  4. You can use this value to create new records in the Field Mapping object.
    Your field mapping should look like this:
Field Mapping
If you want to map a number field (e.g. user story points) all you need to do is 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 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?