Configure Organization Reference Data

   Journey Manager (JM) The transaction engine for the platform.  |    System Manager / DevOps  |  24.04This feature was updated in 24.04

Many applications require some type of reference data that doesn't change often, such as lists of countries, cities and postcodes, vehicle manufacturers and models, and so on. Manager allows you to view, create, configure, and test reference data for a selected organization. Since Maestro 17.10, reference data can be stored in Manager and accessed in Maestro forms by calling the Transact.referenceData function in the Transact name space. For more information, see Maestro API.

To start using reference data in your applications, you should understand more about its structure and types. You can think of reference data as an object that:

• is defined at the organization level.
• is uniquely identified in an organization by a name and locale.
• supports language translation through different locales.
• supports the CSVCSV is a comma-separated values fil, which s a delimited text file that uses a comma to separate values. A CSV file stores tabular data (numbers and text) in plain text. Each line of the file is a data record. Each record consists of one or more fields, separated by commas., JSONJSON (JavaScript Object Notation) is an open standard file format and data interchange format that uses human-readable text to store and transmit data objects consisting of attribute–value pairs and arrays. and XMLXML (Extensible Markup Language) is a markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. data types.
• supports optional dynamic filtering and sorting of the CSV data type.
• supports server caching, with configurable refresh time-out specified for each reference data item.

Manager stores reference data using the following file formats:

CSV

Supports filtering and sorting, so it has specific requirements described below. The first line of a CSV file must be a heading line containing comma-separated field names with corresponding data following on subsequent lines. Field names defined in the first line are used in filtering and sorting order options by Maestro clients. Field names in the heading line are case sensitive.

JSON and XML

No specific format requirements and are returned as-is to the requesting Maestro client.

Every reference data item must be defined with a localeLocale is a set of parameters that defines the user's language, region and any special variant preferences that the user wants to see in their user interface. Usually a locale identifier consists of at least a language code and a country/region code.. The locale, in conjunction with the reference data Name property, forms a unique combination. Both the name and locale must be specified when requesting reference data in a Maestro form.

An organization can have a set of properties that you can use in your applications, so it's important to understand the difference between the organization properties and reference data. This allows us to determine when one should be preferred over the other.

• Organization properties can be included in an application package, but reference data can't.
• Organization properties can be deployed through CI/CD pipelines, but reference data can't.
• Reference data elements include locale as part of a compound key, which means that you can have multiple reference data entries with the same name as long as the locale is different. Each organization property must be uniquely named, and there's no concept of locale.
• Organization properties support property prefill mapping.
• Reference data must be CSV, JSON, or XML. Organization properties can also be String, Boolean, Number, List or even Image.
• Reference data can be fetched from Maestro by using Transact.referenceData(name, query, locale, hideProgressFlag, hideAlertError).
• Reference data is cached in Manager to improve performance, as opposed to running PropertyQuery every time data is needed.

To view organization reference data:

1. Select Forms > Organizations.
2. Locate an organization and click Edit.
3. Select the Reference Data tab.

   

You can check the following details of all configured reference data:

• Name of the reference data set
• Locale of the data set
• Cache timeout
• Data type
• Size of the reference data set
• Last modified
4. Click Edit to update the existing reference data.
5. Click Remove to delete a reference data.
6. Click Download as File to save a reference data set on your local PC.
7. Click Query Test to test your reference data set by running a test query against a reference data set.
   Note

   This option is only available for CSV data type.

To create or edit organization reference data object:

1. Select Forms > Organizations.
2. Locate an organization and click Edit.
3. Select the Reference Data tab.
4. Click New to create a new reference data set, or click Edit to update the existing reference data set.

   

5. Enter a unique name of reference data set in the Name field.
6. Enter a locale in the Locate field, which can be any non-empty string, for example en_AU.
7. Provide cache timeout in seconds in the Cache Timeout field.
8. Select a data type from the Data Type dropdown list, which can be one of the following:
   • CSV
   • JSON
   • XML
9. Click Choose File to upload a reference data file. A type of the reference data file and a file extension must match the selected data type, otherwise an error is thrown.  |  24.04 This feature was introduced in 24.04
10. Click Save to update the changes.

After you've created a new reference data, you can test it verify everything works as expected.

Next, learn how to configure organization form categories.