Azure DevOps Work Item Interface for MDCMS

from Midrange Dynamics

Version 8.4

Published July 1, 2021

Azure Work Item Interface for MDCMS - Table of Contents

Overview

What is Azure DevOps?

Azure DevOps is a web-based, proprietary project and release management product, developed by Microsoft. It can be licensed to run in the cloud on Microsoft servers or licensed as a server product installed within the organization’s infrastructure. The Azure DevOps interface for MDCMS is designed to communicate seamlessly with either licensing version with a common set of administrative tools.

MDCMS interfaces with Azure DevOps for the import of Work Item data into MDCMS Projects, Tasks and Subtasks. MDCMS also interfaces with the Git repositories in Azure DevOps and with the Pipelines. This document focuses on the interface for Work Items.

Information Shared between Azure DevOps and MDCMS

The intention of the interface is to enforce the workflow rules and information flow through Azure DevOps, so that Azure DevOps is the central Project/Task management tool for the organization and the full body of information about any given work item is easily reached from MDCMS, while the data stored within MDCMS is kept to the minimum necessary for developers to perform their work and for release managers to see the objects impacted by an Azure DevOps work item.

Projects outside of Azure DevOps can still be managed within MDCMS, if MDSEC authority is provided, if some aspects of development work are outside the scope of Azure DevOps.

A work item is imported into MDCMS as a Project, Task or Subtask with several key fields automatically mapped to MDCMS fields and any other fields can be optionally mapped to MDCMS custom fields.

Additionally, MDCMS can trigger state transitions for a work item in Azure DevOps and it can add comments to work items.

Prerequisites for using the Interface

• An active MDCMS license (v8.4+) on the IBM i partition used to connect to Azure DevOps

• An active MDOpen license (v8.4+) on the IBM i partition used to connect to Azure DevOps (a developer license for MDOpen isn’t required for administrating the interface)

• An active MDWorkflow base license (v8.4+) on the IBM i partition used to connect to Azure DevOps

• An active MDWorkflow Pipeline license (v8.4+) on the IBM i partition used to connect to Azure DevOps

• The Azure DevOps URL must be reachable from the MDWorkflow partition via https

• The credentials for an Azure DevOps user(s) with admin rights to the applicable organizations/projects must be known.

• The administration of the Interface in MDOpen must be performed by a user with MDSEC authority to function code md/10 (Server Location Maintenance)

Optional Prerequisites to enable the MDCMS Webhooks for Azure DevOps:

• The MDCMS REST http server must be configured on the MDWorkflow partition (this is done from MDCMS->Setup Menu->Interface Settings->9= MDCMS REST API and Diagramming Server)

• The MDCMS REST http server on the MDWorkflow partition must be reachable from the Azure DevOps server

Configure the Interface in MDOpen

Preparation of MDOpen

1. Install MDOpen, which is the MDCMS plugin for Eclipse into an Eclipse IDE, such as Rational Developer for i or a flavor of eclipse from eclipse.org.

2. Create a repository connection in MDOpen to the IBM i partition that is designated as the MDWorkflow partition. This is typically the development partition, but may be a different one depending on firewall rules. That partition will then share the Work Item information with other partitions used by the same team, using the MDPUSH/MDPULL services.

3. Connect to the repository connection and expand the Settings section.

Pipeline Servers Settings

A Pipeline Server in MDCMS is the URL address and credential information used by MDCMS to communicate with a server over http(s) using REST APIs.

For this interface, there will be one Pipeline Server definition for each Azure DevOps Organization/Project combination that contains Work Items that should be imported into MDCMS.

Within the MDOpen Settings, click the option Pipeline Servers to manage the definitions.

Right-Click within the Pipeline Servers view and select option Add to add a new definition.

Left-Click on an existing definition to edit it. Right-Click on an existing definition for a number of other options.

Pipeline Server Parameters

Test/Troubleshoot Connection to Azure DevOps Server

Once a Pipeline Server definition has been saved, you can right-click on the entry and select option Test Connection. MDCMS will then start the MDAZUR service jobs (if not already started) and then test for the existence of the Organization and Project.

All REST communication from MDCMS to Azure DevOps is logged to the IFS with a log file per Server ID and day. Right-click on the Pipeline Server entry and select option Connection Logs to list and view the contents of the logs.

Project Mapping

For each Pipeline Server, which represents a Project in Azure DevOps, the various Work Item Types can be mapped to MDCMS Project and Task types. To manage this mapping, right-click on the Pipeline Server entry and select option Project Mapping.

This brings up a view with all defined Work Item Types for the project. If the list is empty, or if changes have been made to the types since the last pull of information into MDCMS, click the button Get Work Item Types. This may take several seconds. If it fails, review the Connection Log.

Left-Click on a work item type to edit the global mapping parameters for the work item type. Right-Click on a work item type to select the option to map individual fields and status codes.

Work Item Type Parameters

Field Mapping for a Work Item Type

For each Work Item Type in a Project in Azure DevOps, the fields defined for the type can be mapped to fields in MDCMS. To view/manage the field mappings, right-click on the Work Item Type entry and select option Field Mapping.

Some of the fields have fixed mapping MDCMS fields.

The remaining fields can be mapped to either *intref for the Internal Reference field for a task/subtask, or they can be mapped to a custom field.

To modify the mapping for a row in the view, place the cursor in the MD Field Name field and edit the value. Content-Assist can be used to select a custom field ID from a list.

Work Item State -> MDCMS Status

For each Work Item Type in a Project in Azure DevOps, the work item import can be conditioned by the state of the work item and that state can be mapped to a MDCMS Project/Task status. To view/manage the State import rules and mappings, right-click on the Work Item Type entry and select option Work Item State -> MDCMS Status.

Editable Parameters

MDCMS Status -> Work Item State

For each Work Item Type in a Project in Azure DevOps, the state of a work item can be automatically changed by MDCMS when the status of the corresponding project or task is changed.

To view/manage the State export rules and mappings, right-click on the Work Item Type entry and select option MDCMS Status -> Work Item State.

Editable Parameters

User Mapping

For each Pipeline Server, which represents a Project in Azure DevOps, the team members can be mapped to MDSEC Users. To manage this mapping, right-click on the Pipeline Server entry and select option Project User Mapping.

This brings up a view with all defined users for the project. If the list is empty, or if changes have been made to the teams since the last pull of information into MDCMS, click the button Get Project Users. This may take several seconds. If it fails, review the Connection Log.

When the team members are retrieved from Azure DevOps, MDCMS will try to automatically map them to MDSEC users where the email address are the same or display names are the same.

To modify the mapping for a row in the view, place the cursor in the MDCMS User field and edit the value. Content-Assist can be used to select a MDCMS user from a list.

Project Webhooks

For each Pipeline Server, which represents a Project in Azure DevOps, webhooks can be created by MDCMS in the Azure DevOps Service Hooks settings in order for MDCMS to be automatically informed whenever a work item is created or updated, so that there isn’t a delay in importing the work item data into MDCMS.

See the pre-requisites section at the beginning of this tutorial to ensure that the communication from Azure to MDCMS will be feasible.

In order to create, update or delete the MDCMS webhooks for an Azure DevOps project, right-click on the Pipeline Server entry and select option Project Webhooks.

This brings up a view with both event types, and information about the currently registered Webhook, if applicable.

Press the Create/Update Webhooks to create the webhook for each event or to update them if the MDCMS URL changes due to a new address of the partition.

If the webhooks are no longer needed, then click the Delete Webhooks button.

In order to verify that the webhooks are functioning, do the following:

1. go into the Project in Azure DevOps

2. click on Project settings at the bottom-left

3. click on option Service hooks under the General section

4. verify that both events are listed and the host is correct.
   If they aren’t listed, then create from MDOpen.
   If they are listed, ensure the State = Enable. If in a different state, then click on the … and Enable

5. click on History to be able to review any recent attempts made to invoke the webhook

Pull Work Items from Azure DevOps

Full Import

Once the mapping is complete for work item types, users, fields and status codes, enable the applicable Work Item Types in the Project Mapping view and then click button Import Work Items.

All work items of enabled work item types matching the filter criteria will be imported or updated in MDCMS.

A full import should be performed initially and whenever a work item type definition is added or modified.

Delta Import

Once an initial Full Import is performed, the MDAZUR service will check every n seconds for any new or changed work items since the last check for each enabled Azure DevOps Work Item Type that is registered in MDCMS. The bandwidth for this request is very small since only differences from the prior check are returned.

The number of seconds to delay is set in Services->MDAZUR

If using the MDCMS webhooks, the recommended delay interval is 1800 seconds (30 minutes)

If not using the MDCMS webhooks, the recommended delay interval is 30 seconds

Push Comments to Azure DevOps

Command MDCMS(ENV)/MDAZURCMT can be used to push information in the form of comments to Azure DevOps for either a specific Issue or for all impacted Azure DevOps Issues in an RFP. It is intended to let the Azure DevOps participants know about RFP activity in MDCMS and can be added as a *RFP command to occur at necessary exit points, such as after an install so that testing will proceed or when approval is required for an installation.

MDJIRACMT transactions are logged in file MDCMS(ENV)/MDDJIRR.

The MDCMS, MDXREF and MDSEC libraries must be in the library list when the command is invoked.

MDJIRCMT Parameters

Example of *RFP command to post a comment to impacted work items with a link to the RFP and its objects in the MDWorkflow WebApp:

Command Type = Q (Installation Archive/Cleanup)

Keep MD Libs in Libl = true

Command =

MDAZURCMT CMT('<p>Object changes have been deployed to the QA environment by MDC
MS RFP ##RFPNBR##</p><p><a href="https://<yourhost.com>/mdworkflow/pages/u
serLoginInit.jsf?link=true&screen=RW0011&location=##WFLLOC##&application=##APPLI
C##&RFP=##RFPNBR##">MDWorkflow Link</a></p>') AGP(##APPLIC##) RFP(##RFPNBR##)

View Azure DevOps Information in MDCMS

Azure DevOps Work Items as Projects

The Azure DevOps Work Item ID is used as the Project ID in MDCMS + any prefix set in the configuration, so searching and listing is the same as for any other project.

Azure DevOps Work Items as Tasks/Subtasks

The Azure DevOps Work Item ID is directly used as the Task or Subtask number. The only exception to this is if the Work Item ID is > 9,999,999 or if the task number already existed because it originated from somewhere else. Additionally, the Work Item ID is stored in the MDCMS Task Reference Code. The code value can be searched and listed in MDCMS by pressing F8=Ref Code in the Task Listing.

In MDOpen, the Azure DevOps Workitem ID is shown in its own column in the task/subtask views and can be clicked on to open the page in Azure DevOps showing the Work Item.