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.


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


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

    • 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 Install SSL certificates.
    • 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 Jira SAFe Epic to Feature Translator Plugin.
  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. We will not change this default setting. This effects both creation and updates of entities and types. We will instead modify direction at the type and field level.

  2. In our use-case we create stories in Jira and push them to ALM Octane, so 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 we see mapping between the fields, which impacts the direction of updates between the data sources. Although we are pushing stories from Jira to ALM Octane, we want to allow users in ALM Octane to update these fields and push updates to Jira, so we edit 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 sync a link to an item, before you sync the item itself. We therefore will come back here after we 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. In our use-case we will also sync bugs with defects, but not tasks with sub-tasks, so we click the delete button for the task and sub-task types (and their values).

  6. Bugs and defects can originate in either system, so we leave them as bi-drectional. We 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 we 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. We 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 like Phase.

  9. For our use case, we will also add releases and sprints using the above steps. We 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, this means that all the types we are synchronizing will apply to the same two projects. In our 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 our use-case we will map common projects for simplicity.

  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 we sync to make sure everything is set up properly. We recommend that you first sync standalone types: stories, bugs, and epics; then sync sprints and releases, which have dependencies. This makes it easier to debug any problems that may appear.

  1. On the Connections tab, we now see our 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 we've synced epics, features, sprints, and releases, we 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. Once the synchronization is set up properly, choose Start Connection to run sync 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