Integrating with Documents

This guide will provide an overview of how documents are used in Mobiledock and will cover the process required to integrate.

Before proceeding, it is recommended that you follow the instructions in the integration setup guide.

Overview

In Mobiledock, a document is a record of a pre-determined reason to visit a Mobiledock-controlled site. Most commonly, documents are used to model a Purchase Order (PO), an Advanced Shipping Notice (ASN) or Work Order, though they can be used in many other ways.

Benefits of Documents

By providing Mobiledock with information about the pre-determined reasons to visit, as documents, the following benefits can be realised:

It is ensured that individuals creating a booking have a valid reason to be on site
Less data is required to be provided by the booker, as much of it can be pre-filled
Earlier visibility of specific orders, to enable better resource planning

Included on a Document

A document will typically be sent to Mobiledock with the following information:

Details of the supplier, receiver and carrier (if known)
Details of the load (i.e. quantity of each unit)
Valid dates to service the document
Whether or not the booker is able to deviate from the number of units descriped on the document (i.e. partial shipment)

The anatomy of a document is described in additional detail later in this guide.

Requirements

To integrate with Mobiledock documents, the following requirements should be met:

Your organisation has API access, location functionality and document functionality enabled by your account manager
You have created an API token with the permissions of Document Observation and Document Management
You have a working Mobiledock configuration, and have connections with suppliers, receivers and carriers, where applicable

REST Endpoint

The root endpoint of the REST API is /api/v2.

This should be appended to the base URL, specific to the environment that you are working with.

Creating a Document

Anatomy of a Document

Documents use the DocumentInput object.

ID

This is the unique identifier of the document, which will be entered by users creating a booking at your site.

Direction

The direction can be either Inbound or Outbound, depending of the nature of the visit.

Occupant, Offsite and Carrier

Note: if the direction of the document is Inbound, then the offsite is the sender and the occupant is the receiver. If the direction of the document is Outbound, then the occupant is the sender and the offsite is the receiver.

The occupant, offsite and carrier are all references to an organisation in Mobiledock. It is a requirement that 1 or more of these organisations is defined on a document.

When using the REST API, a Mobiledock organisation should be referenced by a unique Core ID. This is the ID that this organisation would be known by, in your system. Mobiledock keeps this mapping between Mobiledock organisations and your system.

Loads

Loads model the units that are related to this document. Any number of loads can be defined as part of a document.

Each line contains the following information:

Property	Description
Load Type	The type of load. This can be referenced by name or ID.
Quantity	The number of units for this line.
Load Tag (Optional)	An optional identifier for this line. This could be an SKU, for example.

Document Mode

Document mode determines how a document can be booked agains. Currently there are two supported modes, but more will be added in future.

Mode	Description
Free	The load may be modified by a user booking against this document.
Fixed	The load cannot be modified by a user booking against this document.
Flexible	The load quantities may be modified by a user booking against this document, however they will be unable to modify the types of loads.

Valid Dates

Document valid dates dictate the time in which a booking can be scheduled for, where the document is referenced. Both the begin and end dates are optional. If a booking is scheduled outside of the valid dates, it can be submitted for manual review.

Preferred Dates

Document preferred dates indicate preferred delivery dates to users when making a booking under this document. These dates have no bearing on whether or not a booking can be automatically approved. Both the begin and end dates are optional.

Max Uses

If applicable, the number of bookings that can be created against a document can be restricted. Bookings that are pending approval or cancelled do not count towards this limit.

Description

This is an optional description that can be added. It is displayed to the user when booking, and additionally on the booking confirmation screen.

Attributes

Attributes are an optional key-value store to keep additional information that may be helpful for integration. Attributes are not displayed to the user when booking, though they are displayed on the booking confirmation screen.

Status

A document status is an optional piece of information, that can denote what state a document is in. Document Status is not displayed to the user when booking, though it is displayed on the booking confirmation screen. Statuses are most commonly used to denote transient states, such as High Priority or Low Priority.

Type

A document type is an optional piece of information, that can denote what type a document is. Document Type is not displayed to the user when booking, though it is displayed on the booking confirmation screen. Types are particularly useful when sending through multiple types of documents, such as PO and ASN.

Example Payload

In this example, we are adding a document to an organisation with an ID of c10d7362-4d1f-40c3-87e3-dd46f93590cb.

{
  "id": "PO-2000",
  "direction": "Inbound",
  "occupant": {
    "id": "c10d7362-4d1f-40c3-87e3-dd46f93590cb"
  },
  "offsite": {
    "coreName": "SUPPLIER",
    "coreId": "0001"
  },
  "loads": [
    {
      "name": "Cartons",
      "quantity": 500,
      "loadTag": "SKU-199"
    },
    {
      "name": "Cartons",
      "quantity": 1000,
      "loadTag": "SKU-094"
    }
  ],
  "settings": {
    "mode": "Fixed",
    "maxUses": 1
  },
  "validDates": {
    "begin": "2024-09-01T21:00:00Z",
    "end": "2024-10-01T21:00:00Z"
  },
  "preferredDates": {
    "end": "2024-09-15T21:00:00Z"
  },
  "attributes": {
    "PRIORITY": "1",
    "SUPPLIER_CATEGORY": "03"
  },
  "status": {
    "name": "High Priority"
  },
  "type": {
    "name": "PO"
  }
}

In the above payload, we have modelled a Purchase Order (PO) PO-2000 with the following information & constraints:

The shipment is an inbound delivery.
The shipment is for 500 cartons with an SKU of SKU-199 and 1000 cartons with an SKU of SKU-094. Due to the mode being Fixed, when booking against this document, the loads/quantities cannot be changed. It will be brought in as-is.
The sender of the shipment has a connection core details of of coreName: SUPPLIER and coreId: 0001.
The receiver of the goods is simply the organisation that the document is being created under, and can easily be referenced by ID.
The carrier has not been specified, as this information is not known.
Only 1 booking can be created against this document.
Bookings against this document can only occur between 1st September, 2024 at 21:00 (UTC) to 1st October, 2024 at 21:00 (UTC).
Bookings against this document are preferred before 15th September, 2024 at 21:00 (UTC).
A simple set of attributes, PRIORITY and SUPPLIER_CATEGORY, have been added as additional information, though this data has no bearing on Mobiledock behaviour.
The document is High Priority as denoted by its status.
The document is a Purchase Order as denoted by its type.

Submitting a Document

_Note: if you are submitting many documents at once, it is recommended to use the more efficient Batch Document Job end point.

Once a valid payload has been constructed, it is ready to send to Mobiledock.

The recommended method is to use the upsert operation. This will either update an existing document if it already exists, or create a new one if it doesn't.

For example, in the Production environment if you want to add a document to the organisation with ID 990090c9-7506-487b-9872-c4e65557ae75, the payload should be sent via an HTTP PUT request to the following URL:

https://my.mobiledock.com/api/v2/organisations/990090c9-7506-487b-9872-c4e65557ae75/documents/PO-2000?upsert=true

Handling Unmatched Core Details

By default, the API rejects documents when the Core ID and Core Name do not match an existing connection. However, a new organisation can be created when details can't be matched.

You can enable this feature by adding enableBase=true to the query string. For example:

https://my.mobiledock.com/api/v2/organisations/990090c9-7506-487b-9872-c4e65557ae75/documents/PO-2000?upsert=true&enableBaseOrgs=true

HTTP Status Codes

Status Code	Description
200	The document has been successfully updated.
201	The document has been successfully created.
400	There is an issue with the payload. Details can be found in the response body.

Document Batch Jobs

Document batch jobs are an efficient way of submitting large amounts of documents to Mobiledock at once. A single payload can be sent containing many documents, and the job will then be processed asynchronously on Mobiledock servers.

Submitting a Document Batch Job

The payload of a batch job is a JSON array containing documents as described above. It should be sent via an HTTP POST request to the endpoint /api/v2/organisations/:organisation_id/document-jobs/.

All documents sent through this endpoint will automatically use the upsert method.

Unmatched core details can be handled just like when submitting a single document by appending enableBase=true to the query string. To set the location's self core id use selfCoreId=. For example:

https://my.mobiledock.com/api/v2/organisations/990090c9-7506-487b-9872-c4e65557ae75/documents/document-jobs?enableBaseOrgs=true&selfCoreId=DC

HTTP Method	Endpoint	Description
GET	`/api/v2/organisations/:organisation_id/document-jobs/`	Retrieve a list of all document batch jobs
GET	`/api/v2/organisations/:organisation_id/document-jobs/:batchId`	Retrieve detailed information for a specific document batch job
GET	`/api/v2/organisations/:organisation_id/document-jobs/:batchId/result`	Retrieve the final results of a completed document batch job
DELETE	`/api/v2/organisations/:organisation_id/document-jobs/:batchId`	Cancel a document batch job that is currently in progress

Deleting a Document

Deleting a document ensures that no additional bookings can be created against it. In the example of a document modelling a PO, deleting could be done in response to the PO being cancelled, or being closed due to fulfilment.

To delete a document, send an HTTP DELETE request to the resource location.

Bookings that have already been created against a now-deleted document will still have visibility of the document.

HTTP Status Codes

Status Code	Description
200	The document has been successfully deleted.

Fetching a Document

To fetch a document, send an HTTP GET request to the resource location. A GET request will provide additional information about the linked resources. View an example payload below:

{
  "id": "PO-2000",
  "direction": "Inbound",
  "occupant": {
    "id": "990090c9-7506-487b-9872-c4e65557ae75",
    "name": "Mobliedock Warehouse",
    "timezone": "Australia/Melbourne",
    "address": {
      "address1": "150 Albert Rd",
      "country": "Australia"
    }
  },
  "offsite": {
    "id": "990090c9-7506-487b-9872-c4e65557ae75",
    "name": "Supplier A",
    "timezone": "Australia/Melbourne",
    "address": {
      "address1": "Flinders St",
      "country": "Australia"
    },
    "connectionAttributes": {
      "SUPPLIER_ID": "0001"
    }
  },
  "loads": [
    {
      "id": "8e9f4814-3801-4665-ab5b-8deeb98d1fc2",
      "name": "Cartons",
      "quantity": 500,
      "loadTag": "SKU-199"
    },
    {
      "id": "8e9f4814-3801-4665-ab5b-8deeb98d1fc2",
      "name": "Cartons",
      "quantity": 1000,
      "loadTag": "SKU-094"
    }
  ],
  "settings": {
    "mode": "Fixed",
    "maxUses": 1
  },
  "validDates": {
    "begin": "2023-06-19T21:00:00Z"
  },
  "attributes": {
    "PRIORITY": "1",
    "SUPPLIER_CATEGORY": "03"
  },
  "status": {
    "id": "dba95174-13bc-4ae2-9224-58ebfed4e841",
    "name": "High Priority"
  },
  "type": {
    "id": "2eb8c992-0a01-47bf-8299-7e9317124290",
    "name": "PO"
  }
}

HTTP Status Codes

Status Code	Description
200	The document has been successfully fetched.

Next Steps

To learn more about documents, visit the Documents REST API Specification and the Documents GraphQL API Specification.

If after reading this guide you have any further questions, please don’t hesitate to contact us at assistance@mobiledock.com.

Overview​

Benefits of Documents​

Included on a Document​

Requirements​

REST Endpoint​

Creating a Document​

Anatomy of a Document​

ID​

Direction​

Occupant, Offsite and Carrier​

Loads​

Document Mode​

Valid Dates​

Preferred Dates​

Max Uses​

Description​

Attributes​

Status​

Type​

Example Payload​

Submitting a Document​

Handling Unmatched Core Details​

HTTP Status Codes​

Document Batch Jobs​

Submitting a Document Batch Job​

Other Document Batch Job Endpoints​

Deleting a Document​

HTTP Status Codes​

Fetching a Document​

HTTP Status Codes​

Next Steps​

Overview

Benefits of Documents

Included on a Document

Requirements

REST Endpoint

Creating a Document

Anatomy of a Document

ID

Direction

Occupant, Offsite and Carrier

Loads

Document Mode

Valid Dates

Preferred Dates

Max Uses

Description

Attributes

Status

Type

Example Payload

Submitting a Document

Handling Unmatched Core Details

HTTP Status Codes

Document Batch Jobs

Submitting a Document Batch Job

Other Document Batch Job Endpoints

Deleting a Document

HTTP Status Codes

Fetching a Document

HTTP Status Codes

Next Steps