Skip to main content
Matrix42 Self-Service Help Center

Data Definition


A Data Definition (DD) in the system is always represented by a table in the database. A DD contains attributes providing the Schema for user data. There is a direct connection between the attributes of a DD and the columns of the database table. Explicit relationships between DDs are also defined at the DD level and they are also present as foreign key constraints in the database.

If you compare the database table columns with the attributes of a DD, you see several hidden columns that are explicitly created to support the basic operations of the application; you cannot change them or remove them with the application. Every DD in the Schema always has one attribute of type unique identifier with the name ID (the only exceptions are tables in the internal schema) and a timestamp attribute used for concurrency checks in the API. You must never directly change the Schema of any database table created by the application in any way. Allowed are only transparent operations like creation of indexes, but there is a certain danger that product Schema operations may fail because of this kind of customization. It might happen that the application removes any non product indexes, triggers or statistics without any notice, especially during updates.

DDs have different "Class Types" (type). These define the physical presentation of the DD in the DB and how the DD can be used in the system. You cannot change the type of a DD afterwards.
The DDs of these class types are the basic elements of a CI and only they can be added to a CI as members.

  • Custom Class: This is the basic DD type. If you want to create a DD to include it in a CI, this is normally your best choice.
  • Simple Common Class: If your design needs the same DD in a lot of CIs (approximately more than 10) you should use a Simple Common Class.
  • Common Class: The old version of the Simple Common Class; it should not be used for new DDs and is present for compatibility reasons.

These DDs cannot be added as members to a CI

  • Simple CI Base: DDs of this type cannot be added to a CI, but they can be used as the base for a CI. See -->CI for an explanation.
  • Pickup: A Pickup is a lookup table, that normally relates a simple number to a textual display value. (One simple possible example would be 1:Yes, 0:No.) The number can be added as an attribute to a DD and be automatically related to the display value by special UI elements. A pickup should not be used for data that is frequently changed; it should be used only for static data.
  • View Based: If you need a SQL view of your data that cannot be expressed in ASQL, you can define a SQL view and bind it to a DD using this type. The only mandatory column your view must provide is an ID column of type unique identifier. You can now access this DD by ASQL.

Data Definition Dialog Pages

To create a Data Definition (DD): 

  1. Go to Matrix42 > Administration > Schema > Data Definition > Classes. 
  2. Click Add Data Definition at the top of the Data Definitions page to open the New Data Definition dialog. Provide all the necessary information as explained below and save the Data Definition. 


Internal Name Provide a name for the DD to be used internally. All the Internal Names added by customers have the Ud_ prefix (user defined) automatically added to them. An example of a customer defined Internal Name would be 'Ud_Workplace'. 
Display Name Automatically generated by the system based on the provided Internal Name, without the Ud_ prefix. An example of a Display Name automatically generated based on the Ud_Workplace Internal Name is 'Workplace'. The automatically generated Display Name is not set in stone; users can modify it. 
Description Provide a detailed description of the Data Definition here. 
Class Type

Select one of the available types here: Common Data Definition, Data Definition, Pickup, Simple Configuration Item Base, Simple Data Definition, View Based Class. Common Data Definition, Data Definition, and Pickup are the most often used types. 

Refer to the Data Definitions section of this article for the description of the Class Types. 

Display Expression Provide an ASQL Display Expression. Example: LastName, + ',' + FirstName . In this case, the DD must have LastName and FirstName. 


There are always some hidden (from the UI) attributes in a DD that we use for our own referencing, internally. For example, database tables normally have an ID column and a TimeStamp column, automatically added for you; these two columns are hidden from the UI.

Adding an Attribute from the UI - Type section of the New dialog: 

Field Name Field Description

StringType is a string of characters the number of which is defined (in the Length field).
TextType is a string that has no limit, except for the technical limit. 

Use StringType (and not TextType) whenever possible for the following reasons. You can define indexes only for restricted fields (i.e. the ones where the number of chars you can store is defined), such as StringType. You cannot define an index for unrestricted fields, such as TextType. An index is used to find entries in a huge table very fast; an index is like an index page in a book, the keywords with page numbers at the end of the book. Besides, the StringType is faster for a general search.
BlobType: Use this type if there is no real structure in the attribute, for example, for pictures and binary data. 
BoolType: Yes/No or True/False. 
Currency: this is the number for currencies. The Currency type always has the Scale of 4, i.e. it has 4 digits after the decimal point, which is a convention. 

Whether users are able to select the currency (e.g. USD, EUR) for such controls or end up with the default currency specified in Global Settings depends on whether the Support Multiple Currencies checkbox on the Advanced Dialog Page of the corresponding Configuration Item Dialog is selected or not. See the description of the Support Multiple Currencies checkbox in the Configuration Item Dialog > Advanced Dialog Page section of this article for more details.
DateType: Use for dates. 
DecimalType: Something that has a defined scale (number of digits after the decimal point) and position (number of digits in the whole number). Use this type to avoid rounding errors; their probability is low with DecimalType. 
FloatType: Alternative to DecimalType. It has a decimal point and numbers preceding the decimal point, as well as numbers following the decimal point. It is also restricted somehow in length. This type could be used for a general number, such as a real number in math. Be cautious when using this type, as it brings the danger of errors when you calculate with it. 
GuidType: Use this type of you need long technical unique integers. 
intType: Integer type, so it is a whole number stored in 32 bits. Since it is a 32-bit number, you can store values from -2 billion to 2 billion. 
LongType: a whole number type stored in a 64-bit number. You can store a much larger number here than in the intType. 

Default Value You may specify a default value for the attribute here. 
Allow Null Leave the checkbox deselected to make the attribute mandatory; null value is not allowed in this case. 
Select the checkbox to allow null value for the attribute. Example: if let's say a user should always have a Last Name, the Allow Null checkbox must be deselected. 
Localizable Select the checkbox to be able to add entries for different languages. A good example is a Name of the Service. When you are logged in as a German user, you see the German name. When you are logged in as an English user, you see the English name. 


The Relations dialog page allows you to add relations between DDs. Example of a relation: a person with a birthday, address, etc. stored in the database. This person also has an account in the system which is a different item. A person may have several accounts: e.g. Google account, Matrix42 account, etc. To define the relation between the person and accounts of the person, use the Relations dialog page. The Accounts relation is a 0/1 to N relation. This means that an account can have an owner or not; 0 or 1 person can have N accounts. An account never has more than one owner, but a person can have many accounts. You can navigate relations with ASQL. Names of relations cannot be changed after you define them, at least from the UI. This is important for ASQL. If you want to navigate from a user to its accounts with ASQL, use the Relation Attribute Name (Accounts). If you want to navigate from an account to its owner, use the Relation Attribute Name (Owner). 

A relation connects two different DDs and, normally, these two DDs are used in different CIs.
A Technical Name is automatically generated for you and you cannot change it.
You can define a Display Expression (ASQL) for a Relation but this is not a normal case. Normally, a relation points to some DD and if there is no explicit Display Expression on this Relation, the Display Expression for this Relation is the DD of the target's DD. 

There are other types of relations. 

  • N to M relation: not only a user can be in several roles (an Administrator, a License Manager, an Incident Manager, etc), a role can have several members.
  • N to 1 relation says, for example, that an account must have, for example, an owner. 
  • N to 0/1 relation says an account might have, for example, an owner or not.
  • 1 to 0/1 and 0/1 to 1 relations: please do not use these types. 


Field Name  Field Description
ID Every schema item in our database has an ID which is a unique Guid. You cannot change the ID but you can view it. 
Protection Level Possible options: Custom, Customizable, System. A user can only add and change something that is Custom, change something that is Customizable, and cannot add or change something that is System
Enable History You can disable the history for the DD (table) with the help of this checkbox. Whenever you change something in our system and the Enable History checkbox is selected, the change will be written to the History database. You can later check the changes using the History action in the UI. 




  • Was this article helpful?