Azure Boards

Bigeye's Azure Boards integration keeps a Bigeye issue and an Azure DevOps work item in step in both
directions. When an issue opens, Bigeye creates a work item in your project carrying the metric
context, thresholds, and query that triggered it. From then on, whichever side someone works in, the
other follows: state, comments, priority, assignee, and threshold feedback all sync.

Setup

Setup is done once per Azure DevOps project. Steps 1–3 need a Project Collection Administrator;
step 4 needs a Project Administrator. Allow about 30 minutes.

The one step that catches people out is the first: custom fields can only be added to an inherited
process, and Azure DevOps' built-in processes are locked. If your project is already on an inherited
process, skip to Step 2.

Step 1 — Put the project on an inherited process

1. Organization Settings → Boards → Process.
2. Find the process your project uses (for example Basic), open its ⋯ menu, and choose
   Create inherited process. Name it something like Bigeye Alerts.
   Inheriting is non-destructive: the new process starts with exactly the same work item types, states
   and rules as the one it came from.
3. Put your project on it — open the inherited process → Projects → Change process. If you are
   creating a new project instead, pick the inherited process in the advanced options at creation time
   and skip the switch entirely.

Step 2 — Add the three Bigeye fields

Bigeye files work items as the type named in your credential — Issue by default. Add the fields
to that type: custom fields in Azure DevOps are per work item type.

Organization Settings → Boards → Process → your inherited process → Work item types → the type
Bigeye will use → New field, three times:

Keep each field visible on the form (the Layout tab).

Do not rename, retype, or delete these fields afterwards. Azure DevOps derives a field's
reference name from its display name when it is created (Bigeye Issue ID → Custom.BigeyeIssueID), field names are org-global, and a field's type is fixed once created. Deleting a field destroys its history. If a name is wrong, create a new field rather than trying to repair the old one.

Which work item type to use

Do not use Task. It never appears on a board, in any process —
it is a child item, visible only in the flat Work Items list. To get board visibility, point Bigeye at
your process's backlog-level type:

Step 3 — Add a Monitoring state

Bigeye has four issue states. The Basic process ships with three — To Do, Doing, Done — which leaves
Bigeye's Monitoring state with nowhere to map. Adding a Monitoring state to the work item type
(between Doing and Done) gives you exact one-to-one status sync. Without it, Monitoring maps onto the
closest available state.

Step 4 — Install the Bigeye extension and connect

The extension is currently distributed privately. Give Bigeye your Azure DevOps
organization name, and we will share it with you — you will also receive your
webhook URL and secret at this point.

1. Once shared, go to Organization Settings → Extensions → Shared, select
   Bigeye for Azure Boards, and install it.
2. Open Project Settings → Bigeye in the project you want to sync.
3. Enter the webhook URL and webhook secret Bigeye gave you, and Save.

That provisions the two service hook subscriptions Bigeye needs. Confirm them under Project Settings
→ Service Hooks: you should see Work item updated and Work item commented on, both posting to
your webhook URL.

Saving again is safe — it replaces its own subscriptions rather than adding duplicates.

Step 5 — Send the details to Bigeye

Share the following with your Bigeye contact:

{
  "ado_org_url": "https://dev.azure.com/<your-organization>",
  "ado_project": "<project name>",
  "ado_pat": "<token from step 4>",
  "ado_work_item_type": "Issue",
  "bigeye_workspace_id": "<your Bigeye workspace id>",
  "bigeye_api_key": "<service account API key>"
}

Step 6 — Verify

Open a Bigeye issue and choose Create ticket. A work item should appear in your project within a
few seconds, tagged Bigeye, with the metric detail in its description and a Bigeye Issue link
under the Links tab. Change its state in Azure Boards and confirm the Bigeye issue follows.

Using the integration

What syncs

State mapping

Bigeye matches your work item type's states by keyword, so custom state names usually work without
configuration:

Comments

Comments copy in both directions and are prefixed with their origin — Comment by Bigeye user … on the
Azure Boards side, Comment by Azure Boards user … on the Bigeye side. That prefix is also how each
side recognizes its own writes, so a comment never bounces back and forth.

Comments written in the Azure Boards UI keep their line breaks; formatting is reduced to plain text.

Assignment

Assignment matches users by email address, so a person's Bigeye and Azure DevOps accounts need to
use the same address for it to sync. Removing an assignee in Azure Boards unassigns the Bigeye issue.

Threshold feedback

For issues on autothresholds, setting Bigeye Threshold Feedback to Anomalous or Normal when you close the work item tells Bigeye whether the alert was real, which trains future thresholds. It
also flows the other way: feedback given in Bigeye is written to the field.

Merged issues

When Bigeye merges issues into an incident, the incident gets its own work item — tagged Bigeye; Incident — and each merged issue's work item is linked to it as Related, visible under the work
item's Links tab (Azure DevOps shows this as Related Work). Unmerging removes just that link.

An issue that has no work item of its own is not given one at merge time. Only issues already synced to
Azure Boards are linked.

Troubleshooting

Work items are not being created. Bigeye's Create ticket action is synchronous — if it reports a
failure, the work item was not created. The usual cause is a missing field from Step 2, or Bigeye
pointing at a work item type that does not have those fields.

Changes in Azure Boards do not reach Bigeye. Check Project Settings → Service Hooks:

• If a subscription shows Enabled (restricted), it is on probation after repeated delivery
  failures, and Azure DevOps is discarding new events. Re-saving in Project Settings → Bigeye
  recreates the subscriptions and clears it.
• If it shows Disabled, re-enable it there.
• Select a subscription and choose History to see each delivery, including Bigeye's response. That
  response usually says exactly what was wrong.

A work item says it is not linked to a Bigeye issue. Its Bigeye Issue ID field is empty — most
often because the work item was copied or cloned, or the field was cleared. Other work items are
unaffected.

Changes to work items Bigeye did not create. These are ignored. The subscriptions deliberately
listen to every work item in the project, and Bigeye skips anything without a Bigeye Issue ID.