V5 onwards only
This tutorial demonstrates how to create a job 12d Synergy via the Web RESTful API.
The steps include:
Creating a basic job with no required attributes or naming rules
Finding required job attributes
Creating a job with required attributes
Finding the required job naming rule
Creating a job that matches the required attributes and naming rule
Finding job templates based on required attributes (and naming rules for those templates)
The commands are provided in curl and can be run from the command prompt when the Synergy Server is running (or in a batch script).
Additional API documentation
To get a list of most of the API requests available, with the 12d Synergy server running, browse http://synergy.myserver.com/api-docs/ui/index.
(Replace synergy.myserver.com with the external server address and update the port numbers if necessary.)
1.1. Logging in and using access tokens for the API requests
A bearer access token is required to be sent up with each request. The tutorial for getting and updating tokens is here: Generate PAT in 12d Synergy Client
1.2. Creating a basic job
This request can be found in the API documentation under Jobs, marked 'Create a new job'.
For this first example, a top-level job is being created in 12d Synergy. It does require attributes, and it does not need to adhere to any naming rule.
It requires a JobCreateModel to be sent up as JSON in the body. If it is successful, it will return the Entity ID of the newly created job. In the curl example below, the JSON body can be seen after the command line option -- data.
Note that the JSON body is all on one line. Multi-line JSON data does not work well with curl when being used in a batch script or from the Windows command prompt (more on that later).
If the job being created is a sub-job, then the "ParentJobID" must be the Entity ID of the parent job instead of null.
Create Job Request
curl --location --request POST "http://synergy.myserver.com/api/v1/jobs/create" ^
--header "Authorization: Bearer <token>" ^
--header "Content-Type: application/json" ^
--data "{\"AlwaysDisplayParent\": false,\"CaptureData\": null,\"Categories\": null,\"Attributes\": null,\"CopyFromId\": null,\"IsDeleteLocked\": false,\"HasCoverImage\": false,\"InheritPermissions\": true,\"InheritsFileNamingRules\": false,\"ParentJobId\": null,\"JobDescription\": \"Test job created by curl\",\"JobName\": \"12ds Rest API Job\",\"RuleSetId\": -1,\"CoverImage\": null}"1.2.1. Optional Values
In the above request, all of the properties of the JobCreateModel are shown. But most of them will default to false or null. So they may not have to be included. At the very least, a job can be created with just the 1 property: "JobName".
Below is an example response if the job is successfully created (giving the Entity ID of the newly created job).
Create Job Response
{
"_id": 50189,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "50189_1"
}1.3. Finding Required Job Attributes
If the following error message is returned with the response: "is required but not defined!", it means that 12d Synergy has been configured so that Jobs must be created with at least one attribute. For example, "Job Type is required but not defined!" means that an attribute value must go up for the attribute "Job Type".
A request can be sent to get all the System Job Attributes. This request can be found in the API documentation under Attributes, marked 'Get system Job attributes'.
The parameter get_initial must be set to true or false in the request URL. If set to true, and default values have been configured for the attributes, then the default values will be returned with the attribute information.
Get System Job Attributes Request
curl --location "http://synergy.myserver.com/api/v1/attributes/getSystemJobAttributes?get_initial=true" ^
--header "Authorization: Bearer <token>" ^
--header "Content-Type: application/json"Below is an example of a successful response, returning three job attributes.
Two of them are required, "Job Type" and "Job Status", and both of these are list attributes. One of the attributes is optional, "Location", a text attribute.
For more information on attribute types, see the first tutorial How to upload files to 12d Synergy via the Web RESTful API.
The required attributes (the ones needed for job creation) are marked "optional": false
"Job Type" has a default value of "Standard Job", so the attribute has that as the "_value", "enum_id" and "value_id" set in "value". "Job Status" does not have a default value, so it is marked "value": null.
Note that a list attribute that contains all the items in that list is in the "enum_items" array.
Click 
in the line below to see the code.
System Job Attributes Response
[
{
"auto_increment_start": 1,
"description": "",
"enum_items": null,
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"optional": true,
"order": 3,
"read_only": false,
"reprompt_on_change": false,
"type": 0,
"value": null,
"visibility_constraint": null,
"workflow_id": null,
"attribute_id": {
"_id": 50536,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "50536_1"
},
"name": "Location",
"display_name": "Location",
"id": {
"_id": 50536,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "50536_1"
}
},
{
"auto_increment_start": 1,
"description": "",
"enum_items": [
{
"visibility_constraint": null,
"enum_id": {
"_id": 135,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "135_1"
},
"value": "Standard Job",
"display_name": "Standard Job",
"hidden": false,
"id": {
"_id": 135,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "135_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 136,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "136_1"
},
"value": "Administration",
"display_name": "Administration",
"hidden": false,
"id": {
"_id": 136,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "136_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 137,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "137_1"
},
"value": "JVO",
"display_name": "JVO",
"hidden": false,
"id": {
"_id": 137,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "137_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 138,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "138_1"
},
"value": "International",
"display_name": "International",
"hidden": false,
"id": {
"_id": 138,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "138_1"
}
}
],
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"optional": false,
"order": 1,
"read_only": false,
"reprompt_on_change": false,
"type": 4,
"value": {
"_value": "Standard Job",
"enum_id": {
"_id": 135,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "135_1"
},
"value_id": {
"_id": 184300,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "184300_1"
}
},
"visibility_constraint": null,
"workflow_id": null,
"attribute_id": {
"_id": 50537,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "50537_1"
},
"name": "Job Type",
"display_name": "Job Type",
"id": {
"_id": 50537,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "50537_1"
}
},
{
"auto_increment_start": 1,
"description": "",
"enum_items": [
{
"visibility_constraint": null,
"enum_id": {
"_id": 139,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "139_1"
},
"value": "Preparation",
"display_name": "Preparation",
"hidden": false,
"id": {
"_id": 139,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "139_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 140,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "140_1"
},
"value": "Begun",
"display_name": "Begun",
"hidden": false,
"id": {
"_id": 140,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "140_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 141,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "141_1"
},
"value": "Waiting For Approval",
"display_name": "Waiting For Approval",
"hidden": false,
"id": {
"_id": 141,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "141_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 142,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "142_1"
},
"value": "Blocked",
"display_name": "Blocked",
"hidden": false,
"id": {
"_id": 142,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "142_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 143,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "143_1"
},
"value": "Complete",
"display_name": "Complete",
"hidden": false,
"id": {
"_id": 143,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "143_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 144,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "144_1"
},
"value": "Re-Opened",
"display_name": "Re-Opened",
"hidden": false,
"id": {
"_id": 144,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "144_1"
}
}
],
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"optional": false,
"order": 2,
"read_only": false,
"reprompt_on_change": false,
"type": 4,
"value": null,
"visibility_constraint": null,
"workflow_id": null,
"attribute_id": {
"_id": 50538,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "50538_1"
},
"name": "Job Status",
"display_name": "Job Status",
"id": {
"_id": 50538,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "50538_1"
}
}
]1.4. Creating a job with required attributes
In the following example, the same create job request is sent up, but this time the property "Attributes" will contain all the attribute information required. Because the "Location" attribute is optional, it will be left out.
This is largely a copy and paste from the above response, but with one main difference. The "value" sent up cannot be null, because the value is required.
In this example, the default value for "Job Type" will be sent back up, but an item from the list attribute "Job Status" must be selected as the value for that attribute.
1.3.1. Sending the JSON body from a file
The JSON body in this example is too big to be easily read on one line. So, to make it more readable, the JSON body can be put in a separate JSON file. This way, it can be multi-line and nested. The curl request will specify the file path for -- data and use the @ symbol to signify that the file content should be sent up. If the file is in the same folder as the batch file or where the command is being run from, the file name will suffice.
Create Job With Attributes Request
curl --location --request POST "http://synergy.myserver.com/api/v1/jobs/create" ^
--header "Authorization: Bearer <token>" ^
--header "Content-Type: application/json" ^
--data @job_create_model.jsonBelow is the contents of the job_create_model.json file.
The optional attribute has been removed from the array of attributes.
The "value": null for "Job Status" has been replaced with the following:
Value for "Job Status"
"value": {
"_value": "Preparation",
"enum_id": {
"_id": 139,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "139_1"
},
"value_id": null
},"Value_id" can be left as null, as 12d Synergy will create one when the job is created.
Aside from those two changes, the "Attributes" array is the same as the response from Get System Job Attributes.
Click in the line below to see the code.
job_create_model.json
{
"AlwaysDisplayParent": false,
"CaptureData": null,
"Categories": null,
"Attributes":
[
{
"auto_increment_start": 1,
"description": "",
"enum_items": [
{
"visibility_constraint": null,
"enum_id": {
"_id": 135,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "135_1"
},
"value": "Standard Job",
"display_name": "Standard Job",
"hidden": false,
"id": {
"_id": 135,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "135_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 136,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "136_1"
},
"value": "Administration",
"display_name": "Administration",
"hidden": false,
"id": {
"_id": 136,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "136_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 137,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "137_1"
},
"value": "JVO",
"display_name": "JVO",
"hidden": false,
"id": {
"_id": 137,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "137_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 138,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "138_1"
},
"value": "International",
"display_name": "International",
"hidden": false,
"id": {
"_id": 138,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "138_1"
}
}
],
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"optional": false,
"order": 1,
"read_only": false,
"reprompt_on_change": false,
"type": 4,
"value": {
"_value": "Standard Job",
"enum_id": {
"_id": 135,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "135_1"
},
"value_id": {
"_id": 184300,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "184300_1"
}
},
"visibility_constraint": null,
"workflow_id": null,
"attribute_id": {
"_id": 50537,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "50537_1"
},
"name": "Job Type",
"display_name": "Job Type",
"id": {
"_id": 50537,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "50537_1"
}
},
{
"auto_increment_start": 1,
"description": "",
"enum_items": [
{
"visibility_constraint": null,
"enum_id": {
"_id": 139,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "139_1"
},
"value": "Preparation",
"display_name": "Preparation",
"hidden": false,
"id": {
"_id": 139,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "139_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 140,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "140_1"
},
"value": "Begun",
"display_name": "Begun",
"hidden": false,
"id": {
"_id": 140,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "140_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 141,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "141_1"
},
"value": "Waiting For Approval",
"display_name": "Waiting For Approval",
"hidden": false,
"id": {
"_id": 141,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "141_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 142,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "142_1"
},
"value": "Blocked",
"display_name": "Blocked",
"hidden": false,
"id": {
"_id": 142,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "142_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 143,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "143_1"
},
"value": "Complete",
"display_name": "Complete",
"hidden": false,
"id": {
"_id": 143,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "143_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 144,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "144_1"
},
"value": "Re-Opened",
"display_name": "Re-Opened",
"hidden": false,
"id": {
"_id": 144,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "144_1"
}
}
],
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"optional": false,
"order": 2,
"read_only": false,
"reprompt_on_change": false,
"type": 4,
"value": {
"_value": "Preparation",
"enum_id": {
"_id": 139,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "139_1"
},
"value_id": null
},
"visibility_constraint": null,
"workflow_id": null,
"attribute_id": {
"_id": 50538,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "50538_1"
},
"name": "Job Status",
"display_name": "Job Status",
"id": {
"_id": 50538,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "50538_1"
}
}
],
"CopyFromId": null,
"IsDeleteLocked": false,
"HasCoverImage": false,
"InheritPermissions": true,
"InheritsFileNamingRules": false,
"ParentJobId": null,
"JobDescription": "Test job created by curl",
"JobName": "12ds Rest API Job",
"RuleSetId": -1,
"CoverImage": null
}As before, a successful request sent up with the attributes will result in the Entity ID of the newly created job being sent back in the response.
1.5. Creating a job with required attributes to match a naming rule
If the error message comes back "violates global naming rules!", it means that every job created must adhere to a single naming rule.
If the error message comes back "violates the parent naming rules!", it means that all sub-jobs created under a particular parent job are required to adhere to a single naming rule.
If the error message comes back "violates Job naming rules!", it means that a naming rule has been set up on the matching job template (see job templates further on).
The Get Job Naming Rule request can be sent to get the naming rule. Set the parameter "parent_job_id" to equal null in the request URL for the first error, or to equal the job ID for the parent job for the second error.
This request can be found in the API documentation under Jobs, marked 'Get naming rule for jobs'.
Get Job Naming Rule Request
curl --location "http://synergy.myserver.com/api/v1/jobs/getJobNamingRule?parent_job_id=null" ^
--header "Authorization: Bearer <token>" ^
--header "Content-Type: application/json"The response below returns a JobNamingRuleModel, which includes an array of naming rule components and the rule itself at the bottom.
In this example, the rule is ".".
The example rule is made up of three components. The first is an attribute ("type": 0), and it gives all the enum_items for that attribute. The second component is a fixed string ("type:" 3). The string is " - ". The third component is a free-text string ("type": 1), represented by an asterisk.
This means the job name must start with one of the list values for Job Type, followed by " - ", followed by any text.
For example, an acceptable name would be "Standard Job - My New Rest API Job" or "JVO - Hoover Dam Site".
For more information, please refer to the article Job Naming Rules.
Click in the line below to see the code.
Get Job Naming Rule Response
{
"components": [
{
"type": 0,
"attribute": {
"auto_increment_start": 1,
"description": "",
"enum_items": [
{
"visibility_constraint": null,
"enum_id": {
"_id": 135,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "135_1"
},
"value": "Standard Job",
"display_name": "Standard Job",
"hidden": false,
"id": {
"_id": 135,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "135_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 136,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "136_1"
},
"value": "Administration",
"display_name": "Administration",
"hidden": false,
"id": {
"_id": 136,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "136_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 137,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "137_1"
},
"value": "JVO",
"display_name": "JVO",
"hidden": false,
"id": {
"_id": 137,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "137_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 138,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "138_1"
},
"value": "International",
"display_name": "International",
"hidden": false,
"id": {
"_id": 138,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "138_1"
}
}
],
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"optional": false,
"order": 0,
"read_only": false,
"reprompt_on_change": false,
"type": 4,
"value": null,
"visibility_constraint": null,
"workflow_id": null,
"attribute_id": {
"_id": 50537,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "50537_1"
},
"name": "Job Type",
"display_name": "Job Type",
"id": {
"_id": 50537,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "50537_1"
}
},
"fixed_component": null,
"rule_def": "[Job Type]"
},
{
"type": 3,
"attribute": null,
"fixed_component": " - ",
"rule_def": ""
},
{
"type": 1,
"attribute": null,
"fixed_component": null,
"rule_def": ""
}
],
"created_by_id": null,
"created_date": "0001-01-01T00:00:00",
"ID": null,
"rule": "[Job Type] - *"
}1.6. Get Job Naming Rule Component Types
The 'Get Any Types' request can be used to retrieve the Job Naming Rule Component Types. This is the same request that is used to retrieve attribute types. But the type parameter has the value Contracts.Data.ProjectNamingRuleComponentType instead of Contracts.Data.AttributeType.
This request can be found in the API documentation under Types, marked 'Get a list of available options from given enum type_name'.
"http://synergy.myserver.com/api/v1/types?type=Contracts.Data.ProjectNamingRuleComponentType".
Given that the previous Create Job request was sent up with the "Job Type" attribute set to "Standard Job", and the naming rule contains that attribute - the Job Name will need to match that value ("Standard Job").
Edit the job_create_model.json and change "JobName" at the bottom to something acceptable, like "Standard Job - My New Rest API Job".
Job Naming Rules might not contain attributes, but many are set up that way.
1.7. Finding job templates based on matching attributes
Job creation may also need to adhere to templates configured in Synergy Admin. A template is used when an attribute value sent up for job creation matches the 'match attribute' in the template.
For more information on job templates, please refer to the article Job Templates.
In the above screenshot, a template has been set up which will be used when a job is created with the "Job Type" attribute set to "Standard Job". In this case, the job name must adhere to the naming rule "[Job Type] - [Location], [Job Status]".
As mentioned earlier, if an error message is returned in the response "violates Job naming rules!", this means that the job creation is matching up on a template and the job name does not adhere to the naming rule for that template.
To find out what template is being matched and what naming rule it has, the Get Matched Job Template request will need to be sent up. This can be found in the API documentation under Jobs, marked 'Find matched job templates'.
The JSON body must be an array of attributes that were sent up in the attempted job creation. A simple copy and paste of the attributes array into a separate JSON file should suffice.
Get Matched Job Template Request
curl --location "http://synergy.myserver.com/api/v1/jobs/findMatchedTemplate" ^
--header "Authorization: Bearer <token>" ^
--header "Content-Type: application/json" ^
--data @job_attributes.jsonHere is the content of the job_attributes.json file. It is the information for the 2 required list attributes ("Job Type" and "Job Status") that were being sent up in the previous job creation request:
Click in the line below to see the code.
job_attributes.json
[
{
"auto_increment_start": 1,
"description": "",
"enum_items": [
{
"visibility_constraint": null,
"enum_id": {
"_id": 135,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "135_1"
},
"value": "Standard Job",
"display_name": "Standard Job",
"hidden": false,
"id": {
"_id": 135,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "135_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 136,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "136_1"
},
"value": "Administration",
"display_name": "Administration",
"hidden": false,
"id": {
"_id": 136,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "136_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 137,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "137_1"
},
"value": "JVO",
"display_name": "JVO",
"hidden": false,
"id": {
"_id": 137,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "137_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 138,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "138_1"
},
"value": "International",
"display_name": "International",
"hidden": false,
"id": {
"_id": 138,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "138_1"
}
}
],
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"optional": false,
"order": 1,
"read_only": false,
"reprompt_on_change": false,
"type": 4,
"value": {
"_value": "Standard Job",
"enum_id": {
"_id": 135,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "135_1"
},
"value_id": {
"_id": 184300,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "184300_1"
}
},
"visibility_constraint": null,
"workflow_id": null,
"attribute_id": {
"_id": 50537,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "50537_1"
},
"name": "Job Type",
"display_name": "Job Type",
"id": {
"_id": 50537,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "50537_1"
}
},
{
"auto_increment_start": 1,
"description": "",
"enum_items": [
{
"visibility_constraint": null,
"enum_id": {
"_id": 139,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "139_1"
},
"value": "Preparation",
"display_name": "Preparation",
"hidden": false,
"id": {
"_id": 139,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "139_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 140,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "140_1"
},
"value": "Begun",
"display_name": "Begun",
"hidden": false,
"id": {
"_id": 140,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "140_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 141,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "141_1"
},
"value": "Waiting For Approval",
"display_name": "Waiting For Approval",
"hidden": false,
"id": {
"_id": 141,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "141_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 142,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "142_1"
},
"value": "Blocked",
"display_name": "Blocked",
"hidden": false,
"id": {
"_id": 142,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "142_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 143,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "143_1"
},
"value": "Complete",
"display_name": "Complete",
"hidden": false,
"id": {
"_id": 143,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "143_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 144,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "144_1"
},
"value": "Re-Opened",
"display_name": "Re-Opened",
"hidden": false,
"id": {
"_id": 144,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "144_1"
}
}
],
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"optional": false,
"order": 2,
"read_only": false,
"reprompt_on_change": false,
"type": 4,
"value": {
"_value": "Preparation",
"enum_id": {
"_id": 139,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "139_1"
},
"value_id": null
},
"visibility_constraint": null,
"workflow_id": null,
"attribute_id": {
"_id": 50538,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "50538_1"
},
"name": "Job Status",
"display_name": "Job Status",
"id": {
"_id": 50538,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "50538_1"
}
}
]Below is the response for a successful request. It includes the "template_name", the "match_attributes" array (in this case, just the one attribute, "Job Type") and the "naming_rule" object. The "naming_rule" object contains the "rule" - which is what we need. It also includes the array of naming rules "components" which can help identify what values are accepted for the individual components.
For this example the "rule" is "[JobType] - [Location], [Job Status]".
This means that the job name must start with a list value from the "Job Type" attribute, followed by " - ", followed by a value for the "Location" attribute (which can be any text, because it is a text type attribute), followed by ", " followed by a list value from the "Job Status" attribute.
An acceptable job name would be "Standard Job - Any Location, Preparation".
Remember that because the attribute values for "Standard Job" and "Job Type" are being sent up for job creation, these same values must be used for the naming rule.
Although the attribute "Location" is part of the naming rule, it is optional. So the request can be sent up without the "Location" attribute. In this case, the text in the job name for [Location] will update the job name, but the value for the Location attribute will remain empty.
Create Job Request
curl --location --request POST "http://synergy.myserver.com/api/v1/jobs/create" ^
--header "Authorization: Bearer <token>" ^
--header "Content-Type: application/json" ^
--data @job_create_model.jsonBelow is the job_create_model.json file that is sent up with the final request. The job name has been changed to fit the job naming rule for the template the attributes match up on. The attribute values also match up with the job name.
Click in the line below to see the code.
job_create_model.json
{
"AlwaysDisplayParent": false,
"CaptureData": null,
"Categories": null,
"Attributes":
[
{
"auto_increment_start": 1,
"description": "",
"enum_items": [
{
"visibility_constraint": null,
"enum_id": {
"_id": 135,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "135_1"
},
"value": "Standard Job",
"display_name": "Standard Job",
"hidden": false,
"id": {
"_id": 135,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "135_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 136,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "136_1"
},
"value": "Administration",
"display_name": "Administration",
"hidden": false,
"id": {
"_id": 136,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "136_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 137,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "137_1"
},
"value": "JVO",
"display_name": "JVO",
"hidden": false,
"id": {
"_id": 137,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "137_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 138,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "138_1"
},
"value": "International",
"display_name": "International",
"hidden": false,
"id": {
"_id": 138,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "138_1"
}
}
],
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"optional": false,
"order": 1,
"read_only": false,
"reprompt_on_change": false,
"type": 4,
"value": {
"_value": "Standard Job",
"enum_id": {
"_id": 135,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "135_1"
},
"value_id": {
"_id": 184300,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "184300_1"
}
},
"visibility_constraint": null,
"workflow_id": null,
"attribute_id": {
"_id": 50537,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "50537_1"
},
"name": "Job Type",
"display_name": "Job Type",
"id": {
"_id": 50537,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "50537_1"
}
},
{
"auto_increment_start": 1,
"description": "",
"enum_items": [
{
"visibility_constraint": null,
"enum_id": {
"_id": 139,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "139_1"
},
"value": "Preparation",
"display_name": "Preparation",
"hidden": false,
"id": {
"_id": 139,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "139_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 140,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "140_1"
},
"value": "Begun",
"display_name": "Begun",
"hidden": false,
"id": {
"_id": 140,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "140_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 141,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "141_1"
},
"value": "Waiting For Approval",
"display_name": "Waiting For Approval",
"hidden": false,
"id": {
"_id": 141,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "141_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 142,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "142_1"
},
"value": "Blocked",
"display_name": "Blocked",
"hidden": false,
"id": {
"_id": 142,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "142_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 143,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "143_1"
},
"value": "Complete",
"display_name": "Complete",
"hidden": false,
"id": {
"_id": 143,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "143_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 144,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "144_1"
},
"value": "Re-Opened",
"display_name": "Re-Opened",
"hidden": false,
"id": {
"_id": 144,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "144_1"
}
}
],
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"optional": false,
"order": 2,
"read_only": false,
"reprompt_on_change": false,
"type": 4,
"value": {
"_value": "Preparation",
"enum_id": {
"_id": 139,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "139_1"
},
"value_id": null
},
"visibility_constraint": null,
"workflow_id": null,
"attribute_id": {
"_id": 50538,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "50538_1"
},
"name": "Job Status",
"display_name": "Job Status",
"id": {
"_id": 50538,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621ca6-7fd912e6b11e",
"IDString": "50538_1"
}
}
],
"CopyFromId": null,
"IsDeleteLocked": false,
"HasCoverImage": false,
"InheritPermissions": true,
"InheritsFileNamingRules": false,
"ParentJobId": null,
"JobDescription": "Test job created by curl",
"JobName": "Standard Job - Any Location, Preparation",
"RuleSetId": -1,
"CoverImage": null
}As before, the Entity ID of the newly created job will be returned in a successful response.
1.8. Calculate Job Name Request
This request can be found in the API documentation under Jobs.
http://synergy.myserver.com/api/v1/jobs/calculateJobName (Replace synergy.myserver.com with the external server address and update the port numbers if necessary.)
The json body requires three Properties: "attribute_values" which should contain all the attribute values in the same format as before, "gmt_offset_in_minutes" which accepts an int (gmt off-set of local time zone in minutes), and "rule" which should include the naming rule information that was received from the Get Job Naming Rule Request or the Get Matched Job Template Request.
It will generate a job name by replacing the naming rule components with the provided attribute values and timestamp. But it won't resolve rule components for job variables, user variables (such as free text) and counters.
Unless the naming rule is difficult to calculate, this request will most likely not be needed, as the job name can be inferred from the Get Job Naming Rule request or the Get Matched Job Template request.