Skip to main content
What you can do:
  • Ingest Azure DevOps work items into Gradial with their fields, comments and attachments
  • Trigger Gradial execution when work items match your route criteria
  • Write results — previews, links, status — back to the originating work item
  • Target work items precisely, using structured filters or your own WIQL query
Gradial syncs Azure DevOps on a schedule. New and updated work items are picked up on the next sync cycle rather than instantly.

​
Why route web work through Azure DevOps

Marketing content requests often arrive in Azure DevOps because that is where the engineering organization already works — a shared board, an existing intake form, a sprint everyone can see. The request lands as a work item, joins a backlog of genuine engineering work, and then waits, because “update the pricing page headline” and “fix the checkout race condition” are competing for the same team’s attention. That’s the wrong queue for the work, but the right place for the request. Connecting Azure DevOps keeps intake and reporting exactly where they are, and moves execution out of the engineering backlog.

​
Prerequisites

​
Create a dedicated Gradial service user

Create a service account in Azure DevOps for Gradial rather than using a person’s credentials. This keeps the audit trail legible — every comment and update Gradial writes back is clearly attributable — and means the connection survives people changing roles. The service user needs:
  • Access to each project Gradial will read work items from
  • Permission to read work items in those projects
  • Permission to add comments and attachments, and to edit the fields you want Gradial to update on completion
Grant only the projects Gradial should see. Project membership is the outer boundary on what any route can reach.

​
Connect Azure DevOps to Gradial

Go to Settings → Integrations, find Azure DevOps under Ticketing & work management, and select Connect. The wizard covers Connection, Routing, and Route Summary.

​
Step 1 — Create a personal access token

  1. Sign in to Azure DevOps as the service user
  2. Open User settings → Personal access tokens
  3. Select New Token
  4. Scope it to the organization Gradial will work in, set an expiry, and grant Work Items (Read, write & manage)
  5. Copy the token — Azure DevOps shows it only once
Personal access tokens expire. Note the expiry date when you create the token and set a reminder, because an expired token stops ingestion silently — routes simply return nothing new.

​
Step 2 — Configure the connection

  1. Enter an Integration Name to identify this connection
  2. Enter your Organization URL — https://dev.azure.com/{your-organization}
  3. Paste the service user’s personal access token
  4. Select Validate Connection
  5. Once validated, continue to routing
Once saved, credentials are stored securely and cannot be viewed again. To rotate the token, update the integration with the new value.

​
Step 3 — Configure routing

On the Routing step, add a route for each set of work items Gradial should ingest. Routes can be toggled on and off independently. Gradial destination:
The most reliable intake pattern is assignment: have requesters assign the work item to the Gradial service user, and route on Assigned to. It makes intake an explicit act rather than a filter that might match more than anyone intended — and it gives requesters an obvious way to opt a single item out.

​
Advanced: routing with WIQL

Where structured filters can’t express the selection you need, a route can carry a raw WIQL query instead. This is worth reaching for when your intake depends on a combination of custom fields, or on relationships between work items.
Test the query in Azure DevOps first and confirm the result set is what you expect. A WIQL route ingests everything the query returns. Select Next to review the Route Summary, and confirm each route pulls in what you expect before finishing. For ingestion modes and best practices, see Routing Tickets →

​
How work item execution works

  1. A work item matching a route’s criteria is discovered on the next scheduled sync
  2. Gradial ingests it as a Task, including its title, description, field values, comments and attachments
  3. Gradial executes the requested work
  4. Results — previews, links and status — are written back to the originating work item as the service user
  5. Gradial keeps watching the work item for changes that should trigger follow-up work

​
Troubleshooting

​
Who this is for

​
Availability

Access: Must be enabled for your organization. Contact your Gradial team to get access.