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:
Outreach
Registration
Data Verification
Eligibility Determination
Enrollment
Payment
Ongoing case management
Ongoing M&E
Updating
While working on detailed process for each of this steps it’s important to have in mind:
What information will be required later on in the process
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:
Payment details
Consent for processing of personal data during program
Beneficiary data regarding eligibility
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]:
Data inputs
What data will be required to determine data output and post conditions .
Actors
What are actors taking part in particular steps?
Data output
What data will be required by future steps and post conditions?
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:
Description
Key Digital Functionalities
Cross Cutting Functionalities
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.
Step 8. Review
Step 9. Adjustments