createJob¶

Deprecated

This endpoint will stop working on 1 August 2027. Migrate to POST /v1/jobs in the new API; the migration guide has the recommended order of work and the important model differences.

Latest legacy createJob also accepted appointmentDate + zoneType to attempt a pooled appointment booking, plus a freeform attributes section for WorkType Attributes. Neither is present in the new POST /v1/jobs body - book appointments separately via POST /v1/appointments. Contact details are no longer accepted inline.

Open POST /v1/jobs in the new API →

View legacy reference

/rest/workflow/job/createJob

POST

Adds a Job (including WorkLog, Job and Activities) and attempts to book a pooled appointment.

Changes from previous version

Attempts to book a pooled appointment based on the date/time in the appointmentDate field if that field is populated and use the zoneType in the new zoneType field.
Include the appointmentDate field (if populated) in the job creation event note.
Add job attributes.

Any attributes that are populated in the "attributes" section will be added as Job Attributes IF the name matches the name of a valid WorkTypeAttribute for the WorkType the new job is associated to.
If the name does not match a valid Work Type Attribute it will be ignored.

Ensure that if appointmentDate field, zoneType field and attributes section are missing the interface still works.

acceptable request representations:

application/json (NOTE: expects request parameter named "jobs" to contain this, i.e. jobs=<data>)

jobs={
  "jobs" : [
    {
      "clientId" : "2",
      "clientRef" : "abc123",
      "siteRef" : "abc123",
      "poiId" : "123",
      "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",
      "raisedBy" : "colin",
      "serviceID" : "21",
      "workflowID" : "3",
      "supplierID" : "4",
      "codeID" : "1",
      "resourceID" : "76",
      "eventNotes" : "a note",
      "targetDate" : "30/09/2011",
      "postcodeUse" : "0",
      "jobDuration":"150",
      //Manually sets the job duration in minutes "parentRef" : "parentRef",
      "ownerID" : "1234",
      "preferredContact" : "2",
      "causeID" : "5",
      "description" : "fix photocopier",
      "appointmentDate":"30/09/2011 08:30",
      "zoneType":"0",
      "activities": [
        {
          "activityRef" : "act123",
          "quantity" : "3",
          "description" : "optional desc",
          "supplierId" : "13" //since v.11.4 - optional activity.supplier_id "assetId" : "1234" "libraryActivityCode" : "5647",
          "siteLocation" : "Harford Court" 
        } 
      ],
      "attributes": [
        {
          "name":"Issued Date",
          "value":"12/12/2012 12:23:56" 
        } 
      ] 
    } 
  ]
}

NOTE for more information relating to the allowable values, business rules and data format for each field in the format specification see file format spec.

Field Notes

zoneType: 0 = Any, 1 = Primary Only, 2 = Primary and Secondary

available response representations:

200 - application/json

{
  "result" : "success or fail",
  "result_msg" : "error message",
  "jobs" : ['J00021', 'J00022', 'J00023'], //ref list of jobs created
  "jobVersionStatus" : ['1', '2', '3'] //list of jobs versions status
}

Exceptions:

libraryActivityCode:

If the given libraryActivityCode is not present in database for the corresponding clientId, workLogTypeId and jobCreatedDate the following error is thrown

- Could not find Library Activity Code: libActCode, clientId: clientId, wlt: workLogTypeId

ClientRef:

If the clientRef is null then the following error is thrown

- Client Ref was null.

libraryActivityCode:

If libraryActivityCode is null then the following error is thrown

- No library activity id has been supplied.

AssetId:

If the assetId is provided then its checked in the db for the same. If its not present then the following error is thrown

- Invalid asset id.

If the asset/siteLocation/site.siteId is not equal to workLog/site.siteId then the following error is thrown

- Site and asset site don't match

If the siteLocationId is not equal to asset/siteLocation.id then the following error is thrown

- Site location and asset location don't match.

workTypeID:

workTypeID field is used to find out the workType and if its not present in the database then the following error is thrown

- No work type found for ID WorkTypeId for Job Client ref ClientRef()

If workType is found but there are no associated activities for the clientRef and workTypeId then the following error is thrown

- No activities found for Job Client ref ClientRef and none associated with Work Type ID WorkTypeId.

If workTypeID is empty or null in the request then we use serviceID to get the workType and if the serviceID is empty as well then we use the activityId from the activities as serviceId to get workType

If we are not able to fetch the details of workType from db using the serviceId as well then we throw the exception

- No Work Types found for Service ID: serviceId, WLT ID: id, TT ID: tenancyTypeId

SupplierID:

If supplierID is provided we check if the provided supplier exists in db else we try to auto assign supplier and if thats unsuccessful as well then we throw the error

- Failed to auto assign supplier

See the Workflow API matrix for the full list of endpoints in this category.