Use-case: Syncing ALM and Jira

The following use-case provides an example of how to set up a connection between ALM 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/QC. This means that stories are created in Jira and synced to ALM/QC. QA tracks their testing in ALM/QC 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/QC.

Back to top

Prerequisites

  • On the ALM/QC side, you need a user with full read/write access for the domains and projects you will be 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/QC data source

In Micro Focus Connect, you first define an ALM/QC 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, Jira and Microfocus ALM).

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

  2. Type the ALM/QC server name, username, and password. Confirm the port as well, and click Next.

  3. Select a space, and click Next.

  4. Select the proper domain, and click Next.

  5. Select a project 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 projects in the selected space.)

  6. Select a default cycle parent and requirement parent from the dropdown menus.

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

  7. 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/QC project 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 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, ALM and Jira Backlog Sync).

  3. Select ALM/QC 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 requirements in ALM/QC. Click + Type Mapping, and select Story on the Jira side, and Requirement on the ALM/QC side. We set the direction from Jira -> ALM/QC.

  3. Click + Type Mapping, and select Epic on the Jira side, and Requirement on the ALM/QC side. We set the direction from Jira -> ALM/QC (similar to stories).

  4. Click the pencil next to the Story/Requirement 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/QC (but not from ALM/QC to Jira).

  5. Click + Field Mapping to add the fields below. The direction of mapping between the fields impacts the direction of updates between the data sources.

    • Although we are pushing stories from Jira to ALM/QC, we want to allow users in ALM/QC to update these fields and push updates to Jira, so we edit these fields to be bi-directional.

    • The only exception is the Epic Link field, which is uni-directional to the ALM/QC parent-id field. This is a relationship field, that indicates which Epic/Requirement in ALM/QC will be a parent of any given Story/Requirement.

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

    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.

  6. List fields typically need to be mapped. For example, priority in Jira needs to mapped with priority in ALM/QC because they are not automatically aligned with one another.

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

    For example, if 5-Urgent in ALM/QC is not mapped to a value in Jira, click Select a Value in the Jira column and choose the value Highest.

  7. In this use case we want to also sync epics from Jira as requirements in ALM/QC. Click + Type Mapping, and select Epic on the Jira side, and Requirement on the ALM/QC side.

    We set the direction from Jira -> ALM/QC (similar to stories). For now just map these fields to sync between epics and requirements..

  8. In our use case we will sync bugs and defects, and they can originate in either system so we leave them as bi-directional. We map the values from ALM/QC 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 Priority and Status on Defects.

  9. For our use case, we will also add releases and sprints/release cycles using the above steps. We add each type, and map them as uni-directional from ALM/QC to Jira. (None of their fields need to be value-mapped.)

    Alternatively, you can manually enter the sprint/cycle and release names in Jira and ALM, and schedule runs of the matchByNameJiraAlmQc 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/requirements, bugs, epics/requirements, releases and sprints/release cycles 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. When expanded, each individual type set should only show Common Projects.

  2. Click Save.

  3. For our use case, we would like the requirements in ALM/QC to have a specific requirement type be set automatically, based on whether it is an epic or a story in Jira. If you have custom requirement types defined for these, you can assign them accordingly. For this example, we will use default requirement types in ALM.

  4. In this view, expand Story/Requirement type. Click the pencil button to the far right of the Common Projects labels.

  5. Click on the tab to the right labeled Calculated Value (Master), then click + Calculated Value below.

  6. We will use calculated values to automatically set the ALM/QC requirement type on creation, since there is no similar field in Jira from which to synchronize.

    In the Add Calculated Value window (shown below), in the When criteria section, click the Add Child Criteria icon on the far right. From the drop down menu, choose Is New and Click OK.

  7. Choose the Set Field to be Requirement Type.

  8. In the To Value field, select Functional for this example.

    When a story is created from Jira as a requirement in ALM/QC, it will be set as a Functional requirement.

    Note: After you select Functional you will see an integer appear in its place. This is normal because ALM/QC stores these types as integers.

  9. Click OK.

  10. Repeat the above steps for Epic/Requirement as shown in the image below.

    For epics, set the requirement type to Folder.

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, epics, and bugs; 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/QC to verify that the expected items synced between them.

Back to top

Step 7: Map relationship links

Now that we've synced epics, stories, 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/QC:

    • link.fixVersions > target-rel

    • Sprint > target-rcycl

    These enable you to sync links between stories and their related 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