please provide a sample request for creating a work item, type is release.

Question

please provide the sample request for creating a work item with type as release, which can meet all the rule validations.

Answer 1

Hi @Chang, Linda ,

Thanks for reaching out to Microsoft Q&A.

Below is a sample REST API request (JSON-patch style) to create a new work item of type “Release” that includes all the usual required fields (title, area path, iteration path) plus a couple of common built-in fields.

You can tweak it to include any custom fields or relations your process enforces.

Sample HTTP request

POST https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/$Release?api-version=7.1-preview.3  

Headers:

• Content-Type: application/json-patch+json
• Authorization: Basic BASE64_PAT
• Request body (JSON-patch array):

[

  {

    "op": "add",

    "path": "/fields/System.Title",

    "value": "Release v1.2.0"

  },

  {

    "op": "add",

    "path": "/fields/System.Description",

    "value": "Deploying version 1.2.0 to production"

  },

  {

    "op": "add",

    "path": "/fields/System.AreaPath",

    "value": "ContosoProject\\Releases"

  },

  {

    "op": "add",

    "path": "/fields/System.IterationPath",

    "value": "ContosoProject\\Releases\\Sprint 23"

  },

  {

    "op": "add",

    "path": "/fields/Microsoft.VSTS.Common.Priority",

    "value": 2

  },

  {

    "op": "add",

    "path": "/fields/Custom.ReleaseDate",

    "value": "2024-07-15T10:00:00Z"

  },

  {

    "op": "add",

    "path": "/relations/-",

    "value": {

      "rel": "System.LinkTypes.Hierarchy-Reverse",

      "url": "https://dev.azure.com/{organization}/_apis/wit/workItems/123",

      "attributes": {

        "comment": "Parent release work item"

      }

    }

  }

]

Notes:

• Replace {organization}, {project} and the PAT placeholder with your values.
• Change or remove the custom field (Custom.ReleaseDate) to match your process rules.
• If your “Release” work‐item type has additional required fields, add them as more "add"/fields/... operations.

Alternatively, using the Azure CLI:

az boards work-item create \

  --title "Release v1.2.0" \

  --type Release \

  --area "ContosoProject\Releases" \

  --iteration "ContosoProject\Releases\Sprint 23" \

  --fields "System.Description=Deploying version 1.2.0 to production" \

           "Microsoft.VSTS.Common.Priority=2" \

           "Custom.ReleaseDate=2024-07-15T10:00:00Z" \

  --org https://dev.azure.com/{organization} \

  --project ContosoProject

Hope this helps!

---

If the resolution was helpful, kindly take a moment to click on and click on Yes for was this answer helpful. And, if you have any further query do let us know.

Answer 2

Use the Work Item Tracking REST API (or .NET client) to create a work item of type Release by sending a JSON Patch document that sets all required fields so that no rules are violated. The exact required fields and rule conditions depend on the process and custom rules configured in the project, but the request structure is as follows.

Example HTTP request (REST API) to create a Release work item:

POST https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/$Release?api-version=7.0
Content-Type: application/json-patch+json

[
  {
    "op": "add",
    "path": "/fields/System.Title",
    "from": null,
    "value": "Release 2024.04"
  },
  {
    "op": "add",
    "path": "/fields/System.Description",
    "from": null,
    "value": "Description of the release contents."
  },
  {
    "op": "add",
    "path": "/fields/Microsoft.VSTS.Common.Priority",
    "from": null,
    "value": 2
  },
  {
    "op": "add",
    "path": "/fields/Microsoft.VSTS.Scheduling.StartDate",
    "from": null,
    "value": "2024-04-10T00:00:00Z"
  },
  {
    "op": "add",
    "path": "/fields/Microsoft.VSTS.Scheduling.TargetDate",
    "from": null,
    "value": "2024-04-30T00:00:00Z"
  },
  {
    "op": "add",
    "path": "/fields/Custom.Approved",
    "from": null,
    "value": true
  },
  {
    "op": "add",
    "path": "/fields/Custom.ApprovedBy",
    "from": null,
    "value": "Release Manager"
  },
  {
    "op": "add",
    "path": "/fields/Custom.Risk",
    "from": null,
    "value": "Medium"
  },
  {
    "op": "add",
    "path": "/fields/Microsoft.VSTS.Scheduling.RemainingWork",
    "from": null,
    "value": 10
  },
  {
    "op": "add",
    "path": "/fields/Microsoft.VSTS.Scheduling.CompletedWork",
    "from": null,
    "value": 0
  }
]

Key points based on the rule engine and validations:

• Use the POST .../wit/workitems/$Release endpoint with Content-Type: application/json-patch+json.
• Each field is added via a JSON Patch operation (op: "add", path: "/fields/<refname>").
• To satisfy custom rules such as:
  • “When a value is defined for Priority, make Risk required” – include both Microsoft.VSTS.Common.Priority and the Custom.Risk field.
  • “When a change was made to Remaining Work, make Completed Work required” – include both Microsoft.VSTS.Scheduling.RemainingWork and Microsoft.VSTS.Scheduling.CompletedWork.
  • “When the value of Approved is True, make Approved By required” – include both Custom.Approved and Custom.ApprovedBy.
• Do not set bypassRules=true; rules must run to validate the work item.

Example using .NET WorkItemTrackingHttpClientBase.CreateWorkItemAsync:

using Microsoft.TeamFoundation.WorkItemTracking.WebApi;
using Microsoft.VisualStudio.Services.WebApi.Patch;
using Microsoft.VisualStudio.Services.WebApi.Patch.Json;

var document = new JsonPatchDocument
{
    new JsonPatchOperation
    {
        Operation = Operation.Add,
        Path = "/fields/System.Title",
        Value = "Release 2024.04"
    },
    new JsonPatchOperation
    {
        Operation = Operation.Add,
        Path = "/fields/Microsoft.VSTS.Common.Priority",
        Value = 2
    },
    new JsonPatchOperation
    {
        Operation = Operation.Add,
        Path = "/fields/Custom.Risk",
        Value = "Medium"
    },
    new JsonPatchOperation
    {
        Operation = Operation.Add,
        Path = "/fields/Microsoft.VSTS.Scheduling.RemainingWork",
        Value = 10d
    },
    new JsonPatchOperation
    {
        Operation = Operation.Add,
        Path = "/fields/Microsoft.VSTS.Scheduling.CompletedWork",
        Value = 0d
    },
    new JsonPatchOperation
    {
        Operation = Operation.Add,
        Path = "/fields/Custom.Approved",
        Value = true
    },
    new JsonPatchOperation
    {
        Operation = Operation.Add,
        Path = "/fields/Custom.ApprovedBy",
        Value = "Release Manager"
    }
};

var client = new WorkItemTrackingHttpClient(new Uri("https://dev.azure.com/{organization}"), credentials);

var workItem = await client.CreateWorkItemAsync(
    document,
    project: "{project}",
    type: "Release",
    validateOnly: false,
    bypassRules: false,
    suppressNotifications: false,
    userState: null,
    cancellationToken: CancellationToken.None);

To ensure all rule validations are met in a specific project:

1. Review the custom rules defined for the Release work item type in the process (for example, rules that make fields required based on other field values).
2. Include all required fields and any dependent fields in the JSON Patch document, following the patterns shown in the rule samples.
3. Call CreateWorkItemAsync or the REST endpoint with bypassRules set to false (or omitted) so the rule engine validates the request.

---

References:

• WorkItemTrackingHttpClientBase.CreateWorkItemAsync Method
• WorkItemTrackingHttpClient.CreateWorkItemBatchRequest Method
• Sample custom rule scenarios
• Add a rule to a work item type (Inheritance process)
• CreateProcessRuleRequest Class
• CreateProcessRuleRequest interface