Access to Form Reference Data

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

Many applications require some type of reference data that infrequently changes, such as lists of countries, vehicle manufacturers, models, years, titles, product types, and so on.

Journey Maestro allows Form Designers to access reference data using the following techniques:

• JavaScript library
• Property prefill
• Dynamic Data service

JavaScript Library

The Form Designer supplies JavaScript source, which is embedded directly into the form as a JavaScript Library component. Reference data under this scenario stays with the form and has no external dependencies, with the benefit that versioning of the data is managed by Maestro as part of the form content.

The reference data here is embedded in the form inside a JavaScript library. In the sample data below, we have used the property names label and value in our JSON object. These property names are the default values for displaying in Data Driven Dropdown components. By using these names, we can accept the default values for the dropdown's Label Field and Value Field properties. We can use any names we want in our JSON though, and simply change the dropdown properties to suit. To do this, follow these steps:

1. Create a JavaScript file that contains a variable holding your reference data as a JSON object. You can have as many variables as you want, but for this example, we will only use one, motorCyclesReferenceData.
2. Add a JavaScript Library component to your form, and upload your JavaScript file into it.



3. Add a Data Field component to your form to hold each variable your JavaScript file contains. We use the name 'manufacturers'
4. Add a Calculation rule to the manufacturers Data Field.



5. In the Calculation rule, put the name of the JavaScript variable and save the rule.
6. Reference your Data Field component as you want, in other parts of the form.
7. Add a Data Driven Dropdown to your form, calling it 'Manufacturer'.
8. In the Data Source property, double-click the 'manufacturers' Data Field.
9. Preview the form.
10. Your Manufacturer dropdown will now show values from your reference data.

Property Prefill

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 Prefill a Cascading Dropdown in Composer and Form Prefill for Anonymous Users. Be aware that prefilled data will be returned along with other data fields in the submission XML. 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. Log on to Maestro.
2. Create a form and add a ManufacturersPropertyData Data Field component to it.
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;

7. This rule converts the JSON formated text value that has been injected into the ManufacturersPropertyData data field into a JSON object. Then, it saves the converted JSON object into a temporary data field $tempManufacturers - form fields with names beginning with '$', are not sent back in the submission XML data. 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
8. Save and Publish your form to Manager
9. Log on to Manager.
10. Select Forms > Property Types and click New to create a new property type.
11. Name it as ReferenceData.
12. Select a scope as Client.
13. Select a data type as JSON.
14. Save the new property type.
15. Select Forms > Forms and find your form to open it in the Dashboard window.
16. Click the Properties link in the Form Versions section.
17. Click New to create a new property.
18. Name it as ReferenceData.
19. Choose ReferenceData from the Property Type dropdown list.
20. 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.

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

Dynamic Data Service

Reference data is stored and managed by running a custom Fluent Groovy Service in Manager and made available at run-time when the form decides to fetch it. An advantage of this method is the potential ability to dynamically filter the data. Reference data is still external to the form using this method, but it does require the creation of a service in Manager. A form builder will need to write code to persist the dataaccess the service and deal with the response.

The table below lists compares the features of each techniques.

Feature	JavaScript Library	Property Pre-fill	Dynamic Data Service
Works in Preview mode	Yes	No	No
Version control	Managed by Form versioning	None	Determined by service
Use When	form-specific data infrequent data changes no sharing required static data required work entirely in Maestro	sharing required static data required need to override at org/form/user	filtering requiredsharing required
Manager content validation	N/A	Yes	Determined by code
Supports lazy-loading	No	No	Yes
Share-ability	None	Shareable	Shareable
Security	None	None	Determined by code
Re-publish required after change	Yes	No	No
No-code implementation	No	Only for simple data type	No
Impact on save/retrieved forms	No	May break	None
Impact on review task forms	None	May break	None
Good Points	easy to implementno TM action requiredversioned with formno server calls needed	content managed by TMhierarchical org/form/user overridesno server calls needed	most flexiblelazy loadabilityfilterablesecurable
Filterable data source	No	No	Yes, if coded
Data variability	Static	Static	Dynamic, if coded
Data type	Object	String, can be converted to Object in code	Object
Data source	Embedded in JavaScript code	TM Properties	Determined by service
Data instance location	Global context	Form XML	Determined by code
Data associated with	Form	Organization / Form / User	Determined by service
Complexity of TM setup	Not required	Medium	Complex
Bad points	re-publish on change scope directly to form cannot be shared static data only	complex TM setup may break review / retrieved forms code required for object conversion initially, but contaminates form XML static data only	higher coding requirement overkill for simple cases

Each of the following guides details how to gain access to reference data using the techniques discussed above. In each case, we populate an initial Data Field with some sort of data (for this example we will use data from motorcycle manufacturers). At the end of the guides, we will demonstrate methods of using the manufacturer's data to build cascading data dropdowns. Building the cascading dropdowns with each method is exactly the same process, the only difference is how you initially obtain the reference data.

Here we will create a new Manager service which will return our JSON as text. Then we will call the new service from a form to populate a dropdown as before. We will call our new service from the form's Load event.

1. In Manager, choose All Services from the Services menu and click New
2. Choose Service Type 'Dynamic Data'
3. Choose Service Template 'Fluent Dynamic Data'
4. Enter Service Name 'Motorcycle Manufacturers'
5. Choose your Organization
6. Click Save
7. Select the Groovy Script tab
8. Replace all the existing JSON text between the pairs of triple single-quotes (''') with text from this Motorcycles.json file
9. Your complete code should now look like:



10. Click Save
11. In Maestro, create a new form
12. Drop a Data Field onto the form, call it 'ManufacturersDDS'
13. Drop a Data Driven Dropdown onto the form, call it 'Manufacturers From DDS'
14. Change its Data Source to data.manufacturersdds by double-clicking on ManufacturersDDS
15. Click the Form Options button in the Maestro control bar
16. Click Form Rules
17. Click Create Rule and click Load under 'Form'
18. Paste in this code:

    DynamicData.call("Motorcycle Manufacturers", {}).then(function(response) {data.manufacturersdds = response;});

19. Click Save
20. Click Save again
21. Save and Publish the form
22. Render the form and you will see data from the service in the dropdown

Add Cascading Dropdowns

To complete your reference data implementation, you need to add cascading dropdowns. Here we will add additional dropdowns for Model and Year to the form. When the value selected in the manufacturer dropdown changes, the model will be re-populated with the models available from the chosen manufacturer. Similarly, when the model dropdown selection changes, the years dropdown will be re-populated.

Because we have continued to use the 'label' and 'value' properties throughout all levels of our JSON data, we don't need to change the 'Label Field' and 'Value Field' properties on any of the dropdowns.

The instructions here relate to the initial Data Field named 'manufacturers' and Dynamic Data Dropdown called 'manufacturer'. We created these components in the JavaScript library method. If you followed the JavaScript Library instructions and saved your form, re-use that form here so that your data fields and dropdown names match these instructions.

1. In Maestro, open your form created during the JavaScript Library method instructions
2. Check the Calculation rule on the 'manufacturers' Data Field... it should already contain 'motorCyclesReferenceData' from the JavaScript Library method instructions
3. Add 2 more Data Field components to your form, name them 'models' and 'years'
4. Add 2 more Dynamic Data Dropdown components, name them 'Model' and 'Year'
5. Change the Data Source properties of Model and Year dropdowns to the Data Fields 'models' and 'years'
6. Add a Change rule to the Manufacturer dropdown, with the code:

   var selected = data.manufacturer;
   data.manufacturers.some(function(element) {
       if (element.value === selected) {
           data.models = element.models;
           data.years = undefined;
           return true;
       }
   });
   return undefined;

7. The code above will execute when the Manufacturer dropdown selection is changed. The code just replaces the Data Fields 'models' with the child property 'models' from the selected manufacturer, and also sets 'years' to undefined.
8. At this stage, you could Publish and render your form and see the Model dropdown populates on a change of Manufacturer, but the Year dropdown is always empty. We will implement a Model Change rule to bring the Year dropdown into play.
9. Now add a Change rule to the Model dropdown, with the code:

   data.years = data.models.filter(function(element) {
       return element.value === data.model
   })[0].years;

10. The code above just sets the 'years' Data Field to the years property of the currently select model. It closely follows the Manufacturer change rule code but is implemented slightly differently to demonstrate there are different methods that can be used to achieve the same result. In this case, we use the JavaScript filter function to find the matching data from the models Data Field.
11. Save and Publish your form

Now when you render the form, you will see the cascading behavior between the Manufacturer, Model, and Year dropdowns.

Next, learn about pre-submit validation.