Design Services

Identify Registries and Services

To identify the registries and other services, once needs to identify the common nouns and verbs. Broadly, nouns will translate to registries/services and verbs will translate to operations or APIs.
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 have called the activity "Pay Charges" instead of "Make Payment" - so this may require a few iterations.
Generalized Activity
Apply for Birth Certificate
Create Birth Certificate
Birth Certificate
Make Payment
Make Payment
Verify Application
Verify Birth Certificate
Birth Certificate
Approve Application
Approve Birth Certificate
Birth Certificate
Send Notification
Send Notification
Update Application
Update Birth Certificate
Birth Certificate
Download Certificate
Download Birth Certificate
Birth Certificate
Now transform the above Verb and Noun columns to the table below to identify first set of services and their operations.
Birth Certificate
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 the Workflow

Workflows can be configured in DIGIT using the Workflow Service. Workflows must be extracted from the swim lane diagrams and converted into sequence of states and specific activities a specific actor can perform on that state.
Workflows are a series of steps that moves a process from one state to another state through actions performed by different kind of Actors - Humans, Machines, Time based events etc. to achieve a goal like onboarding an employee, or approve an application or grant a resource etc.
DIGIT's workflow service is a simple state machine.
The workflow configuration can be used by any module which performs a sequence of operations on an application/Entity. It can be used to simulate and track processes in organisations to make it more efficient too and increase accountability.
The below table illustrates the process:
What is the State of the Application?
Which Role can Act?
What Actions can the Role Take?
Awaiting Verification
Mark Verified Ask for Clarification
Awaiting Clarification
Assign Approver
Awaiting Approval
Approve Reject
Workflow Table1
The above table needs to be translated into Workflow and MDMS service configurations.
At a high level, a workflow consists of:
  1. 1.
  2. 2.
    Actions that can be taken on each state
  3. 3.
    Roles that can perform these actions.
Below is a sample Workflow JSON template that can be customised.
Sample workflow JSON
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 this file below. This can be used as a customisable template.

Identify reference data

DIGIT comes with a MDMS (Master Data Management Service) that holds master data for a module.
MDMS is used to store data that is unchanging or slow changing. Examples of MDMS data are administrative hierarchies, revenue hierarchies, property types, trade license types etc.. Data that changes frequently and requires exposing CRUD APIs go into the database as registries.
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.
Master data can be state level or city level. State-level configurations go into master-config.json under the tenant folder. Set the isStateLevel flag is 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.
The folder names and the file names for the custom, module related master data can be defined as per the user's needs. What has to remain the same is the module names and master names that are defined inside the JSON. These have to match with the master-config.json also where applicable. If there are mismatches here, MDMS will not find the required data.
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 co-ordinates and other tenant information to be configured here.
Sample tenant information can be referred here.

Extract roles and access control MDMS configuration

A part of 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 the role-action mapping.
Note that this is only a part of MDMS configuration. Other configuration that the module requires has to be setup in MDMS separately.

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:
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:
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 mappings:

Add the role action mapping in a file called roleactions.json under the following path:
"rolecode": "EMPLOYEE",
"actionid": {{ACTION_ID}},
"actioncode": "",
"tenantId": "{{tenantId}}"

Detailed Design for Registries and Services

Detailed Design consists of
  1. 1.
    External Service Interface
  2. 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 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 consist 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 and 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 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 language then Localization Service will be required.
All DIGIT services pushes 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 large volume of writes and also provides ability for the Indexer to enrich the data and push it to the Elastic Search for Decision Support Service (DSS) to display dashboard. In addition, all changes to data is signed and logged into a 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 the SMS, Email and App Notification Service.
Telemetry Service provides ability to track user activities to identify drop offs. However, this requires user interface developer to inject the telemetry instrumentation at appropriate points in code e.g. when users starts a new application, when user moves to a new section, when saves the application, when user makes a payment etc.

Develop Sequence Diagrams

Now that we have identified the list of services, develop the sequence diagrams which shows how all the services talk to each other to enact a use case or user story. A sequence diagram is illustrated below.
Typical Sequence Diagram for DIGIT
Creative Commons License
All content on this website by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.
All content on this page by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.