Order

The Order object

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

An order can consist of:

Title and/or description
Customer, project, contact(s) etc
Job specification(s), detailing:
- job content, the work that is to be carried out/delivered, a subset of the job object
- recurring interval(s), for repeated job creation
Documents - photos and/or other documents attached as instructions or documentation
Events - a log of what has been done with the order

When job(s) are scheduled for an order, the job is filled in with information from the order and the respective job specification.

Attributes

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

Attribute	Description
state	State of the order. See order states.

Example

List Item Representation

Lists of orders do not include the following attributes:

jobSpecifications
events
documents
contacts
customFields

States

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

The state of an order is determined automatically from its jobs. For example, when an order is first created, its state will be PENDING. When a job is created, the order will be PUBLISHED. When that job is scheduled, the order will become SCHEDULED. When the job is started, the order will be ACTIVE, and when the job is finished, the order will finally be DELIVERED.

Order states can also be expclicitly overridden.

Order States

INITIAL, DRAFT, INACTIVE, PENDING, CONFIRMED, PUBLISHED, SCHEDULED, ACTIVE, DELIVERED, CANCELED

Events

Order 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:

{
	"comment": null,
	"discrepancy": false,
	"eventTimeStamp": 1417910852394,
	"id": 41949333,
	"internal": false,
	"jobEvent": null,
	"jobId": null,
	"newState": "PUBLISHED",
	"type": "UPDATE",
	"userId": 2038612
}

Event types

CREATE, UPDATE, DELETE, JOB_CREATE, JOB_ACTION, NOTE

List orders

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

Paths

/order, /order/list/all	All orders
/order/list/mine	Orders created by me, or where "orderer" is set to me
/order/list/customer/:customerid	Orders by customer
/order/list/project/:projectid	Orders by customer project
/order/list/asset/:assetid	Orders by asset

Query Parameters

from	List orders from this date/time	Timestamp	2013-01-01
to	List up to this date/time	Timestamp	2013-01-05
states	Comma-separated list of order states to include	List	DRAFT,PUBLISHED,SCHEDULED
untimed	Include orders that have no start time	Flag
current	Include unfinished orders 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 /order

Response

A list of order list items

Method: GET
URL: /order/list/...
Authentication: Token
Response: Array of OrderListItem

Search orders

Search orders. 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 orderNo 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:DELIVERED
See the ElasticSearch documentation for more information.

Example

GET /order/search?q=ac+unit
Content-type: application/json

Method: GET
URL: /order/search
Authentication: Token
Response: OrderSearchEntry object

Get an order

Get a specific order by ID or UUID

Example

GET /order/123456

Response

An order object.

Method: GET
URL: /order/:id
Authentication: Token
Response: Order object

Create an order

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

Example

POST /order

{
	"title": "Clean garage floor"
}

Response

The created order object.

Method: POST
URL: /order
Authentication: Token
Request: Order object
Response: Order object

Update or create an order

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

Example

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

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

Response

The updated order object.

Method: PUT
URL: /order/:id
Authentication: Token
Request: Order object
Response: Order object

Delete an order

Delete an order.

Example

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

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

Additional content

Link to an external document on an order

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 order.

Example

PUT /order/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 order. 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 an order

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.

For step 1 and 2, see attaching a document to a job, the steps are identical for orders.

3. Attach the document to the order

Attaching the document is a simple PUT request without content.

Example

PUT /order/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: /order/:id/document/:did
Authentication: Token
Response: Status code only

Detach a document from an order

Detaching a document from an order is a simple DELETE request without content.

Example

DELETE /order/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: /order/:id/document/:did
Authentication: Token
Response: Status code only