Summary
Requirements
All API calls require a dedicated JSON Web Token (JWT). These are created when a user with a dedicated mobile resource logs in to the application. If you are using the API for programmatic queries, it is best to create a dedicated user for the JWT as this gets reset each time the user logs in.
Endpoint
/rest/workflow/job/createJob
POST
Adds a Job (including WorkLog, Job and Activities) and (optionally) attempts to book a pooled appointment.
This API will attempt to book a pooled appointment using the date/time passed in the appointmentDate
field in combination with the specified zoneType
. If no date is passed in this field, no appointment will be booked.
Activities and attributes can be passed as array values in the job creation call. The attributes passed must exist against the work type in order for their values to be populated.
File Format Spec
List of included fields
Field Name
Data Type
Mandatory
Description
clientRef
Text (50)
Yes
Client Job reference - stored in Oneserve Client Job Ref field
siteRef
Text (50)
Yes
The reference of the site against the job
reportedDate
Date (dd/mm/yyyy hh:mm)
Yes
The reported date of the job
contactMode
Integer (0-4)
Yes
0 – no contact
1 – use first preferred contact (or none if not available)
2 – use specified contact id
3 – use contact details specified in file (site address used to populate other contact fields on incident)
4 – use contact details specified in file and add as contact in system and attach to site – if contact already exists (sal, forename, surname, client used as key) and is on site will not add (site address used to populate other contact fields on incident)
contactRef
Text (50)
No
The Ref of the contact record to use. Only use if
contactMode
is 2. Will add contact to site if contact not already existing.
contactSal
Text (50)
No
Contact salutation. Used if
contactMode
is 3 or 4.
contactForename
Text(80)
Depends
Mandatory if
contactMode
is 3 or 4
contactSurname
Text(80)
Depends
Mandatory if
contactMode
is 3 or 4
contactC1
Text(80)
Depends
Mandatory if
contactMode
is 3 or 4
contactC1Type
Integer
Depends
The contact type for contact number 1. Mandatory if
contactMode
is 3 or 4
contactC2
Text (80)
No
Used if
contactMode
is 3 or 4.
contactC2Type
Integer
No
Used if
contactMode
is 3 or 4. The contact type for contact number 2. Index into the CType table.
contactC3
Text (80)
No
Used if
contactMode
is 3 or 4.
contactC3Type
Integer
No
Used if
contactMode
is 3 or 4. The contact type for contact number 3. Index into the CType table.
contactC4
Text (80)
No
Used if
contactMode
is 3 or 4.
contactC4Type
Integer
No
Used if
contactMode
is 3 or 4. The contact type for contact number 4. Index into the CType table.
workLogTypeID
Integer
Yes
The ID of the work log type the job is to be raised under
workTypeID
Integer
No
Work Type ID. If blank will choose first Work Type from list of WorkTypes associated to the Service.
priorityID
Integer
Yes
The ID of the job priority
description
Text (4000)
Yes
The description of the job
causeID
Integer
Yes
The ID of the job cause
raisedBy
Text (60)
No
The name of the person raising the job
serviceID
Integer
No
Service ID. If blank will take the Service ID associated to the first Activity in the list.
workflowID
Integer
No
The ID of the workflow to be used for the job. If blank the system will automatically assign the most applicable workflow
supplierID
Integer
Yes
The ID of the team to be assigned to the job.
-1
can be used to allow the system to pick the most suitable team automatically
resourceID
Integer
No
The ID of the resource to be assigned to the job
eventNotes
Text (4000)
No
Notes that will be added to the history event
targetDate
Date (dd/mm/yyyy hh:mm)
No
If this field is not null then target date on job is set using this date. Otherwise target date is set based on priority.
postcodeUse
Integer (0-2)
No
0 = All suppliers irrespective of postcode covered
1 = Postcode in Supplier’s primary list
2 = Postcode in Supplier’s primary or Secondary list
preferredContact
Integer (1-4)
Yes
The
contact
value to be set as preferred. Mandatory if contactMode
is 3 or 4.
zoneType
Integer (0-2)
No
0 = Any
1 = Primary Only
2 = Primary and Secondary
Only used if appointmentDate
is specified
codeID
Integer
No
The ID of the job code in Oneserve
jobDuration
Integer
No
Sets the job duration in minutes. Will default to duration of activities if left blank
appointmentDate
DateTime
No
Sets the appointment date for the job. If not included no appointment will be booked
activities
Array
Yes
An array of activity data. All jobs must include at least one activity
libraryActivityCode
Text (50)
Yes
The code of the activity to be used. Specified within
activities
struct
activityRef
Text (50)
No
Your unique reference for the activity. Specified within
activities
struct
description
Text (100)
No
A description of the activity. Specified within
activities
struct
quantity
Integer
Yes
The quantity of activities to be added to the job. Specified within
activities
struct
supplierId
Integer
No
The supplier to be assigned to the activity. Specified within
activities
struct
attributes
Array
No
An array of attributes to be added to the job
name
Text (50)
No
The name of the Attribute. Specified within
attributes
struct
value
Text (100)
No
The value to be assigned to the attribute. Specified within
attributes
struct
Request Representations
Example JSON Payload
jobs={
"jobs" : [
{
"clientId" : "2",
"clientRef" : "abc123",
"siteRef" : "abc123",
"reportedDate" : "12/09/2011",
"contactMode" : "2",
"contactRef" : "2342",
"contactSal" : "Mr",
"contactForename" : "Barry",
"contactSurname" : "Walters",
"contactC1" : "08767 883788",
"contactC1Type" : "1",
"contactC2" : "08767 883788",
"contactC2Type" : "1",
"contactC3" : "08767 883788",
"contactC3Type" : "1",
"contactC4" : "08767 883788",
"contactC4Type" : "1",
"workLogTypeID" : "1",
"workTypeID" : "7",
"priorityID" : "3",
"description" : "fix photocopier",
"causeID" : "5",
"raisedBy" : "colin",
"serviceID" : "21",
"workflowID" : "3",
"supplierID" : "4",
"resourceID" : "76",
"eventNotes" : "a note",
"targetDate" : "30/09/2011",
"postcodeUse" : "0",
"preferredContact" : "2",
"appointmentDate":"30/09/2011 08:30",
"zoneType":"0",
"jobDuration":"150", //Manually sets the job duration in minutes
"codeID" : "1",
"activities": [
{
"libraryActivityCode" : "5647",
"activityRef" : "act123",
"description" : "optional desc",
"quantity" : "3",
"supplierId" : "13" //since v.11.4 - optional activity.supplier_id
}
],
"attributes": [
{
"name":"Issued Date",
"value":"12/12/2012 12:23:56"
}
]
}
]
}
Example XML Payload
<?xml version="1.0" encoding="UTF-8" ?>
<jobs>
<clientRef>abc123</clientRef>
<siteRef>abc123</siteRef>
<reportedDate>12/09/2011</reportedDate>
<contactMode>2</contactMode>
<contactRef>2342</contactRef>
<contactSal>Mr</contactSal>
<contactForename>Barry</contactForename>
<contactSurname>Walters</contactSurname>
<contactC1>08767 883788</contactC1>
<contactC1Type>1</contactC1Type>
<contactC2>08767 883788</contactC2>
<contactC2Type>1</contactC2Type>
<contactC3>08767 883788</contactC3>
<contactC3Type>1</contactC3Type>
<contactC4>08767 883788</contactC4>
<contactC4Type>1</contactC4Type>
<workLogTypeID>1</workLogTypeID>
<workTypeID>7</workTypeID>
<priorityID>3</priorityID>
<description>fix photocopier</description>
<causeID>5</causeID>
<raisedBy>colin</raisedBy>
<serviceID>21</serviceID>
<workflowID>3</workflowID>
<supplierID>4</supplierID>
<resourceID>76</resourceID>
<eventNotes>a note</eventNotes>
<targetDate>30/09/2011</targetDate>
<postcodeUse>0</postcodeUse>
<preferredContact>2</preferredContact>
<appointmentDate>30/09/2011 08:30</appointmentDate>
<zoneType>0</zoneType>
<activities>
<libraryActivityCode>5647</libraryActivityCode>
<activityRef>act123</activityRef>
<description>optional desc</description>
<quantity>3</quantity>
</activities>
<attributes>
<name>Issued Date</name>
<value>12/12/2012 12:23:56</value>
</attributes>
</jobs>
Available Response Representations
HTTP Code | Description | Schema |
---|---|---|
200 | Job(s) Posted | jobs [array]jobVersionStatus [array] |
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
{
"jobs": [
"J00021",
"J00022",
"J00023"
],
"jobVersionStatus": [
1,
2,
3
],
"result": "success",
"result_msg": ""
}
Troubleshooting
This error occurs if the Verify your This error indicates that something is blocking your connection to the server Open a ticket with the support team with details of your connection so that your access can be verified 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 Verify the endpoint matches the value specified in this article This error will occur if an unacceptable method has been used in the call such as Ensure that you are using a This message appears if no valid Provide a This message appears if the Provide a different This error occurs if the activity code specified does not exist or there is no valid cost for the client and work log type specified. If the code does not exist, it will need to be created in Oneserve first. If the code does exist, a valid cost needs to be created for the client and work log type specified in the call. This error occurs if a field has been overfilled and is too long for the API to accept Ensure that all fields are under the maximum length per the file format spec This error usually occurs if the job data presented in the call is improperly formatted leading to incomplete data being passed Validate your call using an online JSON validator to make sure everything is written correctly. Ensure that each JSON object starts with 401 Unauthorized
Response
401 Unauthorized
Reason
OS-REST-AUTH-TOKEN
has not been provided, has expired, or does not exist in the systemResolution
OS-REST-AUTH-TOKEN
with support403 Forbidden
Response
403 Forbidden
Reason
Resolution
404 Not Found
Response
404 Not Found
Reason
Resolution
405 Method Not Allowed
Response
405 Method Not Allowed
Reason
GET
or DELETE
Resolution
POST
call to this endpointJob for job_client_ref could not be found
Response
{
"result": "fail",
"result_msg": "Job for job_client_ref could not be found."
}
Reason
clientRef
has been providedResolution
clientRef
and post the job againWorkLog with Client Ref already exists
Response
{
"result": "fail",
"result_msg": "WorkLog with Client Ref already exists."
}
Reason
clientRef
has already been usedResolution
clientRef
, or validate whether or not the job is already in the systemCould not find Library Activity Code (REST0015)
Response
{
"result": "fail",
"error_code": "REST0015",
"result_msg": "Could not find Library Activity Code: xxx clientId: 1 wlt: 1"
}
Reason
Resolution
String index out of range
Response
{
"result": "fail",
"result_msg": "String index out of range: -14"
}
Reason
Resolution
No job data found to add
Response
{
"result": "fail",
"result_msg": "No job data found to add"
}
Reason
Resolution
jobs={...
as is required by the endpoint