Jira & Jira Align Integration: Syncing a Jira Date Custom Field with Jira Align Accepted Date

[#1]

Issue workflows in Jira can be quite complex. When integrating Jira with Jira Align workflows must be simplified in order to sync the Jira statuses with Jira Align states. It is recommended best practice that resolutions in Jira are also simplified to ensure that the Accepted Date of features and stories in Jira Align are syncs with the Resolution Date in Jira.

What if you need to use multiple resolutions within Jira for tracking additional metadata correlated to an issue status? By default the Jira Connector in Jira Align is configured to sync the Accepted Date for features and stories in Jira Align with the Resolution Date in Jira.

Jira Align Default Accepted Date Mapping (Admin → Jira Settings → Jira Setup → Custom Fields)

To support this mapping of Accepted Date to Resolution Date, the Resolution Date in Jira is populated by setting up a Post Function for when a story or epic (feature) issue is transitioned to the Done status (See article on Jira and Jira Align Integration: Story Resolution Transition Best Practices). In Jira, the Resolution Date is populated when ANY resolution is populated in a workflow. This limits story and epic (feature) workflows to having only one resolution which is Done that is configured as a Post Function for the final status in the workflow (typically Done).

To enable the use of multiple resolutions in a workflow, a new Date Picker custom field must be created in Jira. Below are the steps to configure a Date Picker custom field in Jira Cloud to sync with the Accepted Date in Jira Align. This solution can also be used with Jira Server or Jira Data Center but will require the use of a marketplace app such as JSU Automation for Jira Workflows that enables the creation of post-functions to update custom fields.

1. In Jira, navigate to Custom Fields in Jira Administration (Settings cog icon) and add a new custom field. On Select a Field Type, search for and select Date Picker (under Standard).

2. On the Configure [Field Type] Field window, add a name for the new custom field (ex. Accepted Date) in the Name field that can be easily associated to the Jira Align Accepted Date for work items. Click Create to create the custom field.                                           
3. Associate the new custom field to the issue screens for stories and epics (features) in Jira. One thing to keep in mind is that the Date Picker custom field type is an editable field which raises an issue because anyone can modify the Date Picker field to a different date after it has been set by the Post Function which will update the Accepted Date in Jira Align. To not allow the new Date Picker field from being modified by users do not select a screen to add the field to and skip to step 4.
4. To prevent the new Date Picker custom field from being modified, a separate view screen must be created in Jira with the Date Picker custom field added and associated to the View issue operation in the Screen scheme configuration for stories and epics (features). This enables the Date Picker field to be updated by the Post Function and viewed but not edited by Jira users. Navigate to Screen schemes → Configure.
5. On the Configure Screen Scheme page, click on Associate an issue operation with a screen.
6. Select View issue in the Issue Operation field and select the new view screen with the new Date Picker custom field in the Screen field. Then click Add.
7. Now only the View issue screen has the Date Picker custom field on the screen. The Create Issue and Edit Issue screens must not have the new Date Picker custom field present.
8. Next add a Post Function when an issue is transitioned to the final status for the story and epic (feature) workflows in Jira to populate the current date the story or epic (feature) is completed. Click on the transition to add the new Post Function in the Transition (id) column. In the example below, a Post-Function will be added to the transition to the Done status (red arrow).
9. Navigate to the Post Functions tab. Click on Add post function.
10. Select Update Issue Custom Field and click on Add.
11. Select the Date Picker custom field (ex. Accepted Date) in the Issue Custom Field. Enter %%CURRENT_DATETIME%% in the the Custom Field Value and then click on Add.                
12. The newly created post-function appears on the Post Functions tab. When the status is transitioned (in this example to Done) the Accepted Date custom field is populated with the date and time the status is updated which will sync to the Jira Align Accepted Date.
13. A Post Function for transitions to all other statuses in the workflow must be added to clear the Accepted Date field.                                
14. Navigate to Custom Fields in Jira and search for the Date Picker field that was just created (in this example Accepted Date). Identify the custom field ID for mapping the field to the Jira Align Accepted Date in the Jira Connector by navigating to … → Edit details.
15. On the Edit customer field details page, look for the custom field ID in the URL. This ID number is required in the next step.                        
16. In Jira Align, navigate to Admin → Jira Settings → Jira Setup → Custom Fields. Update the Accepted Date field with custom field ID from Jira in the format: customfield_NNNN. Then click on Save.

The end result…

The Accepted Date field on the view issue screen in Jira…

…syncs with the Accepted Date in Jira Align

This sounds great but what’s the catch?…

  Jira reports and chart gadgets may not be consistent with Jira Align reports

Some Jira reports and gadgets (ex. Created vs. Resolved Issues Report) use the resolution date of issues which may be different than the Accepted Date for stories and features in Jira Align due to those two dates not being synced.

  The Date Picker custom field type is an editable field

Remember that in Jira the Date Picker custom field type is an editable field which means that users can modify the date when creating or editing an issue. This can be problematic as any user can change the date which will sync with the Accepted Date in Jira Align. The solution for this is to create a new view screen with the new Date Picker custom field and associating it to the View operation for the story and epic (feature) Screen scheme (See steps 4-7). The Date Picker custom field must not be added to the screen(s) associated with the Create Issue and Edit Issue operations in the Screen scheme.

  Jira issues synced with Jira Align stories as custom issue types must also use the Date Picker custom field

If Jira issues such as Bugs or custom issues are mapped to sync with the Jira Align story work item (For reference see article on Jira and Jira Align Integration: Configure Custom Issue Type Mapping and Stories of Type Defect), the View issue screen for these issue must have the Date Picker custom field and the issue workflow must also have the Post Functions added to the status transitions for populating and clearing the Date Picker custom field.

[M Amine]

Good information