Property Prefill to Access Reference Data

   MaestroThe UI design product.  |   Form BuilderPlatform Developer |  19.05 This feature was introduced in 19.05.

While building onboarding application forms, you can use various reference data to pre-fill and autocomplete form's fields, as well as validate user input against this data. Reference data is static data that is created and stored in Manager and it is pertinent to an organization, which Maestro forms, belonging to that organization, can access.

As we showed in Use Reference Data with JavaScript Library, you can access reference data using the JavaScript Library component. However, Journey Maestro also allows you to access reference data using property prefill. In this case, reference data is stored and managed by Journey Manager and injected into the form's XML data at the time of the rendering of the form. There is a non-trivial setup process required in Manager, but one benefit is that reference data remains external to the form. For more information, see form prefill for anonymous users. Be aware that prefilled data is returned along with other data fields in the submission XML, which can increase the size of data passed between a client and a server. For this reason, using prefill for reference data is not the ideal choice. For example, if your reference data is a list of country codes, you don't really what to have this data come back in the submission XML.

The reference data here is held in Manager as a Form Property. Before you can assign a value to a 'Property', you need to create a Property Type for it. To do this, follow these steps:

1. Open a Maestro form in the Maestro editor.
2. Add a ManufacturersPropertyData Data Field component to the form.
3. Click the Integration tab and select the Include in Submission Data checkbox to be able to map property data into the ManufacturersPropertyData field using the Property Mapping functionality of Manager. This also causes the data field to be sent back with the submission XML data. However, we don't want to do this for reference data, so we can prevent this from happening by using the following code.
4. Add a ManufacturersPropertyDropdown Data Driven Dropdown component to the form.
5. Change the Data Source to data.$tempManufacturers.
6. Add the following Form Load rule to the form:

   data.$tempManufacturers = JSON.parse(data.manufacturerspropertydata);
   delete data.manufacturerspropertydata;
   delete data.prefill.manufacturerspropertydata;

   This rule converts the JSON formatted text value that is injected into the ManufacturersPropertyData data field into a JSON object. Then, it saves the converted JSON object into a temporary data field $tempManufacturers. It removes the manufacturerspropertydata field from the form data object, so it will not be sent back in the submission XML. It also removes the manufacturerspropertydata field from the form prefill data object, otherwise it will be merged back into the form data object before submission.

   Note

   Form fields with names beginning with $ are not sent back in the submission XML data.

7. Save and publish the form to Manager.
8. Log on to Manager.
9. Select Forms > Property Types and click New to create a new property type using the following configuration:
   • Name: ReferenceData
   • Scope: Client
   • Data type: JSON
10. Select Forms > Forms and find and open the form in the Dashboard.
11. Click the Properties link in the Form Versions section.
12. Click New to create a new property.
13. Name it as ReferenceData.
14. Choose ReferenceData from the Property Type dropdown list.
15. Paste your JSON data into the Value field, which you can copy from the Motorcycles.json file.
    Note

    If you try to create a new property of the same Property Type in your form, you cannot do that. A Property Type can only be given a value by one Property in the same form.

16. Click Save.
17. Re-open your form in the Dashboard window.
18. Click Data Config link in the Form Versions section and select the Property Prefill Mapping tab.
19. Click Edit.
20. Scroll the left pane down until you can see the ReferenceData property
21. From the right pane 'Target: Form Data XML', drag 'ManufacturersPropertyData' into the 'Form Data XPath' column and drop it beside 'ReferenceData'
22. Click Save
23. In some browsers, you may now be left with a blank screen. If so, press F5 to refresh the page.
24. Open the form and select the Dashboard tab.
25. Test the form by clicking the icon under 'Direct' in the Form URLs box
26. Your form should now show data in the dropdown

Next, learn how to use reference data with a dynamic data service.