jobStateChange API

Follow

Summary

The jobStateChange endpoint allows you to move jobs to different statuses, publishing events to the job history to record changes programatically.

Endpoint

/rest/workflow/job/jobStateChange

POST

Adds an event to a job specified in the call and moves it to a new status.

File Format Spec

List of included fields
Field Name Data Type Mandatory? Description
jobRef Text (6) Yes The job reference in Oneserve
clientRef Text No The reference of the client against the job in Oneserve
clientID Integer No The ID of the client against the job in Oneserve
jobStatusID Integer Yes The ID of the job status you want to move the job to
transitionNotes Text Yes The date the event was recorded
sor Text No The SOR (activity code) you want to modify
jobCost Decimal No The cost associated to the SOR code
vat Decimal No The VAT value of the cost
jobTotal Decimal No The total cost of the job
sigEventCode Text Yes The code of the event to be left in the job's history
transitionRef Text No The transition reference of a specific workflow transition. This can be used to ensure that business logic specified in a transition is followed

Request Representations

JSON payload examples
{
  "jobRef" : "J00YTG",
  "clientRef" : "",
  "clientId" : "",
  "jobStatusID" : "234",
  "transitionNotes" : "some notes",
  "sor" : "abc,123",
  "jobCost" : "34.23",
  "vat" : "12:23",
  "jobTotal" : "83.23",
  "sigEventCode" : "83.23",
  "transitionRef" : "12-345"
}
{
  "jobRef" : "J00YTG",
  "jobStatusID" : "0",
  "transitionNotes" : "Job Cancelled",
  "sigEventCode" : "CAN"
}

Available Response Representations

HTTP Code Description Schema
200 Job Status Updated "result": "success"
400 Bad Request Error
401 Unauthorized Error
403 Forbidden Error
404 Address Not Found Error
405 Method Not Allowed Error
500 Internal Server Error Error

Example Success Response

{
    "result": "success",
    "result_msg": ""
}

Troubleshooting

401 Unauthorized

Response

401 Unauthorized

Reason

This error occurs if the OS-REST-AUTH-TOKEN has not been provided, has expired, or does not exist in the system

Resolution

Verify your OS-REST-AUTH-TOKEN with support

403 Forbidden

Response

403 Forbidden

Reason

This error indicates that something is blocking your connection to the server

Resolution

Open a ticket with the support team with details of your connection so that your access can be verified

404 Not Found

Response

404 Not Found

Reason

This error should only occur if the endpoint has been mistyped in some way, which will lead the call to an endpoint that does not exist

Resolution

Verify the endpoint matches the value specified in this article

405 Method Not Allowed

Response

405 Method Not Allowed

Reason

This error will occur if an unacceptable method has been used in the call such as GET or DELETE

Resolution

Ensure that you are using a POST call to this endpoint