Welcome to the second in our series of blogs documenting the process of creating a Rules As Code repository for New Zealand as part of the Digital Aotearoa Collective (DAC) initiative.
How to turn legislation into Rules as Code
Of course, there are many different methods you could use to turn existing legislation into code. However, the purpose of this series of blogs is to document the process we’re using in the DAC project.
Starting with Miro
Pia and her team had already set up a great system using a Miro board to start the codifying process. The Miro board is the source of truth for the planning stages. It’s a large board, with many different sections. One section is used to keep track of what needs to be done, what’s in progress and what’s ready to code.
Miro board
Most of the ‘to do’ items relate to New Zealand’s Social Security Act, however there are also some high-value service-based items such as applying for a passport, applying for citizenship and applying for a visa.
The DAC team had identified a first and second pass for each benefit.
The first pass — analysing the Act
In the first pass the goal is to identify:
- Eligibility criteria
- Relevant entities
- Eligibility logic
- Calculation logic
The Miro board is set up with ‘frames’ for each benefit, and screenshots of the relevant section from the Act on the left. Sticky notes are colour-coded to help visually differentiate different parameters.
We broke into groups of 2-3 people per group, with each group choosing a benefit and starting work on the first pass. The first benefit I was involved in was the supported living payment. This payment is designed for people who are totally blind or have restricted work capacity. It also covers carers looking after someone who would otherwise need institutional care.
Supported living payment
We literally read through the Act and pulled out eligibility criteria, including definitions if necessary.
For example, section 34:
Supported living payment: on ground of restricted work capacity or total blindness: requirements
A person is entitled to the supported living payment if the person—
- has restricted work capacity or is totally blind; and
- meets the residential requirement; and
- is aged 16 years or over.
In our first pass, this translates to the following sticky notes on the Miro board:
- The person (P)
- Age = 16 or over
- Meets residential requirement
- Totally blind OR Restricted work capacity
We use AND/OR connectors as required.
The frame also includes any relevant definitions (e.g. the definition of ‘restricted work capacity’ and ‘residential requirement’). If definitions are across more than one section of the Act, they can simply be copied into the payment type or cross-referenced.
Calculation logic
The first pass also looked at calculation logic and payment rates. To track the different payment types, Pia Andrews created a spreadsheet that pulled in the rates. As you can see from the screenshot below, the supported living payment is quite a complex one, with many variables determining the rate, plus the application of two different income tests.
Calculation logic
Income test calculations were set up on the Miro board, for example:
If income_total_weekly<160 then benefit = <rate> (regardless of income test)
if 250 > income_total_weekly > 160 then if income_test_1, benefit = <rate> - ((income_total_weekly - 160) * 0.15)
if income_total_weekly > 250 then if income_test_1, benefit = <rate> - ((income_total_weekly - 250) * 0.35) - ((250-160) * 0.15)
The second pass — user variables and test cases
The second pass looks at translating entities, legislative requirements, and eligibility criteria into user variables. For example:
- p_age
- p_residential_status
- beneficiary_total_blindness
- p_restricted_work_capacity
The test cases look at both eligibility criteria and rate calculations. For example:
- P=17yro
- Meets residential requirement
- Is totally blind
- And not self-inflicted
- Is employed
- Earns $20K/year (384.61 per week)
- Is single
Using this test case, we then worked out the payment.
Payment:
- total_income * 0.25 = $96.15/week (384.61+96.15=480.76, which is under the maximum allowed of 524.65)
This scenario and payment will then be checked against the code once it’s set up.
Next steps
With three groups in total and 17 social security payments to analyse (and then code), our first and second passes on the Miro board do take time. As we finish one benefit, we move onto the next. Given all team members are working on this part time, setting up each benefit on the Miro board is going to take several weeks.
In our next blog we'll look at our first steps towards coding!