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.

    At the end of the synchronization process, the Synchronizer removes the "dummy" entities if the Jira user 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. In this case, there are two options for mapping:

  • Map the ALM Octane Sprint field <-> Jira Sprint field. In this case the mapping will be by ID, with a fall-back to name mapping if necessary. When a defect or user story is assigned to a sprint, ALM Octane forces the entity to also be assigned to the matching release.

  • Map an ALM Octane user defined field called Sprint (of type List) <-> Jira Sprint field. In this case the sprint in ALM Octane will not be a real sprint but only an attribute. The mapping will be by name so make sure the names on both sides match.

Tip: If the sprint assignments are originally set in Jira, start with setting the mapping direction from Jira to ALM Octane only. You can later switch to bi-directional mapping if relevant to your use case.

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.

What happens when you move defects from one Jira project to another?

If you have multiple Jira projects mapped to one ALM Octane workspace using multiple links, when you move a defect from one Jira project to another this move is synchronized in ALM Octane. For example, 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.

Note that synchronization of Move events is currently supported for defects only.

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 commit message patterns.

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


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

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.

  • If a defect is associated with an epic or story, synchronization does not carry over this association.

  • Attachments are not carried over during synchronization. Instead, a link to the attachment is created, enabling you to access the attachment when needed.

  • 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.

  • Versions associated with defects in Jira are mapped to releases in ALM Octane. However, in ALM Octane releases are single value lists (unlike releases in Jira), so that if you have multiple versions in a defect in Jira, ALM Octane only takes the first value in the list.

  • 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.

  • If you delete a release in Jira or ALM Octane after they have been synchronized, and then run a manual sync, 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.

Back to top

See also: