{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":19791,"path":"impact/configure-azure-devops-integration-options.md","title":"Configure Azure DevOps story integration","bundle":null,"doc_type":null,"release":"australia","body":"\n# Configure Azure DevOps story integration\n\nPerform the following procedure to configure your Azure DevOps integration options.\n\n## Before you begin\n\n-   Before you begin, gather the following from your Azure DevOps environment:\n\n    -   Organization name\n    -   Project name\n    -   Work item type\n\nRole required: Scan Engine admin \\(sn\\_se.scan\\_engine\\_admin\\).\n\n## Procedure\n\n1.  Generate an Azure DevOps API token\n2.  In Azure DevOps, select **Personal access tokens** from the user settings menu.\n\n3.  Select **New Token** and follow the Azure DevOps documentation to configure and generate the token.\n\n4.  Configure the integration\n5.  Navigate to `sys_auth_profile_basic.list` and select **New**.\n\n    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**.\n\n6.  Navigate to **ALL** > **Impact** > **Configuration** > **Scan Engine Properties** and select the **User Story Integration** properties tab.\n\n7.  Set **Integration Type** to `Azure DevOps` and populate the following fields: **Organization name**, **Project name**, **Work item type**.\n\n8.  Select **Update**.\n\n\n## What to do next\n\nSee [Azure DevOps integration script leading practices](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/impact/configure-azure-devops-integration-options.md) for available script variables, common field paths, and guidance on writing field mapping scripts for Azure DevOps.\n\n**Parent Topic:**[User story integration](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/impact/user-story-integration-properties.md)\n\n## Azure DevOps integration script leading practices\n\nScript variables, field paths, and leading practices for writing field mapping scripts in the Azure DevOps story integration.\n\n### Script variables\n\nThe 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`.\n\n|Variable|Description|\n|--------|-----------|\n|`payload`|The field mapping object sent to your Azure DevOps project. Set field path keys on this object to populate work item fields.|\n|`grFinding`|GlideRecord of the finding. Use this to read finding data for field mapping.|\n|`workItemType`|The work item type selected for this integration.|\n\n### Common Azure DevOps field paths\n\n|Field path|Maps to|\n|----------|-------|\n|`/fields/System.Title`|Work item title|\n|`/fields/System.Description`|Work item description|\n|`/fields/Microsoft.VSTS.Common.Risk`|Risk level|\n|`/fields/Microsoft.VSTS.Scheduling.StoryPoints`|Story points|\n\n### Leading practices\n\n-   **Use field path syntax for all payload assignments**\n\n    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.\n\n-   **Verify field paths against your process template**\n\n    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.\n\n-   **Use grFinding to pull finding context**\n\n    Access finding details using standard GlideRecord methods on `grFinding`. For example, `grFinding.getValue('short_description')` maps cleanly to `/fields/System.Title`.\n\n-   **Enable ES12 mode for modern JavaScript**\n\n    To use modern JavaScript syntax, enable **ECMAScript 2021 \\(ES12\\) mode** in Scan Engine Properties before writing your mapping script.\n\n\n"}}