A data dictionary enables business users to use information from back-end data sources without knowing technical details about their underlying data models. A data dictionary is composed of data dictionary elements (DDEs). You use these data elements to integrate back-end data to the letters as input for use in a customer correspondence.
A data dictionary is an independent representation of metadata that describes underlying data structures and their associated attributes. A data dictionary is created using business vocabulary. It can be mapped to one or more underlying data models.
The data dictionary is made up of elements of three types: Simple, Composite, and Collection elements. Simple DDEs are primitive elements such as strings, numbers, dates, and Boolean values that hold information such as a city name. A Composite DDE contains other DDEs, which can be of type primitive, composite or collection. For example, an address, which consists of a street address, city, province, country, and postal code. A Collection is a list of similar Simple or Composite DDEs. For example, a customer with multiple locations, or different billing and shipping addresses.
Correspondence Management uses the back end, customer, or recipient-specific data stored according to the data dictionary’s structure to create correspondence meant for different customers. For example, a document can be created with friendly names, such as “Dear {First Name}”,“Mr. {Last Name}”.
Typically, business users do not require knowledge of metadata representations such as XSD (XML schema), and Java classes. However, they usually require access to these data structures and attributes to build solutions.
Install the Compatibility Package to view the Data Dictionaries option on the Forms page.
You use the Data Dictionary Editor to create a data dictionary or you can upload an XSD schema file to create a data dictionary based on that. You can then extend the data dictionary by adding more required information, including fields. Regardless of how the data dictionary was created, the business process owner does not need knowledge of the back-end systems. The business process owner only needs knowledge of the domain objects, and their definitions, for their process.
For multiple letters that require similar elements, you can create a common data dictionary. A large data dictionary with a large number of elements, however, may lead to performance issues while using the data dictionary and loading the elements, such as in letters and document fragments. If you run into performance issues, try to create separate data dictionaries for different letters.
Select Forms > Data Dictionaries.
Tap Create Data Dictionary.
In the Properties screen, add the following:
Title: (Optional) Enter the title for the data dictionary. Title do not need to be unique and can have special characters and non-english characters. Letters and other document fragments are referred with their title (when available), such as in thumbnails and asset properties. Data dictionaries are referenced with their names and not titles.
Name: The unique name for the data dictionary. In the Name field, you can enter only English language characters, numbers, and hyphens. The Name field is automatically populated based on the Title field and the special characters, spaces, numbers, and non-English characters entered in the Title field are replaced with hyphens. Although the value in the Title field is automatically copied to the Name, you can edit the value.
Description: (Optional) Description of the data dictionary.
Tags: (Optional) To create custom tag, enter value in text field and press Enter. You can see your tag below text field of tags. When you save this text, the newly added tags also get created.
Extended Properties: (Optional) Tap Add Field to specify metadata attributes for your data dictionary. In the Property Name column, enter a unique property name. In the Value column, enter a value to associate with the property.
(Optional) To upload an XSD schema definition for your data dictionary, under the Data Dictionary Structure pane, tap Upload XML Schema. Browse to XSD file, select it, and tap Open. A Data Dictionary gets created based on the uploaded XML schema. You need to tweak display names and descriptions of the elements in the data dictionary. To do this, select the names of the elements by tapping them and edit their descriptions, display names, and other details in the fields in the right pane.
For more information on Computed DD Elements, see Computed Data Dictionary Elements.
You can skip uploading the schema file and build your data dictionary from scratch using the user interface. To do this, skip this step and continue with the next steps.
Tap Next.
In the Add Properties screen, add the elements to the data dictionary. You can also add/delete elements and edit their details if you have uploaded a schema to get a basic structure of the data dictionary.
You can tap the three dots on the right side of an element and add an element to the data dictionary structure.
Select either Composite Element, Collection Element, or Primitive Element.
Following are some rules for creating a data dictionary:
For more information on Composite, Collection, and Primitive elements and working with data dictionary elements, see Mapping Data Dictionary Elements to XML Schema.
For information on validations in Data Dictionary, see Data Dictionary Editor validations.
(Optional) After selecting an element, in the Advanced tab you can add properties (attributes). You can also tap Add Field and extend the properties of a DD element.
(Optional) You can remove any element by tapping the three dots on the right side of an element and selecting Delete.
Deleting a composite/collection element with child nodes deletes its child nodes also.
(Optional) Select an element in the Data Dictionary Structure pane, and in the Field and Variable List panel. Change, or add any required attributes associated to the element.
Tap Save.
To quickly create one or more data dictionaries with properties and elements similar to existing data dictionaries, you can copy and paste them.
While editing or viewing a data dictionary, you can see which elements in the data dictionary are referred in which Texts, Conditions, Letters, and Interactive Communications.
Do one of the following to edit the data dictionary:
Or tap on a data dictionary to view it.
In the data dictionary, tap a simple element to select it. Composite and collection elements do not have references.
Along with Basic and Advanced properties of the element, Lent Content also appears.
Tap Lent Content.
The Lent Content tab appears with the following: Texts, Conditions, Letters, and Interactive Communications. Each of these headings also displays the number of references to the selected element.
Tap on a heading to see the name of the assets that refer to the element.
To view lent content for another element, tap the element.
To display an asset that refers to the element, tap on its name. The browser displays the asset, letter, or Interactive Communication.
On the Data Dictionaries page, tap Select.
Tap a data dictionary for which you want to download test data and then tap Download Sample XML Data.
Tap OK in the alert message. An XML file gets downloaded.
Open the XML file with Notepad or another XML editor. The XML file has the same structure as the data dictionary and placeholder strings in the elements. Replace the placeholder strings with the data you want to test a letter with.
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Company>
<Name>string</Name>
<Type>string</Type>
<HeadOfficeAddress>
<Street>string</Street>
<City>string</City>
<State>string</State>
<Zip>string</Zip>
</HeadOfficeAddress>
<SalesOfficeAddress>
<Street>string</Street>
<City>string</City>
<State>string</State>
<Zip>string</Zip>
</SalesOfficeAddress>
<HeadCount>1.0</HeadCount>
<CEO>
<PersonName>
<FirstName>string</FirstName>
<MiddleName>string</MiddleName>
<LastName>string</LastName>
</PersonName>
<DOB>string</DOB>
<CurrAddress>
<Street>string</Street>
<City>string</City>
<State>string</State>
<Zip>string</Zip>
</CurrAddress>
<DOJ>14-04-1973</DOJ>
<Phone>1.0</Phone>
</CEO>
</Company>
In this example, XML creates space for three values to a collection element, but the number of values can be increased/decreased as per the requirement.
After making the data entries, you can use this XML file when you are previewing a letter with test data.
You can add this test data with DD (Select DD and tap Upload Test Data and upload this xml file)
So after this when you preview letter normally (not custom), then this XML data is used in letter. You can also tap Custom and then upload this XML.
The following code samples show implementation details for the Data Dictionary.
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns="DCT" targetNamespace="DCT" xmlns:xs="https://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified" attributeFormDefault="unqualified">
<xs:element name="Company">
<xs:complexType>
<xs:sequence>
<xs:element name="Name" type="xs:string"/>
<xs:element name="Type" type="xs:anySimpleType"/>
<xs:element name="HeadOfficeAddress" type="Address"/>
<xs:element name="SalesOfficeAddress" type="Address" minOccurs="0"/>
<xs:element name="HeadCount" type="xs:integer"/>
<xs:element name="CEO" type="Employee"/>
<xs:element name="Workers" type="Employee" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:complexType name="Employee">
<xs:complexContent>
<xs:extension base="Person">
<xs:sequence>
<xs:element name="CurrAddress" type="Address"/>
<xs:element name="DOJ" type="xs:date"/>
<xs:element name="Phone" type="xs:integer"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="Person">
<xs:sequence>
<xs:element name="PersonName" type="Name"/>
<xs:element name="DOB" type="xs:dateTime"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="Name">
<xs:sequence>
<xs:element name="FirstName" type="xs:string"/>
<xs:element name="MiddleName" type="xs:string"/>
<xs:element name="LastName" type="xs:string"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="Address">
<xs:sequence>
<xs:element name="Street" type="xs:string"/>
<xs:element name="City" type="xs:string"/>
<xs:element name="State" type="xs:string"/>
<xs:element name="Zip" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
The following table details the common attributes associated with a DDE:
Attribute | Type | Description |
Name | String | Required. Name of the DDE. It must be unique. |
Reference Name |
String | Required. Unique Reference name for the DDE allowing for references to the DDE that are independent of changes to the hierarchy or structure of the data dictionary. Text modules are mapped using this name |
displayname | String | An optional user-friendly name of the DDE. |
description | String | Description of the DDE. |
elementType | String | Required. The type of DDE: STRING, NUMBER, DATE, Boolean, COMPOSITE, COLLECTION. |
elementSubType | String | The subtype for DDE: ENUM. Only allowed for STRING and NUMBER elementType. |
Key | Boolean | A Boolean field to indicate if a DDE is key element. |
Computed | Boolean | A Boolean field to indicate if a DDE is computed. A computed DDE value is a function of other DDE values. By default, jsp expressions are supported. |
expression | String | The expression for the "computed" DDE. The expression evaluation service shipped by default supports JSP EL expressions. You can replace the expression service with a custom implementation. |
valueSet | List | A set of allowed values for an Enum type DDE. For example, Account type can have (Saving, Current) values only. |
extendedProperties | Object | A Map of custom properties added to the DDE (user interface specific or any other information). |
Required | Boolean | The flag indicates that the source of instance data corresponding to the data dictionary must contain the value of this particular DDE. |
Binding | BindingElement | The XML or Java binding of the element. |
A data dictionary can also include computed elements. A computed data dictionary element is always associated with an expression. This expression is evaluated to get the value of a data dictionary element at runtime. A computed DDE value is a function of other DDE values or literals. By default JSP Expression Language (EL) expressions are supported. The EL expressions use the ${ } characters and valid expressions can include literals, operators, variables (data dictionary element references), and function calls. While referencing a data dictionary element in the expression, the reference name of the DDE is used. The reference name is unique for every data dictionary element within a data dictionary.
A computed DDE PersonFullName can be associated with an EL concatenation expression such as ${PersonFirstName} ${PersonLastName}.
Exporting an XSD requires specific data mapping, which is detailed in the following table. The DDI column indicates the type of the DDE value as available in the DDI.
XSD |
Data Dictionary |
DDI (Instance Value Data Type) |
xs:element of type - Composite Type |
DDE of type - COMPOSITE |
java.util.Map |
xs:element where maxOccurs > 1 |
DDE of type - COLLECTION- A DDE node is created next to the COLLECTION DDE which captures information from the parent COLLECTION node. The same gets created for both collection of simple/composite data types. Whenever you have a COLLECTION of the type composite, the Data Dictionary tree captures the constituent fields in the children of the DDE created for capturing type information. - DDE (COLLECTION) - DDE(COMPOSITE for type info) - DDE(STRING) field1 - DDE(STRING) field2 |
java.util.List |
Attribute of type - xs:id |
DDE of type - STRING |
java.lang.String |
xs:attribute /xs:element of type - xs:string | DDE of type - STRING |
java.lang.String |
xs:attribute /xs:element of type - xs: boolean |
DDE of type - Boolean |
java.lang.Boolean |
xs:attribute /xs:element of type - xs:date | DDE of type - DATE | java.lang.String |
xs:attribute /xs:element of type - xs:integer | DDE of type - NUMBER | java.lang.Double |
xs:attribute /xs:element of type - xs:long | DDE of type - NUMBER | java.lang.Double |
xs:attribute /xs:element of type - xs:double | DDE of type - NUMBER | java.lang.Double |
Element of enum type and baseType - xs:string | DDE of type - STRING subtype - ENUM valueSet - the allowed values for ENUM |
java.lang.String |
Once you have created a data dictionary, you can download it as an XML sample data file to make text entries in it.
In the Data Dictionaries page, tap Select and then tap a data dictionary to select it.
Select Download Sample XML Data.
Tap OK in the alert message.
Correspondence Management creates an XML file based on the selected data dictionary’s structure and downloads it to your computer with the name <data-dictionary-name>-SampleData. Now you can edit this file in an XML or text editor to make data entries while creating a letter.
When you want to send the same letter in different languages to your customers, you can localize the display name, description, and enum value sets of the Data Dictionary and Data Dictionary Elements.
On the Data Dictionaries page, tap Select and then tap a data dictionary to select it.
Tap Download Localization Data.
Tap OK in the alert. Correspondence Management downloads a zip file to your computer with the name DataDictionary-<DDname>.zip.
The Zip file contains a .properties file. This file defines the downloaded data dictionary. The contents of the property file are similar to the following:
#Wed May 20 16:06:23 BST 2015
DataDictionary.EmployeeDD.description=
DataDictionary.EmployeeDD.displayName=EmployeeDataDictionary
DataDictionaryElement.name.description=
DataDictionaryElement.name.displayName=name
DataDictionaryElement.person.description=
DataDictionaryElement.person.displayName=person
The structure of the properties file defines one line each for the description and the display name for the data dictionary and each data dictionary element in the data dictionary. In addition, the properties file defines one line for an enum value set for each data dictionary element. As with a data dictionary, the corresponding properties file can have multiple data dictionary elements definitions. In addition, the file can contain the definitions for one or more enum value sets.
To update the .properties file in a different locale, update the display name and description values in the file. Create more instances of the file for each language you want to localize in. Only French, German, Japanese, and English languages are supported.
Save the different updated properties files with the following names:
_fr_FR.properties French
_de_DE.properties German
_ja_JA.properties Japanese
_en_EN.properties English
Archive the .properties file (or files for multiple locales) into a single .zip file.
In the Data Dictionaries page, select More > Upload Localization Data and select the zip file with localized properties files.
To view the localization changes, change your browser locale.
The Data Dictionary Editor enforces following validations when creating or updating a data dictionary.
Validations that are applied at the Data Dictionary Level
Validations that are applied at the Data Dictionary Element Level.
You can create a data dictionary from an XML Schema or build it using the Data Dictionary user interface. All the Data Dictionary Elements (DDEs) within a data dictionary have an XML Binding field to store the binding of the DDE to an element in the XML schema. The binding in each DDE is relative to the parent DDE.
The following details sample models and code samples which show implementation details for the Data Dictionary.
A primitive DDE represents a field or attribute which is atomic in nature. Primitive DDEs defined outside the scope of a complex type (composite DDE) or a repeating element (collection DDE) can be stored in any location within the XML Schema. The location of the data corresponding to a primitive DDE is not dependent on the mapping of its parent DDE. Primitive DDE uses the mapping information from the XML Binding field to determine its value and the mappings translate into one of the following:
The following example shows a simple schema.
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="https://www.w3.org/2001/XMLSchema">
<xs:element name='age' type='integer'/>
<xs:element name='price' type='decimal'/>
</xs:schema>
Data Dictionary Element | Default XML Binding |
---|---|
age | /age |
price | /price |
Binding is not supported for Composite elements, if binding is provided, it is ignored. The binding for all the constituent child DDEs of primitive type, must be absolute. Allowing absolute mapping for child elements of a composite DDE provides more flexibility in terms of XPath Binding. Mapping a composite DDE to a complex type element in XML schema limits the scope of binding for its child elements.
The following example shows the schema for a note.
<xs:element name="note">
<xs:complexType>
<xs:sequence>
<xs:element name="to" type="xs:string"/>
<xs:element name="from" type="xs:string"/>
<xs:element name="heading" type="xs:string"/>
<xs:element name="body" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Data Dictionary Element | Default XML Binding |
note | empty(null) |
to | /note/to |
from | /note/from |
heading | /note/heading |
body | /note/body |
A collection element is only mapped to another collection element which has cardinality > 1. The child DDEs of a collection DDE have relative(local) XML Binding with respect to its parent’s XML Binding. Since the child DDEs of a collection element must have the same cardinality as that of parent, the relative binding is mandated to ensure the cardinality constraint so that the child DDEs do not point to a non-repeating XML Schema element. In the example below, the cardinality of “TokenID” must be same as “Tokens” which is its parent collection DDE.
When mapping a collection DDE to an XML Schema element:
the binding for the DDE corresponding to Collection element must be the absolute XPath
Provide no binding for the DDE representing the type of Collection element. If provided, the binding would be ignored.
The binding for all the child DDEs of Collection element must be relative to the parent Collection element.
The XML Schema below declares an element with the name Tokens and a maxOccurs attribute of “unbounded”. Thus, Tokens is a collection element.
<?xml version="1.0" encoding="utf-8"?>
<Root>
<Tokens>
<TokenID>string</TokenID>
<TokenText>
<TextHeading>string</TextHeading>
<TextBody>string</TextBody>
</TokenText>
</Tokens>
<Tokens>
<TokenID>string</TokenID>
<TokenText>
<TextHeading>string</TextHeading>
<TextBody>string</TextBody>
</TokenText>
</Tokens>
<Tokens>
<TokenID>string</TokenID>
<TokenText>
<TextHeading>string</TextHeading>
<TextBody>string</TextBody>
</TokenText>
</Tokens>
</Root>
The Token.xsd associated to this sample would be:
<xs:element name="Root">
<xs:complexType>
<xs:sequence>
<xs:element name="Tokens" type="TokenType" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:complexType name="TokenType">
<xs:sequence>
<xs:element name="TokenID" type="xs:string"/>
<xs:element name="TokenText">
<xs:complexType>
<xs:sequence>
<xs:element name="TextHeading" type="xs:string"/>
<xs:element name="TextBody" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
Data Dictionary Element | Default XML Binding |
---|---|
Root | empty(null) |
Tokens | /Root/Tokens |
Composite | empty(null) |
TokenID | TokenID |
TokenText | empty(null) |
TokenHeading | TokenText/TextHeading |
TokenBody | TokenText/TextBody |