Home › Developer's Handbook › Online Booking API ›

Online Booking API V2

Submitted by tanderson on Wed, 13/02/2019 - 10:55

The OpenVPMS Booking API V2 is a JSON API for making appointments in OpenVPMS.

The following assumes:

The openvpms-booking-api-v2-draft.zip contains API documentation generated by Enunciate. Extract and browse from index.html.

You can also get an overview by browsing http://localhost:8080/openvpms/ws/booking/v2/application.wadl

Locations

To get the locations:

> curl -u sample:changeit http://localhost:8080/openvpms/ws/booking/v2/locations
[{"id":106,"name":"Branch Clinic","timeZone":"Australia/Sydney"},
 {"id":98,"name":"Main Clinic","timeZone":"Australia/Sydney"}]

Notes:

  • for a location to be returned, its Online Booking flag must be ticked.

To get the schedules available at a location:

> curl -u sample:changeit http://localhost:8080/openvpms/ws/booking/v2/locations/98/schedules
[{"id":136,"name":"Main Appointment Schedule","slotSize":15},
 {"id":211,"name":"Main Surgery Schedule","slotSize":30}]

Notes:

  • For a schedule to be returned, its Online Booking flag must be ticked.

Appointment Types

To get the appointment types applicable to a schedule:

> curl -u sample:changeit http://localhost:8080/openvpms/ws/booking/v2/schedules/136/appointmentTypes
[{"id":79,"name":"Short Consult","slots":1},
 {"id":66,"name":"Standard Consult","slots":1},
 {"id":63,"name":"Long Consult","slots":2},
 {"id":76,"name":"New Patient","slots":2}]

Notes:

  • the same appointment type may be used by multiple schedules, each with a different slot size
  • for an appointment type to be returned, its Online Booking flag must be ticked.

Free/Busy

A number of methods are provided to get free and busy times:

> curl -u sample:changeit 'http://localhost:8080/openvpms/ws/booking/v2/schedules/136/free?from=2019-02-15T00:00:00%2B11:00&to=2019-02-16T00:00:00%2B11:00'
[{"start":"2019-02-15T09:00:00.000+11:00","end":"2019-02-15T10:45:00.000+11:00"},
 {"start":"2019-02-15T11:30:00.000+11:00","end":"2019-02-15T17:30:00.000+11:00"}]

 

> curl -u sample:changeit 'http://localhost:8080/openvpms/ws/booking/v2/schedules/136/busy?from=2019-02-15T00:00:00%2B11:00&to=2019-02-16T00:00:00%2B11:00'
[{"start":"2019-02-15T10:45:00.000+11:00","end":"2019-02-15T11:30:00.000+11:00"}]

If you want both free and busy times, its more efficient to do a single call:

> curl -u sample:changeit 'http://localhost:8080/openvpms/ws/booking/v2/schedules/136/freebusy?from=2019-02-15T00:00:00%2B11:00&to=2019-02-16T00:00:00%2B11:00'
{"free":[{"start":"2019-02-15T09:00:00.000+11:00","end":"2019-02-15T10:45:00.000+11:00"},{"start":"2019-02-15T11:30:00.000+11:00","end":"2019-02-15T17:30:00.000+11:00"}],
 "busy":[{"start":"2019-02-15T10:45:00.000+11:00","end":"2019-02-15T11:30:00.000+11:00"}]}

To return the free and busy times in slots, specify &slots=true e.g.:

> curl -u sample:changeit 'http://localhost:8080/openvpms/ws/booking/v2/schedules/136/free?from=2019-02-15T00:00:00%2B11:00&to=2019-02-16T00:00:00%2B11:00&slots=true'
[{"start":"2019-02-15T09:00:00.000+11:00","end":"2019-02-15T09:15:00.000+11:00"},
 {"start":"2019-02-15T09:15:00.000+11:00","end":"2019-02-15T09:30:00.000+11:00"},
 {"start":"2019-02-15T09:30:00.000+11:00","end":"2019-02-15T09:45:00.000+11:00"},
 {"start":"2019-02-15T09:45:00.000+11:00","end":"2019-02-15T10:00:00.000+11:00"},
 {"start":"2019-02-15T10:00:00.000+11:00","end":"2019-02-15T10:15:00.000+11:00"},
 {"start":"2019-02-15T10:15:00.000+11:00","end":"2019-02-15T10:30:00.000+11:00"},
 {"start":"2019-02-15T10:30:00.000+11:00","end":"2019-02-15T10:45:00.000+11:00"},
 {"start":"2019-02-15T11:30:00.000+11:00","end":"2019-02-15T11:45:00.000+11:00"},
 {"start":"2019-02-15T11:45:00.000+11:00","end":"2019-02-15T12:00:00.000+11:00"},
 {"start":"2019-02-15T12:00:00.000+11:00","end":"2019-02-15T12:15:00.000+11:00"},
 {"start":"2019-02-15T12:15:00.000+11:00","end":"2019-02-15T12:30:00.000+11:00"},
 {"start":"2019-02-15T12:30:00.000+11:00","end":"2019-02-15T12:45:00.000+11:00"},
 {"start":"2019-02-15T12:45:00.000+11:00","end":"2019-02-15T13:00:00.000+11:00"},
 {"start":"2019-02-15T13:00:00.000+11:00","end":"2019-02-15T13:15:00.000+11:00"},
 {"start":"2019-02-15T13:15:00.000+11:00","end":"2019-02-15T13:30:00.000+11:00"},
 {"start":"2019-02-15T13:30:00.000+11:00","end":"2019-02-15T13:45:00.000+11:00"},
 {"start":"2019-02-15T13:45:00.000+11:00","end":"2019-02-15T14:00:00.000+11:00"},
 {"start":"2019-02-15T14:00:00.000+11:00","end":"2019-02-15T14:15:00.000+11:00"},
 {"start":"2019-02-15T14:15:00.000+11:00","end":"2019-02-15T14:30:00.000+11:00"},
 {"start":"2019-02-15T14:30:00.000+11:00","end":"2019-02-15T14:45:00.000+11:00"},
 {"start":"2019-02-15T14:45:00.000+11:00","end":"2019-02-15T15:00:00.000+11:00"},
 {"start":"2019-02-15T15:00:00.000+11:00","end":"2019-02-15T15:15:00.000+11:00"},
 {"start":"2019-02-15T15:15:00.000+11:00","end":"2019-02-15T15:30:00.000+11:00"},
 {"start":"2019-02-15T15:30:00.000+11:00","end":"2019-02-15T15:45:00.000+11:00"},{"start":"2019-02-15T15:45:00.000+11:00","end":"2019-02-15T16:00:00.000+11:00"},{"start":"2019-02-15T16:00:00.000+11:00","end":"2019-02-15T16:15:00.000+11:00"},{"start":"2019-02-15T16:15:00.000+11:00","end":"2019-02-15T16:30:00.000+11:00"},{"start":"2019-02-15T16:30:00.000+11:00","end":"2019-02-15T16:45:00.000+11:00"},{"start":"2019-02-15T16:45:00.000+11:00","end":"2019-02-15T17:00:00.000+11:00"},{"start":"2019-02-15T17:00:00.000+11:00","end":"2019-02-15T17:15:00.000+11:00"},{"start":"2019-02-15T17:15:00.000+11:00","end":"2019-02-15T17:30:00.000+11:00"}]

Users

Clinician users can be be scheduled for appointments, subject to their availability at a Practice Location.

Notes:

  • For a user to be returned, their Online Booking flag must be ticked.

Users at a Practice Location

To determine the users available at a practice location:

> curl -u sample:changeit http://localhost:8080/openvpms/ws/booking/v2/locations/98/users
[{"id":1158,"name":"Andrew Turner"},
 {"id":1159,"name":"Chris Barton"}]

User Locations

To determine which locations a user may be available at:

> curl -u sample:changeit http://localhost:8080/openvpms/ws/booking/v2/users/1158/locations
[{"id":106,"name":"Branch Clinic","timeZone":"Australia/Sydney"},
 {"id":98,"name":"Main Clinic","timeZone":"Australia/Sydney"}]

User Availability at a Location

To determine user availability at a Practice Location, and which schedules they may be assigned appointments to:

> curl -u sample:changeit 'http://localhost:8080/openvpms/ws/booking/v2/users/1158/locations/98/free?from=2019-02-15T00:00:00%2B11:00&to=2019-02-16T00:00:00%2B11:00'
[{"start":"2019-02-15T11:00:00.000+11:00","end":"2019-02-15T17:00:00.000+11:00","schedule":136},
 {"start":"2019-02-15T09:00:00.000+11:00","end":"2019-02-15T17:00:00.000+11:00","schedule":211}

Notes:

  • The user must be rostered on to a Roster Area with Schedules attached
  • The returned times are per schedule, indicating the times that the user is free/busy for that schedule only.
    It does not take into account other appointments on the schedule, or other appointments the user has on a different schedule.

    To determine the times a user is available, the union of busy times needs to be removed from each schedule.

Submitting Bookings

 

> curl -u sample:changeit -H "Content-Type: application/json" --data @booking.json http://localhost:8080/openvpms/ws/booking/v2/bookings

Where booking.json is a file containing:

{
  "location": 98,
  "schedule": 136,
  "appointmentType": 66,
  "start": "2019-02-15T12:30:00.000+11:00",
  "end": "2019-02-15T12:45:00.000+11:00",
  "title": "Ms",
  "firstName": "Judith",
  "lastName": "Bourke",
  "mobile": "0418976543",
  "patientName": "Muffett"
  "user": 1158
}

Notes:

  • the email and phone attributes can be specified as well.
  • a booking customer is considered a match if its firstName and lastName are equal to an OpenVPMS customer, ignoring case,  and at least one of the 3 contacts are present.
  • the reference returned is a concatenation of the appointment identifier, customer identifier and UUID. This is to:
    • make it harder to retrieve/cancel bookings not made through the API
    • prevent retrieval of appointments subsequently assigned to another customer
  • the user is optional

Retrieving Bookings

> curl -u sample:changeit http://localhost:8080/openvpms/ws/booking/v2/bookings/603:3:be08f3c6-1afb-11e6-be41-3dbaef689d97

Notes:

  • the mobile, phone and email submitted with the request are not stored; the values returned are those associated with the existing customer
  • the notes aren't returned as these may have been updated since the booking was made and contain information that shouldn't be disclosed

Cancelling Bookings

 

> curl -X DELETE -u sample:changeit http://localhost:8080/openvpms/ws/booking/v2/bookings/391:a98f02c9-1a4b-...

Notes:

  • bookings can only be cancelled while their corresponding appointment is pending
  • once cancelled, bookings cannot be retrieved

Security

There are a number of security considerations to be aware of:

  • an OpenVPMS user account is required to make online bookings. This should be a restricted account that only has the authorities required to make online bookings.
    This can be done by creating a user that only has the Online Booking role assigned.
  • the OpenVPMS web application should not be exposed to the wider internet to allow external providers to connect. Restricted access can be provided through a VPN, IP filtering, and/or URL filtering. For the purposes of online booking, only the:
       /openvpms/ws/booking
    URL should be exposed.

 

Syndicate content