api/templates
A Job template contains a complete or partial ROAD job, which may be used repeatedly.
Template data is documented in Templates Data.
For general understand of ROAD data types and especially ROAD jobs, see Jobs Data.
Contents
About Job Templates
Job templates are useful to prepare ROAD jobs with similarities, e.g. with same purpose. Specific differences can be realized later by filling or overwriting some data. By copying a template's job data into a new job and sending that job to the ROAD Service, this job is being created.
Templates can also contain only partial information, e.g. Transitions which may be appended to any job.
Template Data
A template contains some describing information and a job data:
- TemplateId
- Name
- Description
- Groups
- Job
Template data is documented in detail in Templates Data.
Templates are supported only in an installation with database.
Use Cases
- Get a specific template to run a job from it. If requested, add or modify some of its data before making this job.
- Search for templates
- Get or update a single template (change its data, its category or description)
- Create a new template
Interface Usage
REST philosophy is a bit different from function-centric thinking. So to fulfill best practices, we use resource-centric interfaces:
| URI | Verb | Parameters (optional) | Success Result | Description |
|---|---|---|---|---|
| templates | GET | (see below) | OK = 200 | Get data for all existing templates (completely or specific fields). Examples: Note: If no matching template is found, the result value is not 404 (not found) - instead an empty results list will be returned. |
| templates/{templateId} | GET | (see below) | OK = 200 | Get an existing template's data (completely or specific fields). Example: <uri>/api/templates/5c8fd7aa8775951f98d11c9d?fields=name, category, job.transitions.trigger.requestedProcState Note: If the template is not found, the result value is 404 (not found). |
| templates | POST | - | Created = 201 | Creates a new template object, returning its TemplateId. BODY must contain a json-formatted template which contains at least the field "Name". Ids (for template, job or transitions) must not be passed. The TemplateId is being created by object creation in database. Ids for job or transitions make no sense until the job is being created as a real job. |
| templates/{templateId} | PUT | - | OK = 200 | Updates an existing template object by replacing it with the new BODY's json-formatted template. See annotations to the template data in description of POST. Note: If the template is not found, the result value is 404 (not found). |
| templates/{templateId} | DELETE | - | OK = 200 | Deletes a template Note: If the template is not found, the result value is 404 (not found). |
GET: Supported Parameters for templates
Optional Query Parameters (for all GET requests)
| Parameter | Description | Example |
|---|---|---|
| fields | Limit the response to specified fields | fields=name, category, jobs.transition.trigger |
filter | Search filter. See Query Expressions for a detailed description. See below for fields which are supported by this interface. | filter=name=="Test Template" AND "group.Users"=="David" |
sort | Sort order. Comma-separated list of sort fields. An optional "asc" or "desc" can be added after each field name (separated by space). | sort=name desc, job.name |
offset skip | Offset in results list (default: 0) offset and skip are synonymic | offset=100 |
| limit | Limit the result list size (default: 100) | limit=100 |
fields Parameter
The (optional) fields parameter can contain one or several comma-separated column titles (case-insensitive). If this parameter is not used, the results' data will be provided completely. All job's field names can be passed in PascalCase or in camelCase.
Fields not existing in general or in a specific template will lead into not providing these fields in the result.
Fields of sub-objects are specified by the dot syntax (see in table).
For a complete list of template fields see Confluence page Templates Data. Here only some of the most important fields:
| Field Name | Description |
|---|---|
| templateId | Unique id of a template as created by the Service for a POST request |
| name | Title of a template |
| job | Job data for this template. This field is a sub-object. If it is specified this way, all its sub-fields will be returned completely. If sub-fields of jobs are specified, only these will be returned. For a complete list of job fields see Confluence page Jobs Data. |
filter Parameter
The (optional) filter parameter can restrict the found objects by providing one or several parameters. See Query Expressions for a detailed description.
Fields of sub-objects are specified by the dot syntax. For a complete list of template fields see Confluence page Templates Data.
For category groups there is a special syntax: filter="group.<category>" == "<group>” (g.g. filter="group.Users"=="Turing" AND "group.Job Type" == "Recording")
Template Data as REST Body
Where template data is transferred with a REST request to ROAD Service or response from ROAD Service, it is formatted as a JSON. This JSON's structure corresponds to the data structure as described in Confluence page Templates Data, its embedded jobs are documented in Jobs Data.
The provided fields may be incomplete:
- A template creation request (HTTP POST) contains the fields to be set initially, where only "Name" is mandatory.
- A template update request (HTTP PUT) will replace the template with the new one provided. The embedded job data must not contain a JobId.
Template JSON examples are provided in Confluence page Templates Data.