Don’t forget to subscribe to our to stay up-to-date.
Introduction to the Webform OpenFisca Drupal module
This video provides an introduction to the Webform OpenFisca Drupal module. It shows you how to use the module to connect the webform to the OpenFisca API, how to map the webform fields to OpenFisca variables and how to set up results content that’s shown based on OpenFisca values.
Video sections
0:00 – 1:04 - Introduction
1:05 – 2:23 - Solution architecture, OpenFisca and Drupal
2:24 – 3:15 - Drupal integration
3:16 – 4:14 - Sample webform and results
4:15 – 4:46 - The webform handler
4:47 - 5:08 – Third-party settings
5:09 - 6:10 - Webform to OpenFisca mapping
6:11 - 7:15 - Branching and redirect rules (using the nodes)
7:16 - 7:49 - Contextual results content
7:50 - 8:06 - Closing
Resource links
Transcript
Hi, and welcome to the fifth video in our five-part series about Rules as Code. My name is Phillipa Martin, and I'm the rules as code lead at Selsa 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.
A quick introduction. With a background in content and an interest in the law, I started in 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 fifth video in our Rules as Code series focuses on the process of configuring the Drupal webform and results content.
But first, let's take a high-level look at the solution architecture in case you missed it from our fourth video on OpenFisca. Looking at this diagram, you can see that we start with legislation bottom right, which then gets coded into OpenFisca. From there, the OpenFisca API integrates with Drupal. We cover the Drupal part of this solution in this video. Users can interact with the rules via different user experiences such as websites, mobile apps, and voice devices.
Before we look at the Drupal module, I do want to address one issue that we often get asked about. Why OpenFisca and not Drupal? While we could have used Drupal to code the logic by creating a custom module, it's a square peg into a round hole. Drupal is not built for rules coding and complex logic. Drupal is built for content modelling and content management, and it's one of the best CMSs. On the other hand, OpenFisca is the most widely adopted free and open-source engine to write rules as code. The way OpenFisca is programmed, it makes the process faster and more efficient for our purposes. OpenFisca is a lightweight, modular, and scalable Python-based rules engine. OpenFisca was initially developed by the French Government in 2011 to codify the French social security benefits.
We use Drupal in our Rules as Code implementations to gather inputs from users and display the outputs results. We use two key elements webforms and nodes. With webforms, you can either create one webform for users to fill out or create a series of webforms as part of a user journey with questions grouped together logically on different pages, i.e. different webforms. You then map the webform fields to the OpenFisca fields which use the Drupal module and the OpenFisca API.
Next, we use nodes. In terms of nodes, we can use these to add the rules for the branching, defining where the user needs to be redirected to based on the response from the OpenFisca API. To explain this process in more detail, let's take a look at a sample webform. On-screen are two screenshots from one single webform. This is a webform for BenefitMe, a website that checks eligibility and payment rates for New Zealand Social Security benefits. As you can see, this is quite a long form and it also has some conditional fields. For example, if the user adds children into the dependent children field, some more fields show up so they can fill in more information about the children.
And this is the sample result. When the user fills out the form, all the responses are sent to the OpenFisca API and based on the responses, the results are shown. In this particular implementation, there is one result page with relevant blocks displayed on the page depending on the user's inputs. Each of the social security benefits has two content blocks one for if you are eligible for the benefit and one for when you are not eligible for the benefit. These blocks are shown/hidden on the page based on the response from the API.
Now let's look at the backend of the webform. The custom module we created extended the webforms. Using this module, we can connect the webform to the OpenFisca API, define the return variables we need, and also define which field in the webform maps to which input variable. First, we create a custom handler for the webform to interact with the OpenFisca API after form submission. You can see in this screenshot the name of the handler is OpenFisca Journey Handler.
Second, through our OpenFisca Drupal module, we can specify an OpenFisca endpoint. In this screen of the backend, we define the API endpoint and also define the return variables and the journey handler will use for this webform. We also need to define the keys for these return variables. Please note that these variables need to be fully qualified.
Next, we map the fields in the UI. You can see in this screenshot we have added a new field linked OpenFisca variable and the user can select the appropriate OpenFisca field, residential requirement in this example. Please note that in the same form we can also add the entity key and the entity role. When we save the form field, these values are actually reflected in the third-party settings as well. This shows the list of variables that can be mapped. This list is pulled from the OpenFisca API URL that we added earlier.
So basically, we extended the Drupal webforms to take the appropriate inputs from the user, which are then mapped to corresponding OpenFisca variables. Another thing to note when building the form is that all the return variables need to be added to the form as hidden fields and mapped correctly. OpenFisca expects these variables in the payload that Drupal sends.
Now the webform is built. The next step is to decide what to do with the responses we get from the API. This is where the nodes come into play. The branching rules or redirect rules nominate what pages should be shown based on the OpenFisca values. In the case of the BenefitMe webform, we needed to always go to a single page and there were not multiple steps of the journey. But if we have multiple forms, we can decide where to take the user based on responses from the API.
To make this also content editable, we created a content type and a few paragraph types so the branching can be defined by content creators. Of course, they need to know about the journey. Each rule was associated with a webform. This slide shows two very different rules from a COVID vaccination proof of concept. When the webform is submitted, based on the return values combined with these rules for the webform, the redirections take place. The simple version on the left shows two different redirects based on a true/false return. The screenshot on the right shows a slightly more complex redirect scenario.
The redirects as explained in the earlier slide might be to two different types of pages. It could be to the next step in the journey which means redirecting to the next web form or the redirect could be to a results page. This is where Drupal again becomes super useful. The content team can now create really relevant and contextual content. On the left is the BenefitMe results page with the relevant blocks displayed. On the right is a results page from a COVID proof of concept and the highlighted content in the response comes in from OpenFisca API calls as tokens.
Well, that's it from me for this fifth and final video in our series. We hope you've enjoyed learning more about Rules as Code and the implementation methods we're using for our Rules as Code projects, including the GovCMS Rules as Code sandpits. Thank you.