Skip to main content
Version: 10.x (Current)

Appointment Manager configuration

The Appointment Manager can be used in two different configurations, depending on your use case:

  • an appointments mode, if you just need to manage appointments;
  • a full mode, if you need to configure availabilities and exceptions and want to create appointments from slots.

Whatever your use case, to deploy an instance of the microservice you have to configure the required CRUD collection(s) and the microservice itself, as described in the following sections.

Overview

This section provides a detailed overview of the microservice configuration and the CRUD collections required.

If you are looking for instructions to configure the service in appointments or full mode, look at the Appointments mode and Full mode sections at the end of the document.

Service configuration

info

v2.0.0 Since v2.0.0 two new service configuration fields are supported: isMessagingAvailable and isTimerAvailable. Together with isTeleconsultationAvailable, these three configuration fields allow you to enable or disable the integration with the messaging, timer and teleconsultation service respectively. They are set to false by default, so you need to set them explicitly to true in order to get the Appointment Manager to generate teleconsultation links, send messages and set reminders.

danger

v2.1.0 Since v2.1.0 the service configuration accepts a list of reminders, that you can send at different times using different templates. You need to upgrade your existing configuration before upgrading to v2.1.x, since the older reminder property is no longer valid.

The service requires you to provide a configuration file in JSON format as a configmap. You can choose the name and mounting point of the map, as long as you specify the correct path in the CONFIGURATION_PATH environment variable.

Here's an example of a full configuration:

{
"users": {
"doctor": {
"create": "template_id",
"delete": "template_id",
"reminders": {
[
{
"template": "template_id",
"reminderMilliseconds": 86400000
}
]
}
},
"patients": {
"update": "template_id",
"reminders": {
[
{
"template": "template_id_1",
"reminderMilliseconds": 86400000
},
{
"template": "template_id_2",
"reminderMilliseconds": 3600000
},
]
}
}
},
"channels": ["email", "push", "sms"],
"reminderThresholdMs": 86400000,
"isTeleconsultationAvailable": true,
"isMessagingAvailable": true,
"isTimerAvailable": true,
"defaultLockDurationMs": 60000
}

A reference presentation of each available field is provided in the following table, more details are available in the following sub-sections.

NameRequiredDefaultDescription
usersYes-Templates to use for sending messages (when you create, update or delete an appointment) and reminders to appointment participants (e.g. doctor and patients)
channelsYes-The list of channels to send messages on (currently supported channels: email, push, sms)
reminderThresholdMsNo0Send reminders only at least as early before the appointment starts. Zero means the reminders, if enabled, are always sent
isTeleconsultationAvailableNofalseIf the teleconsultation service is available, enable the integration to generate teleconsultation links.
isMessagingAvailableNofalseIf the messaging service is available, enable the integration to send messages and reminders.
isTimerAvailableNofalseIf the timer service is available, enable the integration to set reminders.
isUserAvailableNofalseIf the resources crud path is available, enable to recover resource's information for POST /searches/first-available-slot/ endpoint.
defaultLockDurationMsNo-The default duration of the temporary slot lock (in milliseconds).

users

With this field you can specify for each category of users which template has to be used when sending messages to notify the different phases of an appointment lifecycle (see the service overview for more information).

The structure of the map is the following:

{
"users_category_name": {
"create": "template_id",
"update": "template_id",
"delete": "template_id",
"reminders": {
[
{
"template": "template_id_1",
"reminderMilliseconds": 86400000
},
{
"template": "template_id_2",
"reminderMilliseconds": 3600000
},
]
}
}
}

As you can see, inside each user category you can specify four fields: create, update, delete and reminders. Each of these fields will allow you to set the template for a specific part of the appointment lifecycle. The reminders field allows setting multiple templates and the amount of time before the appointment (expressed in milliseconds) when each of these templates has to be sent.

In particular, you will have:

  • create: where you can set the template for messages sent on the creation of an appointment
  • update: where you can set the template for messages sent when update of an appointment
  • delete: where you can set the template for messages sent on the deletion of an appointment
  • reminders: where you can set the list of template for messages sent when the respective appointment reminder expires.
danger

v2.1.0

Every reminder belonging to the same user group must have an unique template id

channels

In the channels field you can specify the list of channels on which the Appointment Manager will send messages. Possible values are email, sms, and push.

A correct configuration may be

{
"channels": ["email", "push"]
}

reminderThresholdMs

This field defines a time threshold (in milliseconds) under which reminders are not sent. For instance, if you don't want any reminders sent if the created appointment is set to happen below the next 24 hours, you can define a threshold of 86400000 ms as follows:

{
"reminderThresholdMs": 86400000
}

This behavior also applies in case of appointment update. Please also note that if the threshold is not defined, reminders are always sent.

isTeleconsultationAvailable

A boolean which determines if the teleconsultation service can be used. If the value is set to false, the user can't use the teleconsultation. If the value is set to true, the user can choose between teleconsultation or onsite modes.

The default value is false.

isMessagingAvailable

info

v2.0.0 This configuration field is supported only from v2.0.0

A boolean which determines if the messaging service can be used. If the value is set to false, the user can't send messages or reminders. If the value is set to true, the user can configure which messages are sent to which participants.

The default value is false.

isTimerAvailable

info

v2.0.0 This configuration field is supported only from v2.0.0

A boolean which determines if the messaging service can be used. If the value is set to false, the user can't send set reminders. If the value is set to true, the user can configure the reminders templates and when they are sent.

The default value is false.

isUserAvailable

info

v2.1.0 This configuration field is supported only from v2.1.0

A boolean which determines if resource CRUD path has been configured. If the value is set to false, the user can't use search endpoints. If the value is set to true, the user can call the POST /searches/first-available-slot/ endpoint. The default value is false.

defaultLockDurationMs

This field defines the default duration in milliseconds of the temporary slot lock. For instance:

{
"defaultLockDurationMs": 60000
}

Environment variables

The Appointment Manager accepts the following environment variables.

NameRequiredDescription
CONFIGURATION_PATHYesPath of the config map file containing the service configuration.
CRUD_SERVICE_NAMEYesName of the CRUD service.
RESOURCE_ID_FIELD_NAMEYesName of the CRUD field containing the resource ID (the field must be present in the availabilities, appointments and exceptions CRUD collections).
DEFAULT_TIME_ZONEYesDefault IANA time zone, to be used when no time zone is specified by the client when creating new availabilities.
APPOINTMENTS_CRUD_NAMEYesName of the CRUD collection containing the appointments.
AVAILABILITIES_CRUD_NAMEIn full modeName of the CRUD collection containing the availabilities.
EXCEPTIONS_CRUD_NAMEIn full modeName of the CRUD collection containing the exceptions.
USERS_CRUD_NAMEIf isUserAvailable is trueName of the CRUD collection containing the users.
USER_ID_FIELD_NAMEIf isUserAvailable is trueName of the CRUD field containing the user ID in the users CRUD.
MESSAGING_SERVICE_NAMEIf isMessagingAvailable or isTimerService is trueName of the Messaging Service. Required if you want to send messages or set reminders for your appointments.
TIMER_SERVICE_NAMEIf isTimerService is trueName of the Timer Service. Required if you want to set reminders for your appointments.
TELECONSULTATION_SERVICE_NAMEIf isTeleconsultationAvailable is trueName of the teleconsultation service. Required if you want to create teleconsultations.
TELECONSULTATION_ENDPOINT_FEIf isTeleconsultationAvailable is trueEndpoint associated with the Teleconsultation Service FrontEnd (the root). Required if you want to create teleconsultations.
TELECONSULTATION_BASE_PATHIf isTeleconsultationAvailable is trueCustom base path for the teleconsultation URL. Required if you want to create teleconsultations.

CRUD collections

The following sections describe the schema of each CRUD collection used by the Appointment Manager.

Availabilities, appointments and exceptions CRUD collections need to have a string field with any name of your choice, as long as you specify it in the RESOURCE_ID_FIELD_NAME environment variable, containing the resource ID. This field is necessary to correlate availabilities and appointments to exceptions referring to the same resource. The name of the string field in the users CRUD collection that identifies a user can be specified in the USER_ID_FIELD_NAME environment variable.

Appointments CRUD collection

info

v2.0.0 Starting from v2.0.0 the slotId field is no longer used since slots are computed dinamically. The new availabilityId field is introduced to link an appointment to an availability and, in combination with startDate and endDate, to a specific slot. Since the slots CRUD collection is no longer used, this CRUD collection also stores the appointment reservations and inherits from the slots CRUD collection two fields: status and lockExpiration. A new isFlagged field is added to track the appointments whose slots are no longer valid and may need to be rescheduled.

The Appointment Manager requires a CRUD containing the appointments. The collection can have any name you want, as long as you specify the correct name in the APPOINTMENTS_CRUD_NAME environment variable.

The appointments collection must have the following fields, plus the same custom fields defined in the availabilities CRUD:

NameTypeRequiredNullableDescription
startDatedateYesNoStart date/time expressed in format ISO 8601.
endDatedateYesNoEnd date/time expressed in format ISO 8601.
availabilityIdstringIn full modeNoID of the appointment's related availability.
ownerIdstringIn full modeNoUser who booked the appointment.
slotIdstringNoNoSlot ID for backward compatibility.
reminderMillisecondsnumberNoNoAmount of time before the appointment when users are notified about it (expressed in milliseconds).
reminderIdsarray of ObjectIdNoNoList of unique identifiers of the reminders associated with the appointment.
channelsarray of stringNoNoList of communication channels used to send messages and reminders. Possible values are email, sms, and push.
isRemotebooleanNoNoIf an appointment will use the teleconsultation or not.
linkTeleconsultationstringNoNoThe link to join the teleconsultation.
isFlaggedbooleanNoNoIf an appointment may need to be rescheduled because the associated slot is no longer available.
statusstringYesNoThe status of the appointment: AVAILABLE (reserved but not confirmed) or BOOKED (confirmed).
lockExpirationdateNoYesThe expiration of the slot's temporary lock (expressed in format ISO 8601), set when the slot is locked with the PATCH /slots/lock/:id.
tip

On top of the aforementioned fields, you can add any field you want to the CRUD. The service will treat them as the CRUD would.

danger

If you want to use the Appointment Manager in conjunction with the Calendar component of the Backoffice, you need to add a required property title (string) to your CRUD.

As explained in the service overview, the service assumes that the users involved in an appointment are contained in one or more attributes of the appointment itself.

When you create your CRUD you will need to create a new field for each category of users you will need to involve in the event. These fields have to be of type string or array of string.

Availabilities CRUD collection

info

v2.0.0 Starting from v2.0.0 a document in the availabilities CRUD collection represents a single or recurring availability, while the daily occurrences of each availability are computed dynamically. For users coming from version 1.x.x, the field slotIds is no longer used since slots are computed dinamically, and we use the unique identifier generated from the CRUD for each availability to replace recurrenceUuid.

The new availabilityId field is introduced to link an appointment to an availability and, in combination with startDate and endDate, to a specific slot.

The Appointment Manager can also have a CRUD containing the availabilities. The collection can have any name you want, as long as you specify the correct name in the AVAILABILITIES_CRUD_NAME environment variable.

The availabilities collection must have the following fields:

NameTypeRequiredDescription
startDatedateYesStart date/time of the first occurrence of the availability, expressed in format ISO 8601
endDatedateYesEnd date/time of the first occurrence of the availability, expressed in format ISO 8601
slotDurationnumberYesThe duration of the slot (in minutes)
simultaneousSlotsNumbernumberYesThe number of appointments you can book in each slot.
eachstringNoThe frequency of a recurring availability: daily (day), weekly (week) or monthly (month).
onArray of numberNoThe weekdays on which a weekly availability occurs (0 for Sunday, 1 for Monday, 2 for Tuesday, and so on).
untilDatedateNoThe expiration date of a recurring availability. If the field is omitted, the availability never expires.
timeZonestringNoThe IANA time zone of the availability
tip

On top of the aforementioned fields, you can add any custom field you want to the CRUD. The service will treat them as the CRUD would.

Exceptions CRUD collection

info

v2.0.0 Starting from v2.0.0 the Appointment Manager needs an exceptions collection when used in full mode.

The Appointment Manager can have also a CRUD containing the exceptions. The collection can have any name you want, as long as you specify the correct name in the EXCEPTIONS_CRUD_NAME environment variable.

The exceptions collection must have the following fields:

NameTypeRequiredDescription
startDatedateYesStart date/time of the exception, expressed in format ISO 8601
endDatedateYesEnd date/time of the exception, expressed in format ISO 8601
reasonstringNoThe reason for the absence of the resource (a doctor vacation, an equipment out of use, ...)
tip

On top of the aforementioned fields, you can add any field you want to the CRUD. The service will treat them as the CRUD would.

Users CRUD collection

The Appointment Manager uses the users CRUD collection to fetch additional information about appointments participants. This collection is currently required only by the following endpoints:

  • POST /searches/first-available-slot/.

Appointments mode

This section provide instructions on how to configure the Appointment Manager to deploy it in appointments mode.

  • Create the service configuration JSON file, defining the users to notify and the external services to integrate with.

  • If you enabled the integration with the teleconsultation service, setting isTeleconsultationAvailable to true, set the following environment variables:

    • TELECONSULTATION_SERVICE_NAME;
    • TELECONSULTATION_ENDPOINT_FE;
    • TELECONSULTATION_BASE_PATH.
  • If you enabled the integration with the messaging service, setting isMessagingAvailable to true, set the following environment variables:

    • MESSAGING_SERVICE_NAME.
  • If you enabled the integration with the timer service, setting both isMessagingAvailable and isTimerAvailable to true, set the following environment variables:

    • MESSAGING_SERVICE_NAME;
    • TIMER_SERVICE_NAME.
  • Choose a name for the CRUD field containing the resource ID (e.g. resourceId) and assign this value to the RESOURCE_ID_FIELD_NAME environment variable.

  • Create the appointments CRUD collection with at least the following custom properties:

    • one field for each users category defined in the service configuration;
    • the field of type string containing the resource ID (e.g. resourceId).
  • Add the name of the appointments CRUD collection to the APPOINTMENTS_CRUD_NAME environment variable.

caution

Since the reminder service in turn requires the messaging service to send reminders, if you set isTimerAvailable to true you must also set isMessagingAvailable to true.

Full mode

This section provide instructions on how to configure the Appointment Manager to deploy it in full mode.

caution

Since the reminder service in turn requires the messaging service to send reminders, if you set isTimerAvailable to true you must also set isMessagingAvailable to true.