Appointment Validation

Appointment Validation (also known as PO Validation or Reference Number Validation) is a feature allowing facilities to hook into the appointment creation (and update) lifecycle of Opendock, to enforce their own custom business rules. A common use case is enforcing an accurate PO # or reference # input before scheduling an appointment, however many other things about the appointment can be validated such as the start date/time, load type, custom fields, and more. This enforcement is carried out for both carrier and warehouse scheduling users.

Facility operators usually request this feature in order to protect their schedule from abuse and avoid incorrect appointment bookings. Also, matching on a valid and unique PO/Ref Number will provide additional functionality of being able to share more data back and forth between your other systems and Opendock.

The ultimate design philosophy is that Opendock doesn't store this data but will instead send the "appointment context" (information about the appointment to be created or updated) to your middleware system (a webserver you must set up), which will communicate back to Opendock about whether the appointment is valid or not.

This diagram illustrates the major concepts of this "Appointment Validation Protocol":

Your Custom Middleware

How you decide to build your middleware is totally up to you and your engineers. This protocol is language/platform agnostic as it only relies on a simple HTTPS POST request. Opendock just needs to know the URL of your web server ( see Opendock Configuration section below), and then it will send requests to it when a user is attempting to create (or update) an appointment. Your middleware can then reach out to any of your systems (e.g. WMS/TMS/ERP/etc.) to fetch data and make a decision about the validity of the appointment.

Validation Version

The current version of our Appointment Validation Protocol is V2. Your Opendock Warehouses will default to this version (there is a drop-down selector to choose the protocol version). The remainder of this documentation will assume you are using V2.

info

We do have an older V1 Protocol, including a Google Sheet based option. If you are using that system, we suggest upgrading to V2. If you need support for V1/Google Sheet, then reach out to Opendock customer support. Note that V1/Google Sheet will stay in operation for the foreseeable future, but is considered "deprecated", and will eventually be discontinued.

Appointment Validation Protocol V2

In order for Opendock to validate an appointment, your middleware must implement a publicly accessible HTTPS endpoint that can accept a POST request.

The URL can be whatever you like as long as the protocol is HTTPS, and you do not specify an explicit port.

For example, it could be something like this:

https://www.my-company.com/opendock-validator

When an appointment creation or update is being attempted, Opendock will make a POST request to the URL you provided. Authentication is not required (see Security section below), however HTTPS protocol must be used.

The body of the request to your server will be a JSON object containing the relevant information about the appointment ( known as the "appointment context"), as well as the "action" which will be either "create" or "update".

The appointment information will appear in two objects under the keys: appointmentFields and existingAppointment.

• appointmentFields will contain all the "proposed" field values for an appointment that is about to be created, or for an update, it will have the fields that are about to be changed.
• existingAppointment will be null for appointment creation, but for an appointment update it will contain the existing data for the appointment.

The Reference Number (PO number) can, for example, be read out from appointmentFields.refNumber, and then could be checked against an external system/database for validity (typical "PO Validation" use case). But you can also utilize all of this other appointment "context" data to help you make a decision about the appointment. For instance, you could verify the correct loadTypeId, or make sure the "start" Date/Time is valid for the given shipment PO. It all depends on your business needs, and with this system, you will have all the data at your fingertips to make that decision.

tip

Note that the appointment data fields follow the same "shape" as the Appointment entity in our REST API.

Examples

Payload for a pending appointment creation

{
   "action":"create",
   "appointmentFields":{
      "start":"2022-11-07T19:00:00.000Z",
      "userId":"91df55e9-b324-4ae0-9061-32058763e2a6",
      "loadTypeId":"b238b21f-4f60-4810-b81f-9133d3c8c1d0",
      "dockId":"5cb3c325-74fc-4f65-b829-8ae1affe75ca",
      "refNumber":"1234",
      "tags":null,
      "createdBy":"a1badb81-39d7-4695-8e42-56efcc4040e8",
      "lastChangedBy":"a1badb81-39d7-4695-8e42-56efcc4040e8",
      "orgId":"6d1467d4-c987-4b79-9d12-d5998c80e06f",
      "end":"2022-11-07T20:30:00.000Z",
      "statusTimeline":{
         "Scheduled":"2022-11-04T20:45:42.801Z",
         "Arrived":null,
         "Completed":null,
         "NoShow":null,
         "Cancelled":null
      }
   },
   "existingAppointment":null
}

Payload for a pending appointment update

{
   "action":"update",
   "appointmentFields":{
      "refNumber":"ABC98765",
      "lastChangedBy":"a1badb81-39d7-4695-8e42-56efcc4040e8",
      "orgId":"6d1467d4-c987-4b79-9d12-d5998c80e06f",
      "dockId":"5cb3c325-74fc-4f65-b829-8ae1affe75ca",
      "loadTypeId":"b238b21f-4f60-4810-b81f-9133d3c8c1d0"
   },
   "existingAppointment":{
      "id":"11bc0240-ff55-49d2-b872-4522271e4b1d",
      "start":"2022-11-07T19:00:00.000Z",
      "end":"2022-11-07T20:30:00.000Z",
      "refNumber":"ABC12345",
      "createDateTime":"2022-11-04T20:45:42.938Z",
      "createdBy":"a1badb81-39d7-4695-8e42-56efcc4040e8",
      "lastChangedDateTime":"2022-11-04T20:45:42.938Z",
      "lastChangedBy":"a1badb81-39d7-4695-8e42-56efcc4040e8",
      "isActive":true,
      "tags":[
         "late",
         "damaged"
      ]
   }
}

Response: Success or Failure

Once your middleware has decided if an appointment is valid or not, it should then reply to the POST request. If the HTTP response code is “2xx”, then the appointment is considered valid, and the appointment scheduling will proceed. Any other HTTP return code (4xx, 5xx, etc) results in an error and prevents the appointment from being scheduled.

You should also return a custom error message, which the Opendock UI will display to your users. This allows your middleware to give them specific information about what went wrong, and how to correct it. All you have to do is include a JSON object with an errorMessage string value as part of your response (along with 4xx or 5xx code). For example:

{
   "errorMessage":"PO Number must be at least 6 characters long"
}

warning

Currently, Opendock requires your validator to respond within 8 seconds, or a timeout error will occur. If your systems cannot reliably respond within this time window, you should consider a different approach to integrating with Opendock.

Security Concerns / Passcode Feature

Some users may be worried about having to expose a public web service. To alleviate that this protocol requires HTTPS connections, to eliminate man-in-the-middle style attacks.

However, this doesn't stop unknown parties from sending requests to your validator service. You can of course make your URL as obscure as possible to alleviate this, however if this isn't enough, then you may want to use the optional " Passcode" feature.

All you have to do is set a "passcode" of your choice (it can be any string, but should be considered a secret within your company), into your Warehouse configuration (see Opendock Configuration section below). Once that is set, then every POST request Opendock makes to your validator will include your passcode as a Bearer token on the * Authorization* header. This way, your middleware can receive the passcode and verify its correctness.

To disable this feature, simply clear out the passcode field in your warehouse config, and then Opendock will no longer set anything in the Authorization header.

For example, if you set your passcode to 123456, then Opendock will send POST requests to your middleware with the Authorization header set to:

Bearer 123456

Opendock Configuration

Once you're ready to enable Appointment Validation:

1. Go to the individual Warehouse's Info page
2. Scroll down to the RefNumber Validation Setup section
3. Make sure Version is set to: Version 2
4. Enter your validator's URL into the Validator URL field
5. If you wish to use the Passcode feature (see security section above) then fill this field out as well (otherwise leave it blank)
6. Click the Save button

At this point, whenever an appointment is created or updated for this warehouse, your validator will get invoked. To test, just go attempt to create an appointment with a known mistake, and ensure you see the error message returned from your validator. Then create a "good" appointment and confirm it gets scheduled properly.

Troubleshooting

First and foremost, ensure you have access to the logs of your middleware server. This will be the best place to start debugging any issues. If you're middleware is not properly responding with the error message in the format described above, then Opendock will not be able to display the error message to the user.

Some other common issues to look out for:

• Ensure your middleware is accessible from the public internet (if you're using a local development server, it may not be reachable by Opendock). This one is easily tested by trying to access your validator URL from an application like Postman or cURL.
• Ensure your middleware is responding within 8 seconds. If it's taking longer, then Opendock will timeout and the TIMEOUT_ERROR message will be displayed to the user.
• Ensure your middleware SSL certificate is valid. It is common for URLs to be inaccessible if the SSL certificate is expired or invalid. Remember, Opendock requires HTTPS connections for this feature.

Need more help?

Please reach out to our support team to get help with any questions, or join our API Slack Workspace.