OpenAir-Jira template guide for advanced users

Introduction

Many organizations today use JIRA, OpenAir or any other relevant tool for project management purposes and often times these tools could be used by diverse audience and user groups. For example, for the same project, the Engineering teams may be using JIRA to log and track issues and enter a Worklog, whilst the Project Managers would use OpenAir to track the overall project. There arises a need to keep both the systems in sync to ensure greater accuracy of metrics and also to avoid double entries and leakage of effort.

This template explores frequently implemented integration use cases between OpenAir and JIRA and provides an out of the box integration which is also customizable by an Intermediate level user, Developers or Integration partners. This document provides an overview of the high level flows that come with the template and provide steps for the user to get started.

Prerequisites

1. You must have valid credentials for both OpenAir and JIRA application to be able to set up the connections.

2. Setup any custom fields that may be required on the integrating applications. Refer to the Custom Fields and Lookups section for more info.

3. When scheduling the flows, ensure that Parent objects are synchronized first.

4. Ensure that both systems have the Users synchronized.

5. To be able to customize the template, an understanding of OpenAir XML APIs and JIRA Webhooks will be helpful.

Integration Flows

1. OpenAir Project to JIRA Project Create/Update (Batch)

This flow synchronizes Projects created in Openair as Projects in JIRA. It also supports the update of Projects from OpenAir to JIRA.

2. OpenAir Project Task to JIRA Issue (Batch)

This flow synchronizes Project Task in Openair to JIRA as Issues. It supports both create and update operations.

3. JIRA Issue to OpenAir Project Task (Batch)

This flow synchronizes JIRA Issues as a Project Task in OpenAir.

4. JIRA Worklog to OpenAir Timesheet entry (Real Time)

This flow synchronizes the Worklog entry made against any issue in JIRA on a particular day to a user’s Timesheet as a time entry in OpenAir. A time entry in OpenAir is a task created on a user’s Timesheet for a client , under a project on a given day. This can also correct the time entry whenever you correct the same worklog entry.

Note: It is assumed that Users will already be synchronized between the two systems. In case such a flow is required, it can be created as a DIY flow.

Create Connections

OpenAir connection (Type: REST/XML):

Please follow the instructions below to populate the fields for OpenAir connection.

JIRA connection (Type: REST/JSON)

Ensure that the login credentials being used have the required permissions to access records via REST. A user with Admin role level permissions would be ideal for testing the template.

Setup JIRA Webhook

Once the connections are set up, You will need to create a webhook on JIRA for the ‘JIRA Worklog to OpenAir Timesheet’ flow. JIRA Webhooks allow real-time synchronisation based on events that occur in JIRA, in our case we shall use Webhooks to synchronise JIRA Worklogs with OpenAir TimeSheet time entry.

To set up the Webhook , go to ‘JIRA Worklog to OpenAir Timesheet entry’ flow and select the JIRA Worklog Export in Page Generator.

JIRA Worklog Export adaptor:

Update the custom URL token and regenerate Webhook URL. Copy that URL and go to your JIRA account.

1. Navigate to JIRA Administrator->System-> Webhook (left side bottom).

Paste the above copied URL from integrator.io on to the JIRA Webhook URL input box and check all the required fields as shown in the screenshot above.

Custom Fields and Lookups

1. You are required to manually create the following custom fields in your OpenAir account:

a. Jira_project_id on Openair Project record to store jira project id

b. Jira_issue_id on Openair Project Task to store jira issue id.

Note: When you create a custom field, OpenAir automatically assigns a suffix "__c"  to the custom field name and creates the internal field id for the custom field. Therefore, when you create the Jira_project_id and Jira_issue_id custom fields, OpenAir automatically assigns field id's for these custom fields as Jira_project_id__c and Jira_issue_id__c.

2. OpenAir allows you to filter records based on custom fields. To filter records, you are required to:

• Add property: enable_custom = “1”
• Add internal field id of the custom field: Jira_issue_id__c or Jira_project_id__c

as demonstrated in the following example. This information can be added in the template lookup criteria, mappings, or exports.

3. In JIRA Worklog to OpenAir Timesheet entry flow, there is a lookup configured to search for Users in OpenAir, which will need to be updated to specific needs. In this template, we have assumed that the JIRA Username field value is same as the user’s email address.

How and where to modify?

Traverse to the OpenAir Timesheet Lookup adapter in the flow and in the Mapping, open the UserId Lookup.

You can edit the Post Body XML to suit your requirements to be able to successfully search for users in OpenAir.

Orchestrations

The data flows mentioned in this user guide are all orchestrated flows. For more information on the orchestrated flows used here, refer to Orchestration Notes.

 Assumptions

1. The mappings in the flows have been created with minimum required fields for data creation. A user can add more fields in the mapping, provided, those are available in the response of the Webhook or API response call to respective systems.

2. Worklog time entry is converted to minutes and updated on OpenAir where it is internally converted to hours.

3. Users on both the systems are assumed to be in sync.

4. User ID in JIRA will be the user’s email address.

5. There could be a need to sync only those objects (Projects, Issues/Project Tasks, Worklogs) which are marked by the user for sync. This could be either set in a Webhook in JIRA or as a flag/boolean on the object and checked against in the flow.

Limitations

We cannot use both ‘Openair Project task to JIRA issue’ flow and ‘JIRA issue to Openair Project Task flow together’. In this case, only one system/application always need to be the master and that system will create and update the other system. If used together there could be a case that an update could trigger recursive updates.

References

• JIRA Rest API Documentation
• OpenAir API Documentation