Prepare for Jira synchronization

Before synchronizing records between ALM Octane and Jira, adapt the data in either endpoint to match the fields supported in the other endpoint, as well as synchronization requirements.

Note: The authentication to Jira REST API is done through basic authentication, based on the capabilities provided by Jira. The integration user that is used in the synchronization must have minimal permissions to perform the required operations.

Create mandatory entities in ALM Octane and Jira

  • Before synchronizing ALM Octane and Jira, you should have at least one Jira issue from each type defined in your system. For example, the default Jira issue types are epic, story, subtask, defect and task. If you are missing any one of these, create a dummy entity that you can manually delete later.

    The Synchronizer will also create dummy entities in Jira to detect all of the available transitions for each entity type. At the end of the synchronization process, the Synchronizer removes these dummy entities that it created, if the Jira user used in the Credentials Manager has permission to delete entities. Otherwise, these dummy entities will remain in the project.

    Tip: If you do not want to create a separate Jira issue for every issue type, you can specify issue types in the Synchronizer Endpoint Manager > Adapter Properties section. For details, see Step 2: Create an endpoint (Endpoint Manager).

    However, we recommend that you not change the Adapter Properties section on a link that you have already synchronized, as this may cause database corruption.

  • In ALM Octane, each release must have a start and end date, but in Jira these dates are optional. To enable synchronization, each entity in Jira must be associated with a release that has a defined start and end date. Make sure all of your Jira entities meet this requirement before synchronizing.

Back to top

Create optional entities if needed

  • In epics, the summary field is mandatory in Jira but does not exist by default in ALM Octane. If you want to map summary data from Jira, create a summary field in ALM Octane before synchronizing. (In other entities, summary is mapped by default to the name field in ALM Octane.)

    If you do not need the summary field in addition to the epic name, you can map the ALM Octane name field with one direction to the summary field in Jira.

  • Phases in ALM Octane are called Status in Jira. These values are mapped by default, but if you customized these fields in ALM Octane or Jira you will need to manually adjust the mapping accordingly.

Back to top

Synchronize sprints

Sprints in ALM Octane are always associated with a specific release, with a specific start and end date. In Jira the only definition of a sprint is a time frame, and within a time frame you can have issues that belong to different versions. In addition, Jira sprints are defined in the context of a board, and a sprint can appear in multiple boards. As a result of these differences, sprints are synchronized between ALM Octane and Jira according to the following guidelines:

Creating and updating sprints

Sprints created or updated in ALM Octane can be synchronized to Jira using the Releases link. However, sprints that are created in Jira cannot be synchronized to ALM Octane.

Sprints that are defined in ALM Octane are then synchronized to the first board defined in the mapped Jira project. These sprints are “flattened” in Jira, and do not belong to a specific release.

There is no ability to turn off sprint creation on the Releases link from ALM Octane to Jira.

Assigning sprints to defects or backlog items

If you have sprints defined in both ALM Octane and Jira, you can map them to one another using the Defects and Backlog links. Before you do that, make sure that you have created and synchronized a Release link.

In order to synchronize sprints make sure that you map the release field first in the field mapping.

Back to top

Map multiple Jira projects

When synchronizing with Jira you can map multiple Jira projects to a single ALM Octane workspace, using the Jira optional fields Project Name and Project Key.

  1. For each entity that you are synchronizing (defect, feature, and user story), create two user-defined fields in ALM Octane: Project Name and Project Key. The UDFs should be field type String. For details, see Customize fields.

  2. In Synchronizer, map these fields from Jira to ALM Octane as follows:

    • Project (Jira) > Project Name (ALM Octane)
    • Project Key (Jira) > Project Key (ALM Octane)

  3. In the ALM Octane Backlog module, create a filter for each entity using the Save filter to Synchronizer button . For details, see Create favorites.

    In the filter, define the Project Key field to match your Project Key value in Jira.

    Example: Suppose we want to synchronize features and user stories. We create a filter for features in the Backlog > Features tab:

    Then we create a filter for user stories in the Backlog > Backlog Items tab:

  4. In the Synchronizer General tab, select the link where you mapped the project name and key earlier. Click Edit link, and specify the filters that you created in the Backlog module. You can select multiple filters for a Backlog link:

  5. Run the synchronization.

The items that are synchronized from Jira to ALM Octane are populated with values for the Project Key and Project Name fields. Note that this workflow is one-directional, and is supported only from Jira to ALM Octane. Do not change the values of these fields in ALM Octane.

Back to top

Synchronize defect relations

When synchronizing defect links, you can also synchronize relations between ALM Octane defects and their related features or user stories, with the Jira links between bugs and their related entities.

  • For a relation to be synchronized successfully on the target side, the entity related to the defect must already be synchronized on the target using a backlog link synchronization.

  • Links on Jira bugs have to point to Jira issues in the same project as the bug, otherwise the links will not be synchronized.

  • For a backlog link that maps an entity type from ALM Octane to multiple entity types from Jira, only the links to the entities mapped by default will be synchronized.

To synchronize defect relations:

  1. After setting up a defect link in Synchronizer between ALM Octane and Jira, open the Rules pane. The lower left area contains Relation synchronization settings.

  2. The recommended configuration for the Jira backlog link is:

    • Feature (ALM Octane) - Epic (Jira)

    • User Story (ALM Octane) - Story / Task / Custom issue (Jira)

    with the following relation mapping in the defect link:

    • Parent feature relation (ALM Octane) - Epic link (Jira)

    • Linked user stories (ALM Octane) - “Relates” links (Jira)

  3. If you have a relation from a defect to an unmapped entity (for example a user story in ALM Octane that does not have a mapped issue in Jira), synchronization will fail.

    To prevent this, select the checkbox Ignore relations to unmapped entities.

  4. Select a dominant side (ALM Octane or Jira) to follow in case of conflicts, namely when changes on the relation fields are detected both on ALM Octane and Jira.

  5. Save changes and run sync when ready.

Limitations:

  • If you have a user story linked to a defect on the ALM Octane side, and it is synchronized in Jira, if you convert the user story or defect to a feature the relation is deleted.

  • When running full sync, the relations on the dominant side will override the ones in the other endpoint. This includes deleting the relations that do not exist on the dominant side.

  • The relations will be synchronized only if changes are detected on one of the sides (ALM Octane defects or Jira bugs). For example, if you delete a story in Jira no change is detected on a bug that is related to this story. Therefore this bug will not be updated on the ALM Octane side when synchronizing the defect link.

Back to top

Moving entities from one Jira project to another

If you have multiple Jira projects mapped to multiple ALM Octane workspace using multiple links, when you move an entity from one Jira project to another, this move is synchronized in ALM Octane. The entity will be re-created in the new ALM Octane workspace and deleted from the old one (if delete rules are enabled).

Note: In order to delete the old entity from ALM Octane, you need to have a link to the new workspace where it was moved, and synchronize that link. After that, when the old link will be synchronized again, the old entity will be deleted.

  • If you move a story that has a relation to an epic, the synchronization will fail only if the Synchronize epics and stories to the backlog root option is not checked. In this case, Synchronizer will suggest that you delete the relation, or move all related entities to the same workspace. For example, if you have a user story under an epic and you move the user story to another workspace, the synchronization will fail for the user story.

  • If you move a story that has a relation to an epic, and the Synchronize epics and stories to the backlog root option is checked, the relation is deleted from the ALM Octane side but not from the Jira side.

  • If you move an epic that has a relation to a story, the synchronization will pass regardless of whether the Synchronize epics and stories to the backlog root option is checked or not.

  • Suppose a QA tester opens a defect in ALM Octane and a developer moves this defect in Jira from one project to another, the synchronizer continues to run and the move event is reflected in the ALM Octane Project Key and Project Name fields.

    When you move an issue in Jira from project A to B, the defect is moved in ALM Octane when project B is synchronized. As a result, if you move an issue into a project that is not yet synchronized with ALM Octane, the corresponding defect will only be moved in ALM Octane when you create a link to the previously un-synchronized project.

Back to top

Use commit message patterns to relate commits from Jira to ALM Octane entities

If you manage your backlog in a third-party application such as Jira, and you manage your quality using ALM Octane, perform the following steps to enable ALM Octane to assign commits to their related entities. This enables you to analyze recently changed areas, decide where to focus your testing efforts, and track the development of a specific backlog item.

This solution requires the following:

  • You use a third-party application to manage your backlog.

  • ALM Octane is synchronized with the other application.

  • You have a user-defined field in ALM Octane with the original backlog item ID, as described below.

  • You have a pipeline configured in ALM Octane containing SCM commits made against the items in the other application.

To relate commits to ALM Octane entities:

  1. For each story type that you are synchronizing (user story, quality story, defect), create a user-defined field in ALM Octane, for example Jira_ID_UDF. The UDFs should be field type String or Long. For details, see Customize fields.

  2. During synchronization, map this UDF to the Jira ID.

  3. For each story type, add a Commit message pattern to associate the commits with their related ALM Octane entity. In the Pattern field, select the UDF that you created. This field shows the UDFs of type String or Long that exist on the entity. For details, see Customize SCM change patterns.

    This enables ALM Octane to assign each commit message that contains a Jira ID to the correct ALM Octane entity.

Example:  

I created a commit message pattern: (JRA-\d+)

  • Suppose my Jira commit message is as follows: JRA-34 #time 1w 2d 4h 30m Total work logged.

    In ALM Octane this commit will be linked to work items which have the UDF containing JRA-34.

  • Suppose my Jira commit message is as follows: JRA-123 JRA-234 JRA-345 #resolve #time 2d 5h #comment Task completed ahead of schedule.

    In ALM Octane this commit will be linked to work items which have any of the following UDF values: JRA-123 JRA-234 JRA-345.

Back to top

How Synchronizer handles converted backlog items

If you convert a backlog item from one subtype to another in ALM Octane or Jira, the conversion will be synchronized in the following cases:

  • Defect / bug > backlog item / requirement.

  • Backlog item / requirement > defect / bug.

  • Backlog item / requirement > backlog item / requirement.

Note: ALM Octane does not support synchronization of the Move and convert option in Jira.

When converting from a bug or defect to a backlog item or requirement, you must have a Requirement link and synchronize it in order for the backlog item to appear.

Synchronizer deletes the old entity and then creates a new entity with the new subtype. History is not carried over to the new entity.

To enable the deletion, you must have a delete rule enabled in Synchronizer. If the delete rule is not enabled, an error message will appear instructing you to manually delete the original entity. For details, see Edit synchronization rules.

Back to top

Synchronizing comments

  • Comment fields are synchronized from Jira to ALM Octane. However, comments which originated in ALM Octane lose their original user name in Jira, and are assigned the name of the user used by the REST API.

  • If an entity with an invalid comment is synchronized from ALM Octane to Jira, the entity will be synchronized without the comment.

Back to top

Notes and limitations

  • ALM Octane uses a hierarchy of epics > features > stories, while Jira uses epics > stories. When you synchronize, map features in ALM Octane to epics in Jira. Epics in ALM Octane will not be synchronized to Jira.

  • If you have epics in ALM Octane, when you create a Backlog link you must select the Synchronize epics and user stories to the Backlog root checkbox.

  • In Jira every release has a status, but not in ALM Octane. Release status is not synchronized.

  • The integration does not support the following two mappings together: Octane Sprint -> Jira Sprint and Octane UDF Sprint <- Jira Sprint.

  • The following fields are supported in Release synchronization: Name, Start date, End date, and Description.

  • Rich text is not supported in the release description.

  • Highlight color is removed when synchronizing from ALM Octane to Jira. If you update the description in Jira and run synchronization again, the highlight color is removed from Octane as well.

  • When synchronizing tables with merged columns, the resulting table may be slightly misaligned.

  • Custom font size and type are not supported in Jira, so the text will always have the Jira default font size and type.

  • If you delete a release in Jira or ALM Octane after they have been synchronized, and then run a manual sync, results depend on the rule “Recreate the record in based on the corresponding record in Jira.” If the rule is not selected, the manual sync does not recreate the deleted release, but rather fails with an error.

  • One-day long sprints are not synchronized from ALM Octane to Jira.

  • If you perform the following steps, sprints are not recreated from Jira to ALM Octane:

    1. Create a release in both ALM Octane and Jira.
    2. Select the rule “Recreate the record in ALM Octane based on the corresponding record in Jira.”
    3. Run Manual Sync. This creates two releases in ALM Octane and two in Jira, because the sync copies each endpoint’s record to the other endpoint.
    4. If you delete the original release in both Jira and ALM Octane, the deleted release is recreated from the other endpoint based on the rule, but sprints are not recreated from Jira to ALM Octane.
  • Filtering limitation:

    1. Create a backlog link in Synchronizer
    2. In the Backlog module, add a filter on features or user stories (for example by story points or phase).

    3. Save the filter to Synchronizer.

    4. In Synchronizer edit the backlog link, adding the filter you saved. (The filter can be chosen when the link is created, or edited.)

      The filter is applied to all entities, and not just the entities you selected in the Backlog module.

Back to top

See also: