Configuring Azure DevOps Record Transformers for Notification and Import (Custom Field Mapping) - Product Knowledge

Configuring Azure DevOps Record Transformers for Notification and Import (Custom Field Mapping) ServiceNow DevOps – Azure DevOps Record Transformer Configuration Map Your Own Custom Fields for Notification & Import using Integration Capability Transformers Applies to: Azure DevOps (Boards / Work Items) | Actions: Notification & Import

🔄 What This Guide Covers Out of the box, ServiceNow DevOps maps a fixed set of fields from Azure DevOps work items into the DevOps data model. If you want to bring across an additional field (for example, map the work item’s State on a notification, or copy the Iteration Path into the Description on import), you can build your own Record Transformer and attach it to the relevant Integration Capability — no development request required.

This guide walks you through creating your own record transformer for both the Notification and the Import flow, step by step, with the exact tables, field values, and JSON paths to use:

🔔 Part A — Notification (Azure DevOps Boards Notification) Add a mapping that runs when a work item change webhook / notification arrives from Azure DevOps. → Go to Part A

📥 Part B — Import (ADO Import WorkItems) Add a mapping that runs when work items are imported from Azure DevOps. → Go to Part B

Table of Contents 1. Key Concepts & Tables 2. How a Record Transformer Works 3. Prerequisites 4. Finding the Correct Path (Most Important Step) 5. Part A — Notification: Azure DevOps Boards Notification Step A1: Create the Record Transformer Step A2: Add the Record Transformer Rule Step A3: Link it via Integration Capability Transformer Step A4: Allow the notification to track your field (custom fields) 6. Part B — Import: ADO Import WorkItems Step B1: Create the Record Transformer Step B2: Add the Record Transformer Rule Step B3: Link it via Integration Capability Transformer 7. Verify & Test 8. Reference 💡 In one line: You create three (3) records — a Record Transformer , a Record Transformer Rule under it, and an Integration Capability Transformer that links the transformer to the right capability. (For the Notification flow only, one extra step is needed if you want to track a custom field — see Step A4.)

🧩 1. Key Concepts & Tables Four tables work together. You will read from the first and create records in the other three.

Concept Table What it is Integration Capability sn_devops_integration_capability An action a tool can perform (Notification, Import, Discover, …). Already exists — you only reference it. Record Transformer sys_record_transformer The transformer definition — the “container” for your mapping rules. You create this. Record Transformer Rule sys_record_transformer_rule One rule = one field mapping ( source path → target field ). You create one per field. Integration Capability Transformer sn_devops_m2m_capability_transformer The link that says “run this transformer for this capability .” You create this to activate the mapping. 💡 Note: A Record Transformer Rule Sequence ( sys_record_transformer_rule_sequence ) is created automatically for you when you fill in the Record Transformer Rule Sequence field on the transformer — it just groups the rules. You do not need to build it by hand.

⚙️ 2. How a Record Transformer Works Azure DevOps sends a raw JSON payload (a webhook notification, or an imported work item). DevOps looks up the matching Integration Capability (by tool + capability mapping + action). It finds every Integration Capability Transformer linked to that capability and runs each Record Transformer . Each Record Transformer Rule reads a value from the source payload at its Path and writes it to the target field named by its Symbol . The transformer output is merged on top of the standard out-of-the-box payload, then the record is saved. Your mapped field wins. ⚠️ Because the output is merged over the standard payload, the Symbol you choose becomes the target field. Use an existing target field name (e.g. state , description ) to override it.

✅ 3. Prerequisites Role: You need the sn_devops.admin role to see the “Create a record transformer” action and to edit these records. Application scope: Set your scope to DevOps Integrations ( sn_devops_ints ) before you begin. All records in this guide should be created in this scope. Tool onboarded: The Azure DevOps tool must be created, connected, and have its projects / plans discovered. Know your field: Decide which Azure DevOps field you want to map and to which target field. 🧭 4. Finding the Correct Path (Most Important Step) The Path on a Record Transformer Rule is a JSON path into the source payload . The payload shape is different for Notification vs Import , so the path prefix is different too. Get this from the actual payload, not from memory.

For Notification — inspect the inbound event’s original payload Trigger a work-item change in Azure DevOps so a webhook is sent to ServiceNow. Open the corresponding inbound event record ( sn_devops_inbound_event ; note that processed events are moved to sn_devops_processed_inbound_event hourly). Open the Original payload field — this is the raw JSON body Azure DevOps sent. The transformer receives this whole body under a top-level payload key, and an Azure DevOps work-item webhook nests the fields under resource.revision.fields . So the path is .payload.resource.revision.fields['System.State'] — format the path for any other field the same way, reading it off the original payload. For Import — inspect the flow action response Open Workflow Studio and find the action azure_devops__get_workitem_details (label: “ADO-get workItem details” ). Click Test , provide a connection alias and a work item id, and run it. Open the Response Body output and view the JSON. It will look like the sample below. Import feeds one work item at a time into the transformer, so your path is relative to a single work item object (one element of value[] ) — it starts at fields[…] . Example: fields['System.IterationPath'] . Sample response from azure_devops__get_workitem_details : (trimmed — the field you want lives inside value[ ].fields )

{ "count": 1, "value": [ { "id": 67, "rev": 1, "fields": { "System.WorkItemType": "Epic", "System.State": "New", "System.Title": "testinh", "System.IterationPath": "SampleProject\\LatestSprint2", "System.CreatedDate": "2026-08-25T07:12:09.14Z", "System.CreatedBy": { "displayName": "Mahesh Ganji", "uniqueName": "mahesh.ganji@example.com" } }, "url": "https://dev.azure.com/org/.../_apis/wit/workItems/67" } ] } So to map the Iteration Path, the Path on your rule is fields['System.IterationPath'] . To map any other field, copy its key from value[ ].fields the same way.

“ADO-get workItem details” action inputs (Workflow Studio)

Test → Response Body JSON — the field lives under value[ ].fields

⚠️ This is the #1 gotcha: the same field has a different path in each flow.

Flow Payload the transformer receives Path prefix Notification The whole webhook event body .payload.resource.revision.fields['System.…'] Import A single work item object fields['System.…'] 🔔 5. Part A — Notification: Azure DevOps Boards Notification Goal (worked example): When a work-item change notification (webhook) arrives from Azure DevOps, map the work item’s State using a custom rule.

Step A1: Create the Record Transformer 📍 Table: sys_record_transformer

Name Azure Devops State Output Type JSON Print Format COMPACT Base Path $ Active ✔ true Record Transformer Rule Sequence Azure Devops State Rule (create new) Record Transformer: Azure Devops State

Step A2: Add the Record Transformer Rule 📍 Table: sys_record_transformer_rule

Name state Symbol (target field) state Path (source) .payload.resource.revision.fields['System.State'] Order 100 Type JSON Record Transformer Rule Sequence Azure Devops State Rule Record Transformer Rule: state (Path = .payload.resource.revision.fields['System.State'])

Step A3: Link it via Integration Capability Transformer 📍 Table: sn_devops_m2m_capability_transformer

Open DevOps Tool Integration → Azure DevOps → Integration Capabilities , open the Notification row (Sub flow sn_devops_ints.azure_devops_boards_notification ), and add a new Integration Capability Transformer :

Active ✔ true Integration capability sn_devops_ints.azure_devops_boards_notification Record transformer Azure Devops State Symbol Leave blank ⚠️ Keep the Symbol on this link blank. If you set it, the transformer output gets nested under that symbol instead of merging directly onto the work-item payload, and your field will not be applied.

Integration Capability: azure_devops_boards_notification with its Transformers related list

Integration Capability Transformer linking Azure Devops State to the notification capability

Step A4 (custom fields only): Allow the notification to track your field ⚠️ Only needed for custom / non-standard fields. Azure DevOps only sends a work-item notification for fields ServiceNow is set up to track. If you map a field that is not already tracked, the notification is dropped before your transformer ever runs — so the mapping appears to do nothing. The standard fields System.State , System.Title , System.WorkItemType , System.IterationPath , System.Parent , System.CreatedDate , System.AssignedTo , System.CreatedBy are already tracked — if your field is one of these, skip this step.

📍 Script Include: DevOpsAzureEventFilterAPIHandlerSNC | Method: _preProcessPlanEventWorkItemUpdated

Add your field’s Azure DevOps reference name to the _trackedFields array. For example, to also track a custom field Custom.MyField :

Before:

var _trackedFields = ['System.WorkItemType', 'System.State', 'System.Title', 'System.CreatedDate', 'System.Parent', 'System.IterationPath', 'System.AssignedTo', 'System.CreatedBy']; After (added Custom.MyField ):

var _trackedFields = ['System.WorkItemType', 'System.State', 'System.Title', 'System.CreatedDate', 'System.Parent', 'System.IterationPath', 'System.AssignedTo', 'System.CreatedBy', 'Custom.MyField']; 💡 How it fits together: this filter only decides whether the notification is processed (not ignored). Adding your field here lets the event through; your Record Transformer rule (Steps A1–A3) is still what reads the value and maps it onto the record. Custom-field notification tracking needs both .

The _trackedFields array inside _preProcessPlanEventWorkItemUpdated in DevOpsAzureEventFilterAPIHandlerSNC .

📥 6. Part B — Import: ADO Import WorkItems Goal (worked example): When work items are imported from Azure DevOps, copy the work item’s Iteration Path into the Description field.

Step B1: Create the Record Transformer 📍 Table: sys_record_transformer

Name ADO Import WorkItem - IterationPath to Description Output Type JSON Print Format COMPACT Base Path (leave blank) Active ✔ true Record Transformer Rule Sequence ADO Import WorkItem - IterationPath to Description (create new) Record Transformer: ADO Import WorkItem - IterationPath to Description

Step B2: Add the Record Transformer Rule 📍 Table: sys_record_transformer_rule

Name description Symbol (target field) description Path (source) fields['System.IterationPath'] Order 100 Type JSON Record Transformer Rule Sequence ADO Import WorkItem - IterationPath to Description Record Transformer Rule: description (Path = fields['System.IterationPath'])

Step B3: Link it via Integration Capability Transformer 📍 Table: sn_devops_m2m_capability_transformer

This is the record that activates your mapping. Open DevOps Tool Integration → Azure DevOps → Integration Capabilities , open the Import row (Sub flow sn_devops_ints.ADO Import WorkItems ), and add a new Integration Capability Transformer :

Active ✔ true Integration capability sn_devops_ints.ADO Import WorkItems Record transformer ADO Import WorkItem - IterationPath to Description Symbol Leave blank (see note) Order 100 ⚠️ Keep the Symbol on this link blank. If you set it, the transformer output gets nested under that symbol (e.g. { mySymbol: { … } } ) instead of merging directly onto the work-item payload, and your field will not be applied.

Azure DevOps tool → Integration Capabilities (the Import row)

Integration Capability Transformer linking the transformer to ADO Import WorkItems

🧪 7. Verify & Test Notification: Make a change to a work item in Azure DevOps so a webhook fires, then confirm the mapped field is applied on the corresponding DevOps record. Import: Run an Azure DevOps work item import (or re-run the import request) and open the imported work item in DevOps. Confirm the target field (e.g. Description ) now shows the mapped value (e.g. the iteration path). Use the Record Transformer Debug Triggers related list on the transformer / rule to debug if a value does not come through. If nothing is applied, re-check: (a) the link record is Active , (b) the Symbol on the link is blank , and (c) the rule Path exactly matches the payload (Notification starts at .payload.resource.revision.fields[…] ; Import starts at fields[…] ). Notification, custom field only: if the event never arrives, confirm the field is in _trackedFields (Step A4) — otherwise Azure DevOps updates to that field are ignored before the transformer runs. ⚠️ Note on parent work items (Import): During import, the transformer runs for the main imported work items. Parent work items pulled in indirectly (via the epic / parent link) do not receive the transformer, so a mapped field may not appear on those parent records.

📚 8. Reference 📖 Related Knowledge Article: ServiceNow DevOps Knowledge Base – KB Reference

Tables referenced in this guide: sn_devops_integration_capability , sn_devops_m2m_capability_transformer , sys_record_transformer , sys_record_transformer_rule , sys_record_transformer_rule_sequence .