Structure Editor

The Structure Editor (Main Menu / Admin / Structure Editor) is one of Txture's most powerful tools. It allows you to configure the Structure (sometimes also called Meta-Model, Information Model or Schema) employed by your Txture server on the fly, without restarting the server.

Basic Modeling Concepts

Txture is based on a simple, yet powerful modeling language. This language provides the following concepts:

Asset Type: An Asset Type (sometimes also called Class or Meta-Class) specifies to which category an object belongs. Each Asset Type also defines which Properties it contains and which Link Types it allows. The relational analogy for an Asset Type is a Table.
Property: A Property is a named slot for a value. It specifies a name, the Property Type (e.g. text, number, ...) and the multiplicity (many-valued: single value or list of values). A single property can be used by many Asset Types. The relational analogy for a Property is a Column.
Link Type: A Link Type connects a source Asset Type with a target Asset Type. Link Types can have linked Properties, just like Asset Types. The relational analogy for a Link Type is a Join Table.
Aspect: An Aspect is a named container for Asset Types and other Aspects. It only serves organizational purposes.

The Structure, consisting of the concepts mentioned above, defines which elements (or instances) can exist in Txture. There are only two kinds of such elements:

Asset: An Asset (sometimes also called Entity or Configuration Item) is a concrete instance of an Asset Type. Its Asset Type defines which Properties and Link Types there are, and the Asset fills those slots with Property Values and Links. The relational analogy for an Asset is a Row in a Table.
Link: A single Link always connects exactly one Source Asset to exactly one Target Asset. Each Link has exactly one Link Type, and can have Property Values according to the Properties defined in the Link Type.

Both assets and links can have an arbitrary amount of properties attached to them. Properties can and should be reused across different asset types or link types by linking them to an asset type or link type. There are different property types that can hold different pieces of data. E.g. there is an integer property type and an email property type among others (see the following list). All properties are either single-valued or many-valued indicating that either one single data object can be stores in this property or several data objects (think of it as a list). For example a single valued integer property can hold one integer (e.g. 8) where a many-valued email property can hold several email addresses (a@b.com, c@d.com).

There is no limit to the amount of properties an asset type can handle, but the total amount of data must not exceed 8MB per asset.

Property type	Example value	Comment
Text	`abc`	Any string in UTF8.
Number	`23.57`	A numeric floating-point value.
Date	`12.08.2016`	Represented by a date picker in the UI.
Timestamp	`1616410244000`	In `ms` since Jan 01, 1970. Similar to Unix Epoch Seconds, but measured in milliseconds.
Duration	`5000`	A timespan in millisecond granularity.
Integer	`5`	A numeric integer value.
Percentage	`0.8`	A percentage value, typically between `0.0` (displayed as 0%) and `1.0` (displayed as 100%).
Currency	`13 USD`	Also available with `CHF` and `EUR`. No automatic conversion.
Boolean	`true`	A truth value, either `true` or `false`. Can be thought of as a checkbox.
Yes/No	`No`	A boolean, but rendered as Yes/No.
On/Off	`On`	A boolean, but rendered as On/Off.
IP Address	`1.2.3.4`	An IP address. Leading zeroes are ignored, i.e. `001.002.003.004` is the same as `1.2.3.4`.
Range	`[3.0; 12.5]`	A numeric range with inclusive lower and upper bounds.
Range of date and time	`12.08.2016 11 AM to 16.08.2016 4 PM`	Represented by a dual date-time picker in the UI
Range of date (without time)	`12.08.2016 to 16.08.2016`	Represented by a dual date picker in the UI
Range of integer value	`[5000; 20000]`	Same as a regular range, but both bounds are integer values.
Enumeration	`Low, Medium, High`	Represented as drop-down in UI. The available values are customizeable.
Version	`23.4.0-RELEASE`	A semantic software version (semver) following the pattern `major.minor.patch`.
Multiline Text		Same as `Text`, but will be displayed as a text area, rather than a single-line text field.
Text with Markdown support		Markdown in such a property will be rendered (e.g. `bold` or `italic`)
URL	`https://txture.io`	Will be rendered as a clickable link in the UI
Phone	`123-456-789`	Styled with a in the UI. No format constraints are imposed here.
Email address	`a@b.com`	Rendered as a clickable email link
Corporate Internal ID of User		Used in conjunction with user importer and/or SCIM. Holds the external user ID.

In short, the Structure Editor allows you to modify the Structure part of the example above, while keeping the concrete Assets and Links in sync with your structural changes. The relational analogy for the Structure Editor is a DDL Statement such as ALTER TABLE.

In addition to the content-related aspects of the modeling language, there is also a number of concepts which concern themselves strictly with the way the data in the model is displayed.

One example of such display-related concepts is the Priority. Many elements, including Aspects, Asset Types and Properties, have a Priority attached to them, which allows the User Interface to display them in a certain order. Given a set of elements, the element with the highest priority will be displayed first. Elements which do not have a Priority assigned are treated as if they had Priority zero.

Properties can be grouped into Categories. Categories are identified by their name, and Properties within the same category will be displayed together whenever possible. Within each Category, the Priority sorting rule applies. It is also possible to sort categories by changing their order with a Change order of property categories operation. Navigate to the lower end of the properties section in the right panel to configure their order after adding the operation.

Navigating the Structure Editor View

This report is subdivided into three parts:

The left panel shows your current list of Refactoring Operations (see below).
The middle panel shows a visualization of your current Structure, including all Refactoring Operations in the left panel.
The right panel acts as an inspector. It shows the details of the element you have selected in the middle panel. When nothing is selected, it displays a list of all Types and their linked Properties, grouped by Aspects.

You can left-click any element in the middle preview panel to reveal its incoming and outgoing Link Types as well as inspect its details in the right panel:

Left-clicking the same element again will deselect it. You can also select any of the Link Types:

Modifying the Structure

The Structure Editor contains a wide range of Refactoring Operations. A Refactoring Operation takes your Structure (as well as your Assets and Links) and transforms it into a new Structure. Some Refactoring Operations have little impact, others will heavily modify your structure.

Use the Preview

The Structure Editor is a very powerful tool - it should be used with care. As a general rule, nothing you do in the Structure Editor will be actually applied onto your Txture instance, until you click on the Apply Changes button, so feel free to experiment and investigate the Structure Preview closely before saving.

For Time Machine Users

If you use the Time Machine, you will notice that your changes to the Structure are only applied to the latest version. If you look at past data, you will still see the Structure as it was at that point in time.

There are several ways in which you can create a Refactoring Operation. The most general way (by which all operations are accessible) is by clicking on the Add operation button:

This will bring up an overlay, listing all available Refactoring Operations grouped into tabs by the element type:

After clicking on Add, the selected operation will be added to your current session in the left panel:

Once the form is filled, the Refactoring Operation will be carried out on your Structure Preview. It will not take effect on your actual data yet. You should closely inspect the results of your operation on the Structure Preview. Also keep an eye on the warnings and errors produced by your Refactoring Operations. They are displayed right below the list of operations in your current session.

In this example, we added a Property (called My New Property). Since it is not linked to any Type it is useless - and the editor reports this as a warning.

Keep your Structure clean

We strongly recommend that you fix the cause for all warnings and errors before you click on Apply Changes. A Structure which exhibits errors or warnings is likely to cause troubles later on.

After completing one Refactoring Operation, you have several options:

Continue by adding the next Refactoring Operation.
Modify the details of Refactoring Operations in your current session.
Remove Refactoring Operations from your current session by clicking on their icon.
Cancel your session and discard the changes by clicking on Reset.
Commit the changes of your session and apply them to your actual data by clicking on Apply Changes.

Alternative ways to create Refactoring Operations

Since entering all details for a Refactoring Operation can be cumbersome, there are several useful shortcuts integrated into the Structure Editor. For example:

To add a Remove operation, simply select the element you wish to remove in the preview, and click on the Remove button in the right panel.
You can also insert Rename and Change Priority operations in a similar fashion: select the element, then use the appropriate button in the right panel.
To add a Link Property operation, select an Asset Type or Link Type in the Structure Preview, then scroll down in the right panel to find its Properties. The Link Property button located right below the current properties.

All of those shortcuts will add the appropriate Refactoring Operation to the session list and pre-fill the operation details form accordingly.

Applying Refactoring Operations

After adding Refactoring Operations to your session, reviewing the Structure Preview and resolving the reported issues, you can apply your changes by clicking on the Apply Changes button. You will be asked to enter a short description of your work for future reference.

Your changes will then be pushed onto the Task Scheduler and executed at the next possible point in time. The User Interface will display the progress of this task. If another scheduled task (e.g. an Importer) is currently running, your Refactoring Task will be delayed until the other task is complete. While a Refactoring Task is running, the Txture Server will automatically be switched into Maintenance Mode (and will exit Maintenance Mode again when the task is complete).

Major Refactorings take time

Depending on the Refactoring Operations in your session, applying them can take several minutes or (in extreme cases) even several hours. As an active Maintenance Mode is required, the Txture Server will not be available to regular users during this time. While users with the admin User Role can still log in and use the Txture web UI, the Txture Server will not allow any modifications and may appear unresponsive due to the workload of the refactoring. Users without admin role cannot log in during the refactoring.

We recommend applying major refactorings during time periods where Txture is not actively used by many users.

Advanced: Managing Indices

In addition to the data stored in the properties of your assets and links, Txture can create and manage indices on them. In literature, such indices are often referred to as "secondary indices".

What is an Index?

An index is a lookup table that is stored on the hard drive in addition to the data itself. For example, an index on the Migration Status property may look like this:

`Migration Status` Value	Application / Asset
In Migration	CRM App
In Migration	Order Processing App
Descoped	Employee Management App
Migrated	Reporting App

An index in Txture will always cover all Scenarios, including As-Is, Cloud Scenarios (such as the Target Architecture) and other (custom) Scenarios. Indices support over-time-queries and historic queries as well.

Advantages of an Index

Having an index on a property can greatly increase the performance of queries that operate on this property, in particular:

Search for values of an indexed property (e.g. using the query bar in the Repository)
Grouping by an indexed property (e.g. in Donut Chart visualizations)
Sorting by an indexed property

The positive effects of an index on query performance become more pronounced as more data is added to the repository.

Txture will automatically make use of all suitable indices for query processing whenever the opportunity arises. This will not change the actual query result, only reduce the time it takes to compute it.

Costs of an Index

An index on a property has significant performance benefits, but the index itself needs to be managed and therefore consumes resources. This is the reason why Txture does not simply add an index to all properties by default.

As indices have to be stored on the hard drive, they increase the on-disk footprint of your Txture instance. The on-disk size of a secondary index depends on a wide variety of factors (such as the total number of properties, the actual property values, the type and multiplicity of the property, ...). As a general rule of thumb, expect that adding an index to existing data will increase the disk footprint of your Txture instance by 1%-3% for each index.

Since every index needs to reflect the state of your data, indices need to be updated whenever your data changes. This leads to a small computational overhead in processing time whenever you make changes to the data stored in the repository. This overhead will become more noticeable the more indices you add to your data.

Managing Indices in the Structure Editor

The following refactoring operations can be used to manage indices:

Add Property: Allows to add an index to the newly added property, if desired.
Remove Property: This operation will automatically remove the index for the removed property (if there is one).
Add Property Index: This operation is used to add an index to an existing property (if it doesn't already have one). Adding an index to an existing property (especially when including the history) can take a lot of time.
Remove Property Index: Removes an index (if there is one) from a specified property, without changing the property itself.
Change Property Type: An index is always bound to a type. Changing the property type means that a new index has to be created.

Indices on Built-In Properties

You can only manage indices in the structure editor which target your custom properties. Properties which are built into Txture (such as Name, Description, Creation Date, etc.) will have their indices managed by the Txture development team.

Supported Property Types for Indexing

The following property types are supported for indexing (for both single- and many-valued variants):

Text (and all derived types, e.g. URL, multiline, markdown, Version...)
Enumerations
Numbers (and all derived types, e.g. Integer, Percentage, Currencies, ...)
Dates (and all derived types, e.g. Date-Time)

Ranges and booleans (including their derived types) are currently not supported for indexing.

Best Practices for Indices

Do not add indices to all properties blindly. This will not only needlessly increase the disk footprint, but it will slow down operations that change your data (e.g. importers, consolidations, manual changes...).
Create indices on properties that are often used for querying, sorting and grouping. Those are the indices that will provide the highest benefit.
When adding an index to an existing property, please consider that this is an intense operation that can potentially take a long time to complete (depending on your data and the size of your history).

Domain Models

Lern more about semantic tags and domain models in the dedicated documentation page about Domain Models.

List of Refactoring Operations

General Operations

| | | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Operation | Description | Notes and Side Effects | | Rename | Renames an arbitrary Structure element. | Renamings can break Change Propagation Rules and Importer setups. You will receive a warning in the Structure Editor if this is the case. | | Change Description | Changes the description of an arbitrary Structure element. | — | | Change Priority | Changes the Priority of an arbitrary Structure element. | The priority typically affects the ordering of structure elements. E.g. sibling aspects or properties are ordered (and visually sorted on any occurence in the user interface) from higher priority to lower priority. | | Change Feature Multiplicity | Changes the number of values that can be assigned to a Property or the number of assignable targets for a Link Type. Mandatory values that are defined via multiplicity (e.g. "oneToMany") are currently not interpreted. | If the multiplicity of property values or Link Type targets is reduced from many to one then the first encountered value or target is kept and all remaining values or targets are removed. |

Aspect Operations

| | | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Operation | Description | Notes and Side Effects | | Add Aspect | Adds an aspect to the structure and optionally links it to a parent aspect. | — | | Remove Aspect | Removes an aspect from the structure. | All Asset Types assigned to this Aspect get their parent aspect unset. All Aspects for which the removed Aspect was a parent, get their parent unset. Optionally, those "orphan" elements can be automatically re-wired to the parent of the removed aspect. | | Change Parent Aspect | Removes an Aspect (or Asset Type) from its current parent (if any) and adds it as a child to another existing parent aspect. | — |

Asset Type Operations

| | | | ----------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Operation | Description | Notes and Side Effects | | Add Asset Type | Adds an Asset Type to the structure and optionally links it to a parent Aspect. | — | | Remove Asset Type | Removes an Asset Type from the structure. | All Assets belonging to the removed Asset Type will be removed as well. Furthermore, all Link Types and corresponding relationships between Assets will be removed. Removing an Asset Type can also have a strong impact on Importers and Change Propagation. | | Change Asset Type Icon | Changes the icon of the specific Asset Type. | All Assets of this Asset Type will have the specified icon in all Reports. This operation has no impact on the Assets belonging to the Asset Type. | | Add Semantic Tag to Asset Type | Adds a Semantic Tag to an Asset Type. | Tag Requirements will be evaluated automatically, and reported as warnings if they are not met. | | Remove Semantic Tag from Asset Type | Removes a Semantic Tag from an Asset Type. | All Tag Requirements will also be removed. |

Link Type Operations

| | | | ---------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Operation | Description | Notes and Side Effects | | Add Link Type | Adds a Link Type to the structure by linking to a source (owning) and target Asset Type. | — | | Remove Link Type | Removes a Link Type from the structure. | All Links that correspond to the Link Type get removed as well. Removing a Link Type can also have a strong impact on Importers and Change Propagation. | | Invert Link Type Direction | Inverts the Link Type by swapping its source (owning) and target Asset Type. | Depending on the number of affected links, this operation can take a while to execute. Also, this operation can have a strong impact on Importers and Change Propagation. | | Change Link Target | Changes the target Asset Type of a Link Type. | All relationships that correspond to the Link Type get removed. | | Add Semantic Tag to Link Type | Adds a Semantic Tag to a Link Type. | Tag Requirements will be evaluated automatically, and reported as warnings if they are not met. | | Remove Semantic Tag from Link Type | Removes a Semantic Tag from a Link Type. | All Tag Requirements will also be removed. |

Property Operations

| | | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Operation | Description | Notes and Side Effects | | Add Property | Adds a Property to the Structure. | The operation can be configured to automatically add an index alongside the new property. This operation will execute faster than adding the property, then later adding an index to it. | | Remove Property | Removes the Property from the Structure (and unlinks it from all Asset Types and Link Types). | All values of this property in assets and relationships get removed as well. | | Link Property | Assigns the Property to an Asset Type or Link Type. A Property can (and if semantically the same should) be shared by multiple Asset Types or Link Types. | The secondary index on the property (if there is any) will be removed as well. | | Unlink Property | Removes the Property from an Asset Type or Link Type. | All values of this Property on the Assets and Links that belong to the Asset Type or Link Type will be removed. | | Change Property Type | Changes the Property Type of a Property. | Attempts to convert the values of a Property of the corresponding Assets and Links. Depending on the original Property Type and the new Property Type, a conversion may or may not be possible (e.g. Number to Text will always work, but Text to Number may fail depending on the content of the text). Conversions will be attempted on a per-value basis. Failed conversion attempts can be configured to either unset the value or set it to a default value. Note that changing the property type from Currency X to Currency Y does not convert that values! | | Change Property Category | Changes the Category of the Property. | — | | Add Semantic Tag to Property | Adds a Semantic Tag to a Property. Tag Requirements will be evaluated automatically, and reported as warnings if they are not met. | — | | Remove Semantic Tag from Property | Removes a Semantic Tag from a Property. All Tag Requirements will also be removed. | — |

Index Operations

FAQ

How can the currency of properties be changed Txture currently supports three distinct currency property types: Currency EUR, Currency USD, Currency CHF. The currency can be changed by using a Change property type operation. Note however, that the currency values will not be converted e.g. if the value before the refactoring was 100 USD the new value will be 100 EUR.

What does "many-valued" mean? Many-valued properties allow to configure properties to contain a list of values, rather than a single value. This works regardless of the property type. For example, it is possible to have a many-valued integer property that contains a list of integers.

Basic Modeling Concepts​

Display-Related Concepts​

Navigating the Structure Editor View​

Modifying the Structure​

Use the Preview

For Time Machine Users

Keep your Structure clean

Alternative ways to create Refactoring Operations​

Applying Refactoring Operations​

Major Refactorings take time

Advanced: Managing Indices​

What is an Index?​

Advantages of an Index​

Costs of an Index​

Managing Indices in the Structure Editor​

Indices on Built-In Properties

Supported Property Types for Indexing​

Best Practices for Indices​

Domain Models​

List of Refactoring Operations​

General Operations​

Aspect Operations​

Asset Type Operations​

Link Type Operations​

Property Operations​

Index Operations​

FAQ​