1. Checkbox
  2. Knowledge Base
  3. Studio Blocks
  4. Function Blocks

MERGE Block

SKIP AHEAD TO
What does a MERGE block do?
What are some common use cases for MERGE blocks?
How to create List variables in a MERGE block
What are value types in MERGE blocks?
Why would I want to merge in the label?
How to reference MERGE Lists
(Beginner) Use Case: Risk Scoring

 

 

 


Note: It is recommended you read about LIST variable functionality before reading this article in order to fully maximise your understanding of the MERGE functionality.

What does a MERGE block do? 

MERGE blocks collate end user inputs from inside an Assessment into a List variable. List variables created this way can also be referenced throughout the App or inside documents.

Being a function block (similar to COMP Table or FILTER blocks), a MERGE block does not display a page to the end user. It instead processes the end user's inputs in the background to create a List variable.

Wiki_-_MERGE_Block_V2__1__2021-01-05_14-22-31.png

 

What are some common use cases for MERGE blocks?

A common and simple use case for the MERGE block includes the collation of personal details of the end user (e.g., full name, age, occupation etc) which can be referenced later in the App or inside the generated document.

For more complex use cases, MERGE blocks are often used in conjunction with the COMP Table block. A common use case explained later in this article is a risk scoring.

 

How to create List variables in a MERGE block

To create a collated List variable with a MERGE block:

  1. Identify the variable names for the inputs you want to reference.

    For example, the FullName and Age of the end user.

    Wiki_-_MERGE_Block_V2__1__2021-01-05_14-23-35.png


  2. In the Property Editor of the MERGE block, click "+ Add output sets" to create a List variable inside the MERGE block.

    Wiki_-_MERGE_Block_V2__1__2021-01-05_14-24-27.png


  3. Click "+ Add variable" until there is a "Variable REF" field for each variable that you aim to collate into a List variable and enter the variable names into each "Variable REF" field.

    For example, to collate FullName and Age, you will need to add 2 "Variable REF" fields as shown in the screenshot below

    Note: Your list will print out variables in the same order that you add them to the MERGE block and will ignore any uninitialised variables.

    v1.22_Release_Notes_and_Wiki_2021-02-11_18-43-36.png

  1. [Optional] Enter a condition to any variable in your List created in the MERGE block. If the condition is not met, the variable will be excluded from the collated List variable.

    For example, if the Age is not greater than 25, only the FullName of the end user will appear in the List variable when referenced.

    v1.22_Release_Notes_and_Wiki_2021-02-11_18-44-22.png

  2. [Optional] Click "+ Add output sets" to create multiple collated Lists in one MERGE block. Each output set represents one collated List variable.

    Note: There is no limit to how many Lists a MERGE block can hold, but we recommend having no more than 2 – 3 lists per MERGE block for ease-of-use.

 

What are value types in MERGE blocks?

A variable REF allows you to select between two different “types” for each variable you merge into a List:

  1. Merging a Value: Pulls the end user response to a variable during run time into the List.
  2. Merging a Label: Pulls the variable’s label value (the grey guidance text on a field) into the list.

To understand this better, let’s look at the example variable fullName, set up as follows on a FORM block:

Wiki_-_MERGE_Block_V2__1__2021-01-05_14-27-55.png

If we set up our variable REF to merge the VALUE, and during run time the user entered ‘John Smith’ as their full name, the MERGE block would add ‘John Smith’ to the list.

If we set up our variable REF to merge in the LABEL, during run time, the MERGE block would add ‘Input text’ to the list.

 

Why would I want to merge in the label?

Most of the time, merging in Value is what we want to do, because it’s the user response to the TXT field, radio, dropdown etc that we care about.

The exception to this rule is Checkboxes. The value of a Checkbox is either TRUE (when ticked by the user) or FALSE (when not ticked), so if we merge in the value, our list will show the word “TRUE” or “FALSE”. Most of the time, this isn’t helpful (because we don’t know what is TRUE or FALSE), so we merge in the Label value of the Checkbox instead.

Building on the earlier example, we can add in a Checkbox for the user to confirm that they’ve spelt their name correctly:

Wiki_-_MERGE_Block_V2__1__2021-01-05_14-28-43.png

When we want to merge this into a list, we set up our variable REF as follows:

Note: The condition included is optional, but commonly used so that the Checkbox is only merged into the list if the user has ticked it.

Wiki_-_MERGE_Block_V2__1__2021-01-05_14-29-26.png

 

How to reference MERGE Lists

To reference a collated List:

  1. Identify the variable name for the Output List, either in the Property Editor of the corresponding MERGE block or by clicking "Show Logic" in the toolbar of the Studio.

    v1.22_Release_Notes_and_Wiki_2021-02-11_18-45-12.png

    Note: Output Lists in the MERGE block can be renamed by editing its text field.

    v1.22_Release_Notes_and_Wiki_2021-02-11_18-45-58.png

  2. In sections of your App following the said MERGE block, reference the List(s) in double curly braces.

    Wiki_-_MERGE_Block_V2__1__2021-01-05_14-31-17.png

 

What will the end user see?

Referring to the FullName and Age example above, if you did not add a condition or if the age given was greater than or equal to 25 (i.e. if the condition was met), your end user will see the following:

Inside an Assessment:

Wiki_-_MERGE_Block_V2__1__2021-01-05_14-31-55.png

 

Inside a rich style document:

Learn more about printing list variables in a rich style document.


Wiki_-_MERGE_Block_V2__1__2021-01-05_14-32-27.png


If the age given was less than 25 (i.e., if the condition was not met), the "Age" variable will be excluded from the List and your end user will see the following:

Inside an Assessment:

Wiki_-_MERGE_Block_V2__1__2021-01-05_14-33-17.png


Inside a rich style document:

Learn more about printing list variables in a rich style document.


Wiki_-_MERGE_Block_V2__1__2021-01-05_14-34-05.png

 

(Beginner) Use Case: Risk Scoring

Disclaimer: It is recommended that you understand the capabilities of a COMP Table block before reading this use case. Don't know how the COMP Table block works? Learn more here.

Risk scoring is commonly used in apps where quantitative evaluation of an end user’s responses is required (e.g. surveys, risk assessments etc.)

Example Scenario:

If your user is selecting numerical values you can use the MERGE block to pull all the selected values into a List, then a COMP Table block can be used to sum the List and get a total risk score. Here, no conditions are used on MERGE variables.

Example App Setup:

The App design for this example use case should look similar to the screenshot below:

Wiki_-_MERGE_Block_V2__1__2021-01-05_14-36-30.png

  1. Firstly, the end user will select the numerical values to score each risk in a FORM page and click “NEXT”

    Wiki_-_MERGE_Block_V2__1__2021-01-05_14-37-38.png


  2. The total risk score will then be calculated in the background and displayed at the end of the Assessment

    Wiki_-_MERGE_Block_V2__1__2021-01-05_14-38-09.png

How this works:

The key to this system working is the interaction between the MERGE and COMP Table blocks.

  1. The MERGE block collates all numerical values for each risk from the initial FORM block into a single List (In this example, LIST5)

    Note: Output Lists in the MERGE block can be renamed by editing its text field.

    v1.22_Release_Notes_and_Wiki_2021-02-11_18-47-04.png


  2. Inside the COMP table block, the List created in the MERGE block (I.e., LIST5) will be referenced in a cell that will be used to calculate the total risk score using the “=sum()” syntax. See screenshot below

    Wiki_-_MERGE_Block_V2__1__2021-01-05_14-39-25.png


  3. Finally, the cell with the calculated total risk score in the COMP Table block will now be referenced to be displayed to the end user once they have finished the Assessment. See screenshot below

    Wiki_-_MERGE_Block_V2__1__2021-01-05_14-39-54.png