Module: job_template

API address: /api/job_templates

Functionality for Job Templates. A Job Template is the template for a type of job or process or procedure, from which Job instances are created.

Module	Services	Data types	Constants
job_template	JobTemplateService acquireLock addDocument addStepGroupModular addStepModular archive beginReview cloneStepGroupModular cloneStepModular cloneTemplate create createLocalTemplate endReview fetch fetchPublicVersions fetchPublishedVersions forceAcquireLock getHistory getLatestVersions getPublicVersion moveStepGroupModular moveStepModular publish publishVersion query releaseLock removeDocument removeStepGroupModular removeStepModular revert unarchive update updateAttribute updateDocument updateMetadata	ForceAcquireResponse IndexOpts JobTemplate JobTemplateLockFailed JobTemplateModular JobTemplateParams JobTemplateStats JobTemplateStatus TemplateDraft TemplateFetchResult TemplateHistoryResult TemplateInfo TemplateOrder TemplateOrderBy TemplatePublicVersion TemplateQueryResult TemplateSelectOpts TemplateTag TemplateTextSearch TemplateType TemplateWhereOpts

Enumerations

Enumeration: TemplateType

`Job`	`0`
`Issue`	`1`

Enumeration: JobTemplateStatus

Status of a job template

`PUBLISHED`	`1`
`UNPUBLISHED`	`2`
`IN_REVIEW`	`3`

Enumeration: TemplateOrderBy

`TITLE`	`1`
`AUTHORED_AT`	`2`
`LAST_MODIFIED_AT`	`3`
`TYPE`	`4`

Data structures

Struct: IndexOpts

Key	Field	Type	Description	Requiredness	Default value
1	showUnpublished	`bool`		default	`true`
2	showArchived	`bool`		default	`true`

Options for listing job templates

Struct: JobTemplateParams

Key	Field	Type	Description	Requiredness
1	title	`string`	Name of the job template. This is required on creation.	optional
2	descrip	`string`	Description of the job template	optional
3	metadataEntry	`list<metadata.MetadataEntry>`	Metadata for the job template	optional
4	typ	`TemplateType`	Template type, cannot be updated	optional

Mutable parts of the job template

Exception: JobTemplateLockFailed

Key	Field	Type	Description	Requiredness	Default value
1	previousLock	`JobTemplateLock`	conflicting lock details	default
2	message	`string`		default

Response type for acquireLock

Struct: ForceAcquireResponse

Key	Field	Type	Description	Requiredness	Default value
1	previousLock	`JobTemplateLock`	broken lock details (may be missing)	optional
2	currentLock	`JobTemplateLock`	new lock details	default

Response type for forceAcquireLock

Struct: TemplateTag

Key	Field	Type	Description	Requiredness
1	tagId	`string`	Id of the associated tag. The tag must belong to the same team as the template.	default
2	name	`string`	Name of the tag. This is a READ-ONLY field, will be ignored on writes	optional
3	comment	`string`	Optional comment on the association between the tag and template	optional

Defines a relationship between a tag and a template. tagId is the only required field. The server will populate all three fields.

Struct: JobTemplate

Key	Field	Type	Description	Requiredness
1	id	`string`		default
2	title	`string`	The name of a Job Template	default
3	version	`i32`	Only increments when update is called.	default
4	publicVersion	`i32`	Increment logic for `publicVersion`: Normal team flow: 1. A new job template 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 job template, a new entry is created with `publicVersion=0` and `status=Unpublished`. 4. Repeat from step 2) or 3). Review team flow: 1. A new job template 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 job template, a new entry is created with `publicVersion=0` and `status=Unpublished`. 6. Repeat from step 2) or 5).	default
5	stepGroup	`step.BaseStep`	The top step group of the job template's step hierarchy	default
6	status	`string`	Status of the job template	default
7	descrip	`string`	Details about the job	default
8	team	`team.Team`		default
9	metadataEntry	`list<metadata.MetadataEntry>`		optional
10	UNSUPPORTEDdocumentEmailAddress	`string`	UNSUPPORTED Email address for this particular job template	default
11	documents	`list<document.Document>`	List of documents for this job template	default
12	archivedAt	`i64`	Unix timestamp of when the job template was archived. 0 means the job template is not archived. An archived job template cannot be edited or used to create a job	default
13	lastAuthor	`string`	The id of the last user to modify this template version	default
14	system	`bool`	System template, cannot be modified	default
15	locked	`JobTemplateLock`	Internal authoring lock	optional
16	lastAuthoredAt	`i64`	Unix timestamp of authored time for this edit	default
17	publishedAt	`i64`	Unix timestamp of publish time for this edit. 0 if not published	default
18	lastPublishedAt	`i64`	DEPRECATED Bumps up on Create/Publish/InReview/Reject, 0 if no such event has occurred. Note that this field is wrongly named.	default
19	templateTags	`list<TemplateTag>`	List of tags	default
20	metadataById	`map<string, metadata.MetadataEntry>`	Replaces metadataEntry	default
21	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 job templates with `status!=Published`.	default
22	typ	`TemplateType`		default
23	lastPublishedBy	`string`	The id of the last user to publish this template	optional
24	readOnly	`bool`		optional
25	globalTemplate	`bool`		optional
26	localTemplate	`bool`	If the current template is a Local instance of a Global template. I.e. true if sourceTemplateId, sourceTemplateVersion are populated.	optional
27	archiveDisabled	`bool`		optional

Fields of a JobTemplate

Struct: JobTemplateStats

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

Struct: TemplateDraft

Key	Field	Type	Requiredness
1	version	`i32`	default
2	authoredAt	`i64`	default
3	authorId	`string`	default
4	display	`bool`	default
5	publicVersion	`i32`	default
6	status	`JobTemplateStatus`	default
7	publishedVersion	`i32`	default

Struct: JobTemplateModular

Key	Field	Type	Description	Requiredness
1	id	`string`	Template UUID	default
2	internalVersion	`i32`	See `version` in JobTemplate	default
3	publicVersion	`i32`	See `publicVersion` in JobTemplate	default
4	title	`string`		default
5	descrip	`string`	Description	default
6	status	`JobTemplateStatus`		default
7	stepGroupId	`string`		default
8	teamId	`string`		default
9	UNSUPPORTEDdocumentEmailAddress	`string`	UNSUPPORTED Email address for this particular job template	default
10	lastAuthoredAt	`i64`	authored time for this edit	default
11	publishedAt	`i64`	published time for this edit, 0 if not published	default
13	archivedAt	`i64`	archive time, 0 means the job template is not archived	default
14	lastAuthorId	`string`		default
15	system	`bool`		default
16	metadataEntry	`list<metadata.MetadataEntry>`		default
17	metadataById	`map<string, metadata.MetadataEntry>`		default
18	publishedVersion	`i32`	See `publishedVersion` in JobTemplate	default
19	typ	`TemplateType`		default
20	locked	`JobTemplateLock`	Internal authoring lock	optional
21	publishedById	`string`	The id of the last user to publish this template	optional
101	team	`team.TeamModular`		optional
102	rootHeaders	`group_headers.StepGroupHeaders`		optional
103	stepGroup	`step.BaseStep`		optional
104	documents	`list<document.Document>`		optional
105	lastPublishedAt	`i64`	DEPRECATED Bumps up on Create/Publish/InReview/Reject, 0 if no such event has occurred. Note that this field is wrongly named.	optional
106	lastAuthor	`user.User`		optional
107	stats	`JobTemplateStats`		optional
108	templateTags	`list<TemplateTag>`		optional
109	drafts	`list<TemplateDraft>`	All drafts since and including last published	optional
110	lastPublishedVersion	`i32`	last published version for this template. 0 if not published	optional
111	lastPublishTime	`i64`	Bumps up on Publish, 0 if never pubished. (fixed version of lastPublishedAt)	optional
112	lastModifiedAt	`i64`	Bumps up on edit, status change, archive	optional
113	attributes	`list<abac.AbacAttribute>`		optional
115	references	`map<reference.RefSource, set<string>>`		optional
120	plannedDataSheetIds	`map<string, string>`	Map of data sheet set id -> data sheet id picked during job planning This is only valid if the data sheet set ids are contained in `references` above	optional
121	snapshottedDataSheetValues	`map<string, data_sheet.DataSheetValue>`	Map of data sheet set definition id -> data sheet value snapshotted at/after job start This is only valid if the data sheet set definition ids are contained in `references` above	optional
122	originalAuthor	`user.UserModular`		optional
123	reviewFlowRequired	`bool`	If true, this template requires the review flow. This is only populated by JobTemplateService.Fetch	optional
124	lastPublishedBy	`user.User`		optional
125	readOnly	`bool`		optional
126	globalTemplate	`bool`		optional
127	localTemplate	`bool`	This is TRUE If the current template is a Local instance of a Global template.	optional
128	archiveDisabled	`bool`		optional
129	globalTemplateVersion	`i32`	globalTemplateVersion come with the current version of the global template. It only will be populated if the template is a local template.	optional
130	localTemplateOutdated	`bool`	localTemplateOutdated is TRUE if the source template version is greater than the local template. It only will be populated if the template is a local template.	optional
200	structDiff	`diff.ChangeType`		optional
201	titleDiff	`diff.StringDiff`		optional
202	descripDiff	`diff.StringDiff`		optional

Struct: TemplateSelectOpts

Key	Field	Type	Description	Requiredness
1	includeTeam	`bool`		default
2	includeRootHeaders	`bool`		default
3	includeSteps	`bool`		default
4	includeDocuments	`bool`		default
5	includeLastPublished	`bool`	Loads both lastPublishedAt and lastPublishedVersion	default
6	includeLastAuthor	`bool`		default
7	includeStats	`bool`		default
8	includeTags	`bool`		default
9	includeDrafts	`bool`		default
10	includeLastModified	`bool`		default
11	includeAttributes	`bool`		default
15	includeRefMap	`bool`		default
16	includeOriginalAuthor	`bool`		default
17	includeDocumentUrls	`bool`		optional

Struct: TemplateTextSearch

Key	Field	Type	Description	Requiredness	Default value
1	query	`string`		default

Full text search against title and description

Struct: TemplateWhereOpts

Key	Field	Type	Description	Requiredness
1	teamId	`string`		default
2	isArchived	`bool`		optional
3	isPublished	`bool`		optional
4	txt	`TemplateTextSearch`		optional
5	metadata	`list<metadata.MetadataEntry>`	See MetadataValue for specific metadata filter criteria	optional
6	authorId	`string`		optional
7	rootCategoryId	`string`		optional
8	modifiedSinceTime	`i64`		optional
9	modifiedBeforeTime	`i64`		optional
10	templateTypes	`set<TemplateType>`	Will default to TemplateType Job	optional
11	isLatestArchived	`bool`		optional
12	isLatestPublished	`bool`		optional
13	attributes	`list<abac.AbacAttribute>`	allows template filtering by attributes	optional
20	pageReq	`common.PageReq`		optional
30	externalOpts	`common.ExternalOpts`		optional

Options for choosing records

Struct: TemplateOrder

Key	Field	Type	Description	Requiredness	Default value
1	field	`TemplateOrderBy`		default
2	asc	`bool`		default	`true`

Struct: TemplateQueryResult

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

Union: TemplateFetchResult

Key	Field	Type	Description	Requiredness	Default value
1	template	`JobTemplateModular`		default
2	err	`common.SystemException`		default

Union: TemplateHistoryResult

Key	Field	Type	Description	Requiredness	Default value
1	template	`JobTemplateModular`		default
2	err	`common.SystemException`		default

Struct: TemplatePublicVersion

Key	Field	Type	Description	Requiredness	Default value
1	jobTemplateId	`string`		default
2	publicVersion	`i32`		default

Struct: TemplateInfo

Key	Field	Type	Description	Requiredness
1	templateId	`string`		default
2	templateVersion	`i32`		default
3	addedAfterId	`string`	should be the jobBaseStepId of the stepgroup for uniqueness	default
4	materializedSteps	`step.BaseStep`		default

Templates that were added offline addedAfterId should be previous step/step group id This is needed as step position could have changed by modifying job online

Services

Service: JobTemplateService

Function: JobTemplateService.query

TemplateQueryResult query(TemplateSelectOpts selectOpts,
                          TemplateWhereOpts whereOpts,
                          list<TemplateOrder> order)
    throws common.SystemException

Query a list of Job Templates

Function: JobTemplateService.fetch

map<string, TemplateFetchResult> fetch(TemplateSelectOpts selectOpts,
                                     list<string> templateIds)
    throws common.SystemException

Fetch a specific list of JobTemplates. Returns a hashmap of TemplateFetchResults keyed off template ids. One entry for every requested id. Value in hashmap is either an error indicating that the fetch failed or the JobTemplateModular object for that id.

Function: JobTemplateService.getLatestVersions

map<string, i32> getLatestVersions(list<string> templateIds)
    throws common.SystemException

Fetch a map of the given templates ids to their latest version

Function: JobTemplateService.create

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

Create a new template

Function: JobTemplateService.update

JobTemplate update(string jobTemplateId,
                   JobTemplateParams params)
    throws common.SystemException

Update template title, description

Function: JobTemplateService.archive

JobTemplate archive(string jobTemplateId)
    throws common.SystemException

Mark a job template as archived. Archived templates cannot be edited or used to start jobs. This marks all versions of the job template as archived

Function: JobTemplateService.unarchive

JobTemplate unarchive(string jobTemplateId)
    throws common.SystemException

Mark a job template as unarchived. This marks all versions of the job template as unarchived

Function: JobTemplateService.publish

JobTemplate publish(string jobTemplateId)
    throws common.SystemException

Publish a job template

Function: JobTemplateService.getPublicVersion

JobTemplate getPublicVersion(string jobTemplateId,
                             i32 publicVersion)
    throws common.SystemException

Get a JobTemplate based on public version.

If publicVersion is 0, get the currently published version

Function: JobTemplateService.fetchPublicVersions

map<string, map<i32, TemplateFetchResult>> fetchPublicVersions(TemplateSelectOpts selectOpts,
                                                           list<TemplatePublicVersion> versions)
    throws common.SystemException

Get a list of JobTemplateModulars based on a list of template ids and their public versions.

If publicVersion is 0, get the currently published version.

Returns a map> response.

Function: JobTemplateService.fetchPublishedVersions

map<string, map<i32, TemplateFetchResult>> fetchPublishedVersions(TemplateSelectOpts selectOpts,
                                                              list<TemplatePublicVersion> versions)
    throws common.SystemException

Get a list of JobTemplateModulars based on a list of template ids and their published versions.

If publicVersion (publishedVersion) is 0, get the currently published version.

Returns a map> response.

Function: JobTemplateService.beginReview

i32 beginReview(string jobTemplateId)
    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: JobTemplateService.endReview

i32 endReview(string jobTemplateId)
    throws common.SystemException

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

Function: JobTemplateService.publishVersion

JobTemplate publishVersion(string jobTemplateId,
                           i32 publicVersion)
    throws common.SystemException

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

Function: JobTemplateService.cloneTemplate

JobTemplate cloneTemplate(string jobTemplateId)
    throws common.SystemException

Clone an entire template. ErrorCodes: RESOURCE_ARCHIVED - returned when there exist steps in the copied template that are assigned to an archived role

Function: JobTemplateService.createLocalTemplate

JobTemplate createLocalTemplate(string jobTemplateId)
    throws common.SystemException

Create a new local template from the global template specified by jobTemplateId.

Function: JobTemplateService.addStepModular

JobTemplateModular addStepModular(string jobTemplateId,
                                  string parentId,
                                  step.BaseStep step,
                                  i32 position,
                                  bool replace)
    throws common.SystemException

Add a step to a step group in a job template and return modular template.

position is the position to insert the new step. position == -1 inserts it at the end.
If replace == true then it will replace instead of inserting at the position.

Function: JobTemplateService.addStepGroupModular

JobTemplateModular addStepGroupModular(string jobTemplateId,
                                       string parentId,
                                       step.BaseStep stepGroup,
                                       i32 position,
                                       bool replace)
    throws common.SystemException

Add a step group to a step group in a job template and return modular template.

position is the position to insert the new step group. position == -1 inserts it at the end.
If replace == true then it will replace instead of inserting at the position.

Function: JobTemplateService.moveStepModular

JobTemplateModular moveStepModular(string jobTemplateId,
                                   string parentId,
                                   string stepId,
                                   i32 oldPosition,
                                   string newParentId,
                                   i32 newPosition)
    throws common.SystemException

Move a step to a step group in a job template and return modular template.

parentId/newParentId is the old/new step group to move the current step from/to.
oldPosition/newPosition is the old/new position to move the current step from/to. newPosition == -1 inserts it at the end.
Can move between step groups if parentId != newParentId.

Function: JobTemplateService.moveStepGroupModular

JobTemplateModular moveStepGroupModular(string jobTemplateId,
                                        string parentId,
                                        string stepGroupId,
                                        i32 oldPosition,
                                        string newParentId,
                                        i32 newPosition)
    throws common.SystemException

Move a step group to a step group in a job template and return modular template.

parentId/newParentId is the old/new step group to move the current step group from/to.
oldPosition/newPosition is the old/new position to move the current step group from/to. newPosition == -1 inserts it at the end.
Can move between step groups if parentId != newParentId.

Function: JobTemplateService.removeStepModular

JobTemplateModular removeStepModular(string jobTemplateId,
                                     string parentId,
                                     string stepId,
                                     i32 position)
    throws common.SystemException

Remove a step from a step group in a job template and return modular template.

position is the position the step is currently at.

Function: JobTemplateService.removeStepGroupModular

JobTemplateModular removeStepGroupModular(string jobTemplateId,
                                          string parentId,
                                          string stepGroupId,
                                          i32 position)
    throws common.SystemException

Remove a step group from a step group in a job template and return modular template.

position is the position the step group is currently at.

Function: JobTemplateService.cloneStepModular

JobTemplateModular cloneStepModular(string jobTemplateId,
                                    string parentId,
                                    string stepId,
                                    i32 position,
                                    string newParentId,
                                    i32 newPosition)
    throws common.SystemException

Clone a step in a job template and return modular template.

parentId/newParentId is the old/new step group to clone the current step from/to.
position/newPosition is the old/new position to clone the current step from/to. newPosition == -1 inserts it at the end.
Can clone between step groups if parentId != newParentId.

Function: JobTemplateService.cloneStepGroupModular

JobTemplateModular cloneStepGroupModular(string jobTemplateId,
                                         string parentId,
                                         string stepGroupId,
                                         i32 position,
                                         string newParentId,
                                         i32 newPosition)
    throws common.SystemException

Clone a step group in a job template and return modular template.

parentId/newParentId is the old/new step group to clone the current step group from/to.
position/newPosition is the old/new position to clone the current step group from/to. newPosition == -1 inserts it at the end.
Can clone between step groups if parentId != newParentId.

Function: JobTemplateService.addDocument

JobTemplate addDocument(string jobTemplateId,
                        i32 jobTemplateVersion,
                        string documentId)
    throws common.SystemException

Add a document to a Job Template; update version

Function: JobTemplateService.removeDocument

JobTemplate removeDocument(string jobTemplateId,
                           string documentId)
    throws common.SystemException

Remove a document from a Job Template; update version

Function: JobTemplateService.updateDocument

JobTemplate updateDocument(string jobTemplateId,
                           string documentId,
                           i32 position)
    throws common.SystemException

Update a document to a Job Template; update version

Function: JobTemplateService.updateMetadata

map<string, metadata.MetadataEntry> updateMetadata(string jobTemplateId,
                                                 map<string, metadata.MetadataValue> updated,
                                                 list<string> removedIds)
    throws common.SystemException

Update the metadata on a template. Updated are the values to be added or updated on the template. RemovedIds are the IDs of the values to be removed from the template.

Function: JobTemplateService.acquireLock

JobTemplateLock acquireLock(string jobTemplateId)
    throws common.SystemException, JobTemplateLockFailed

Start editing the template 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: JobTemplateService.forceAcquireLock

ForceAcquireResponse forceAcquireLock(string jobTemplateId)
    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: JobTemplateService.releaseLock

void releaseLock(string jobTemplateId)
    throws common.SystemException

Release the lock on the template; will throw exception if you don't have the lock

Function: JobTemplateService.getHistory

map<i32, TemplateHistoryResult> getHistory(string id,
                                         list<i32> internalVersions,
                                         i32 otherVersion)
    throws common.SystemException

Get diff of requested version of a template against the latest version Returns a hashmap keyed off version. One entry for every requested internalVersion. Value is either an error indicating something went wrong with the diffing operation for that version or the JobTemplateModular object with diff fields filled in

Function: JobTemplateService.revert

void revert(string id,
            i32 internalVersion)
    throws common.SystemException

Copies the draft version referred to on top of the current latest draft version

Function: JobTemplateService.updateAttribute

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

Update a single attribute on a job template return value will always be a list with a single attribute determined by which attribute was updated param templateId: job template 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 templateId param behave: determine the behaviour of the endpoint, merge or clobber. Default: clobber