Records - Update

Service:: Distributed Task

API Version:: 7.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

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' to use this version of the api.

Request Body

Name	Type	Description
count	integer (int32)	The number of serialized items.
value	string (T)	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

{
  "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

Object

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

Enumeration

The type (error, warning) of the issue.

Value	Description
error
warning

JObject

Object

Represents a JSON object.

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

TaskLogReference

Object

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 (int32)	The ID of the task log.
location	string	The REST URL of the task log.

TaskReference

Object

A reference to a task.

Name	Type	Description
id	string (uuid)	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

Enumeration

Value	Description
succeeded
succeededWithIssues
failed
canceled
skipped
abandoned

TimelineAttempt

Object

An attempt to update a TimelineRecord.

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

TimelineRecord

Object

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 (int32)	The number of record attempts.
changeId	integer (int32)	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 (int32)	The number of errors produced by this operation.
finishTime	string (date-time)	The finish time of the record.
id	string (uuid)	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 (date-time)	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 (int32)	An ordinal value relative to other records within the timeline.
parentId	string (uuid)	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 (int32)	The percentage of record completion.
previousAttempts	TimelineAttempt[]	The previous record attempts.
queueId	integer (int32)	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 (date-time)	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 (int32)	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

Enumeration

The state of the record.

Value	Description
pending
inProgress
completed

TimelineReference

Object

A reference to a timeline.

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

VariableValue

Object

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

Object

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

Name	Type	Description
count	integer (int32)	The number of serialized items.
value	string (T)	The serialized item.

Share via

Records - Update

URI Parameters

Request Body

Responses

Security

accessToken

Examples

Update timeline's records

Sample request

Sample response

Definitions

Issue

IssueType

JObject

TaskLogReference

TaskReference

TaskResult

TimelineAttempt

TimelineRecord

TimelineRecordState

TimelineReference

VariableValue

VssJsonCollectionWrapper