Use-case: Syncing ALM Octane and Jira

The following use-case provides an example of how to set up a connection between ALM Octane and Jira.

Overview

This topic illustrates the end-to-end flow of setting up synchronization. Although your exact environment may require different configuration steps, we recommend that you review this use-case to get an idea of what the end-to-end workflow involves.

In this example, our development is managed in Jira, and our QA is managed in ALM Octane. This means that stories are created in Jira and synced to ALM Octane. QA tracks their testing in ALM Octane and pushes their results to Jira.

Caution: We do not recommend testing this procedure in a production environment. To learn the Micro Focus Connect workflow you can use a demo environment with demo data on both Jira and ALM Octane.

Back to top

Prerequisites

  • On the ALM Octane side, you need to create an API key that has both workspace admin and space admin roles in the workspace you are synchronizing.

  • On the Jira side you need to have a project, and a board that includes everything in that project. This is required because Micro Focus Connect reads Jira content from the board.

  • You need to have installed the Jira connector, which is not downloaded as part of the default Micro Focus Connect package. The Jira connector can be downloaded from the Connectors Marketplace.

Back to top

Step 1: Define the ALM Octane data source

In Micro Focus Connect, you first define an ALM Octane data source and a Jira data source. After defining each data source, Micro Focus Connect collects sample data from each source regarding their types, fields, and values.

  1. In the Data Sources area, click the + Data Source button, and specify a data source name and product (for example, Octane 1 and ALM Octane).

    Note: Data sources and connections cannot be renamed, so be careful to use names that will be useful over time.

  2. Type the ALM Octane server URL defined as http://<server>:<port>. Enter the client ID and secret from the API key you created earlier, and click Next.

  3. Select a space, and click Next.

  4. Select a workspace that has types, fields, and values similar to the data that you want to sync, and click Next.

    (After setting up the connection you can synchronize with multiple workspaces in the selected space.)

  5. Select a default release for sprints.

    This is needed because in Jira sprints can be unrelated to releases, while ALM Octane always links sprints with releases. Micro Focus Connect will assign any unrelated sprints from Jira to this default release in ALM Octane.

  6. Click Save. Micro Focus Connect verifies that the values you have entered are valid.

    On the Types tab, you can see the entities that Micro Focus Connect identified in the ALM Octane workspace as available for synchronization. On the Relationships tab, you can see the available relationships.

Back to top

Step 2: Define the Jira data source

You now repeat the above steps to define the Jira data source.

  1. Click the + Data Source button, and specify the Jira data source name and product (for example, Jira 1 and Jira).

  2. Type the Jira server URL defined as http://<server>:<port>, and enter a user and password that has full read/write privileges for the Jira instance. (For Jira Cloud, enter a user and token.) Click Next.

      Note:
    • If you receive a message indicating a problem with certificates, import your Jira certificate to the Micro Focus Connect web server to enable Micro Focus Connect to access Jira. For details, see Configure Micro Focus Connect for SSL/TLS.
    • The Jira user account must use English UI settings (en-us or en-uk). In addition, if you are using the SAFe add-on for Jira, review locale information in Translate Jira epics to features .
  3. Select a project that has types, fields, and values similar to the data that you want to sync. Click Next.

  4. Select a board for the project.

    Tip: We recommend that you create a dedicated board for Micro Focus Connect showing everything in the project, rather than use an existing user board where you might change filters and block visibility to Micro Focus Connect.

    Optional: In the Types field you can filter which types you want to sync for performance purposes. Click Next.

  5. We recommend that you leave the remaining fields as set by default, and click Save. Micro Focus Connect verifies that the values you entered are valid.

    On the Types tab, you can see the entities Micro Focus Connect identified in the Jira project that are available for synchronization. If you have custom types that you want to add, click + Types and select the type you want to add.

    On the Relationships tab, you can see the available relationships.

Back to top

Step 3: Create Connection Wizard > Data Sources tab

You now create a connection between the two data sources using the Create Connection Wizard. First you specify the data sources:

  1. In the Connections window, click the + Connection button.

  2. In the Data Source tab, name your connection (for example, Octane and Jira Backlog Sync).

  3. Select ALM Octane as the master and Jira as the target data source. Leave the remaining settings as set by default, and click Next.

Back to top

Step 4: Create Connection Wizard > Types and Fields tab

Micro Focus Connect creates an initial auto-mapping of fields, which you will now enhance in the Types and Fields tab.

Map between types and fields on both ends:

  1. In the upper right, the Default Sync Direction is set to bi-directional. Do not change this default setting. This affects both creation and updates of entities and types. Instead this use-case will modify the direction at the type and field level.

  2. This use-case creates stories in Jira and pushes them to ALM Octane. Set the story direction as Jira -> ALM Octane.

    Click the pencil next to the Story type to edit its settings, and set the type's Direction as -> To Master. The direction set on the type is used for the creation of items, so when a story is created in Jira, it is pushed to ALM Octane (but not from ALM Octane to Jira).

  3. In the lower pane you can see mapping between the fields, which impacts the direction of updates between the data sources. Although you are pushing stories from Jira to ALM Octane, you want to allow users in ALM Octane to update these fields and push updates to Jira, so you modify these fields to be bi-directional.

    Note: You can click + Field Mapping to add other fields such as points, priority, and so on.

    However, you cannot synchronize a link to an item, before you sync the item itself. Therefore you will return to this section after you synchronize between the basic fields, and add link fields such as Epic link.

    If you are not sure if a field is a link field, you can look at the Data Source > Relationships tab. If you see a field listed there, it is a link field, and you need to first sync the items before you can sync their links.

  4. List fields typically need to be mapped. For example, statuses in Jira need to mapped with phases in ALM Octane because they are not automatically aligned with one another.

    Click the Value Mapping button to the right of the Status and Phase row, and map each unmapped value.

    For example, if In Testing in ALM Octane is not mapped to a value in Jira, click Select a Value in the Jira column and choose the value In Progress.

  5. This use-case also synchronizes bugs with defects, but not tasks with sub-tasks. Therefore, you click Delete for the task and sub-task types (and their values).

  6. Bugs and defects can originate in either system, so you can leave them as bi-drectional. Map the values from ALM Octane defects to Jira bugs as follows:

    If a field is required in one of the sides, it will be highlighted in red. Make sure to map any required fields that are not automatically populated.

    Similar to the value maps you set for stories, you also need to set value maps for fields like Phase and Severity on Defects.

  7. For this use case you want to add the Feature type, which exists in ALM Octane but not in Jira.

    Click + Type Mapping, and select Epic on the Jira side, and Feature on the ALM Octane side. Set the direction from Jira -> ALM Octane (similar to stories).

  8. Click Auto Field Mapping to populate the field mapping quickly, then modify or add fields as described above.

    Remember to also add value maps for fields such as Phase.

  9. This use-case also adds releases and sprints using the above steps. Add each type, and map them as uni-directional from ALM Octane to Jira. (None of their fields need to be value-mapped.)

    Alternatively, you can manually enter the sprint and release names in Jira and ALM Octane, and schedule runs of the matchByNameJiraOctane script to populate the cross references in the Micro Focus Connect database. For details, see MatchByName scripts.

  10. Click Next.

Back to top

Step 5: Create Connection Wizard > Projects and Rules tab

In the Projects and Rules tab, you define which projects to sync. You can use the projects that you entered as the sample projects, or other projects.

  • If you map projects under the Common Projects heading, then all the types being synchronized will apply to the same two projects. In this use-case, stories, bugs, epics, releases, and sprints will all be synchronized in the two sample projects.

  • You could specify one project for stories and another for defects, or use different rules for different types (for example, only sync defects with a certain severity or priority). However, for simplicity, this use-case will map common projects.

  1. At the very top under Common Projects, select the projects you want to connect. Do not set any projects under the individual types for this use case.

  2. Click Save.

Back to top

Step 6: Run one sync iteration in the Connections tab

At this stage, you synchronize to make sure everything is set up properly. We recommend that you first synchronize standalone types: stories, bugs, and epics. Then you can synchronize sprints and releases, which have dependencies. This makes it easier to debug any issues that may arise.

  1. On the Connections tab, you can see the new connection.

    Click the gear icon to the left of the connection name, and choose Run One Iteration.

    This runs one sync iteration, to test that it works properly.

    Note: Running one iteration does not sync everything completely, especially if the sync was never run before (e.g. links between items, items that are in certain parent/child relationships, etc.).

  2. Click the connection row. In the lower pane, open Connection Messages to track progress and look for errors. When the Status shows Disabled, the iteration is done.

  3. In the Audit tab of the lower pane, click Run to run an audit. This gives you an idea of which types synced, and if there were any errors.

    We recommend now looking at Jira and ALM Octane to verify that the expected items synced between them.

Back to top

Step 7: Map relationship links

Now that you have synchronized epics, features, sprints, and releases, you can add their relevant relationship links.

  1. In the Connections tab, edit the new connection.

  2. In the Types and Fields tab, edit the Story type.

  3. Add the following link mappings from Jira to ALM Octane:

    • Epic link > Feature

    • link.fixVersions > Release

    • Sprint > Sprint

    These enable you to sync links between stories and their related features, releases, and sprints.

Back to top

Step 8: Run synchronization

  1. On the Connections tab, click the gear icon to the left of the connection name, and choose Run One Iteration to test the latest changes.

  2. After the synchronization has been set up properly, choose Start Connection to run the synchronization continuously at the frequency defined for the connection.

Tip: Every iteration, Micro Focus Connect sets a watermark so that it only looks for changes since the last iteration. If you run sync and do not see expected changes, this may be because you changed mappings since the last iteration, but the change is not registering because of an existing watermark. In this case, choose Clear Watermarks from the Connection gear icon before running sync.

Back to top

Synchronizing Jira tasks and sub-tasks

This section describes how to synchronize between Jira and ALM Octane tasks and sub-tasks. This is only an example and is not guaranteed to work for all data sets or scenarios.

Before using Micro Focus Connect to synchronize your applications, make sure you are familiar with the data structures of both endpoint systems, and the differences in systems' behaviors. Also note any customizations performed on each of the systems. For details, see Before you begin.

Micro Focus Connect uses the following to address differences between two systems that need to be synchronized:

  • Sync Criteria

  • Calculated values

  • Server-side filters

In this ALM Octane Jira bi-directional scenario, the following differences exist:

Endpoint  
ALM/Octane
  • Has the Tasks type, but not a Sub-Task type

  • Tasks must be associated with a Story or Defect

Jira

  • Tasks do not have to be associated with any type

  • Tasks are related to Stories and Bugs

  • Sub-Tasks are children of Bugs and Stories. They cannot exist without a parent item

  • Custom types based on a standard type are supported, for example custom sub-tasks

Basic mappings

Firstly, make sure the type mapping is correct. You must map all available list values of any mapped enumeration fields. In this example, this is the Status / Phase fields and the enum mapping is accessible via the blue symbol in the screen shot. If the enum mapping is detected as being incorrect, the symbol will turn red.

Project mapping

Since you are mapping multiple types, the Common Projects area should not be used. Each type must have its own, type-specific project mapping. For details, see Add projects and rules to a connection.

Application configuration

This section describes the mapping of a type from one endpoint, to multiple types on another endpoint, through a single configuration. The mapping is from an ALM Octane Task to a Jira Task and Sub-task. Since an ALM Octane Task can be associated with a Jira Task or Sub-Task, you must differentiate between the two types within ALM Octane to ensure that the correct data is synchronized with the appropriate Jira type.

This can be achieved by creating a custom UDF (user-defined field) for the Task type in ALM Octane. In this case, a List UDF and a rule were created to set the default value to Task. This can be changed by a user in ALM Octane to then synchronize with a Sub-task in Jira. The field should not be changed after Micro Focus Connect has already synchronized the item with Jira. It should only be editable by an ALM Octane user when creating a new Task item.

Sync criteria and calculated values

Follow these steps to prepare for the synchronization and specify synchronization criteria and calculated values:

  1. In the Edit Connection Type Rule box for the Jira (Target Sub-Task) <--> ALM Octane (Master Task) , open the Sync Criteria (Master) tab.

    Set the rule to only include ALM Octane tasks that have the JIRA_TASK_TYPE UDF set to Sub-Task.

  2. In the Edit Connection Type Rule box for the Jira (Target Sub-Task) <--> ALM Octane (Master Task) , open the Calculated Value (Master) tab,

    Set the JIRA_TASK_TYPE UDF to Sub-Task when creating a Task in ALM Octane.

  3. In the Edit Connection Type Rule box for the Jira (Target Task) <--> ALM Octane (Master Task) , open the Sync Criteria (Target) tab.

    Create a Sync Criteria (Target) to restrict Jira sub-tasks that are associated with Stories and Bugs. This criteria will exclude custom types.

  4. In the Edit Connection Type Rule box for the Jira (Target Sub-Task) <--> ALM Octane (Master Task) , open the Sync Criteria (Master) tab.

    Set the JIRA_TASK_TYPE UDF to Task when creating a Task in ALM Octane.

  5. In the Edit Connection Type Rule box for the Jira (Target Sub-Task) <--> ALM Octane (Master Task) , open the Calculated Value (Target) tab.

    Set the JIRA_TASK_TYPE UDF to Task when creating a Task in ALM Octane.

  6. In the Edit Connection Type Rule box for the Jira (Target Sub-Task) <--> ALM Octane (Master Task) , open the Sync Criteria (Target) tab.

    When a task is created in Jira, make sure the relationship type is set to blocks, the default.

    As a result, the sync criteria will only synchronize tasks that are set to relinward.is.blocked.by.

Synchronization results

The screen below shows the result of the synchronization described above, showing the mappings of Jira on the left, and ALM Octane on the right.

Back to top

Synchronizing the Jira Teams field

This section shows a sample synchronization between the Jira and ALM Octane Teams fields using a custom mechanism, not involving the manipulating of value maps. This is only an example and is not guaranteed to work for all data sets.

To set up the synchronization:

  1. Run the mfcQueryTemplates.bat script to determine the Custom Field ID of the Teams field in Jira. Examine the JSON data returned by the utility. For details, see QueryTemplates. The script will generate files based on the data source, type, and property set. For example:

    Utility settings Generated file name File contents

    set DATA_SOURCE=JIRA

    JIRA.txt

    Syncable types for the data source

    set TYPE=Story

    JIRA.Story.txt

    Syncable fields for the data source

    set PROPERTY=Team

    JIRA.Story.Team.txt

    Field's return values

    The following is a sample of the contents of a JIRA.Story.txt file:

    Example: Field name:Team details:{"SyncableField":{"fieldName":"Team","fieldLabel":"Team","fieldType":"FIELD_TYPE_ENUM","fieldUnits":"UNITS_NONE","fieldRequired":"NOT_SURE","isReadOnly":false,"isMultiValued":false,"isParentField":false,"isHtml":false,"isUserField":false,"uniqueField":false,"isLinkField":false,"referredToLinks":[],"connectorFieldInfo":"fieldId=10107"}}

    From the text generated in the file, we can see that the field ID of the Team custom field ID in Jira is 10107. The value to use in the script will be: customfield_10107.

  2. Create a property bag file jiraoctanecustomsync.property.bag.txt in the UserMaps folder in the Micro Focus Connect installation with the values retrieved in step 1. Make sure to set the ALM Octane Team value to team.

    customfield_10107=team

    There is a switch in ALM Octane to create teams based on the teams list in Jira. By default, this option is set to true, indicating that all teams in JIRA will be created in ALM Octane. Set it to false to enable the customization.

    createoctaneteams=false

  3. Locate the mfcJiraOctaneCustomSync.bat script in the utility folder under the Micro Focus Connect installation. Run the script as an administrator.

Back to top

See also: