Jira Integration Setup
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.
- 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.
- 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.
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:
- Go to Setup > Named Credentials and click on New Named Credential:
- Give your named credential a name, e.g. Jira Integration.
- 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:
- 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.
- 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.To generate your access token, go to: https://id.atlassian.com/manage-profile/security/api-tokens.
- Set the Generate Authentication Header checkbox to True.
- 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:
- Navigate to the Copado Integration Settings tab and click on New.
- Give your integration a name, e.g. Copado <> Jira.
- Select JIRA from the External System drop-down menu.
- In the Name Credential field, provide the exact same name of the named credential you created in the previous step (API name).
- 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:
- Go to Setup > Object Manager > Project.
- Click on Project Layout to adjust the layout.
- Add the following fields to the layout:
- JQL Extended Filter
- Project External Id
- Copado Integration Setting
- Enable Logs
- Team Info
- Add the following buttons to the layout:
- Sync External User Stories
- Sync User Stories with Sprints
- Add the Field Mappings related list and include the following fields in it:
- Field Mapping Name
- Salesforce Field Name
- Third Party Field Name
- Exclude from Salesforce
- Exclude from Third Party
- Created by
- Last Modified by
- Add the Callout Logs related list.
Setting Up Your Project
It is time now to set up your project or if you already have one, to update it.
- Navigate to the Projects tab and create a new project or edit your existing project.
- Update the Copado Integration Setting field and select the Copado Integration Setting record you created in a previous step.
- Set the Enable Logs checkbox to True.
- 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:
- 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/).
- Copy the content and paste it in a JSON formatter tool like https://jsonformatter.curiousconcept.com/.
- Get the custom field name from the key attribute:
- You can use this value to create new records in the Field Mapping object.
Your field mapping should look like this:
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.
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.