6-functional-requirements.md

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

6.1 User Story 1 - Registry Schema User Interface

As an Administrator/Analyst I want to use a web user interface to create a register database (example registry use case - social security program), so that I can configure and launch the registry database instantly to be used by internet users and client systems (e.g. Registration BB, Information Mediator BB) VIA web interface and API.

Actors: Analyst - An administrator user who is creating / changing registry database schema.Main actor/user in these requirements is the Analyst.

Preconditions:

1. 1.User is authenticated.
2. 2.User is authorized as an admin;
3. 3.The user interface is a web interface;
4. 4.User has internet;
5. 5.System has electricity.

Process:

1. 1.Create a new registry database project.
2. 2.Define the database fields.
3. 3.Publish the database.
4. 4.Validate/configure the API services.
5. 5.Manage user rights to access the database and APIs.

Post conditions:

1. 1.System contains a database that is ready to process new data.
2. 2.System has API services to CRUD data (and API to validate if data exist).
3. 3.User can enter data to the registry via web UI.
4. 4.User can see log information in the UI.
5. 5.User can see statistics in the UI.
6. 6.User can give authorization to use the database and process data.

REQ-#	Requirement	Type/UC-nr
DRS-1	Analysts must have the option to create a new registry database by filling the following information: Name of the database; A short name; Schema of the database (see DRS-3 ).	Must have UC1
DRS-2	Analysts can create multiple databases into one system instance. Databases must be linkable with foreign keys. See foreign key API description example in Appendix 2. Analysts can configure which databases and which fields are linked in the user interface. In this document and foreign key function we consider databases as database tables that can be linked with one another. See example illustration here. User story: As a user I can browse database content (Data) in the UI and when databases are linked, then I can click and move from one database to another where the corresponding linked data will open in the UI. In the Digital Registries Data user interface, it must be possible to open another database by clicking on the record ID in one database and all corresponding records from the other Database will open. It is required to have at least two levels of ID’s (database ID and field ID) to link the databases. See example API below in Appendix 2. Example: In one registry database we store information about Mother and Child record. In the second registry database we store information about payments made for the mother. System must enable a foreign key link between the payment database to the Mother and child record database. Users can click in the payment database record UI to the Mother ID field and the system UI must open the corresponding record in the Mother and Child database.	Must have
DRS-3	Analysts must have the option to add fields to the database schema. Fields of the database should contain at least the following elements: Field name; Field type, at least with following types: Text; Number; Boolean; Date; Date/time; File (pdf, doc etc). File extensions/types must be configurable; Edit grid (sub-table inside a field); Block container (to group fields visually); Catalog (holding value and key). Field advanced properties (mask, format, read-only, password (blinded), PersonalData, enum list selection); Validation options- Required Unique, max, min. Triggers (to create ID-s, merge fields, condition logic, transform-upper/lower case); Foreign keys (to link other databases in the same ecosystem). See example schema in Appendix 2.	Must have UC1
DRS-4	Analysts must have the option to publish the database. Publishing will reveal the database to users. Publish uses versioning. Every publish creates a new version of the database schema and API services; Old database schemas must be available to the users; Data stored in the old database versions must be usable in old versions and in new versions; Analysts can delete database schema versions. Same version API services must be deleted at the same time.	Must have
DRS-5	Analysts must be able to configure the API services per registry database. The system automatically creates API services to: create data; read data; update data; delete data; validate data (if exists); update or create data. Analysts can hide API services; Analysts can delete API services; Analysts can copy API services; Analysts can create custom API services; The system generates the API data structure from the dynamic database structure automatically each time a publish is done.	Must have
DRS-6	Authorization to: create and manage databases; API usage per service, per record, per data field; access to DATA. Analyst must have the option to manage user rights of a database and data via API and via UI. Attribute Based Access Control (ABAC) logic could be used (API, Schema, data fields, record filter, users); Anonymous user role must be available; Any logged in user role must be available; Per user, per group of users option must be available. Group is a set of users in a role. Role is a set of rights. Authorization/user rights are stored in addition in the central GovStack IAM system- read more here.	Must have
DRS-7	The system must log all data processing in the database. Schema changes must be logged; Data processing (CRUD) must be logged; Logs must be visible and searchable to the Analyst via UI; Every data owner (e.g. physical person) must have the option to see who has processed his/her data (PersonalData). The function is standard function for all registries. See more (DRS-14 API example) Change logs are protected with highest level of integrity (chaining of logs) Database logs could be logged with external blockchain(Nice to have). See more Audit Logging requirements here.	Must have UC3
DRS-8	Personal Data usage. System must automatically store all data read requests and store these in log table. Covers data read events via UI and via APIs. Personal Data logs are stored with PersonalData data tag, storing at least the following information. Log ID; Data record ID; Field ID; PersonalDataID(unique and unchangeable identifier of a person); Reader ID- who read the data; Reader name- name or initial of a person; When- the moment when the Personal Data was read. Personal Data report is visible only for Analyst to see all data read logs and Data Owners (physical person) to see their own personal data usage log. Input is PersonalDataID field. PersonalData report is usable as API service (read) System must have API for PersonalData reports. API is per registry(database) System must log Personal Data log read events to the log table.	UC3
DRS-9	Analysts must be able to create views of a database. View is a selection of data from a database; View can be opened as OPEN DATA (anonymous user); View can be created and it can be as a base for an API service (Custom API); View is not for changing or deleting data, only for reading; View rights are managed by the user rights management system.	Optional
DRS-10	Must have the option export/import database schema to JSON file, (optional: xls file).	Must have
DRS-11	Import DB structure Must have the option to import database structure from JSON file Must have the option to import database structure from XLS file	Optional
DRS-12	Service usage statistics System must record all API service usage information. System must record all searches made in the Registry UI and via APIs.	Optional
DRS-13	Analyst must be able to mark a field as PersonalData log object- This field contains personal data.	UC3
DRS-14	Analyst must be able to mark a field as PersonalDataID. This is the data owner’s ID.	UC3
DRS-15	Analyst must be able to mark a field as secret- This field contains secret data (credit card number). E.g. secret data (card data) must be encrypted while at rest. Information in transit between the BB-s is secured with encryption. Information in Transit is described and governed by Information Mediator BB.	Must have
DRS-16	Analyst must have the option to read database schema in the web UI.	Must have

6.2 User Story 2 - CRUD Data in User Interface

As an Administrator/ Analyst I want to process (CRUD) registry data so that I do not have to know the query language.

Actors:

• Analyst- main actor in these requirements is the Analyst/administrator.
• Data owner- is a physical person whose personal data is stored in the registry.

Preconditions:

1. Analyst is authenticated and authorized to use the BB and process data in the database.
2. The user interface is a web interface.
3. User has internet;
4. System has electricity.

Process:

1. Analyst searches a record via search or filter function.
2. Analyst selects a record.
3. Analyst processes a record.
4. System stores changes to the Change Log database.

Post conditions:

• Processing changes done by analysts are done and log for change is created.

REQ-#	Requirement	Type
DRS-17	Analysts must have a view to see all data in the registry. Two main views: Main registry records grid view. Record detail view. See data; See documents(open if image, download if other type); Data log view (changes (create, update, delete). Data before and after). Data read view (information about who has looked the data, /exported data). Data and data readers information is stored in the log registry.	Must have UC2 UC3
DRS-18	Analysts must have a view to edit data in the registry. Two main views: Main grid (inline editing); Detail record edit view. Edit data Remove/add documents (upload) All data changes are logged. Analyst must have option to delete data in the registry. All data changes are logged.	Must have
DRS-19	Analysts can use additional functions to simplify data searching: Filtering by search criteria by field content Full text data search Order by each data field	Must have UC2
DRS-20	Import data to the registry Analyst must have an option to import information to the database. Import formats are: json, csv, xls.	Must have
DRS-21	Export data from the registry Analyst must have an option to export selected/filtered data from a registry to CSV, XLS, Json.	Must have UC2
DRS-22	Statistical queries. The system should have the ability to: Produce standard statistical reports System must show statistics of all registered items in the registry, with various criteria for filtering. For example: Details of registered people Details of registered services Time series: Change in registration of people/services over time Details of change to data elements (audit logs) Generate customizable reports based on the fields registered in the registry. Allow the analyst/user to analyze data collected in the system in various ways: (Option) Develop functionality to allow custom dashboards for analysts to analyze data within databases Provide APIs for extracting data from databases to analyze in external data analytics systems (eg. Tableau)	Must have
DRS-33	Users can share data with other users. Share data with other users via e-mail, or via unique and secure URL. Sharing must be record level and field level. Data sharing can be turned off in authorization module. Data can be shared to anonymous users with URL.	May have

6.3 User Story 3 - CRUD Data APIs

As an Applicant I want to process (Create, Read, Update, Delete) data in the registry database.

Actors:

• Applicant - Main actor in these requirements is an applicant via client system. In this use case applicant is any user who is using a client system (Registration BB). For example, a Health Care worker is an applicant in this user story; a mother, using the Registration BB. Example client system in this document is Registration BB.

Preconditions:

1. Applicant is using client system (e.g. Registration BB) that is connected to Information Mediator BB;
2. Client system has been given authorization to access Registry to process (CRUD) information;
3. Applicant has been given authorization to access Registry to process (CRUD) information;
4. Applicants are registered in the system and able to use authentication. Applicant is Authenticated by client system or Security BB (Authentication).
5. Applicant has internet;
6. System has electricity.

Process:

1. Applicant uses a client system to process data in the registry
   1. Applicant can create data;
   2. Applicant can read data;
   3. Applicant can update data;
   4. Applicant can delete data;
   5. Applicant can create or update data;
   6. Applicant can validate data.
2. System logs all processing events in the dedicated audit registry;

Post conditions:

1. When Applicant is authenticated by a client system (e.g. Registration BB) the registry allows processing (CRUD) information from the registry. All users who are authenticated can read data.
2. When a user is not authenticated in the system, the system allows to process (CRUD) data from all databases where an anonymous user has been allowed to process data.
3. When a user has no authorization, one can not process (CRUD) any information in the registry.

REQ-#	Requirement	Type
DRS-23	BB must enable client systems to process (CRUD) the database records via Open API services. Applicant can search data; Applicant can create data; Applicant can read data; Applicant can update data; Applicant can delete data Applicant can create or update data BB authorizes client systems and users to process data.	Must have UC1;UC2
DRS-24	BB must have an Open API service list (Swagger) to visualize all API services and API service versions. Client systems must be able to see all API service descriptions including: Description of each field Example data of each field. If possible then the example must be real so that whoever is looking at the API specifications can test the example data in the service (try it).	Must have
DRS-25	System must have an API for PersonalData usage report. API input must be configurable by the analyst. Input must be a unique identifier of the data owner(e.g. personal identification number). If registry database schema is designed to store personal data then the analyst must be able to link the personal data to the owner of personal data (e.g. citizen).	Must have UC3
DRS-26	Statistical queries via API. System should make data accessible through the API Registration Data Programme Data API should allow querying data with multiple parameters Date, time ranges Registered Program Only authorized data should be available through the API.	May have
DRS-27	Using viewing event logs- every data owner has the right to see who has looked at their personal data. Data owner is a physical person whose personal data is stored in the registry. Data owner has the right to access data reading/processing event logs of the personal data they own. Personal data in a registry is marked accordingly (PersonalData) by the analyst. PersonalData logs are visible via API or via user interface (PersonalData report).	Must have UC3

6.4 User Story 4- Registry Schema API

As an IT-developer I want to Create/update/delete registry database schema via API services.

Actors:

• IT-developer (Developer)- Main actor in these requirements is planning to open a new business program and web form to capture applicants data. Captured data must be registered in the registry. In this use case a Developer is any user who is using API services to create and manage registries database.

Preconditions:

1. Developer is using API with a client system or a script that is connected to Information Mediator BB. Client system is any BB that is using API services via IM;
2. IT-Developer (IM organization) has been given authorization to Create/update/delete database schemas via API services.
3. Developer has internet;
4. System has electricity.

Process:

1. Developer uses a client system to edit registry database in the BB
   1. Developer can create database/schema;
   2. Developer can read database schema;
   3. Developer can modify database schema;
   4. Developer can delete database schema and all data in it.

Post conditions:

1. When Developer is authorized to use BB API then the Digital Registries BB allows processing (CRUD) schema of a registry. All authorized users can read/create/update/delete database schema;
2. When Developer is not authorized to process/CRUD the database schema, the system allows to process schema of all databases where an anonymous user has been allowed to edit database schema (simplification for GovStack Sandbox instance);
3. When a user has no authorization, one can not create nor change (CRUD) any schema in the BB.

REQ-#	Requirement	Type
DRS-28	Developer must have the option to create a new registry database by sending data via API: Name of the database; A short name; Schema of the database (see DRS-3 ). See full list of example API descriptions /database/modify here.	Must have
DRS-29	Developer can create multiple registry databases into one system instance.	Must have
DRS-30	Developer must have the option to publish the database. Publishing will reveal the database to users.	Must have
DRS-31	Developer must be able to modify API services per registry database. The system generates the API data structure from the dynamic database structure automatically each time a publish is done. The system automatically creates API services to: create data; read data; update data; delete data; validate data (if exists); update or create data. Developer can hide API services; Developer can delete API services; Developer can copy API services; Developer can create custom API services.	Must have
DRS-32	Developer must have the option to read database schema via API. Developer must have the option to read the list API services available per Database.	Must have

6.5 Coverage Map

The coverage map shows how the Functional Capabilities (by an applicant and a registrar) in specific use cases match the functional requirements described

Use Case	User Journey	Functional Capabilities	Technical Requirements of Admin tools	Technical Requirements of User tools
Registration	Postpartum and Infant Care	6. Update Register. The local register is updated for later use.	4.1 User story 1 - Registry schema User Interface; 4.4 User story 4- Registry schema API; DRS-1; DRS-3; DRS-4; DRS-5; DRS-6	4.3 User story 3 - CRUD data APIs; 6. Service APIs; API - Schema; API - Data
Registration	Postpartum and Infant Care	9. Update Registry The card number and mothers details are sent to the Govn. Registry for update, e.g. Department of Health or Home Affairs.	DRS-5	4.3 User story 3 - CRUD data APIs; API - Data
Registration	Postpartum and Infant Care	11. Update Register The local register is updated for later use and submit the information for the remote Govn. Department Registry.	DRS-5; DRS-13; DRS-14	4.3 User story 3 - CRUD data APIs; API - Data
Registration	Postpartum and Infant Care	13. Give Reference Number Once the request is successfully committed the mother is given a reference number	DRS-5	4.3 User story 3 - CRUD data APIs; API - Data
Registration	Postpartum and Infant Care	14. Search Patient Case Generate a new folder for case records and link it to the child ID. If no case exists, create one and link the Card, otherwise identify the correct record and store the case UID.	DRS-5; DRS-13; DRS-14	4.3 User story 3 - CRUD data APIs; API - Data
Registration	Postpartum and Infant Care	15. Update Registry The card number, mothers details, childs details and birth details, are sent to the Govt, e.g. the Department of Home Affairs.	DRS-5; DRS-13; DRS-14	4.3 User story 3 - CRUD data APIs; API - Data
Payments	Postpartum and Infant Care	3. Capture details for the Mother Capture data to verify the mother and prevent fraud per legal requirements, for processing later.	DRS-5; DRS-13; DRS-14; DRS-28; DRS-29; DRS-30; DRS-31.	4.3 User story 3 - CRUD data APIs; API - Data
Payments	Postpartum and Infant Care	4.1 Validate the mother has completed all steps	DRS-2; DRS-5; DRS-9	4.3 User story 3 - CRUD data APIs; API - Data
Payments	Postpartum and Infant Care	4.2 Verify mother has no pending incentive voucher for this milestone?	DRS-2; DRS-5;	4.3 User story 3 - CRUD data APIs; API - Data
Payments	Postpartum and Infant Care	6. For the mother, a cash payment is given via a paper payment voucher	DRS-2; DRS-5;	4.3 User story 3 - CRUD data APIs; API - Data
Payments	Postpartum and Infant Care	9. Record payment status and amounts in registry	DRS-3 DRS-5;	4.3 User story 3 - CRUD data APIs; API - Data
Case Management	Postpartum and Infant Care	3. HC workers have access to minimal required data for the purposes of completing this process.	DRS-5;	4.3 User story 3 - CRUD data APIs; API - Data
Case Management	Postpartum and Infant Care	5. The HC worker updates prescriptions for medication	DRS-2; DRS-5;	4.3 User story 3 - CRUD data APIs; API - Data
Registration	Unconditional Social Cash Transfer	3. The admin may create a new registration record if none exists for for the potential beneficiary	DRS-2; DRS-5;	4.3 User story 3 - CRUD data APIs; API - Data
Registration	Unconditional Social Cash Transfer	7. Optional: Programme specific data is often entered into a separate Beneficiary Registry associated with a Beneficiary Operations Management System (BOMS)*	DRS-1 DRS-2; DRS-3; DRS-4; DRS-5;	4.3 User story 3 - CRUD data APIs; API - Data