Copado JIRA Setup

Updated 4 days ago by Copado Solutions

  1. Install the Copado Change Management Integrations package, please see this article to get the links.

There is one for sandbox orgs and one for Production/Developer orgs. You can choose to install for admins only (recommended option) or for specific profiles.

  1. After the package has been successfully installed, go to SFDC Setup > Named Credentials:
    1. URL: In some cases a Jira URL can look like this: “jira.<CompanyName>.com”, in others something like this “<CompanyName>.atlassian.net”. Whatever the case, make sure to add the “https://” prefix and the “/rest/api/2/” suffix. If we use Copado as the Company Name example, the final URLs may look like these according to the case:
      e.g. https://copado.atlassian.net/rest/api/2/
      e.g. https://jira.copado.com/rest/api/2/
    2. Identify Type: Named Principal - this means that one user will provide the authentication for all callouts from Salesforce to the external application.
    3. Authentication Protocol: Password Authentication - username and password will be required to provide the authentication for 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.
    1. Generate Authentication Header: True.

  1. Go to SFDC Setup > Object Manager > Project.
    1. Edit the object layout - (if there is none yet, it may be a good idea to create a new page layout which you can use as the default page layout).
    2. Add the following fields to the layout:
      1. JQL Extended Filter
      2. Project External Id
      3. Copado Integration Setting
      4. Enable Logs
    3. Add the following button:
      1. Sync External User Stories
    4. Add the Field Mappings related list with the following fields:
      1. Field Mapping Name
      2. Salesforce Field Name
      3. Third Party Field Name
      4. Exclude from Salesforce
      5. Exclude from Third Party
      6. Created by
      7. Last Modified by
    5. Add the Callout Logs related list.
    6. Make sure you add the FLS and OLS access to the corresponding profiles or permission within your organization.
  2. Go to the Copado Integration Setting tab and create a new record:
    1. Name: Enter the desired Name (e.g. Copado <> Jira).
    2. External System: JIRA.
    3. Named Credential: Enter exactly the same name as the Named Credential record created in step #2 (please note that it is the API name and not the label).

  1. Go to the corresponding Project record. If there’s none, create a new one.
    1. Update the Copado Integration Setting lookup field with the Copado Integration Settings record created in the previous step (#4).
    2. Update the following fields:
      1. Enable Logs: True.
      2. Project External Id: Corresponding Jira Project Id value, which can be obtained from Jira by going to Project Settings > here the key should be displayed.

    3. Configure the Field Mapping object by doing an insert upload of the default mapping file Jira_Default_Field_Mapping.csv which can be found in the Git repository. Insert can be done by means of any of the Salesforce data upload tools such as data loader or metadata inspector.
      1. Before importing the file, you need to enter the corresponding Project__c record id in the CSV file.
      2. 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’ll get a JSON that describes all the fields of your Jira implementation (example with Copado’s Jira account: https://copado.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 that value to create new records in the Field Mapping object.

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 new 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.

Sample on how to schedule the fetch process can be found in the Readme file in the Git repository.

Update User Stories in Jira Based on Updates Within Copado

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.

Common Errors

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 Named Credential name in the Integration Settings record is not an exact match of the Named Credential that you set up. Make sure that the API name and the name of the 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, password URL or a combination of these is incorrect in the Named Credential. Please, try any of the following solutions:
    1. Re-enter the password and make sure it is correct.
    2. 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.
    3. Check the URL. In some cases a Jira URL can look like this: “jira.<CompanyName>.com”, in others something like this “<CompanyName>.atlassian.net”

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 on insert.


How did we do?