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 edit the file jira\conf\ which defines which issue types are synchronized.

    1. Uncomment the entry issuetypes.requirement and specify which issue types you want to synchronize, using commas but no blank spaces. For example:
      issuetypes.requirement = Feature,TestIssue,Story

      Note that Story is mandatory.

    2. After saving your changes to the file, stop the Integration Bridge service and then start it again using Stop and Start.

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

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

Mapping 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

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: