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

Name	Required	Default	Description
users	Yes	-	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.
channels	Yes	-	The list of channels to send messages on (currently supported channels: email, push, sms)
reminderThresholdMs	No	0	Send reminders only at least as early before the appointment starts. Zero means the reminders, if enabled, are always sent
isTeleconsultationAvailable	No	false	If the teleconsultation service is available, enable the integration to generate teleconsultation links.
isMessagingAvailable	No	false	If the messaging service is available, enable the integration to send messages and reminders.
isNotificationManagerAvailable	No	false	If the Notification Manager service is available, enable the integration to send messages and set reminders.
isTimerAvailable	No	false	If the timer service is available, enable the integration to set reminders.
isUserAvailable	No	false	If the resources crud path is available, enable to recover resource's information for POST /searches/first-available-slot/ endpoint.
isFlexibleSlotAvailable	No	false	If you can create availabilities without setting a fixed slot duration.
isParticipantStatusAvailable	No	false	If additional status information about the participants are stored in the appointments CRUD.
defaultLockDurationMs	No	-	The default duration of the temporary slot lock (in milliseconds).

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.

Name	Type	Description
status	string	If 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.
required	boolean	If the participant is required to participate.
acceptanceRequired	boolean	If 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.

Name	Required	Description
CONFIGURATION_PATH	Yes	Path of the config map file containing the service configuration.
CRUD_SERVICE_NAME	Yes	Name of the CRUD service.
RESOURCE_ID_FIELD_NAME	Yes	Name of the CRUD field containing the resource ID (the field must be present in the availabilities, appointments and exceptions CRUD collections).
DEFAULT_TIME_ZONE	Yes	Default IANA time zone, to be used when no time zone is specified by the client when creating new availabilities.
APPOINTMENTS_CRUD_NAME	Yes	Name of the CRUD collection containing the appointments.
AVAILABILITIES_CRUD_NAME	In full mode	Name of the CRUD collection containing the availabilities.
EXCEPTIONS_CRUD_NAME	In full mode	Name of the CRUD collection containing the exceptions.
USERS_CRUD_NAME	If isUserAvailable is true	Name of the CRUD collection containing the users.
USER_ID_FIELD_NAME	If isUserAvailable is true	Name of the CRUD field containing the user ID in the users CRUD.
MESSAGING_SERVICE_NAME	If isMessagingAvailable or isTimerService is true	Name of the Messaging Service. Required if you want to send messages or set reminders using the Messaging Service.
NOTIFICATION_MANAGER_NAME	If isNotificationManagerAvailable is true	Name of the Notification Manager service. Required if you want to send messages or set reminders using the Notification Manager.
TIMER_SERVICE_NAME	If isTimerService is true	Name of the Timer Service. Required if you want to set reminders using the Messaging Service.
TELECONSULTATION_SERVICE_NAME	If isTeleconsultationAvailable is true	Name of the teleconsultation service. Required if you want to create teleconsultations.
TELECONSULTATION_ENDPOINT_FE	If isTeleconsultationAvailable is true	Endpoint associated with the Teleconsultation Service FrontEnd (the root). Required if you want to create teleconsultations.
TELECONSULTATION_BASE_PATH	If isTeleconsultationAvailable is true	Custom base path for the teleconsultation URL. Required if you want to create teleconsultations.
PARTICIPANT_USER_PROPERTIES	If isParticipantStatusAvailable and isUserAvailable are set to true	Comma-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:

Name	Type	Required	Nullable	Description
startDate	date	Yes	No	Start date/time expressed in format ISO 8601.
endDate	date	Yes	No	End date/time expressed in format ISO 8601.
availabilityId	string	In full mode	No	ID of the appointment's related availability.
ownerId	string	In full mode	No	User who booked the appointment.
slotId	string	No	No	Slot ID for backward compatibility.
reminderMilliseconds	number	No	No	Amount of time before the appointment when users are notified about it (expressed in milliseconds).
reminderIds	array of ObjectId	No	No	List of unique identifiers of the reminders associated with the appointment.
channels	array of string	No	No	List of communication channels used to send messages and reminders. Possible values are email, sms, and push.
isRemote	boolean	No	No	If an appointment will use the teleconsultation or not.
linkTeleconsultation	string	No	No	The link to join the teleconsultation.
isFlagged	boolean	No	No	If an appointment may need to be rescheduled because the associated slot is no longer available.
status	string	Yes	No	The status of the appointment: AVAILABLE (reserved but not confirmed) or BOOKED (confirmed).
lockExpiration	date	No	Yes	The expiration of the slot's temporary lock (expressed in format ISO 8601), set when the slot is locked with the PATCH /slots/lock/:id.
participants	array of object	No	No	A list of all the participants with status information.

Each participant has the following properties:

Name	Type	Required	Description
id	string	Yes	The user ID, corresponding to the value in the custom user field.
type	string	Yes	The role or group the user belongs to, corresponding to the name of the custom user field containing it.
status	string	Yes	If 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.
required	boolean	Yes	If the user is required to attend the appointment.
acceptanceRequired	boolean	Yes	If 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:

Name	Type	Required	Description
startDate	date	Yes	Start date/time of the first occurrence of the availability, expressed in format ISO 8601
endDate	date	Yes	End date/time of the first occurrence of the availability, expressed in format ISO 8601
slotDuration	number	No	The duration of the slot (in minutes). Required before version 2.2.0.
simultaneousSlotsNumber	number	Yes	The number of appointments you can book in each slot.
each	string	No	The frequency of a recurring availability: daily (day), weekly (week) or monthly (month).
on	Array of number	No	The weekdays on which a weekly availability occurs (0 for Sunday, 1 for Monday, 2 for Tuesday, and so on).
untilDate	date	No	The expiration date of a recurring availability. If the field is omitted, the availability never expires.
timeZone	string	No	The IANA time zone of the availability.
onCreate	Object	No	The custom behaviors when the availability is created.
onUpdate	Object	No	The custom behaviors when the availability is updated.
onDelete	Object	No	The custom behaviors when the availability is deleted.
onCompute	Object	No	The 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:

Name	Type	Required	Description
startDate	date	Yes	Start date/time of the exception, expressed in format ISO 8601
endDate	date	Yes	End date/time of the exception, expressed in format ISO 8601
reason	string	No	The 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:

• use the Messaging Service to send messages and the Timer Service to send the reminders;
• use the Notification Manager to both send messages and 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:

  • USERS_CRUD_NAME: the name of the users CRUD collection;
  • USER_ID_FIELD_NAME: the name of the users CRUD collection field containing the user ID as passed in the custom user fields;

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

  • USERS_CRUD_NAME: the name of the users CRUD collection;
  • USER_ID_FIELD_NAME: the name of the users CRUD collection field containing the user ID as passed in the custom user fields;
  • PARTICIPANT_USER_PROPERTIES: a comma-separated list of users CRUD collection fields to add to each appointment participant under the userProperties field.

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

  • one field for each users category defined in the service configuration;
  • a required field with type string containing the resource ID (e.g. resourceId);
  • the participants field, if you set the isParticipantStatusAvailable configuration field to true.

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

• Configure the service performing all the steps described in Appointments mode

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

  • a required field with type string containing the resource ID (e.g. resourceId);

• Add the name of the availabilities CRUD collection to the AVAILABILITIES_CRUD_NAME environment variable.

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

  • a required field with type string containing the resource ID (e.g. resourceId);

• Add the name of the exceptions CRUD collection to the EXCEPTIONS_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.