Best Practices: Data Dictionaries

Overview

Data dictionaries store critical information about the data needed for each page. When planning to build an enterprise application, it's important to plan carefully. The configuration can get confusing if your application has many pages with many components. One aspect of that information is the naming conventions for Property IDs. Setting up and adhering to a data dictionary will:

• Increase the efficiency of all creators on the project.

• Reduce the need for refactoring configuration at a later stage.

What is a Data Dictionary?

A data dictionary is a document used to record:

• All the individual pieces of data that you plan to include in an application.

• The Property IDs and details about each piece of data. For example, corresponding IDs in a legacy system, validations, and formatting requirements.

A data dictionary should include all the elements you plan to store in the database so you can access them later. It can also include key UI elements, such as buttons, that you still need to add. Generally, a data dictionary only includes components the end-user sees in Express View. It doesn't include Plug-Ins, Data Workflows, Initializers, Hidden components, and so on.

Using a data dictionary is critical for efficient builds. For example, say your application doesn't have a data dictionary. And, say you have a quote or account number in a module. Without a data dictionary, one creator might use a Number component to represent this data in their module. Another might use a Text Field for this same data somewhere else in the application. Data dictionaries ensure that the component and data type stay consistent. Also, without a data dictionary, details about data configuration likely won't match your client's needs. This results in needing to refactor configuration, which costs time and money.

It helps to always start with a data dictionary before finishing any configuration. That way, your configuration is as smooth as possible.

Building a Data Dictionary

Making a data dictionary is one of the first steps in building an application. Many start it as part of the initial project scoping and requirement-gathering phase.

Here's how the process often works. At Unqork, the Engagement Managers meet with the client. They walk through every detail and functionality of an application, including data details. So, as a configurator, you'll likely receive the initial data dictionary. (This depends on your project and team composition.) And, configurators on the project are often the ones who complete the Unqork Property IDs for each piece of data.

By now, you should know the main guidelines for creating Property IDs. For example, using camel case, avoiding numerals, and knowing what prefixes to use for each component type. As you think about the design of your application, there's more to keep in mind.

To help you on your journey, here are other best practices to use when creating Property IDs.

Page Prefixes

Creators often want to reuse configuration that shows on every page, like headers and footers. This is why many applications use the Import Module functionality of Panels. But, you get an error if you reuse Property IDs across your modules. Here's a way to avoid this error and keep your components organized—attach a shared prefix to all Data & Event Processing components on a specific page. Putting a page prefix (sometimes called a screen prefix) on each Property ID ensures that each component's ID is unique, even if it refers to the same data across screens.

For example, say you have a confirmation page that follows a page where end-users submit an application. You can use the page prefix of conf for components on the Confirmation page. And you can use the page prefix app for components on the Application page.

Grouping Components

You can use prefixes to group related Property IDs. This way, they display together in the Console. Grouped Property IDs make your life easier when building and troubleshooting. You can group components by what they do. For example, say you have components working together to calculate an insurance quote. Including the prefix quote in the Property ID of each of these components is helpful.

When building a Property ID, think of it as going from general to specific. For instance, take a look at the Property ID appQuoteRuleAge. The most general level is app, which is the page prefix. Next is the group Quote. Then, the component type prefix of Rule. Lastly, the Property ID ends with a detail about what the rule (Decisions component) does. Assuming the Decisions component does something with the end-user's age, Age is at the end of the Property ID.

Abbreviations

You're right if you’re concerned about the potential length of Property IDs using the above method. There’s no rule for how many characters to limit Property IDs to. But, they do become harder to read as they get longer.

Here's what you can do to shorten Property IDs while still including all descriptors. Choose the abbreviations you want to use for frequently used terms ahead of time. Include these abbreviations in your data dictionary. This makes it easy to reference so all Property IDs use the same abbreviations.

Other Best Practices

Here are a few more best practices to keep in mind when building.

Data Formatting

Sometimes, the format of the data you store in the database differs from how you want it to show on the page. For example, consider a percentage. You might store a percentage in the database in a decimal format. That format makes it easy to use that data in calculations. But, on the page, you want it to display as an integer with a percent sign. Or, perhaps the client wants the data saved in the display format. To do any calculations on the percentage, you need to apply logic first to convert it to a usable format. Either way, make this decision ahead of time and record your choices in the data dictionary.

Validations

Your data dictionary should include any relevant data validation you plan to configure. This can include things like the number of decimal places. Or, it can be the list of items to include in a drop-down. Determining these details in advance ensures that the data aligns with your client's expectations. Writing this out also helps the QA process.

Other Details

You'll also include configuration details related to RBAC (role-based access control). For example:

• Visibility: Is the component always visible or conditionally visible? If conditionally, what is that condition?

• Editability: Is the component always editable or conditionally editable? If conditionally, what is that condition?

Here are some other details you can include in your data dictionary:

• The section on the page where the component lives.

• A general description of fields.

• If the component is required or optional.

• Prepopulated values.

• Any corresponding IDs from legacy systems or other integrated applications.

Using a Data Dictionary When Building Applications

When you start working on a feature or page, start by identifying which items in the data dictionary to include. Make sure you understand each item. And, if any details are missing, clarify those before you build. Check how values need to store and display. This way, you can plan for any logic needed to make conversions.

As you build, check that you follow all specifications in the data dictionary. During troubleshooting and testing, you can use the data dictionary as a guide to check for expected behavior. If you make changes to the dictionary, record and communicate those changes to your team.

During the building process, it's common to make changes to the data dictionary. Ensure a version control process is in place for tracking and communicating changes. This way, the dictionary doesn't become outdated and messy.

Data Dictionary Example

To help you visualize the above concepts, look at an excerpt of an example data dictionary. This example data dictionary is for an insurance application. The excerpt includes data for 2 pages: a Quote page, and a Contract page.

Remember, the format and structure vary based on your project and your team's preferences.

Here are the abbreviations used in the example data dictionary:

Term	Abbreviation
Quote Page prefix	qte
Contract Page prefix	con
annuitant	annt
benefits	bnfts
number	num
revision	rev

And here's the example data dictionary: