Configure Azure DevOps story integration

Perform the following procedure to configure your Azure DevOps integration options.

Before you begin

• Before you begin, gather the following from your Azure DevOps environment:

  • Organization name
  • Project name
  • Work item type

Role required: Scan Engine admin (sn_se.scan_engine_admin).

Procedure

Generate an Azure DevOps API token

1. In Azure DevOps, select Personal access tokens from the user settings menu.
2. Select New Token and follow the Azure DevOps documentation to configure and generate the token.

Configure the integration

3. Navigate to sys_auth_profile_basic.list and select New.
   Create one basic auth record per user who will create Azure DevOps work items. Set Username to the user's email address and paste the API token in Password.
4. Navigate to ALL > Impact > Configuration > Scan Engine Properties and select the User Story Integration properties tab.
5. Set Integration Type to Azure DevOps and populate the following fields: Organization name, Project name, Work item type.
6. Select Update.

What to do next

See Azure DevOps integration script leading practices for available script variables, common field paths, and guidance on writing field mapping scripts for Azure DevOps.

Azure DevOps integration script leading practices

Script variables, field paths, and leading practices for writing field mapping scripts in the Azure DevOps story integration.

Script variables

The Azure DevOps field mapping script runs on the ServiceNow instance at the time a work item is created. Set field values on the payload object using the Azure DevOps field path format: payload['/fields/System.Title'] = value.

Table 1. Available script variables

Variable	Description
payload	The field mapping object sent to your Azure DevOps project. Set field path keys on this object to populate work item fields.
grFinding	GlideRecord of the finding. Use this to read finding data for field mapping.
workItemType	The work item type selected for this integration.

Common Azure DevOps field paths

Field path	Maps to
/fields/System.Title	Work item title
/fields/System.Description	Work item description
/fields/Microsoft.VSTS.Common.Risk	Risk level
/fields/Microsoft.VSTS.Scheduling.StoryPoints	Story points

Leading practices

Use field path syntax for all payload assignments

Azure DevOps requires field values to be set using the JSON Patch path format. Always use bracket notation: payload['/fields/System.Title'] = grFinding.getValue('short_description'). Do not use dot notation or plain property names.

Verify field paths against your process template

The available field paths depend on your Azure DevOps process template (Agile, Scrum, or CMMI). Confirm that the field paths you use exist in your project's work item type before deploying your mapping script.

Use grFinding to pull finding context

Access finding details using standard GlideRecord methods on grFinding. For example, grFinding.getValue('short_description') maps cleanly to /fields/System.Title.

Enable ES12 mode for modern JavaScript

To use modern JavaScript syntax, enable ECMAScript 2021 (ES12) mode in Scan Engine Properties before writing your mapping script.