---
sourceDocument: Australia Impact
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/impact

 Release :

    - australia

ft:locale :

    - en-US

ft:publication_title :

    - Australia Impact

ft:clusterId :

    - ipact

bundleId :

    - ipact


---

# Configure Azure DevOps story integration

# Configure Azure DevOps story integration {#ariaid-title1}

* Release version: Australia
* 
* Updated March 12, 2026
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 2 minutes to read

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
{#configure-azure-devops-integration-options__ul_kgx_1lv_3hc}

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 ALLImpactConfigurationScan Engine Properties and select the User Story Integration properties tab.
5. Set Integration Type to <kbd class="ph userinput">Azure DevOps</kbd> 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](https://servicenow-prod.fluidtopics.net/3z3H6kBuoXH4638exKAZ2A#azure-devops-integration-script-best-practices "Script variables, field paths, and leading practices for writing field mapping scripts in the Azure DevOps story integration.") for available script variables, common field paths, and guidance on writing field mapping scripts for Azure DevOps.

## Azure DevOps integration script leading practices {#ariaid-title2}

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

### Script variables {#azure-devops-integration-script-best-practices__section_w2v_jfw_djc}

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`.
{#azure-devops-integration-script-best-practices__table_x2v_jfw_djc__entry__2}

| 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. |
[Table 1. Available script variables]

{#azure-devops-integration-script-best-practices__table_x2v_jfw_djc}

### Common Azure DevOps field paths {#azure-devops-integration-script-best-practices__section_y2v_jfw_djc}

{#azure-devops-integration-script-best-practices__table_z2v_jfw_djc__entry__2}

| 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 |
[ ]

{#azure-devops-integration-script-best-practices__table_z2v_jfw_djc}

### Leading practices {#azure-devops-integration-script-best-practices__section_afv_jfw_djc}

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.

*[\>]: and then