Welcome to the fifth 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.
After the rules mapping (see our rules mapping blog for more information) we broke into two working streams:
Salsa’s OpenFisca Drupal module brought the two above streams together at a crucial stage. As part of the Cardana grant the project received, stage 1 of the service/site needed to be live around the end of November. Six weeks before that deadline, the broader DAC team came to the conclusion that the timeframes and resources meant we couldn’t build the custom website and user experience that had originally been envisioned. Instead, (with Drupal) was chosen for a fast build. CivicTheme is a design system and Drupal theme that ships with the ability for users to easily apply their own colour palette and branding.
An important element of this approach was building a custom webform that leveraged Salsa’s work for a GovCMS RaC proof of concept.
The Drupal/OpenFisca work was broken into the following stages:
- Content and mapping for questions
- Customising the OpenFisca Drupal module
- Building the webform
- Theming the webform
- Creating custom blocks for the results pages
Content and mapping for questions
One of the most important content elements was the questions that would appear on the My story . These needed to be mapped to OpenFisca but also ensure ALL eligibility criteria and calculation logic was included. To streamline the eligibility and calculation process for various benefits, we used a Google sheet to list all the necessary criteria and logic. This allowed us to identify which criteria could be merged into common questions.
To further organise this information, we created a table that included the minimum required questions for eligibility and calculation, as well as additional information such as help text, conditional visibility logic, business logic, and the mapping to the OpenFisca system. This table served as a valuable tool in simplifying the eligibility and calculation process and ensuring that all necessary information was easily accessible.
Customising the OpenFisca Drupal module
To fully meet the requirements of the My story webform, the OpenFisca Drupal module Salsa had created for the GovCMS PoC needed to be customised. These enhancements and features were necessary to ensure the webform functioned as intended.
One of the key customisations was the dynamic creation of multiple OpenFisca entities and the retrieval of the correct date periods to be set for the OpenFisca variables in the payload sent to the OpenFisca system. This was crucial to accurately calculate the benefits and ensure that the correct information was being used in the calculations.
Another necessary customisation was the dynamic parsing of the results from the OpenFisca response. This allowed us to extract specific fields and use them to set redirect rules and conditionally show certain block sections on the results page. These blocks showed what benefits the user was eligible for (if any) and the amount of money they should expect.
To work around the limitations of the Drupal webform, Javascript and CSS were added to the webform to handle specific custom business logic required in the OpenFisca mappings. This allowed us to customise the webform further and ensure that it could accurately and efficiently manage the project's specific needs.
Building the webform
The webform for the was built using the OpenFisca Drupal webform module. We used the Figma design and the content and mapping info from the Google sheet to create each question and map it to the correct OpenFisca variable.
The webform consists of various question types, including dropdowns and number input fields, each with defined options, default values, and help tooltips linked to the corresponding OpenFisca variable.
Some questions needed to be hardcoded, which was achieved by creating hidden elements on the form that were passed on to the OpenFisca system.
Custom Javascript and CSS were added to the webform to work around certain limitations of the Drupal webform module. This allowed us to implement specific functionalities and meet the requirements of the project, ensuring that the webform could accurately and efficiently handle the particular needs of the project.
Theming the webform
The webform also needed to be themed. The My story webform looks very different to a traditional webform. Salsa’s Drupal FE developer worked to theme the webform so it looked more like the designs. Key changes included:
- Spacing changes so the dropdowns and fields appeared in line with text
- The addition of custom help icons
- Updated styles that only apply to the webform
- Stacked form for mobile
- Extra fieldset styles
- Updated styles to wrap description elements onto the next row
- Adjusted width settings for suffixes according to breakpoints
Below is a screenshot that shows part of the final webform.
Creating custom blocks for the results pages
As part of the OpenFisca and Drupal solution, we had to think about how we could display the results and cherry-pick values from the results to be displayed in different sections. Salsa tech manager and Drupal tech lead Suchi Garg set up custom blocks in Drupal that include logic for when they should be displayed. Every benefit has two custom blocks that track to entitled=yes or entitled=no. If entitled=yes, the custom block includes code that inserts the dollar value from the OpenFisca calculation.
Next steps
With the alpha launch completed, the Digital Aotearoa Collective is now conducting user testing with advocacy groups and other end users. The goal is to continue the OpenFisca development to include the other social security payments. The webform will be expanded as necessary. The Collective is also planning to use more custom frontend theming work so that the My story page and profile pages can be displayed in line with the original vision.