Records - Update

Reference

Service:: Distributed Task

API Version:: 7.1-preview.1

Update timeline records if they already exist, otherwise create new ones for the same timeline.

PATCH https://dev.azure.com/{organization}/{scopeIdentifier}/_apis/distributedtask/hubs/{hubName}/plans/{planId}/timelines/{timelineId}/records?api-version=7.1-preview.1

URI Parameters

Name	In	Required	Type	Description
hubName	path	True	string	The name of the server hub. Common examples: "build", "rm", "checks"
organization	path	True	string	The name of the Azure DevOps organization.
planId	path	True	string uuid	The ID of the plan.
scopeIdentifier	path	True	string uuid	The project GUID to scope the request
timelineId	path	True	string uuid	The ID of the timeline.
api-version	query	True	string	Version of the API to use. This should be set to '7.1-preview.1' to use this version of the api.

Request Body

Name	Type	Description
count	integer	The number of serialized items.
value	string	The serialized item.

Responses

Name	Type	Description
200 OK	TimelineRecord[]	successful operation

Security

accessToken

Personal access token. Use any value for the user name and the token as the password.

Type: basic

Examples

Update timeline's records

Sample Request

HTTP

PATCH https://dev.azure.com/{organization}/{scopeIdentifier}/_apis/distributedtask/hubs/{hubName}/plans/{planId}/timelines/{timelineId}/records?api-version=7.1-preview.1

{
  "value": [
    {
      "id": "5e6d5dbf-ac69-5f56-8b85-8e9038703a8b",
      "parentId": null,
      "type": null,
      "name": null,
      "startTime": null,
      "finishTime": null,
      "currentOperation": null,
      "percentComplete": null,
      "state": null,
      "result": null,
      "resultCode": null,
      "changeId": 0,
      "lastModified": "0001-01-01T00:00:00",
      "workerName": null,
      "log": {
        "path": "logs\\5e6d5dbf-ac69-5f56-8b85-8e9038703a8b",
        "createdOn": "0001-01-01T00:00:00",
        "lastChangedOn": "0001-01-01T00:00:00",
        "id": 0,
        "location": null
      },
      "details": null,
      "errorCount": null,
      "warningCount": null,
      "location": null,
      "attempt": 1,
      "identifier": null
    }
  ],
  "count": 1
}

Sample Response

Status code:: 200

{
  "count": 1,
  "value": [
    {
      "id": "5e6d5dbf-ac69-5f56-8b85-8e9038703a8b",
      "parentId": "096e11e7-c8bb-5a90-1a73-4e639c9ea0f9",
      "type": "Task",
      "name": "Invoke REST API",
      "startTime": "2022-12-02T09:33:15.0466667Z",
      "finishTime": "2022-12-02T09:37:37.8433333Z",
      "currentOperation": null,
      "percentComplete": null,
      "state": "completed",
      "result": "succeeded",
      "resultCode": null,
      "changeId": 13,
      "lastModified": "0001-01-01T00:00:00",
      "workerName": null,
      "order": 1,
      "refName": "InvokeRESTAPI0",
      "log": {
        "id": 0,
        "location": "https://dev.azure.com/fabrikam/_apis/distributedtask/plans/787562d7-f1da-59cf-22c4-8a94fa784503/logs/0"
      },
      "details": null,
      "errorCount": 0,
      "warningCount": 0,
      "task": {
        "id": "9c3e8943-130d-4c78-ac63-8af81df62dfb",
        "name": "InvokeRESTAPI",
        "version": "1.198.0"
      },
      "location": "https://dev.azure.com/fabrikam/_apis/distributedtask/plans/787562d7-f1da-59cf-22c4-8a94fa784503/timelines/787562d7-f1da-59cf-22c4-8a94fa784503/records/5e6d5dbf-ac69-5f56-8b85-8e9038703a8b",
      "attempt": 1,
      "identifier": null
    }
  ]
}

Definitions

Name	Description
Issue	An issue (error, warning) associated with a pipeline run.
IssueType	The type (error, warning) of the issue.
JObject	Represents a JSON object.
TaskLogReference	A reference to a task log. This class contains information about the output printed to the timeline record's logs console during pipeline run.
TaskReference	A reference to a task.
TaskResult
TimelineAttempt	An attempt to update a TimelineRecord.
TimelineRecord	Detailed information about the execution of different operations during pipeline run.
TimelineRecordState	The state of the record.
TimelineReference	A reference to a timeline.
VariableValue	A wrapper class for a generic variable.
VssJsonCollectionWrapper	This class is used to serialize collections as a single JSON object on the wire.

Issue

An issue (error, warning) associated with a pipeline run.

Name	Type	Description
category	string	The category of the issue. Example: Code - refers to compilation errors Example: General - refers to generic errors
data	object	A dictionary containing details about the issue.
message	string	A description of issue.
type	IssueType	The type (error, warning) of the issue.

IssueType

The type (error, warning) of the issue.

Name	Type	Description
error	string
warning	string

JObject

Represents a JSON object.

Name	Type	Description
item	string
type	string	Gets the node type for this JToken.

TaskLogReference

A reference to a task log. This class contains information about the output printed to the timeline record's logs console during pipeline run.

Name	Type	Description
id	integer	The ID of the task log.
location	string	The REST URL of the task log.

TaskReference

A reference to a task.

Name	Type	Description
id	string	The ID of the task definition. Corresponds to the id value of task.json file. Example: CmdLineV2 { "id": "D9BAFED4-0B18-4F58-968D-86655B4D2CE9" }
inputs	object	A dictionary of inputs specific to a task definition. Corresponds to inputs value of task.json file.
name	string	The name of the task definition. Corresponds to the name value of task.json file. Example: CmdLineV2 { "name": "CmdLine" }
version	string	The version of the task definition. Corresponds to the version value of task.json file. Example: CmdLineV2 { "version": { "Major": 2, "Minor": 212, "Patch": 0 } }

TaskResult

Name	Type	Description
abandoned	string
canceled	string
failed	string
skipped	string
succeeded	string
succeededWithIssues	string

TimelineAttempt

An attempt to update a TimelineRecord.

Name	Type	Description
attempt	integer	The attempt of the record.
identifier	string	The unique identifier for the record.
recordId	string	The record identifier located within the specified timeline.
timelineId	string	The timeline identifier which owns the record representing this attempt.

TimelineRecord

Detailed information about the execution of different operations during pipeline run.

Name	Type	Description
agentSpecification	JObject	The specification of an agent running a pipeline job, in binary format. Applicable when record is of type Job. Example: { "VMImage" : "windows-2019" }
attempt	integer	The number of record attempts.
changeId	integer	The ID connecting all records updated at the same time. This value is taken from timeline's ChangeId.
currentOperation	string	A string that indicates the current operation.
details	TimelineReference	A reference to a sub-timeline.
errorCount	integer	The number of errors produced by this operation.
finishTime	string	The finish time of the record.
id	string	The ID of the record.
identifier	string	String identifier that is consistent across attempts.
issues	Issue[]	The list of issues produced by this operation.
lastModified	string	The time the record was last modified.
location	string	The REST URL of the record.
log	TaskLogReference	A reference to the log produced by this operation.
name	string	The name of the record.
order	integer	An ordinal value relative to other records within the timeline.
parentId	string	The ID of the record's parent. Example: Stage is a parent of a Phase, Phase is a parent of a Job, Job is a parent of a Task.
percentComplete	integer	The percentage of record completion.
previousAttempts	TimelineAttempt[]	The previous record attempts.
queueId	integer	The ID of the queue which connects projects to agent pools on which the operation ran on. Applicable when record is of type Job.
refName	string	Name of the referenced record.
result	TaskResult	The result of the record.
resultCode	string	Evaluation of predefined conditions upon completion of record's operation. Example: Evaluating `succeeded()`, Result = True Example: Evaluating `and(succeeded(), eq(variables['system.debug'], False))`, Result = False
startTime	string	The start time of the record.
state	TimelineRecordState	The state of the record.
task	TaskReference	A reference to the task. Applicable when record is of type Task.
type	string	The type of operation being tracked by the record. Example: Stage, Phase, Job, Task...
variables	<string, VariableValue>	The variables of the record.
warningCount	integer	The number of warnings produced by this operation.
workerName	string	The name of the agent running the operation. Applicable when record is of type Job.

TimelineRecordState

The state of the record.

Name	Type	Description
completed	string
inProgress	string
pending	string

TimelineReference

A reference to a timeline.

Name	Type	Description
changeId	integer	The change ID.
id	string	The ID of the timeline.
location	string	The REST URL of the timeline.

VariableValue

A wrapper class for a generic variable.

Name	Type	Description
isReadOnly	boolean	Indicates whether the variable can be changed during script's execution runtime.
isSecret	boolean	Indicates whether the variable should be encrypted at rest.
value	string	The value of the variable.

VssJsonCollectionWrapper

This class is used to serialize collections as a single JSON object on the wire.

Name	Type	Description
count	integer	The number of serialized items.
value	string	The serialized item.