Guideline for writing Use Case steps

Based on USCT-1 Registration  and Use Case Template.

Template

Use case Template provides overview of what information has to be provided by the use case. 

Template Components 

Step - Name of the use case step. 

Preconditions - List of conditions that have to be met to execute the process. Examples:

  • Beneficiary has to be enrolled to social program to receive payments; 

  • Claim has to be issued in order to get reimbursement; 

Data inputs - What pieces of information are used during normal course of use case actions. Could be provided by one of the actors or pulled from the system. Examples: 

  • Beneficiary Functional ID 

  • Health Facility Name 

  • Government Program Bank Account

Actors - entities involved in the course of use case actions, can be either physical (beneficiary, data scientist, social worker), legal (agency, ministry, organization), system (registry, building block). All relevant building blocks should be listed as system actors.  

Normal Course - expected flow of actions. Should be aggregated with steps. Each step should be explained using the Gherkin scenario and point to a particular Building Block’s endpoint if possible (note: some of the building blocks are codeless). 

Alternative course - steps that also fulfill the use case however are different from normal ones. Could be actions executed if some pieces of information are missing. For example: normal course payment process would assume that the beneficiary has a bank account to which the transfer will be made. However if there’s no bank account, alternative course of action could assume utilization of mobile payments. 

Data output - what information is available after steps were executed. This could be either data provided to some of the actors at the end of the process or data that was put in the ecosystem and is available. Example: for registration use case data output would be potential beneficiary entry in the digital registry. 

Post-conditions - indicators of the success, criterias that have to be fulfilled as a result of the normal/alternative course steps. Examples: registered applicants can be enrolled in the social program. Insuree with added policy can receive medical treatment for services that are in scope of policy.

Exceptions - anticipated events or conditions that may arise during the use case steps and affect the success of the operation.

 Related BB - list of building blocks taking part in the use case flow. 

Sequence diagram - visual representation of normal course steps. 

Approach for creating use case step from scratch 

Step 1. Gather information

This step might seem trivial, however it’s still mentioned as it’s important to have everything in one place. As for the USCT most crucial materials were: 

Step 2. Understanding Requirements

Another trivial step, however it’s the most important one. For USCT, the starting point is a document on the Figma which gives consecutive steps for the use case: 

  1. Outreach 

  2. Registration 

  3. Data Verification 

  4. Eligibility Determination 

  5. Enrollment 

  6. Payment 

  7. Ongoing case management 

  8. Ongoing M&E

  9. Updating 

While working on detailed process for each of this steps it’s important to have in mind: 

  1. What information will be required later on in the process 

  2. What information from previous steps can (and should) be utilized

For example in the registration step we know that latter on following beneficiary data will be required: 

  1. Payment details 

  2. Consent for processing of personal data during program 

  3. Beneficiary data regarding eligibility

  4. Confirmed identity of potential beneficiary

It is also good to define Post-conditions of the whole use case. 

Step 3. Understanding Requirements of single Step

Workflow for each step should also be understandable, at least on the abstract level. For the registration step in USCT there are 3 workflows with 3 corresponding reasonings:

WORKFLOW 

REASONING 

Data collection and reporting

Capture interview response and worker observations during registration process 

[Gather information required later on in the process]

Identification and registration 

Enable permissions for beneficiary activities in the SIRS (Social Registry information System) and potentially track households during interview process [Fill consent, associate beneficiary from national registry with program actor]

Client Case Management 

Create beneficiary user record [Potential beneficiary from national registry doesn’t have all required information a priori, in SIRS application they exist as cases] 

 

After analyzing the requirements we should have initial definitions for following use case sections [For use case step]: 

  1. Data inputs

What data will be required to determine data output and post conditions .

  1. Actors

What are actors taking part in particular steps?

  1. Data output

What data will be required by future steps and post conditions?

  1. Post-conditions

Retrospectively, what has to be achieved in the following step for remaining steps to succeed and in process to achieve use case goal. 

 Step 4. Identify BBs relevant for the Use Case Step 

Define core stages of the use case step based on the workflows. To finish this step general domain knowledge and experience from other projects should be sufficient. In case of doubts, to ascertain the correct practices, missing information, it is a good idea to review how a given process looks in the applications proposed as building block candidates and look into literature explaining some steps (e.g. government guidelines for beneficiary registration). It is important not to copy 1:1 solution from a particular platform as those use cases should be generic / reusable as possible. 

This should result in gherkin features & scenarios for the normal (and alternative) courses.  

Step 5. Identify building blocks used in step stages

To finish this step overall knowledge of all defined building blocks is required. It would be optimal to familiarize with the each BB documentation chapters:

  1. Description

  2. Key Digital Functionalities 

  3. Cross Cutting Functionalities

  4. Internal Workflows 

to have a good understanding of BB usage before describing the use case in more detail. 

Step 6. Align generic steps with functionalities provided by BBs

The nomenclature in point 4 should be adapted to the specific language of Building Blocks. Endpoints usage should be added. Any process-related activities for the overall flow should be aligned with the internal workflow of the building block if possible (e.g. authentication, consent, fetching information about user). 

Besides courses, it is also required to make adjustments in the inputs, actors and conditions to make alignments with data expected by the BBs (Data Structures chapter). 

Endpoints for all steps should be identified during this step. 

 

Part Of Use Case Step

Without alignment

Alignment of definitions with BB

Step name 

Applicant logs into SIRS application.

 

 

 

    

 

Applicant is authenticated. Requires ID [Identity BB]

Scenario 

Feature: Log into SIRS App

Scenario: Applicant logs into SIRS application using credentials.

  Given: Applicant has been registered and have credentials for general purpose authentication platform (e.g. Electronic Platform for Public Administration Services)

And SIRS APP can authorize applicant using Electronic Platform for Public Administration Services System

  When: Applicant enters data required for authentication

  Then: The authenticated applicant gains access to the system. 

 

Feature: Get authentication token

Scenario: Applicant use credentials to get token

  Given: Applicant has been registered in Foundational ID System

And Registration App is connected to Registry BB

  When: Applicant enters data required for authentication

  Then: The Identity BB returns Auth Token and Social ID

Endpoints

/login

/getApplicatnDetails

/authorize/data/{registryname}/{versionnumber}/exists

/data/{registryname}/{versionnumber}/read

Feature without alignment was loosely based on ePUAP authentication. It shows the process of logging into a system using an external authentication platform. However, it is far from the standards set by the definition coming from building blocks description. It is also not generic and has low re-usability in terms of other types of registration. Endpoints have no relation to the definitions derived from the specification.

Close cooperation with domain experts responsible for creating specific building blocks is most important during this step. 

Once all the key points of the normal course are defined, more attention can be paid to potential errors and risks that may affect this course and, as a result, block the fulfillment of post conditions.

Step 7. Create sequence diagram

It should correspond to the steps defined so far in the application. A sequence diagram can be defined using the Mermaid UML tool.  

Example diagram

Step 8. Review 

Step 9. Adjustments