Templates - Save Template

Updates an existing build definition template.

PUT https://dev.azure.com/{organization}/{project}/_apis/build/definitions/templates/{templateId}?api-version=5.0

URI Parameters

Name In Required Type Description
organization
path True

string

The name of the Azure DevOps organization.

project
path True

string

Project ID or project name

templateId
path True

string

The ID of the template.

api-version
query True

string

Version of the API to use. This should be set to '5.0' to use this version of the api.

Request Body

Name Type Description
canDelete

boolean

Indicates whether the template can be deleted.

category

string

The template category.

defaultHostedQueue

string

An optional hosted agent queue for the template to use by default.

description

string

A description of the template.

iconTaskId

string

The ID of the task whose icon is used when showing this template in the UI.

icons

object

id

string

The ID of the template.

name

string

The name of the template.

template

BuildDefinition

The actual template.

Responses

Name Type Description
200 OK

BuildDefinitionTemplate

successful operation

Security

oauth2

Type: oauth2
Flow: accessCode
Authorization URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token URL: https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

Scopes

Name Description
vso.build_execute Grants the ability to access build artifacts, including build results, definitions, and requests, and the ability to queue a build, update build properties, and the ability to receive notifications about build events via service hooks.

Definitions

Name Description
AgentPoolQueue

Represents a queue for running builds.

AuthorizationHeader
Build

Data representation of a build.

BuildAuthorizationScope

The job authorization scope for builds queued against this definition.

BuildController
BuildDefinition

Represents a build definition.

BuildDefinitionTemplate

Represents a template from which new build definitions can be created.

BuildDefinitionVariable

Represents a variable used by a build definition.

BuildLogReference

Represents a reference to a build log.

BuildMetric

Represents metadata about builds in the system.

BuildOption

Represents the application of an optional behavior to a build definition.

BuildOptionDefinitionReference

Represents a reference to a build option definition.

BuildProcess

Represents a build process.

BuildReason

The reason that the build was created.

BuildRepository

Represents a repository used by a build definition.

BuildRequestValidationResult

Represents the result of validating a build request.

BuildResult

The build result.

BuildStatus

The build status.

BuildTrigger

Represents a trigger for a buld definition.

ControllerStatus

The status of the controller.

DataSourceBindingBase

Represents binding of data source for the service endpoint request.

DefinitionQuality

The quality of the definition document (draft, etc.)

DefinitionQueueStatus

A value that indicates whether builds can be queued against this definition.

DefinitionReference

Represents a reference to a definition.

DefinitionTriggerType

The type of the trigger.

DefinitionType

The type of the definition.

Demand

Represents a demand used by a definition or build.

IdentityRef
ProcessParameters
ProjectState

Project state.

ProjectVisibility

Project visibility.

PropertiesCollection

The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a TypeCode != TypeCode.Object) except for DBNull are accepted. Values of type Byte[], Int32, Double, DateType and String preserve their type, other primitives are retuned as a String. Byte[] expected as base64 encoded string.

QueueOptions

Additional options for queueing the build.

QueuePriority

The build's priority.

ReferenceLinks

The class to represent a collection of REST reference links.

RetentionPolicy

Represents a retention policy for a build definition.

TaskAgentPoolReference

Represents a reference to an agent pool.

TaskInputDefinitionBase
TaskInputValidation
TaskOrchestrationPlanReference

Represents a reference to an orchestration plan.

TaskSourceDefinitionBase
TeamProjectReference

Represents a shallow reference to a TeamProject.

ValidationResult

The result.

VariableGroup

Represents a variable group.

AgentPoolQueue

Represents a queue for running builds.

Name Type Description
_links

ReferenceLinks

The class to represent a collection of REST reference links.

id

integer

The ID of the queue.

name

string

The name of the queue.

pool

TaskAgentPoolReference

The pool used by this queue.

url

string

The full http link to the resource.

AuthorizationHeader

Name Type Description
name

string

value

string

Build

Data representation of a build.

Name Type Description
_links

ReferenceLinks

The class to represent a collection of REST reference links.

buildNumber

string

The build number/name of the build.

buildNumberRevision

integer

The build number revision.

controller

BuildController

The build controller. This is only set if the definition type is Xaml.

definition

DefinitionReference

The definition associated with the build.

deleted

boolean

Indicates whether the build has been deleted.

deletedBy

IdentityRef

The identity of the process or person that deleted the build.

deletedDate

string

The date the build was deleted.

deletedReason

string

The description of how the build was deleted.

demands

Demand[]

A list of demands that represents the agent capabilities required by this build.

finishTime

string

The time that the build was completed.

id

integer

The ID of the build.

keepForever

boolean

Indicates whether the build should be skipped by retention policies.

lastChangedBy

IdentityRef

The identity representing the process or person that last changed the build.

lastChangedDate

string

The date the build was last changed.

logs

BuildLogReference

Information about the build logs.

orchestrationPlan

TaskOrchestrationPlanReference

The orchestration plan for the build.

parameters

string

The parameters for the build.

plans

TaskOrchestrationPlanReference[]

Orchestration plans associated with the build (build, cleanup)

priority

QueuePriority

The build's priority.

project

TeamProjectReference

The team project.

properties

PropertiesCollection

The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a TypeCode != TypeCode.Object) except for DBNull are accepted. Values of type Byte[], Int32, Double, DateType and String preserve their type, other primitives are retuned as a String. Byte[] expected as base64 encoded string.

quality

string

The quality of the xaml build (good, bad, etc.)

queue

AgentPoolQueue

The queue. This is only set if the definition type is Build.

queueOptions

QueueOptions

Additional options for queueing the build.

queuePosition

integer

The current position of the build in the queue.

queueTime

string

The time that the build was queued.

reason

BuildReason

The reason that the build was created.

repository

BuildRepository

The repository.

requestedBy

IdentityRef

The identity that queued the build.

requestedFor

IdentityRef

The identity on whose behalf the build was queued.

result

BuildResult

The build result.

retainedByRelease

boolean

Indicates whether the build is retained by a release.

sourceBranch

string

The source branch.

sourceVersion

string

The source version.

startTime

string

The time that the build was started.

status

BuildStatus

The status of the build.

tags

string[]

triggerInfo

object

Sourceprovider-specific information about what triggered the build

triggeredByBuild

Build

The build that triggered this build via a Build completion trigger.

uri

string

The URI of the build.

url

string

The REST URL of the build.

validationResults

BuildRequestValidationResult[]

Represents the result of validating a build request.

BuildAuthorizationScope

The job authorization scope for builds queued against this definition.

Name Type Description
project

string

The identity used should have build service account permissions scoped to the project in which the build definition resides. This is useful for isolation of build jobs to a particular team project to avoid any unintentional escalation of privilege attacks during a build.

projectCollection

string

The identity used should have build service account permissions scoped to the project collection. This is useful when resources for a single build are spread across multiple projects.

BuildController

Name Type Description
_links

ReferenceLinks

The class to represent a collection of REST reference links.

createdDate

string

The date the controller was created.

description

string

The description of the controller.

enabled

boolean

Indicates whether the controller is enabled.

id

integer

Id of the resource

name

string

Name of the linked resource (definition name, controller name, etc.)

status

ControllerStatus

The status of the controller.

updatedDate

string

The date the controller was last updated.

uri

string

The controller's URI.

url

string

Full http link to the resource

BuildDefinition

Represents a build definition.

Name Type Description
_links

ReferenceLinks

The class to represent a collection of REST reference links.

authoredBy

IdentityRef

The author of the definition.

badgeEnabled

boolean

Indicates whether badges are enabled for this definition.

buildNumberFormat

string

The build number format.

comment

string

A save-time comment for the definition.

createdDate

string

The date the definition was created.

demands

Demand[]

Represents a demand used by a definition or build.

description

string

The description.

draftOf

DefinitionReference

A reference to the definition that this definition is a draft of, if this is a draft definition.

drafts

DefinitionReference[]

The list of drafts associated with this definition, if this is not a draft definition.

dropLocation

string

The drop location for the definition.

id

integer

The ID of the referenced definition.

jobAuthorizationScope

BuildAuthorizationScope

The job authorization scope for builds queued against this definition.

jobCancelTimeoutInMinutes

integer

The job cancel timeout (in minutes) for builds cancelled by user for this definition.

jobTimeoutInMinutes

integer

The job execution timeout (in minutes) for builds queued against this definition.

latestBuild

Build

Data representation of a build.

latestCompletedBuild

Build

Data representation of a build.

metrics

BuildMetric[]

Represents metadata about builds in the system.

name

string

The name of the referenced definition.

options

BuildOption[]

Represents the application of an optional behavior to a build definition.

path

string

The folder path of the definition.

process

BuildProcess

The build process.

processParameters

ProcessParameters

The process parameters for this definition.

project

TeamProjectReference

A reference to the project.

properties

PropertiesCollection

The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a TypeCode != TypeCode.Object) except for DBNull are accepted. Values of type Byte[], Int32, Double, DateType and String preserve their type, other primitives are retuned as a String. Byte[] expected as base64 encoded string.

quality

DefinitionQuality

The quality of the definition document (draft, etc.)

queue

AgentPoolQueue

The default queue for builds run against this definition.

queueStatus

DefinitionQueueStatus

A value that indicates whether builds can be queued against this definition.

repository

BuildRepository

The repository.

retentionRules

RetentionPolicy[]

Represents a retention policy for a build definition.

revision

integer

The definition revision number.

tags

string[]

triggers

BuildTrigger[]

Represents a trigger for a buld definition.

type

DefinitionType

The type of the definition.

uri

string

The definition's URI.

url

string

The REST URL of the definition.

variableGroups

VariableGroup[]

Represents a variable group.

variables

<string,  BuildDefinitionVariable>

BuildDefinitionTemplate

Represents a template from which new build definitions can be created.

Name Type Description
canDelete

boolean

Indicates whether the template can be deleted.

category

string

The template category.

defaultHostedQueue

string

An optional hosted agent queue for the template to use by default.

description

string

A description of the template.

iconTaskId

string

The ID of the task whose icon is used when showing this template in the UI.

icons

object

id

string

The ID of the template.

name

string

The name of the template.

template

BuildDefinition

The actual template.

BuildDefinitionVariable

Represents a variable used by a build definition.

Name Type Description
allowOverride

boolean

Indicates whether the value can be set at queue time.

isSecret

boolean

Indicates whether the variable's value is a secret.

value

string

The value of the variable.

BuildLogReference

Represents a reference to a build log.

Name Type Description
id

integer

The ID of the log.

type

string

The type of the log location.

url

string

A full link to the log resource.

BuildMetric

Represents metadata about builds in the system.

Name Type Description
date

string

The date for the scope.

intValue

integer

The value.

name

string

The name of the metric.

scope

string

The scope.

BuildOption

Represents the application of an optional behavior to a build definition.

Name Type Description
definition

BuildOptionDefinitionReference

A reference to the build option.

enabled

boolean

Indicates whether the behavior is enabled.

inputs

object

BuildOptionDefinitionReference

Represents a reference to a build option definition.

Name Type Description
id

string

The ID of the referenced build option.

BuildProcess

Represents a build process.

Name Type Description
type

integer

The type of the process.

BuildReason

The reason that the build was created.

Name Type Description
all

string

All reasons.

batchedCI

string

The build was started for the trigger TriggerType.BatchedContinuousIntegration.

buildCompletion

string

The build was started when another build completed.

checkInShelveset

string

The build was started for the trigger ContinuousIntegrationType.Gated.

individualCI

string

The build was started for the trigger TriggerType.ContinuousIntegration.

manual

string

The build was started manually.

none

string

No reason. This value should not be used.

pullRequest

string

The build was started by a pull request. Added in resource version 3.

schedule

string

The build was started for the trigger TriggerType.Schedule.

triggered

string

The build was triggered for retention policy purposes.

userCreated

string

The build was created by a user.

validateShelveset

string

The build was started manually for private validation.

BuildRepository

Represents a repository used by a build definition.

Name Type Description
checkoutSubmodules

boolean

Indicates whether to checkout submodules.

clean

string

Indicates whether to clean the target folder when getting code from the repository.

defaultBranch

string

The name of the default branch.

id

string

The ID of the repository.

name

string

The friendly name of the repository.

properties

object

rootFolder

string

The root folder.

type

string

The type of the repository.

url

string

The URL of the repository.

BuildRequestValidationResult

Represents the result of validating a build request.

Name Type Description
message

string

The message associated with the result.

result

ValidationResult

The result.

BuildResult

The build result.

Name Type Description
canceled

string

The build was canceled before starting.

failed

string

The build completed unsuccessfully.

none

string

No result

partiallySucceeded

string

The build completed compilation successfully but had other errors.

succeeded

string

The build completed successfully.

BuildStatus

The build status.

Name Type Description
all

string

All status.

cancelling

string

The build is cancelling

completed

string

The build has completed.

inProgress

string

The build is currently in progress.

none

string

No status.

notStarted

string

The build has not yet started.

postponed

string

The build is inactive in the queue.

BuildTrigger

Represents a trigger for a buld definition.

Name Type Description
triggerType

DefinitionTriggerType

The type of the trigger.

ControllerStatus

The status of the controller.

Name Type Description
available

string

Indicates that the build controller is currently available.

offline

string

Indicates that the build controller has taken itself offline.

unavailable

string

Indicates that the build controller cannot be contacted.

DataSourceBindingBase

Represents binding of data source for the service endpoint request.

Name Type Description
callbackContextTemplate

string

Pagination format supported by this data source(ContinuationToken/SkipTop).

callbackRequiredTemplate

string

Subsequent calls needed?

dataSourceName

string

Gets or sets the name of the data source.

endpointId

string

Gets or sets the endpoint Id.

endpointUrl

string

Gets or sets the url of the service endpoint.

headers

AuthorizationHeader[]

Gets or sets the authorization headers.

initialContextTemplate

string

Defines the initial value of the query params

parameters

object

Gets or sets the parameters for the data source.

resultSelector

string

Gets or sets the result selector.

resultTemplate

string

Gets or sets the result template.

target

string

Gets or sets the target of the data source.

DefinitionQuality

The quality of the definition document (draft, etc.)

Name Type Description
definition

string

draft

string

DefinitionQueueStatus

A value that indicates whether builds can be queued against this definition.

Name Type Description
disabled

string

When disabled the definition queue will not allow builds to be queued by users and the system will not queue scheduled, gated or continuous integration builds. Builds already in the queue will not be started by the system.

enabled

string

When enabled the definition queue allows builds to be queued by users, the system will queue scheduled, gated and continuous integration builds, and the queued builds will be started by the system.

paused

string

When paused the definition queue allows builds to be queued by users and the system will queue scheduled, gated and continuous integration builds. Builds in the queue will not be started by the system.

DefinitionReference

Represents a reference to a definition.

Name Type Description
createdDate

string

The date the definition was created.

id

integer

The ID of the referenced definition.

name

string

The name of the referenced definition.

path

string

The folder path of the definition.

project

TeamProjectReference

A reference to the project.

queueStatus

DefinitionQueueStatus

A value that indicates whether builds can be queued against this definition.

revision

integer

The definition revision number.

type

DefinitionType

The type of the definition.

uri

string

The definition's URI.

url

string

The REST URL of the definition.

DefinitionTriggerType

The type of the trigger.

Name Type Description
all

string

All types.

batchedContinuousIntegration

string

A build should be started for multiple changesets at a time at a specified interval.

batchedGatedCheckIn

string

A validation build should be started for each batch of check-ins.

buildCompletion

string

A build should be triggered when another build completes.

continuousIntegration

string

A build should be started for each changeset.

gatedCheckIn

string

A validation build should be started for each check-in.

none

string

Manual builds only.

pullRequest

string

A build should be triggered when a GitHub pull request is created or updated. Added in resource version 3

schedule

string

A build should be started on a specified schedule whether or not changesets exist.

DefinitionType

The type of the definition.

Name Type Description
build

string

xaml

string

Demand

Represents a demand used by a definition or build.

Name Type Description
name

string

The name of the capability referenced by the demand.

value

string

The demanded value.

IdentityRef

Name Type Description
_links

ReferenceLinks

This field contains zero or more interesting links about the graph subject. These links may be invoked to obtain additional relationships or more detailed information about this graph subject.

descriptor

string

The descriptor is the primary way to reference the graph subject while the system is running. This field will uniquely identify the same graph subject across both Accounts and Organizations.

directoryAlias

string

displayName

string

This is the non-unique display name of the graph subject. To change this field, you must alter its value in the source provider.

id

string

imageUrl

string

inactive

boolean

isAadIdentity

boolean

isContainer

boolean

isDeletedInOrigin

boolean

profileUrl

string

uniqueName

string

url

string

This url is the full route to the source resource of this graph subject.

ProcessParameters

Name Type Description
dataSourceBindings

DataSourceBindingBase[]

Represents binding of data source for the service endpoint request.

inputs

TaskInputDefinitionBase[]

sourceDefinitions

TaskSourceDefinitionBase[]

ProjectState

Project state.

Name Type Description
all

string

All projects regardless of state.

createPending

string

Project has been queued for creation, but the process has not yet started.

deleted

string

Project has been deleted.

deleting

string

Project is in the process of being deleted.

new

string

Project is in the process of being created.

unchanged

string

Project has not been changed.

wellFormed

string

Project is completely created and ready to use.

ProjectVisibility

Project visibility.

Name Type Description
private

string

The project is only visible to users with explicit access.

public

string

The project is visible to all.

PropertiesCollection

The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a TypeCode != TypeCode.Object) except for DBNull are accepted. Values of type Byte[], Int32, Double, DateType and String preserve their type, other primitives are retuned as a String. Byte[] expected as base64 encoded string.

Name Type Description
count

integer

The count of properties in the collection.

item

object

keys

string[]

The set of keys in the collection.

values

string[]

The set of values in the collection.

QueueOptions

Additional options for queueing the build.

Name Type Description
doNotRun

string

Create a plan Id for the build, do not run it

none

string

No queue options

QueuePriority

The build's priority.

Name Type Description
aboveNormal

string

Above normal priority.

belowNormal

string

Below normal priority.

high

string

High priority.

low

string

Low priority.

normal

string

Normal priority.

The class to represent a collection of REST reference links.

Name Type Description
links

object

The readonly view of the links. Because Reference links are readonly, we only want to expose them as read only.

RetentionPolicy

Represents a retention policy for a build definition.

Name Type Description
artifactTypesToDelete

string[]

artifacts

string[]

branches

string[]

daysToKeep

integer

The number of days to keep builds.

deleteBuildRecord

boolean

Indicates whether the build record itself should be deleted.

deleteTestResults

boolean

Indicates whether to delete test results associated with the build.

minimumToKeep

integer

The minimum number of builds to keep.

TaskAgentPoolReference

Represents a reference to an agent pool.

Name Type Description
id

integer

The pool ID.

isHosted

boolean

A value indicating whether or not this pool is managed by the service.

name

string

The pool name.

TaskInputDefinitionBase

Name Type Description
aliases

string[]

defaultValue

string

groupName

string

helpMarkDown

string

label

string

name

string

options

object

properties

object

required

boolean

type

string

validation

TaskInputValidation

visibleRule

string

TaskInputValidation

Name Type Description
expression

string

Conditional expression

message

string

Message explaining how user can correct if validation fails

TaskOrchestrationPlanReference

Represents a reference to an orchestration plan.

Name Type Description
orchestrationType

integer

The type of the plan.

planId

string

The ID of the plan.

TaskSourceDefinitionBase

Name Type Description
authKey

string

endpoint

string

keySelector

string

selector

string

target

string

TeamProjectReference

Represents a shallow reference to a TeamProject.

Name Type Description
abbreviation

string

Project abbreviation.

defaultTeamImageUrl

string

Url to default team identity image.

description

string

The project's description (if any).

id

string

Project identifier.

name

string

Project name.

revision

integer

Project revision.

state

ProjectState

Project state.

url

string

Url to the full version of the object.

visibility

ProjectVisibility

Project visibility.

ValidationResult

The result.

Name Type Description
error

string

oK

string

warning

string

VariableGroup

Represents a variable group.

Name Type Description
alias

string

The Name of the variable group.

description

string

The description.

id

integer

The ID of the variable group.

name

string

The name of the variable group.

type

string

The type of the variable group.

variables

<string,  BuildDefinitionVariable>