Data Dictionary is a very flexible system. You can use it to gather information in as much or as little detail as you like. The sections below suggest how you can use different aspects of Data Dictionary.
Basic use
Installation
You need to install a separate instance of Data Dictionary for each organisation.
Most organisations can run multiple projects using the same instance of Data Dictionary. However, large or very different projects may benefit from a separate instance.
You can install Data Dictionary using reference metrici.products.data_dictionary.install. No product key is required.
Familiarisation
Before you start using Data Dictionary, read about the Data Dictionary data model, which describes in detail the structure of the information that can be held by Data Dictionary and descriptions of all the available data items. Also familiarise yourself with the folders that Data Dictionary installs.
User interface
Data Dictionary is presented as a series of folders. Each folder is represented by an icon.
Each of the main data types is available from the Data Dictionary home page: systems, data stores, interfaces, definitions (data structures and fields), intermediaries, parties (people and organisations), agreements and tags.
The other icons are:
- Uploaded files stores files that have been uploaded as attachments. You can upload additional files here and then reference them as attachments.
- Exports allows you to export the main data types as comma-separated values (CSV) files.
- Workbench shows you the Data Dictionary instance using the workbench interface, which provides an explorer-like view of the data, a tabbed detail pane, action and contextual help.
- Settings provides settings that administrators can set.
- Reference is a link to this documentation.
The settings area contains two items that are only available to administrators. It contains User roles which allow users to be authorised to use Data Dictionary, giving them roles of administrators (who can update data and administer the system), users (who can update data, but not administer the system) and read-only users (who can only read the data).
Settings also contains a Setup folder which in turn contains a series of folders for managing reference items available in drop-down lists, including data types, formats, life cycles, platforms, protocols, schedules, sizes, statuses and time periods. Only administrators can change these setup items.
Systems, data stores and interfaces
As a minimum, you will need to document systems, data stores and/or interfaces. All you need are names for each system, data store and interface. For each data store, identify the containing system. For each inteface, pick an Interface type, Source and Target. This of itself will provide a useful level of structure and consistency.
Each item has a description, which lets you describe what the item is. There are similar textual fields on other tabs:
- Notes let you hold working notes on things, for example to record what you are not sure about.
- Purpose is for documenting why. This can be particularly useful when documenting existing systems and interfaces because it lets you challenge the purpose of the integration.
- Implementation notes gives you a place to write the how of integration, and acts as a place for writing specifications if you choose to do so in Data Dictionary.
Tags
The Tags folder lets you define tags to categorise items or to make them easier to manage. What tags you use is up to you, and depends entirely on the needs of your project. For example, you might use tags to identify whether a system is internal, external, or Software-as-a-Service (SaaS).
Tagging lets you filter your items. From the tag page, you get a list of all the items in with that tag. When you're looking at the folder with your items in (for example, the Systems folder), the tag appears in the drop-down on the right, letting you select all the items in a particular tag.
Notes
The notes tab lets you keep track of information that you need to manage the process. You can hold rough notes, list the people who are contacts for the information. You can also upload attachments, which can be a useful way of structuring and retrieving existing documentation.
The life cycle and status let you categorise where information is in its life cycle (for example, is it existing or proposed), and where it is in your pocess (is it in progress or completed). You can set up your own list of life cycle stages and statuses - see categorisation below.
Purpose
The purpose tab is for recording the business meaning, purpose or relevance.
Implementation
The implementation tab lets you record how the item is or needs to be implemented. As well as providing notes, you can enter a reference, such as a program name, which may be useful to refer to in the development process.
Data structures
Data structures let you document the data that is stored in data stores or passed in Interfaces. You don't have to document data structures (you could just note down the details in the implementation notes of the data store or interface), but documenting the data structures separately can make the information clearer.
Use the implementation notes on the data structure to record the data structure, or use the attachments on the notes page to upload other documentation.
Fields and component structures
You can model the data structures further in Data Dictionary if you wish.
You can define the individual fields that make up the data structures. Each field should have a data type (such as string or number), and can set length and number of decimal places. You can then arrange fields into data structures, which you can then arrange into higher-level structures, and so on.
As you create the structures you can specify cardinality - such as whether fields and optional and whether structures repeat.
You can indicate that some structures are "component structures". This means that they are not used direcly by interfaces, only to build other data structures, and so do not appear in the list when maintaining interfaces.
Intermediaries
In intermediary is an additional integration process that is not part of the sending or receiving system, such as a transformation in an ETL tool. Its useful to document these if you are designing an integration solution that uses them.
Intermediaries act in a similar way to systems, but are finer grained and may themselves be grouped into systems.
When itermediaries are used, the intermediary is shown along with the ultimate source and target when listing the interfaces.
Categorisation
As well as the flexible grouping structure, there are some standard categorisations that can be applied:
- All items can be categorised by life cycle and status.
- Systems can be categorised by platform.
- Interfaces can be categorised by format and protocol.
These categories must be set up before you can use them, but you can add to them and change them after they have been set up. Go into the setup folder to set up categories.
Like groups, items are tagged with the categories that you use, and each category links back to the items that have been categorised using it.
Exports
Data Dictionary provides a set of tables which can be used to export all the data in Data Dictionary. Each export provides a download button to export the table as CSV.
You can change what goes on an export, by including/excluding rows, changing and renaming columns, and filtering rows. To do this, copy the export that you want to base your new export on, and then use the Edit option to set filter criteria. The syntax for the filter criteria is defined in Table Filter Script.