Module: template_set

API address: /api/template_sets

Functionality for Template Sets. A Template Set is a list of Templates.

Module	Services	Data types	Constants
template_set	TemplateSetService acquireLock addTemplate addTemplateSet archive beginReview create endReview fetch fetchUpdated forceAcquireLock getPublicVersion getTags moveTemplate publish publishVersion query queryCombined removeTemplate setTemplateList unarchive update updateAttribute updateTags	TemplateSet TemplateSetCounts TemplateSetFetchResult TemplateSetParams TemplateSetQueryResult TemplateSetSelectOpts TemplateUnion TemplateUnionFetchResult TemplateUnionQueryResult TemplateUnionSelectOpts TemplateUnionWhereOpts VersionRef

Data structures

Struct: TemplateSetParams

Key	Field	Type	Description	Requiredness
1	title	`string`	Name of the template set	optional
2	descrip	`string`	Description of the template set	optional
3	typ	`job_template.TemplateType`	* Set the type of the template set. * It can either contain job or issue templates. *	optional

Mutable parts of the job template

Struct: TemplateSetCounts

Key	Field	Type	Description	Requiredness	Default value
1	completedJobs	`i32`		default
2	activeJobs	`i32`		default

Struct: TemplateSet

Key	Field	Type	Description	Requiredness
1	id	`string`		default
2	internalVersion	`i32`	Only increments when update is called.	default
3	publicVersion	`i32`	Increment logic for `publicVersion`: Normal team flow: 1. A new template set is created with create, initially `publicVersion=0` and `status=Unpublished`. 2. `publicVersion` increments by 1 from latest published `publicVersion` when publish is called, and `status=Published`. 3. When a new edit is made with update on either published or unpublished template set, a new entry is created with `publicVersion=0` and `status=Unpublished`. 4. Repeat from step 2) or 3). Review team flow: 1. A new template set is created with create, initially `publicVersion=0` and `status=Unpublished`. 2. `publicVersion` increments by 1 from max `publicVersion` when beginReview is called, and `status=InReview`. `publicVersion` does not change if this `internalVersion` has already been reviewed before, i.e., `publicVersion != 0`. 3. endReview must be called next to close review, making `status=Unpublished`. 4. A specific `publicVersion` must be used to call publishVersion and make `status=Published`. 5. When a new edit is made with update on either published or unpublished template set, a new entry is created with `publicVersion=0` and `status=Unpublished`. 6. Repeat from step 2) or 5).	default
4	title	`string`		default
5	descrip	`string`	Description	default
6	status	`job_template.JobTemplateStatus`		default
7	teamId	`string`		default
8	lastAuthoredAt	`i64`	authored time for this edit	default
9	publishedAt	`i64`	published time for this edit, 0 if not published	default
10	archivedAt	`i64`	archive time, 0 means the template set is not archived	default
11	lastAuthorId	`string`		default
12	lock	`job_template.JobTemplateLock`	Status of lock by another user. Internal authoring lock	optional
13	publishedVersion	`i32`	Only increments when publish or publishVersion is called. Is the same as `publicVersion` for normal teams, and only increments on publish for review teams. Is 0 for all template sets with `status!=Published`.	default
14	typ	`job_template.TemplateType`		default
15	publishedById	`string`		optional
101	team	`team.TeamModular`		optional
102	lastPublishedAt	`i64`	last published time for this template set. 0 if not published	optional
103	lastAuthor	`user.UserModular`		optional
104	templates	`list<job_template.JobTemplateModular>`		optional
105	counts	`TemplateSetCounts`		optional
106	templateTags	`list<job_template.TemplateTag>`		optional
107	lastPublishedVersion	`i32`	last published version (public version) for this template set. 0 if not published	optional
108	lastModifiedAt	`i64`	Bumps up on edit, status change, archive	optional
109	attributes	`list<abac.AbacAttribute>`		optional
110	originalAuthor	`user.UserModular`		optional
111	lastPublishedBy	`user.User`		optional

Struct: TemplateSetSelectOpts

Key	Field	Type	Description	Requiredness
1	includeTeam	`bool`		default
2	includeLastPublished	`bool`	includes both lastPublishedAt and lastPublishedVersion	default
3	includeLastAuthor	`bool`		default
4	includeTemplates	`bool`		default
5	includeTags	`bool`		default
6	includeCounts	`bool`		default
7	includeLastModified	`bool`		default
8	includeAttributes	`bool`		default
9	includeOriginalAuthor	`bool`		default

Union: TemplateSetFetchResult

Key	Field	Type	Description	Requiredness	Default value
1	templateSet	`TemplateSet`		default
2	err	`common.SystemException`		default

Struct: TemplateSetQueryResult

Key	Field	Type	Description	Requiredness	Default value
1	templateSets	`list<TemplateSet>`		default
2	pageInfo	`common.PageInfo`		optional

Union: TemplateUnion

Key	Field	Type	Description	Requiredness	Default value
1	templateSet	`TemplateSet`		default
2	template	`job_template.JobTemplateModular`		default

Struct: TemplateUnionQueryResult

Key	Field	Type	Description	Requiredness	Default value
1	templateUnions	`list<TemplateUnion>`		default
2	pageInfo	`common.PageInfo`		optional

Struct: TemplateUnionFetchResult

Key	Field	Type	Description	Requiredness	Default value
1	templateResult	`map<string, job_template.TemplateFetchResult>`		default
2	templateSetResult	`map<string, TemplateSetFetchResult>`		default

Struct: TemplateUnionWhereOpts

Key	Field	Type	Requiredness	Default value
1	whereOpts	`job_template.TemplateWhereOpts`	default
2	includeTemplates	`bool`	default	`true`
3	includeTemplateSets	`bool`	default	`true`

Filtering options to be passed to queryCombined

Struct: TemplateUnionSelectOpts

Key	Field	Type	Description	Requiredness	Default value
1	templateSetSelectOpts	`TemplateSetSelectOpts`		default
2	templateSelectOpts	`job_template.TemplateSelectOpts`		default

Struct: VersionRef

Key	Field	Type	Requiredness
1	id	`string`	default
2	publicVersion	`i32`	default
3	isArchived	`bool`	default

Services

Service: TemplateSetService

Function: TemplateSetService.query

TemplateSetQueryResult query(TemplateSetSelectOpts selectOpts,
                             job_template.TemplateWhereOpts whereOpts,
                             list<job_template.TemplateOrder> order)
    throws common.SystemException

Query a list of template sets

Function: TemplateSetService.fetch

map<string, TemplateSetFetchResult> fetch(TemplateSetSelectOpts selectOpts,
                                        list<string> templateSetIds)
    throws common.SystemException

Get a template set

Function: TemplateSetService.create

TemplateSet create(string teamId,
                   TemplateSetParams params,
                   list<abac.AbacAttribute> attributes)
    throws common.SystemException

Function: TemplateSetService.update

TemplateSet update(string templateSetId,
                   i32 internalVersion,
                   TemplateSetParams params)
    throws common.SystemException

Function: TemplateSetService.archive

TemplateSet archive(string templateSetId)
    throws common.SystemException

Function: TemplateSetService.unarchive

TemplateSet unarchive(string templateSetId)
    throws common.SystemException

Function: TemplateSetService.publish

TemplateSet publish(string templateSetId)
    throws common.SystemException

Function: TemplateSetService.getPublicVersion

TemplateSet getPublicVersion(string templateSetId,
                             i32 publicVersion)
    throws common.SystemException

Get a published TemplateSet.

If publicVersion is 0, get the currently published version

Function: TemplateSetService.beginReview

i32 beginReview(string templateSetId)
    throws common.SystemException

Enter review state, which means that editing will be locked until the review process ends; also generates a new public version number which is returned. When configured, this will also call a registered webhook.

During review state, all operations which add or update content will fail with an error.

Function: TemplateSetService.endReview

i32 endReview(string templateSetId)
    throws common.SystemException

Exit review state, release editing lock; returns current public version number.

Function: TemplateSetService.publishVersion

TemplateSet publishVersion(string templateSetId,
                           i32 publicVersion)
    throws common.SystemException

Publish a specified version of the template set; must be called AFTER endReview

Function: TemplateSetService.addTemplate

TemplateSet addTemplate(string templateSetId,
                        i32 internalVersion,
                        string templateId,
                        i32 position,
                        bool replace)
    throws common.SystemException

Function: TemplateSetService.addTemplateSet

TemplateSet addTemplateSet(string templateSetId,
                           i32 internalVersion,
                           string addedSetId,
                           i32 position)
    throws common.SystemException

Function: TemplateSetService.moveTemplate

TemplateSet moveTemplate(string templateSetId,
                         i32 internalVersion,
                         string templateId,
                         i32 oldPosition,
                         i32 newPosition)
    throws common.SystemException

Move a template to a different position in the template set

Function: TemplateSetService.removeTemplate

TemplateSet removeTemplate(string templateSetId,
                           i32 internalVersion,
                           string templateId,
                           i32 position)
    throws common.SystemException

Remove a template from the template set

Function: TemplateSetService.setTemplateList

TemplateSet setTemplateList(string templateSetId,
                            i32 internalVersion,
                            list<common.ListActions> movements)
    throws common.SystemException

Set full list of templates on a template set. This replaces the need for consecutive api calls when moving, removing, and adding templates

Function: TemplateSetService.getTags

list<job_template.TemplateTag> getTags(string templateSetId)
    throws common.SystemException

Get all of the tags and comments for a template set

Function: TemplateSetService.updateTags

void updateTags(string templateSetId,
                list<job_template.TemplateTag> added,
                list<string> removedTagIds)
    throws common.SystemException

Update the tags on a template set. additions are the tags and comments to be added to the template. Removals are the ids of the tags to be removed from the template.

Function: TemplateSetService.acquireLock

job_template.JobTemplateLock acquireLock(string templateSetId)
    throws common.SystemException, job_template.JobTemplateLockFailed

Start editing the template set Note that this lock is associated with the specific authToken used, not just the user owning that token. The life of the lock is until releaseLock (which should be called when editing is complete), forcible takeover, or implicitly on logout. Returns the new lock on success. If the lock is already owned by another token, raises JobTemplateLockFailed with previous lock information.

Function: TemplateSetService.forceAcquireLock

job_template.ForceAcquireResponse forceAcquireLock(string templateSetId)
    throws common.SystemException

Start editing the template, forcibly taking over any existing lock. Note that this lock is associated with the specific authToken used, not just the user owning that token. The life of the lock is until releaseLock (which should be called when editing is complete), forcible takeover, or implicitly on logout. Returns the new lock in the response structure. If the lock was owned by another token, also returns details of previous lock. This method is intended to be called after acquireLock fails and an explicit user response to forcibly take the lock. WARNING: this could result in data loss if another user is editing.

Function: TemplateSetService.queryCombined

TemplateUnionQueryResult queryCombined(TemplateUnionSelectOpts selectOpts,
                                       TemplateUnionWhereOpts whereOpts,
                                       list<job_template.TemplateOrder> order)
    throws common.SystemException

Query across both templates and template sets.

Function: TemplateSetService.fetchUpdated

TemplateUnionFetchResult fetchUpdated(TemplateUnionSelectOpts selectOpts,
                                      list<VersionRef> templateArgs,
                                      list<VersionRef> templateSetArgs)
    throws common.SystemException

Only returns back templates and sets where either the version or the archivedAt timestamps don't match To figure out if you have the latest versions of the templates inside the template sets, pass those along in the templateArgs

Function: TemplateSetService.updateAttribute

list<abac.AbacAttribute> updateAttribute(common.UUID templateSetId,
                                         string attributeId,
                                         list<abac.AbacAttributeValue> values,
                                         abac.AbacUploadBehaviour behave)
    throws common.SystemException

Update a single attribute on a template set return value will always be a list with a single attribute determined by which attribute was updated param templateSetId: template set to update param attributeId: the AttributeId of the team level attribute to be updated param values: the new AttributeValues to associated with Attribute attributeId on template set templateSetId param behave: determine the behaviour of the endpoint, merge or clobber. Default: clobber