Webform Entity Handler Configuration

Why we need this ?

Webform submissions i.e. answers to questionnaires that patients provide are stored in a separate manner as compared to usual content in Drupal. The model used one where each element i.e. question on the form is stored separately and data for the element is stored in the same coloumn (EVA - Entity Value Attribute model). As a result there is an important problem for our use case.

⚠️ It is important to note that for some reason decimal fields in content do not work with this handler. The most reliable way to storing numerical data with this is to use a text field in the content type as it stores the numbers as such in the field.

Usually patients will be asked to answer questionnaires and different disease groups have different questions that need to be asked. At the same time there are common questions also. As an example, for a patient with Cervical cancer we can have two questionnaires: EORTC QLQ C30 and EORTC CX24. Another patient has a head neck cancer for whom the questionnaires required are EORTC QLQ C30 and EORTC HN35. From the patients perspective, we will need to show the two Questionnaires seperately and therefore the patient with Cervical cancer will see a different questionnaire with questions from both EORTC QLQ C30 and EORTC CX24 modules whilst the patient with Head Neck Cancer will see another questionnaire with EORTC QLQ C30 and EORTC HN35 modules. From the perspective of the healthcare worker scoring of the EORTC QLQ C30 questionnaire will be same for both patients. However given the design of the webform module we can infer that we will need to create duplicate dashboards for the two groups of patients as the same questions will be on two seperate questionnaire. This is not only redundant but difficult to maintain in the long run. To overcome this issue we rely on the Webform Entity Handler Module. This allows us to map the webform submission to an entity - in this case content type. This for the above example, there will be three content types:

1. EORTC QLQ C30
2. EORTC CX24
3. EORTC HN35

The configuration of the module will be such that for both sets of patients, the responses to the EORTC QLQ C30 questionnaire will be used to create a content called EORTC QLQ C30. In other words we ensure data from two questionnaires go into the same data structure. This allows us to create a dashboard for the QLQ C30 data which will show results of both groups of patients. So from the perspective of the healthcare worker they will need to see a single page.

The following cartoon explains the concept.

Configuration

Entity Handlers are configured in each individual webform. To do so open the webform for which this has to be enabled. Go to settings > Emails/Handlers tab.

Click on the Add Handler Button and Choose Entity as the Handler

A new form will open called "Add Entity Handler"

1. Enter the title and a description
2. Then in the Entity settings click on Create a new entity
3. Choose Entity Type as Content as in the dropdown though other entities can be created in this manner.
4. Once you click this you will a section will become visible which will allow you to map webform submission values to the respective content field.
5. It is important the the node title is set. You can choose to set this to any value but we generally set it to the UUID of the webform submission.
6. Next we map the questions fields to the respective content fields.
7. Once done click on Save button. Note that there are a bunch of additional properties that can be set up but these can be kept to the default

The output of the entire process will be that once a questionnaire is submitted, the handler will automatically create a new entity (in the above workflow a content) with the values chosen from the form. Multiple handlers can be created in this manner such that if there is a mix of questions from multiple questionnaires in a single form then respective questionnaire data can be pointed to the correct entity.

To illustrate this with an example suppose you have a questionnaire with the four questions : 2 questions from the EORTC QLQ C30 questionnaire and 2 from the BR 23 questionniare then create 2 handlers. The first handler maps the responses of the first 2 questions to the EORTC QLQ C30 questionnaire content type and the second handler will map the next 2 questions to the EORTC BR 23 questionnaire.

Note

Alternative ways for acheiving this:

1. Webform Content Creator Module : This module is available in the installation. As compared the the Webform Entity Handler the mechanism is a bit different and it provides a seperate configuration page. Webform Entity Handler on the other hand provides a Webform Handler which is generally easier to work with. Also as it is a Webform Handler the configuration gets exported also along with the webform. Copying the webform thus copies the handler also.
2. Webform Query : An alternative approach where the webform submission table is queried. However this module is not under active development and not having security advisory coverage hence not considered for this project.