Azure DevOps (ADO) Work Item Integration

Simscope can integrate to Azure DevOps (ADO):

Link Simscope Issue IDs to ADO work items.
Create work items from Simscope Signatures.
Refresh work items from Simscope.

Here is an example ADO work item created from Simscope:

Installation / Configuration

1. Configure Azure Authentication Credentials

There are two options for authenticating with Azure. Choose ONE of these options:

Option A: Personal Access Token (similar to an API token)
- Simpler, but less secure.
Option B: App Registration (also called Serice Principal, Service Account, or Managed Identity)
- More complicated, but more secure.

Option A. Personal Access Token (PAT)

If you would like to get a PAT:

→ Docs: Create an Azure Personal Access Token (PAT).

Note: the Personal Access Token must at least have the following privileges:

Work Item: Read, write and manage

Option B. App Registration (Service Account)

→ See the Azure Authentication page to get ClientID, ClientSecret, and TenantID.

2. Copy Configuration

To install the ADO integration, copy:

bin/TEMPLATE_simscope_azure_config.py

To your simscope config/ directory (or your home directory) as:

PATH/simscope_azure_config.py

3. Install Azure Python libraries

This requires the following Azure Python libraries to be installed:

# NOTE: replace /PATH/TO with your Python path

> /PATH/TO/python3 -mpip install azure-devops azure-common msrestazure

4. Edit simscope_azure_config.py

Change: OrganizationURL to your organization base URL.
Change: (PersonalAccessToken OR ClientID/ClientSecret/TenantID) to the value(s) from Step 1.

AzureConfig = Config(
    OrganizationURL     = 'https://dev.azure.com/ORGANIZATION',

    # Option A: authentication using PAT
    # To create an Azure Personal Access Token (PAT)
    # > https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate
    #PersonalAccessToken = 'REPLACE-WITH-AZURE-PAT',

    # Option B: authenticate via TenantID/ClientID/ClientSecret
    #ClientID     = 'REPLACE-WITH-CLIENT-ID',
    #ClientSecret = 'REPLACE-WITH-CLIENT-SECRET',
    #TenantID     = 'REPLACE-WITH-TENANT-ID',
)

Edit AzureConfig.SimscopeToAzureMapping to map between each Simscope component and each ADO Project/Area.

Optional: you can add a _default line to point to a default Azure Project/Area, as a default fallback for any Simscope component not specified.

Here is an example mapping for two Simscope components (my_simscope_uart and my_simscope_i2c) mapped to Azure project Project Alpha, with separate Azure Areas set:

AzureConfig.SimscopeToAzureMapping = {
    # Table format:
    # ----------------------------------------
    # 'SIMSCOPE_COMPONENT1': ['AZURE_PROJECT', 'AZURE_AREA'],
    # ----------------------------------------
    # Note: the AZURE_AREA field can be set to None if the Azure project does not use an Azure field.
    # ----------------------------------------

    'my_simscope_uart': ['Project Alpha', None],
    'my_simscope_i2c':  ['Project Alpha', 'i2c'],

    # ----------------------------------------

    # OPTIONAL: If you want a default Azure Project/Area mapping.
    #           This is a fallback if all components use the same Azure Project/Area.
    '_default': ['Project Beta', 'Area1'],
}

5. Enable via Simscope configuration

To enable the plugin in Simscope, add the following to your simscope.config file:

Replace ORGANIZATION and the PATH variables.

# Simscope Azure DevOps (ADO) integration
[bugtracker "ADO"]
regex = "^[0-9]+$"
url = "https://dev.azure.com/ORGANIZATION/_workitems/edit/%s"
createplugin = "PATH/TO/simscope-azure.py --create-work-item --config=/CONFIG/simscope_azure_config.py"
refreshplugin = "PATH/TO/simscope-azure.py %s --config=/CONFIG/simscope_azure_config.py"
advanced = true

Enable auto-refresh, so Simscope will query ADO and pull updates. You can pick any update schedule (e.g. 30 mins).

[bugs]
# Auto-refresh ADO work items in Simscope
autorefresh = "30m"

6. Restart Simscope

Restart Simscope, to enable the ADO configuration.

Testing Work Item Create from Simscope

To test work item creation from Simscope:

Go to any Job Details page.
In the top-right section of the page, click Create Rule.
Under the Issue box, click Create Bug in ADO.

If successful, you will see an ADO work ID in Simscope.

Otherwise, Simscope will show the error message received from Azure on screen.

Testing Work Item Refresh

To test work item refresh (from Azure to Simscope):

In Simscope, find any Bug# and click on it.
In ADO, open the same work item and change any field (e.g. change the title) and save it.
In Simscope, click the Red refresh circle, to pull the latest update from Azure.

Common Azure Errors

Here are some common errors received from Azure, and what they mean.

Authentication

The requested resource requires user authentication:
...

type=<class 'azure.devops.exceptions.AzureDevOpsAuthenticationError'>

This is likely caused by an incorrect Azure Personal Access Token, or the token does not have read/write privileges for Work Items.

Not Authorized

- TF400813: The user 'aaaaa-aaaa-aaaa-aaaa-aaaaaaaaaa is not authorized to access this resource.
- type=<class 'azure.devops.exceptions.AzureDevOpsServiceError'>

This error indicates the Service Account is not a member of your ADO tenant project.

In other words, the user authenticated successfully as a valid user, but does not have membership privileges in the ADO Tenant project.

Simscope Administration Guide