Building Block Definition

<Name of Building Block>

Developed by: <Names and organization affiliations of working group members> In cooperation with GIZ, ITU, DIAL, and the Government of Estonia

Table of Contents

Version History

Description

<Example Description below>

Registration services attribute a unique functional ID to a person, place or other entity to identify and access information about it. According to the World Bank, functional IDs are those that evolve out of a single use-case, such as voter IDs, health records, or bank cards, and are created with a specific purpose in mind, differing from foundational IDs which are created with a general purpose in mind. Registration services can also use the foundational ID or map it to the functional ID where such an identity exists. Examples of specific registration services include immunization, disease and citizenship records, as well as birth and death registration. The ensemble of utilities for capturing, recording, profiling, searching, retrieving and verifying this identity information is encapsulated as registration services. The information itself will be deposited into and retrieved from corresponding functional registries (see the Registries ICT Building Blocks). Registration services help profile entities by enabling the registration of different categories or groups and documenting their access to various services. These services also onboard users into a programme or service offered by an organization (eg rural advisory service), capturing related demography, profile and citizen ID information.

Terminology

Terminology/glossary used within the specification

 Key Digital Functionalities

The Key Digital Functionalities describe the core (required) functions that this building block must be able to perform. These functionalities should be described as business processes as opposed to technical specifications or API definitions.

  Examples for Identification Building Block

1. Foundational IDs come with no specified purpose or attached entitlement but functionalities simply let an entity prove who it is

2. Captures only limited information about users, such as name, date of birth, address and gender

3. For a given set of credentials, fetches a corresponding ID if it exists in the registry

4. Uses different biometric methods to identify and authenticate users through means other than user photographs (eg fingerprints, iris scans, facial recognition) to ensure there are no duplicates or fakes, creating a highly trustworthy database

5. This ICT Building Blocks also uses a publicly available interface, or open API, which allows any licensed service provider to verify if users are who they claim to be

6. Used to enable services such as opening bank accounts, buying SIM cards, receiving entitlements from the government, signing forms electronically, investing in mutual funds and getting credit

7. Incorporates privacy into its design when the purpose of the authentication is not revealed if a service provider sends an authentication request.

Examples for Registration Building Block

1. Assign a unique (functional) ID and create identification pieces (eg smart card, bar functionalities code, RFID, digital token, unique number) with that ID and all related information about the entity

2. Map the assigned new (functional) ID to existing national (foundational) ID, if any

3. Populate demographic and/or geographic data of entities when registering for the first time

4. The complete registration information will be further used for any transaction or services later

5. This information can be used to complete the know your customer (KYC) requirements that businesses use to assess potential clients and comply with regulations

6. Capture identification information from biometrics, photos, scanned images, typed input, etc, and update the relevant registry with these entries using a specific ID tag

7. Determine if the specified ID exists in the registry according to a match with the given credentials

8. Automatically identify possible duplicate entries and merge them

9. Retrieve information corresponding to queries for a chosen entry, such as eligibility for subsidy, enrollment status, profile

10. Retrieve information of entries in the registry matching or nearly matching given credentials

Examples for Data Collection Building Block

1. Uses different data collection devices such as mobile phones, tablets and sensors functionalities

2. Requires identification and authentication to ensure that the system considers only data captured by authentic sources

3. Customizes data collection forms to enforce data quality, integrity and business Workflows

4. Collects multimedia content (eg video, audio and photos) and records geolocation coordinates

5. Uses a data collection form or interface that can include access to a camera or a sensor to capture ambient information

6. Sets data definitions and standards such as measurement system, format and nomenclature (eg population census, definition of income groups, standards related to type of housing, and terminology such as literate and semi-literate)

7. Provides data analytics tools to create statistics derived from collected data

8. Collects data offline and synchronizes data with a central data repository once connectivity is established

9. Provides safeguards against data loss

10. Provides access to data through APIs

  Cross-Cutting Requirements

The Cross-cutting requirements described in this section are an extension of the cross-cutting requirements defined in the architecture blueprint and nonfunctional requirements document. This section will describe any additional cross-cutting requirements that apply to this building block.

Cross-cutting requirements will use the same language (MUST or SHOULD) as specified in the architecture document.

<Example Cross-cutting requirements>

Privacy

Personal data MUST be kept private and never shared with any parties, except where specific authorization has been granted

Audit Logging

Logs MUST be kept in a database of all records that are created, updated, or deleted. Logs MUST include timestamps and identify the user and affiliation that performed the transaction

Source Code

Source code SHOULD be available and easily accessible

Security Requirements

List any cross-cutting security requirements that don’t apply 5. Cross-cutting Requirements of https://www.govstack.global/wp-content/uploads/2021/08/Security_Building_Block_Definition_1.0.1.pdf

MUST use 3FA for transactions accessible via mobile

Functional Requirements

The functional requirements section lists the technical capabilities that this building block should have. These requirements should be sufficient to deliver all functionality that is listed in the Key Digital Functionalities section.

These functional requirements do not define specific APIs - they provide a list of information about functionality that must be implemented within the building block.

These requirements should be defined by subject-matter experts and don’t have to be highly technical in this section..

Example Security Requirements

List any cross-cutting security requirements that apply with the context from the

Detailed Functional Requirements:

https://www.govstack.global/wp-content/uploads/2021/08/Security_Building_Block_Definition_1.0.1.pdf

Multiple API Gateway: this building block requires an API gateway to separate UI from API calls.

  Must

1. The registration system will allow users to create and update programs (also referred to as initiatives - a use case or project that requires registration of persons or facilities)

2. The registration system will allow users to create and update registrations of entities (either persons or facilities) into a specific program

3. User can query existing registrations based on search criteria.

4. Users should be able to query a single record or multiple records

5. The registration system will have a roles-based permission system to determine which users can perform which operations

Should

1. The registration system should have search and matching capabilities to avoid  duplication of existing records

2. The rules for matching records should be configurable

May

1. The registration system can provide reports and listings of all entities registered in a specific

   Out of Scope

 Performance Requirements

Data Structures

 Resource Model

The resource model shows the relationship between data objects that are used by this Building Block.

Note: Recommend using Flowchart Maker & Online Diagram Software to create the resource model and store in BuildingBlock repository (GitHub - GovStackWorkingGroup/BuildingBlockAPI )

  <Example Resource Model>

The registration building block’s core data model is an Entity. Based on the use case, this entity may be defined either as a Person or a Facility. A registration record connects an Entity to a specific Program. Finally, a Facility/Person entity can be associated with a Geography. (Note: this model may be extended to include additional entities, such as vehicles or equipment). 

Note that a Person or Facility entity can be further expanded based on the specific use case. For example, a Patient entity may be defined (derived from Person) for a health use case.

Open

Standards

The following standards are applicable to data structures in the registration building block:

   <Example Standards>

      All dates should follow ISO 8601.

Data Elements

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. Information about data elements will include:

1. Name

2. Description

3. Data Type

4. Required/Optional flag

5. Link to applicable standard(s)

6. Notes

Note: The data elements for each entity in the resource model will also be represented in the OpenAPI schema (link to GitHub repository)

<Example Data Elements>

Person

<Example Model Schemas>

Each model schema MUST have a corresponding JSON Schema. The API definition file can be found here:

https://raw.githubusercontent.com/GovStackWorkingGroup/BuildingBlockAPI/main/ExampleSchema.json

Service APIs

This section describes external APIs that must be implemented by the building block. Additional APIs may be implemented by the building block (all APIs must adhere to the standards and protocols defined), but the listed APIs define a minimal set that must be provided by any implementation.

All APIs will be defined using the OpenAPI (Swagger) standard. The API definitions will be hosted outside of this document. This section may provide a brief description of required APIs. This section will primarily contain links to the GitHub repository for OpenAPI definition (yaml) files as well as to a website hosted by GovStack that provides a live API documentation portal. 

<Example Service APIs>

Any implementation of the registration building block must support the APIs documented at this site: <link to GovStack API portal>

The API definition file can be found here: BuildingBlockAPI/ExampleAPI.yaml at main · GovStackWorkingGroup/BuildingBlockAPI

Changes to the API definitions can be made by submitting a Pull Request on this repository.

Workflows

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.

Standards

The workflows MUST adhere to all standards defined in this document as well as in the GovStack architecture document (link to appropriate section in architecture document)

Example workflow

Registration of new person

Prerequisites

Describe any prerequisites

Description

This workflow is used to enter a new record in the registration database. Data is submitted from a front-end application. This workflow shows a connection to an Identification building block (such as a government ID system) to validate that the registration is associated with a real person.

Interaction with Other Building Blocks

This workflow requires interaction with the User Interface and Identification Building Blocks

Sequence Diagram

The sequence diagram shows the flow of data between building blocks for this workflow.

The diagram is created with a tool like WebSequenceDiagrams - Draw sequence diagrams online in seconds

The raw text used to create the diagram should be saved and stored in the GitHub repository (GitHub - GovStackWorkingGroup/BuildingBlockAPI ).

Open

Interactions

 <The next workflow would go here, including name, description, sequence diagram and interactions>

Other Resources

Link to architecture requirements document (and specific sections within that document, such as cross-functional requirements, general recommendations)

Link to use cases document – this document may be a valuable resource while developing workflows to ensure that a variety of different use cases are covered by the building block definition.

 Link to BB criteria and maturity metrics document created by Tanvir

 Link to Low Resource Settings document

 Link to GitHub repository and OpenAPI documentation site for the building blocks.    

Key Decision Log

 11-06-2021 We decided to add a key decision log to capture the reasons behind key decisions made for future team members

Future Considerations

Internal Review

Please list future considerations arrived at by the team.

Peer Review Feedback

Please list future considerations arrived at by reviewers. This is useful to log complex suggestions that don’t fit in google doc comment threads.

Before this section, are there any assumptions of existing conditions or pre-requisites that must be in place for this building block to work?

Yes - we should address this in the next revision of the spec post reviewer feedback when we add more integration details. Perhaps we can address this along with @taylor@openfn.org comment about performance requirements (beyond what is defined in the functional spec) in a general pre-reqs section.