Overview

This document provides details on how to model the requirements for workflows, user stories and process indicators.

Steps - Model the Service Process Workflow

Given the requirements document from your business analyst, create a process model that looks as follows. It captures who (role) does what (activity) in what sequence to accomplish the outcome.

Start by identifying the users. The users could be citizens, vendors or employees. It is important to identify the roles the users are playing e.g. in the above the citizen is the "Applicant", Vendor is the "Verifier" and the Head of Department is the "Approver".

For each role draw a swim lane (grey horizontal bar in the above diagram) which contains all the activities (boxes and rhombus). The activities should ideally be expressed in a "Verb Noun" pattern e.g. pay charges, verify application and so on.

Elaborate Activities

Activities can be elaborated in two ways - as a user story or a use case. User Stories are an informal way of expressing what the user wants e.g. “As a [persona], I [want to], [so that].”

As an Applicant, I want to be able to provide enter the form as quickly as possible. I want to know the process and when the certificate will be available to me.

Use Case is a more formal way of capturing exact steps and alternate flows the user can follow e.g.

The Applicant logs into the system by entering the user name and password. The applicant then enters the following fields - child's name, mother's name, father's name, date of birth, and place of birth. All these fields are mandatory.

If you are following an agile process then the user story-based approach works fine. Agile also works well when you are not clear about the end outcome and want to iterate. However, if you are clear about what you want and also want to avoid too much back & forth communication between the product and engineering team during development with predictable outcomes then go with the use case-based approach.

Elaborate Process Performance Indicators

Identify the process performance indicators that an administrator may want to see to monitor and identify areas of improvement. For example, the administrator may want to see the following metrics and compare them over various time periods and administrative hierarchies.

1. Number of applications

2. Number of applications by status

3. Average time to deliver the applications

4. Average time by status

5. Average feedback

6. Number of complaints

7. Number of complaints by status

8. Average time to resolve complaints

9. Number of reopened complaints

This section provides step by step guide on how to design services on DIGIT. Design is a process of identifying the various layers of abstractions and also unbundling each layer into reusable components. We will start by modelling the requirements into high-level process workflow. This helps us identify the actors and sequence of activities. From this, we can extract the roles, services and workflows. Roles and workflows are configured into DIGIT. DIGIT also comes with many services that can be reused.

The DIGIT design process covers the steps outlined below:

Design Phase Outputs

The outputs of the design phase are listed below:

1. Process Workflows

2. User Stories

3. Service Specifications (YAML)

4. Service Detailed Design (Class & Database Design)

5. Sequence Diagrams for each user story

6. User Navigation Model

7. User Interface Design

8. Dashboard Design

9. Engineering Plan

Browse through the following checklists before commencing development.

• APIs dos and don’ts

• Security guidelines handbook

• Deployment checklist

• Performance checklist

Overview

This document provides the steps to identify the registries and other services. One needs to identify the common nouns and verbs. Broadly, nouns translate to registries/services and verbs translate to operations or APIs.

Steps - Identify Registries & Services

List the activities in a table and separate the nouns and the verbs as illustrated in the table below. The activities are generalized e.g. in verify application the word application refers to "Birth Certificate Application" hence generalize this to Verify Birth Certificate (we have dropped the term Application for brevity). Knowing the list of services available in DIGIT also helps - as you may call the activity "Pay Charges" instead of "Make Payment". This process may require a few iterations.

Now transform the above verb and noun columns to the table below to identify the first set of services and their operations.

So we have now identified 2 services Birth Certificate and Notification. When we get into detailing the sequence diagrams, it is quite possible that a few more services may emerge e.g. Birth Certificate Charge Calculator - assume charge calculation logic varies between different cities hence it makes sense to externalize this outside Birth Certificate Service.

Extract Workflows

Workflows can be configured in DIGIT using the Workflow Service. Workflows must be extracted from the swim lane diagrams and converted into a sequence of states and specific activities a specific actor can perform on that state.

The below table illustrates the process:

Workflow Table1

The above table needs to be translated into Workflow and MDMS service configurations.

At a high level, a workflow consists of:

1. States

2. Actions that can be taken in each state

3. Roles that can perform these actions.

Below is a sample workflow JSON template that can be customised.

The states in the first column of the table go into the states array in the workflow JSON. Each state has to be enumerated with the right attributes.

The actions in the third column of the table go into an actions JSON array inside each state object. These are the actions that can be taken on any given state to move it to another state. Each action object in the array has the following attributes:

• "action" - name of the action

• "nextState" - the state this action leads to

• "roles" - The roles that can take action on the state. These roles should be a subset of the roles in the second column of the table and need to map to the roles.json config in MDMS.

The workflow service needs to be configured with this JSON through a REST API call. See here for a hands-on example of how this is done. A sample workflow JSON with placeholders is defined in the file below. This can be used as a customisable template.

Identify Reference Data

DIGIT comes with an MDMS (Master Data Management Service) that holds master data for a module.

Reference data is configured in GitHub in the forked MDMS repository. Each tenant is created as a folder under the data folder. It is recommended that each module's reference data be stored under its own folder for easy reference.

The master data can be at the state level or city level. State-level configurations are stored in master-config.json under the tenant folder. Set the isStateLevel flag as true if these values cannot be overridden. Other subtenants can define their own modules and master names inside their sub-tenant folders.

Note that MDMS does not follow any inheritance rules between tenants and sub-tenants. i.e. a sub-tenant defining data inside their folders will NOT implicitly inherit master tenant data.

Example: https://github.com/egovernments/egov-mdms-data/blob/UAT/master-config.json

The tenancy is configured under the tenant folder. tenants.json configures a list of tenants including state-level and city-level tenants. This is used by the front-end login screen to show a list of tenants. Back-end will still work without an explicit tenants.json file. Logos, shape files, lat long coordinates and other tenant information are to be configured here.

Sample tenant information can be referred to here.

Extract Roles & Access Control MDMS Configuration

A part of the MDMS configuration for access control can be extracted from the table above. All new services need to provide access control for the URIs they expose via role action mappings. A module needs to define roles, actions (URIs) and role-action mapping.

Configure Roles

Create a file called roles.json. All the unique roles in the second column of the table need to go into the JSON in the following format below. This needs to be copied to the MDMS repository under the following path:

/{{mdms-repo}}/data/{{tenantId}}/ACCESSCONTROL-ROLES

For this sample application, we will have two roles: EMPLOYEE and CITIZEN.

// Roles JSON 
{[
{
      "code": "{{Role1}}", //Example: Employee
      "name": "{{Role1 Display Name}}",//Example: ULB Employee
      "description": "Default role for all employees"
},
{
      "code": "{{Role2}}",
      "name": "{{Role2 Display Name}}",
      "description": "End user citizen"
},
]
}

Configure Actions

Add the URIs from the API spec in a file called actions-test.json under the following path:

/{{mdms-repo}}/data/{{tenantId}}/ACCESSCONTROL-ACTIONS-TEST/

All URIs for the module need to be included here. The ACTION_ID needs to be unique and manually generated. Pick a unique ID series for your module.

{
      "id": {{ACTION_ID}}, //Needs to be a hand generated unique ID
      "name": "Create birth certificate",
      "url": "/birth-services/v1/_create",
      "parentModule": "",
      "displayName": "Create Birth certificate application",
      "orderNumber": 0,
      "enabled": false,
      "serviceCode": "birth-services",
      "code": "null",
      "path": ""
}

Configure Role-action Mapping

Add the role action mapping in a file called roleactions.json under the following path:

/{{mdms-repo}}/data/{{tenantId}}/ACCESSCONTROL-ROLEACTIONS/

{
      "rolecode": "EMPLOYEE",
      "actionid": {{ACTION_ID}},
      "actioncode": "",
      "tenantId": "{{tenantId}}"
    }

Detailed Design For Registries & Services

The detailed design consists of

1. External Service Interface

2. Internal Implementation

External Service Interface is expressed as in Open API Specification using tools like Swagger. You can open the sample Pet Store provided and modify it to your needs. Here is a sample API specification in YAML for the above example. This will require identifying the attributes of the Birth Certificate Object - this information will be available in the user stories or use cases. The YAML document thus created can be used to generate the initial service code as well as the service client.

Internal Implementation of the services consists of specifying the class diagram and database tables in which the state of the service i.e. Birth Certificate Object with be stored.

Identify DIGIT Reusable Registries & Services

To identify the list of services, one way is to go through the list of below questions.

If users need to be authenticated, then User Service will be required.

If there is a need to restrict certain functionalities to certain users, then Role Service will be required. When adding an Employee to the system, roles can be added giving them appropriate access.

If reference data e.g. Gender - Male, Female, Others etc. needs to be configured, then Master Data Management Service will be required.

If information needs to be presented to users in multiple languages then Localization Service will be required.

All DIGIT services push data into a Kafka queue which is then picked up by the Persister Service which then writes it to the database. This shields the database from a large volume of writes and also provides the ability for the Indexer to enrich the data and push it to the Elastic Search for Decision Support Service (DSS) to display the dashboard. In addition, all changes to data are signed and logged into an audit log by the Signed Audit Service. This ensures non-repudiation. File Store Service is used to store files - depending on the private or public cloud - it can be configured to use the appropriate underlying technologies.

All workflows can be configured in the Workflow Service.

Users and Employees can be notified using SMS, Email and App Notification Service.

Telemetry Service provides the ability to track user activities to identify drop-offs. However, this requires the user interface developer to inject the telemetry instrumentation at appropriate points in code e.g. when a user starts a new application, when a user moves to a new section, when the user saves the application, or when a user makes a payment etc.

Develop Sequence Diagrams

Now that we have identified the list of services, develop the sequence diagrams which show how all the services talk to each other to enact a use case or user story. A sequence diagram is illustrated below.

Overview

This page provides the details on designing the transactional user interface and performance dashboards.

Steps

Design Transactional User Interface

Identify the points different roles interact with the system from the process model.

DIGIT UI design guidelines are available here.

FIGMA designs using the above Guidelines are available here. Feel free to copy and modify as per your needs.

DIGIT UI Accelerators available in React and Flutter implement these Guidelines as reusable components and UI frameworks. The entire source code is open and available here.

Design Performance Dashboard

DIGIT Decision Support Dashboard (DSS) looks like below.

Each of the widgets corresponds to one service and that displays basic performance metrics for that service. This can be further drilled down to the below view for deeper analysis.

The performance metrics and dimensions identified of the service can be mapped to different available visualizations in DSS.