Skip to main content
Version: 13.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.4.0 Since v2.4.0 a new service configuration field is supported: isNotificationManagerAsync.

The isNotificationManagerAsync configuration field, disabled by default, allows you to send notification through the Notification Manager asynchronously.

info

v2.3.0 Since v2.3.0 a new service configuration field is supported: isNotificationManagerAvailable.

The isNotificationManagerAvailable configuration field, disabled by default, allows you to enable or disable the integration with the Notification Manager to send messages and set reminders, as an alternative to the Messaging Service.

info

v2.2.0 Since v2.2.0 two new service configuration fields are supported: isFlexibleSlotAvailable and isParticipantStatusAvailable.

The isFlexibleSlotAvailable configuration field, disabled by default for backward compatibility, enable the creation of availabilities without specifying the slot duration, resulting in flexible slots. For more details about flexible slots, please read the Overview section.

The isParticipantStatusAvailable configuration field, disabled by default for backward compatibility, enable the participants field in the appointments CRUD to store status information about the participants. For more details about flexible slots, please read the Overview section.

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.

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.

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
}
],
"status": "accepted",
"required": true,
"acceptanceRequired": true
},
"patients": {
"update": "template_id",
"reminders": [
{
"template": "template_id_1",
"reminderMilliseconds": 86400000
},
{
"template": "template_id_2",
"reminderMilliseconds": 3600000
},
],
"status": "needs-action",
"required": true,
"acceptanceRequired": false
}
},
"channels": ["email", "push", "sms"],
"reminderThresholdMs": 86400000,
"isTeleconsultationAvailable": true,
"isMessagingAvailable": true,
"isNotificationManagerAvailable": false,
"isTimerAvailable": true,
"isFlexibleSlotAvailable": true,
"isParticipantStatusAvailable": 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) and set participant defaults.
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.
isNotificationManagerAvailableNofalseIf the Notification Manager service is available, enable the integration to send messages and set reminders.
isNotificationManagerAsyncNofalseIf the call to the Notification Manager should be executed asynchronously
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.
isFlexibleSlotAvailableNofalseIf you can create availabilities without setting a fixed slot duration.
isParticipantStatusAvailableNofalseIf additional status information about the participants are stored in the appointments CRUD.
defaultLockDurationMsNo-The default duration of the temporary slot lock (in milliseconds).
danger

v2.4.0 If the configuration filed isNotificationManagerAsync is set to true the call to the Notification Manager is no longer awaited. If any errors occur during the sending of the notification they will not be present in errors array of the response.

danger

v2.3.0 Starting with version 2.3.0, you can choose if you want to send messages and reminders using the Messaging Service or the Notification Manager, but you can't have them both enabled, so if you set both the isMessagingAvailable and isNotificationManagerAvailable configuration fields to true, the AM service returns an error on startup.

users

info

v2.3.0 Starting with version 2.3.0, if you choose to send messages and reminders using the Notification Manager, you must configure which messages and reminders to send using NM notification settings.

With this field you can specify, for each category of users, which template to use when sending messages on different phases of an appointment lifecycle (see the service overview for more information), and the default values for the participation status fields.

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
}
],
"status": "accepted|declined|tentative|needs-action",
"required": true,
"acceptanceRequired": true
}
}
Message templates

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

Participant status
info

v2.2.0

The status, required and acceptanceRequired fields are available only if the isParticipantStatusAvailable configuration field is set to true.

The status, required and acceptanceRequired fields allow you to specify, for a given user category, the default values. Since these fields are fully managed by the AM and accessible in read only through the API, setting these defaults is currently the only way to set the corresponding values in the appointment CRUD fields.

The following table gives you an overview of how you can configure these fields.

NameTypeDescription
statusstringIf the user accepts (accepted), declines (declined) or tentatively accepts (tentative) the appointment. Omit the field or set it to needs-action if you expect the participant to provide an explicit feedback.
requiredbooleanIf the participant is required to participate.
acceptanceRequiredbooleanIf the participants must answers to the invitation by accepting or declining explicitly the appointment.

The status field can have the following values, that follow the semantic of the FHIR Participation Status standard:

  • accepted: the participant accepted the appointment;
  • declined: the participant declined the appointment;
  • tentative: the participant tentatively accepted the appointment;
  • needs-action: the participant did not provide a feedback about the participation.

So, if you have a users field looking like this:

{
"users": {
"doctor": {
"status": "accepted",
"required": true,
"acceptanceRequired": false
},
"patients": {
"status": "needs-action",
"required": true
}
}
}

and a new appointment is created with the following custom user fields:

{
"doctor": "dr.gregory.house",
"patients": ["mary.winston", "lucy.watson"]
}

then the resulting appointment has a new participants field looking like this:

{
"doctor": "dr.gregory.house",
"patients": ["mary.winston", "lucy.watson"],
"participants": [
{
"id": "dr.gregory.house",
"type": "doctor",
"status": "accepted",
"required": true,
"acceptanceRequired": false
},
{
"id": "mary.winston",
"type": "patients",
"status": "needs-action",
"required": true
},
{
"id": "lucy.watson",
"type": "patients",
"status": "needs-action",
"required": true
}
]
}

To summarize, for each user ID in a custom users field, a new participant is added with the following properties:

  • id (required): the user ID from the custom user field;
  • type (required): the name of the custom user field;
  • status: the value of the status field, if provided under the corresponding users configuration field;
  • required: the value of the required field, if provided under the corresponding users configuration field;
  • acceptanceRequired: the value of the acceptanceRequired field, if provided under the corresponding users configuration field.

If participants are added or removed from the custom user fields, they are automatically added or removed following the rules described above.

tip

You can include additional user properties, like first and last name, by setting the isUserAvailable configuration field.

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

caution

v2.3.0 If both this field and the isNotificationManagerAvailable field are set to true, an error is raised at startup, since only one can be enabled at the same time.

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.

isNotificationManagerAvailable

info

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

caution

If both this field and the isMessagingAvailable field are set to true, an error is raised at startup, since only one can be enabled at the same time.

A boolean which determines if the Notification 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 using the NM notification settings.

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 and requires, when set to true, the following environment variables: USERS_CRUD_NAME, USER_ID_FIELD_NAME.

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.

isFlexibleSlotAvailable

info

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

info

This configuration option is ignored when the AM is deployed in Appointments mode.

A boolean which determines if you can create availabilities without setting a fixed slot duration.

If the value is set to false (default), you must always provide a slot duration when creating the availability (see the POST /availabilities/ endpoint) and you can only change its value later (see the PATCH /availabilities/:id endpoint).

If the value is set to true, you can create availabilities without specifying a slot duration (see the POST /availabilities/ endpoint) or you can remove a slot duration from an existing availability (see the PATCH /availabilities/:id endpoint).

isParticipantStatusAvailable

info

v2.2.0 This configuration field is supported only from v2.2.0 and is disabled by default for backward compatibility.

A boolean which determines if the participants field in the appointments CRUD is required and used to store additional status information about the participants.

If the value is set to false (default), you don't need the participants fields in the CRUD and the appointment only stores the IDs of the participants in the users configuration field.

If the value is set to true, the AM automatically updates the participants field every time a participant is added or removed from the appointment through the users configuration field.

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 using the Messaging Service.
NOTIFICATION_MANAGER_NAMEIf isNotificationManagerAvailable is trueName of the Notification Manager service. Required if you want to send messages or set reminders using the Notification Manager.
TIMER_SERVICE_NAMEIf isTimerService is trueName of the Timer Service. Required if you want to set reminders using the Messaging Service.
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.
PARTICIPANT_USER_PROPERTIESIf isParticipantStatusAvailable and isUserAvailable are set to trueComma-separated list containing the fields in the users crud to insert in the appointment participants array.

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.3.0 Starting from v2.3.0, if you set reminders using the Notification Manager, the reminders are not saved in the reminderIds field.

info

v2.2.0 Starting from v2.2.0 the new participants field is used to store additional details about the participants status. You need to add the field to the CRUD only if you enable the feature by explicitly setting the isParticipantStatusAvailable configuration field to true.

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.
participantsarray of objectNoNoA list of all the participants with status information.

Each participant has the following properties:

NameTypeRequiredDescription
idstringYesThe user ID, corresponding to the value in the custom user field.
typestringYesThe role or group the user belongs to, corresponding to the name of the custom user field containing it.
statusstringYesIf the user (tentatively) accepted or declined the appointment. Admitted values: accepted, declined, tentative, needs-action. These values have the same semantic of the FHIR ParticipationStatus value set.
requiredbooleanYesIf the user is required to attend the appointment.
acceptanceRequiredbooleanYesIf the user is expected to explicitly accept or decline the participation to the appointment.

You also need to create a required string field named as specified in the RESOURCE_ID_FIELD_NAME environment variable.

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.

The AM will automatically keep the participants field aligned with these fields.

Availabilities CRUD collection

info

v2.2.0 Starting from v2.2.0 the slot duration (slotDuration) is no longer required if isFlexibleSlotAvailable configuration option is set to true (false by default), resulting in flexible duration slots. For more details about flexible duration slots, take a look at the Overview section.

The following optional fields have been added: onCreate, onUpdate, onDelete and onCompute. If you have custom properties with these names, please rename them before upgrading from a version prior to 2.2.0.

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
slotDurationnumberNoThe duration of the slot (in minutes). Required before version 2.2.0.
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.
onCreateObjectNoThe custom behaviors when the availability is created.
onUpdateObjectNoThe custom behaviors when the availability is updated.
onDeleteObjectNoThe custom behaviors when the availability is deleted.
onComputeObjectNoThe custom behaviors when the availability occurrences and slots are computed.

You also need to create a required string field named as specified in the RESOURCE_ID_FIELD_NAME environment variable.

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, ...)

You also need to create a required string field named as specified in the RESOURCE_ID_FIELD_NAME environment variable.

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

caution

v2.3.0 Starting with version 2.3.0, you can choose between two different configurations to send messages or reminders:

You should choose carefully which configuration to use, since you cannot easily change it later.

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.
  • (v2.3.0 and later) If you enabled the integration with the Notification Manager service, setting isNotificationManagerAvailable to true, set the following environment variables:

    • NOTIFICATION_MANAGER_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.
  • If you enabled the integration with an external users CRUD, setting the isUserAvailable to true, set the following environment variables:

  • If you enabled the participants field with user properties, setting both isParticipantStatusAvailable and isUserAvailable to true, set the following environment variables:

  • Choose a name for the CRUDs 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:

  • 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.