V5 onwards only
This tutorial demonstrates how to create a job 12d Synergy via the Web RESTful API.
The commands are provided in curl and can be run from the command prompt when the 12d 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 must be sent 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 is available 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 requires attributes, and it does not need to adhere to any naming rules.
It requires a JobCreateModel to be sent as JSON in the body. If it is successful, it returns the Entity ID of the newly created job. In the curl example below, the JSON body is seen after the command line option --data.
Note that the JSON body is on a single 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 properties of the JobCreateModel are shown. But most of them default to false or null. So, they may not need to be included. At the very least, a job can be created with just one 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 be provided for the attribute "Job Type".
A request can be sent to get all the System Job Attributes. This request is available 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 are 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 that returns 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, but this time the attribute’s property contains all the required attribute information. Because the "Location" attribute is optional, it is left out.
This is largely a copy-and-paste from the above response, but with one main difference. The "value" sent cannot be null because it is required.
In this example, the default value for "Job Type" is sent back, but an item from the list attribute "Job Status" must be selected as the value for that attribute.
1.4.1. Sending the JSON body from a File
The JSON body in this example is too large to 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 specifies the file path for --data and uses the @ symbol to indicate that the file contents should be sent. If the file is in the same folder as the batch file or in the folder from which the command is run, the file name suffices.
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 creates 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 with the attributes results 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 says "violates the parent naming rules!", it means that all sub-jobs created under a particular parent job must adhere to a single naming rule.
If the error message says "violates Job naming rules!", it means that a naming rule has been set up for 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 is 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 "[Job Type] - *".
The example rule consists 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. Getting 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 is 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 with the "Job Type" attribute set to "Standard Job", and the naming rule contains that attribute, the Job Name must 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 the 12d Synergy Administration application. A template is used when an attribute value is sent for job creation that 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 is 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 matches a template, and the job name does not adhere to the naming rule for that template.
To find out which template is being matched and what naming rule it uses, the Get Matched Job Template request must be sent. This is in the API documentation under Jobs marked 'Find matched job templates'.
The JSON body must be an array of attributes that were sent during 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 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 which 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 is "Standard Job - Any Location, Preparation".
Remember that because the attribute values for "Standard Job" and "Job Type" are being sent 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 without the "Location" attribute. In this case, the text in the job name for [Location] updates the job name, but the value for the Location attribute is 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 with the final request. The job name has been changed to fit the job-naming rule for the template whose attributes match. 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 is returned in a successful response.
1.8. Calculating Job Name Request
This request is available 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 generates 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 is most likely not needed, as the job name can be inferred from the Get Job Naming Rule request or the Get Matched Job Template request.