Native Targetprocess – Jira integration

How to view Jira Issue information in Targetprocess

'Synced Work' block

Jira links will be shown in the entity detail view by default. It will either be a block in the right-hand side panel (for old-layout views) or a ‘Synced Work’ tab (if a customizable layout is enabled). ‘Synced Work’ shows info relating to the Jira issue or, if the entity is not linked yet, a menu - Push as new / Link to Existing - is shown. This button(-s) name is the name of the integration profile(-s)

In the ‘Synced Work’ of a linked entity, two areas are the most important:

• Hyperlink to Jira issues and actions menu
• Log Messages

Customize Entity View with a Tab or Right Panel Block

If a customizable layout is enabled, then, in most cases, Entity view will be customized automatically with the ‘Synced Work’ tab. It will be the last tab on the view and could be relocated, if needed, in the detailed view configuration.
If tab or block is not shown, it is most likely because this entity type mapping was previously removed from profile and then added back, or it has a dynamic routing. In this case the view might require manual customization.
If ‘Synced Work’ must be shown as a tab, place this code between the code of the tabs in the order that you prefer:

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

If it must be a block in the right-hand side panel, use the following configuration:

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

Customize Board/List Views with Links to Jira

You can display a Jira icon or link in the Boards / Lists Views with no additional fields mapping.Simply customize cards with the ‘Synced Work’ unit. This is a short non-clickable unit to mark the cards which are shared to Jira

It could also be a hyperlinked unit with Jira Key. It’s named ‘External ID’ in view cards customization settings.

Search for Jira Key in Targetprocess

Should you want to search for Jira Keys in Targetprocess, then add a custom field to Targetprocess, like ‘Jira Link’, and add it to fields mapping (JS):
From TP to Jira

const workSharing = context.getService("workSharing/v2");
const tpApi = workSharing.getProxy(args.sourceTool);
const fieldId = args.sourceField.id
await tpApi.postAsync(`api/v1/${args.sourceEntity.entityType}/${args.sourceEntity.sourceId}`, {
body: {
[fieldId]: args.targetEntity.sourceId
}
});

From Jira to TP:

return {
kind: 'Value',
value: args.value.changed.toString()
}

Then, you have this ID in the custom field and can query Targetprocess for custom field values.

Actions: Pull Update from Jira, Push Updates to Jira, Unlink, Batch Push to Jira

How to (un-)link, pull updates, find errors

Near the Jira ID you have a menu under three dots:

These actions allow you to actualize either a Jira Issue with the changes applied in Targetprocess or the Targetprocess entity with updates from Jira, or break the link and stop syncing.

Push Updates

Pushing updates to Jira is not used often, as Integration sends all the changes to Jira as they happen. This action resyncs all the mapped fields of the selected entity, and fields in Jira will have the same values as they have in Targetprocess (if any differences were apparent).

Pull Updates

Pull updates will resync all the fields of the selected entity with the date from Jira, including  collections lists (set of Bugs, User Stories, etc.) but won’t update the fields of the child collections (i.e. Team Iteration of some Bugs if they changed).

Unlink

As soon as you unlink two issues, they stop syncing and you can re-link a Targetprocess Entity to something new in Jira. However, it’s important to note that, if you have auto-push enabled and this entity changes and still passses the filters, it will be pushed to Jira again, and pushed as a new item (this might cause duplicates in Jira).

Context Menu / Batch Actions  (TBD)

In the board or list views for the regular types (not Extendable Domain types), Jira menu can be found. Currently only ‘Push to Jira’ is available. It will attempt to push a batch of new issues to Jira, when you select which profile to use for that.  Entities that are already shared will not be pushed again.

Later, it will be a Jira menu with the batch Pull/Push updates  and Unlink.

Team Iterations Sync

Targetprocess team iterations are suggested to be synced seamlessly as Jira Sprints. Every Team Sprint will be linked to a Jira Sprint and they will sync Names, Descriptions and Start/End Dates.

You can also choose to sync not only Sprint details, but also automatically sync work assigned to Team Sprint in Targetprocess or in Jira to the Sprint (e.g. Users Stories, Bugs).

For example, if you link ‘Q1-2021-1’ team iteration to a Jira Sprint, then a Jira story, created and assigned to this Sprint, will be automatically be added to Targetprocess and assigned to the same team iteration.

When a team is mapped to the Scrum Board, the team iteration could be pushed to Jira.

You will see a button in the Synced Work block / Work Sharing tab of the iteration view:

With this button you can push iteration to Jira or link it to an existing Jira Sprint:

Like any other mapped entity types, team iterations can be pushed in a batch.

Import from Jira

Import from Jira imports all issues, selected with the provided JQL filter, if they match profile setup – types and project routings.

Then you need to press ‘Review’ and see the number of issues that are going to be imported. Following the ‘Preview in Jira’ link you can open issue list in a new tab and review import scope.

Issues that are synced already, will be skipped and won’t be imported again. You will see log message, that those issues were already been synced.

Note: should you need to import any issues as Targetprocess Tasks, you need to import only their parent User Stories. When parent relation link is set, then Tasks will be imported automatically. It is not possible to import Tasks directly.

Similar for other hierarchies.

If you have mapped hierarchy Feature (Jira Epic) ➜ User Story (Stories via Epic Link) ➜ Bugs, Tasks (Defects, Tasks via Parent of (or any other preselected link type), then you need to import only Jira Epics. All the rest will be imported automatically.

To import Bus or Stories separately you need in the case, when they are not connected to any imported parent entities.

Diagnostic Logs & Errors

Logs can be accessed from the detailed view of a synced entity and from Settings.

In the detailed view, you will see warnings, errors and logs of the entity syncs:

More logs can be found in the footer of the integration profile:

From Settings, logs for all profiles and messages if profile could not be identified (applies to exceptional cases):