devops_utils.core.azure_devops.bulk module

Bulk work-item operations driven by a declarative plan.

A plan is a YAML/JSON document describing a batch of work-item writes — creates, updates, links, comments — applied in order with local ref: cross-references so a child can be parented to an item created earlier in the same run. The schema is deliberately loose: beyond the small set of named keys below, any work-item field (process-specific or Custom.*) goes through the free-form fields map untouched, so callers are never limited to what this module names explicitly.

Plan shape:

project: Contoso              # default project for every item (optional)
defaults:                     # merged into every item; the item wins
  type: User Story
  area_path: Contoso\Payments
  fields:
    Custom.Source: git-history
items:
  - ref: feat-checkout        # local handle other items can point at
    type: Feature
    title: Guest checkout
    description: "<p>…</p>"   # HTML
    state: Closed             # applied via a follow-up patch on create
    assigned_to: dev@contoso.com
    tags: [checkout]
    area_path: …
    iteration_path: …
    fields:                   # ANY reference name passes through as-is
      Microsoft.VSTS.Scheduling.TargetDate: 2026-08-31
      Custom.RiskLevel: High
    links:
      - {kind: commit, value: 3f2a91c, repo: web-app}
      - {kind: hyperlink, value: "https://…"}
    comments:
      - Imported from git history.
  - ref: story-1
    type: User Story
    title: Pay without an account
    parent: ref:feat-checkout # or a real work-item id
  - id: 1421                  # an existing item → update
    state: Active
    fields: {Custom.RiskLevel: Low}

Rules:

• An item with id is an update; without it, a create (type and title required). action: create|update may be given explicitly and is validated against the presence of id.

• parent and the value of work-item link kinds (parent, child, work_item, predecessor, successor) accept ref:<name> — the referenced item must appear earlier in items.

• Unknown item keys are collected as warnings, not errors: a typo should be visible in the review window without making user extensions impossible.

• All links of an item are sent in a single JSON-patch request.

devops_utils.core.azure_devops.bulk.KNOWN_ITEM_KEYS = ('ref', 'action', 'id', 'project', 'type', 'title', 'description', 'state', 'assigned_to', 'tags', 'area_path', 'iteration_path', 'parent', 'fields', 'links', 'comments')

Item keys this module interprets. Everything else is warned about; arbitrary fields belong under the free-form fields map.

exception devops_utils.core.azure_devops.bulk.PlanError

Bases: ValueError

A plan failed validation; the message lists every problem found.

devops_utils.core.azure_devops.bulk.apply_plan(client: AzureDevOpsClient, plan: dict[str, Any], *, stop_on_error: bool = False) → list[dict[str, Any]]

Apply a validated plan sequentially and return per-item results.

Each result is {"ref", "action", "status", "id", "url"} with status one of created/updated/failed (plus "error" when failed). A failed item never stops ref resolution bookkeeping; later items parented to it fail with a clear message instead of mis-parenting.

Parameters:

stop_on_error – When true, stop at the first failed item (already applied items stay applied — there is no rollback).

devops_utils.core.azure_devops.bulk.load_plan(text: str) → dict[str, Any]

Parse a YAML (or JSON — a YAML subset) plan document.

devops_utils.core.azure_devops.bulk.plan_preview(items: list[dict[str, Any]]) → list[dict[str, Any]]

Summarize normalized items for the human review window (no requests).

devops_utils.core.azure_devops.bulk.validate_plan(plan: dict[str, Any]) → tuple[list[dict[str, Any]], list[str]]

Normalize and validate a plan.

Merges defaults into every item (item values win; the two fields maps are merged key-wise), resolves the effective project, and checks ordering of ref: references.

Returns:

(items, warnings) — the normalized items in application order and human-readable warnings (unknown keys, …) for the review window.

Raises:

PlanError – With every hard problem found, one per line.