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:

  • event
  • 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

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

Upload and attach a document to a job

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

  1. Upload the document content (i.e. an image or PDF file),
  2. (Optional) Update the document meta data (i.e. description),
  3. 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