RESTful Job Control
A recipe for supporting general workflow management for independent service interfaces
This profile provides a basic set of actions and metadata for orchestrating independent services on the open web.
Each job contains one or more tasks. The set of tasks in each job MUST be able to run in parallel. Each task SHOULD be repeatable and reversible. Each job SHOULD be restartable and reentrant.
To run a job, the job document should be submitted to a workflow engine. Upon recieving the document the workflow engine will return a
202 Accepted while the tasks are processed and will eventually return a
200 OK or a
4xx/5xx HTTP status with the completed response. Upon completion of a job, that job document MAY be archived for future reference (or re-execution) and the appropriate link (
jobFailedURL) SHOULD be activated.
Compliant Workflow engines MUST be prepared to handle the
taskRerunURL properties as well as monitor/update progress via
jobStatus. The engines SHOULD also monitor the
taskMaxTTL values and cancel jobs where the maximum run time has been exceeded.
Tasks that need to be run in a fixed sequence MUST be separated into individual job documents and those job documents can be run in fixed order as each job successfully completes.
NOTE: Workflow authoring services MAY be separate from workflow execution services. The editor and the engine don't need to be hosted within the same service interface.
For more on RESTful Job Control see RESTful Web API Patterns and Practices Cookbook.
- Application State Diagram
- Semantic Descriptors
- doJobCancel (idempotent), Request to cancel this outstanding job (using DELETE)
- doJobContinue (idempotent), Request to contineu this job from where it last left off
- doJobCreate (idempotent), Create a new job record.
- doJobFailed (idempotent), Navigate to the failed resource
- doJobRemove (idempotent), remove job record (via DELETE).
- doJobRestart (idempotent), Request to restart this job from teh beginning
- doJobSuccess (idempotent), Navigate to the delayed response resource
- doJobUpdate (idempotent), Update existing job item resource
- doTaskCancel (idempotent), Cancel the task
- doTaskRerun (idempotent), Force rerun the task
- doTaskRollback (idempotent), Rollback the task
- doTaskStart (idempotent), Start a task
- doTaskUpdate (idempotent), Update the task
- goHome (safe), Navigate to the home resource
- goJobFilter (safe), Filter the jobs list resource
- goJobItem (safe), Navigate to the job item resource
- goJobList (safe), Navigate to the jobs resource
- home (semantic), Home resource
- jobCancelled (semantic), Cancelled job resource
- jobCancelURL (semantic), URL to cancel this job
- jobContinueURL (semantic), URL to continue this job where it last left off.
- jobDateCreated (semantic), Indicates the date/time (UTC) this resource was first created).
- jobDateUpdated (semantic), Indicates the last date/time (UTC) this resource was modified).
- jobDescription (semantic), Human-readable text that describes this document.
- jobFailed (semantic), Failed job resource
- jobFailedURL (semantic), URL to follow after a failed job run of this job resource
- jobID (semantic), unique identifier for this job resource.
- jobItem (semantic), Job item resource
- jobList (semantic), Job list resource
- jobMaxTTL (semantic), Indicates the maximum amount of time (in seconds) this resource is considered valid.
- jobRecord (semantic), A job record (which has a collection of tasks)
- jobRestartURL (semantic), URL to restart this jobfrom the very beginning.
- jobStatus (semantic), Indicates resource status (pending, working, completed, failed)
- jobSuccess (semantic), Successful job completion resource
- jobSuccessURL (semantic), URL to follow after successful completion of this job resource
- jobURL (semantic), URL of this job resource document
- stateID (semantic), unique identifier for the state resource for this job.
- taskCancelURL (semantic), URL to cancel task
- taskDescription (semantic), Human-readable text that describes this task.
- taskID (semantic), unique identifier for this task.
- taskMaxTTL (semantic), Indicates the maximum amount of time (in seconds) this task is considered valid.
- taskMessage (semantic), Human-readable text that contains any messages related to the task.
- taskRecord (semantic), A task record (part of a job)
- taskRerunURL (semantic), Forced Rerun URL of the task
- taskRollbackURL (semantic), Rollback URL of the task
- taskStartDateTime (semantic), Indicates the date/time (UTC) processing started.
- taskStartURL (semantic), Starting URL of the task
- taskStatus (semantic), Indicates resource status (pending, working, completed, failed)
- taskStopDateTime (semantic), Indicates the date/time (UTC) processing stopped).
- taskURL (semantic), URL of the task resrouce