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.

Note

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.

RequestResponse
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:

  1. Locate and update calls for job target and Job description entities.

  2. Locate and update calls that create job target or job descriptions.

  3. Locate and update calls that create a job target entity.

  4. Locate and update calls that delete job target or job descriptions.

Note

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.

RequestResponse
GET /api/entities/{TARGET_ID}

This call returns a response similar to the following example:

RequestResponse
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:

RequestResponse
GET /api/jobs/{jobId}/targets

This call returns a response similar to the following example:

RequestResponse
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.

RequestResponse
GET /api/entities/{JOB_DESCRIPTION_ID}

This call returns a response similar to the following example:

RequestResponse
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:

RequestResponse
GET /api/jobs/{jobId}/description

This call returns a response similar to the following example:

RequestResponse
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.

RequestResponse
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:

RequestResponse
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.

RequestResponse
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:

RequestResponse
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.

Important

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:

RequestResponse
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:

RequestResponse
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:

RequestResponse
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:

RequestResponse
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:

RequestResponse
DELETE /api/entities/{ID}

Replace this call as follows:

RequestResponse
DELETE /api/jobs/{jobId}/targets/{targetId}

Here is one that deletes a job description entity:

RequestResponse
DELETE /api/entities/{ID}

Replace this call as follows:

RequestResponse
DELETE /api/jobs/{JOB_ID}/description

Do you have some feedback for us?

If you have suggestions for improving this article,