Based on GovStack Building Block Cookbook

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:

Open

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:

Open

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.

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)

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:

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:

  license:

  version: 1.0.0

externalDocs:

servers: [

    {

      "description": "Scheduler BB Security server"

tags:

• name: session

• description: session  API

• name: find

• name: alert

• name: resources

• name: subscribers

• name: status

• name: get_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:

      responses:

        200:

            application/json:

              schema:

                type: string

                example: "4524458935"

                description: ID of created session

        '405':

        '403':

        default:

Cross cutting requirements:

The BB group can, after studying the Govstack architecture and security guidelines documents, can identify any additions or deviations from the recommended security and architectural applicable to this BB. Such deviations shall be noted with due reference to relevant sections o f architecture and security guidelines documents and justification for such deviations / additions / deletions if any.

Other components of specification documentation: Taking notes of other important elements of the specifications, the BB groups will enter key decisions taken with justifications, include key references to other published standards and best practices and describe or link to description of terminology used in the bb specifications. The specifications will also make additional recommendations as various modalities incorporated inside the BB to achieve the same services with different level of infrastructural maturity of target demography. For example, Govstack payments building block clarifies requirements of alternate modalities for making payments, based on paper vouchers to institutional memberships, mobile money transfer to banking transactions.

Building Block API Testing

The APIs define the software interface on the surface of a building block. Associated with each API there are service request formats with a set of input parameters that trigger specific actions in a building block and a set of response parameters depending on how the building block processed the inputs to produce specific outputs. Infact the unit testing phase involves on the BB without any integration. Each test is design to check the API compliance with a specific service functionality such that given a specific inputs the response carries correct results from the BB. Initially instead of a real life BB implementation,  mock requestor and responder applications are built to emit appropriate data stubs for an api call and response. When run, the mocks emulate the BB’s expected behaviours and should hence provide exactly the same expected functional behaviour at its outputs as per specification. This qualifies the BB API is functionally compliant and syntactically correct with respect to the specification. If a functionally API compatible product replaces the mock responder, the requestor should get the same responses from that product as well, to qualify the target product is Govstack API compliant.

Building Block Integration testing:

Once an API is qualified as functional compatible to specifications and technical compatible t the interface definitions, the associated mock requestor and responder BB emulator applications can be registered as services into an information mediator.

Doing this will expose the API as a microservice discoverable and securely accessible from across the internet. In a typical situation, the requestor would be an application or a building block connecting to the internet through their own Information mediator as illustrated below:

The information mediator has specific protocol to register a new building block service provider BB into the system, publish such services to external consumers for discovery and access request, and subscribing of requestor BBs/apps to access the services through IM on demand. The requester and responder mocks/BBs will be following these steps to become available for service exchange through IM at specific endpoints through the internet. Once these are ensured, the requestor and responder are ready to run the same tests that were run in direct connection earlier, except that it will now run across request-response sequences through information mediator and internet and produce expected results. This test ensures compliance with Secure access of the BB services through internet from other apps/bbs. This step will help build up a stack of BB APIs that are guaranteed to be functionally compliant and accessible through internet.

Interoperability tests:

The next step would be to check if building block apis can be called from other building blocks (mocks or actual BBs). This assumes that both provider and requestor BBs are registered with Information mediator and are replacing the mocks with Govstack API spec compliant APIs or Adapters that transform native interfaces to Govstack compliant API requests and responses. For example, a third-party registration building block can work with another third party payment building block, as long as they are both Govstack compliant either directly or through respective adapters.

The BBs at this stage are guaranteed to send and received correct data expected in a service request and response stream between actual building blocks either directly or through respective API adapters Interoperability.

The first step (API testing) involves only the BB under test, the second step (Integration testing) involves the tested BB and IM BB, the third step (interoperability testing) involves testing the BB under test and is client BB connected through the IM and the fourth step (handshake testing) involves complete logical handshakes connected with service calls from request to completion of service. 

Handshake Testing :

Beyond the API interfaces, there are handshake protocols necessary between a caller and called party. For example upon requesting a service the requester may expect confirmation if the provider has accepted the request. The requestor may further query to know if the service is completed and obtain the results. The requestor may wait till service is completed or may proceed to other work expecting the servicer provider BB to proactively inform the requestor when service is completed.  There are some common underlying assumption that APIs are designed to carry out work asynchronously by default and may only by exception work in synchronous calls with due justification.

A synchronous call waits for a response while an asynchronous call does not. In Govstack architecture Async calls to any BB service are also expected to get back a synchronous token number in return to indicate that the request has been received or rejected, whereas the results of the gets pushed later along with token number to the requesting BB through a call back function exposed by the requestor BB. Alternately the requestor BB may query status giving the token number and get results if ready from the responding BB.

A third mechanism adopts the pub-sub model wherein, the service provider BB publishes results in its pubsub room and if requestor BB is a subscriber to that room, the pubsub will automatically push the message to the requester BB’s exposed status update endpoint.

All these mechanisms are useful in difference scenarios, and are to be tested for inter-BB communication. These mechanisms can be tested to make sure that beyond syntax and formats, the logical handshakes are performed properly.

The BB APIs that have passed all above tests are stacked as qualified for consumption in manifesting and demonstration of different use-case. The sandbox team can at this stage pick well defined usecases and develop demos using qualified BB APIs