Data Definition

Overview

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 the 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 the system 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.

Data Definition Types

The DDs of these class types are the basic elements of a CI and only they can be added to a CI as members.

Data Definition: 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.
Common Data Definition: If your design needs the same DD in a lot of CIs (approximately more than 10) you should use a Common Data Definition.
Simple Data Definition: 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 Configuration Item Base: DDs of this type cannot be added to a CI, but they can be used as the base for a CI. See also Simple Configuration Item page for more details.
Pickup: A Pickup is a lookup table, that normally relates a simple number to 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. See also Pickup Data Definition page for more details.
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):

Go to Matrix42 → Administration → Schema → Data Definition → Classes.
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.

General

Internal Name	Provide a name for the DD to be used internally. All Internal Names added by customers have the Ud_ prefix (stands for user-defined) automatically added to them. An example of a customer-defined Internal Name would be 'Ud_Workplace'. The user-defined prefix can be changed in the Global System Settings of the Administration application (see General information section).
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 can be modified as necessary.
Description	Provide a detailed description of the Data Definition here.
Class Type	Choose one of the available DD types: 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 attributes with respective internal names.

Attributes

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.

To add a new attribute to the Data Definition fill out the following fields:

Field Name	Field Description
Internal Name	Internally used attribute name. All Internal Names added by customers have the Ud_ prefix (stands for user-defined) automatically added to them. An example of a customer-defined Internal Name would be 'Ud_Workplace'. The user-defined prefix can be changed in the Global System Settings of the Administration application (see General information section).
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 can be modified as necessary.
Description	Optional description of the attribute.
Enable History	Check-box options: disabled (default): the attribute changes are not tracked and not recorded to the History database. enabled: attribute changes will be written to the History database. You can later check the changes using the History action in the user interface of the corresponding Configuration Item which includes the current Data Definition; This option is only one of the conditions that are necessary to track changes in the specific attributes of the Data Definition. The detailed description and all required settings for the History tracking are available on the History wizard page.
Type	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. For more details see the description of the Support Multiple Currencies checkbox on the Configuration Item page. DateType: Use for dates. DecimalType: Something that has a defined scale (number of digits after the decimal point) and precision (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. For more details, see also Microsoft Documentation: Type float page. 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. intType range: -2,147,483,648 to +2,147,483,647 LongType: a whole number type stored in a 64-bit number. You can store a much larger number here than in the intType. LongType range: -9,223,372,036,854,775,808 to +9,223,372,036,854,775,807
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 the 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.
Contains HTML	The checkbox is present only for attributes of types "String" and "Text". Signals the System to perform an HTML Sanitization procedure of the data before saving it to the database. The HTML Sanitization removes advanced attributes and potentially unsafe tags in order to prevent malicious code from being injected, while the basic text styling or font changing tags are kept. Applying the sanitization for the HTML which could be rendered in User Interface is very important for System security and allows preventing Cross-site Scripting attacks (XSS).
Link to Pickup	This section can be configured for the Data Definition attributes with intType in the Type field. Pickup: choose the necessary Data Definition of a Pickup type; Referenced Attributes of the Pickup: the drop-down list suggest suitable attributes from the specified Pickup Data Definition.

Relations

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.

Click on the relation attribute to view the details and configure the relation properties:

Enable History: select the check-box to automatically save the relation attribute changes to the History database. The configuration of this option and its usage is similar to the enable history property of the data definition attribute.

Advanced

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: all manually created DDs by default have custom protection level (custom attributes). This protection level denotes that the DD's structure can be modified, extended or reduced at your own choice and necessity; Customizable: the DD has basic components that cannot be removed from the DD structure (system attributes). Such DDs structure can only be extended with manually added Attributes (custom attributes). System: DD structure and attributes are system components (system attributes) and their structure cannot be modified in any way.
Enable History	Check-box options: disabled (default): the history for the Data Definition (table) is not saved; enabled: allows keeping track of the changes in the attribute values of the current Data Definition and record them to the History database. This option is only one of the conditions that are necessary to track changes in the specific attributes of the Data Definition. The detailed description and all required settings for the History tracking are available on the History wizard page.

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: all manually created DDs by default have custom protection level (custom attributes). This protection level denotes that the DD's structure can be modified, extended or reduced at your own choice and necessity;
Customizable: the DD has basic components that cannot be removed from the DD structure (system attributes). Such DDs structure can only be extended with manually added Attributes (custom attributes).
System: DD structure and attributes are system components (system attributes) and their structure cannot be modified in any way.

Enable History

Check-box options:

disabled (default): the history for the Data Definition (table) is not saved;
enabled: allows keeping track of the changes in the attribute values of the current Data Definition and record them to the History database.

This option is only one of the conditions that are necessary to track changes in the specific attributes of the Data Definition. The detailed description and all required settings for the History tracking are available on the History wizard page.

Adding a new Attribute to the DD

Users with access to the Administration application → Schema → Data Definition menu can add new attributes to the Data Definitions with Customizable or Custom Protection Levels.

Custom/Customizable Protection Level

To add an attribute to a Data Definition with Customizable or Custom Protection Levels:

In Administration application → Schema → Data Definition menu;
Click Edit action for the Data Definition with Customizable or Custom Protection Level;
In Attributes view, click icon to add new attribute;
Fill out necessary data;
Click OK and DONE to save the changes.

Data Definition Dialog: adding a new custom attribute

System Protection Level

The data structure of the Data Definition with System Protection Level cannot be extended by a system administrator from the user interface.

In case you need to change the system data structure, create and adjust the script as provided below. Changes to the system data result in data conflicts during the system update.

Changing attribute of a DD

Attributes of the Data Definitions can be customized to meet your organization's needs. It is useful when the attribute value is imported from an integrated system, for example, from Active Directory.

Users with access to the Administration application → Schema → Data Definition menu can edit Data Definitions that have Custom attributes.

In case you need to modify the system data, create and adjust the script as provided below.

Changes to the system data result in data conflicts during the system update.

Changing Custom attributes

To change an attribute of a Data Definition with Custom Protection Level:

In Administration application → Schema → Data Definition menu;
Click Edit action for the Data Definition with Custom Protection Level;
In Attributes view, click the attribute that should be changed;
Modify the attribute as necessary;
Click OK and DONE to save the changes:

Similarly, you may edit the Custom attributes of the Customizable Data Definition.

Changing System attribute with a script

If you need to edit an attribute, you can run a script that will make changes directly in the database.

Any action taken upon the system data modification with the script is strictly at your own risk. Changes to the system data result in data conflicts during the system update. We assume no responsibility or liability for the data loss caused by the modified with the script system data structure.

Example: You need to change the length of the Position attribute for the Account CI. The SPSAccountClassADUSer data definition stores this attribute.

To write a script that will execute this action:

Go to the <Application Folder>\bin folder.

In most cases, <Application Folder> is C:\Program Files (x86)\Matrix42\Matrix42 Workplace Management.
Open the Command Prompt so that it points directly to this folder and execute the following utility:
```
SchemaEL.exe -es -c -fc:SPSAccountClassADUSer -od:C:\Temp\Schema 
```
As a result, the SPSAccountClassADUSer.class file will be generated and placed in the C:\Temp\Schema folder.

The .class file is a script that allows creating, modifying and deleting the structural elements of the Data Definition.

Edit the SPSAccountClassADUSer.class file so that it contains the directive for resizing the Position attribute:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<NewDataSet>
        <BasicSchemaObjectClass>
                <ID>b59407db-cd53-4647-92d1-6fb04c648496</ID>
                <Name>SPSAccountClassADUSer</Name>
                <ActionOnImport>update</ActionOnImport>
                <BasicSchemaAttributeClass>
                        <ID>9387a907-02bc-4e80-b60b-d2829ed50b54</ID>
                        <Name>Position</Name>
      <ActionOnImport>update</ActionOnImport>
      <ActionOnUpdate>resize</ActionOnUpdate>
      <NewAttributeLength>100</NewAttributeLength>
                 </BasicSchemaAttributeClass>
         </BasicSchemaObjectClass>
</NewDataSet>

Put the SPSAccountClassADUSer.class file in the <Application Folder>\bin folder.

Create two more files in the <Application Folder>\bin folder:

The CustomScript.bat file

cd "..\..\Root\bin"
update -schema ..\..\Config\CustomScript\CustomScript.xml ..\..\Config\CustomScript
pause

The CustomScript.xml file

<?xml version="1.0" standalone="yes"?>
<SchemaScripts>
 
        <Script Major="02" Minor="72" Build="0002" Type="class"
Name="SPSAccountClassADUSer" FilePath="SPSAccountClassADUSer.class" />
 
</SchemaScripts>

Run the CustomScript.bat file from a Command Prompt in Windows.
As a result, the length of the Position attribute of the SPSAccountClassADUSer data definition will be set to 100 characters.

Overview

Data Definition Types

Data Definition Dialog Pages

General

Internal Name

Display Name

Description

Class Type

Display Expression

Attributes

Internal Name

Display Name

Description

Enable History

Type

Default Value

Allow Null

Localizable

Contains HTML

Link to Pickup

Relations

Advanced

ID

Protection Level

Enable History

Adding a new Attribute to the DD

Custom/Customizable Protection Level

System Protection Level

Changing attribute of a DD

Changing Custom attributes

Changing System attribute with a script