Don’t forget to subscribe to our to stay up-to-date.
Introduction to rules mapping
This video covers an introduction to rules analysis and mapping, and the GovCMS and Salsa Rules as Code process.
Video sections
0:00 – 0:58 - Introduction
0:59 – 1:48 - Rules mapping overview
1:49 – 3:15 - Rules statements
3:16 – 3:55 - Eligibility logic
3:56 – 4:42 - Questions and journey mapping
4:43 - 5:23 – Mapping in a spreadsheet
5:24 - 6:35 - Test cases
6:36 - 6:44 - Closing
Resource links
Transcript
Hi, and welcome to the third video in our five-part series about Rules as Code. My name is Phillipa Martin, and I'm the Rules as Code lead at Salsa Digital, an open-source digital innovation company based in Melbourne, Australia. Today, I'm here to talk to you about Rules as Code or RaC for short, on behalf of GovCMS. GovCMS is a whole-of-government content management system and web hosting platform built by government for government.
With a background in content and an interest in the law, I started Rules as Code in January 2022, working with a larger project team to convert the New Zealand Social Security Act into an interactive rules as code experience for New Zealand citizens. Since then, I've continued working in the Rules as Code space as a business analyst, analysing and mapping legislation and other rules while also focusing on user journeys.
This third video in our Rules as Code series focuses on the process of mapping legislation ready for coding. There are many different ways you could potentially analyse and map rules ready for coding into OpenFisca and in our case a frontend build like Drupal. Today I'm going to talk to you about the process we follow. The rules mapping process could be done by subject matter experts or business analysts. As a business analyst, I like to start by writing rule statements which are plain English statements of the rules or legislation. Next, we look at the logic and map either as eligibility logic or user journey flow. Then we write the questions needed to get inputs to check against the rules or legislation. We then map this into a spreadsheet and finally write test cases. In this video, I'll give you a high-level overview and examples of each of these stages.
Rule statements provide a plain English version of legislation or rules. They're used to formulate questions, help map the logic, and can be also used for results pages. Rule statements are also a way to validate and cross-check the logic mapping that we do in the next step. Importantly, we also like to publish the rule statements so users have a clear understanding of what the rules actually are. This helps to make the legislation or rules more accessible and transparent for all.
Let's look at a few examples. This example is around Govc CMS eligibility. What organisations can build a website on the GovCMS platform? Two rule statements are: "All state and territory agencies are eligible for a GovCMS site." AND "All organisations, entities that report to their state or territory minister or a federal minister are eligible for a GovCMS website." In this example from the New Zealand Social Security Act, the rule statement outlines the key eligibility criteria for the supported living payment: "A person can get supported living payment if they're 16 or over, meet the residential requirements, are totally blind or have restricted work capacity, and their injury is not self-inflicted. In this case, residential requirements and restricted work capacity are defined elsewhere.
Our next step is to look at the journey flow or eligibility logic. While you can use a variety of tools to do this process, we use Miro. We can copy and paste the legislation in Miro then create the visual logic mapping next to it. On-screen is the eligibility mapping for the supported living payment from the example just provided. You can see that we have “a person is eligible if” and then we have the conditions around age, residential requirement, etc. Also note that we can also put the legislative references next to the logic. This is included in OpenFisca and helps with traceability and makes it easier to update OpenFisca when legislation changes.
Once all the eligibility logic is mapped, we work out what questions we need to ask. On-screen, you can see some of the sample questions for supported living payment. Next, we look at journey mapping, also using Miro. On the left, we have the first question: What type of organisation are you? Below that is one of the options, Australian government department or entity. And the other options sit below this one on the Miro board. To the right, we have the next question which isn't really legible in this screenshot. It provides the options for Australian government departments. Finally, this leads us to eligibility. For example, eligible equals true in the top scenario. You'll also notice in this example, we've included the variables in the Miro board.
The next and second last step we follow is to map the questions into a spreadsheet. This is our template. We use this centralised spreadsheet to map the OpenFisca variables and the frontend questions. So the one source can be used by both dev teams. This avoids any confusion and all are working off the one source of truth. In this example, you can see we have columns for the question, a help tip, OpenFisca variable name, the definition period, the variable type, the OpenFisca value, the default value, the Drupal type (e.g. radio button, drop down, etc.), the Drupal value, and the path where the user goes next.
The last step is to write test cases. We write these in the spreadsheet in a separate tab. On screen you can see some example test cases from one of our recent GovCMS Rules as Code samples. The input shows what the OpenFisca variables will be in the test case and the expected output. The OpenFisca developer uses these test cases when coding and then we use them again during our final quality assurance QA. The first row on screen shows the inputs of an Australian government department or entity and they're on the PGPA flip chart. The expected output is to be eligible for a GovCMS website. Moving down, we have several different combinations of inputs and the expected results.
And that's the analysis and mapping complete. The developers use a Miro and spreadsheet to code in OpenFisca. And then finally, once all the OpenFisca code is prepared, the webform is created in Drupal. While the devs are working on the build, we also prepare the results content that's displayed for the user. This content is created in a separate document and then linked to the spreadsheet for the individual results so the developers have easy access.
That's it for this video and we look forward to seeing you in our next video about OpenFisca. Thank you.