Job

The Job object

A job can contain just a title and a description (well actually everything is optional), but is typically filled with attributes as the planning and work process progresses.

A job can consist of:

Title and/or description
Resources - users doing the work
Destinations - places to go
Work Items - work to complete, on the job or at destinations
Documents - photos and/or other documents attached as instructions or documentation
Notes and Events - a log of what has been done and possibly discrepancies (notes are actually just events)
Customer and project

Attributes

This table does not include attributes that are considered trivial or self-explanatory. See also common attributes.

Attribute	Description
allDay	If true, `startTime` and `endTime` specify dates, not timestamps.
startTime, endTime	Timestamps or dates (if `allDay` is specified).
duration	Planned work duration, in minutes. Might not be equal to `endTime - startTime`, for example if the job is part of a route and in transit-time is considered in `startTime`. If `endTime` is null and `duration` is set, it is normally assumed that `endTime = startTime + duration`.
state	State of the job. See job states.
resources.state	State of the resource. See resource states.
reported, resources.reported	If true, there is a work report referencing this job (and resource).

Example

List Item Representation

Lists of jobs do not include the following attributes:

events
signature
documents
items
customFields

States

Job state is an important concept that tells where it a job is in the workflow process. It is used to control a lot of business logic in the system.

The state of a job is determined automatically from its resources. For example, when a resource is scheduled on a job, the resource changes to SCHEDULED and so does the job. Another example: If two resources are scheduled on a job and one of the goes changes state to FINISHED while the other resource is still SCHEDULED the job will be PAUSED until the other resource is STARTED (in which case the job will also be STARTED).

Job states can also be expclicitly overridden, but as soon as a resource changes state, the job state will be updated.

Job States

INITIAL, DRAFT, PUBLISHED, ASSIGNED, SCHEDULED, IN_TRANSIT, ON_STATION, STARTED, PAUSED, FINISHED, CANCELED, CLOSED

Resource States

UNASSIGNED, DECLINED, ASSIGNED, SCHEDULED, ACCEPTED, INACTIVE, IN_TRANSIT, ON_STATION, STARTED, PAUSED, FINISHED, CANCELED

Events

Job events essentially consist of:

a timestamp,
a type,
state changes (optional),
the acting user (userId) and, if applicable, the subject user (toUserId, used i.e. when a user is scheduling another user),
and sometimes also location information.

Here's an example:

{
    "accuracy": null,
    "comment": null,
    "destinationId": null,
    "discrepancy": false,
    "eventTimeStamp": 1392822122203,
    "id": 3886455,
    "internal": false,
    "latitude": null,
    "longitude": null,
    "newResourceState": null,
    "newState": null,
    "toUserId": null,
    "type": "UPDATE",
    "userId": 2038715,
    "uuid": null
}

Event types

CREATE, PUBLISH, UNPUBLISH, UPDATE, ASSIGN, UNASSIGN, SCHEDULE, UNSCHEDULE, RESOURCE_ACTION, NOTE, REPORT, REPORT_UPDATE, INVOICE, NOT_INVOICE, CLOSE, STATE_OVERRIDE, NOTIFY_REPORT, SIGN, WORKITEM_DONE, WORKITEM_NOTDONE, ACCEPT, DECLINE, SHARE, DELETE, ADD_RESOURCE, DELETE_RESOURCE, BROADCAST, SEND_SCHEDULE, CONFIRM_DISCREPANCY, SCHEDULE_VEHICLE, UNSCHEDULE_VEHICLE, ATTACH_FORM, DETACH_FORM, COMPLETE_FORM, ATTEST, ARRIVE, DEPART, UPDATE_ITEMS, UPDATE_DOCUMENTS, ASSIGN_ASSET, UNASSIGN_ASSET

List jobs

Note: Job list entries do not contain all attributes of a Job. Some attributes, like job events, are only available when getting a specific Job by ID.

By default, the list contains all upcoming jobs that have a start time and are not finished, canceled, closed or drafts. Use query parameters to change the filter options.

There are several sets of job lists:

Paths

/job, /job/list/all	All jobs
/job/list/unassigned	Unassigned jobs
/job/list/mine	Jobs assigned or scheduled to the token user
/job/list/user/:userid	Jobs assigned or scheduled to the specified user
/job/list/customer/:customerid	Jobs by customer
/job/list/project/:projectid	Jobs by customer project
/job/list/order/:orderid	Jobs by customer order
/job/list/asset/:assetid	Jobs by asset

Query Parameters

from	List jobs from this date/time	Timestamp	2013-01-01
to	List up to this date/time	Timestamp	2013-01-05
states	Comma-separated list of job states to include, except if fetching `mine` or `user/:userid` lists, then it is a list of resource states. Default: all states but DRAFT, FINISHED, CANCELED, CLOSED.	List	DRAFT,PUBLISHED,SCHEDULED
untimed	Include jobs that have no start time	Flag
current	Include unfinished jobs even though their start time is before `from`	Flag
limit	Limit the number of returned objects	Integer
offset	Skip the first N objects	Integer
modified	Include only objects modified since this date/timestamp	Timestamp	2015-10-05

Example

GET /job

Response

A list of job list items

Method: GET
URL: /job/list/...
Authentication: Token
Response: Array of JobListItem

Search jobs

Search jobs. Please note that the search representation contains only a subset of the detail and list representations.

Query Parameters

Search query. Required. The default search behavior is an ElasticSearch query, each search term ORed, with some fields boosted.

A query that starts with the # character searches the jobNo field.
Example: #123
A query that starts with the ! character is treated as a raw ElasticSearch DSL Query String query, which can be used to satisfy a lot of different search needs.
Example: !labels:transport AND state:FINISHED
See the ElasticSearch documentation for more information.

Example

GET /job/search?q=transfer+rocks
Content-type: application/json

Method: GET
URL: /job/search
Authentication: Token
Response: JobSearchEntry object

Get a job

Get a specific job by ID or UUID

Example

GET /job/123456

Response

A job object.

Method: GET
URL: /job/:id
Authentication: Token
Response: Job object

Create a job

Create a job. The job will be assigned a server-generated ID and UUID.

Example

POST /job

{
	"title": "Clean garage floor"
}

Response

The created job object.

Method: POST
URL: /job
Authentication: Token
Request: Job object
Response: Job object

Update or create a job

Update an existing job or create it (if it doesn't exist and :id is a UUID).

Example

PUT /job/0847ed17-b060-4599-a38c-be9a8b9cbb34

{
	"title": "Clean garage floor",
	"description": "Use mop"
}

Response

The updated job object.

Method: PUT
URL: /job/:id
Authentication: Token
Request: Job object
Response: Job object

Delete a job

Delete a job.

Example

DELETE /job/0847ed17-b060-4599-a38c-be9a8b9cbb34

Method: DELETE
URL: /job/:id
Authentication: Token
Response: Status code only

Additional content

Add a note to a job

Post a note to a job.

Note: Job notes are really just job events, so in order to get them, get the job's events and filter out those with type="NOTE".

Example

POST /job/123456/note
Content-type: application/x-www-form-urlencoded

text=OMG+I+forgot+her+birthday!&discrepancy

Form Parameters

text	Note content	String	Hello World!
discrepancy	This note is a discrepancy	Flag

Method: POST
URL: /job/:id/note
Authentication: Token
Request: Form
Response: Status code only

Link to an external document on a job

To attach/link to an external document, accessible by a URL (i.e. a document uploaded to Dropbox or similar storage service), update the documents list of the job.

Example

PUT /job/123456
Content-type: application/json

{
	"documents": [
		{
			"contentUrl": "http://www.cbu.edu.zm/downloads/pdf-sample.pdf", 
			"mimeType": "application/pdf", 
			"fileName": "pdf-sample.pdf",
			"description": "Very important instructions"
		}
	]
}

The example above adds the URL as a "document" on the job. The mimeType property ensures the correct icon is displayed (you can also use the thumbUrl property to specify your own).

Upload and attach a document to a job

This operation is divided into two or (optionally) three requests:

Upload the document content (i.e. an image or PDF file),
(Optional) Update the document meta data (i.e. description),
Attach the document to the job.

1. Upload the document content

The actual document content (the image, PDF file or whatever) is uploaded using a standard (multipart/form-data) file upload using file as the form parameter name.

POST /document/content
Content-type: multipart/form-data

Example using curl

curl -i 'https://app.coredination.net/api/1/document/content' \
	-H 'API-Key: {my-api-key}' \
	-F file=@myimage.jpg

HTTP/1.1 100 Continue

HTTP/1.1 200 OK
Content-Type: application/json
{
  "success": true,
  "document": {
    "uuid": "8acac590-cc94-45aa-a237-18a9d268f431",
    "thumbUrl": "/vault/thumbnail/8acac590-cc94-45aa-a237-18a9d268f431",
    "size": 7911,
    "mimeType": "image/jpeg",
    "lastModified": 1447890986622,
    "contentUrl": "/vault/document/8acac590-cc94-45aa-a237-18a9d268f431",
    "creationTimeStamp": 1447890986484,
    "creatorId": null,
    "description": null,
    "fileName": "myimage.jpg",
    "groupId": 17,
    "id": 26174165,
    "internal": false
  }
}

The response should contain the success flag set to true, indicating that the upload and backend storage was successful. It also contains the Document (meta data entity) itself, which you later need to refer to, so hang on to its UUID from here on.

Method: POST
URL: /document/content
Authentication: Token
Response: Upload DTO

2. (Optional) Update the document meta data

If you want to change any of the meta data (i.e. description, filename, the internal flag) of the document, you can update it using a PUT request:

Example

PUT /document/8acac590-cc94-45aa-a237-18a9d268f431
Content-type: application/json

{
	"description": "Top secret map of job site",
	"internal": true
}

The response will contain the updated document (meta data).

Method: PUT
URL: /document/:did
Authentication: Token
Response: Document object

3. Attach the document to the job

Attaching the document is a simple PUT request without content.

Example

PUT /job/cbfc4b6f-ee81-4591-8e88-fd359cb2f967/document/8acac590-cc94-45aa-a237-18a9d268f431

The response has no content and should just return status code 200 (OK).

Method: PUT
URL: /job/:id/document/:did
Authentication: Token
Response: Status code only

Detach a document from a job

Detaching a document from a job is a simple DELETE request without content.

Example

DELETE /job/cbfc4b6f-ee81-4591-8e88-fd359cb2f967/document/8acac590-cc94-45aa-a237-18a9d268f431

The response has no content and should just return status code 200 (OK).

Method: DELETE
URL: /job/:id/document/:did
Authentication: Token
Response: Status code only

List job events

List events on a job. Note that events are also included if you get a job by ID.

Example

GET /job/123456/events

Response

[
  {
    "vehicleId": null,
    "uuid": null,
    "userId": null,
    "type": "CREATE",
    "toUserId": null,
    "newState": "DRAFT",
    "newResourceState": null,
    "longitude": null,
    "accuracy": null,
    "comment": null,
    "destinationId": null,
    "discrepancy": false,
    "eventTimeStamp": 1446832802321,
    "id": 26066013,
    "internal": false,
    "latitude": null
  }
]

Method: GET
URL: /job/:id/events
Authentication: Token
Response: Array of JobEvent

Job resource operations

Schedule a user on a job

Schedule a user as a resource on a job.

Query Parameters

userId	ID or UUID of user, or `me`	ID	me
sendMessage	Send a message to the user	Flag

Example

PUT /job/0847ed17-b060-4599-a38c-be9a8b9cbb34/schedule?userId=dd738c3a-5a66-4f1c-bc03-52d2f4c03913&sendMessage

Method: PUT
URL: /job/:id/schedule
Authentication: Token
Response: Status code only

Unschedule a user from a job

Unschedule a user as a resource from a job.

Query Parameters

userId	ID or UUID of user, or `me`	ID	me
sendMessage	Send a message to the user	Flag

Example

PUT /job/0847ed17-b060-4599-a38c-be9a8b9cbb34/unschedule?userId=dd738c3a-5a66-4f1c-bc03-52d2f4c03913&sendMessage

Method: PUT
URL: /job/:id/unschedule
Authentication: Token
Response: Status code only

Assign a user on a job

Assign a user as a resource on a job.

Query Parameters

userId	ID or UUID of user, or `me`	ID	me
sendMessage	Send a message to the user	Flag

Example

PUT /job/0847ed17-b060-4599-a38c-be9a8b9cbb34/assign?userId=dd738c3a-5a66-4f1c-bc03-52d2f4c03913&sendMessage

Method: PUT
URL: /job/:id/assign
Authentication: Token
Response: Status code only