Use-case: Syncing ALM/QC and Jira

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

ALM/QC to Jira workflow

This section provides an 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 Connect workflow you can use a demo environment with demo data on both Jira and ALM/QC.

Prerequisites

On the ALM/QC side, you need a user with full read/write access for the domains and projects being synchronized.
On the Jira side you need to have a project, and a board that includes everything in that project. This is required because Connect reads Jira content from the board.
You need to have installed the Jira connector, which is not downloaded as part of the default installation package. The Jira connector can be downloaded from the Connectors Marketplace.

Step 1: Define the ALM/QC data source

You first define an ALM/QC data source and a Jira data source.After each data source is defined, sample data is collected from each data source regarding their types, fields, and values.

In the Data Sources tab, click the + Data Source button, and specify a data source name and product (for example, Jira).

Note: Data sources and connections cannot be renamed, so choose names that will be useful over time.
Type the ALM/QC server name, username, and password. Confirm the port as well, and click Next.
Select a space, and click Next.
Select the proper domain, and click Next.
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.
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. Connect assigns any unrelated sprints from Jira to this default release in ALM/QC.
Click Save. A system check verifies that the values you have entered are valid.

On the Types tab, you can see the entities that Connect identified in the ALM/QC project as available for synchronization. On the Relationships tab, you can see the available relationships.

Step 2: Define the Jira data source

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

Click the + Data Source button, and specify the Jira data source name and product (for example, Jira 1 and Jira).
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 Connect web server to enable Connect to access Jira. For details, see SSL/TLS configuration.
- 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 plugin.
Select a project that has types, fields, and values similar to the data that you want to sync. Click Next.
Select a board for the project.

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

Optional: In the Types field you can filter which types you want to sync for performance purposes. Click Next.
We recommend that you leave the remaining fields as set by default, and click Save. A system check verifies that the values you have entered are valid.

On the Types tab, you can see the entities 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.

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:

In the Connections tab, click the + Connection button.
In the Data Source tab, name your connection (for example, ALM and Jira Backlog Sync).
Select ALM/QC as the master and Jira as the target data source. Leave the remaining settings as set by default, and click Next.

Step 4: Create Connection Wizard > Types and Fields tab

The wizard creates an initial auto-mapping of fields. You enhance the mappings in the Types and Fields tab.

Map between types and fields on both ends:

In the upper right, the Default Sync Direction is set to bi-directional. Keep this default setting. This effects both creation and updates of entities and types. Instead, you modify the direction in the type and field levels.
Our use-case creates stories in Jira and pushes them to requirements in ALM/QC. Click + Type Mapping and select Story on the Jira side, and Requirement on the ALM/QC side. Set the direction from Jira to ALM/QC.
Click + Type Mapping. Select Epic on the Jira side and Requirement on the ALM/QC side. Set the direction from Jira to ALM/QC (similar to stories).
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).
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 this use-case pushes stories from Jira to ALM/QC, you want to allow users in ALM/QC to update these fields and push updates to Jira, so you 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. Therefore, you will return to this screen after you synchronize 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.
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.
This use-case 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.

Set the direction from Jira -> ALM/QC (similar to stories). For now, just map these fields to sync between epics and requirements..
Our use-case syncs bugs and defects. They can originate in either system, so you can leave them as bi-directional. Map the values from ALM/QC defects to Jira bugs as follows:

If a field is required in one of the sides, it is 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.
Our use-case also adds releases and sprints/release cycles using the above steps. You 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/QC, and schedule runs of the matchByNameJiraAlmQc script to populate the cross references in the database. For details, see Batch utility scripts.
Click Next.

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 our use-case, stories/requirements, bugs, epics/requirements, releases, and sprints/release cycles will all be synchronized in the 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, our use-case maps common projects.

At the top section 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.
Click Save.
Our use-case is for the requirements in ALM/QC to automatically set a specific requirement type, based on whether it is a Jira epic or a story. If you have custom requirement types defined for these, you can assign them accordingly. For this example, you will use default requirement types in ALM.
In this view, expand Story/Requirement type. Click the pencil-shaped button to the far right of the Common Projects labels.
Click on the tab to the right labeled Calculated Value (Master), then click + Calculated Value below.
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.
Choose the Set Field to be Requirement Type.
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, an integer appears in its place. This is the correct behavior, as ALM/QC stores these types as integers.
Click OK.
Repeat the above steps for Epic/Requirement as shown in the image below.

For epics, set the requirement type to Folder.

Step 6: Run one sync iteration in the Connections tab

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

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, such as links between items or items that are in certain parent/child relationships.
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.
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.

Step 7: Map relationship links

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

In the Connections tab, edit the new connection.
In the Types and Fields tab, edit the Story type.
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.

Step 8: Run synchronization

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.
After the synchronization has been set up properly, choose Start Connection to run the synchronization continuously at the frequency defined for the connection.

Tip: For every iteration, a watermark is set so that the synchronization 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's gear icon before running sync.