action.skip

Setting Up Jira Connector

Info

Jira Connector requires at least the Salesforce Enterprise Edition.

Contact JustOn Support to have the add-on installed in your org.

Setting up Jira Connector involves the following tasks:

Creating Named Credential

To allow the access from Jira, you need a named credential.

  1. Click to enter Setup, then open Named Credentials.

    In Salesforce Lightning, navigate to Security > Named Credentials.

    In Salesforce Classic, navigate to Security Controls > Named Credentials.

  2. Click New Named Credential.

  3. Specify an appropriate label and API name, for example, Jira.

  4. Specify the Jira base URL.

    Find the base URL in the system configuration section of the Jira administration.

  5. Select Named Principal as the identity type and Password Authentication as the authentication protocol.

  6. Specify the user name and API token of a Jira user who has access to all worklogs and issues.

    To get the Atlassian API token:

    1. Access the Jira user's account settings.
    2. Open the Security page, then click Create and manage API tokens.
    3. Click Create API token, and follow as prompted by the wizard.
    4. Copy the created token.
    5. Paste the token to the Password field of your new named credential.

  7. Select the checkbox Generate Authorization Header.

  8. Click Save.

Defining Jira Connection Setting

You define basic parameters for connecting to your Jira instance using a JIRA Connection custom setting. It provides the following fields:

Field Possible Values Description
Name name of the named credential The unique name for the custom setting record.
Must match the name of the named credential created before.
Batch Size empty | 1 - 1000 The batch size defines the maximum number of worklogs that are processed at the same time. If empty, falls back to the default Jira page size (1000).
If there are limit issues when refreshing worklogs, specify a smaller value.
Last Upsert Refresh date/time value | empty The timestamp of the newest worklog. If empty, the next refresh retrieves all existing worklogs.
Last Delete Refresh date/time value | empty The timestamp of the last deleted worklog. If empty, the next refresh retrieves all deleted worklogs.
Shift Date/Time by Hours pos/neg numbers
1,-1,2.5		 Specifies a correction value to adjust time zone differences between Salesforce and Jira. Imported date/time values are shifted by n hours (positive and negative values allowed).

To define the settings for your Jira connection:

  1. Click to enter Setup, then open Custom Settings.

    In Salesforce Lightning, navigate to Custom Code > Custom Settings.

    In Salesforce Classic, navigate to Develop > Custom Settings.

  2. Click Manage in the row of JIRA Connection.

  3. Click New.
  4. Specify the details as necessary.
  5. Click Save.

Adding Jira Custom Fields

Jira allows to add custom fields (with various data types) to issue records. Jira Connector can retrieve the data of these fields and add them to the worklog records in Salesforce.

All custom fields in Jira share a similar field name, like customfield_10001. In order to add a particular Jira custom field to the Worklog object, proceed as follows:

  1. Obtain the name of the Jira custom field.
  2. In Salesforce Setup, navigate to the fields list of the Worklog object.
  3. Create the new field(s) as required.

Note

  • Make sure to select the appropriate data type.

  • The API name of the custom worklog field in Salesforce must be identical to or end with the name of the custom issue field in Jira, like customfield_10001__c.

    Find the name of the relevant field calling the Jira Cloud platform REST API via

    https://<your-domain>.atlassian.net/rest/api/3/field

    as explained in Issue fields in the Atlassian Developer documentation.

For help about creating fields, see Managing Object Fields.

Example custom worklog fields
Jira Custom Field Jira Data Type Salesforce Custom Field Salesforce Data Type Notes
customfield_10001 Date customfield_10001__c Date
customfield_10003 Number StoryPoints_customfield_10003__c Number(18,0) Make sure that the number of decimal places matches.
customfield_10024 Complex JiraAccount_customfield_10024__c Text(255) Complex data types from Jira plugins are serialized to JSON and stored as text. You may consider a formula or process/workflow to parse the resulting JSON.

Enabling Worklog Data Summaries on Worklog Periods

Your business may require to show summarized worklog values on the worklog period. To this end, you create roll-up summary fields on the Worklog Period object with the name of the worklog fields to be "rolled up". JustOn then summarizes the individual worklog values and sets the result in the corresponding worklog period field.

  1. Navigate to the fields list of the Worklog Period object.

  2. Create the new field(s) as required.

    Make sure to use the API names and data types of the original worklog fields.

    For help about creating fields, see Managing Object Fields.

Example worklog period summary fields
Worklog Field Worklog Period Field Notes
IssueKey__c IssueKey__c "Rolls up" the issue key from the worklog to the worklog period.
CustomField_10001__c CustomField_10001__c "Rolls up" the value of customField_10001 from the worklog to the worklog period.

Enabling Worklog Distribution to Worklog Periods

You can distribute worklogs to different worklog periods. To this end, you define a formula field on the Worklog object. The formula determines the criterion by which the worklog is associated to a worklog period.

  1. Navigate to the fields list of the Worklog object.

  2. Create the following new field as required.

    API Name Data Type Description
    WorklogPeriodKey Formula(Text) Determines the criterion by which the worklog is associated to a worklog period.

    For help about creating fields, see Managing Object Fields.

Example worklog grouping formulas
Intention Worklog Period Key Formula Notes
Group worklogs by issue IssueKey__c JustOn creates one worklog period per Jira issue and links the worklogs to them. Worklogs with an unknown issue are linked to the worklog period UNKNOWN.
Group worklogs by year and month TEXT(YEAR(DATEVALUE(Started__c))) + '_' + TEXT(MONTH(DATEVALUE(Started__c))) JustOn creates one worklog period per month and accordingly associates all worklogs of one month.
Group worklogs by customer CustomField_10001__c Assuming that CustomField_10001__c holds the customer name, this formula groups the worklogs by customer.