Use-case: Syncing ALM and Azure DevOps

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

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, the Quality team will work in ALM/QC, and the Development team will be working in Azure DevOps with a Scrum workflow project. We will create epics, features, and product backlog items in Azure DevOps and sync those to the requirements view of ALM/QC. We will configure Micro Focus Connect to originate in either endpoint system.

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 Azure DevOps and ALM.

Back to top

Prerequisites

This use-case requires the following:

  • Azure DevOps Scrum Workf low Project called AOS Scrum. Note that the default Basic process type does not contain the relationships required for synchronization.

  • Azure DevOps account email address, and a related API token with full read/write access to the Azure DevOps instance and project. This token is required for Cloud Azure DevOps instance access only.

  • ALM/QC account (non-SSO) with full read/write access to the ALM/QC domain and projects.

  • ALM/QC project called AOS.

Back to top

Step 1: Define the ALM/QC data source

In Micro Focus Connect, you first define an ALM/QC data source and an Azure DevOps 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, Azure DevOps and Micro Focus ALM).

    Note: Be careful to use names that reasonably describe your connection. Avoid using blank spaces or special characters in names. If needed, data source and connection names can be changed using the Rename script. For details, see Batch utility scripts.

  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 correct 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. 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 Azure DevOps data source

You now repeat the above steps to define the Azure DevOps data source.

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

  2. Type the Azure DevOps server URL, such as https://dev.azure.com/<nameofyourorganization>. Enter your user name. In the password field, enter your Personal Access Token. Click Next.

  3. From the Sample Project dropdown list, select your project and click Save.

    Note: If you have multiple projects in Azure DevOps that you intend to sync, and all these projects have the same workflows, you can use a common data source and a single connection (or connections) stemming from that data source.

    However, if you have multiple projects with different workflows, such that the entity types and relationships are different, you must describe each such project on a different data source and corresponding connections.

    This is true of the majority of products that are synchronized using Micro Focus Connect, including ALM/QC.

  4. 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 Azure DevOps 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. We will call the connection Nimbus ALM Azure DevOps.

  3. Leave the 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.

  1. Click Add Type Mapping.

  2. Select Product Backlog Item on the left and Requirement on the ALM/QC side. Change the direction of the type mapping to be To Master. This means product backlog items will originate in Azure DevOps and sync to ALM/QC.

  3. Add additional fields to sync for these types by clicking + Field Mapping, as shown in the next image. When done, click OK.

  4. After adding the four fields, click the small blue icon to the right of the Priority field mapping. This is where you map the priority value options between the two systems. In this example, Azure DevOps has four values and ALM/QC has five. Therefore, we will map priority number 4 in Azure DevOps to both Very High and High in ALM/QC.

    Note: The bolded font on 5-Very High indicates which will value be set on the ALM side when syncing the priority from Azure DevOps. You will follow this same process for any enumerated list value fields that you sync.

  5. Add another type to map, and this time choose Feature on the left and Requirement on the right. Ensure the arrow at the type level is again set to To Master.

    Note: Type level direction indicates which system the items can originate from. Field level direction indicates which system the fields can be updated from. For this example, we will set the type and field level directions to match, but it is common to have type level direction to be unidirectional and some fields to be bidirectional.

    Parent -> parent-id is an example of mapping relationships. In this example, Parent is a relationship field on Azure DevOps features that we are using to create the hierarchy in the ALM/QC requirement tree. If you leave out this field mapping, then epics, features, and product backlog items will sync into the ALM/QC tree as a flat list.

  6. Add type mapping from Epic on the left to Requirement on the right. Ensure the arrow at the type level is again set to To Master.

  7. Add type mapping from Bug to Defect. For this type, set the type level direction to bidirectional, as well as the fields for updates.

  8. Set the value maps for the Severity, Priority, and Status fields, as follows.

    Click the blue icon to the right of the Severity field mapping, set these value maps and click OK.

  9. Click the icon to the right of the Priority field mapping, set these value maps and click OK.

  10. Click the icon to the right of the State/Status field mapping, set these value maps and click OK.

Back to top

Step 5: Create Connection Wizard > Projects and Rules tab

In the Projects and Rules tab, define which projects to sync.

  1. Click Collapse All at the top right. Under Common Projects, click + Project Mapping. Select AOS Scrum under Azure DevOps Project on the left, and select AOS under Micro Focus ALM Project on the right.

  2. Collapse Common Projects at the top, and expand the Product Backlog Item/Requirement type set.

    Note: If you are syncing multiple projects in a connection, you need to decide whether using Common Projects is sufficient. In most cases, it is not.

    If you map many Azure projects to a single ALM/QC project in a given connection, or vice versa, you need to set sync criteria for the specific mapped types that fan the artifacts out to the individual projects. You cannot and should not use Common Projects in this situation. The entire Common Projects block must be empty.

    You need to create separate sync sets joining the types and projects being synchronized with the relevant sync criteria guiding the artifacts picked for each such sync set. It is very rare that you would use Common Projects to contain multiple projects, spanning multiple type sync sets.

  3. Click the pencil icon under the Product Backlog Item/Requirement type to edit calculated values. Here we tell Micro Focus Connect to set the requirement type when new items are created in ALM from Azure DevOps.

  4. Select the Calculated Value (Master) tab, then click + Calculated Value.

  5. Click the Add Child Criteria button on the far right.

  6. Select Is New from the operator list and click OK.

    This tells Micro Focus Connect to calculate and set this value when the requirement is newly created in ALM/QC.

  7. In the Set field list, choose Requirement Type. In the To value list, select the requirement type that you want product backlog items to become when they are created in ALM/QC. Click OK.

    Note that any type you select will promptly change to an integer. This is how ALM/QC recognizes these types in the database.

  8. Repeat this process for Feature/Requirement sync, but choose a different requirement type.

    For this use case we choose requirement types that do not have additional required fields.

  9. Repeat again for Epic/Requirement and choose another requirement type.

  10. Save the connection.

  11. Go to Azure DevOps and ensure you have at least one epic, one feature, and one product backlog item. In ALM/QC, create at least one defect.

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.

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

  2. As the iteration runs, click the Connection Messages tab on the bottom of the screen, and click your connection name at the top to set focus. This shows you the status of your iteration.

  3. In the Audit tab of the lower pane, click Run to run an audit. This generates an audit of items that were added, updated, and failed. In the example below, you can see that several requirements were updated that had already synched.

    Below is the result in ALM/QC. The hierarchy is built to match the parent-child relationships you have in Azure DevOps.

Note: Running a single iteration does not necessarily sync everything completely. Micro Focus Connect might need multiple iterations to align everything (for example links, relationships, and some hierarchies).

Similarly, running a single iteration three times is not as effective as starting the connection and letting it run for three iterations before stopping it again. Micro Focus Connect employs caching mechanisms for links and relationships, so the first iteration might provide pre-requisites for later iterations (which is not possible with Run One Iteration).

Back to top

Step 7: Map relationship links

After everything has synched as expected, edit your connection to add more types and fields.

  1. Add a new type mapping for Azure DevOps iterations with ALM/QC release cycles. For this example, set the direction to From Master with the following fields.

  2. Edit the bug-defect mapping. Choose + Field Mapping, and add Iteration Path <-> target-rcyc if not already mapped. Click OK.

    When Azure DevOps or ALM/QC users set an iteration or target release cycle in one system, the bug or defect will be updated on the related bug or defect in the other system.

  3. Choose + Field Mapping and add Iteration Path -> target-rcyc. Click OK and save changes.

    When Azure DevOps users set a planned iteration on a product backlog item, that information will show on the related requirement in ALM as the target release cycle.

  4. In ALM/QC, create a single release called Azure DevOps Iterations. Create 3 release cycles inside it called ALM Iteration 1, ALM Iteration 2, and ALM Iteration 3.

    These will sync to Azure DevOps as available iterations, and Azure DevOps users will set the target iterations on product backlog items and bugs to indicate in which iteration or release cycle they will be delivered.

    Note: Although it is possible to sync iterations from Azure DevOps to ALM/QC, this will not be covered in our example.

  5. For this example, we will tell Micro Focus Connect to look in our default release for cycles.

    To set the default release, open the Data Source tab in Micro Focus Connect. Select the ALM data source on the left side. On the right side Properties tab, select your new ALM release from the Cycle Parent dropdown menu.

    Save the change at the top of the Properties tab.

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. In Azure DevOps, confirm that ALM Iterations 1-3 are visible in the Iteration field.

  3. When available, open a product backlog item in Azure DevOps, and set the Iteration field to one of the iterations that just came from ALM/QC as shown above.

  4. Run one iteration. In ALM/QC, refresh your requirements view and confirm that your product backlog item has a target release and target iteration now set.

Back to top