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