Reporting on Bookings (GraphQL)

Note: This guide uses the BookingsFilterInputV2 object, which offers additional functionality compared to the previous version.

This guide provides an overview of how bookings are managed in Mobiledock using the GraphQL API. It covers the steps required to integrate with the booking system, including querying and filtering bookings based on various criteria.

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

Overview

In Mobiledock, a booking represents a scheduled visit to a Mobiledock-controlled site. This guide focuses on interacting with the booking system via GraphQL, equipping you with the tools to report on and view bookings.

Benefits of Booking Integration

By integrating with Mobiledock's booking system through GraphQL, you can:

Retrieve real-time booking data to improve operational planning and resource allocation.
Filter and sort bookings based on various criteria.
Access detailed booking information, tailored to your specific needs.

Requirements

To integrate with Mobiledock bookings using GraphQL, the following requirements must be met:

Your organisation must have API access.
You have created an API token with the BookingObservation permission.
You have a working Mobiledock configuration that includes bookings.

Composing a Bookings Query

The primary operation for retrieving bookings is the bookingsV2 query. This query allows you to search for bookings that meet specific criteria. The return value is the BookingQuery object. Since GraphQL allows customisation, you can tailor the properties returned to fit your specific use case.

Below is the structure of the bookings query and the available filters you can apply.

Anatomy of a Bookings Query

Ordering

Booking results can be ordered by a specific field. The available ordering options are described below:

Ordering Option	Description
`Time`	Bookings will be ordered by the booking date and datetime.
`Created`	Bookings will be ordered by their creation datetime.
`Modified`	Bookings will be ordered by their last modification datetime.

By default this property is equal to Time

Ascending

This is a boolean value that determines whether to sort the ordering property in ascending or descending order. Defaults to true.

If true, bookings will be returned in ascending order based the ordering property.
If false, they will be returned in descending order based the ordering property.

Count and Start

Note: the maximum number of bookings allowed to be queried at once is 1000, a limit enforced by the API.

Count and start allow you to paginate through large datasets.

count specifies how many bookings to fetch.
start specifies the index from which sorted booking to begin counting, starting at 0.

For example, a query with count=50 and start=100 would fetch 50 bookings, starting from the 101st booking (index 100) and ending at the 150th booking (index 149).

Filter

The filter is an object that allows the application of specific criteria to the booking query. More details are provided in the following sections.

The Filter Property

_Note: This guide uses the BookingsFilterInputV2 object.

The filter property is the most complex and powerful parameter when querying bookings. All filter properties are optional and can be used simultaneously in any combination, allowing you to refine the search for bookings that match specific criteria.

Breakdown of Filter Inputs

Below is a brief overview of the available filter inputs, what they mean, and their input type. More details of each input type can be found in the following sections.

Filter Input	Description	Input Type
`activeTime`	Filter bookings by their active time, which is the time period between their scheduled start and scheduled end time.	`Comparison`
`area`	Filter bookings by specific areas, either by name or ID.	`EntityRefComparisonInput`
`bookingOption`	Filter bookings by their booking options, using either its name or ID.	`EntityRefComparisonInput`
`carrier`	Filter bookings by the carrier’s name or ID.	`EntityRefComparisonInput`
`createdTime`	Filter bookings by the creation datetime.	`Comparison`
`document`	Filter bookings that use specific documents by name or ID.	`EntityRefComparisonInput`
`documentStatus`	Filter bookings by the document status.	`EntityRefComparisonInput`
`documentType`	Filter bookings by the document type.	`EntityRefComparisonInput`
`fieldValue`	Filter bookings based on custom fields using the `FieldValueFilterInput` object.	`[FieldValueFilterInput!]`
`group`	Filter bookings by groups associated with the booking.	`EntityRefComparisonInput`
`loadQuantity`	Filter bookings by the quantity of specific loads using the `LoadQuantityFilterInput`.	`[LoadQuantityFilterInput!]`
`loadTag`	Filter bookings based on load tags.	`Comparison`
`location`	Filter by the booking location’s name or ID.	`EntityRefComparisonInput`
`modifiedTime`	Filter bookings by the last modified datetime.	`Comparison`
`occupant`	Filter bookings by the occupant’s name or ID.	`EntityRefComparisonInput`
`offsite`	Filter bookings by the offsite’s name or ID.	`EntityRefComparisonInput`
`participant`	Filter bookings by participants involved, either by name or ID.	`EntityRefComparisonInput`
`space`	Filter bookings based on the space they are assigned to, using name or ID.	`EntityRefComparisonInput`
`status`	Filter bookings by the booking status, using name or ID.	`EntityRefComparisonInput`
`vehicle`	Filter bookings by the vehicle’s name or ID.	`EntityRefComparisonInput`

The Base Comparison Object

Many of the filters revolve around the Comparison object, which allows you to perform detailed comparisons on a range of operations. These comparisons provide greater flexibility in querying bookings by specifying how values should be matched, whether through equality, range, or inclusion in a list.

You can apply multiple comparison types within a single filter to achieve more complex queries. Below are the available comparison types:

Comparison Type	Description
`eq`	Matches if the field is equal to the specified value.
`gt`	Matches if the field is greater than the specified value.
`gte`	Matches if the field is greater than or equal to the specified value.
`in`	Matches if the field is included in the specified list of values.
`lt`	Matches if the field is less than the specified value.
`lte`	Matches if the field is less than or equal to the specified value.
`match`	Matches if the field value contains the specified pattern (like operator).
`neq`	Matches if the field is not equal to the specified value.
`nin`	Matches if the field is not included in the specified list of values.

Other Input Objects

Other filter inputs are built on top of the base Comparison object.

Here are the breakdowns of EntityRefComparisonInput, LoadQuantityFilterInput, FieldValueFilterInput, and EntityRefInput:

EntityRefComparisonInput

The EntityRefComparisonInput object is used to filter bookings by either the id or name of a referenced entity, such as a carrier, location, or document. Each field uses the Comparison object to specify the comparison type.

Field	Description	Input Type
`id`	Compare by the entity’s UUID.	`Comparison`
`name`	Compare by the entity’s name (case-insensitive).	`Comparison`

Note: Although the EntityRefComparisonInput allows searches by name or by ID, when possible it is recommended to always search by ID for more reliable results (e.g., when the name of an area changes or if there are multiple carriers with the same name).

LoadQuantityFilterInput

The LoadQuantityFilterInput object allows filtering based on the quantity of specific loads in a booking. It compares both the load type and its quantity using the EntityRefInput and Comparison objects.

Field	Description	Input Type
`load`	The load type to filter by, using its ID or name.	`EntityRefInput`
`quantity`	The quantity of the load to compare.	`Comparison`

FieldValueFilterInput

The FieldValueFilterInput object is used to filter bookings based on custom fields and their values. The field is identified by an EntityRefInput and the value is compared using the Comparison object.

Field	Description	Input Type
`field`	The custom field to filter by, identified by name or ID.	`EntityRefInput`
`value`	The value to compare in the custom field.	`Comparison`

These tables offer clear definitions of the input objects used for more specific filtering, such as by load quantities or custom field values.

EntityRefInput

The EntityRefInput object is used to reference entities such as locations, carriers, and custom fields in filters. You can filter by either the entity's id or name.

Field	Description	Input Type
`id`	The entity’s unique identifier (UUID).	`UUID`
`name`	The entity’s name (case-insensitive).	`String`

The Booking Query Object

The return value of this query is the BookingQuery object, which contains details of bookings results as well as the Booking object.

The Booking object represents a single booking and allows you to specify the fields you want to retrieve in your GraphQL queries. You can customise the response by selecting relevant fields such as vehicle, status, and location to format the results as needed.

For a complete overview of the available options, read about the booking object specification.

Example Query

Below is an example of a simple query that uses different types of Comparison and EntityRefComparisonInput objects:

query GetBookings {
  bookingsV2(
    count: 500
    start: 0
    filter: {
      location: { id: { eq: "61b0d4c9-41f3-432a-420f-3f69c00a344f" } }
      area: { name: { in: ["West Docks", "South Docks"] } }
    }
  ) {
    results
    bookings {
      id
      bookingType
      createdAt
      modifiedAt
      requestedTime
      bookedTime
      duration
      carrier {
        name
      }
      space {
        name
      }
      area {
        name
      }
      location {
        name
        description
      }
      vehicle {
        name
        size
      }
      fields {
        field {
          label
        }
        value
      }
      status {
        name
      }
      tasks {
        id
        document {
          id
          attributes
          type {
            name
          }
          status {
            name
          }
        }
        direction
        senderCore {
          name
        }
        receiver {
          name
        }
        loads {
          load {
            name
          }
          loadTag
          quantity
        }
      }
      bookingHistory {
        time
        user
        organisation {
          name
        }
        ... on StatusHistory {
          status {
            name
          }
        }
        __typename
      }
    }
  }
}

In the above query, we are retrieving bookings with the following information and constraints:

The query searches for bookings at a specific location, identified by the UUID "61b0d4c9-41f3-432a-420f-3f69c00a344f", as defined by the location filter.
It filters bookings that occured in the areas "West Docks" or "South Docks", using the area filter and the in comparison.
The query fetches up to 500 bookings (count: 500), starting from the first result (start: 0).
The query returns the total number of results and details of each booking through the bookings field.
For each booking, key information is returned such as: id, bookedTime, duration, carrier, space, vehicle, fields, status, tasks, and bookingHistory.

Submitting a Bookings Query

GraphQL API

All requests to interact with the booking system are via GraphQL and made to the /api/v1/graphql endpoint. Unlike the REST API, which has multiple endpoints for different resources, all GraphQL operations are performed through this single endpoint.

Example

Once a valid GraphQL query has been constructed, it is ready to be submitted to Mobiledock.

All GraphQL queries, including bookings queries, must be sent as HTTP POST requests to the GraphQL endpoints:

https://my.mobiledock.com/api/v1/graphql

https://staging.mobiledock.com/api/v1/graphql

The query should be included in the body of the request in JSON format. Below is an example JSON payload based on the GraphQL query provided earlier:

{
  "query": "query GetBookings { bookingsV2( count: 500 start: 0 filter: { location: { id: { eq: \"61b0d4c9-41f3-432a-420f-3f69c00a344f\" } } area: { name: { in: [\"West Docks\", \"South Docks\"] } } } ) { results bookings { id bookingType createdAt modifiedAt requestedTime bookedTime duration carrier { name } space { name } area { name } location { name description } vehicle { name size } fields { field { label } value } status { name } tasks { id document { id attributes type { name } status { name } } direction senderCore { name } receiver { name } loads { load { name } loadTag quantity } } bookingHistory { time user organisation { name } ... on StatusHistory { status { name } } __typename } } } }"
}

Next Steps

To learn more about bookings, visit the BookingsV2 GraphQL API Specification and the Booking Object 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 Booking Integration​

Requirements​

Composing a Bookings Query​

Anatomy of a Bookings Query​

Ordering​

Ascending​

Count and Start​

Filter​

The Filter Property​

Breakdown of Filter Inputs​

The Base Comparison Object​

Other Input Objects​

EntityRefComparisonInput​

LoadQuantityFilterInput​

FieldValueFilterInput​

EntityRefInput​

The Booking Query Object​

Example Query​

Submitting a Bookings Query​

GraphQL API​

Example​

Next Steps​