Consent BB status update
Based on GovStack Building Block Cookbook
Milestones | Typical Activities | Deliverables | Status |
Scoping | Identify use cases that may use services in domain addressed by this BB in its workflow. Define journey within these use-cases with episodic serial logical steps that groups activities that happen in parallel. | Logical process blueprint describing use-case journey with episodic steps | Completed v1 |
Map activities within a logical process step (episode) and identify activities which are handled by specific BBs. Create list of BB microservices needed in each episode. | Logical process blueprint updated with list of BB microservices needed with priority(current/future scope/ needed but from other BBs) | Completed v1 | |
Describe Scenarios of service calls | Define unique scenarios in which each microservice may be consumed with different inputs and outputs | BB Use-Case Scenarios defined for all prioritized BB microservices | Completed v1 |
For each unique scenario, describe the preconditions, assumptions, actors, data inputs, normal and alternate internal workflows, outputs and post conditions, exceptions, dependency on other BBs (egress calls from this BB) expected to deliver the requested service. | Use-case scenario definition and link updated in relevant BB specification docs | Completed v1 | |
Defining Key digital Functionalities (KDF) | Identify key functionalities needed within each BBs in order to provide a specific microservice. | KDF updated in relevant BB specification docs | Completed v1 |
Define assumption and prerequisites to use each functionality | Functional requirement section of respective BB specification documents updated in BB definition document with relevant references to standard practices / features Enumerate candidate s/w products that might satisfy some of the functional requirements | Completed v1 | |
Identify common internal functional blocks that may be required to orchestrate all KDS of the BB | Completed v1 | ||
Layout internal functional blocks and workflow along with block diagrams, flowchart, etc. for each KDF | Completed v1 | ||
Defining Data Structures | Identify data elements, groups and schema needed by functional blocks to orchestrate services of this BB in a MVP footprint | Resource model defined in BB specifications with references to relevant standards | Completed v1 |
Cross cutting requirements | Describe security and architectural deviations if any needed in this BB that is in addition to or exclusion of those defined in Govstack Security and Architecture specification documents | Define deviations with justification and populate links to other compliant sections of BB security and Architecture guidelines | Completed v1 |
Key decisions | Comprehensively Log any key decisions taken either internally or due to external feedback from reviews along with references and justifications | Updated key decisions log in bb specification | Completed v1 |
Terminology | Identify and describe new terms if any, used in the BB specifications for this BB | Terminology document with links inserted in Glossary of BB specification | Completed v1 |
TAC Review | Finalized BB definition template submitted and presented for review by Tech-advisory group review | BB Spec presentation PPTS, draft documents signed off by BB leads | Completed v1 |
TAC feedbacks collection and assessment, discuss recommendations leading to corrections/pun into future or out of scope bins | Current specs updated with changes or posting for future scope / not in scope signed off by BB leads | Completed v1 | |
Functional specification Publication | Clean up presentation for typos, consistency, clarity and reader friendly presentation. | BB specifications verified for accuracy and signed off by BB leads | Completed v1 |
Specification with appropriate versioning details published on Govstack and other sites | BB documents hosted publicly and Govstack Website links updated accordingly | Completed v1 | |
Open API Interface Definition | Define interaction with external applications/BBs specified in workflow during ingress and egress service calls of this building block | Interaction protocol flowcharts with associated data fields defined in English into BB definition document with references to relevant standards | Completed v1 |
Open API specification of service calls and return formats for success/error/exception conditions | Swagger OPENAPI V3.0+ service APIs | Completed v1 | |
BB API compliance Tests | Define Rest-Api according to service request-response protocols and data structure from BB specs | APIs in Open-API V3.0 Yaml/JSON format | Completed v1 |
For each API write test requirements in English including all associated API calls (both ingress and egress requests) | Set of test cases with expected requests and responses for service calls landing on the BB and calls emanating from this BB to other BBs | In progress v1 | |
Develop stubs with mock requestor-responder code or API adapter (if BB code exists) to cover set of test cases | Dockerized Stubs with mock requestor-responders / BB Adapters | In progress v1 | |
Launch Mocks with Stubs and run test cases between requestor and responder stub endpoints | APIs qualified for compliance with BB specs | In progress v1 | |
BB API Integration Tests | Add IM interface into Mock requestor/responder code | BB APIs mock/adapter codes upgraded with IM interface and protocols |
|
Integrate with information mediator | BB Apis adopted into IM (service discovery and access) |
| |
Run same test cases with IM in between the requestor and responder stubs | BB service integration qualified to work with same requests coming through IM |
| |
BB API Interoperability Tests | Replace requestor stubs with other IM integrated BBs (stubs/adaptors) | BB configured to access APIs of other BBs on Govstack as well as receive service requests through info med |
|
Run interoperability tests with other BBs that are integrated as consumers / service providers for the BB under test | BB APIs qualified to interoperate with APIs of other integrated BBs (both ingress and egress) |
| |
API Publication | Document qualified APIs and associated test case definitions as part of BB specifications | Published Open API interface specifications |
|
User journey integration | Integrate Qualified APIs into Sandbox | Sandbox updated with qualified BB APIs |
|
Develop cross-building block workflows at backend and application front end according to logical process flow | Application frontend (screen flow) and backend(workflow) developed according to logical process blueprint |
| |
Conduct tests of logical process flow | Test automation scripts and mock applications, test results |
| |
Create automated demo presentations | Hosting of qualified demos |
|
Building Block Specification:
Every use-case of Gov-Stack is defined as a journey of several steps along which services of one or more BBs are called by the main workflow. At the beginning of the specification a brief description of the main goals achieved by the building blocks, different application sectors in which it can be used, terminologies specific to the BB and clear indication of things that fall within the scope and out of scope of the building block’s functionalities are identified. A building block may provide multiple services to address the needs of several use-cases. Each use-case may consist of a journey of activities among one or more participant people and systems (actors).
Establishing Logical process blueprint:
To start deriving a BB specification, a given user journey is typically broken down into “logical process steps” where each step depends on completion of previous steps. For example, in a use-case of mother and infant care program, one may find the following logical process steps typically starting by promoting awareness to citizens, registration of eligible willing citizens, helping them to book, track and avail services such as doctor consultation, therapy and medicine such that the mother and health assistant get incentives on successful completion of stated activities in adherence with rules of the program. This use-case can be broken into a journey of several logical process steps accordingly as shown in diagram below:
The breakdown of this use-case journey is captured in the “logical process blueprint (LPG)”. Different LPGs may exist depending on the condition of the mother and child. BB groups can define different LPGs using the LPG template available “here”.
Mapping service calls to Building blocks:
Further, a single step within a LPG may involve several sub-steps. For example, the “Registration” step in mother and childcare LPG may involve the following sub-steps that map to different Building Block service calls as shown below:
Mapping BB microservice calls : Typically this breakdown is at a level where a sub step may request a specific BB to get the desired work done. Such BB micro-services return specific outcomes based on the input parameters. Micro Service Definitions: All microservices of the building blocks are defined as request-response pairs in a list as shown in an example subset below.
ID | Service call | Service returns |
1 | Create_session(sessionconfig[fieldnames, field values]) | Returns new session ID after creating new Session in worklist with given details in JSON array of [field name: field value]pairs |
2 | update_session(Session Id, sessionconfig[fieldnames, field values]) | Returns success code after changing details of given session ID in the worklist, as per given details in JSON array of [field name: field value]pairs |
3 | cancel_sessions(session_id) | Returns success code after deleting given Session in worklist |
4 | get_session_details (Session ID, sessiondetails [field names]) | Returns details as per JSON array of {fields} for a specific session ID |
Note that the building block may have both ingress calls (external sources calling services of the BB) and egress calls (BB calling services of other BBs to complete part of its internal workflow). Depending on the inputs of a use-case in which a microservice is called, the BB may respond with different outcomes from same service. A BB’s behaviour in response to different scenarios are defined in multiple scenario templates. The template will detail the context (preconditions, assumptions, inputs) and expected functional outcomes from the BB microservice using the template here – BB use-case scenario definition template, An example use-case template for scheduler building block is produced below:
Example Use-case scenario definition Post-Partum Care Program (Apointment booking)
ID | PPCP_Scheduler_UC_01 |
Logical process step | Consultation Appointment: Post-Partum Care Programhttps://github.com/GovStackWorkingGroup/BuildingBlockAPI/projects/1 |
Scenario | Health worker assisted appointment management for consultation |
Description
| Brief description of the scenario in which this service of the building block is consumed by another BB or Application, by giving specific inputs and return of specific outputs. Note the same service could have multiple modalities depending on infra maturity, each becomes a separate scenario, although service may be same. For example payments through mobile money or through banks create two alternative scenarios for the payment BB. |
Trigger | PPCP App sends request to scheduler BB to create/cancel consultation event. |
Preconditions | Entities that provide consultation services are registered under the PPCP program …. |
Data inputs | Query parameters to find free slots 2… |
Actor | mother, Doctor, Health Worker |
Normal Course | Appointment booking: Organizer(Health worker) captures subscriber’s (Patient) preferences (such as doctor, dates, time-zones, entities, etc.) in PPCP App and submits appointment request for a consultation session ….. Appointment Cancellation: Organizer(Health worker) submits appointment ID and request for cancellation of booked session through PPCP_app to Scheduler[planner]…. |
Alternative Course (Scenario 2) | In an alternative scenario, patients may themselves login to the PPCP_App application and book appointments without support of Health worker. This is a subset of the workflow mentioned above. |
Data output | List of available free slots Event related alert Messages…….. |
Post-Conditions | Appointment booking: Specific session of event plan is updated with either completed or no show status Reporting: Relevant datasets are returned as JSON formatted string….. |
Exceptions | PPCP_App prompts Organizer(Health worker) to request new appointment if confirmation is not received from Scheduler within a predefined timeout period ….. |
Related BBs | Service ordering, Registration, workflow, Information mediator, Messaging, PPCP App |
Remarks | This use case model can be used for other types of consultations such as legal/financial/etc. between subscribers (plaintiff/investor/etc.) and consultants (lawyer/auditor/etc), organized by respective assistants. |
Workflows | Link internal workflow diagrams here for various micro services used: e.g booking/cancellation/tracking and alerting/status reporting of appointments |
Deriving key digital functionalities: By inspection of micro service definitions from multiple use-case scenarios, a set of common key digital functionalities are identified. These functionalities are organized into internal function blocks with suitable control and dataflows so as to orchestrate all define micro services appropriately. Each functional block will have to be described in the building block specification and associated interactions with other internal or external blocks be illustrated in suitable workflow diagrams ( Websequence diagram is a tool commonly used currently for drawing these flows and http://draw.io is used for block diagrams).
Example functional blocks given below:
Example illustration of microservice workflow given below:
Data modelling: Data elements needed by the functional blocks are identified and grouped into structured lists and resourced models on an MVP footprint. An example is given below:
Resource Class | Element | Description |
Worklist | ID | Unique ID of a specific session |
Start_Date | Starting date of the session | |
Start_Time | ending date of the session | |
…… | ….. |
Log | Log_ID | Unique identifier of a specific transaction |
Category | Unique identifier of a specific type of transaction (Based on what change did the administrator affect) | |
…… | Details of transaction done and who did it | |
BB Config | Block_ID | Name of internal block which is to be configured |
Config_data | Latest Configuration settings of various parameters in this block given in JSON format | |
………. |
| |
Alert List | ID | Unique identifier of a specific alert message bound to a session |
Category | Type of alert message (appointment alert/ process trigger/ healthalert/crimealert/etc.) | |
…... |
| |
Resources | ID | Unique identifier of a specific Resource |
Phone | Resource phone number | |
…… |
| |
Subscribers | ID | Unique identifier of a specific subscriber |
Phone | Subscriber phone number | |
Location | Address of subscriber | |
… | ……. | ……. |
API interface definition:
All service transactions with a BB will happen through specific protocol interfaces defined as per OPENAPI V3.0+ Resfult API definition standards. These interfaces are defined to indicate hosting requirements, API calling input formats, expected output formats and dependencies if any for all ingress calls. The egress calls are expected to comply with the appropriate target BB’s APIs. The definitions may be drafted with any editor, swagger tools are most common.
An example API definition snippet is shown below:
openapi: 3.0.1
info:
title: Govstack Scheduler BB API
description: Interfaces to services rendered by Scheduler building block
termsOfService: TBD
contact:
email: psramkumar2@gmail.com
license:
name: Apache 2.0
version: 1.0.0
externalDocs:
description: Find out more about scheduler
servers: [
{
"url":
"description": "Scheduler BB Security server"
}
]
tags:
name: session
description: session API
name: find
description: find API
name: alert
description: alert API
name: resources
description: resources API
name: subscribers
description: subscribers API
name: status
description: status API
name: get_log_report
description: log report
paths:
# session
/session/create_session/{requestor_Entity}/{requestor_Role}/:
post:
tags:
session
summary: create a new session
operationId: createSession
parameters:
name: requestor_Entity
in: path
required: true
schema:
type: string
name: requestor_Role
in: path
required: true
schema:
type: string
requestBody:
content:
'json':
schema:
$ref: '#/components/schemas/sessionconfig'
responses:
200:
description: success
content:
application/json:
schema:
type: string
example: "4524458935"