Switch to the Jobs API
To use the Jobs API instead of the Entities API or Querying API, you need to replace calls to get, create, update, and delete M.Target
and M.JobDescription
entities that currently use the Entities API /api/entities
with calls to the Jobs API /api/jobs
.
After you have updated your code by completing this walkthrough, you can then follow the recommended steps to manage jobs.
The following example shows a call to the Jobs API with the skip
and take
query parameters.
GET /api/jobs/123/targets?skip=0&take=25&state=Pending
You have to update your code to switch to the Jobs API. This walkthrough describes how to:
-
Locate and update calls for job target and Job description entities.
-
Locate and update calls that create job target or job descriptions.
-
Locate and update calls that create a job target entity.
-
Locate and update calls that delete job target or job descriptions.
The structure of the responses from the Jobs API is the same as those from the Entities API and the Querying API.
Locate and update calls for job target or job description entities
To locate API calls that retrieve job target entities using the Entities API, search for calls such as the ones shown in the following example.
GET /api/entities/{TARGET_ID}
This call returns a response similar to the following example:
HTTP status code 200
{
"id": 31388,
"identifier": "dLQk3EjdT46PvqdVeqXFgw",
"cultures": [
"en-US"
],
"properties": {
"Target.Location": "10607",
"Target.StartedOn": "2024-10-22T18:31:01.9773702Z",
"Target.CompletedOn": "2024-10-22T18:31:27.4345384Z",
"Target.StateDescription": "File processed",
"Target.Data": {
"type": "Web",
"href": "http://www.stylelabs.com/product/annotation-templates/400/Annotation report - PDF template.zip"
},
"Target.Scope": null,
"Target.Priority": null,
"Target.RetryCount": null,
"Target.State": {
"identifier": "Completed",
"labels": {
"en-US": "Completed"
}
},
"Target.Condition": {
"identifier": "Success",
"labels": {
"en-US": "Success"
}
},
"Target.Type": {
"identifier": "Fetch",
"labels": {
"en-US": "Fetch job"
}
},
"Target.StatusData": {
"code": "FileProcessed"
},
"Target.PriorityLevel": null
},
"relations": {
"JobToTarget": {
"href": "https://localhost:8180/api/entities/31388/relations/JobToTarget"
}
},
"created_by": {
"href": "https://localhost:8180/api/entities/6",
"title": "The user who created the entity"
},
"created_on": "2024-10-22T18:31:01.879725Z",
"modified_by": {
"href": "https://localhost:8180/api/entities/6",
"title": "The user who last modified the entity"
},
"modified_on": "2024-10-22T18:31:27.4733914Z",
"entitydefinition": {
"href": "https://localhost:8180/api/entitydefinitions/M.Target",
"title": "The entity definition for this entity"
},
"copy": {
"href": "https://localhost:8180/api/entities/31388/copy",
"title": "Copy this entity"
},
"permissions": {
"href": "https://localhost:8180/api/entities/31388/permissions",
"title": "The permissions on this entity"
},
"lifecycle": {
"href": "https://localhost:8180/api/entities/31388/lifecycle",
"title": "The lifecycle action for this entity."
},
"saved_selections": {
"href": "https://localhost:8180/api/entities/31388/savedselections",
"title": "The saved selections this entity belongs to"
},
"roles": {
"href": "https://localhost:8180/api/entities/31388/roles",
"title": "Roles for this entity"
},
"annotations": {
"href": "https://localhost:8180/api/entities/31388/annotations",
"title": "Annotations for this entity"
},
"is_root_taxonomy_item": false,
"is_path_root": false,
"inherits_security": true,
"is_system_owned": false,
"version": 3,
"self": {
"href": "https://localhost:8180/api/entities/31388"
},
"renditions": {}
}
Replace this with:
GET /api/jobs/{jobId}/targets
This call returns a response similar to the following example:
HTTP status code 200
{
"items": [
{
"id": 31388,
"identifier": "dLQk3EjdT46PvqdVeqXFgw",
"cultures": [
"en-US"
],
"properties": {
"Target.Location": "10607",
"Target.StartedOn": "2024-10-22T18:31:01.9773702Z",
"Target.CompletedOn": "2024-10-22T18:31:27.4345384Z",
"Target.StateDescription": "File processed",
"Target.Data": {
"type": "Web",
"href": "http://www.stylelabs.com/product/annotation-templates/400/Annotation report - PDF template.zip"
},
"Target.Scope": null,
"Target.Priority": null,
"Target.RetryCount": null,
"Target.State": {
"identifier": "Completed",
"labels": {
"en-US": "Completed"
}
},
"Target.Condition": {
"identifier": "Success",
"labels": {
"en-US": "Success"
}
},
"Target.Type": {
"identifier": "Fetch",
"labels": {
"en-US": "Fetch job"
}
},
"Target.StatusData": {
"code": "FileProcessed"
},
"Target.PriorityLevel": null
},
"relations": {
"JobToTarget": {
"parent": {
"href": "https://localhost:8180/api/entities/31380"
},
"inherits_security": true,
"self": {
"href": "https://localhost:8180/api/entities/31388/relations/JobToTarget"
}
}
},
"created_by": {
"href": "https://localhost:8180/api/entities/6",
"title": "The user who created the entity"
},
"created_on": "2024-10-22T18:31:01.879725Z",
"modified_by": {
"href": "https://localhost:8180/api/entities/6",
"title": "The user who last modified the entity"
},
"modified_on": "2024-10-22T18:31:27.4733914Z",
"entitydefinition": {
"href": "https://localhost:8180/api/entitydefinitions/M.Target",
"title": "The entity definition for this entity"
},
"copy": {
"href": "https://localhost:8180/api/entities/31388/copy",
"title": "Copy this entity"
},
"permissions": {
"href": "https://localhost:8180/api/entities/31388/permissions",
"title": "The permissions on this entity"
},
"lifecycle": {
"href": "https://localhost:8180/api/entities/31388/lifecycle",
"title": "The lifecycle action for this entity."
},
"saved_selections": {
"href": "https://localhost:8180/api/entities/31388/savedselections",
"title": "The saved selections this entity belongs to"
},
"roles": {
"href": "https://localhost:8180/api/entities/31388/roles",
"title": "Roles for this entity"
},
"annotations": {
"href": "https://localhost:8180/api/entities/31388/annotations",
"title": "Annotations for this entity"
},
"is_root_taxonomy_item": false,
"is_path_root": false,
"inherits_security": true,
"is_system_owned": false,
"version": 3,
"self": {
"href": "https://localhost:8180/api/entities/31388"
},
"renditions": {}
}
],
"total_items": 1,
"returned_items": 1,
"offset": 0,
"self": {
"href": "https://localhost:8180/api/jobs/31380/targets?skip=0&take=25",
"title": "This collection"
}
}
To locate API calls that retrieve the job description entity using the Entities API, search for calls such as the one shown in the following example.
GET /api/entities/{JOB_DESCRIPTION_ID}
This call returns a response similar to the following example:
HTTP status code 200
{
"id": 31382,
"identifier": "2OjPPWkhQj-4tc2dUGlaog",
"cultures": [
"en-US"
],
"properties": {
"Job.Configuration": {
"file_id": 0,
"asset_id": 10607,
"files": [
{
"type": "Web",
"href": "http://www.stylelabs.com/product/annotation-templates/400/Annotation report - PDF template.zip"
}
],
"post_fetch": [],
"process_only_post_fetch_tasks": false,
"key": "local-df77b7f3dfd040f3bb11805218077a0e"
},
"Job.Data": {
"qbtMDX_JSAmNzJcIaMJxFA": {
"Id": 31391,
"has_completed": true
}
}
},
"relations": {
"JobToJobDescription": {
"parent": {
"href": "https://localhost:8180/api/entities/31380"
},
"inherits_security": true,
"self": {
"href": "https://localhost:8180/api/entities/31382/relations/JobToJobDescription"
}
}
},
"created_by": {
"href": "https://localhost:8180/api/entities/6",
"title": "The user who created the entity"
},
"created_on": "2024-10-22T18:30:37.442564Z",
"modified_by": {
"href": "https://localhost:8180/api/entities/6",
"title": "The user who last modified the entity"
},
"modified_on": "2024-10-22T18:31:27.135262Z",
"entitydefinition": {
"href": "https://localhost:8180/api/entitydefinitions/M.JobDescription",
"title": "The entity definition for this entity"
},
"copy": {
"href": "https://localhost:8180/api/entities/31382/copy",
"title": "Copy this entity"
},
"permissions": {
"href": "https://localhost:8180/api/entities/31382/permissions",
"title": "The permissions on this entity"
},
"lifecycle": {
"href": "https://localhost:8180/api/entities/31382/lifecycle",
"title": "The lifecycle action for this entity."
},
"saved_selections": {
"href": "https://localhost:8180/api/entities/31382/savedselections",
"title": "The saved selections this entity belongs to"
},
"roles": {
"href": "https://localhost:8180/api/entities/31382/roles",
"title": "Roles for this entity"
},
"annotations": {
"href": "https://localhost:8180/api/entities/31382/annotations",
"title": "Annotations for this entity"
},
"is_root_taxonomy_item": false,
"is_path_root": false,
"inherits_security": true,
"is_system_owned": false,
"version": 3,
"self": {
"href": "https://localhost:8180/api/entities/31382"
},
"renditions": {}
}
Replace this with:
GET /api/jobs/{jobId}/description
This call returns a response similar to the following example:
HTTP status code 200
{
"id": 31382,
"identifier": "2OjPPWkhQj-4tc2dUGlaog",
"cultures": [
"en-US"
],
"properties": {
"Job.Configuration": {
"file_id": 0,
"asset_id": 10607,
"files": [
{
"type": "Web",
"href": "http://www.stylelabs.com/product/annotation-templates/400/Annotation report - PDF template.zip"
}
],
"post_fetch": [],
"process_only_post_fetch_tasks": false,
"key": "local-df77b7f3dfd040f3bb11805218077a0e"
},
"Job.Data": {
"qbtMDX_JSAmNzJcIaMJxFA": {
"Id": 31391,
"has_completed": true
}
}
},
"relations": {
"JobToJobDescription": {
"parent": {
"href": "https://localhost:8180/api/entities/31380"
},
"inherits_security": true,
"self": {
"href": "https://localhost:8180/api/entities/31382/relations/JobToJobDescription"
}
}
},
"created_by": {
"href": "https://localhost:8180/api/entities/6",
"title": "The user who created the entity"
},
"created_on": "2024-10-22T18:30:37.442564Z",
"modified_by": {
"href": "https://localhost:8180/api/entities/6",
"title": "The user who last modified the entity"
},
"modified_on": "2024-10-22T18:31:27.135262Z",
"entitydefinition": {
"href": "https://localhost:8180/api/entitydefinitions/M.JobDescription",
"title": "The entity definition for this entity"
},
"copy": {
"href": "https://localhost:8180/api/entities/31382/copy",
"title": "Copy this entity"
},
"permissions": {
"href": "https://localhost:8180/api/entities/31382/permissions",
"title": "The permissions on this entity"
},
"lifecycle": {
"href": "https://localhost:8180/api/entities/31382/lifecycle",
"title": "The lifecycle action for this entity."
},
"saved_selections": {
"href": "https://localhost:8180/api/entities/31382/savedselections",
"title": "The saved selections this entity belongs to"
},
"roles": {
"href": "https://localhost:8180/api/entities/31382/roles",
"title": "Roles for this entity"
},
"annotations": {
"href": "https://localhost:8180/api/entities/31382/annotations",
"title": "Annotations for this entity"
},
"is_root_taxonomy_item": false,
"is_path_root": false,
"inherits_security": true,
"is_system_owned": false,
"version": 3,
"self": {
"href": "https://localhost:8180/api/entities/31382"
},
"renditions": {}
}
Locate and update calls that create a job target or job description entity
When you replace calls that use the Entities API with ones that use the Jobs API instead, ensure that the request body used in the old API calls is correctly mapped to the new API calls. The new endpoints expect the following request bodies:
-
EntityPostResource
for creating targets. -
JobDescriptionResource
for creating job descriptions.
The following examples illustrate how to switch from using the Entities API to using the Jobs API when working with M.Target
and M.JobDescription
.
Create a job target entity
Here is an example that creates a job target entity using the Entities API.
POST /api/entities
Content-Type: application/json
{
"properties": {
"Target.StateDescription": <description>,
"Target.Location": <location>
},
"relations": {
"JobToTarget": {
"parent": {
"href": "https://<host>/api/entities/{jobId}"
}
}
}
}
Replace this one using the Jobs API as follows:
POST /api/jobs/{jobId}/targets
Content-Type: application/json
{
"properties": {
"Target.StateDescription": <description>,
"Target.Location": <location>
}
}
Create a job description entity
Here is an example that creates a job description entity using the Entities API.
POST /api/entities
Content-Type: application/json
{
"properties": {
"Job.Data": {
...
}
},
"relations": {
"JobToTarget": {
"parent": {
"href": "https://<host>/api/entities/{jobId}"
}
}
}
}
Replace this with one using the Jobs API as follows:
PUT /api/jobs/{jobId}/description
Content-Type: application/json
{
"properties": {
"Job.Data": {
...
}
}
}
Update the job targets or job description
After you identify calls in the code that update job targets or job description entities using the Entities API, modify these calls to use the Jobs API.
PUT
operations perform a full update on a target or description associated with a job. Properties or relations not included in the request will be set to null.
PATCH
operations perform a partial update on a target or description associated with a job. Only the properties and relations included in the request will be updated.
Ensure that the request body used in the old API calls is correctly mapped to the new API calls. The new endpoints expect the following request bodies:
-
EntityResource
for updating (PUT) or partially updating (PATCH) targets. -
JobDescriptionResource
for updating (PUT) and an EntityResource for partially updating (PATCH) job descriptions.
Here is a call that updates a job target entity using the Entities API:
PUT /api/entities/{id}
PUT /api/entities/identifier/{identifier}
Content-Type: application/json
{
"properties": {
"Target.StateDescription": <description>,
"Target.Location": <location>
},
"relations": {
"JobToTarget": {
"parent": {
"href": "https://<host>/api/entities/{jobId}"
}
}
}
}
Here is a call that updates a job target entity using the Jobs API:
PUT /api/jobs/{jobId}/targets/{targetId}
PATCH /api/jobs/{jobId}/targets/{targetId}
Content-Type: application/json
{
"properties": {
"Target.StateDescription": <description>,
"Target.Location": <location>
}
}
Here is a call that updates a job description entity using the Entities API:
PUT /api/entities/{id}
PUT /api/entities/identifier/{identifier}
Content-Type: application/json
{
"properties": {
"Job.Data": {
...
}
},
"relations": {
"JobToTarget": {
"parent": {
"href": "https://<host>/api/entities/{jobId}"
}
}
}
}
Here is a call that updates a job description entity using the Jobs API:
PUT /api/jobs/{jobId}/description
PATCH /api/jobs/{jobId}/description
Content-Type: application/json
{
"properties": {
"Job.Data": {
...
}
}
}
Locate and update calls that delete job targets or the job description
After you identify calls in the code that delete job targets or the job description using the Entities API, update these calls to use the Jobs API.
Here is a call that deletes a job target entity using the Entities API:
DELETE /api/entities/{ID}
Replace this call as follows:
DELETE /api/jobs/{jobId}/targets/{targetId}
Here is one that deletes a job description entity:
DELETE /api/entities/{ID}
Replace this call as follows:
DELETE /api/jobs/{JOB_ID}/description