Integrate With Azure DevOps (ADO) | ReqView Documentation

⚠ The web page functionality is limited because your browser blocks Javascript. Please enable Javascript and reload the page to continue.

Table of Contents

Workflow
Set up ADO Integration
Synchronize With ADO
Update From ADO
Manage Tests in ADO
Example Integration With ADO

You can connect ReqView with Azure DevOps (ADO) to benefit from an integrated Application Lifecycle Management (ALM) solution.

With ReqView, you can manage stakeholder requirements, system requirements, low-level HW/SW requirements, risks, validation and verification (V&V) information. This data is organized into structured documents and linked, enabling easy review and tracing of related requirements.
With ADO, you can manage SW development using the available work item tracking processes. You can also manage tests and their execution, Git repositories, build pipelines and artifacts.

Workflow

With ReqView and ADO integration, you can follow this workflow:

Capture Requirements: Manage and trace requirements across the V-model in ReqView. Capture detailed low-level requirements for a HW/SW subsystem.
Export Requirements: Export a baseline of low-level requirements document from ReqView into an ADO project to share them with the development team. Trace requirements between ReqView and ADO work items in both directions.
Manage SW Development: Manage SW development in ADO using one of Basic, Agile, Scrum or CMMI (Capability Maturity Model Integration) work item tracking processes:
- Decompose user stories to tasks.
- Plan user stories and tasks using the ADO Sprints.
- Assign user stories and tasks to developers using the ADO field Assigned To.
- Track the development progress of user stories using the ADO field State.
Update From ADO: Fetch information about the development status of exported ADO work items in the source ReqView document to display it in a Requirements Traceability Matrix (RTM).

Set up ADO Integration

Follow these steps to set up ReqView and ADO integration:

Enable ADO integration in ReqView.
Configure export of documents from ReqView to ADO.
Manage ADO credentials for ReqView.
Manage ADO project permissions.

Enable ADO Integration

To enable ADO integration in ReqView, click Edit, select Preferences, and tick Integrate with Azure DevOps.

Configure Synchronization With ADO

To configure export of requirements from ReqView to ADO, select a document storing requirements, click File, select Azure DevOps and then Configure Synchronization. In the Configure Synchronization With Azure DevOps dialog update the configuration in JSON format:

Configuration of Azure DevOps Synchronization in ReqView

Configuration Properties:

adoOrganization – organization name in Microsoft cloud-based Azure DevOps Services. You can find this value in the URL https://dev.azure.com/<organization-name>/ when you open your ADO project site in a web browser.
adoCollectionUrl – when using an on-premise Azure DevOps Server, its full URL including protocol, port and collection name, e.g. https://myadoserver.local:8443/DefaultCollection.
adoProjectName – e.g. MyProject.
adoWorkItemType – mapping of ReqView document objects to ADO work item types.
- reqviewAttribute – the ReqView custom attribute describing the type of document objects (e.g., “type”).
- mapping – a JSON object describing how to set work item types based on the type of ReqView documents objects.
  - key – ADO work item type (e.g., “Epic” or “User Story”).
  - value – the corresponding value of the ReqView custom attribute (e.g. “EPIC” or “STORY”).
adoFields (optional) – a JSON object describing how to set ADO fields, see Export Requirements to ADO
- key – the target ADO field. Note that only “Description” and Title values are supported.
- value – the source ReqView attribute or template column (e.g., “text”).
reqviewAttributes – a JSON object describing how to set ReqView attribute values based on ADO work items field values. See section Update Requirements From ADO below.
- key – the target ReqView custom attribute (e.g., “adoState”).
- value – the source information fetched from ADO:
  - the name of an ADO field (e.g., “State”), see Work item field index
  - $URL – fetch the URL of the ADO work item
  - $Links(<link_type_name>) – fetch a list of URLs of work items linked by a given link type (e.g., “$Links(Tested By)”), see Link type reference
  - $LinkedWorkItems(<work_item_type>) – fetch URLs of linked work items of a given type (e.g., “$LinkedWorkItems(Test Case)”), see About work items
exportAttachments (optional) – true string to export attachments from ReqView to ADO.

Notes:

Only one of the adoOrganization or adoCollectionUrl properties might be present in the configuration.
Depending on the Work item tracking process used for your ADO project, map ReqView document objects to the following ADO work item types:
- Epic > Issue for Basic process
- Epic > Feature > User Story for Agile process
- Epic > Feature > Product Backlog Item for Scrum process
- Epic > Feature > Requirement for CMMI process
Only Epic work items can be nested in themselves.
Work items at a lower leven than Epic (e.g. Issue or Requirement) can only have parents of a higher level or be unparented.

Example: Open the Example Project and configure the ADO integration to export epics and user stories from the document NEEDS to a new Agile project hosted at ADO.

Create a new project called MyProject by using the New project button on your ADO organization home page located at the URL https://dev.azure.com/<organization-name>/. Expand the Advanced options and choose Agile as the Work item process:
In ReqView, configure the document NEEDS for synchronization with ADO. First, open the document NEEDS and select File > Azure DevOps > Configure Synchronization from the menu, and enter the following configuration in the Configure Synchronization With Azure DevOps dialog:
```
{
  "adoOrganization": "reqview",
  "adoProjectName": "MyProject",
  "adoWorkItemType": {
    "mapping": {
      "Epic": "EPIC",
      "User Story": "STORY"
    },
    "reqviewAttribute": "type"
  },
  "adoFields": {
    "Description": "Story"
  }
}
```
The values of configuration properties adoOrganization and adoProjectName are based on the URL of your ADO project:

Note that:
- The configuration property adoWorkItemType.reqviewAttribute is set to “type” because ReqView document NEEDS defines custom enumeration attribute type to describe the type of document objects, see also Customize Attributes.
- The configuration property adoWorkItemType.mapping is set to create ADO work items as follows:
  - Each ReqView document object with the attribute type equal to “EPIC” is exported as an Epic work item in ADO.
  - Each ReqView document object with the attribute type equal to “STORY” is exported as a User Story work item in ADO.
  - Other document objects are not exported.
- The configuration property adoFields is set to export the ReqView template column Story as the ADO field Description.
  - Display of template column Story for the source document in ReqView:
  - Display of a target ADO work item:

Authentication

ReqView supports two authentication methods for ADO:

Microsoft Entra ID OAuth – Microsoft’s cloud-based identity and access management platform, previously called Azure Active Directory
- This is the default, most secure and recommended option, with no configuration required
- An organizational (work or school) account is required
- When ReqView connects to Azure DevOps Services for the first time, Microsoft’s login page will be opened in your system browser. After a successful login, you will be asked for consent for application permissions needed by ReqView:
- To sign out from ADO in ReqView, click File, select Azure DevOps and then Log Out of Azure DevOps
Personal Access Token (PAT)
- Only for on-premises scenarios with Azure DevOps Server or advanced use
- Ensure that the following access scopes are checked:
  - Work Items – Read & write
  - Project and Team – Read
  - Test Management – Read
- To enter a PAT, use the Authentication button in the Configure Synchronization With Azure DevOps dialog and then select the Personal Access Token radio button option:
- To delete the PAT associated with an organization or collection, press the button or select the default Microsoft Entra OAuth

Synchronize With ADO

To export requirements from ReqView to ADO, open the exported document, click File, select Azure DevOps, and then Synchronize Document. The integration iterates the document and creates new ADO work items or updates already exported work items according to the Export Configuration:

Work Item Type – is based on the type of source document objects in ReqView as defined by the configuration property adoWorkItemType (e.g., Epic or User Story work items).
Hierarchy – ADO work items have the parent-child relationship set according to hierarchy of source ReqView document objects (e.g., Epic work items are the parent of User Story work items).
Title field – is set to the value of attributes heading and id of the source requirement. Optionally, you can adjust the configuration property adoFields to use a custom attribute or a template column instead.
Description field – is set to the value of text attribute of the source requirement. Optionally, you can adjust the configuration property adoFields to use a custom attribute or a template column instead.

ReqView is the source of truth of this information in the exported ADO work items. ADO users should not change it because ReqView will overwrite it in the next synchronization. However, ADO users can update other ADO fields (e.g., State, Assigned To, or Iteration) as needed to manage the development of requirements in ADO.

You can repeat the synchronization of requirements to ADO for each updated version of the source document. ReqView will update ADO work items created earlier or create work items for new requirements added since the last synchronization. ReqView will mark ADO work items corresponding to deleted (or purged) requirements in ReqView as deleted in ADO using “[Deleted]” prefix in the work item Title. You can query such work items based on the prefix to permanently remove them in ADO.

To navigate from a ADO work item to the corresponding requirement in ReqView, open the ADO work item in browser and click the ReqView Link at the end of the work item’s Description field. Optionally tick Always allow dev.azure.com to open links of this type in the associated app in the Open ReqView? dialog, and finally click Open ReqView. For more information about ReqView URL links, see Share URL Links.

Update From ADO

You can fetch information about exported ADO work items (e.g., work item URL, state, assignee, iteration) to the original document in ReqView and display this information in table views for review or coverage analysis purposes.

The information fetched from ADO is stored in custom attributes of the exported document. We recommend that you define attributes for storing ADO information as follows:

external: true to avoid saving attribute values in the Project File or Project Folder.
readOnly: true to disable editing of attribute values by users.

To configure information fetched from ADO during synchronization and update, set the configuration property reqviewAttributes, see Configure Synchronization with ADO. The Work item field index lists all core and process-specific fields available in ADO.

To navigate from a ReqView requirement to the corresponding ADO work item by clicking on URL links, define a custom xhtml attribute and map this attribute to “$URL” in the configuration property reqviewAttributes.

To get navigable links to ADO work items linked by a given link type, define a custom xhtml attribute and map this attribute to “$Links(link type name)” in the configuration property reqviewAttributes. The Link type reference lists all system-defined link types.

To fetch information from ADO without updating ADO work items, open the exported document in ReqView, click File, select Azure DevOps and then Update Document. If the document is editable, then ReqView updates all attributes listed in the configuration property reqviewAttributes. Otherwise, ReqView only fetches values of external attributes from ADO and keeps them until the project is closed.

Example: Fetch the URL, state, assignee and iteration information from the ADO User Story work items exported from ReqView.

In the Document Attributes dialog, define ReqView custom attributes adoUrl, adoState, adoAssignedTo and adoIteration to store information fetched from ADO as follows:
```
{
  "adoUrl": {
    "name": "ADO URL",
    "type": "xhtml",
    "readOnly": true
  },
  "adoState": {
    "name": "ADO State",
    "type": "string",
    "readOnly": true,
    "external": true
  },
  "adoAssignedTo": {
    "name": "ADO Assigned To",
    "type": "string",
    "readOnly": true,
    "external": true
  },
  "adoIteration": {
    "name": "ADO Iteration",
    "type": "string",
    "readOnly": true,
    "external": true
  }
}
```
- All attributes are defined as read-only because their source of truth is in ADO and users should not edit their values in ReqView.
- The attribute adoUrl is not defined as external because we need to persist its values in the project so that other users can display its values and navigate to ADO without having to update the document after opening the project.
- The attributes adoState, adoAssignedTo and adoIteration are defined as external because we do not want to store them within the project. To display their values after opening the project, users need to update their values from ADO.
Display columns ADO URL, ADO State, ADO Assigned To and ADO Iteration in the table view.

In the Configure Synchronization With Azure DevOps dialog, set the configuration property reqviewAttributes as follows:

{
  "reqviewAttributes": {
    "adoUrl": "$URL",
    "adoState": "State",
    "adoAssignedTo": "Assigned To",
    "adoIteration": "Iteration Path"
  }
}

Update the document from ADO:

Manage Tests in ADO

You can describe test cases in ReqView documents and link them to requirements by verification links conveniently. However, you can also manage test plans, test suites and test cases and get results from test runs in ADO.

You can define test plans and test suites and then describe test cases as ADO work items of type Test Case, which provide information about tests steps, test data, and expected results. Then, you link Test Case work items to User Story work items to trace verified requirements. See Azure Test Plans documentation for detailed information about test management in ADO.

Example: Manage tests in ADO.

Test cases in ADO are described in Test Case work items:

And, test coverage is visible in the Boards view:

Test results for a User Story in Azure DevOps

In ReqView, open the Document Attributes dialog and add new external read-only custom attribute to fetch URLs of work items linked to the exported work items by the Tested By work item link:

{
  "adoTestLinks": {
    "name": "ADO Test Links",
    "type": "xhtml",
    "external": true,
    "readOnly": true
  }
}

Then, open the Configure Synchronization With Azure DevOps dialog and map adoTestLinks to URLs of work items linked by Tested By links as follows:

{
  "reqviewAttributes": {
    "adoTestLinks": "$Links(Tested By)"
  }
}

Example Integration With ADO

You can try ReqView integration with ADO easily. We have configured the Example Project for exporting epics and users stories from the document NEEDS into your test ADO project.

Follow these steps:

Download Example ReqView Project (reqview-demo-ado.reqw).
Start ReqView and enable ADO integration, click Edit, select Preferences, and tick Integrate with Azure DevOps.
Open the project file reqview-demo-ado.reqw in ReqView, open NEEDS document, open the Configure Synchronization With Azure DevOps dialog, and replace “MyOrg” and “MyProject” to match your ADO organization and project.
Synchronize epics and user stories from the NEEDS document.

Updated for version 2.22.0