Job

A Job is a chain of Filters and Tasks, using HTTP status codes to control the flow from task to task.

When the chain of tasks reaches the "end of the line" (no other tasks to call) the Job response is created and placed in the response queue.

A Job is declared in the Job Registry. Data is not exchanged from task to task, the Job simply declares the control flow. This allows all Protocol Adapters to use Jobs in a predictable, repeatable way.

Example Job

ExampleJob:
  start: 'check-cache'
  tasks:
    'check-cache':
      task: 'meshblu-core-task-check-cache'
      cacheNamespace: 'example'
      on:
        404: 'fetch-data'
    'fetch-data':
      task: 'meshblu-core-task-fetch-data'
      databaseCollection: 'datum'

In the above example, if the response from check-cache is a 404, fetch-data will be invoked and its response will be sent to the Protocol Adapter. If instead check-cache returns a 204, the response will be sent to the Protocol Adapter and then returned to the Client.

Using Filters

A Filter is a pre-defined chain of tasks. It is defined similar to a Task, using the filter key.

AuthenticatedExample:
  start: 'authenticate'
  tasks:
    'authenticate':
      filter: 'authenticate'
      on:
        404: 'fetch-data'
    'fetch-data':
      task: 'meshblu-core-task-fetch-data'
      databaseCollection: 'datum'

In this example, when the final Task of the authenticate Filter is complete, the normal control flow will resume. If the filter reaches the "end of the line" (no other tasks to call) the Job response is created and placed in the response queue.

Anatomy of a Job

A Job is composed of metadata and data.

Metadata

Metadata is JSON that describes the information needed to process the job. There are two required fields, responseId and jobType. responseId is a unique identifier (UUID) for each request inserted into the queue. jobType must match a job described in the Job Registry. metadata may also contain arbitrary information to be used by the job, however it is recommended to store custom data in a descriptive namespaced key, e.g. device.

metadata:
  responseId: '4797b450-ad8e-47c3-b8dc-6b531fe5bdd6'
  jobType: 'ExampleJob'
  device:
    uuid: '5853ae43-2696-4b4f-9918-e16b6338c8dc'

Data

Data is an optional BLOB that contains information needed by a Job that can be parsed at the last responsible moment. This allows Meshblu to process jobs quickly, while easily allowing for arbitrarily complex datastructures, or binary data to be sent to your job.

If JSON is being sent as data, it is recommended to stringify and/or encode before sending in order to prevent Meshblu from parsing it each time the metadata is parsed.