Azure DevOps

Guide on the Ketryx integration with Azure DevOps

New in 2.11.3

1. Introduction

Ketryx provides seamless integration with Azure DevOps, enhancing compliance and streamlining the management of configuration items. This integration is purpose-built to:

• align your Azure DevOps workflows with industry standards such as ISO 13485, IEC 62304, and ISO 14971,

• synchronize data between Ketryx and Azure DevOps to maintain consistent electronic records,

• provide traceability across requirements and to test cases and test results, and

• enforce workflows that incorporate electronic approvals and audit trails for robust compliance.

This guide offers step-by-step instructions for setting up and utilizing the integration, and answers to frequently asked questions.

2. Setting up the integration

To integrate Ketryx with Azure DevOps, please ensure you have the necessary permissions and access to the REST API.

• Note: the initial connection should be made from a service account (e.g. [e-mail]), which should have Azure DevOps administrator privileges. It should NOT be someone's personal account, even if that person is an administrator.

• Rationale: Whoever sets up the initial connection to Ketryx via the API will be credited with making the changes that Ketryx makes in Azure DevOps. The biggest problem this creates is the danger that once the original person who sets up Ketryx leaves the company, typically, that person's IT credentials are revoked. In turn, this would revoke Ketryx's access to Azure DevOps and cause the Ketryx/Azure DevOps integration to stop working. (No data would be lost, but this is very annoying and potentially difficult to troubleshoot.)

1. Create a personal access token (PAT) for authentication.

   1. Navigate to Azure DevOps and go to User Settings > Personal Access Tokens.

   2. Click New Token and specify a name, expiration date, and necessary permissions.

   3. Click Create Token and take note of the generated PAT.

2. As a Ketryx admin, log in to Ketryx.

3. Navigate to Organization, then Connections and click Add Azure DevOps connection.

4. Provide the URL of your Azure DevOps instance and the generated PAT to establish the connection.

5. Confirm the integration in Ketryx by navigating to the Create project page where the Azure DevOps section will allow you to link an Azure DevOps project.

If the user associated with the PAT has the necessary permissions, a dropdown with a list of available projects will be shown.

After setting up the connection, Ketryx projects can be created and linked with one Azure DevOps project each.

3. Frequently Asked Questions

3.1. Q: How does Ketryx synchronize Azure DevOps data?

By default, Ketryx synchronizes the following work items between the platforms:

Azure DevOps work item type	Ketryx item type
Epic, Feature, Requirement	Requirement
Task	Task
Test Case	Test Case
Bug, Issue	Anomaly
Risk	Risk

Aside from these pre-defined item types, Ketryx allows you to override or add custom work item type mappings. See Azure DevOps configuration.

Work item links are synchronized as relations between items in Ketryx. By default, the following work item link types are created:

Azure DevOps work item link IDs	Ketryx relation type
Related, Predecessor, Successor	Is Related To
Parent	Has Parent
Tested By	Tests

How Ketryx handles test items:

Azure DevOps test item	Ketryx item
Test Plan	Test Plan
Test Run	Test Execution
Test Case	Test Case

Ketryx synchronizes test runs as Test Execution items and creates relations to the corresponding Test Case items.

3.2. Q: Can I customize how Ketryx maps Azure DevOps fields and work item links?

Yes. Ketryx provides advanced settings for Azure DevOps that allow you to define how Azure DevOps fields map to Ketryx items. You can map both built-in and custom fields to Ketryx fields.

3.3. Q: How do I handle changes in Azure DevOps schema (e.g., custom fields)?

If you add custom fields in Azure DevOps, you can configure Ketryx to recognize them using the Azure DevOps field mapping setting. Additional work item links can be configured using Azure DevOps work item links mapping.

3.4. Q: What happens to deleted items?

When any item is deleted in Azure DevOps, it is marked as deleted in Ketryx but remains linked for traceability.

3.5. Q: How do I handle releases?

You can create custom work item fields in Azure DevOps to track versions.

1. To associate a work item with a particular version, create a custom field in Azure DevOps.

2. Configure the field in the Azure DevOps field mapping setting, using the field introducedInVersion and obsoleteInVersion.
3. Then, edit the work item and enter a version number in the custom field (e.g., entering "3.1.0" will synchronize the work item to version "3.1.0" in Ketryx).

4. Azure DevOps Configuration

4.1. Overview

The Azure DevOps settings in Ketryx allow users to configure how Azure DevOps work items and test runs map to Ketryx items. This mapping ensures accurate data synchronization between the two systems, preserving traceability and compliance. These configurations are crucial for seamlessly integrating work items and test runs into Ketryx workflows.

The configuration includes the following mappings:

• Azure DevOps work item mapping to Ketryx item type

• Azure DevOps status mapping to Ketryx item state

• Azure DevOps work item relations mapping to Ketryx relation type

4.2. Azure DevOps work item mapping

Example

[
    {
        "workItemType": "*",
        "fields": { "name": "title", "description": "description" },
    },
    {
        "workItemType": "Risk evaluation",
        "itemType": "RISK",
        "fields": { 
            "description": "sequenceOfEvents",
            "isRiskControlledBy": {
                "type": "references",
                "relationType": "IS_RISK_CONTROLLED_BY",
                "targetSystem": "JIRA"
                }
            },
    },
]

The "workItemType": "*" is a wildcard that applies the field configurations to all configured work item types. This allows you to avoid duplicating the same fields across multiple work item types in the schema. If a field is common to all work item types, you can use this wildcard instead of manually defining it for each type.

In this example, you can also see how to use a custom field to map a relationship. For instance, the isRiskControlledBy field—to relate a work item with the relation type IS_RISK_CONTROLLED_BY to another system, such as Jira.

4.3. Azure DevOps status mapping

Example

{
  "Proposed": "OPEN",
  "Design": "OPEN",
  "Completed": "CLOSED"
}

4.4. Azure DevOps work item relations mapping

Example

{
  "Parent": "HAS_PARENT" 
}

4.5 Azure DevOps status rules

In the beginning of the setup, if you have a complex workflow, it is recommended to set Allow item transition to No to prevent discrepancies between Azure DevOps and Ketryx.

Azure DevOps enforces specific rules on work item status changes. For example, in the CMMI template, a work item cannot transition directly from Closed to Resolved. To align Ketryx with these constraints, you may need to adjust your workflow configuration. This could involve modifying Ketryx to transition reopened items to Active in Azure DevOps instead of Resolved.

To ensure these rules are correctly reflected in Ketryx, configure the appropriate flow in the Approval workflow setting.

For more details on how Azure DevOps handles workflow states, refer to the official documentation here.

5. Azure DevOps extension

Ketryx offers an Azure DevOps extension that can be installed in your organization and used within synchronized projects. This extension enhances the integration by enabling users to view traceability directly within Azure DevOps work items, ensuring seamless visibility of related artifacts. Additionally, it allows users to sign items to transition them to a closed state directly within Azure DevOps, ensuring compliance with approval workflows. You can find the Ketryx Azure DevOps extension in the Azure DevOps Marketplace, where you will find comprehensive installation and setup instructions.

For more detailed instructions and advanced configuration options, please refer to the Ketryx Advanced Settings section of the documentation.