Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
This section links to any external documents that may be relevant, such as standards documents or other descriptions of this Building Block that may be useful.
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.
The reference document for the security requirements.
The Architecture requirements guidance.
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 and Security requirements. This section will highlight important requirements or describe any additional cross-cutting requirements that apply to this Building Block.
Each Building Block must implement access and authorization audit, logging, tracing, and tracking with alerts (minimally proxied or implemented through the API Management and Gateway services).
The system must log all user activity in the system.
User action log is visible for admin users.
By default user action log is stored for 1 year after which the system will delete the log automatically. The storage length is configurable in the rules engine.
See detailed audit logging requirements part of the Security Requirements specification section 6.2. Also refer to the the Information Mediator Building Block's "Logging Services" (section 6.4), which may already provide an audit trail of API requests.
Each building block must implement the ability to provision, de-provision, and manage Identities and access rights (this may or may not be centralized for the whole architecture as a unified provisioning process).
See the Security Requirements specification section 6.2 (IAM).
The design of the building block should be inclusive, allowing for multiple languages/translations, as well as following all accessibility guidelines.
Egress, in the world of networking, implies traffic that exits an entity or a network boundary, while Ingress is traffic that enters the boundary of a network. Any ingress or egress traffic must leverage an Information Mediator or secure API gateway.
The following standards are applicable to data structures in the Registration Building Block:
Key Digital Functionalities describe the core (required) functions that this Building Block must be able to perform.
The Registration Building Block is a software platform that enables online registration services, their creation, and administration. It is composed of the following capabilities:
Online registration: e-services for a citizen/operator to register with an entity for any number of services.
Processing of registrations: a back office system to validate registration requests through human or automated operators.
Development platform for online registration and processing: to set up the interfaces, rules, and workflows for the above-mentioned capabilities.
To enable flexible and affordable creation and adjustment of the e-services, a no-code approach for the development platform is strongly recommended. The development platform is used by authorized personnel, called “analysts”, entrusted by the entities in charge of the registrations to develop the corresponding online registration services.
The online registration services developed with the no-code platform are used by the applicants who want to be registered and by the operators in charge of processing the requests.
The online registration services (e-services) created through the development platform are adapted to any type of registration. They consist of a succession of online screens and actions through which an applicant can complete the following generic process:
An applicant initiates a registration application. The system may smartly evaluate the applicant's data and guide the applicant toward the relevant eligible registration(s) during this initial step.
The applicant can provide claims (= fill out a form), credentials (=upload documents), and fees (= pay online or upload a payment receipt) (we call this part “application file”).
The applicant reviews & submits the application file. The system can warn of invalid or missing information through automatic validation, which can include use of external APIs. The applicant confirms and submits the application file to be processed by one or more entities in charge of the registration.
The applicant can see/monitor the status of the submitted application file while it is being processed by the registration entities' operators. If necessary, the applicant can submit corrections or additional information.
The applicant receives a decision (approve/reject) and results from the entities in charge of the registration.
An operator (a human or automated “robot” role) accesses a list of submitted application files and reviews the claims provided.
If the back office processing flow has multiple roles then the approval by the first processing role operator will take the application processing task to the next role in the workflow.
The operator makes a decision (approve, reject, or send it back for correction) about the application file.
The system, on approval, sends claims to a registry (i.e. registration of relevant information in the registry. See Digital Registries Building Block) and issues a credential.
The system at all stages can interact via API interface with other building blocks and external services to exchange and validate the information.
For each service, user rights can be defined and statistical reports can be configured (a part of the “development platform”).
The development platform allows to design online registration services quickly by configuring necessary rules and screens. The development of a new e-service should be possible through a no-code approach. An analyst user should be able to set up the following aspects:
Rules engine: a tool transforming legal rules relating to a registration (i.e. subjects, results, requirements, and determinants), defined by a human analyst, into machine-readable statements. This configures the high-level requirements and outcomes of the registration service overall.
Screens (user interface) and flow builder: a tool for a human analyst to create and organize the screens and fields that are necessary for the application (by an applicant) and processing (by an operator).
Controls configurator: a tool for a human analyst to define, for each field in the application file and processing screens, what controls will be applied (input format, formulas, actions/checks between fields and with external databases).
Registration Building Block does not define which registrant/object should be registered. But allowing applicants to determine if they are or are not subject to a registration is part of the Registration Building Block.
Long-term storing of registration data/claims and results is not covered in this Building Block. See Digital Registries Building Block for registry and data storage functionalities. However, the integration capability to the Digital Registries Building Block is part of the scope.
Event notification from external endpoints is not covered in this Building Block. See more in Messaging Building Block. However, the connection to the Messaging Building Block is part of the scope.
Payment solutions are not covered in this Building Block. See more in Payment Building Block. However, the connection to the Payment Building Block is part of the scope.
Data transfer security solutions are not covered in this Building Block. See more Information Mediator Building Block. However, the connection to the Information Mediator must exist as it is the base for the connectivity with other Building Blocks.
Consent management is not covered in this Building Block. See more in the Consent Building Block. However, the connection to the Consent Building Block is part of the scope.
Authentication/login is not managed in this Building Block. See more Security Building Block. However, the connection to the Authentication solution must be done in each Building Block.
Integration with special hardware (scanners, fingerprint readers, digital signature solutions, etc.) is not covered in this Building Block.
SMS and/or Voice services are not covered during the first iteration.
Developed by Frank Grozel (UNCTAD), Ingmar Vali (ITU), Tambet Artma(ITU), Saurav Bhattarai (GIZ), Dr. P. S. Ramkumar (ITU), Rauno Kulla (UNCTAD), Sebastian Leidig (Aam Digital), Annemarii Hunt
This section provides context for this Building Block.
Registration is a process through which an applicant gets information recorded in a registry and receives a credential as proof of registration, in exchange for providing information, with or without money. The information provided by the applicant consists of data and/or credentials issued by public or private entities. Money is provided to pay for one or more registration fees/costs.
A registration involves at least two parties:
an applicant who wants to register (something or somebody);
an authorized representative of a registry in charge of registering the data and issuing the credential.
One registration may involve more than two parties, as one or more third parties can be requested to assert/confirm the information provided by the applicant (a notary, a family member, a witness, another public entity, or a non-human entity such as a database); or a third party can be requested to receive the payment made by the applicant (a bank, a cashier, an online payment service). The registry or registries where the information is written can also be considered as a third party.
In some cases, multiple registration processes can take place simultaneously, i.e. the same applicant gets information registered in various registries and receives various credentials while providing information and money only once. This is known as “single window”, “simultaneous registrations” or “integrated registrations”.
In practice, from the applicant’s point of view, a registration process can entail the following operations:
Answer questions to determine if the applicant is eligible to register according to the data, credentials/documents, and fees required (for the applicant’s case).
Provide data in a form, and upload copies of credentials/documents.
Pay fees at a physical point of payment (bank, cashier, etc.) or through an online service (e.g. via GovStack Payments Building Block or equivalent).
Confirm his/her will to register.
Query the status of the registration process.
Receive credentials electronically or collect them at a physical point of collection.
From the point of view of the entity in charge (Registrar) of the registration, the process can include the following operations:
Ask questions to the applicant (on one or more screens) to determine if the applicant is entitled to register according to the data, documents, and fees required (for the applicant’s case).
Display, on one or various screens, the necessary fields for the applicant to enter the required data and documents (including a receipt of payment, in case the system does not propose an online payment option or if the user for some reason wants to make the payment physically or directly, in the traditional way).
Control that the information entered is complete and correct (and the applicant is entitled to register).
Validate the information submitted or, in case the information entered is incomplete or incorrect, send the file back to the applicant for correction.
When possible, call an external application allowing the applicant to pay the fees online.
Record the applicant’s information in a registry.
Issue a credential as proof of registration.
Terminology used within this specification.
Several elements of the glossary are based on the terminology defined by the World Wide Web Consortium (W3C) recommendations on the “Verifiable Credentials Data Model 1.0” (Nov. 2019) and Open ID Connect Core 1.0.
| Term | Description |
|---|---|
The version history table describes the major changes to the specifications between published versions.
| Version | Authors | Comment |
|---|---|---|
Registration
Process through which an entity gets claims recorded in a registry and a credential proving the registration, in exchange of providing some requirements.
Entity
A thing with distinct and independent existence, such as a person, organization, or device.
Claim
An attribute asserted by an entity, about itself or another entity.
Attribute
A property (data, information) relating to an entity.
Subject
An entity obliged or entitled to registration, or about which a claim is made.
Asserter
An entity that asserts a claim.
Registry
A paper-based or electronic database (centralized or decentralized, i.e. blockchain) where claims are stored and can be consulted.
Registrar
An entity that is authorized to register, in a registry, claims submitted by an applicant and to issue a credential proving the registration.
Applicant
Entity that requests the registration of claims in a registry.
Operator
A registrar or a staff of a registrar who is processing the request of an applicant.
Credential
A paper or electronic document created by an issuer and displaying one or more claims about one or more entities.
Issuer
Entity that creates a credential for one or more entities.
Scope
A set of claims and/or credentials required for a registration.
Service
Name given to a registration, or to a combination of registrations which can be undertaken simultaneously, by the entity(ies) in charge of the registration process.
Regulation
Normative text (law, decree, deed, decision, etc.) issued by a public entity.
Rule
Any regulation, or part of a regulation, which creates for specific subjects an obligation or a right to register, and defines, for each category of subjects, the results and requirements of the registration.
Requirement
Information (i.e. claims and credentials) and fees which must be provided in a registration process. Requirements may vary according to each subject.
Result
The result of a registration is usually a credential (sometimes called: certificate, license, permit, card, etc.) proving the registration, in addition to the recording of information in a registry.
Determinant
A determinant is an attribute, defined in the rule, used as a filter to determine/trigger if (1) an entity is subject to a registration and/or (2) what requirements this entity must provide to register.
UC- Use Case
A specific situation in which a product/Building Block or service could potentially be used.
Examples:
Employers must register to the Social Security registry (attribute = employer; what is triggered = subject to register at the Social Security registry) Foreign companies must obtain an investment license before investing (attribute = foreign company; what is triggered = subject to register for an investment license) Married traders must provide a copy of their wedding certificate when they register at the business registry (attribute = married; what is triggered = wedding certificate is one of the requirements to register at the business registry).
MCTS
Mother and Child Tracking System - Example Use Case to validate the system functionality.
0.7
Frank Grozel, Ingmar Vali, Tambet Artma, Saurav Bhattarai, Dr. P. S. Ramkumar, Rauno Kulla
Initial Revision
0.8
Frank Grozel, Ingmar Vali, Tambet Artma, Saurav Bhattarai, Dr. P. S. Ramkumar, Rauno Kulla.
Reviewers:
Neil Roy, Aare Lapõnin, Sasa Kovacevic, Fergal Marrinan, Surendrasingh Sucharia
Applied feedback from technical review.
0.9
Ingmar Vali, Sebastian Leidig, Frank Grozel
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
Reviewers: Steve Conrad, Wes Brown, Valeria Tafoya
New requirements added. Review feedback.
1.0
Wesley Brown, Steve Conrad, Valeria Tafoya
Final edits to align content to specification template for GovStack 1.0 release
This section lists the technical capabilities of this Building Block.
These requirements should be sufficient to deliver all functionalities that are listed in the Key Digital Functionalities section. These Functional Requirements do not define specific APIs, they provide specifications and information about any functionalities that must be implemented within the Building Block.
The functionalities described in this chapter apply to any government registration use case. For specific examples, please review example implementations that have been outlined:
Post-Partum and Infant Care Registration Example
Unconditional Social Cash Transfer
The purpose of the "online registration e-services" (from here on e-services) module of the Registration Building Block is to enable Applicants to apply for and receive registration claims (certificated documents).
As an Applicant, I want to use an e-service, so that I can apply for multiple logically grouped registrations with one integrated service and receive all needed claims/certificates simultaneously.
Provide an Applicant Dashboard that is visible after a user logs in to the registration system (REQUIRED)
This is the first page that all users see after logging in to the system. It provides a complete overview of relevant actions and should contain the following sections:
"My applications" part with various tabs,
List of applications (can be filtered and queried by status);
List of documents in the account and access to each of them;
Application file content - the data sent with the applications;
Messages received.
"Services available" part listing the services available for the applicant to use. For each service, there is a button, an icon, a title, an explanation text.
In order to make the service usable and personalized, Applicants must authenticate to the system - then the Applicant’s information is automatically attached to the application file when sending the application for processing.
Step-by-Step application Process (REQUIRED) An Applicant can select a service and follow a structured registration process to submit an application. This always consists of the following steps (some steps may be inactive for a given service, however):
Guide screen: Text providing information to the applicants (guidelines) or ask questions (through fields) to determine what category of subjects the applicant belongs to (i.e. if the applicant is subject to the registration and what data, documents and fees are required).
Applicant form screen: For the applicant to provide the required data.
Documents upload screen: where the applicant will upload scanned copies of the required documents/credentials.
Payment screen: where the applicant will see a list of fees that must be paid and can be redirected to an external online payment service.
Send screen: where the applicant can be reminded of any information missing in his/her application (if some fields have not been filled or documents have not been uploaded) and will be requested to confirm his/her will to apply for registration.
The above screens, when activated, will be displayed, in the predefined order as a wizard. If not activated, then the applicant will not see the inactive page. Service screens are preconfigured in Screen and flow builder as service schema.
The Applicant can save their application file as a draft and continue data entering later (REQUIRED) When an applicant is entering data the system must capture the data entered. For managing drafts the system must support to:
save and continue filling draft applications
delete draft applications
list applications that are in draft status
Provide guidance on applicable registrations (REQUIRED) The system must tell applicants which services are applicable. The system has a list of applicable registrations where the Applicant can make a selection before continuing to the next form page. Registration may be optional or mandatory. The system will not allow the Applicant to continue or submit the file if mandatory registrations are not selected. Applicants can select multiple registrations in the same application. Example: the UC-Postpartum infant care- Registrations in Civil registry, mother and child tracking program (MCTS), and optionally to paediatrician first meeting registration (three simultaneous registrations within one service).
Validate entered data for application (REQUIRED) When an applicant is entering data the system must validate the data based on the configuration made by the Analyst in the Control Configurator.
Allow document upload (REQUIRED) When an applicant has filled in data on a selected registration to apply for, the system must show which additional information/documents must be uploaded with the application. Duplicate requirements (of multiple registrations within the same application file) are merged. If a requirement is an output of one registration and at the same time the input to the next registration, then this document must not be asked/visible in the requirements list as it will be acquired during the process. An Applicant must be able to upload documents or take the documents to the counter service as originals.
Pay fees for application (REQUIRED) When an applicant has filled in data on a selected registration to apply for, the system must show which fees are relevant and allow the user to pay. Applicants must see the list of all fees to be paid, displayed both as a sum and separately; Fees can be paid in bulk; Fees can be paid at the beginning of the process (pre-payment); in the middle of the process after a decision or after the process is finished upon receiving the result/output (cash payment); Payment options may include: online payment; cash payment; mobile payment, etc.; All payment-related transactions must be logged; All payments received must be available in the payment registry (or equivalent registry) as successful transactions.
Send application for submission (REQUIRED) Applicants can move between the screens of the application process steps and change the data up to the point of submission. Applicants can submit an application for processing (flow). The system must validate inconsistencies in the application upon submission. The Applicant must be requested to confirm his/her will to apply for registration. All submitted applications are recorded in the processing flow engine and the first role defined in the flow builder will receive the registered application file as a task for processing. Movement between the processing roles is done via decisions (approve, reject, send back). Upon submission, the application appears as a task for the Operator of the relevant entity (see 6.2).
View application status and history (REQUIRED) An applicant must see the application and flow history, process registration time, and processing status in a flow:
see all applications in the draft, rejected, validated, and sent back for corrections status
filter applications: search free text from the application name, submission date, deadline date, and status (pending, validated, rejected, sent back for correction)
see the status including expected processing end time for each application and which Institution is currently processing the application
see certificates and/or approvals issued for the Applicant
view the content (data, documents) of submitted applications
correct and resubmit applications that have been sent back for correction by an Operator
communicate with the Operator processing the application (--> see 6.2.6)
Read information for QR-code/barcode and insert to registration form (RECOMMENDED) An applicant can use a function (e.g. button) and the action to capture data from the QR code. Expected result- the applicant can activate (a mobile phone) camera, read the QR code and capture the data from the QR code to a field. Example data to be captured: “MCTS31”; “www.registrations.org”
The purpose of the "processing of registrations" module of the Registration Building Block is to enable Back Office staff, i.e. Operators, to process applications, register information, and issue registration certificates.
Each back office operator can only see relevant data of the application. Operators are authorized to see and process their role-related applications.
List applications and tasks (REQUIRED) Operators have a view to see the list of applications to be processed and a task list dashboard.
The system has the function for an Operator to pick assignments from the common task dashboard.
The system has the view for an Operator to see assigned roles and assigned tasks for this role.
Operators are linked to Institutions (or sub-units) and roles, thus can only see the tasks relevant to their role and Institution.
Optionally (configurable) - an operator could be able to claim a task from the application task dashboard. When the task has been claimed, then the application file will be taken off the common pool.
View application file with all details (REQUIRED) An Operator of a role must see the received application file screen containing all information submitted by an Applicant and information complemented by other Operators while processing the same file.
Required documents relevant to this role and registration linked to the role;
Required data relevant to this role and registration(s) linked to this role.
An Operator must not see any information that is not relevant/required for the registration that this role is serving.
Must be able to see the history of the application file processing.
Must be able to see the status of the application file.
Make decisions about an application (REQUIRED) An Operator must be able to make a decision in the system by selecting the right decision type - approve, reject or send back for correction.
At least one decision option must be available in order to process the application file.
The system must enable a form for an Operator to draft a decision text and select/fill in additional information on the form.
In case of errors in the application, operators must be able to mark which document and/or data field is incorrect. Applicants must see the highlighted information.
Print, sign and upload a certificate (REQUIRED)
The system must not let an Operator make a decision in case a required document/result certificate is missing.
The system can display, print and upload a filled certificate from a template.
Edit application information if corrections are needed (REQUIRED)
The system must highlight if an Operator has made any changes to the information submitted by the Applicant.
The system should enable the Operator to remove and/or upload required documents.
Communicate between Operator and Applicant (REQUIRED) Operators have the option to communicate with applicant users.
Communication is application related and stored with application data.
Communication can be initiated by an operator or by an applicant. Communication initiation options must be configurable.
The communication system must be integrated with other systems via API (Information Mediator) and configurable for multiple channels.
Communication options are asynchronous and/or in real-time.
Many registration applications leverage a no-code development platform. The no-code development platform is composed of:
It is used by authorized personnel, called “analysts”, entrusted by the entities in charge of the registrations to develop the corresponding online services.
Pre-requirements:
The analyst is authenticated and authorized to use the no-code development platform.
The analyst has a computer/smartphone with an internet connection.
Post-requirements:
When the no-code development is finished, the analyst publishes the e-service, which becomes available to users (applicants and operators);
Applicants can submit applications;
Operators can process the applications.
The Rules Engine is a module where an analyst defines:
Who are the subjects of the registration.
For each subject, the result of the registration, e.g. a credential.
For each subject, what are the requirements for the registration:
Claims required;
Credentials required;
Payments/fees required.
The rules can be entered in the rule engine by an analyst, on the basis of the regulations; or provided by external rules providers (e.g. rules databases at the ministries level).
Creation of Services (REQUIRED) An analyst (user) must be able to create, in the rule engine, one or more services, each service encompassing one or more registrations. A “Service” is a name given to a registration, or to a combination of registrations that can be undertaken simultaneously. To create a service, an analyst will:
Give a name to the service;
Link one or more registrations to the service.
Publish service to external instance (RECOMMENDED) Each service can be published in the same or in a separate instance, together with the rule engine. The instance must be configured and interoperable with Registration Building Block service definitions.
Creation of one or more 'Registrations' (REQUIRED) An analyst can create one or more registrations. For each registration, the analyst defines in clear language and in the rules engine:
The name of the registration;
The entity in charge of the registration.
Definition of the subjects of a registration (REQUIRED) For each registration, an analyst must be able to report/input in the rule engine, in clear language, rules defining who/what are the subjects of the registration. To this end, the analyst can select one or various of the following options:
The registration is mandatory for all;
The registration is mandatory for specific subjects;
The registration is optional for all;
The registration is optional for specific subjects.
1 and 2 can’t be selected simultaneously; 3 and 4 can’t be selected simultaneously. Specific subjects (in 2 and 4) can be defined through determinants or a combination of determinants. Determinants can be combined by “AND” and “OR” operators. Combinations can be grouped into “groups of determinants”. A group of determinants can be combined through “AND” and “OR” operators. Examples:
Registration is mandatory for the attribute “resident” (all residents must register).
Registration is mandatory for attribute “resident” AND attribute “foreigner” (all residents who are foreigners must register).
Registration is mandatory for {attribute “resident”} AND {attribute “foreigner” OR attribute “have children”} (all foreign residents must register; national residents who have children must register).
Definition of the results of a registration (REQUIRED) An analyst must be able to report/input in the rule engine, in clear language, rules defining what are the results of registration. The result of a registration has a name (for example registration number, registration certificate, permit, license, etc.). To this name, the analyst must be able to associate a template/document (see RE-11). In some cases, some subjects of the registration will receive a different result. The analyst can define through determinants (or combination of determinants) the different categories of subjects and can link each category of subjects to a specific result. Examples:
Future truck drivers that apply for a driving license and pass the exam will receive a driving license for “large vehicles”, while car drivers will receive a driving license for “light vehicles” (attributes: “truck driver” or “car driver”).
Enterprises with assets below US$5,000 will receive a “Cottage Industry Certificate”; enterprises with assets above US$5,000 will receive a “Business License” when applying for an activity license (attributes: “assets below US$5,000” and “assets above US$5,000”).
Requirements of a registration - Documents/Credentials (REQUIRED) An analyst must be able to report/input in the rule engine, in clear language, rules defining what are the documents/credentials that must be provided.
A document/credential can be defined by a name.
One registration can have several required documents/credentials.
A document/credential can be physical or digital.
For each required document, the analyst can select one of the following options:
has to be brought to the front desk;
has to be uploaded;
has to be signed in front of an Operator.
The required documents can differ according to the categories of subjects. The analyst can define, through determinants (or combination of determinants) the different categories of subjects and link them to specific required documents. Examples:
Married applicants must provide a copy of their wedding certificate (attribute: “married”).
Foreigners must provide a copy of their residence permit (attribute: “foreigner”).
Applicants that can’t provide a copy of their birth certificate must provide a certified copy of their ID (attribute: “can’t provide a copy of the birth certificate”).
Requirements of a registration - Fees (REQUIRED) An analyst must be able to report/input in the rule engine, in clear language, rules defining what are the fees of a registration. The fees of a registration have a name (i.e. State fee of MCTS program, license registration fee, etc.). To this name, the analyst must be able to associate an amount and a currency.
Fee can be calculated or fixed;
One registration may have multiple fees;
All fees have an assigned currency. The system may allow multiple currencies;
A fee can have a description.
When the fee is calculated, a formula builder will allow the analyst to build the formula, using values from any field in the service and numeric values, combined with the usual operators (+, -, *, /). In some cases, some subjects of the registration will receive a different fee. The analyst can define through determinants (or combination of determinants) the different categories of subjects and can link each category of subjects to a specific fee. Examples:
Mothers with one child that apply to a registration to MCTS program will receive an identity card for 10 EUR, while mothers with two children or more will receive an identity card for 15 EUR (attributes: “one child” or “more than one child”).
Farmers with farming land area > 10 000 square meters that apply for registration of farmland will receive a registration certificate for 10 EUR, while farmers with land area <= 10 000 square meters will receive a registration result/credential certificate for 5 EUR.
Requirements of a registration - Data/Claims (REQUIRED) An analyst must be able to report/input in the rule engine, in clear language, rules defining what is the data (claims) that must be provided. A piece of data is defined by:
A name (e.g. date of birth, nationality, first name, last name, etc.);
A type (text, number, date);
mandatory/optional (See Control configurator element for more options).
As for the other requirements, some data can be required only for a specific category of subjects. The analyst can define, through determinants (or combination of determinants) the different categories of subjects and link them to specific required documents. Examples:
Married applicants must provide the first name, last name, and date of birth of their spouse (attribute: “married”).
Owners of farmland should provide the number and date of registration of their property; applicants who rent the farmland must provide the name and ID number of the owner (attribute: “own land”, “rent land”).
Possibility to combine various registrations in one service (REQUIRED) In many cases, the process for the user/applicant contains multiple pre-and post-registration steps in order to achieve the final goal (e.g. applying for a healthcare program). For example, in order to register a mother and a newborn child to the Mother and Child support program, both of the subjects must be previously registered in the Civil/Population registry. Civil registry registration service could be a separate service, but it is much user-friendlier and less time-consuming for the applicant to merge the two registrations into one service that can be filled at the same time. This service type is called Single Window or integrated registrations service. To facilitate the combination of various registrations in one service:
Registration requirements (documents/credentials, results, fees) must be reusable inside the service. One registration may re-use another registration result credentials as input requirements.
Overlapping requirements and/or results must be automatically eliminated.
Fees of all registrations must be merged into one sum so that the applicant could see and pay the total fees. Fee information is stored and segregated per registration.
In one registration the document/credential may be issued as a result and in another registration, the same document/credential may be required as an uploadable requirement. The system must eliminate the overlapping results and/or requirements if the requirements overlap inside the service. Examples:
One service has two registrations and both of them require a passport to be uploaded. When an applicant chooses to apply for both registrations then the system must ask for the passport upload only once.
One service has two registrations. The first registration’s result (credential) is the second registration’s requirement. The system must not ask for this requirement from the applicant as the result will be generated during the process. However, if the user chooses to register for only the second registration then the requirement must be asked.
Creation and functioning of determinants (REQUIRED) The analyst can define through determinants (or combination of determinants) the different categories of subjects and can link each category of subjects to a specific element of a service. An element of a service can be a field, block, button, message, processing role, result, requirement, etc. Being the simplest case, is this claim data field on the screen relevant for all subjects or only for a specific category of subjects? If all then no determinant is needed as all users will see and use it. If a specific (e.g. “applicant is married”) category and this category must fill in additional information (e.g. “Spouse name”), then a determinant must be added to control the field visibility for this category of subjects. If the user is married, then the determinant is true and the “Spouse name” field is visible; if the determinant evaluates to false, then the spouse name field is not visible for the subject. The analyst must be able to:
Create and manage determinants (CRUD);
Search the existing determinant;
Reuse determinants inside the same service;
Use formulas, calculate math functions on the form with user input value and use the calculated value in the determinant. E.g. math functions (SUM, MIN, MAX, AVG, COUNT, MEDIAN, CEILING, FLOOR, ROUND, CONCAT, CONCAT_WS, LEN, REPLACE, UPPER_CASE, LOWER_CASE).
Apply determinants to:
Any element of a service (registration, claims/data fields, screens, roles, templates, etc.);
Any element of a registration (results/credentials, requirements/documents).
Determinants can be combined by “AND” and “OR” operators. Combinations can be grouped into “groups of determinants”. A group of determinants can be combined through “AND” and “OR” operators.
Definition of a template associated with the result of a registration (REQUIRED) An analyst must be able to create an electronic template (a screen with images, text, fields, QR code) and link it to the result of a registration. A template can be:
Filled with values coming from fields in the service or from external databases;
Printed as a pdf file;
Generated and uploaded to the system as a PDF file.
On each template, an analyst can create data fields that must be filled by the system and place them on the screen of the template. Fields will have the following characteristics:
A name (e.g. date of birth, nationality, first name, last name, select option, submit an application, etc.);
A type (text, number, date, selector, catalog, button, etc.);
Source of information/capture data from. Function to capture data from application screens upon creation of PDF.
In addition to fields, the analyst can create information texts and add images, and QR codes on the template screen. QR code must be generated with the ISO/IEC 18004:2015 standard. Determinants and groups of determinants created in the rule engine can be assigned to each field on a template. A field will be displayed/printed only if the determinants assigned to it are true. Fields can be grouped into containers (blocks, tables, etc.). A container is defined by a name. Fields can be moved to and on the screen by “drag-and-drop, inside/outside of and between containers.
The purpose of the Screen and flow builder is to define and display the screens, and the fields on each screen, in the application file and processing parts, and to pre-fill or capture the data entered by the users of these screens in:
The application file, where applicants provide claims (fill out a form), credentials (upload files), and fees (pay online or upload a payment receipt) and send his/her request to one or more entities in charge of the registration.
The processing part, where one or more human or automated (“robot” or “BOT”) operators can review the information (i.e. the data and documents) provided by the applicant, approve or reject an application, send claims to a registry, and issue a credential.
Application file and layout - Creation of screens and their sequence (REQUIRED) An analyst must be able to create one or more screens that will allow to show information to the applicant and display fields that the applicant will have to fill in to provide the requirements of the registration. The analyst can define the sequence/order in which the screens will be displayed to the applicant. The analyst can define a one-screen e-service or create a multi-page wizard e-service supported by Breadcrumb. The number of screens in an e-service is not limited.By default, the system provides a template structure e-service screen skeleton. To this end, the analyst will be able to activate or inactivate, through a toggle, the following screens:
Guide screen: this is a screen where the analyst can create text for the information of the applicants (guidelines) or ask questions (through fields) to determine what category of subjects the applicant belongs to (i.e. if the applicant is subject to the registration and what data, documents and fees are required).
Applicant form screen: this is where the applicant will provide the required data.
Documents upload screen: where the applicant will upload scanned copies of the required documents/credentials.
Payment screen: where the applicant will see a list of fees that must be paid and can be redirected to an external online payment service.
Send screen: where the applicant can be reminded of any information missing in his/her application (if some fields have not been filled or documents are not uploaded) and will be requested to confirm his/her will to apply for registration.
The above screens, when activated, will be displayed, in the predefined order (guide, applicant form, document upload, payment, send). The flow of screens can be visualized by the analyst.
Application file - Creation of fields on each screen (REQUIRED) On each screen, an analyst can create data fields/claims that must be filled by the applicant and place them on the screen. Fields will have the following characteristics:
A name (e.g. date of birth, nationality, first name, last name, select option, submit application, etc.)
A type (text, number, date, selector, catalogue, button, radio, etc.)
Properties:
Multiple values(array type).
Catalog reusable source. Catalogs are reusable across all services in the same instance.
Field/Button reusable action (e.g. activate data bot AND save form AND generate PDF AND upload PDF to application file data).
The name of the registration(s) the field is associated with (i.e. the corresponding data is a requirement for this registration).
Mandatory or optional.
Determinants and groups of determinants created in the rule engine can be assigned to each field. A field will be displayed only if the determinants assigned to it are true. Actions and groups of actions created in the service can be assigned to each field or button. For example, an Action can pull data to the form, submit data to external API endpoints, create PDF documents from templates, or help users to move between the forms. A field will activate action automatically upon form load once. Actions can be controlled with determinants. Every time a field is created it is recorded in the “data” part of the rules engine. Fields can be grouped into containers (blocks). A container is defined by a name. Fields can be moved to and on the screen by “drag-and-drop, inside/outside of and between containers. In addition to fields, the analyst can create information texts and images that (contrary to fields) do not expect any input from the applicant.
Processing part - Creation of screens/roles (REQUIRED) The processing part relies on the flow builder because roles are part of the process flow. An analyst can create one or more screens allowing human operators to process the application files, i.e. to review the information sent by the applicant, to add data or documents to the application file (e.g. a number, a date, a credential, etc.), to approve an application, to reject it or to send it back to the applicant when more information is required. We call “processing role” (or simply “role”) each successive processing an application file will go through until final approval is given and the registration is completed. Usually, different roles are ensured by different government entities. It happens that successive roles are ensured by different units in the same entity. Example flow:
Unit 1 reviews the application file, and checks that all data and documents provided seem true and correct;
Unit 2 approves the application;
Unit 3 issues and signs the credential and sends it to the applicant.
For each role, two screens are necessary:
A first screen (list screen) where the operator will be able to,
see a list of application files, filtered by status (pending, validated, rejected, sent back to the applicant);
select a file for processing (if pending) or for consultation.
A second screen (processing screen) where the operator will be able to,
review the selected application file (data and documents provided by the applicant, fees paid or not);
add data or documents to the file;
Make a decision (approve the file, reject it, or send it back to the applicant).
Therefore, an analyst must be able to create one or more roles, each role coming automatically with one list user interface and one processing screen user interface. Each role will be defined with the following elements:
Name of the role;
Name of the registration the role is associated with;
Entity in charge of the role;
Position in the process flow.
Determinants and groups of determinants created in the rule engine can be assigned to each role. A role will be displayed/activated only if the determinants assigned to it are true. If Role determinants evaluate to false, then the application file passes the processing role without stopping.
Processing part - Ordering of sceens/roles in Flow Builder (REQUIRED) An analyst will be able to define, for each role, a list of possible statuses, by selecting which of the following statuses are possible for the role:
Pending (the file is waiting to be processed by the role).
Approved (the file successfully passed the role).
Rejected (the application is denied, the file is closed).
Send back to the applicant for correction (the operator sends the file back to the applicant and requests that some information be corrected or added).
For each activated status, the analyst will be able to indicate where the application file will be sent in the processing flow:
To another processing role;
To the applicant role (for consultation or payment);
To end (the application file is closed/ end of processing).
Therefore, the roles/screens in the processing part will come in an order specified by the analyst and this functionality is called Flow Builder. The analyst must be able to visualize the flow of roles/screens.
Processing part - creation of fields on processing screens (REQUIRED) On each screen, an analyst can create fields that must be filled by the role operator and place them on the screen. Fields will have the following characteristics:
A name (e.g. registration number, date of registration, type of registration, validate application, etc.);
A type (text, number, date, selector, catalogue, button, etc.);
The name of the registration(s) the field is associated with (i.e. the corresponding data is a requirement for this registration);
Mandatory or optional.
Every time a field is created it is recorded in the “data” part of the rules engine. Fields can be grouped into blocks, columns, field sets, and other containers (tables). A container is defined by a name. Fields can be moved on the screen by “drag-and-drop, inside/outside of and between Blocks. In addition to fields, the analyst can create information texts and images that, contrary to fields, do not expect any input from the applicant. Only human roles have the option to build processing screens. Determinants and groups of determinants created in the rule engine can be assigned to each field. A field will be displayed only if the determinants assigned to it are true.
An analyst must be able to add QR-code/barcode scanning function to the service screen (REQUIRED) An Analyst can add a form field element (e.g. button) to a screen and configure an action to trigger the capture of data from a QR code. Expected result- Analyst will build a service that has a button on the screen and a field on the screen to store the captured data. An applicant/user can trigger the “Read QR code” button on the screen of a service that opens the mobile phone’s (or another device's) camera, reads the QR code and captures the data from the QR code to a field on the screen. Example data extracted from the QR-code is “MCTS123”. QR code must be generated with the ISO/IEC 18004:2015 standard.
Actions (REQUIRED) The analyst must be able to configure the triggering of actions when a user or system initiates an event on a screen of a service. A triggering event can be a button click, a form loading, a form element click, data entered into a field, or a row added to a table. Before actions can be triggered the API request must be defined in action attributes. The action attribute specifies one or more of the following data mappings (BOT):
where to send (request) the form-data when an event is triggered and where to store the received data (response). For example, the user will enter their first name and last name into a form and after entering the last information the system will initiate a data BOT action to search data from the pre-defined external data source (via the Information Mediator Building Block) and store the answer(response) phone number to the correct data field;
where to pull data (from an external registry API) and where to show the answer in the user interface fields;
where to send user (screen flow action). For example, the button click will take a user to the next screen. The next screen can be an internal screen or an external URL;
validate captured data integrity (required fields must be filled);
save entered information, exit service form;
send message (screen message, sms, e-mail, API message etc.).
Some actions can be activated only for a specific category of subjects. The analyst can define, through determinants (or combination of determinants) the different categories of subjects and link them to specific actions. Examples:
User enters a person's identifier (tax number) and a button click pulls first name, last name and date of birth from an external API on the screen.
Married applicants must provide the first name, last name and date of birth for their spouse (attribute: “married”) and when data is entered, then the application screen will validate the entered person's name from the Population Registry and return validation answers on the screen (Success, Fail). Actions are only triggered if the user has entered the data AND “person is married” (determinant).
User clicks the “Validate and send” button on the screen, then the system will activate three actions: Save user data action, validate user data action, send user data action.
User clicks the “Print” button and the system triggers “Print to PDF” data action where a template is used as a base for creating a new PDF document. System will enable the user to see, print or download the generated PDF.
User submits application and system will trigger BOT Role in the flow and it, in turn, activates the data action bot (e.g. POST/GET message to external API).
Formulas (REQUIRED) Analysts must be able to add formula calculations to and between the fields. The Formulas can be added to numeric fields, int, decimal, and date. Calculated values allow calculating values based on the values in other fields of the form. E.g. If the registration subject has more than 2 children, then multiply the social payment times the number of kids.
Preview (REQUIRED) Analyst must be able to preview service User Interfaces before publishing the service to the applicants. The following preview functions must be available:
Preview of user interfaces one by one;
Preview of full service;
Preview of full service in test instance with the functionality to test the full service before publishing to live instance.
Import/Export of service descriptions (REQUIRED) Analyst must be able to import/export full-service description. Service descriptions must contain at least:
User interfaces, screens, fields;
Process flow;
Service settings.
As a result, the service can be imported with minimal effort from another instance and published for users/applicants to use. Instance-specific configurations must be done in each instance and are not target to import or export.
Text-to-speech feature (RECOMMENDED) User can activate the text-to-speech feature in the user information capturing forms to read out the screen information. The goal is to help illiterate users with understanding the text on the screen. The feature can read captured information and other e-service information visible on the e-service screens.
Voice guide feature (OPTIONAL) The feature enables to capture information from voice answers and ask confirmation if captured information is correct. Voice guide enable the user to follow the e-service wizard and submit applications.
The Control configurator is used to check if the claims (claims and credentials of registers) are complete and true. This is done by:
Define if the field is mandatory(required) or optional;
Add input masks (e.g. only numbers, text, alphanumeric, etc.);
Checks between fields in the screens, web services with external databases, or human revision (by an operator of the entity in charge of the registration).
The Control Configurator requires that the user is authenticated and authorized to use this administrative Control Configurator functionality.
Configure the data capture - form field value validation (REQUIRED) An Analyst must be able to configure field-specific validation options e.g.:
required;
number, bigger, smaller, min, max;
text, regular expression, contains, mask;
date, earlier, later, today, older than age (The age of the applicant must be >=18);
File upload size max limit;
File upload type allowed.
Control the data capture - form field value validation from external API (REQUIRED) An analyst must be able to configure screen field(s) validation from an external API data source. Examples:
Applicant name and ID must match with data in the Civil Registry record;
Subject (first name, last name, Dya of Birth) must not have been entered into the MCTS registry.
Control the data capture - data integrity validation (REQUIRED) The system must verify that all claims/fields are correctly captured and all required documents uploaded. The system must generate on-screen meaningful error messages if any requirements are not fulfilled. The system should not let the user submit an application file if screen data capturing is incomplete.
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 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 Registration Building Block can be found in this GitHub repository.
The available services (i.e. registration processes) and form definitions within such a service can be accessed:
Going through the registration process as an applicant requires multiple steps available via API endpoints:
Operators can access and process existing application files:
Currently there are no specifications for API endpoints to manage and design services and workflows.
The statistics API gives Building Block operational statistics, that reference the number of processed applications (per operator, registration, service, date):
This section provides a detailed view of how this Building Block will interact with other Building Blocks to support common use cases.
This workflow section provides a detailed view of how this Building Block will interact with other Building Blocks to support common use cases. It lists workflows that this Building Block must support. Other workflows may be implemented in addition to those listed.
In this section two main workflows are described:
Creating a registration service.
Using a registration service.
For each workflow interaction, a sub-section is added.
The analyst/administrator as the main actor in this workflow will create a new e-service by filling in the required registration requirements, creating screens for the user, and publishing the service on the web ready to be used by internet users.
As a pre-condition, the user/analyst has authentication credentials and authorization to the service builder- rules engine. If the service needs to read or write data from external sources (Information Mediator) that require authorization then this is already authorized for the Registration Building Block. Registration Building Block is connected to Information Mediator.
As a post-condition, the e-Service is published on the internet for users to use immediately. The optimal time for an Analyst to build the e-service of a simple registration service is 2h.
User journey is the step-by-step journey that a user takes to reach their goal. This journey consists of a number of website pages/screens and decision points that carry the user from one step to another. The user journey is used to map out the current journey a typical user might take to reach their goal.
This workflow requires interaction with the following Building Blocks:
Authentication and authorization (Security Building Block);
User registration (Security Building Block);
Information Mediator Building Block;
Payment Building Block;
Setup for multiple Registration Building Blocks.
For each interaction, the following information is provided:
Name;
Sequence diagram;
Notes;
Data structures (link to data resources defined above).
Interaction 1: Authentication and Authorization (Security Building Block)
Name: Authentication - Existing user authentication (Security Building Block).
Illustration 7 - Authentication and authorization.
Notes: Pre-requirements: user has passed the provisioning of user credentials and this can authenticate/login to GovStack (sandbox) system. User roles are also added by an Identity and Access Management (IAM) Security system when the token is sent to the Building Block. Registration Building Block in this case is operating as Building Block. See the full description of the user authentication in the Security Building Block documentation.
Data structures:
Interaction 2: User Registration (Security Building Block)
Name: User first-time registration (Security Building Block)
Sequence Diagram via Self-Registration:
Illustration 8- Self registration
Notes:
Pre-requirements: user does not have user credentials to authenticate/login to GovStack (sandbox) system. Registration Building Block in this case is operating as a Building Block user interface. See the full description of the User registration in Security Building Block documentation.
Sequence Diagram for User Self Registration via Foundational ID:
Illustration 9: Self-registration via foundational ID.
Notes: Pre-requirements: user does not have user credentials to authenticate/login to Govstack (sandbox) system. Registration Building Block in this case is operating as Building Block UI. See the full description of the User registration in the Security Building Block documentation.
Interaction 3: Information Mediator Building Block
Name: Request API descriptions (Information Mediator Building Block)
Illustration 10- Information Mediator API description.
Data structures:
Interaction 4: Payment Building Block
Name: Get list of payment options (Payments Building Block)
Sequence diagram:
Illustration 11- Request payment options.
Data structures:
Interaction 5: Setup for Multiple Registration Building Blocks
Name: Setup for multiple Registration Building Blocks
Description : The Registration Building Block can be set up as a standalone Building Block facilitating multiple institutions and services in one system instance (See illustration 1 below). Setup in one shared instance is required when one single window service is built together with multiple institutions (multiple registrations inside one service). This enables sharing of resources such as Process Flow Diagrams, screens, data, user rights, infrastructure, maintenance personnel, etc.
In other cases, the Registration Building Blocks can be installed in different instances (domain-specific instances- see illustration 2 below), and in this case, the Building Blocks are not sharing resources and are not communicating with the other Registration Building Blocks. In these standalone instances, the Building Blocks are communicating with Information Mediator Building Block and other Building Blocks.
The citizen/applicant, as the main actor in the process, will open a web URL address and authenticate. Once authenticated, the applicant opens an e-service and fills in the required data fields /claims on the first screen. The system/rule engine will then validate if the user is applicable for any registrations and if so will open a list of mandatory or optional registrations for the user to select. Once selected the system will fill the form with the required data fields relevant for the applicant to fill. In addition, the system will show which documents are relevant for the applicant to upload and how much fees to pay. An applicant will then fill in data, upload documents, select a payment method, and make the payment (if required). If designed so the Control Configurator component will validate captured data against external API data and in case validation fails issue warnings to the applicant. After payment, the applicant can submit the application file for registration and processing. The system validates if all required fields are correctly filled in upon submission.
The back office system registers all applications submitted. If configured so, the process flow may have bot(s) and human(s) in the flow. Bot roles process applications by validating information against external API information. When processed the BOT role will pass the processing task to the next role.
The back office operator as the main actor in the second part of the process receives a task notification message and authenticates to the web system. The system shows a list of applications assigned for the operator to process. The operator will then open the application and verify the application content and make a decision (approve, reject, or send it back for correction). If an application has discrepancies then the operator will mark the errors and/or explain the reasons for rejections. When the application file is positively processed by the back office operators, then the applicant will receive the credential/result of the application. If the back office processing flow has multiple roles then the approval by the first processing role operator will take the application processing task to the next role.
Preconditions: As a pre-condition, the web system is accessible from the internet, and the service is published, the user/applicant has user credentials for authentication. No authorization is needed for applicants if the service is usable by all users. The user/operator has authentication credentials and authorization to the web portal/back office system and to a service, if not open to all users. If a service needs to read or write data from an external source (Information Mediator-API) that requires authorization then this is already authorized for the Registration Building Block. As a postcondition, the applicant was able to fill out a registration form and submit an application. As an operator, the user was able to see the pending applications and process the applications.
Sequence Diagram:
This workflow requires interaction with the following Building Blocks:
Authentication and authorization (Security Building Block) - see “Creating a registration service”;
Information Mediator Building Block;
Payment Building Block;
Digital Registries Building Block.
For each interaction, the following information is provided:
Name;
Sequence diagram;
Data structures (link to data resources defined above);
Notes.
Interaction 1: Voucher Pre-Activation (Payment Building Block)
Name: Voucher pre-activation (Payment Building Block)
Use case: e-service user initiates a registration service to issue a payment voucher for the subject/beneficiary. Pre-conditions: The subject is identified and information is verified. The user has credentials to authenticate in the Registration Building Block web interface. User has authorization to use the Voucher activation registration e-service. User has pre-activated vouchers printed on the paper. All communication is securely done via Information Mediator Building Block. Post-conditions: A subject/ beneficiary will receive an activated payment voucher and the voucher is activated in the respective external registry.
Illustration 13 - Voucher issuing diagram.
Data structures:
This section provides information on the core data structures/data models that are used by this Building Block.
The following standards are applicable to data structures in the Registration Building Block in addition to the general Architecture Requirements:
QR code must be generated with the ISO/IEC 18004:2015 standard
The resource model provides a basic description of each data object that is used by the Building Block. It also shows the relationship between the data objects.
The data elements provide detail for the resource model defined above. This section will list the core/required fields for each resource. Note that the data elements can be extended for a particular use case, but they must always contain at least the fields defined here.
Description: Process through which an entity gets claims recorded in a registry and a credential proving the registration, in exchange for providing some requirements.
Fields:
Description: Name given to a registration, or to a combination of registrations which can be undertaken simultaneously, by the entity(ies) in charge of organizing the registration process.
Fields:
Description: A service is composed of one or several screens defined in the Screen Builder by the analyst.
Fields:
Description: One or several screens are defined in the Screen Builder. Screen(s) where a human operator will undertake actions to process an applicant file, usually enter data (e.g. registration number, or registration certificate) and press buttons (approve, send back for correction, etc.).
Fields:
Fields:
Description: Human or bot actor in the workflow who must process the application file in the order set in the workflow.
A role is defined by 4 properties: Name of the role; Who is in charge of the role- Institution entity; Type: Action that will take place in the context of the role, either human or BOT; Status decision options of the application file in relation to the role (0=pending, 1=passed successfully, 2=send back for correction, 3=rejected).
Fields:
Description: Institution in charge of Registration and/or Role.
Fields:
Description: An attribute asserted by an entity, about itself or another entity.
Fields:
Description: The result of a registration, in addition to the recording of information in a registry, is usually a credential (sometimes called: a certificate, license, permit, card, etc.) proving the registration.
Fields:
Description: Information (i.e. claims and credentials) which must be provided in a registration process. The requirements may vary according to each subject.
Fields:
Description: Amount of money to be paid in relation to a registration.
Fields:
Description: A determinant is an attribute, defined in the rule, which determines/triggers if (1) an entity is subject to a registration and/or (2) what requirements this entity must provide to register.
Fields:
Description: A workflow provides a visual representation of a business process. Workflow Engine executes processes that are defined in , the global standard for process modelling. With BPMN, the analyst can automate most complex business processes using an easy-to-adopt visual modelling language.
Name
Required Data
Notes
Existing user authentication
Credentials: username/e-mail/ UID,
Password,
URL of client system
User credentials vary depending on the country. Some countries may have additional user credentials, for example User ID number.
Precondition- user is registered in the GovStack sandbox.
Authorization
Roles
Example: “Service A”; “Registration Role A”; “Institution A”; “Part A”; “Part B”; “SADMIN”
Identity and Access Management (IAM) integration.
Precondition- user is registered in the GovStack sandbox (IAM)
Name
Returned Data
Notes
Get list of registered institutions/databases
Return: List of data providers (institution name, system name, ID)
The returned list (institution ID, system name) will be given as an input to the next call to see the list of APIs
Request API descriptions
Datasource name, ID, URL of the service and url for the service descriptions (swagger)
Pre requirements:
· Subscription for Registration Building Block to use the Information Mediator system is done.
· Before the Registration Building Block can use API information for screen populating with data the system must import API service descriptions
Get service descriptions
Input: URL of the OAPI service.
Output: OAPI descriptions
It works like Swagger. This endpoint may be external.
Example API services to integrate to Registration Building Block screens:
Registry Building Block - Register of Mother and Child Program
Payment Building Block API to read received payments data
Name
Response
Notes
Get list of payment options
Payment API descriptions,
List of payment options, details, data, url
Before the Registration BB can use the Payment BB information for screen populating the system must import API service descriptions
Name
Required Data
Notes
Voucher activation
Voucher ID
See more in Payments Building Block
Response
Status
The response is stored in Registration Building Block
Name | Type | Description | Notes |
id | varchar | identity of the registration |
name | varchar | nhe name of the registration |
entity | varchar | the entity in charge of the registration. |
determinants | object | determines if applicant is eligible for the registration |
Results | object | results that this registration is creating/issuing |
Requirements | object | requirements that this registration is requesting |
Fees | object | fees that apply to receive the registraiton |
properties | object | additional properties |
Name | Type | Description | Notes |
serviceId | varchar | service identifier |
name | varchar | name of a service |
version | varchar | version of the service |
type | varchar | used for grouping |
isExecutable | boolean | defines if service is active |
isClosed | boolean | defines if service is closed |
description | varchar | additional information about the service |
serviceBody | object | additional information about the service |
Name | Type | Description | Notes |
eFormId | varchar | form identifier |
name | varchar | name of the form |
description | varchar | descriptions of the form |
version | varchar | schema version number |
latest | boolean | true if latest version |
schema | object | schema of the form |
Name | Type | Description | Notes |
eFormId | varchar | form identifier |
name | varchar | name of the form |
description | varchar | descriptions of the form |
version | varchar | schema version number |
latest | boolean | true if latest version |
schema | object | schema of the form |
Name | Type | Description | Notes |
taskId | varchar | task identifier | Tasks are processed by operator role. |
mainTaskId | varchar | main task identifier | groups all role tasks into group (parallel and in sequence) |
name | varchar | name of the task |
assigneeId | varchar | user identifier who has been assigened to process the task | may be empty |
roleId | varchar | role name that is in charge of the processing | We call “processing role” (or simply “role”) each successive processing an application file will go through until final approval is given and the registration is completed. |
created | datetime | time of creation |
description | varchar | role description |
serviceId | varchar | service identifier where this role belongs to |
fileId | varchar | file identifier that this task is linked to |
eFormId | varchar | reference to a form that this task role must process |
formVariables | object | additional properties |
status | object | task status code |
data | object | data of the task |
Name | Type | Description | Notes |
id | varchar | role identifier |
name | varchar | role name | e.g. verifier, registrar |
registration | varchar | registration identifier that this role is serving |
entity | varchar | name of the entity-institution in charge of this role | Operators are linked to Institutions (or sub-units) and roles, thus can only see the tasks relevant for their role and Institution. |
position | object | position in the workflow |
determinant | object | defines if the task is applicable for the role |
Name | Type | Description | Notes |
id | varchar | identitifier of the institution entity |
name | varchar | name of the institution |
Name | Type | Description | Notes |
id | varchar | identifier of a field |
name | varchar | name of the field | e.g. First name |
type | varchar | type of the field |
properties | object | properties of the field | determinants, actions, validation/controls |
registration | object | registration(s) requestiong the claim/data |
Name | Type | Description | Notes |
id | varchar | result identifier |
name | varchar | name of the result | e.g. Program certificate |
templateId | varchar | template reference if applicable |
determinant | object | determinant(s) that determine if result is applicable. |
description | varchar | description of the result |
properties | object | additional properties |
Name | Type | Description | Notes |
id | varchar | document identifier |
name | varchar | name of the document | e.g. Program certificate |
templateId | varchar | template reference if applicable |
determinant | object | determinant(s) that determine if requirement is applicable. |
description | varchar | description of the result |
properties | object | additional properties |
Name | Type | Description | Notes |
id | varchar | identifier of a fee |
type | varchar | type of the fee | e.g. fixed/calculated |
formula | object | rules of fee calculation |
currency | varchar | currency identifier | e.g. EUR, USD |
description | varchar | description of the fee |
Name | Type | Description | Notes |
id | varchar | identifier |
name | varchar | name of the determinant |
source | varchar | field or object where the source information is taken |
rules | object | math rules |
properties | object | additional business rules |
Get the list of all e-service forms with schema related to the given service
The id for a defined service in the registration BB workflow engine.
"f7d33db0-2809-484e-a780-76b7ccd4ecbf"list of eForms or an empty array if none are available
The unique identifier of the e-form
"d98a205a-679b-485b-823d-7a32a391e744"The name of the e-form
"FORM"A description of the e-form
Version of the e-form
"1"True if the last version
The ID of the e-form to retrieve
OK
The unique identifier of the e-form
"d98a205a-679b-485b-823d-7a32a391e744"The name of the e-form
"A1"A description of the e-form
Version of the e-form
"1"True if the last version
The JSON schema of the e-form
Returns task list
Pagination of results. Specifies the index of the first result to return.
Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.
Sort the results lexicographically by a given criterion. Valid values are instanceId, caseInstanceId, dueDate, executionId, caseExecutionId,assignee, created, description, id, name, nameCaseInsensitive and priority. Must be used in conjunction with the sortOrder parameter.
Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.
list of tasks or an empty array if none are available
"PENDING""Pending"Returns task by id
Returns task by id
"42962de0-bdb2-11ed-9397-0242ac120004""PENDING""Pending"Upload a document/attachment to receive a documentId that can be linked to applications when submitting a new registration
Additional Metadata
"V2UgbG92ZSBqc29uIQ=="File successfully uploaded
Listing of all services with basic information
"Register Mother and Child"list of services or an empty array if none are available
unique identifier (serviceId)
"f7d33db0-2809-484e-a780-76b7ccd4ecbf"name of a service
"Mother and Child Registration"service version number
"123"Specifies whether the service is executable
whether Messages and Events, not modeled in Service, can occur when the service is executed or performed
Task successfully completed
"PENDING""Pending"Pass in the ID of the service and it will return all information about that service
The id for a defined service in the registration BB workflow engine.
"f7d33db0-2809-484e-a780-76b7ccd4ecbf"Service found and representation returned
unique identifier (serviceId)
"f7d33db0-2809-484e-a780-76b7ccd4ecbf"name of a service
"Mother and Child Registration"service version number
"123"Specifies whether the service is executable
whether Messages and Events, not modeled in Service, can occur when the service is executed or performed
Returns application file
"8a70cd6d-bdb2-11ed-9397-0242ac120004"Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/digitalregistries"Returns application file by id
Application file identifier 81c4445c-bff6-11ed-afa1-0242ac120002
"81c4445c-bff6-11ed-afa1-0242ac120002"Time when the application file was registered in the Registration BB system
"2000-10-23T00:00:00.000Z"id of the service this application relates to
"Post partum registration service""PENDING""Pending"True, if application file processing has ended
"false"Free text application name
"Amya Yuko"Applicant is a user who submitted application, this id references the user account logged in on the system and submitting this request. The applicantId could also come from OAuth2 and OpenID Connect authentication. New applicant records are created by the system internally if necessary.
"42962de0-bdb2-11ed-9397-0242ac120004"Time when the application file was created by the user- Draft
"2000-10-23T00:00:00.000Z"Form ID used in the data capturing
"42962de0-bdb2-11ed-9397-0242ac120004"Returns a list of application files the user has permission to access (i.e. either only the applicant's own applications or all applications for an operator to process)
id of a service to filter for applications of only this service
Applicant user ID
"42962de0-bdb2-11ed-9397-0242ac120004"Pagination of results. Specifies the index of the first result to return.
1Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.
10Sort the results lexicographically by a given criterion. Valid values are instanceId, caseInstanceId, dueDate, executionId, caseExecutionId,assignee, created, description, id, name, nameCaseInsensitive and priority. Must be used in conjunction with the sortOrder parameter.
"created"Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.
"asc"Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/digitalregistries"list of applications or an empty array if none are available
Application file identifier 81c4445c-bff6-11ed-afa1-0242ac120002
"81c4445c-bff6-11ed-afa1-0242ac120002""42962de0-bdb2-11ed-9397-0242ac120004""Application xyz""42962de0-bdb2-11ed-9397-0242ac120004""Registrar"operator ID who is processing the applicant file
"42962de0-bdb2-11ed-9397-0242ac120004"operator ID who has the task of processing the application file
"John Smith""PENDING""Pending""42962de0-bdb2-11ed-9397-0242ac120004"Time when the application file was created by the user- Draft
"2000-10-23T00:00:00.000Z"Time when the application file was registered in the Registration BB system
"2000-10-23T00:00:00.000Z""Any text.""Post partum registration service""42962de0-bdb2-11ed-9397-0242ac120004""42962de0-bdb2-11ed-9397-0242ac120004"Send an application file including all documents and form data to submit a registration request to be processed by operators.
The id for a defined service in the registration BB workflow engine.
"f7d33db0-2809-484e-a780-76b7ccd4ecbf"Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/digitalregistries"Create a new application file in the system
Free text application name
"Amya Yuko"Applicant is a user who submitted application, this id references the user account logged in on the system and submitting this request. The applicantId could also come from OAuth2 and OpenID Connect authentication. New applicant records are created by the system internally if necessary.
"42962de0-bdb2-11ed-9397-0242ac120004"Time when the application file was created by the user- Draft
"2000-10-23T00:00:00.000Z"Form ID used in the data capturing
"42962de0-bdb2-11ed-9397-0242ac120004"Returns started application file ID
Application file identifier 81c4445c-bff6-11ed-afa1-0242ac120002
"81c4445c-bff6-11ed-afa1-0242ac120002"Time when the application file was registered in the Registration BB system
"2000-10-23T00:00:00.000Z"id of the service this application relates to
"Post partum registration service""PENDING""Pending"True, if application file processing has ended
"false"Free text application name
"Amya Yuko"Applicant is a user who submitted application, this id references the user account logged in on the system and submitting this request. The applicantId could also come from OAuth2 and OpenID Connect authentication. New applicant records are created by the system internally if necessary.
"42962de0-bdb2-11ed-9397-0242ac120004"Time when the application file was created by the user- Draft
"2000-10-23T00:00:00.000Z"Form ID used in the data capturing
"42962de0-bdb2-11ed-9397-0242ac120004"Returns updated service application file ID
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/digitalregistries"Update application file data with operators input
Free text application name
"Amya Yuko"Applicant is a user who submitted application, this id references the user account logged in on the system and submitting this request. The applicantId could also come from OAuth2 and OpenID Connect authentication. New applicant records are created by the system internally if necessary.
"42962de0-bdb2-11ed-9397-0242ac120004"Time when the application file was created by the user- Draft
"2000-10-23T00:00:00.000Z"Form ID used in the data capturing
"42962de0-bdb2-11ed-9397-0242ac120004"Returns updated application file
Application file identifier 81c4445c-bff6-11ed-afa1-0242ac120002
"81c4445c-bff6-11ed-afa1-0242ac120002"Time when the application file was registered in the Registration BB system
"2000-10-23T00:00:00.000Z"id of the service this application relates to
"Post partum registration service""PENDING""Pending"True, if application file processing has ended
"false"Free text application name
"Amya Yuko"Applicant is a user who submitted application, this id references the user account logged in on the system and submitting this request. The applicantId could also come from OAuth2 and OpenID Connect authentication. New applicant records are created by the system internally if necessary.
"42962de0-bdb2-11ed-9397-0242ac120004"Time when the application file was created by the user- Draft
"2000-10-23T00:00:00.000Z"Form ID used in the data capturing
"42962de0-bdb2-11ed-9397-0242ac120004"API endpoint that allows anyone to see service statistics
Start date of statistics
"2021-01-30"End date of statistics
"2021-01-30"Name of registration
"MCTS"Name of operator
"Ingmar Vali"Role of the operator
"Handler"Timerame:
day - timeframe value = dayweek - timeframe value = weekmonth - timeframe value = monthyear - timeframe value = yearFormat is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/eregistrations-dev"Success Response
How many applications was processed
100How many applications was approved
90How many applications was sent back
3How many applications was rejected
7Data that was requested
"2021-01-30""2021-01-30""MCTS""Ingmar Vali""Handler"truefalsefalsefalse