Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Key Digital Functionalities describe the core (required) functions that this Building Block must be able to perform.
The Messaging Building Block is a standalone messaging gateway/client/proxy (including all possible modalities: email, SMS, etc.) but can also facilitate connections with existing messaging service providers by enabling safe communication. The communication in this Building Block can be categorized in two different directions as follows:
In scope of v1
informing End clients about their registration;
reminding and requesting End clients' confirmation for appointment booking or other events;
getting confirmation about government services and interactions.
In scope of future releases
delivering information at scale to End clients;
alerting End clients in emergency contexts.
In scope of v1
confirm Client registration for a service;
providing data to the government/service.
In scope of future releases
asking for information about government services.
Communication between different government services (government to government) is out of the scope of this Building Block but can be enabled through the Information Mediator Building Block.
Scheduling messages according to some business logic is out of the scope of this Building Block because is done by Scheduler Building Block.
Processing of incoming message content to apply some business logic.
Fully offline and no internet connection scenarios.
Real-time video and audio conferencing.
This section will highlight important requirements or describe any additional cross-cutting requirements that apply to this Building Block.
The cross-cutting requirements described in this section are an extension of the cross-cutting requirements defined in the architecture specification document. Any implementation MUST adhere to all requirements from GovStack Security Requirements.
There are two main reasons for using denormalized databases instead of traditional normalized databases. First, to significantly improve the performance of read queries. This is highly important as databases of the Messaging Building Block will be under a heavy load of requests that in many cases are expected to respond near real-time. Second, to be able to export the content of databases in the format of time-series databases (see below for its reasons). To achieve this, using "UPDATE" and "DELETE" queries in SQL commands SHOULD be disabled. If not, they MUST be avoided by developers and caught by automated tests if still used.
By having this capability, it is possible to delete the content of processed data from production-level server databases right after they have been securely archived. This is important to reduce the impact of potential data breaches by security incidents of potentially N number of application servers hosted by different parties.
If done so, using archived datasets, either fully or partially, allows to recover and/or re-engineer lost databases (or just datasets of interest) automatically and in a matter of seconds if such pipelines have been predefined. Also, by converting the content of relational databases into a format of time-series databases, these purely text-based datasets are easily usable by different kinds of databases, analytics tools, etc., not just by the relational database used at first.
Technical components (with the exception of relational databases) must be stateless in the sense of the Service statelessness principle.
At least on the level of active-passive nodes based on the principle of "eventually consistent". Pending: initial state for all messages waiting to be queued.
Queued: messages that are in the queue to be sent.
Sent: messages with proper confirmation that was sent to the provider.
Delivered: messages with proper confirmation that was delivered to the end-user.
Errored: messages with an error during delivery.
Failed: messages that are errored and we gave up sending.
If Messaging Building Block protocols are followed, the technical stack used to provide messaging as a service is vendor-neutral, meaning that anyone is free to use technical solutions of their own choice.
Only allowed participants are allowed to provide and use the services of Messaging Building Block.
Messaging Building Block is a dumb messaging proxy that gets all of its relevant input from its clients. This also includes the names and contact information of all relevant participants. Such sensitive information may not exist in its raw and/or re-engineerable form nor in databases or logs.
Depending on the specific use case, this may mean end-to-end encryption or SNI routing.
Every instance of a service must generate audit logs containing information about all of its actions regarding timestamps, related parties, identifiers to operations performed, and HTTP response codes for any given action. Audit logs may not contain the actual content of the message. Audit logs must be in a time series database format. Audit logs must be accessible by a given endpoint by the central service provider only. Audit logs should be periodically removed from their original source after a defined period of time.
All APIs are exposed via secure socket connections (HTTPS).
Manage access quotas and throttling.
Logging of all API calls made.
Allow API providers to limit the rate of consumption for all API users.
Transform backend error messages into standardized messages so that all error messages look similar; this also eliminates exposing the backend code structure.
Contact address (email, phone number, etc.), the message type, the content of the message, and the initiating source’s unique transaction ID.
Asynchronous messaging processing. OpenAPI specifications for calling this function; resource models and data structures, internal and external interfaces.
Stateless architecture.
Message broker tool to enable performant queueing mechanisms such as RabbitMQApache/Kafka, or GRPC for data transfer speed purposes.
Databases with unstructured data should be treated with Elasticsearch/Logstash.
End users should be registered as Message queue clients/subscribers in the Messaging Building Block. Subscription is required to receive a message.
In order to prevent single points of failure, messages must be replicated on at least 2 different service providers. In case of message replication, all unprocessed replicated messages must be kept track of and relevantly updated in order to prevent re-processing them.
Admin of the room must be able to choose the policy profile with the configuration of the message provider, e.g. retrial frequency.
Unsent and unsuccessfully delivered messages must remain in a queue until being successfully delivered or otherwise permanently processed.
Pending (initial state for all messages waiting to be queued); Queued (messages that are in the queue to be sent); Sent (messages with proper confirmation that was sent to the provider); Delivered (messages with proper confirmation that was delivered to the end-user); Errored (messages with an error during delivery); Failed (messages that are errored and we gave up sending).
Messages not delivered in a period of 24 hours (any errored or queued messages more than 24 hours old must be labeled as failed and go out of the queue); Messages retrial (Errored messages must be retried for 24 hours).
Client applications must send authorization tokens in the authorization header of the request to authenticate users and the API Management Gateway will verify whether the token is valid.
Perform input validation checks to prevent oversized message attacks, SQL injection attacks as well as JSON and XML threats.
The following standards are applicable to data structures in the Messaging Building Block:
All services are provided as REST API requests
Only Transport Layer Security (TLS) Server Name Indication (SNI) extension-compatible requests are allowed
REST APIs calls and responses use JSON as the only allowed data format.
Using ISO 8601 on dates and times
UTF-8 character encoding on text input
Developed by Rainer Türner (Information System Authority of Estonia), Magnus Hult (Element.io), John Cordeiro and Martin Karner (Estonian ICT Cluster), Bramhanand Jha (India's National e-Governance Division)
This section lists the technical requirements of this Building Block.
In addition to the functional requirements described in this section, GovStack's cross-cutting requirements defined in the architecture specification document and GovStack Security Requirements, apply.
The queuing process varies according to the policy and message type attached to the messaging, if an emergency messaging type applies to it, the messaging gets prioritized, otherwise, the FIFO algorithm (First In, First Out) applies to other message types. It saves all the requests for further processing, furthermore, works in the form of an "AS IS" process analysis without changing anything on the request. The message queueing mechanism will:
save a hash (MHASH) of the original request and a Unique Message ID (UMID);
respond with "Message received" to the sender with generated UMID.
Messaging requests go through a final check to be clean of defects and inconsistencies, to check with external systems as necessary:
check for message duplicates by making an actual request to a database to see if entries with MHASH and UMID exist;
low-level validation of data types and data completeness;
check for inconsistencies;
standard error messages and codes are used as a response to inconsistent requests.
In relation to batch logic, messages are scheduled against the availability of systems, throughput limitations, and rules set by programs.
Regular and repeat messages are scheduled.
Batches may be given prioritization in the queue according to the message settings.
The essential control logic may be included here specific to the individual batch sending and resending.
Additional workflow checks as required, including resending failed transactions.
Handles the initiation of input data processing from all the API messaging calls and makes the API access control verification from other Building Blocks to the Messaging Building Block and vice versa as well as within the Messaging Building Block, it will:
use Identity and access management for authentication;
perform input validation checks to prevent oversized message attacks, SQL injection attacks as well as JSON and XML threats;
require authentication for all API users;
manage access quotas and throttling;
logging of all API calls made;
allow API providers to limit the rate of consumption for all API users;
transform backend error messages into standardized messages so that all error messages look similar (this also eliminates exposing the backend code structure).
This request could come from two sources: external or internal. An external source could be another GovStack Building Block (e.g. the Registration Building Block). Either source must be appropriately authenticated and authorized to initiate the request. The request must contain at a minimum: the contact address (email, phone number, etc.), the message type, the content of the message, and the initiating source’s unique transaction ID.
Find unprocessed requests from a database.
Prepare each request for actual processing, requests may come as single or batch messages and every message needs to be treated as a separate entry.
It prepares unprocessed requests for actual processing.
Each component of the messaging building block should be capable of producing transaction logs. This is important to ensure that the system can be adequately monitored and troubleshooting can be performed efficiently and effectively.
The components should also generate transaction logs for events that capture at least the following information:
transaction date and time;
transaction source;
transaction destination;
supplementary data;
transaction status (success, failed, in progress).
The event logs and the transaction logs should NOT capture any sensitive data such as contact data, or channel authorization credentials.
Fetch and securely archive logs from working nodes is also expected.
This section lists the technical capabilities of the Messaging Building Block. The following components are needed to achieve the technical functionalities of the messaging Building Block.
The Messaging Building Block is part of the GovStack implementation and is prompted to open up a two-way communication channel to deliver and capture messages/data between the GovStack systems and the end users, physical and legal persons.
As a rule, the Messaging Building Block does not own any information but is carrying the minimum amount of (meta) data needed to transfer/publish a message. Messaging Building Block allows other Building Blocks and applications to reach out to customers/citizens in order for them to be able to make a decision or access a service. This Building Block can also be used for broadcasting a disaster message.
Messaging policies are configurable modalities and channels that can be accessed/utilized through the Messaging Building Block in order to reach out to the users or groups. This Building Block is using existing applications/channels, such as e-mail, SMS, and messaging platforms for enabling users to subscribe to an application/channel provided by Messaging Building Block itself for text-based content.
Having published its messaging policies and services at the Information Mediator Building Block, the other Building Blocks and applications can discover and use the services of the Messaging Building Block.
Messaging Building Block allows for asynchronous communication, using either point-to-point communication or a Pub/Sub model (using Information Mediator Building Block) where the user is subscribed to a message room/group and will be receiving all messages intended for the “mother of newborn child” group.
Security: Before allowing any messages to be published, the Messaging Building Block fetches a corresponding ID and a role or a session token available for the user for authentication and access purposes. Incorporates privacy into its design when the purpose of the authentication is not revealed if a service provider sends an authentication request.
This section provides a detailed view of how this Building Block will interact with other Building Blocks to support common use cases.
A workflow provides a detailed view of how this Building Block will interact with other Building Blocks to support common use cases.
This section lists workflows that this Building Block must support. Other workflows may be implemented in addition to those listed.
The main prerequisite for Person-to-Building Block communication is that there is an existing Sender/Source Building Block with the following properties:
the relevant credentials and details about the Person/Citizen to be addressed with;
the content of the message and a reference to a communication channel (contact details) to be used;
additionally, the service discovery service at the Information Mediator Building Block needs to be active. Information Mediator Building Block publishes the list of available services of the Messaging Building Block to the source GovStack Building Block, i.e. Workflow.
A reference token should be carried throughout the communication session in order to save a point of reference for reverse communication back from the Person to the Building Block. In other words, the main prerequisite for Person-to-Building Block communication is the availability of a communication channel and a reference token.
This generic workflow is used to transfer messages between GovStack Building Block and the end user, Person. Data is submitted from a GovStack Building Block front-end application. This workflow shows a connection to GovStack Building Block (such as a government Health System Application) to convey a message that is associated with a real person.
This workflow requires interaction with the Information Mediator Building Block and a source GovStack Building Block, for example, a Health Care Service Building Block or registry Building Block.
The sequence diagram shows the flow of data between Building Blocks for this workflow.
The following diagram illustrates the internal processes of the Messaging BB to send messages received as external requests and sent via external service providers.
The following diagram illustrates the internal processes of the Messaging BB when providing status report for messages that have been passed on by external partners for further processing by the Messaging BB.
The version history table describes the major changes to the specifications between published versions.
| Version | Authors | Comment |
|---|---|---|
This section provides a reference for APIs that should be implemented by 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.
The 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 Messaging Building Block can be found in
This API is designed to send out emails one by one.
Although an email can be sent to multiple recipients by using email, emailCC and emailBCC appropriately, this is still considered as sending a single email.
As a Doctor working in a hospital, I want to notify my patient about a confirmed registration so that the patient would know when to come for a visit.
This API is designed to send out identical emails to multiple (batch) recipients at once.
As a Hospital I want to notify a specified group of my clients about the possibility to register to vacant time slots within a limited period of time so that the clients potentially needing it the most would have a guaranteed chance to get an appointment
This API is designed to accept responses to emails that have been previously sent out by using the Messaging Building Block. The protocol itself is lightweight and expects custom services from anyone using it. The Messaging Building Block is responsible for delivering the message and does not know (or want to know) anything about the content of it, how it will be used, etc.
As a Hospital, I want to get and send responses from and to clients so that I could continue and keep track of email conversations taking place via GovStack
This API is designed to provide information about the status of emails sent to the Messaging Building Block.
As a Doctor working in a hospital I want to know which emails I have sent haven't reached their destination so that I could contact such patients by using different means
Possible status of emails that can be queried are as follows:
scheduled
processing
deferred
bounced
not sent
delivered
There is no keeping track of emails which have been sent successfully, as this would end up creating and maintaining a massive database of emails, their senders and recipients, etc., which would be wrong for so many reasons.
0.9
Martin Karner, Rainer Türner, John Cordeiro
Technical Reviewers: Tony Shannon, Saša Kovačević, Riham Moawad, Riham Fahmi, Aare Laponin, Manish Srivastava, Palab Saha, Surendra Singh Sucharia, Arvind Gupta, Gayatri. P., Shivank Singh Chauhan, Gavin Lyons
1.0
Martin Karner, Rainer Türner, John Cordeiro, Dr. P. S. Ramkumar, Magnus Hult, Bramhanand Jha
Reviewers: Wesley Brown, Steve Conrad, Valeria Tafoya
Final edits to align content to specification template for GovStack 1.0 release
Messaging Building Block accepts a message from GovStack publisher | Publisher Building Block or service conforming to the Messaging BB schema | Reject messages that do not comply with expected schema |
Retrieve Person and Contact Channel Data from the incoming Message | Map retreived data with appropriate recipient | Technical mapping is an internal service of the Messaging BB |
Publish Message through Communication Channel | Communicate Message Data and User ID to Communication Channel | Reject messages that do not comply with expected schema |
Publish Status for the original sender | User and Message IDs with Delivery Status containing date and time | The Message's unique ID is preserved to keep up its status updated |
Message sent through the communication channel / service provider | Text message and User ID | Reject messages that do not comply with expected schema |
Retrieve Person and Contact Channel Data from the incoming Message | Map retreived data with appropriate recipient | Technical mapping is an internal service of the Messaging BB |
Confirm message received | Message Delivery Data Structure following Communication Channel standards with Status | The Message unique ID is collected to keep up other statuses updated |
Publish Status for the original sender | User and Message IDs with Delivery Status containing date and time | The Message's unique ID is preserved to keep up its status updated |
A historical log of key decisions regarding this Building Block.
A list of topics that may be relevant to future versions of this Building Block.
This section shows possible sample implementations, such as Issuing Birth Certificate; Appointment Booking With a Health Care Worker
This is a high-level overview of how the Messaging BB acts internally, but also to cover the expectation for a third party to deliver requests (to and from).
This is a Use Case Table to cover providing a birth certificate to a child.
This is a Use Case Table to cover the process of confirming an appointment booking when using health services.
This is a Use Case Table to cover the process of sending alert messages.
This is a sample user journey to cover post-partum mother and child care.
In case of applying additional business logic-related functionality, third-party applications must be used.
Terminology used within this specification.
| Term | Description |
|---|
Name
Messaging – Birth Certificate to Children
Description
The use case explains the implementation of the messaging for the birth certificate to minor children.
Main Benefits
1. Provides permanent and official record of a child’s existence.
2. Provides right to an official identity, a recognized name, and a nationality.
3. Provides essential element of national planning for children since it provides a demographic base.
Trigger
(the event that triggers the use case)
The birth registry at hospitals/municipalities-driven.
Citizen-driven and digital application.
Citizen-driven and paper-based application.
Preconditions
(list of conditions that MUST be met in order for the use case to be successful)
The application admin/user is logged into the system and has sufficient privileges to use the system.
A Messaging Policy exists and is based on existing electronic data handling laws and regulations.
Registry of birth exists for digital processing.
Workflow for processing of birth verification and certificate attestation exists.
Assumption: Parent/Guardian is in possession of a digital communication device and an application, capable of receiving and sending messages.
Assumption: The messaging is happening in the language of comprehension for the user.
Assumption: Government/GovStack implementation has Building Blocks namely Identity and Authentication, Registration and Workflow in operation.
Assumption: Government/GovStack implementation has web and mobile-supported technologies such as Push/Pull SMS, IVRS, Mobile-enabled Web Interface, Mobile App, etc.
Data inputs
Registration Details
Application Form Details
Required Documents
3.1 A copy of the birth proof
3.2 A copy of the passport of both the parents
3.3 A copy of the certificate of citizenship if acquired by registration/naturalization
3.4 A copy of the marriage certificate of the parents
3.5 Declaration letter that the child does not hold the passport of any other country
3.6 Scan the documents in PDF format
3.7 Each document can have multiple pages
3.8 The size of each document should not exceed 1 Mb (illustrative)
4. Image
4.1 Passport size photo of the applicant
4.2 Image Dimension of Photograph should be 100(Width) * 120(Hight) Pixel only (illustrative)
4.3 Size of the scanned image is not more than 20kb (illustrative)
4.4 Uploading image should be in jpg format only (illustrative)
4.5 Use the Picture manager for resizing the image
Actors
(a person, a company or organisation, a computer program, or a computer system - hardware, software, or both)
The application admin/user who configures the messaging policy (A person, IT admin).
Applicant (A person, Citizen).
Maker/Checker/Approver (A person, Government/Authorized official).
The birth certificate provider application (A computer system).
Auditors (A person, or an independent authority).
Registration Block –Birth Registry, Marriage Registry, etc. (A computer system).
Identity and Authentication Block for checking the Identity of the applicant, parent (A computer system).
Workflow Block for rule-based processing (A computer system).
Email for communication (A system).
Mobile – Push/Pull/IVRS/USSD/App (A system).
Web Application (A computer system).
Normal Course (what happens if the event is triggered and the preconditions have been met)
Acknowledgment message for receipt of application.
Birth certificate approval message.
The Messaging Building Block application user can invoke the identity and authentication Building Block, registry Building Block and workflow Building Block for e-auth (electronic authentication), birth entry, and rule-based processing respectively.
Alternative Course
(links to other use cases in case there are different ways how to solve the same use case)
-
Data output
The messaging Building Block can send a message to applicants through email or SMS. The types of message(s) include:
Acknowledgement of application receipt;
Application progress status;
Duly signed Birth certificate.
Post-Conditions (the success criteria)
The conformance check including metadata and data standard validation of the message is done.
The exceptions are communicated to the system (through error code and message) and to the user through message.
The accepted message is passed on to the Workflow Building Block, which in return, may make use of Registration, Identity, Security, and Consent Building Blocks.
The system is configured and ready for routing messages during a workflow.
User feedback is taken on messaging and factored in.
Exceptions
(error situations)
In case of any configuration change in messaging or any error in the processing of messaging:
1. An error message is displayed and communicated back to the system that made the request.
2. An error message is communicated in easy-to-understand language to the impacted user.
Related Building Blocks
(related to that particular use case)
Identity Building Block - for acquiring authentication token.
Workflow Building Block – for workflow management.
Registries Building Block – for storing the data.
Information Mediator Building Block - providing interfaces and publishing the Building Block services, routing policy, etc.
Security Building Block – for supervision and safety.
Consent Building Block - for using personal data.
Payment Building Block – for making delayed payment.
Messaging
Examples
Sample Message – Email for user registration
User XXXX has been registered successfully.
User ID: XXXX
Please click here to reset the password or copy the link to your browser
<weblink>
Sample Message – SMS for birth certificate approval
Birth Certificate Approved, please make a note of Acknowledgement Number for Future Reference '1202117XXXXX'—Govt. Organization Name.
Best Practices
Birth certificate in Digital Locker
Digital Locker to provide lifelong access to authentic digital documents to citizen’s digital document wallet. The issued documents in Digital Locker system are deemed to be at par with original physical documents as per rule.
ID
Description
Name
Messaging – Appointment booking confirmation for health services.
Description
The use case explains the implementation of the Messaging Building Block for the confirmation and acknowledgment of appointment booking of health services.
Main Benefits
1. Provides a clear and accessible path for citizens to confirm appointment booking through different digital messaging channels (SMS, email, WhatsApp, Voice message, etc.);
2. Provides transparency for the citizens that need to move to a health facility to consume services;
3. Provides efficient usage of the health services by occupying booking slots accordingly to the demand.
Trigger
(the event that triggers the use case)
Citizen registers an appointment booking through digital messaging channels.
Citizen-driven and digital messaging channels.
Preconditions
(list of conditions that MUST be met in order for the use case to be successful)
The application admin/user is logged into the system and has sufficient privileges to use the system,
A Messaging Policy exists, based on existing electronic data handling laws and regulations.
Citizens are previously registered.
Workflow for registering an appointment booking exists.
Assumption: Parent/Guardian is in possession of a digital communication device and an application, capable of receiving and sending messages.
Assumption: The messaging is happening in the language of comprehension for citizens.
Assumption: Government/GovStack implementation has Building Blocks namely Identity and Authentication, Registration and Workflow in operation.
Assumption: Government/GovStack implementation has web and mobile-supported technologies such as Push/Pull SMS, IVRS, Mobile-enabled Web Interface, Mobile App, etc.
Data inputs
Citizen Registration Details;
Message minimal data such as Unique Material Identifier (UMID), content, policy, and priority.
Actors
(a person, a company or organisation, a computer program, or a computer system - hardware, software, or both)
The application admin/user that configures the messaging policy. (A person, IT admin).
Applicant (A person, Citizen).
Scheduler Block for setting up events that triggers a message (A computer system).
Registration Block – Birth Registry, Marriage Registry, etc. (A computer system).
Identity and Authentication Block for checking Identity of an applicant, parent (A computer system).
Workflow Block for rule-based processing (A computer system).
Email for communication (A system).
Mobile – Push/Pull/IVRS/USSD/App (A system).
Web Application (A computer system).
Normal Course (what happens if the event is triggered and the preconditions have been met)
Acknowledgment message about an appointment booking with the information given by the input;
Citizen answers the message about the appointment booking;
Messaging Building Block application delivers the citizen input to the Workflow Building Block that handles it properly.
Alternative Course
(links to other use cases in case there are different ways how to solve the same use case)
-
Data output
The Messaging Building Block can send and receive messages from citizens through different communication channels, and keep the status of the delivery along with metadata about it.
Post-Conditions (the success criteria)
The conformance check including metadata, data standard validation of message is done.
The exceptions are communicated to the system (through error code and message) and to the user through message.
The accepted message passed on to the Workflow Building Block, which in return, may make use of Registration, Identity, Security, and Consent Building Blocks.
The system is configured and ready for routing messages during a workflow.
User feedback is taken on messaging and factored in.
Exceptions
(error situations)
In case of any configuration change in messaging or any error in the processing of messaging:
1. An error message is displayed and communicated back to the system that made the request.
2. An error message is communicated in easy-to-understand language to impacted users.
Related Building Blocks
(related to that particular use case)
Identity Building Block - for acquiring authentication token.
Scheduler Building Block - for scheduling events.
Workflow Building Block – for workflow management.
Registries Building Block – for storing the data.
Information Mediator Building Block - providing interfaces and publishing the Building Block services, routing policy, etc.
Security Building Block – for supervision and safety.
Consent Building Block - for using personal data.
Messaging
Examples
Sample Message – Appointment Booking Confirmation XXXX, can you confirm an appointment booking for the service ZZZZ scheduled for YYYY? (Answer with YES to confirm or NO otherwise).
Sample Message – Appointment Reminder XXXX, you have an appointment booking confirmed for YYYY, make sure to be prepared for the event as follows: ZZZZ.
Best Practices
The content of the messages may have as much information as possible to the citizen but respecting the restrictions of the communication channel used such as the content length of messages;
The frequency of the confirmation messages should take into consideration the regulations of each country to avoid blacklisting a communication channel considered spam.
Name
Messaging – Alert
Description
The use case explains the implementation of the messaging for alerts especially alerts linked to cyclone disaster management.
Main Benefits
1. Prevent the loss of lives (human and animal) and livelihood.
2. Coordinated efforts for previous, during, and post-disaster events.
Trigger
(the event that triggers the use case)
Early warning on cyclone.
Early warning on a flood.
It can be customized for warning on landslides and/or earthquakes.
It can be tailored and customized for alerts on banking and covid/healthcare.
Preconditions
(list of conditions that MUST be met in order for the use case to be successful)
The application admin/user is logged into the system (mobile, computer, TV, and/or Radio) and has sufficient privileges to use the system,
A Messaging Policy exists and is based on existing electronic data handling laws and regulations.
Common Alert Protocol is in place for synergies among Government Institutions.
Early Warning System is in place.
Observation is available from space (satellites), upper air (Balloon, Radar, Aircraft), and surface (Automatic Weather Station, Automatic Raingauge Station, surface synoptic observations, etc.).
Language translation system and moderator are in place.
Workflow for processing disaster-related data exist.
Assumption: Government Agencies and Residents are in possession of a digital communication device and an application, capable of receiving and sending messages.
Assumption: The messaging is happening in the language of comprehension for the user.
Assumption: Government/GovStack implementation has Building Blocks namely Identity and Authentication, Registration and Workflow in operation.
Assumption: Government/GovStack implementation has web and mobile-supported technologies such as Push/Pull SMS, IVRS, Mobile-enabled Web Interface, Mobile App, etc.
Data inputs
Warning Message for disaster.
What-to-do Message regarding pre-, during, and post-disaster.
Language localization of message.
Friendliness of messages towards disabled people.
Mobile and Email Database.
Geographical and location-based targets for alert messages on a disaster.
Directory of Telecom Service Providers, Social Media Influencers, Government Institutions, Language Translators.
Actors
(a person, a company or organisation, a computer program, or a computer system - hardware, software, or both)
The application admin/user who configures the messaging policy (A person, IT admin).
Message consumer (A person, Resident).
Government Agencies (Institutions).
Language Translation Moderator (A Person, Expert).
Early Warning System.
Email for communication (A system).
Mobile – Push/Pull/IVRS/USSD/App (A system).
Web Application (A computer system).
TV, Radio, social media (A system).
Normal Course (what happens if the event is triggered, and the preconditions have been met)
Message to Government Institutions through Email, Telephone, Police Wireless, or Website.
Message to the Public through Email, SMS, Radio, TV, social media, Newspaper (Electronic & Print Media), or Website.
Message to marine through NAVTEX (NAVigational TEleX), Telephone, Telefax, or Broadcast.
Alternative Course
(links to other use cases in case there are different ways how to solve the same use case)
-
Data output
The Messaging Building Block can send alert messages to concerned institutions and persons. The types of message(s) include:
Voice Alert Message
· With the help of Telecom Service Providers using Outbound Dialler (OBD) infrastructure in local languages.
· With the help of Radio.
Text Alert Message
· With the help of Telecom Service Providers using SMS.
· With the help of an email database.
· With the help of social media/website.
Image and video alert message
· TV.
· Electronic and Print Media – Newspaper, Bulletins.
Post-Conditions (the success criteria)
The conformance check including metadata, data standard validation of message, and adherence to common alert protocol is done.
The exceptions are communicated to the system (through error code and message) and to the user through message.
The accepted message is passed on to the Workflow Building Block, which in turn, may make use of Registration, Identity, and Security. Security Building Block to take care of PI data in a personalized alert message.
The system is configured and ready for routing messages during a workflow.
User feedback is taken on messaging and factored in.
Exceptions
(error situations)
In case of any configuration change in messaging or any error in the processing of messaging
1. An error message is displayed and communicated back to the system that made the request.
2. An error message is communicated in easy-to-understand language to the impacted user.
Related Building Blocks
(related to that particular use case)
Identity Building Block - for acquiring authentication token.
Workflow Building Block – for workflow management.
Registries Building Block – for storing the data.
Information Mediator Building Block - providing interfaces and publishing the Building Block services, routing policy, etc.
Security Building Block – for supervision and safety.
Consent Building Block - for using personal data.
Payment Building Block – for making delayed payments.
Messaging
Examples
Sample Message – SMS for cyclone alert
Warning! Cyclone XXXXX will make landfall on Xth Day, 20XX. The wind speed may go up to 180kmph. Please stay at home, be safe. Or please go to the nearest cyclone shelter.
Best Practices
· Mass Messaging System.
· Universal Communication Interface.
· Reliable SMS Code.
· Common Alert Protocol.
· Warning through SMS (Pull SMS Push SMS).
· Mobile App Solution: - Notification through a unified mobile app – UMANG (Unified Mobile App for New-Age Governance).
· Voice/text bot.
· Warning Through social media: WhatsApp, Facebook, Twitter, and Mobile Apps.
· Electronic and Print Media for Publicity and Broadcast of Warning: National/Regional Bulletin, Poster and Films, Radio and TV Talks, and Newspapers.
· Mode of Dissemination: FAX, GTS, Email, SMS, FTP, Internet, Website, Telephone, Tale-fax, VHF/HFRT, Radio/TV network, IVRS (Interactive Voice Response System) Toll-Free Number, NAVTEX.
User Journey
Use Case
Capability
Functional Requirements
Technical Requirements
Post-partum mother and child care
Mother Registration
Inform the mother about registration through different modalities (SMS[1] , email, WhatsApp, Voice message etc.).
See the functional requirements and technical requirements.
Workflow, preconditions such as phone number/contact.
The user needs to register/connect its contact data to the Messaging Building Block (mailID, phone no etc)[2] [3] [4] or another Building Block.
For example, a) direct MSG Type (Emergency) has concrete API endpoints, blasting all channels/endpoints. Business logic and policy in separate Building Blocks can add MSG type, address: who-to-send-to, MSG channel etc.
In reverse communication, a unique identifier is created per user upon registering at the Messaging Building Block.[5] [6] Allowing push and pull models. To be able to understand and apply a routing policy in the particular Application,enabling the Messaging Building Block for routing the Message [7] [8] through specific channels [9] [10] and graceful degradation.
OpenAPI specifications for calling this function; resource models and data structures; [11] internal and external interfaces.
Stateless architecture.[12] Microservices require Rabbit MQ; Apache/Kafka or GRPC[13] [14] for data transfer speed purposes. Databases with unstructured data should be treated with Elasticsearch/Logstash. [15] [16]
Similarly to the client-to-client pubsub model also the end users can be registered as Message queue clients/subscribers in the Messaging Building Block. Subscription is required to receive a message.[17] [18] The message is put in the queue and communicated to the other Building Blocks[19] [20].
Mother confirmation of a child registration
Mother receives a confirmation registration message with a token that identifies that event for future interactions.
Appointment booking
Asking the mother for the booking confirmation of a doctor or vaccination appointment through different communicable channels (SMS, email, WhatsApp, Voice message, etc.).
Appointment reminder
Reminding the mother about the booking.
ID
UC-C-PIC-001
Name
Messaging - Postpartum and infant care (Configuration).
Description
The use case implements configuration of a Messaging Gateway in infant care use case scenarios. This results in a saved configuration to be issued to all mothers requiring infant care.
Trigger (the event that triggers the use case)
The (healthcare) application admin/user wishes to configure the policies and assign user contact details associated with the Messaging service.
Any change in the pre-condition that requires a re-configuration.
Preconditions (list of conditions that MUST be met in order for the use case to be successful)
The application admin/user is logged into the system and has sufficient privileges to use the system.
A Messaging Policy exists, based on existing electronic data handling laws and regulations.
Assumption: The mother is in possession of a digital communication device and an application, capable of receiving and sending messages.
Assumption: Government/GovStack implementation has an agreement and API GW with the service providers for transmitting text and voice messages, setting up conference calls.
Data inputs
Existing data policies relevant to the messaging scenario.
Contact information of end users accessed in another system or[21] [22] transmitted along the Messaging Request by another GovStack Building Block./Application.
Any legal information, standards.
Actors (a person, a company or organisation, a computer program, or a computer system - hardware, software, or both)
The application admin/user who configures the messaging policy (a person, IT admin)
The health-care provider application (a computer system).
Data Protection Officer, Auditors (A person, or an independent authority).
GovStack application (HealthCareProvider Application, Workflow, Information Mediator) triggers a Message to be sent with an appropriate policy metadata.
Information Mediator publishes the services of the Messaging Building Block for the other Building Block to use (with available policies). When another Building Block discovers Messaging, it receives X number of policies. Metadata says which policy to pick and where to route it to.
Note from the Information Mediator: in order to make your Building Block service available on GovStack, you have to register those services (Open API specs and have a specific business agreement signed between the parties/applications/services).
Normal Course (what happens if the event is triggered and the preconditions have been met)
The Messaging Building Block application user is able to invoke the configuration workflow.
The healthcare application user uses the existing Messaging Building Block policy and relevant metadata about the user for registering for postpartum and infant care. This policy could be signed off by the organisation's Data Protection Officer, for example:
The data required are:
Usage purpose.
Data policies and rules.
Define what data is being collected.
The configuration is saved.
Once the DPO approves, the configuration is published toward the end-use case, i.e. Healthcare Professional registration system.
Alternative Course (links to other use cases in case there are different ways how to solve the same use case)
Data configuration error scenarios.
Data Protection Officer disapproves and the configuration is re-submitted for review and approval.
Data output
The Messaging Building Block policy configuration data.
Post-Conditions (the success criteria)
The Messaging policy is saved in the system and is published in the Information Mediator, making it available for use in the registration process.
The system is now configured and ready for routing messages during a workflow.
Exceptions (error situations)
In case the policy has not been configured, an error message is displayed and communicated back to the system that made the request.
Related Building Blocks (related to that particular use case)
Identity Building Block (Required for acquiring authentication token).
Workflow Building Block - workflow management.
Registries Building Block - stores the data agreement data.
Information Mediator Building Block - providing interfaces and publishing the Building Block services, routing policy, etc.
Security Building Block - supervision.
Consent Building Block - for using personal data.
Interaction with Scheduling Building Block
Reminder messages, time-based triggers.
Appointment booking confirmation, where there are two levels of confirmation:
Immediate confirmation: I have received the message.
I have deposited a message, and have given the message a token number. And on the basis of this, I can pick up the message or a reply later.
Reminder message is already there and an event will trigger it.
Event notification, trigger: for example: please join the call.
Message | The Message is the main entity of communication in this Building Block, it holds all the necessary information to deliver the information to the Publisher or to the Subscriber/client, leaving just a track of delivery Logs with no personal data included. Messages follow a predefined protocol and policy for the chosen or predefined Communication channel. As a rule, the delivery mode of the Message is asynchronous. |
Publisher | This is the originator of the Message, holding information about the content of the Message and the (meta) data regarding the Subscriber who will receive the Message. In other words, Messaging Building Block proxies/relays the Message received by a Communication channel to the proper Subscriber/client/person. |
Subscriber | In the Publish and Subscribe use case, where the Publisher is relaying the Message into the hands of Messaging Building Block, that will in turn route it to the desired Communication channel, the Subscriber is the one who is listening to the relevant Message Room to receive the Message from the Publisher. The Subscriber has given consent to the Publisher to access or retrieve and store its data for the purpose of carrying out the Messaging event. |
Messaging event | Messaging event is the (single) act of asynchronous information transfer between the Publisher and the Subscriber, consisting of the following steps: 1) secure identification and access management of the Publisher and the Subscriber; 2) access to and/or retrieval of relevant Subscriber data and consent for using the data from the Subscriber; 3) selection of relevant data transfer policy and protocol for the Messaging event; 4) Management and processing of Logs and relevant metadata during and after the Messaging event. |
Messaging protocol | It is the protocol enabling the Messaging Building Block to communicate and transfer data between appropriate endpoints. N.B. In its initial versions, GovStack Messaging Building Block is using protocol as a reference point for creating the GovStack Messaging Building Block protocol. |
Communication channel | It is the endpoint of the Message delivery, the means used by the Publisher or the Subscriber to communicate. It can be a social media tool, e-mail or SMS service, or a distributed network. |
Log | It holds track of Message delivery with the encrypted content to help with the maintenance and troubleshooting of the messaging services. |
Routing Policy | Routing policy is the essential, configurable service of the Messaging Building Block, published in the Information Mediator Building Block, and is enabling the Publishers and the Subscribers to pre-define and use the appropriate Routing Policy for the particular Messaging event. In future iterations of this specification, the Routing Policy can be applied to the Messaging Rooms. |
Service provider | Service providers provide service(s) to End clients. For example, medical doctors, hospitals, government agencies, etc. In some cases, a Service provider can also be in a role of an End client, being served by another Service provider. |
End client | In most cases, End clients are citizens of any given country contacting and/or requesting or being served by a Service provider. For example, a mother/caretaker of a newborn child being serviced by a Health Care Service provider. |
This section provides context for this Building Block.
The Messaging Building Block provides a standardized, secure communication channel between GovStack service providers and end customers (in most cases citizens). By using GovStack Messaging Building Block, service providers rely on the building block's central functionalities, logging, back upping, security features, etc. without the need to reproduce and maintain them by themselves.
For greenfield developments, it helps developers build communication components on top of different GovStack services, to make use of federated architecture when passing messages, including machine- and human-triggered (both synchronous and asynchronous) ones.
Messaging Building Block is a standalone messaging gateway/client/proxy (including all possible modalities: email, SMS, etc.), but can also facilitate connections with existing messaging service providers, hence making the adoption process less disruptive for end users.
This Building Block can be used for messaging events in many different applications and use cases, such as:
Example A, encrypted: after being enrolled into a Health Care Program for the mothers of a newborn child, a woman/caretaker receives a message from the Health Care Service Provider about a doctor's appointment. The message is routed to an existing communication channel/application, in use and provided by the mother.
Example B, unencrypted: a reminder/notification message from the service provider to the mother about the same appointment. If a doctor decides to hold the consultation remotely, a link is sent to the mother and a video consultation is started (the conference is started and users join the room). The event is triggered by the Scheduler Building Block component and a new message is processed to the client.
Example C: a user-initiated message regarding a doctor consultation, targeted to a Health Care Provider's phone number or a chatbot URL (universal or targeted messaging back to the system).
Messaging Building Block is enabling signing up for and receiving services, such as:
mother and childcare;
social care;
receiving entitlements from the government;
opening bank accounts;
communicating disaster messages or reminders about the voters' rights during elections;
etc.
The use cases are detailed in the section of the following document: .
This service may reside on both Messaging BB's and client's side. If used, a matching OpenAPI spec must be provided by the service provider, describing the expected input when making request to the endpoint.
Email containing information about the recipient
"Meta-info""Q2xpZW50LXNwZWNpZmljIGNvbnRlbnQsIG1vc3QgbGlrZWx5IEpTT04="Request successfully accepted
Get status of sent emails. Use both "apiKey" and "requestUid" in your request.
Select status values to fetch data for
Request successfully accepted
01004025709032When sending batch emails, recipients information is passed in base64 format. Sender information and email content must be the same for all recipients.
Email containing information about the recipient
"https://example.com/callback/emails/requestUid""Example Medical Insitution""GOV1234567890""Example Medical Insitution""GOV1234567890""sender@example.com""reply-to@example.com""Example Doctor""W3sKCSJyZWNpcGllbnRJbmZvIjogewoJCSJlbWFpbCI6ICJjdXN0b21lckBleGFtcGxlLmNvbSIsCgkJImVtYWlsQ0MiOiAiY3VzdG9tZXItY2NAZXhhbXBsZS5jb20iLAoJCSJlbWFpbEJDQyI6ICJjdXN0b21lci1iY2NAZXhhbXBsZS5jb20iLAoJCSJuYW1lIjogIkV4YW1wbGUgQ3VzdG9tZXIiCgl9Cn0sIHsKCSJyZWNpcGllbnRJbmZvIjogewoJCSJlbWFpbCI6ICJkZWFyLWN1c3RvbWVyQGV4YW1wbGUuY29tIiwKCQkibmFtZSI6ICJVbmtub3duIEN1c3RvbWVyIgoJfQp9XQ==""UTF-8""Example Title Of An Email""Example Customer"Request successfully accepted
"Request successfully accepted. Use \\\"requestUid\\\" to track it's status.""UfQK-CPju-Ea5B-6y7X-8A72-VqU5"Email containing information about the recipient
"https://example.com/callback/emails/requestUid""Example Medical Insitution""GOV1234567890""Example Medical Insitution""GOV1234567890""sender@example.com""reply-to@example.com""Example Doctor""customer@example.com""customer-cc@example.com""customer-bcc@example.com""Example Customer""UTF-8""Example Title Of An Email""Example Customer"Request successfully accepted
"Request successfully accepted. Use \\\"requestUid\\\" to track it's status.""UfQK-CPju-Ea5B-6y7X-8A72-VqU5"This section provides information on the core data structures/data models that are used by this Building Block.
The resource model shows the relationship between data objects that are used by this Building Block.
7.2.1.1 Person
Each model schema MUST have a corresponding JSON Schema (API definition file).
| Name | Type | Description | Notes |
|---|---|---|---|
Name
Type
Description
Notes
Surname
String
Family name
First Name
String
First name
Birth Date
Date
DOB
Mobile Number
String
Phone number (mobile) of user
E.164 Mobile number standard. Should include country code.
Government ID number
Integer
Government issued ID number
Used when linking to global ID Building Block.
