Native Jira Integration: Setup Guide

Useful Links for Jira Integration Setup

• Automation Rules Library
• JS mappings Library
• Additional Feature Toggles List
• Dev Portal: Work Sharing API documentation, how to write JS mappings, comparators and dynamic routings
• How to validate the data quality
• How snapshot service work for integrations
• End user guide

Important to know before Jira Integration Setup

Setup prerequisites

POC or basic test prerequisites

1. Jira Service User, Permission, Authentication

Jira Service User and Targetprocess Authentication

To authorize all actions from Targetprocess in Jira. The user name will appear in ACTIVITY Logs and History, and the user will be an author of all changes in Jira, triggered by Integration (add comment, change state and other fields).

We recommend having a service user dedicated to Targetprocess integration. A dedicated user avoids connection issues and integration interruptions when Jira is configured to prompt CAPTCHA after several failed attempts to log in. If somebody else is using the same Jira user credentials, then CAPTCHA blocking can get enabled and the integration will not be able to sync the data unless CAPTCHA is resolved by the user.

Credentials of Jira service user to authenticate the Targetprocess

Jira Service User Permissions

1. Add/Edit/Delete access for all issue types, comments, attachments and in all projects, will be synced to Targetprocess.
2. ‘Manage sprints’ (if Team Iterations will be synced with Jira Sprints)
3. Global Admin (with permission to request ‘edit workflow’) is required if customer requests for seamless automatic states mappings (if names match, but transitions do not, then integration user with a Global Admin permission can calculate the transitions and apply any of the available)
4. 'Edit comments’ permission is required if comments synchronization is requested (permission to edit comments posted by other Jira users).

2. Jira data set for testing (Jira project for pilot)

For integration setup and testing purposes, you will want an (UI) access to test project in Jira allowed for testing – add or change issues, manage sprints, browse issues in the project, post comments, attachments, etc. OR real POC mappings from PSs

3. Get URL to Jira Rest API

For integration profile to be set up, you need API URL. If Jira users browse it by different URL, it must be provided in the profile so that proper links to Jira issues were generated in Targetprocess.

4. Jira Webhooks setup

Jira webhook needs to be set up for every integration profile. Jira Administrator assistance is required.

Usually, Jira Administrator from a customer side has access to this part of the Jira configuration, so we need to request them to add a webhook and add it for every new profile. Webhook settings are all in the profile instructions (different for Server and Cloud in terms of Attachments)

If using dynamic routings, then it might be a better idea to add JQL filter to Jira and exclude some projects if it is known that the projects will not integrate with Targetprocess. Otherwise, all events of non-integrated projects will come through and error will appear showing target routing was not found.

All other JQL filters in the webhook must be avoided, Jira has common defects with the post reactions to some events when filters apply.

Note: Integration will not work if webhook is set with the body excluded. We need to receive a JSON:

Remember to update webhooks in Jira, if Targetprocess account changes its URL.

5. Jira accessibility for requests from Targetprocess

• Jira must be available for API requests from Targetprocess.
• Allowing Targetprocess IPs may be required on the customer side. The general process is the following:
  1. The range is available at https://community.ibm.com/community/user/apptio/blogs/apptio-community-member/2023/01/16/targetprocess-public-ips-range?CommunityKey=55a3712d-1835-4ec2-bcd7-603e88cd9dd2
  2. If a customer doesn’t have access to the community yet, they request access here: https://community.apptio.com/home/request-community-access
  3. A customer allows the entire IP range. Single IPs are no longer provided.
  4. A customer is subscribed to this page (`Follow` button)
  5. When IP is about to be changed - the support team modifies the IP range on the community page
  6. Subscribed customers receive notification and add this new IP as well

6. Feature toggles

• Initial import from Jira. Comments with the back link to Targetprocess will be added to every Jira issue during the import which generates multiple email notifications to Jira Users. Consider disabling the feature toggle that adds link to Targetprocess entity as a comment in Jira. Enable it after import, if Targetprocess entity link will not be mapped to Jira custom field.

  WorkSharing:Linking:SkipComment

• Delete operation sync is disabled by default on all clusters. However, if a new private cluster is added for a customer, please ensure that delete synchronization is still disabled and WorkSharing:DisableDeleteOppositeEntity is turned ON

WorkSharing:DisableDeleteOppositeEntity

• Some fields can not be synced one way only:
  • Actions like Delete and Convert sync bidirectionally by default when feature toggle WorkSharing:DisableDeleteOppositeEntity is disabled. Default bidirectional sync of Delete or Convert could be set up in a custom way with the automation rules. (Rules could be found in the library. In February 2023 samples will be publiched on dev.targetprocess.com)
  • Mapped and linked collections and relations sync bidirectionally and that could not be set up to sync one way yet (planned for S1 2023). For example, Jira Epics mapped to Features, Stories to User Stories (child collections) and all other types as a regular Relations. It is currently not possible to limit relations sync direction and sync only stories from Targetprocess and bugs only from Jira. Relations sync both ways, fields sync in selected direction. Mind, that project routings regulate new issues creation, and do not affect fields synchronization.

More feature toggles that are not available yet from user interface are listed here.

Mappings

Integration setup is available for Targetprocess Administrators only from Settings > Integrations.

Every integration requires an integration profile where all rules for synchronization are defined. One profile can be connected to one single instance of Jira / ADO / Targetprocess.

Separate Integration Profiles

• One profile can work with one Jira instance.
• Departments (unit, team) are independent, work issues between departments have no relations to each other, and at the same time workflows are very different. Different workflows mean different types/fields mappings. For easier mapping maintenance, split such business units to separate profiles.

Multiple Sharing

WorkSharing:MultiSharing WorkSharing:Jira:SkipIntegrationUserEvents

One Targetprocess parent entity can be shared across several Jira instances with different integration profiles. It means that all properties, including child collections, will be shared across all instances. In order to keep child items in their dedicated Jira and avoid auto-push to another Jira instances, apply filters in the Routings for a specific entity types.

Batch push to Jira supports only one, first matched profile.

Routings

Routings do not affect sync of existing pairs, they regulate an initial creation of a synced pair of issues.

If an issue was pushed to Jira to a Project A, and then routings were updated to exclude Project A from further syncing, it means that you will not be able to push/pull issues to/from that project. But those items that were pushed and linked earlier will proceed to sync as long as types and fields mappings are valid.

Static Routings

Static routings mean simple cases, when projects selector are used in mappings and we map Targetprocess Projects/Teams to Jira Projects.

Every static routing has additional filters. With these filters, you define what conditions must be met in order to sync issue to/from Jira/Targetprocess.

Advanced JS routings for dynamic mapping

This is a JS code for setting conditions of scope mappings. We use it for complicated cases, when target project can be different depending on the values of certain fields. Library with examples

For example:

• Targetprocess Portfolio Epic contains work that creates a separate project in Jira, mapping is not project to project, but Portfolio Epic to Jira Project. Then we add CF ‘Jira Project Key’ to Portfolio Epic and calculate the target Jira project for all child items based on this abbreviation in Portfolio Epic. Example.
• Project in Targetprocess will depend on the field value selected in Jira or vice versa – Targetprocess Entity syncs to Jira project based on custom field, selected at the parent level.
• Additionally any sophisticated set of additional filters and conditions such as, ‘pull child entities if their own project is equal to their parent’s project’. Example.

Auto-push / Auto-pull

Both routing types, static and dynamic, have options for auto pulling or pushing cards.

Auto-push from Targetprocess to Jira

With auto-push enabled all Targetprocess entities will be pushed to Jira as soon as they are added or modified and pass the filter in the routings. Entity is pushed to Jira as new.

Should you need to link Targetprocess items to existing Jira issues, then auto-pull must be disabled. As a workaround you can unlink Targetprocess entity from its Jira issue and link it again to another Jira issue. Unless it gets updated by some other service or user that triggers auto-push again.

Auto-pull from Jira to Targetprocess

We recommend enabling auto-pull and pull Jira issues automatically if you want all issues to be synced immediately, as soon as they are updated or created and match sync filters.

It is not possible to pull cards from Jira manually apart from import.

Entity type mappings

Any Targetprocess entity can be mapped to Jira issue, including Extendable Domain hierarchy. We do not support Test Cases sync and QA area due to multiple nesting levels in the hierarchy.

If you map one type to several different from the other side, then initial import will always consider the first matching types mapping. Should you need to select a specific type, use JS routings where you can define conditions, which custom field values will mark a specific issue type for import.

If you delete type mapping in a running profile, all issues synced by that mapping will be unlinked and stop syncing.

Field mappings

Some fields are supported by default. In case any additional custom behavior is required, use JS mappings. Remember that JS mappings need a custom comparator to be added in order to be considered in data validation reporting.

Library of all JS mappings examples

Supported by default

1. Simple fields like number/text to number or text, date fields, object to text will sync by default.
2. Single and multiple selectors sync by default if their values match by name. Selectors with different, not matching by name, options require JS mappings. See example of Priority JS mapping.
3. States mappings
   • By default States will match by name. If names do not match, then states are matched by flag ‘isInitial’ or ‘isFinal’.
   • If names match but workflows and allowed transitions don’t support such transfer, then possible transitions will be requested and any suitable applied, IF integration service user has permission Global Admin. Without Global Admin permission, search for possible transfers between two selected states is not possible without JS mappings.
   • If names do not match, then JS mapping for states is required
4. Targetprocess Team mapping
   • By default Assigned Team will sync by name to a single-select in Jira
   • Assigned Team to Jira multi-select field
   • Team to Jira Components
5. Components mapping
   • Components to multi-select in Targetprocess, bi-directional mapping with adding new components in Targetprocess automatically;
6. Time Tracking
   • Import actual time spent/remain totals as one time record (old domain Time) to User Story, Bug or Task from Jira Issue Total Time Spent/Remain
7. User mapping

• Targetprocess Role Assignment to Jira Assignee; Creator – Reporter;

In case of mapping Jira users to Targetprocess user fields, integration will create a new user of integration type.

Important. Integration user type:  Users with enabled property ‘isIntegration’ are available for all operations as regular Targetprocess users: assign to work, filter work by users, etc. The difference between regular and integration users is that the last cannot log in to Targetprocess. Integration users are created automatically by integration, when a user email in the assignments is met and no match is found among existing TP users. Integration users could be added manually via API post requests or CSV import. License counts integration users separately from regular users. Currently a total of integration users can be found in the Account > Licenses only.

Important. Email visibility in Jira Cloud: Default user mapping for Jira Cloud users requires a visibility if Jira User email. With not accessible emails, use JS mappings to map users by Jira account stored in ATP custom field.

Jira Assignee is a single-select field. Targetprocess role assignment is multiple. By default when you assign more than one user into mapped role in Targetprocess, then every latest user will sync to Jira Assignee. When assignment change in Jira, it resets all assigned in Targetprocess but latest user set from Jira.

Should you need multiple assignment in Jira, use multi-select Jira field of type ‘User’

• User to Text custom field

Email by default will be pasted to text field. Should you need Full Name or any other details instead of email – add JS to the field mapping.

Not supported fields. Not recommended mappings

The list will be continued as soon as new fields that cannot be supported are discovered.

1. Jira Original Estimate field updates via API triggers and Time Remain and Time Spent recalculation in Jira. Therefore, we do not recommend posting directly to Jira Original Estimate.
2. Effort. Effort field is a calculated field in Targeprocess. Without disabling effort calculation and redefining its calculation with metric, it will regularly update automatically to match Effort Completed and ToDo.Therefore, Effort could be mapped one-way only, to show the total in Jira. But it is not recommended to pull any numbers from Jira to Targetprocess Effort field. To work with effort, use Role Efforts fields – Developer role effort or Solution Owner effort. Then effort will be calculated automatically and correctly based on the effort of the responsible assignees.
3. Created Date in Targetprocess cannot be mapped and set for issues pulled from Jira. First, integration creates an empty issue, and then applies fields values. Created Date can be applied only at the moment of creation, not later. Such change would affect performance, so we suggest mapping Jira Creation Date to Targetprocess date custom field.

Team Iterations > Jira Sprints

There are two different ways to synchronize sprints and assigned work.

1. Recommended default solution is to map and sync Targetprocess Team Sprints as Jira Sprints. As you link Team Iteration to an existing Sprint in Jira, or push as new, Start/End Dates, Description and all the mapped work items will sync to and from Jira.Every team iteration must be linked to Jira sprints. Jira sprint must relate to a board. That is why integration must know, which projects and boards new sprints could be created at. So you must map Targetprocess teams to Jira Boards and all team’s sprints will appear in a selected project and board. End user guide on how to push or link sprints

   ????Only scrum Jira projects could have sprints, only such will be suggested in the Targetprocess Teams - Jira Boards mappings. Team cannot be mapped to kanban board and project.

    

   ????Jira service integration user must have ‘Manage Sprint’ permission granted in Jira

   Every new team iteration could be automatically pushed to Jira with additional Automation Rule

2. Any JS mappings for syncing Team Iteration as a field of synced issue. In the case JS updates the sprint field of Jira and Targetprocess entities without syncing Sprint’s dates and description. Example of such JS mapping

Relations

It is possible to map and sync relations between two Jira issues to Targetprocess.

If you navigate to Relations tab of the profile and match the relations, they will start syncing and appear in Relations tab in an entity view

For example, with types mapping as below and relations as above, if Jira Epic has a ‘Blocks’ type link to a Jira Bug, and both these Jira issues sync to Targetprocess as Feature and Bug appropriately, then ‘Blocker’ relation will be added between Targetprocess items.

Here is where you will find relations between two issues linked to Jira issues:

Relation to the Jira issue where type is mapped in integration profile, replicates in Feature view > Relations tab.

Technical details

View customization

In most situations, entity views will be customized automatically with the ‘Synced Work’ tab as default. It is the last tab in the view. The order of tabs could be changed if needed in ‘Detailed Views’ settings.

If for any reason ‘Synced Work’ was not added automatically after integration profile setup is completed, you can add this block manually

• Tab

{ 
"title": { 
"type": "string", 
"value": "Synced Work", 
"localize": true 
}, 
"component": { 
"type": "work-sharing-v2/v2", 
"component": "WorkSharingInfoComponentV2", 
"componentId": "work-sharing-v2-some" 
}, 
"componentId": "section_si4pcbc" 
},

• Right side panel

{ 
"type": "work-sharing-v2/v2", 
"component": "WorkSharingInfoComponentV2", 
"componentId": "work_sharing_component" 
},

If account has views customization off, then ‘Synced Work’ block shows in the right panel for Request, Bug, Task, User Story, Feature, Epic, Portfolio Epic and Team iteration, with no regard to types mapping in the profile.

Why ‘created by issue level integration’ issues appear, required fields default values reset and ‘Create Date’ cannot be synced

In order to tolerate more errors, integration first creates an empty entity with the technical name such as:

Then this template will be filled in with field values one by one according to mappings. Those which fail to apply will be skipped. If you meet an entity names ‘created by issue level integration (ID)’, it means that field values were not applied yet, partially, or at all.

You can call pull/push updates for such entity, if it’s linked to an issue, to update the fields and check the logs for actual sync errors. If entity is not linked still, it can be removed safely.

Average Synchronization Time

Sync operations may delay for different reasons (import of new issues set is in progress, Jira limits the access for some period of time or is not accessible). To know how long it would take to pass changes between two systems, you can refer to an average update time. The number is approximate and more valid for constantly working profiles. Average update time is calculated from the last 10 updates. That is why if last update occurred yesterday, you will then see a time valid for yesterday’s load.

The average time of updates can be found in the list of integrations for every running profile.

And also in the entity view, below the logs:

Logs and errors

All logs for issue level integration can be found in Settings > Diagnostic and Logs > Service Logs. Here, the most full logs from all native integration profiles are shown.

Logs, filtered by profile appears at the bottom panel inside an integration profile under link ‘View messages log’.

Specific entity sync errors and log appear in the entity view, ‘Synced Work’ area if you click errors count or ‘View messages log’ link.

Invalid link errors

• If type mapping was deleted while profile was disabled or not accessible. For example, you linked several issues and then deleted corresponding types mappings from profile. Sync will be aborted, and sync rule deleted. Previously, we did not delete rules, so old items may show a following message. It will not sync anymore and entity must be re-linked manually (unlink + link to existing or push).

And moments later, you add exactly the same types mapping back into profile, this pair of linked items will not get fixed automatically – this types mapping will be considered as a different one, it will have another ID. And all issues, linked and synced previously with the deleted types mapping must be corrected manually – unlinked from sync report and pushed / linked again.

• You can see the message ‘Linked issue was deleted’ when one of two linked issues was deleted while delete/convert actions support is disabled or integration profile was disabled or Jira was not accessible.If Jira issue was converted or moved to another Jira project and its KEY and/or issue type changed, then pair becomes not valid. It must be fixed manually – issues must be unlinked and pushed or linked to Jira issues again using correct mappings.