createJob API

Follow

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

 

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

Job for job_client_ref could not be found

Response

{
    "result": "fail",
    "result_msg": "Job for job_client_ref could not be found."
}

Reason

This message appears if no valid clientRef has been provided

Resolution

Provide a clientRef and post the job again

WorkLog with Client Ref already exists

Response

{
    "result": "fail",
    "result_msg": "WorkLog with Client Ref already exists."
}

Reason

This message appears if the clientRef has already been used

Resolution

Provide a different clientRef, or validate whether or not the job is already in the system

Could 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

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.

Resolution

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.

String index out of range

Response

{
    "result": "fail",
    "result_msg": "String index out of range: -14"
}

Reason

This error occurs if a field has been overfilled and is too long for the API to accept

Resolution

Ensure that all fields are under the maximum length per the file format spec

No job data found to add

Response

{
    "result": "fail",
    "result_msg": "No job data found to add"
}

Reason

This error usually occurs if the job data presented in the call is improperly formatted leading to incomplete data being passed

Resolution

Validate your call using an online JSON validator to make sure everything is written correctly. Ensure that each JSON object starts with jobs={... as is required by the endpoint