Developed by Dr. P. S. Ramkumar (ITU)

5.1 Requirements

The Cross-cutting requirements described in this section are an extension of the cross-cutting requirements defined in the architecture specification document.

5.1.1 Source code considerations (RECOMMENDED)

Since Scheduler provides time-based triggering of various Building Blocks/Applications, the Scheduler Building Block may use pre-compiled code in the microservices instead of run-time interpreter-based scripted code, to minimize latency in utilizing the time-keeping functions of the underlying operating system.

5.1.2 Infrastructure considerations (RECOMMENDED)

For mission-critical applications, it is recommended to use Scheduler as an embedded internal block of the target Building Block or application. In general, for minimizing internet latency it may be suitable to collocate the scheduler in the same infrastructure hosting other Building Blocks. Multiple instances of Scheduler Building Block may be hosted with load balancing in high-concurrency demand.

5.1.3 Audit considerations (REQUIRED)

Building Block must provide internal functionality to log and report indicators (such as latency, traffic density, queue depth, system resource consumption, service exceptions, and failures, etc.) provisioning and maintaining adequate Quality of Service (QOS). Building Block must provide internal functionality to configure rules to monitor, detect and notify QOS issues to Administrators.

5.1.4 Service caller authentication (REQUIRED)

In all service calls to the Scheduler Building Block, the requestor's token (maybe JWT containing requestor's authentication and requesting application ID) will be published along with the payload of the request, as a security requirement. The BB must be able to independently verify the token with a central IAM server to make sure the service call is from an authenticated user and from an authenticated Application within Govstack.

5.2 Exceptions to Architectural Cross-Cutting Specifications

5.2.1 SQL/NoSQL databases

Local factors (cost, convenience, existing Databases, skillsets, suitability of data structures, etc.) of a given target demography will influence this decision. In practical settings, such factors may lead to an implementation time decision of appropriate databases. From GovStack's point of view, the Scheduler Building Block needs to be agnostic to the type of database implementation and allow flexible choice.

5.2.2 Use of stored procedures

Several mundane localized operations on data such as searching, filtering, and format transformations may find a better performance by being collocated with the database itself in the form of stored procedures in typical SQL databases. Such procedures must be configured to handle the concurrent processing of multiple requests, with an appropriate mechanism (e.g. SQL agents/SSIS packages/service brokers/etc.). Since data is collocated with the code, when scaled up to clusters of multiple instances of database servers, each instance will utilize local Safeguard for Privileged Sessions. However, this will create an additional burden on maintenance and update of source code as applications may have part of logic in backend code and partially embedded in database servers. To host complex queries related to data from different databases it is recommended to implement it in business logic rather than stored procedures. In this case, scalability must be ensured by suitable application infrastructure scaling mechanisms such as Virtual Machine-level scaling and automatic elastic frameworks.

5.3 Standards

The following standards are applicable to data structures in the Scheduler Building Block:

Typical data structure requirements and format representations relevant to this Building Block have been TMF646_Appointment_API_Specification_R19.0.0_fixed. However, the schema and data elements are optimized for minimizing footprint and external dependencies, given that this Building Block handles time-critical alerts. The common minimum datasets have been described in the schema and the table in the Data Structures Section.

Digital governance may employ common software components (Building Blocks) to automate heterogeneous software applications. Different activities of such components may be triggered based on a specific epoch (date-time) in order to orchestrate a sequence of steps within an automated workflow. Instead of replicating the logic needed by each component to schedule, track, trigger and coordinate its activities with other building blocks and applications the "Scheduler" Building Block enables aggregated coordination of time-driven activities within and across Building Blocks by sending appropriate "alert" messages to appropriate Building Blocks according to a predefined schedule.

Each event is identified by an ID field and has a specific name, date, time, and duration. An event may empanel multiple resources (personnel, facilities, equipment, etc.) from different entities to perform various activities. An event may also enrol subscribers to benefit from activities of the event. The Scheduler may have to alert (trigger) specific resources and subscribers at specific times before, during, and after the event. With specific messages in order to carry out respective activities. The Scheduler Building Block contains various functionalities necessary to enable planning, booking, tracking, triggering, notifying, and status reporting needs of multiple events. It hosts several micro-services that orchestrate these functionalities, exposed through RESTful APIs. This Building Block can be used for scheduling events in a wide variety of applications and use cases such as:

Health sector

• Booking appointments with service providers for consultation, therapy, tests, etc.

• Planning and tracking prescribed activities for medication, diet, or exercises.

• Acquiring periodic reports from medical monitoring devices.

eCommerce Sector

• Shipment planning and tracking in supply chain management.

• Announcements for public awareness and programs.

• Maintenance checks for equipment.

Agriculture sector

• Custom planning for agricultural activity such as seeding, harvesting, etc., involving agro-machinery and skilled labor force.

• Planning and booking of third-party services such as machinery maintenance, transportation, etc.

Education sector

• Scheduling classes, exams, official meetings, seminars, etc.

• Scheduled events as deadline-based submission of assignments, reports, etc.

2.1 Current scope

The functional requirements to cover the services required from the Scheduler Building Block currently have considered specific use cases of

• Post-Partum Child Care program (https://app.gitbook.com/o/pxmRWOPoaU8fUAbbcrus/s/YLLEfCKTnmzAMDSDzJJH/product-use-case/hltc-1-postpartum-and-infant-care).

• Unconditional Social Cash Transfer program. https://app.gitbook.com/o/pxmRWOPoaU8fUAbbcrus/s/YLLEfCKTnmzAMDSDzJJH/product-use-case/inst-1-unconditional-social-cash-transfer.

These use cases bring forth the need for example implementations of events such as scheduling doctor appointment for patients, scheduling payroll computation for health workers, and disbursement of salaries and incentives for health workers and beneficiaries of the programs. However, the considerations can be generalized for different types of events involving one or more participants.

Currently the following actors have been identified as "users" of the scheduler building block:

• "Building Block Admin" who manages the building block's implementation settings. A building block admin is also responsible to enrolment of entitles and Organizers of those entities that use the scheduler building block.

• "Resources" who participate in events to perform various services. Resources MUST be registered in the Scheduler before they can be enrolled in events. Resources MAY provide services in multiple entities in time-shared mode (e.g. specialist doctors provide services in multiple hospitals). Hence a registered resource MUST also be affiliated in specific work days and hours to a Host entity, before participation in the events of that entity.

• "Organizer" are resources who manage event schedules using the Scheduler. An Organizer must be a registered and affiliated to a Host entity to manage the events of that entity.

• "Subscribers" who participate in events to consume various activities. Subscribers must be registered in the Scheduler before they can be enrolled in events. Subscribers MAY be enrolled in multiple events.

The Scheduler MUST be able to enable enable these actors to perform in their roles associated with one or more events. More specifically, the scheduler should facilitate following activities of the actors:

2.1.1. The Scheduler MUST enable Building Block Admins to

• register without duplication an entity, into its Entity List with details (e.g. name, phone, email, website, etc.) The entities host various "events" involving their affiliated resources.

• categorize entities for easy searching and sorting. In current scope, "Hospital", "Health ministry", "Social welfare ministry" may be example entities.

• register resources and affiliate them as "Organizer" in specific entity for management of events hosted by that entity.

• configure rules for performance, security and communication management between the scheduler and other building blocks, applications and event participants. The exact parameters may be decided at implementation time

• extract log reports from the system as needed for monitoring and administering the building block operations.

2.1.2 The scheduler MUST enable Organizers to

• register resources (persons, facilities, equipment, s/w building blocks/apps, vehicles, etc.) without duplication into Scheduler's resource list with contact details (phone/mail/URL/), as needed for communication and reuse for enrolment to multiple events.

• categorize resources for easy searching and sorting. In current scope, "doctor", 'payroll app" and "Payments app" are example resource categories.

• affiliate a registered resource into one or more entities with non-overlapping weekdays and working hours. (e.g. a doctor could provide consultation during mornings at a specific hospital, and teaching at another entity in afternoon on specific weekdays).

• register subscribers (persons, equipment, s/w building blocks/apps, etc.) without duplication into Scheduler's Subscriber list with contact details (phone/mail/URL/) as needed for communication, and reuse for enrolment to multiple events.

• categorize Subscribers for easy searching and sorting. In current scope, "patient", "beneficiary", "student" are example resource categories.

• register events with a defined starting and ending time and an optional deadline for participants to log in their attendance in the event, if needed.

• to restricted number of Subscribers to an event.

• to categorize events for easy searching and sorting. In current scope, "doctor consultation", 'payroll" and "Payments" are example event categories.

• brand an event by name and description. An organizer must be able to define a name and description for an event as needed.

• search for resources of a specific category in a specific registered entity

• search for free (unallocated) time slots of specific resources in a chosen date-time range

• enroll a registered resource of the Host entity into a predefined event to provide respective services (before/during/after the event). The same resource may be enrolled into multiple non-overlapping events within the affiliated work days and hours of that resource in the Host entity

• search and list details of events with a chosen category, host entity and resource which are open for subscription in a given date time range

• enroll a registered subscriber into a predefined event to participate as a beneficiary of the event. The same subscriber may be enrolled to multiple events, but each enrollment will generate a unique appointment id

• define and maintain a library of predefined stack of messages for specific Host entity so that it can be reused in multiple events conducted by the specific host entity.

• define alert schedules for sending specific Alert messages associated with specific event at specific date-time to associated subscribers or resources or both.

• define multiple alert schedules (before, during, after) for the same event

• to extract logs related to events that help in continuous improvement in event management

• search and extract details of one or more events, resources, subscribers, alert messages templates and logs associated with entities where the Organizer is also affiliated with.

2.1.3 The scheduler MUST enable Resources to

• search and extract their own registration details in the scheduler

• search and extract their own affiliation details across associated entities

• search and extract details of appointments and events they are enrolled into

• search and extract details of subscribers of events they are enrolled into

• receive scheduled alert messages from events they are enrolled into

• search and list details of events of chosen category, host entity in a specified date-time range

• log status/attendance updates related to events they are enrolled into

2.1.4 The scheduler MUST enable Subscribers to

• search and extract their own registration details in the scheduler

• search and list details of events with a chosen category, host entity and resource which are open for subscription in a specified date-time range

• enroll themselves into a predefined event to participate as a beneficiary of the event and obtain corresponding unique appointment id

• search and extract details of appointments and events they are enrolled into

• receive scheduled alert messages from events they are enrolled into

• log status/attendance updates related to events they are enrolled into

2.1.5 The Scheduler must automated internal functionality to

• track all alert schedules and send corresponding alert messages with unique tokens to relevant participants at appropriate times

• Log each alert sent with date-time stamp and a unique token in Scheduler's log that can be used later to relate responses from recipients of the alerts.

• receive and log acknowledgement/status/attendance updates from event participants date time stamp, optional location stamp and sender information.

• update event status(started/ended/open/closed) depending on date-time and subscriber limit

• poll participants for status updates, by giving the unique token of a specific alert it sent.

• log transactions done by all actors along with actor type and id and date time stamp. Associated implementation specific details that are not specified here.

• monitor and log internal metrics (e.g. latency/capacity utilization/communication failures/etc.) to help in maintenance and capacity management depending on needs of implementation. Associated implementation specific details that are not specified here.

• detect communication failure with other building blocks and applications and perform retries according to configured rules before logging a communication failure. Associated implementation specific details that are not specified here.

• monitor the logs and mark the participant as absent an attendance log did not arrive within a specified deadline. Associated implementation specific details that are not specified here.

2.2 Out of Scope

The following aspects are out of scope of the current version of the scheduler building block specifications considered in this document:

• Evaluation of any criteria other than time-based evaluations for the generation of a trigger is out of scope. The Scheduler can be used to trigger activities based on time only.

• Alerts based on human decision are out of scope. This Scheduler specification is intended for automation of time-based alerting process only.

• Any logical evaluations prior to the onset of alerting applications or building blocks are out of scope. (e.g. repeating an alert if acknowledgement is not received for previous alert)

• An event participant MUST implement own logic to evaluate other conditions as needed before taking action based on an alert. (e.g. if an accounts application is alerted to initiate salary payments but it must check if a payroll has been approved before initiating payments).

• The Scheduler can be used to trigger activities based on time only. Evaluation of any criteria other than time-based evaluations for the generation of a trigger is out of scope.

• Alerts based purely on human decision are out of scope.

The Scheduler can be visualized as a black box with all key digital functionalities discussed in section 4 built-in and all interactions with the building block happening through RESTful API interfaces that exchange service requests and responses with external Building Blocks or Applications. A brief description of the functional requirements required to orchestrate each key digital functionality is been given below, considering a minimum viable product perspective. Detailed design and more elaborate feature lists of these blocks can be customized by developers to optimally match respective implementation needs. It is also left to the application to receive the responses from the scheduler and present it appropriately (e.g. as an Event list or calendar) and provision for associated user interface interactions

6.1 Event Management

• The Scheduler must enable an event organizer to create/update/delete/modify/search and list schedule details of multiple events. The Scheduler must enable setting up in advance with a minimum of a specified starting and ending date-time of an event, an event name and category and placeholders for other details that can be populated later on (REQUIRED)

• It must be possible the modification of event details after registration of the new event scheduled in the Scheduler's Event List (REQUIRED)

• The Scheduler must not allow the addition/modification of any details of an event after the scheduled event is over (REQUIRED)

• In the case of events such as workshops, training sessions, medical camps, marketplace exhibitions, etc., which may host repeated events at different places by different resources for different subscribers, the Events could have the same name, but each instance would have a unique ID. The Scheduler must not allow events with the same name and same host entity to overlap at the same date-time epochs (REQUIRED)

• It must be possible to find details of all events in a chosen date-time range, filtered by a given category, having specific resources and still open for a subscription (REQUIRED)

• If an event is deleted, the Scheduler must remove all dependent appointments of resources and subscribers and all scheduled alerts associated with an event and notify the organizer of the host entity (REQUIRED)

• The Scheduler should send notifications to all resources and subscribers when an associated event is deleted (RECOMMENDED)

6.2 Entity Management

• This sub-block must enable event administrators to create/update/delete/search and list entities that host various event schedules using the Scheduler (REQUIRED)

• All the details about the entity must be stored in a common internal repository so that the resources may be affiliated with multiple entities and booked into multiple events as needed (REQUIRED)

• An entity must have at least one affiliated resource in the Organizer role to manage event scheduling on behalf of the entity. An entity may affiliate with multiple registered resources (REQUIRED)

• When a new resource or alert or event is registered, if the Scheduler finds that the entity is already registered, it must prompt the user and avoid duplication of the registration. An Entity must have a unique single id against its registration in the Scheduler (REQUIRED)

6.3 Alert Schedule Management

• The Scheduler must enable an organizer to create/update/delete/search and list alert_schedules for sending alert messages in association with a specific event. A single alert schedule specifies details of only one epoch of sending a specific message to a specific category of participants of a single event (REQUIRED)

• Each alert schedule must enable sending of the same message to multiple targets (resources/subscribers/both) of a specific event (REQUIRED)

• The Scheduler must assign a unique Id to each alert schedule (REQUIRED)

• The Scheduler must not allow the reuse of an alert scheduler either in the same or another event (REQUIRED)

• All the details about the alert schedules must be stored in a common internal repository so that the alerts may be sent to multiple targets in high throughput environments (REQUIRED)

• The Scheduler must enable an organizer to configure a specific date-time before/during/after the event (REQUIRED)

• The Scheduler must enable the Organizer to choose if the alert should target either all subscribers or all resources or both types of participants in a specific event (REQUIRED)

• The Scheduler must track alert schedules and initiate sending of appropriate alert messages at specified date-time epochs to the Resources and Subscribers accordingly (REQUIRED)

• The alert messages must be composed with associated supplementary information (e.g. who is sending, for which event, what category of message, etc.) along with corresponding contact information and routed to appropriate channels, such as Information Mediator Building Block, Messaging Building Block, or Pub/Sub service (REQUIRED)

• If an alert schedule is deleted, the Scheduler must remove the alert schedule from all its associated events and notify the organizer of the Host entity of the event (REQUIRED)

6.4 Alert Message Management

• The Scheduler must enable an event organizer to create/update/delete/modify/list Alert message templates that can be used to communicate with participants of events. (e.g. appointment reminders to various patients, triggering a periodic transfer of salaries, etc.) (REQUIRED)

• Alert messages must be tagged to a specific host entity and are not accessible to other entities. Each entity must retain its own stack of alert message templates (REQUIRED)

• All the details about the message must be stored in a common internal repository so that the messages may be reused into multiple events in high throughput environments (REQUIRED)

• The Scheduler must generate a unique id for each new message registered, which is independent of which events the message is used in. This is needed to uniquely find and reuse details of the message for various events as needed (REQUIRED)

• In the current scope, only textual messages are considered as content of the templates (RECOMMENDED)

• The Scheduler must have the capability to send alerts tagged to a specific token number to targets either directly to a Rest-API of the target Building Block or through Messaging Building Block or through its Information Mediator Building Block Pub/Sub room. The choice is an implementation time decision, but it is preferred to use direct alerting sparingly for synchronous (time-critical) alerts, other asynchronous alerts can use Messaging Building Block based alerts suited for endpoints on mobile client apps, while Pub/Sub should be chosen only when it is okay the art has no control of who should read it in Pub/Sub room (REQUIRED)

• If an alert message template is deleted, the Scheduler must delete the bindings to any future events and notify the organizer of the entity about the deletion (REQUIRED)

6.5 Resource management

• The Scheduler must enable an event organizer to create/update/modify/search and list multiple Resources (persons/facilities/equipment/vehicles/etc.) as needed for taking part in various events (REQUIRED)

• All the details about the Resource must be stored in a common internal repository so that the resources may be affiliated with multiple entities and booked into multiple events as needed (REQUIRED)

• Each Resource must be defined with a specific category (doctors/nurses/ambulance/room/ etc.) that helps in the grouping, searching, and selection of the resource (REQUIRED)

• Contact details of Resource (email/SMS/webhook/etc. along with a default option) must be registered along with the Resource (REQUIRED)

• The Scheduler must generate a unique ID for each new resource registered, which is independent of which events the resource participates in. This is needed to uniquely find and reuse details of the resource for various events as needed (REQUIRED)

• The preferred mode of communication (mail/sms/URL) with the resource must be captured along with corresponding contact details (REQUIRED)

• It must be possible to identify free (unallocated) time zones in a given date-time range for a chosen resource limited by the resource's affiliated work day/hours in a given host entity (REQUIRED)

• The Scheduler must convey resource ID to a specific resource upon registration (REQUIRED)

• The Scheduler must delete all affiliations and future appointments of a resource that is deleted. In a real-world implementation, a resource may be just deactivated instead of actually deleted (REQUIRED)

• If a Resource is deleted, the corresponding resource and Organizers of all affiliated entities must be notified about the deletion. In a real-world implementation, a resource may be de-affiliated in a particular entity, instead of deletion from the resource registry (REQUIRED)

6.6 Subscriber management

• The Scheduler must enable an event organizer to create/update/modify/search and list subscribers (persons/facilities/equipment/vehicles/etc.) as needed for taking part in various events (REQUIRED)

• All the details about the subscriber must be stored in a common internal repository so that the subscribers may be enrolled into multiple events as their contact details be reused to send alerts as needed (REQUIRED)

• A Subscriber may be affiliated with multiple Events that do not overlap with each other in date-time (OPTIONAL)

• Contact details of the subscriber (email/sms/webhook/etc. along with default option) must be registered along with the subscriber (REQUIRED)

• The Scheduler must generate a unique ID for each new subscriber registered, which is independent of which events the subscribers participate in. This is needed to uniquely find and reuse details of the subscriber for various events as needed (REQUIRED)

• The Scheduler must convey subscriber ID to a specific subscriber upon registration (REQUIRED)

• If a subscriber is deleted the Scheduler must delete all future appointments of the subscriber. In a real-world implementation, a subscriber may be just deactivated instead of actually deleted (REQUIRED)

6.7 Affiliation Management

• The Scheduler must enable an event organizer to create/update/delete/list affiliation of the organizer's entity with multiple Resources (persons/facilities/equipment/vehicles/etc.) as needed for various events hosted by that entity (REQUIRED)

• All the details about the Resource must be stored in a common internal repository so that the resources may be affiliated with multiple entities and booked into multiple events as needed (REQUIRED)

• A Resource must be affiliated with at least one entity with specific working hours during registration. Subsequently, the same Resource may be affiliated into multiple entities such that the weekdays and working hours allocated to affiliated entities do not overlap with each other (REQUIRED)

• The event slots for booking a resource must be restricted to the working hours of the resource in a specific entity the Resource is registered into (REQUIRED)

• A Resource may be booked into multiple entities with different affiliation IDs as long as they have non-overlapping working hours and days for that resource. However, the Resource ID shall be the same in all such affiliations (OPTIONAL)

• If an Affiliation is deleted, the corresponding resource and entity's Organizer must be notified about the deletion (REQUIRED)

6.8 Appointment Management

• This sub-block must enable an event organizer to add/modify/delete/search and list specific participants (resources and subscribers) into specific predefined events. Each new appointment will have a unique appointment ID (REQUIRED)

• All resources must have been registered in Scheduler and MUST have been affiliated with specific entities before they can be enrolled in different events (REQUIRED)

• All actors, except the super-admin, can access information from only entities that the actor is affiliated with in the Scheduler (RECOMMENDED)

• The Scheduler must validate that specified resources, subscribers and events are pre-registered in the system before they are bound together (REQUIRED)

• The Scheduler must map a single appointment to a single resource or subscriber as a participant for a single event and be given a unique appointment ID (REQUIRED)

• The Scheduler must enable a single resource/subscriber that may have multiple appointments for different events with respective IDs (REQUIRED)

• The Scheduler must not allow duplicate entries of the same resource or subscriber for the same event (REQUIRED)

• Once a resource or a subscriber is registered in the scheduler (this is a unique ID independent of any event or appointment), the same ID is used as Participant Id in whichever appointments in which the given resource/subscriber participates (REQUIRED)

• The respective participant (subscriber/resource) organizer of the host entity must be notified if an appointment is cancelled (REQUIRED)

• Participants of an event must send IDs of the event and appointment in headers of their responses/updates sent to the scheduler through any channel (Information Mediator Building Block/PubSub/Messaging Building Block) (REQUIRED)

6.9 Status Logging and Reporting

• Recipients of alerts may send acknowledgements and participants, in general, may send status/attendance updates either directly to Scheduler or through respective Information Mediator Pub/Sub blocks or in response to a status polling request from the Scheduler to the alerted participant. The Scheduler must log all alerts sent and log updates received from participants of all events it handles and store them in a searchable indexed manner (REQUIRED)

• This sub-block must periodically monitor and log specified internal metrics (e.g. latency, queue depth, errors, system resource consumption, number of retries, etc. from critical indicators of the performance of the Scheduler Building Block).(REQUIRED)

• This sub-block must internally check logged indicators, detect anomalies and escalate reports to administrators for timely housekeeping, capacity management, backup, and audit purposes (REQUIRED)

• This sub-block must enable organizers, auditors, and administrators to query specific metrics, trends, and statistics from the logged data and get reports accordingly (REQUIRED)

• All logged messages should have information about their category, date-time and optionally location stamp, who from which entity is logging, etc. (RECOMMENDED)

• The payload size and categories of logged messages may be specified based on the implementation needs and not specified here (OPTIONAL)

6.10 Information Mediator Interface

• This sub-block runs protocols to communicate with the Information Mediator Building Block for exposing Scheduler services to external Building Blocks and applications (REQUIRED)

• It also provides specific calls to APIs of information mediator Building Block to access services of external applications and Building Blocks (REQUIRED)

• It also handles any errors and failures in data exchange between the Scheduler and other Building Blocks/Apps (such as backoff and retries, etc.) (REQUIRED)

• It routes error information if any to the logger sub-block (RECOMMENDED)

• It maintains a list of endpoint addresses of Information Mediator, other Building Blocks, and Applications. These are dedicated API interfaces defined in the Information Mediator Building Block and hence not defined here (REQUIRED)

6.11 Pub/Sub Interface

• This Block must maintain the endpoint address of specific rooms dedicated to the Scheduler Building Block to publish Alert notifications. These are dedicated API interfaces defined in the Pub/Sub (Information Mediator Building Block) and hence are not defined here (REQUIRED)

• It must also use the logging sub-block to maintain the history of Pub/Sub transactions handled by the Scheduler Building Block (REQUIRED)

• It must enable the Scheduler to subscribe with Pub/Sub rooms of other Building Blocks (such as Messaging, Accounting, Payments, etc.) (for example, to receive status updates on the completion of an ongoing event) (REQUIRED)

• This sub-block must provide a mechanism for the Scheduler Building Block to publish alerts and other messages to other Building Blocks through specific rooms in a Pub/Sub Building Block (REQUIRED)

6.12 Messaging Interface

• The Messaging interface should send relevant information to the logging sub-block to maintain the history of all messages sent from this Building Block, which are useful for audit purposes (RECOMMENDED)

• This sub-block should also route response messages coming through the Messaging Building Block from participant users/devices/applications for updating of the status/ attendance/etc. of specific events. The Scheduler should publish an endpoint for receiving notifications from messaging Building Block and a log list to log all messages received (RECOMMENDED)

• The messaging interface should provide the necessary protocol, data format, and information and interface to interact with the Messaging Building Block for sending notifications to specific target users/applications through a variety of channels (SMS/email/etc.) (RECOMMENDED)

6.13 Scheduler Administration

• This component must enable Building Block admins to configure rules for monitoring, detection, and escalation of any performance/security conditions to the administrator proactively. The exact parameters and statistical indicators may be decided at implementation time (REQUIRED)

• This sub-block must enable setup and updates of various end-point addresses (Information Mediator/other Building Blocks/PubSub/Applications/etc.) and associated communication settings such as back-off mechanisms, error handling, network breakdown resilience mechanisms, latency limits, etc. stored in various interfaces of the Building Block (REQUIRED)

• This sub-block may provide native user interfaces to administrators of this Building Block through an API Gateway, as decided during implementation time (OPTIONAL)

The various actors and their activities described in section 2 must be supported by a set of non-redundant, Key Digital Functionalities listed below:

4.1 Event Management

Authorized organizers of a host entity (such as health workers/admins/etc.)must be able to create and manage schedules of events involving several resources, subscribers, and activities that have to be reminded/triggered/informed through alerts at appropriate times before/during/after the event. Schedules of multiple events can be configured, tracked, and managed, avoiding any duplication.

4.2 Entity Management

The Scheduler must enable the administrator of the Building Block to register multiple entities that will use the Scheduler. Each entity will have at least one person registered under "resources" as an Organizer of various events hosted by that entity. An entity may have multiple affiliated resources that can be allocated to different events hosted by the entity. The Scheduler must enable the registration of details about registered entities with duplication avoidance.

4.3 Alert Schedule Management

Authorized organizers of a host entity may schedule one or more alert messages to be sent to specific resources/subscribers of an event before, during, or after an event. It also provides for the mechanism to send alert messages according to the preferred Alerting mode (through Information Mediator to a target Building Block/application URL endpoint, or publish it in its local Information Mediator + Pub/Sub module or through Messaging Building Block. Every alert sent is tagged for tracking status updates from alerted parties (for example an event started/ended/no show/etc.). Each alert sent is tagged with a unique token from Scheduler that can be used to relate responses from recipients of the alerts. The alerted Building Block/app can take appropriate actions based on the alert message and may send attendance/status to an endpoint on the scheduler along with the token. The Scheduler can also poll for status updates, by giving the unique token of a specific alert it sent.

4.4 Alert Message Management

It must be possible for an entity to have its own stack of ready-made message templates that be reused in one or more notifications in multiple events hosted by that entity. Typically organizers of the event maintain this stack of alert templates (reminders/updates/etc.) under specific categories aligned to their business needs. The alerts may further be tagged with a category (appointment reminders/ activity triggers/ etc.) for easy search and identification purposes.

4.5 Resource Management

Authorized organizers of a host entity may enrol different resources resource (persons, facilities, equipment, vehicle, etc.) into respective entities. This scheduler retains the Resource details such as its name, category (doctor/nurse/teacher/health worker/admin/etc.), contact details (phone/mail/URL), etc., as needed for communication, against a unique event id for each Resource. Organizers may search for resources that are free (unallocated) together in a chosen date-time range, or look for time zones when chosen resources are free together. The Scheduler allows multiple entities to register the same resource supported by a de-duplication filter from the Scheduler to avoid replicas in storage.

4.6 Subscriber Management

The subscriber is details of a person/equipment/facility identified by a name and contact details. The Scheduler enables registration of new subscribers by storing their profile and contact information against a unique Id in such a way the same subscriber details can be reused for subscription to several events. Subscribers may also be tagged to a category such as a student/ patient /beneficiary/etc.

4.7 Affiliation Management

The Scheduler must enable the same resource to be affiliated with multiple entities with non-overlapping weekdays and working hours. (e.g. a doctor may work at different hospitals on specific days and time spans). The organizer may allocate resources of their entity into multiple non-overlapping events within the affiliated time zone of their entity for that resource. (e.g. a doctor could provide consultation to a series of patients during their work hours at a specific hospital).

4.8 Appointment Management

This key digital functionality enables the enrollment of registered subscribers into a specific event. The same subscriber may be enrolled with different token ids into different events. In case a subscriber is a person, the person can subscribe to a chosen event or take assistance from an authorized third party (e.g. health worker or a call-center admin) to subscribe him/her self or their application/device that represents them as a participant subscriber into a chosen event.

4.9 Status Logging and Reporting

This key digital functionality maintains logs of user-driven transactions, activities originating from this Building Block as well as status updates coming from external sources. All logs contain a date time stamp, an optional location stamp, details of the information source, and the status of the transaction. For example, the Scheduler can log all alerts it generates and all events that are created/updated/cancelled. It can also log status updates from external Building Blocks or applications (e.g. completion of an event) coming through Information Mediator, Pub/Sub, or Messaging Building Block interfaces. The Scheduler must enable an authorized administrator to get a report of logged information in a chosen category and date range and category across events. The Scheduler does not retain any reports. The Scheduler may also monitor and log internal metrics (e.g. latency/capacity utilization/communication failures/etc.) to help in maintenance and capacity management depending on the needs of implementation. For example, if an alert recipient does not acknowledge within a fixed duration the Scheduler may be designed to resend the trigger/notification for a given number of retries before logging a communication success or failure. In another implementation, the Scheduler may be designed to monitor the logs and mark the participant as absent if an attendance log did not arrive within a certain duration after the alert was sent. These are implementation-specific details that are not specified here.

4.10 Information Mediator Interface

This interface handles protocols to interact with the Information Mediator Building Block in order to securely expose Scheduler services to other Building Blocks and also enables scheduler access services of other Building Blocks and applications through the Information Mediator Building Block.

4.11 PubSub Interface

The interface handles protocols to interact with Pub/Sub messaging rooms assigned to publish asynchronous messages to event participants and receive incoming messages published by participants in the Pub/Sub rooms of the host application.

4.12 Messaging Interface

The interface handles protocols to interact with the messaging Building Block for sending alerts to event participants and receiving incoming messages through the Messaging Building Block. This maintains an internal queue of messages until they are passed on to the Messaging Building Block.

4.13 Scheduler Administration

This key digital functionality enables the setting up of internal configuration requirements that define the technical behavior of the Scheduler Building Block. It also provides for an administrator to monitor and take actions that regulate the usage and performance of the Building Block. This also provides functionalities for the registration of new entities and Event Organizers within those entities.

To facilitate various activities and different actors as described in section 2, the Scheduler building block MUST have specific key digital functionalities. A scheduled event by definition should have pre-determined start and ending date time, venue, resources (to carry out some activity associated with the event) and subscribers (to consume activities of an event). For example, a doctor (resource), may provide consultation (event), to a patient(subscriber), at a specific hospital (host-entity), on specific days and time (schedule) of which patient can book a specific day and time (Appointment). Similarly, the scheduler may be configured to alert a payroll application (Resource) to calculate salary payments (event) on last day of the month (schedule) and alert a payment building block (Resource) to transfer salaries to health workers (event) in Post-Partum Care program or subsidies to beneficiaries in USCT program on first day of month (schedule).

In the current scope, examples drawn from user-journey steps of use-cases of Post-Partum care and Unconditional Social Benefit transfer programs were considered to derive Key Digital Functionalities required to orchestrate services from this Building Block. In this section, we identify workflows to manifest some of the main services. These may be enhanced or customized as needed for specific implementation needs. The following common preconditions may be needed to be met before utilizing these services:

• Entities that Host an Event registered in the Scheduler before scheduling respective events;

• Subscriber, Organizer, and Resources are registered in Scheduler before being used in Event;

• Service Endpoints of Scheduler and other Building Blocks it will interact with are already configured in Information Mediator Building Block;

• All users are logged into the GovStack Host application to do their respective tasks;

• Subscriber/Organizer knows preferred host entity, and event category to search for resources and available events;

• Any payments associated with event subscription are done outside of the Scheduler;

• Records of the latest resource and subscriber contact details stored in the Scheduler are up-to-date;

• Target Building Block is registered as publisher and Scheduler is registered as a subscriber in the “status” room of Information Mediator Building Block Pub/Sub dedicated to the target Building Block before using Pub/Sub mode for status updates/triggers;

• Event schedule with a unique ID already exists in Scheduler before seeking cancellation update;

• Scheduler can also call some of its APIs from inside for operations that do not need external interaction in a particular workflow if the information is already available internally.

This section captures the example workflows that may take place between internal functional blocks to orchestrate key functionalities for a minimum viable product as follows. The exact workflows may be decided depending on implementation time considerations.

• Event creation;

• Finding resources of a host entity which are available in a given date-time range;

• Finding event slots of a given category and resource Id in a given date-time range;

• Appointment Scheduling for the resource or subscriber to a specific event;

• Cancellation of appointment;

• Registering new Alert Message Template;

• Scheduling Alerts for a given event;

• Tracking and Alerting as per schedule;

• Cancellation of a scheduled event;

• Log Reporting;

• Registering a new entity;

• Registering a new resource;

• Affiliating an existing resource to a new entity;

• Registering a new subscriber.

9.1 Event Management

9.1.1 Event Creation

An organizer can use this workflow to create a new event in the system. The Organizer will need to feed in minimum details such as the event name, category, address, start and end date-time, host entity, terms for subscription, and subscription limit (e.g. a doctor consultation event is limited to one patient. In a training event the limit may include multiple students). Optionally, a deadline may be specified for participants to log attendance to the event (else marked as absent). The Scheduler avoids duplication of a given event by checking if the same properties are already registered in its Event_List. The start and end date-time is an JSON array structure that enables scheduling the same event multiple times at different date-time slots. It then returns either success status along with an array of unique event ids one for each requested slot, or an appropriate error code to host the application of the organizer.

9.1.2 Cancellation of scheduled event

Organizer can request the cancellation of a prescheduled event through the host app by supplying the event id. The Scheduler first removes dependent alert_schedules and appointments empanelled in the event. It then deletes the event from the event list and returns success to the host app for confirmation to the organizer. Optionally it can send out an event cancellation message through preferred channels to all subscribers and resources of the event, before deleting the event from the event list.

9.1.3 Finding events of a given type and status having a specific resource in a given date-time range

In some scenarios, one may search for events of a specific category involving a specific resource of a specific host entity (e.g. consultation with a specific doctor in a particular hospital) that are open for subscription. The organizer can feed through a host app, a date range, event type, entity ID, and resource_id seeking matching events with status=open. The Scheduler seeks its appointment_List for the event_ids of events with a given type, resource and entity, within a given time range. For each event, the Scheduler gets details of the event if the event status is = "open". The Schedule returns details of selected open events or returns the appropriate error code (e.g. if specified category/resource not found, etc.). The Host app will present the results or error appropriately to the Organizer.

9.2 Entity Management

9.2.1 Registering a new entity

A new entity that can use the Scheduler must be registered by the administrator of the Scheduler Building Block. The Administrator requests entity registration in the scheduler through Scheduler's administrative front-end user interface by supplying relevant entity details. The Scheduler after verifying the requestor's credentials will store the entity information against a new entity id it generates. In case it finds that the entity details match any of the earlier registered entities it returns an error code and avoids duplication. In the normal course, the entity id is returned to the Administrator along with a prompt to register an Organizer resource for that entity, to use the Scheduler further.

9.3 Alert Schedule Management

9.3.1 Scheduling Alerts for a given event

An organizer may schedule different alert messages to be sent to subscribers and resources before, during, and after a prescheduled event. It is assumed here that the alert messages are borrowed from a list of messaging templates within the Scheduler that have been pre-registered and affiliated with a specific entity. The Organizer may use a host app to request the Scheduler to create a new alert schedule by choosing the alert message template, date-time of when the alert is to be sent, and type of targets to receive the message (subscriber/resource/both). If the Scheduler finds all inputs valid it will store the details against a unique Alert Schedule id in the Alert_schedile_list and returns success status and the unique id, otherwise, it will return an appropriate error code. This workflow assumes that the message templates created by the organizer of one entity should not be accessible to organizers affiliated with the host entity. Also, it is assumed that all participants of a given type (resource/subscriber/both) will receive the alert. If a specific implementation needs to define individual participants who should receive a specific alert, it will require further refining of the steps laid out here and is out of scope of the current workflow.

9.3.2 Tracking and Alerting as per schedule

The Scheduler's internal tracker keeps fetching (with a predefined interval) a list of all alerts for which the scheduled date time has arrived (within the interval). For each alert that is ready to go and based on the given target type (resource/ subscriber/ both) it will list participants of that associated event from the appointment list and send the alert message to them. The alert message will be sent using the preferred channel (sms/URL/mail) registered in the resources /subscribers list. It should be noted that the Scheduler does not wait for confirmation of the delivery of the message. In the current context, a recipient of an alert may asynchronously send back a delivery acknowledgement to the log update (see log update workflow) of the Scheduler.

9.4 Alert Message Management

9.4.1 Registering new Alert Message Template

Several predefined templates of alert messages can be stored in a Message List so that they can be reused in different alerts and events (for example appointment reminders, triggers to devices and software applications, etc. Using a host app an organizer may submit a new message and request the Scheduler to register the message. The Scheduler tries to store a new entry in its message list and returns a success or error code in response.

9.5 Resource management

9.5.1 Registering a new resource

An organizer must register into the scheduler various categories of resources {people, equipment, vehicles, facility, etc.) into a specific entity before the resource can be used in different events. An organizer is also a resource of an entity but can be registered only by the Administrator of the Building Block. An organizer can register resources of other categories only into his/her affiliated entity only. The registration process begins with the submission of resource details with the request to the Scheduler for registration of the resource. The Scheduler internally stores details of the resource into a resource_list and generates a new resource ID.

9.5.2 Finding resource availability in a given date-time range

An organizer may use a host application to seek the Scheduler for availability within a specific period (date-time range) of a chosen resource in a chosen entity. The Scheduler finds the affiliated workdays-hours of a given resource in the given entity from its Affiliation_List and calculates corresponding date-time slots that fall within the given date-time range. Then it finds from Appointments List the start and end date-time zones of all events booked for a given resource id and entity, in a given date-time range. From all this information it calculates the free time zones of the given resource, within the affiliated time zones of the given entity and given date-time range. Finally, the Scheduler returns a list of free zones of the given resource within the given date-time range and affiliated workday hours in the given entity. The host application presents this information to the Organizer. If any of the given criteria have invalid values, the scheduler notifies an appropriate error message to Host-App.

9.6 Subscriber Management

9.6.1 Registering a new Subscriber

A subscriber can be registered into the scheduler with relevant details, either by organizer or by subscriber himself. A subscriber must be registered into the scheduler before they are allowed to book appointments for various events. The user submits subscriber details through Host_App to Scheduler requesting registration. The Scheduler internally stores details of the subscriber into its subscriber_list and generates a new subscriber ID. The Scheduler returns the new subscriber id or a duplication error if it finds the subscriber profile is already existing. The Host app confirms registration or duplication error to the Organizer.

9.7 Affiliation management

9.7.1 Affiliating a resource to an entity

A registered resource must be affiliated with at least one entity. A resource may be affiliated with different entities only in non-overlapping day-time zones (e.g. doctor may give consultation in multiple hospitals). An organizer can be affiliated only by an administrator. All other categories of resources can be affiliated by an Organizer. The affiliation request may be submitted through the host-App to the scheduler along with affiliation details (resource_id, entity_id, affiliated days and time zones in that entity, etc.). The scheduler will add a new affiliation of that resource to the new entity in the Affiliation List and generate a new affiliation ID. The Scheduler flags an error if it finds a duplicate entry.

9.8 Appointment Management

9.8.1 Appointment Scheduling for resource or subscriber to a specific event

An organizer may enrol a subscriber or resource to a specific event through a host app. The host application first finds out details of a chosen event_id. Then the host application requests a new appointment booking by giving participant details, and event details as needed. The Scheduler stores appointment details against a unique appointment id in its Appointment List. The Scheduler then confirms successful enrolment to the user through the host app and publishes the unique appointment id for that participant.

9.8.2 Cancellation of appointment

An organizer may cancel an existing appointment of a resource or a subscriber for an event using the Host App. The user may submit the participant id or participant type (subscriber/resource) and the event ID to the Scheduler through the host app, requesting for cancellation of respective enrollment for the event. If the Scheduler finds the given event id and subscriber/resource id in the appointment_list it will delete the enrolment entry of the given resource in the given event, else it will return an appropriate error message. The Host-app confirms success or error condition to the user. The Scheduler also emits a notification through Messaging Building Block to inform the cancelled participant only (in different implementations one can also inform all participants). It should be noted that the deletion of the enrolment of a subscriber does not remove subscriber/resource details stored in the subscriber/resource list, but it removes only the allocation to the specific event.

9.9 Status Logging and Reporting

9.9.1 Log reporting

In this workflow, a simple case of extracting chosen type of log in a given time range is described. The Organizer requests the Scheduler through a host app to report logs of a chosen category within a chosen date range. The Scheduler fetches a list of matching logs found from its Log_List, or null if nothing is found. The Scheduler publishes the logs or null to the user through the host app. This function can be extended in different implementations to generate more complex types of reports based on information in the log.

10.1 Key Decision Log

A historical log of key decisions regarding this Building Block.

10.2 Future Considerations

A list of topics that may be relevant to future versions of this Building Block.

10.3 Use Case Examples

• Post Partum Care Program: Doctor Consultation appointment management

• Post Partum Care Program and Unconditional Social Cash Transfer Program: Payroll and Payments Event management

10.4 Digital Infrastructure for Vaccination Open Credentialing

API documentation.

A Set of microservices are defined to receive requests from other GovStack-compatible Building Blocks and applications with relevant inputs and return processed results from key digital functionalities of this Building Block. This section provides a reference for APIs that should be implemented by this Building Block. The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionality that should be provided by any implementation of this Building Block.

Scheduler must expose its microservices through RESTful API interfaces as defined by OpenAPI v3+ standards. The Scheduler must have any response data payload it returns through its API only in the form of JSON formatted datasets. A summary of the APIS exposed by this Building Block is summarized in the table below. The Scheduler Building Block can be used also as an internal sub-block of another Building Block. In such a case the same services APIs will be used to embed the Scheduler Building Block (without having to pass through the Information Mediator).

The GovStack non-functional requirements document provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here. This section also provides guidance on how candidate products are tested and how GovStack validates a product's API against the API specifications defined here.

The tests for the Scheduler Building Block can be found in this GitHub repository.

8.1 Event Management

8.2 Entity Management

8.3 Alert Schedule Management

8.4 Alert Message Management

8.5 Resource management

8.6 Subscriber management

8.7 Affiliation management

8.8 Appointment management

8.9 Status Logging and Reporting

4.10 Information Mediator Interface

This Services APIs is not yet specified, but it should be the purpose of a next iteration of the Scheduler Building Block Specification.

4.11 PubSub Interface

This Services APIs is not yet specified, but it should be the purpose of a next iteration of the Scheduler Building Block Specification.

4.12 Messaging interface

This Services APIs is not yet specified, but it should be the purpose of a next iteration of the Scheduler Building Block Specification.

4.13 Scheduler Administration

This Services APIs is not yet specified, but it should be the purpose of a next iteration of the Scheduler Building Block Specification.

API standards

• The microservice interfaces are defined as per OPENAPI Ver3.0 standards.

• For implementation purposes, it is suggested to refer TMF630_REST_API_Design_Guidelines.

The proposed resource model showing the relationship between data objects that are used by this Building Block is illustrated in the diagram below. The Scheduler Building Block stores details of Events in EventList, Resources in a ResourceList, Subscribers in SubscriberList, Alert message templates in an AlertList, alert schedules in an AlertScheduleList, entities in EntityList and Affiliations of resources in entities in the AffiliationList. Entries in this list include properties of respective items and linkages between them Apart from these, the Scheduler has several "internal" registers that are used to log information arising from transactions, from the system, from communications, etc., and metrics/indicators as needed for housekeeping, audit, and administration of the Building Block. The archival and retrieval mechanisms for data generated or received in the Scheduler Building Block are left to implementation time considerations of IT infrastructure planning.

7.1 Resource Model

7.2 Data elements

7.2.1 Group: EventList

7.2.2 Group: Appointment LIst

7.2.3 Group: EntityList

7.2.4 Group: Address

7.2.5 Group: ResourceList

7.2.6. Data Group: AffiliationList

7.2.7 Group: SubscriberList

7.2.8 Group: AlertScheduleList

7.2.9 Group: MessageList

7.2.10 Group: LogList

7.2.11 Group: FreeResources

7.2.12 VenueDetails

7.3 Notes on the Data Model

The internal storage of the Scheduler Building Block MUST hold configuration, status, and logged information of all scheduled events. It MUST also maintain a repository of details of resources and subscribers affiliated with various events

The internal data requirements of the Scheduler operations from heterogenous use cases can be reduced into a comprehensive set of unique data elements, organized into a schema of common reusable datasets, formed by a grouping of closest related data elements, avoiding unnecessary duplication.

In this model, the basic unit of Scheduling is an “Event“, each Event has a unique ID. The API structure that defines the service interface should accommodate various fields relevant across use cases that may consume the service. Some fields may be mandatory inputs while others may be optional depending on the use case.

All details of a data set in the data model may not be populated at once, it may be filled in parts as and when relevant (e.g. although a consultation session may be provisioned, consumers may be appointed later).

As new use cases are discovered, one can add fields that are not in the set in the model already. It is assumed each use case will define the respective subset of the data model along with the mandating of appropriate data fields.

Besides the basic data set needed for scheduling, there are data sets such as configurations, etc., that help to administer and audit the Scheduler Building Block itself (e.g, Security, performance, Transactional and Schedule Compliance audit reports, etc.).

Support of polymorphic data sets and data types is provided by means of a list of generic meta-attributes, to enable Polymorphism in data sets which may occur when different collections inherit common data from base entities.