Asset & configuration item design guidelines
Overview design rules
§1 Normalizing attribute values
§1 Normalizing attribute values
Attribute values should be saved in standardized base unit format for easier readability and better post processing. Here it can also be helpful if the base unit is noted in the attribute name. The Versio.io user interface offers a beautify function to convert base units back into a human readable format.
All attributes with base unit values should be converted to these units.
- Time data: convert to coordinated universal time (UTC) in milliseconds
- Data volume: convert to bytes
- Distance: convert to millimeter or meter (dependent on use case)
- Weight: convert to gram or kilogram (dependent on use case)
# Data format of the original data source
{
"myDate": "Fri, 08-11-19, 3:47 PM",
"myVolume": "4 GB",
"myDistance": "42,195 km"
}
# Optimized data format for Versio.io
{
"myDateUtc": 1573224441820,
"myVolumeBytes": 4294967296,
"myDistanceMeter": 42195
}§2 Enrich & splitt attribute values
§2 Enrich & splitt attribute values
Single attributes with more than one information need to be split into multiple attributes. Every attribute value should contain exactly one piece of information.
Data evaluation is easier with each piece of information matched to one attribute. This is helpful for Inventory Analysis and the definition of verification rules in Governance & Compliance.
Importers can also enrich data by adding attributes that are obvious according to other attributes.
# Data format of the original data source
{
"osInfo": "Ubuntu 18.04.06 OS-Kernel 4.5.4"
}
# Optimized data format for Versio.io
{
"osType": "Linux", // enrichment
"osName": "Ubuntu",
"osVersion": "18.04.06",
"kernelVersion": "4.5.3"
}§3 Define a display name attribute
§3 Define a display name attribute
In Versio.io you can select the displayed name of an asset or configuration item. It is displayed as the title of a single instance and in any specified reference or listing in the web interface. This makes it easier for the user to understand which instance it is.
Sometimes there is no suitable attribute from the original data source for the display name. In this case it is useful to add a new attribute in the importer, in which a meaningful short name is created from several other attributes.
# Data format of the original data source
{
"firstName": "John",
"lastName": "Doe"
}
# Optimized data format for Versio.io
{
"displayName": "John Doe",
"firstName": "John",
"lastName": "Doe"
}§4 Mask security relevant or high volume attribute values
§4 Mask security relevant or high volume attribute values
Security-relevant attribute values (e.g. passwords, tokens) should be masked by conversion to hash values when imported into Versio.io. This prevents the security relevant values from being viewed and prevents misuse. However, the conversion into the hash value still allows the change of the value to be recognized.
We use the same procedure to store attribute values in Versio.io that are unreadable for humans and are of high volume. This reduces the volume of data to be stored and makes it easier to display in the user interface.
# Data format of the original data source
{
"password": "MySecretPassword",
"rawNumericList": [10,45,23,67,98, ...] # a really long series of values that are not readable by humans
}
# Optimized data format for Versio.io
{
"passwordHash": "952729c61cab7e01e4b5f5ba7b95830d2075f74b",
"rawNumericListHash": "77c6211491dd37154e42004266f7a6c6b12b4e48"
}§5 Delete inappropriate attributes
# Data format of the original data source
{
"actualTime": "Fri, 08-11-19, 3:47 PM", # changed continuously
"dynamicMeasure": 10, # changed continuously
"constantAttribute": "CONSTANT-VALUE" # constant for every instance and change
"otherAttribute": "myValue"
}
# Optimized data format for Versio.io
{
"dynamicMeasureLevel": "ok", # level defined by treshold
"otherAttribute": "myValue"
}§6 Divide and combine data instances
§6 Divide and combine data instances
When importing data, instances from a data source can be split and combined to structure or condense the information in Versio.io more meaningfully.
The word "divide" refers to splitting one asset or configuration item into several instances. For example, you can split information about a database schema into a database instance and its table instances.
The word "combine" is the opposite. When importing, you create an instance in Versio.io where the attributes are based on several instances from different data sources. For example, you can create a host in which the attribute values from different monitoring products are combined into one configuration item.
The figure on the right shows an example of a database schema that has been separated into the database and the associated tables in Versio.io. This more fine-grained structure facilitates detail recognition and processing.
# Data instances from different data sources
# Dynatrace
{
"host": "prod-qdocker",
"cpuCores": 4,
....
}
# Check_MK
{
"host": "prod-qdocker",
"maxRAM": "4 GB",
....
}
# Optimized data instance for Versio.io
{
"host": "prod-qdocker",
"cpuCores": 4,
"maxRAM": "4 GB",
....
} §7 Avoid JSON objects in arrays
# Data format of the original data source
{
"managementZones": [
{
"id": "6a98d7bc-abb9-44f8-ae6a-73e68e71812a",
"name": "MyName-1",
"description": "MyDescription-1"
}
]
}
# Optimized data format for Versio.io
{
"managementZones": {
"6a98d7bc-abb9-44f8-ae6a-73e68e71812a": {
"name": "MyName-1",
"description": "MyDescription-1"
}
}
}§8 Extend Asset & CI to include relationships among each other and create a topology
§8 Extend Asset & CI to include relationships among each other and create a topology
The mapping of relationships between assets or configuration items during the import process in Versio.io strongly increases the information quality and the possibilities for downstream processing.
We highly recommend that each time you import data, you check to what extent it can be related to the existing data in Versio.io.
It has proven to be good practice to extend the original JSON data object in the following form (see also the example below):
- 'relation': create a separate root attribute within a JSON object to store all relations
- '<entity-name>': create an attribute with the name of the entity and put it under 'relation'
- ['<instance-id>']: create all relations in the form of IDs in an array of the respective entity attribute
# Data format of the original data source
{
"myAttribute": "myValue"
}
# Optimized data instance for Versio.io
{
"myAttribute": "myValue",
"relation": {
"host": ["HOST-EFF871BC6C2DAA1E", "HOST-BC6C2DAA1EFEF871"]
}
}
Keywords