Helix AU Core
0.1.0 - ci-build

Helix AU Core - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Get Slots Operation

Overview

The $getSlots operation is a type-level custom operation in the Helix FHIR API which is designed to streamline appointment scheduling workflows.

It returns all available slots for the given schedule and date range.

Detail Workflows

  1. This operation is executed by sending a POST request to the Helix Hub in the format: base URL + /Slot/$getSlots + parameters.
    An example: 
    https://<fhir-server>/<tenant>/Slot/$getSlots?scheduleId=schedule_UUID&fromDate=2025-01-21&toDate=2025-01-21&slotSize=30
  2. The following parameters need to be considered when calculating slot availability:
    • Schedule planning horizon
    • Available time
    • Work hours
    • Existing appointments
    • Breaks
    • Holidays and personal leaves
  3. Each availability span is divided into individual Slot resources based on the specified slot size (or the default size if none is provided), and returned as a bundle.

Input Parametters

  1. scheduleID(mandatory): string (1..1)
    • The operation returns a 422 error with the message: 'Invalid request: scheduled must be specified.'
  2. fromDate(optional): Date (0..1, YYYY-MM-DD)
    • If specified, it must be later than the current date. Otherwise, the operation returns a 422 error with the message: 'Invalid request: fromDate must be greather than now.'
    • Default value: current date
    • Mandatory if 'toDate` is specified.
  3. toDate(optional): date (0..1, YYYY-MM-DD)
    • If specified, fromData must also be specified. Otherwise, the operation returns a 422 error with the message: 'Invalid request: if toDate is specified, fromDate must also be specified.'
    • If specified, it must be later than fromDate. Otherwise, the operation returns a 422 error with the message: 'Invalid request: toDate must be greater than fromDate.'
    • If specified, the requested time range (toDate - fromDate) must not exceed 14 days. Otherwise, the operation returns a 422 error with the message: 'Invalid request: Maximum allowed period is 14 days.'
    • Default value: fromDate plus 14 days.
  4. slotSize(optional): number (0..1)
    • If specified, it should be a number between 5 and 720 minutes (minimum and maximum value for slot). Otherwise, the operation returns a 422 error with the message: 'Invalid request: slotSize must be 5 and 720 minutes.'
    • Default value: Schedule.extensions(appointment-duration). If this value is not set, it will be set to 10 minutes.

Validation rules

  1. If the Schedule resource lacks a planningHorizon, the operation returns a 404 error with the message: 'Requested schedule does not contain a planning horizon.'
  2. If Schedule.planningHorizon does not overlap with the requested date range, the operation returns a 404 error with the message: 'Requested date range not available.'

getSlots scenarios

  1. Request with a single parameter: scheduleId. The date range and slot size will be determined per the rules below:

    https://<fhir-server>/<tenant>/Slot/$getSlots?scheduleId=[scheduleId]

  2. Request with scheduleId and start of the date range. The date range and slot size will be determined per the rules below:

    https://<fhir-server>/<tenant>/Slot/$getSlots?scheduleId=[scheduleId]&fromDate=[YYYY-MM-DD]

  3. Request with scheduleId, start and end of the data range. Slot size will be determined per the rules below:

    https://<fhir-server>/<tenant>/Slot/$getSlots?scheduleId=[scheduleId]&fromDate=[YYYY-MM-DD]&toDate=[YYYY-MM-DD]

  4. Request with scheduleId, start and end of the date range, and slot size.

    https://<fhir-server>/<tenant>/Slot/$getSlots?scheduleId=[scheduleId]&fromDate=[YYYY-MM-DD]&toDate=[YYYY-MM-DD]&slotSize=[number]

Edge cases and error scenarios

  1. A request missing scheduleId will result in an error: 'Invalid request: scheduleId must be specified.'

    https://<fhir-server>/<tenant>/Slot/$getSlots

  2. A request with scheduleId that does not exist will result in an error: 'HTTP 404 Not Found: getSlots: Error occurred while fetching Schedule with ID non_existing_scheduleId.'

    https://<fhir-server>/<tenant>/Slot/$getSlots?scheduleId=non_existing_scheduleId

  3. A request where fromDate is in the past will result in an error: 'Invalid request: fromDate must be greater than now.

    https://<fhir-server>/<tenant>/Slot/$getSlots?scheduleId=schedule_UUID&fromDate=2000-01-01

  4. A request with toDate earlier than fromDate will result in an error: 'Invalid request: toDate must be greater than fromDate.

    https://<fhir-server>/<tenant>/Slot/$getSlots?scheduleId=schedule_UUID&fromDate=2025-01-21&toDate=2025-01-20

  5. A request with an invalid slotSize will result in an error:'Invalid request: slotSize must be between 5 and 720 minutes.

    https://<fhir-server>/<tenant>/Slot/$getSlots?scheduleId=schedule_UUID&slotSize=1

  6. A request with a date range outside the bounds of Schedule.PlanningHorizon will result in an error: 'HTTP 404 Not Found: getSlots: Requested date range not available.'

    https://<fhir-server>/<tenant>/Slot/$getSlots?scheduleId=schedule_UUID&fromDate=2025-05-21&toDate=2025-05-21

  7. A request with a data range exceeding 14 days will result in an error: 'Invalid request: Maximum allowed period is 14 days.

    https://<fhir-server>/<tenant>/Slot/$getSlots?scheduleId=schedule_UUID&fromDate=2025-01-21&toDate=2025-02-21

  8. If no available slots exist for the specified schedule and date range, an empty bundle will be returned.

    {
  "resourceType": "Bundle"
}

An Example

Context: Requesting available slots for a day when all of the following details are specified:

  • Work time: 07:30-16:00
  • Break time: 10:00-10:30 and 12:30-13:30
  • Scheduled appointments: 08:00-09:00, 11:00-12:00, and 14:00-15:00
  • Default slot size: 30 minutes

Request:

https://<fhir-server>/<tenant>/Slot/$getSlots?scheduleId=schedule_UUID&fromDate=2025-01-21&toDate=2025-01-21&slotSize=30

Response:

{
  "resourceType": "Bundle",
  "entry": [
    {
      "resource": {
        "resourceType": "Slot",
        "schedule": {
          "reference": "Schedule/schedule_UUID"
        },
        "status": "free",
        "start": "2025-01-21T07:30:00",
        "end": "2025-01-21T08:00:00"
      }
    },
    {
      "resource": {
        "resourceType": "Slot",
        "schedule": {
          "reference": "Schedule/schedule_UUID"
        },
        "status": "free",
        "start": "2025-01-21T09:00:00",
        "end": "2025-01-21T09:30:00"
      }
    },
    {
      "resource": {
        "resourceType": "Slot",
        "schedule": {
          "reference": "Schedule/schedule_UUID"
        },
        "status": "free",
        "start": "2025-01-21T09:30:00",
        "end": "2025-01-21T10:00:00"
      }
    },
    {
      "resource": {
        "resourceType": "Slot",
        "schedule": {
          "reference": "Schedule/schedule_UUID"
        },
        "status": "free",
        "start": "2025-01-21T10:30:00",
        "end": "2025-01-21T11:00:00"
      }
    },
    {
      "resource": {
        "resourceType": "Slot",
        "schedule": {
          "reference": "Schedule/schedule_UUID"
        },
        "status": "free",
        "start": "2025-01-21T12:00:00",
        "end": "2025-01-21T12:30:00"
      }
    },
    {
      "resource": {
        "resourceType": "Slot",
        "schedule": {
          "reference": "Schedule/schedule_UUID"
        },
        "status": "free",
        "start": "2025-01-21T13:30:00",
        "end": "2025-01-21T14:00:00"
      }
    },
    {
      "resource": {
        "resourceType": "Slot",
        "schedule": {
          "reference": "Schedule/schedule_UUID"
        },
        "status": "free",
        "start": "2025-01-21T15:00:00",
        "end": "2025-01-21T15:30:00"
      }
    },
    {
      "resource": {
        "resourceType": "Slot",
        "schedule": {
          "reference": "Schedule/schedule_UUID"
        },
        "status": "free",
        "start": "2025-01-21T15:30:00",
        "end": "2025-01-21T16:00:00"
      }
    }
  ]
}