Job Manager APIs 🚀

These APIs provide the outcome of the on-demand operation and identify the newly created Job. They submit the Job and return its JobId. These on-demand APIs are synchronous.

By specifying an external idempotency identifier (extIPID) for each on-demand request, Data One can determine if a request has already been processed and reject duplicate execution.

The extIPID is a unique key provided by the user to identify the on-demand operation based on the application domain. extIPID is used to compute the internal idempotency identifier (IPID) used by Data One to identify and avoid duplicate submit operations. In case of no response to the original on-demand request, the on-demand operation can be retried by providing the same extIPID. This avoids creating a duplicate job if the previous operation was successful. In this case, the JobId is returned.

When the Submit REST receives an on-demand request containing the extIPID, the following request parameters are used to generate the IPID of the internal Job submit operation, so that the Job Manager can detect duplicate operations: IPID = hash(User, Contract, Action, extIPID)

The extIPID length is limited to 64 characters.

Submit

• Endpoint: /job-manager/jobs

• Method: POST

• Context: /ghibli-rest/v2

• Description: this API submits a new job to Data One.

• Parameters: request body parameter

• Parameter content type: application/JSON

Parameter	Value	Description	Parameter Type	Data Type
body	(required) Parameter content type: application/JSON	the payload	body	Model: Example Value { “contractName”: “string”, “actionName”: “string”, “actionVariables”: {}, “extIPID”: “string” }

Response: The API will return the newly submitted job (response code 201), or the existing one if collision is detected (response code 409).

 {
 "id": "",
 "status": "",
 "statusMessage": "",
 "createdAt": "",
 "updatedAt": "",
 "submittedBy": "",
 "queue": "",
 "actor": "",
 "contract": "",
 "contractType": "",
 "contractAction": "",
 "contractActionTrigger": "",
 "contractActionWorkflowInstance": {
       "id": "",
       "workflowTemplateId": "",
       "workflowTemplateName": "",
       "workflowTemplateRevision": "",
       "workflowTemplateDescription": ""
  },
  "dfic": {
    "dfiid": "",
    "lcid": "",
    "userAttrs": {
        "key1": "",
        "key2": ""
     }
   },
   "extIPID": ""
 }

• Permissions:

  • Resource: WORKFLOW

  • Default Allowed Roles: Administrators

Job List

• Endpoint: /job-manager/jobs

• Method: GET

• Context: /ghibli-rest/v2

• Description: this API retrieves job details in Data One. The search is executed with an exact matching for all fields.

• Parameters:

Parameter	Value	Description	Parameter Type	Data Type
maxItems	100	Maximum number of values that the server should return (must be less than or equal to 1000)	query	integer
sort		Sort field (+ = ASC, - = DESC, e.g. '+id', '+status', '-contract', '+createdAt': id, status, queue, contract, workflowTemplateId, workflowTemplateName, workflowTemplateRevision, submittedBy, createdAt, updatedAt.	query	string
id		Job id	query	long
status		The job status: SUBMITTED, SUSPENDED, RUNNING, ERROR, ABORTED, COMPLETED	query	string
queue		Job queue	query	string
contract		Contract name	query	string
workflowTemplateId		Id of the workflow template	query	long
workflowTemplateName		Name of the workflow template	query	string
workflowTemplateRevision		Revision number of the workflow template	query	long
createdAtFrom		Creation time lower-bound in ISO8601 format (e.g. 2024-03-26T13:30:30+01:00)	query	string
createdAtTo		Creation time upper-bound in ISO8601 format (e.g. 2024-03-26T13:30:30+01:00)	query	string
updatedAtFrom		Update time lower-bound in ISO8601 format (e.g. 2024-03-26T13:30:30+01:00)	query	string
updatedAtTo		Update time upper-bound in ISO8601 format (e.g. 2024-03-26T13:30:30+01:00)	query	string
extIPID		External idempotency identifier	query	string
submittedBy		Job submitter	query	string
dfiid		Dataflow instance Id	query	string
lcid		Log Correlation Id	query	string
actor		Actor	query	string
contractAction		Action defined in the contract	query	string
contractType		Type of contract	query	string
contractActionTrigger		Trigger defined in the contract	query	string

• Defaults:

  • "maxItems": 100 o "maxItems" cannot exceed limit of 1000 items

  • "sort": id DESC

• Response: The response is a list of JSON objects, each representing a job in the system. Moreover, the "next" element contains the link (absolute, from context path) of the next page. If the next page is not available, it is not present.

{  
 "jobs": [  
   {  
     "id": "",  
     "status": "",  
     "statusMessage": "",  
     "createdAt": "",  
     "updatedAt": "",  
     "submittedBy": "",  
     "queue": "",  
     "actor": "",  
     "contract": "",  
     "contractType": "",  
     "contractAction": "",  
     "contractActionTrigger": "",  
     "contractActionWorkflowInstance": {  
       "id": "",  
       "workflowTemplateId": "",  
       "workflowTemplateName": "",  
       "workflowTemplateRevision": "",  
       "workflowTemplateDescription": ""  
     },  
     "dfic": {  
       "dfiid": "",  
       "lcid": "",  
       "userAttrs": {  
           "key1": "",  
           "key2": ""  
 		  }  
	   },  
 	   "extIPID": ""  
   }  
  ],  
  "next": ""  
}

• Permissions:

  • Resource: SPENGCEMANJOBS

  • Default Allowed Roles: Users, Administrators