Skip to content

Jira Connector

Jira Connector is an add-on to JustOn that integrates JustOn Billing & Invoice Management with Atlassian Jira. It retrieves tracked time data from Jira and saves it to dedicated worklog records in Salesforce. Consequently, you can use JustOn's usage data billing to generate invoices.

Info

Jira Connector requires at least the Salesforce Enterprise Edition.

In broad strokes, the data retrieval works as follows:

  • Jira Connector is installed in your org.
  • You have set up a named credential for the authentication, and you have created a custom setting for your Jira connection.
  • Once all is set up, you actually retrieve the data. It is upserted using the Salesforce REST API to the worklog records in Salesforce.
  • Using JustOn's usage data billing, you generate invoices according to your requirements: During the invoice run, JustOn itemizes the worklog data and matches it against your defined subscription items. It evaluates the provided quantity information and calculates each item's subtotal, which then makes up the according invoice line item.

Info

This document describes how to set up Jira Connector in order to enable the worklog data retrieval. For details about setting up worklog data invoicing, see Usage Data Billing.

Jira Connector Implementation Details

Jira Connector relies on a named credential and a matching custom setting in order to connect to a Jira instance (either on-premise Jira Server or Jira Cloud).

The Jira instance must comply with the following conditions:

  • Jira must be accessible via Internet.
  • The access from the Salesforce IP ranges must not be blocked by a firewall.
  • The Jira instance must be accessible using HTTPS with TLS 1.1 or TLS 1.2.
  • The SSL certificate must be signed by a trusted SSL Root Certificate (no self-signed certificates).
  • All intermediate certificates must be available during the SSL handshake.
  • The Jira worklogs must be stored in the Jira database (some 3rd party Jira plugins store data to other servers).

The worklog data is structured in worklog periods and worklogs. Worklog periods and worklogs are in a master-detail relationship.

Worklog Object

The Worklog object holds the actual worklog data. It includes all fields that are available in the Jira worklog and, in addition, some Jira issue-specific fields. The following information is available:

Field Jira Source Field Data Type Description
Name - Autonumber
W-{000000000}
-
Author worklog.author.displayName Text(255) The Jira user who created the Jira worklog, falls back to worklog.author.name or UNKNOWN for inactive/deleted Jira users.
Comment worklog.comment Long Text Area(2000) The comment saved with the Jira worklog, truncated to 2000 characters.
Connection - Text(255) The name of the Jira connection.
Created worklog.created Date/Time The creation timestamp of the Jira worklog.
End - Formula(Date/Time) The end time, calculated by the worklog.started timestamp and the worklog.timeSpentSeconds field.
Hours Worked - Formula(Number) The number of worked hours accumulated for this worklog.
Issue Components issue.components Text(255) A comma-separated list of Jira issue components.
Issue Description issue.description Long Text Area(32768) The description saved with the Jira issue.
Issue Id issue.id Text(255) The ID saved with the Jira issue.
Issue Key issue.key Text(255) The key ID saved with the Jira issue, is set to UNKNOWN if the issue is not accessible.
Issue Summary issue.summary Text(255) The summary saved with the Jira issue, truncated to 255 characters.
Issue Type issue.type Text(255) The name of the Jira issue type.
Project Key project.key Text(255) The project key saved with the Jira issue, is set to UNKNOWN if the issue is not accessible.
Started worklog.started Date/Time The start timestamp of the Jira worklog.
Time Spent worklog.timeSpent Text(255) A human-readable time spent string ( 2h 30m).
Time Spent Seconds worklog.timeSpentSeconds Number(18,0) The duration tracked for the Jira worklog in seconds.
Update Author worklog.updateAuthor.displayName Text(255) The Jira user who updated the Jira worklog, falls back to worklog.updateAuthor.name or UNKNOWN for inactive/deleted Jira users.
Updated worklog.updated Date/Time The timestamp specifying when the worklog has been updated by the Update Author.
URL worklog.self URL The permalink to the worklog in the Jira UI, falls back to a REST URL if the issue is not accessible.
Worklog Id worklog.id Text(255) The ID of the worklog, prefixed with the connection string ( JIRA_10003). This field is used to upsert existing worklogs without knowing their Salesforce ID.
Worklog Id (No Prefix) worklog.id Text(255) The ID of the worklog without prefix.
Worklog Period - Master-Detail(Worklog Period) The ID of the master worklog period.

Note

The Jira issue-related fields remain empty if the user who retrieves the worklog data has no access to the related issue.

Info

If required, you can

Worklog Period Object

The Worklog Period object can be used to combine worklogs using your own criteria. JustOn keeps at least one worklog period record per Jira connection.

The worklog period includes the following information:

Field Data Type Description
Key Text(255) A unique identifier, used to upsert existing worklog periods without knowing their Salesforce ID.
Connection Text(255) The name of the Jira connection.

Info

If required, you can create additional fields to roll up values from worklogs to worklog periods.

Setting Up Jira Connector

Info

Jira Connector requires at least the Salesforce Enterprise Edition.

Contact the JustOn support team 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. In Setup, 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 password of a Jira user who has access to all worklogs and issues.
  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. In Setup, 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.

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

Retrieving Worklog Data

JustOn retrieves the worklogs from Jira via the Jira REST API using a chain of queueable Apex jobs. JustOn retrieves new and updated worklogs first. After that, it retrieves the deleted worklogs and deletes the corresponding records in Salesforce as well.

You can control the worklog retrieval manually or using a scheduled job.

Upon execution, you can monitor the status of the queueable jobs via the Apex job queue. To do so, look for the Apex classes UpsertWorklogManager and DeleteWorklogManager.

The user who has triggered the refresh receives an email upon completion. The email includes statistics about the refreshed worklogs and periods, and, if applicable, also error messages.

Manually Retrieving Worklogs

You can manually retrieve or refresh worklog from the Worklogs list view.

  1. Open the Worklogs tab, and select the list view All.

    The list view Recently Viewed does not display the Refresh button.

  2. Click Refresh.

  3. Select the intended Jira connection.
  4. Specify a start date.

    • Leaving the start date empty retrieves all worklogs.
    • Setting a start date in the past retrieves the worklogs starting from this date.
  5. Click Start.

    This starts the worklog retrieval.

Note

If you connect to a Jira instance that integrates Tempo Timesheets and you have not added the Tempo user access token, JustOn displays an according error message. The message provides a link to the Tempo API Token page for you to add the token.

Scheduling Worklog Retrieval

You can set up a job in order to have worklogs automatically retrieved on a regular basis.

To schedule the worklog retrieval, you can use either Salesforce's Schedule Apex functionality or the Salesforce Developer Console. For details, see Scheduling a Job.

Via Salesforce's Schedule Apex functionality:

  1. In Setup, open Apex Classes.

    In Salesforce Lightning, navigate to Custom Code > Apex Classes.

    In Salesforce Classic, navigate to Develop > Apex Classes.

  2. Click Schedule Apex on top of the list.

  3. Specify the details as required.

    • Job Name: The name of the Jira connection setting (see Defining Jira Connection Setting)
    • Apex Class: ScheduledRefreshWorklogs
    • Frequency: Weekly or Monthly (with an according weekday or day of month setting)
    • Start
    • End
    • Preferred Start Time
  4. Click Save.

    This sets up the worklog retrieval to be executed at the specified time.

Via the Salesforce Developer Console:

  1. Open the Developer Console.

    For details, see Open the Developer Console in the Salesforce Help.

  2. Execute the following code

    JOJC1__ScheduledRefreshWorklogs.setupSchedule(name, schedule);
    

    where name is the name of the Jira connection setting (see Defining Jira Connection Setting) and schedule is a cron expression.

    This sets up the worklog retrieval to be executed at the specified time.

For more details about job scheduling, see Scheduling a Job in the JustOn documentation and Schedule Apex in the Salesforce Help.

Using Jira Cloud With Tempo Timesheets

If you use the Tempo Timesheets Jira plugin, the worklogs are not stored in the Jira database. It is therefore necessary to retrieve the worklogs from a different REST endpoint.

Note

Use Tempo Timesheets with caution. The Tempo Worklog API is currently marked as experimental and has some shortcomings compared to the original Jira worklogs:

  • No support for paging: Be aware of operation issues if there are more than 2000 worklogs per week.
  • No support for changed or deleted worklogs: You must re-import all worklogs to circumvent this limitation.

JustOn does not guarantee the correct operation of the Jira integration with Tempo Timesheets.

Setting up Jira Connector for a Jira instance that integrates Tempo Timesheets involves the following specific tasks:

Configuring Jira Connection

You must create a dedicated custom setting and named credential for the Jira connection as described above.

The JIRA Connection custom setting requires the following specific information:

Field Possible Value Notes
Worklog Source TEMPO Must be set to TEMPO in order to switch the REST endpoint.
Last Upsert Refresh not empty Must be set before the first import. Must be set to a date before the first Tempo worklog in order to retrieve all worklogs.
Batch Size Set this to a number between 200-500 if you expect many worklogs per week.
Shift Date/Time by Hours Tempo reports the date/time values in the user's time zone. If your Salesforce instance uses a different time zone, you must specify a correction value to adjust the date/time values.

Adding Tempo User Access Token

  1. Generate a new Tempo user access token in your Jira account.

    Make sure your Tempo plugin is properly installed, then open Tempo > Tempo Settings > Create User Token.

  2. Copy the token.

  3. In your Salesforce org, open the Tempo API Token page.
  4. Paste the token.
  5. Click Save.