Mapping questions to fields

Customers often want questionnaires connected to other entity records. For example, existing record data can be the default answer to some questions. Or the other way around: some answers should be used to update related entity records. This is where data mapping comes in: In the questionnaire template, you define a connection between a question and a related entity field. When answering the questionnaire, the field value can be used as the default answer, or the answer can be saved to a record field at the end – or both.

A similar effect can be accomplished using rules. Data mapping is a lot simpler to set up.

Identify the mapped record

The app needs to know the record linked to a questionnaire. There are two options for indicating which record and field should be mapped to an answer.

• One of the simplest options is using the regarding record. This is the record from which the questionnaire was started. If your workflow assumes that you launch questionnaires from an entity form, for example, you go to an asset and start the inspection; this is the way to go.
• If you have a list of questionnaire templates directly on your home screen or start inspection differently, the regarding field is empty. Instead, you can add a lookup question to your questionnaire template and use the lookup target as the mapped record.
• If you want to use the questionnaire to create new records, use the lookup question. In question properties, set Allow create new to "Automatic". When answering such a questionnaire, users can select the option "Create new record" as the lookup target.

Set the mapping direction

Once you identify the record and field, you can choose the mapping direction. Essentially, you can:

• read data from the record to populate the answer on the questionnaire
• write data from the answer into the record field
• or both!

You can read the data only once, when the questionnaire is created, or repeatedly whenever you open an incomplete questionnaire.

You can save the data only once, when the questionnaire is completed, or repeatedly whenever you save an in-progress questionnaire.

Edit the questionnaire template

In the Questionnaire Designer, there are two ways to set up data mapping.

• Start from the question - and then select the related record and field. Use this option when the questionnaire template already exists, and you add limited data mapping capabilities (only a few mapped questions).
• Start from the related record - then select fields and create questions linked to the fields. Use this option to create multiple mapped questions at once.

In either case, start the Questionnaire Designer. Edit a questionnaire template and enable Data Mapping in the toolbar.

Add mapping to question

1. Click the link button to start the data mapping wizard.
   
2. Select which record should be linked to the question:
   • Regarding record (Record from which the questionnaire was started)
   • Record from a lookup question
3. For each entity, select the record that should be mapped.
4. Finally, select whether to read data from the record field or save the answer to the field.

Create mapped questions in bulk

1. To designate the linked record, do one of the following:
   • Click Map Regarding to use the record from which the questionnaire was opened.
   • Select a lookup question in the questionnaire template and click Map Lookup to use the lookup question target.
2. In the first step of the wizard, select the target entity, then select the fields that should be added as questions in the template.
3. In the second step of the wizard, select whether to read data from the record field or save the answer to the field.

Note the green eye icon on the questions. If you have created the questions from a lookup, a smart visibility rule is automatically configured. The question is not displayed in the questionnaire if the lookup target does not match the entity selected in the mapping configuration. This smart rule is not available for regarding lookup.

Once the questions are created, you can no longer manage them in bulk.

Usage in the app

Once you start such a questionnaire in the app, the record data can populate the default answers. And when you complete it, changed answers can be saved to the mapped record. For example, your inspection could include details of the inspected entity. In the example below, you can review and update the contact information of your contact directly from the questionnaire.

When you start the questionnaire without a regarding record or without answering the lookup, you can continue using the questionnaire as usual. The data mapping is ignored: the answer is not populated at the start and is only saved in the questionnaire.

If you allow creating new records from the questionnaire, you can select the "Create new record" option as your lookup target. Completing such a questionnaire creates a brand-new record.

Example: refresh form after completing questionnaires

Problem: Start a questionnaire from an entity form. The questionnaire uses data mapping to modify the record data. After completing the questionnaire, data is changed, but the form is not refreshed automatically, showing old data. User needs to close and reopen the form and that's an unintuitive and redundant step.

Solution: Use an On Change rule triggered by a change in the Inspections tab to execute a JavaScript function that refreshes the form.

Allow the Inspections unrelated list to trigger On Change events

1. Edit the app project in Woodford.
2. Select the entity from the Project menu and edit the form.
3. Select the Inspections tab and click Properties.
4. Go to the Properties tab, enable Trigger OnChange event.
5. Save all changes.

Add an iframe and upload JavaScript

1. On the entity form, click Add IFrame, then click Manage.
2. Verify that a recent version of JSBridge.js is included in the offline HTML.
3. Create or import an HTML file with the simple script listed below.
4. Save and close the Offline HTML window.
5. On the Configure IFrame window, enter the name of the script file.
6. Click OK and save all changes.

<!DOCTYPE html>
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta charset="utf-8" />
    <title>Empty Offline HTML page</title>
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="initial-scale=1, user-scalable=no" />
    <script src="JSBridge.js"></script>
</head>
<body>
    <script>
        function refreshForm(){
        MobileCRM.UI.EntityForm.refreshForm();
        }
        function saveForm() {
            MobileCRM.UI.EntityForm.save();
        }
    </script>
</body>
</html>

This example includes only two simple functions:

• Use refreshForm if you only need to refresh the form without saving possible unsaved changes.
• Use saveForm to save the form. This automatically refreshes the form.

Create a rule that executes the script

1. On the entity form, click On Change.
2. Enter the following rule:
   
3. Save all changes.

See also

• Related feature: Automatically copy answer to a custom field

Was this information helpful? How can we improve?