Skip to main content

Jobs and Scheduling

Conscia's DXO Platform provides a set of pre-defined Job Types that can be used to perform common tasks. A Job Type is a template for a Job Definition that can be used to create a Job. The Job Type defines the parameters that are required to create a Job Definition and the behavior of the Job Definition when it is executed. A Job is an actual unit of work being executed (e.g. downloading a file, calling a webservice, processing a file, etc.).

A Job Definition is a template for a Job that can be used to create a Job. A Job Definition consists of:

  • A Job Type
  • A set of parameters that are required by the Job Type
  • Optionally, a schedule for the Job to be executed.

There are two methods of creating a Job.

  1. Using a Job Definition - A Job Definition is created and then a Job is created from the Job Definition. This is the recommended method for creating Jobs as it allows for the reuse of Job Definitions and the ability to change the parameters of a Job Definition without affecting the Jobs that have been created from that Job Definition.
  2. Using a Job Type Directly - A Job can be created directly without a Job Definition by specifying a Job Type and its necessary parameters. This is useful for creating a Job that is not going to be reused or does not require a schedule.

When a Job is created, it is assigned a unique Job ID. This Job ID can be used to check the status of the Job.

Job Type Endpoints​

Listing Job Types​

GET https://io.conscia.ai/vue/_api/v1/job-types
Content-Type: application/json
Authorization: Bearer {{apiKey}}
X-Customer-Code: {{customerCode}}

Getting a specified Job Type​

GET https://io.conscia.ai/vue/_api/v1/job-types/{{jobTypeCode}}
Content-Type: application/json
Authorization: Bearer {{apiKey}}
X-Customer-Code: {{customerCode}}

Creating a Job using a Job Type​

POST https://io.conscia.ai/vue/_api/v1/job-types/callWebserviceEndpoint/_execute
Content-Type: application/json
X-Customer-Code: {{customerCode}}
Authorization: Bearer {{API_KEY}}
{
  "params": {
    "url": "https://api.example.com/_query_",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "searchTerms": "running shoe"
    },
    "searchParams": {
      "limit": 10
    }
  }
}

Example response:

{
  "jobId": "20240302-f3eb6180-9fc0-43c6-9fe3-528cc4981f2c"
}

Job Definition Endpoints​

Creating a Job Definition​

The params section will vary by job type.

POST https://io.conscia.ai/vue/_api/v1/job-definitions
Content-Type: application/json
Authorization: Bearer {{apiKey}}
X-Customer-Code: {{customerCode}}

{
  "jobDefinition": {
    "jobDefinitionCode": "web-test",
    "jobType": "callWebserviceEndpoint",
    "name": "Call My favourite webservice",
    "schedule": { "cron": "* * * * *" }, // Optional.
    "params": {
      "url": "https://jsonplaceholder.typicode.com/posts",
      "method": "GET",
      "headers": {
        "Content-Type": "application/json"
      }
    },
    "options": {
      "skipNotification": true, // Show/hide notifications in the UI
      "sendCompletionEmail": true, // Send completion email to the person who triggered the job
      "sendFailureEmail": true, // Send failure email to the person who triggered the job
      "emailList": ["{{email address}}"]  // Optional. Send completion/failure email to the specified email addresses
    }
  }
}

Listing Job Definitions​

GET https://io.conscia.ai/vue/_api/v1/job-definitions
Content-Type: application/json
Authorization: Bearer {{apiKey}}
X-Customer-Code: {{customerCode}}

Getting a specified Job Definition​

GET https://io.conscia.ai/vue/_api/v1/job-definitions/{{jobDefinitionCode}}
Content-Type: application/json
Authorization: Bearer {{apiKey}}
X-Customer-Code: {{customerCode}}

Updating a Job Definition​

PATCH https://io.conscia.ai/vue/_api/v1/job-definitions/{{jobDefinitionCode}}
Content-Type: application/json
Authorization: Bearer {{apiKey}}
X-Customer-Code: {{customerCode}}

{
  "jobDefinition": {
    "jobDefinitionCode": "web-test",
    "jobType": "callWebserviceEndpoint",
    "name": "My new name", // new name
    "schedule": { "cron": "*/5 * * * *" }, // every 5 minutes
    "params": {
      "url": "https://jsonplaceholder.typicode.com/posts",
      "method": "GET",
      "headers": {
        "Content-Type": "application/json"
      }
    }
  }
}

Deleting a Job Definition​

DELETE https://io.conscia.ai/vue/_api/v1/job-definitions/{{jobDefinitionCode}}
Content-Type: application/json
Authorization: Bearer {{apiKey}}
X-Customer-Code: {{customerCode}}

Create a Job by Executing a Job Definition​

POST https://io.conscia.ai/vue/_api/v1/job-definitions/{{jobDefinitionCode}}/_execute
Content-Type: application/json
Authorization: Bearer {{apiKey}}
X-Customer-Code: {{customerCode}}

{}

Example response:

{
  "jobId": "20240302-f3eb6180-9fc0-43c6-9fe3-528cc4981f2c"
}

Job Endpoints​

Getting a specified Job​

Ths endpoint will return the status and the result of the job.

A job status can have three possible values: STARTED, COMPLETED, and FAILED.

GET https://io.conscia.ai/vue/_api/v1/jobs/{{jobId}}
Content-Type: application/json
Authorization: Bearer {{apiKey}}
X-Customer-Code: {{customerCode}}

Scheduling Jobs​

As shown above, a Job Definition can be created with a schedule. The schedule is defined using a cron expression.

Here is a reference that will help you to format your Cron Expressions. For instance, 0 0 12 * * ? means Fire at 12pm (noon) every day.