Categorization data source

Categorization Data Source is a data source type that enables you to use a database query for creating object categories. For example, you could categorize objects according to their construction status (purchased/delivered/installed) or risk level (low/medium/high). When such categorizations exist, the user can select a suitable category from the visual style or hierarchy drop-down menu of the Model tab and then view objects that relate to the given category.

Creating a categorization data source

Create a categorization data source to enable users to easily locate and view objects that relate to a specific category.

Prerequisites

The project contains a database adapter that can connect to the database that contains the categorization information. See Creating a database adapter if needed.

Do the following:

Navigate to the project to edit, and then click Project Admin in the main menu. The project administration view opens.
Click Adapters and Data Sources. The Adapters and Data Sources configuration view opens.
On the Adapters list, click the database adapter to which to add the data source.
In the adapter settings, click Add data source, select the data source type Categorization Data Source, and then click Create data source.
In the Data Source section, specify the following settings:

Name – Enter a name for the data source.
Description (optional) – Enter a description for the data source.
State – Specify whether the data source is disabled or enabled (default).

In the Groups allowed to see the data section, select user groups that should be allowed to see the data that this data source provides.
- If no groups are selected, only administrators will see the data.
- Add user groups with Add.
- Remove user groups with the remove button.
- If the All Users group is selected, other group selections will be ignored.

The Adapter Configuration section is read-only.

Specify the Data Source Configuration settings:
- Caching – This setting defines if data source categorization is always fetched from the data source or if a cached categorization is used.
  - Disabled (default) – The data source categorization is always fetched from the data source.
  - Enabled – The data source categorization is fetched from the data source when eShare is started or when a data source is configured. After that caching is renewed in intervals defined in Caching Interval field. The value is given in minutes.
- Visual Style – When this setting is enabled (default), the user can select the attribute from the visual style drop-down menu, and the 3D view highlights objects with value-specific colors.
  - Conflict resolution – This setting specifies which category should override others when multiple categories are defined in this configuration and the database query returns several matches: First Category, Last Category, or the special Multiple Categories category.
- Hierarchy – When this setting is enabled (default), the user can select the attribute from the hierarchy drop-down menu, and the Models tree lists objects in attribute value specific nodes.
  - Conflict resolution – This setting specifies which category should override others when multiple categories are defined in this configuration and the database query returns several matches: First Category, Last Category, or the special Multiple Categories category.
- Queries – Click Add query and define the tags and the database query to use:
  - In the Tags field, specify which tags in the model should match the query results. In the simplest case, the query returns values of a single tag that is typically a position id such as Valve Position (vpo) or line id such as Pipeline (pli).
    It is also possible to enter multiple tags as a comma-separated list, or use compound tags that combine the values of several tags.
    Do not use group tags in categorization. Instead, use the tag that the members of the group have. For example, use pli instead of [pli].
  - In the Query field, specify the database query. This is an SQL query that returns a number of rows, one row for each model entity for which a category is defined.
    The query should do a SELECT into the database and return the category as the first column, followed by a column for each tag that is needed to identify the model items.
    Example: The database table ValveTable has a Status column that we want to use as a category, and it has a column that contains the value of a single model attribute. If the query is providing data for the Valve Position (vpo) tag based on the database column ValvePosition, the configuration is:
    Tags – vpo
    Query – SELECT Status, ValvePosition FROM ValveTable
    This query will return rows where the category name is derived from the Status column, and the values in the ValvePosition column will be matched against the value of the vpo tag of the objects in the model.
- Categories – Create the categories that should be available to users in the 3D model viewer. You can create a new category manually (click Add category) or generate categories by running the database query (click Refresh).
  The Case sensitivity setting specifies if the value column in the defined categories is expected to be case-sensitive when matching the values to the found values. Case sensitivity does not affect fields that use ranges or regexes (they are always case sensitive). For categorizations created in earlier releases, case sensitivity is disabled by default.
  The Show to user setting specifies what categories are displayed to the user in the visual style and hierarchy drop-down menus.
  - If set to Listed categories, the user will only see the categories that are defined in this view.
  - If set to All categories, the system will create a category for each value that is not defined in this view, and the user will see both manually configured and automatically generated categories. Because these dynamic categories are created on-the-fly and not saved, the color that is assigned to them in visual style might change if the values change.
Specify the settings of each category:
1. Value – The internal category name. This should match a value that the database query returns. Note that it is also possible that the query returns empty/undefined values.
2. Display Value – This is the name that the users see. If left empty, the value of the Name field is shown to users instead.
  
  You can use the same display name for multiple categories, to allow users to view them as a single category.
  
  You can define a display name for categories for which the database query returns an empty Name value. By default their display name is [Empty], and also null values and values that only consist of white space are handled in the same way.
3. Color – If Visual Style is enabled, use the Color tool to pick an appropriate highlight color for categories returned by the query. All categories that are generated by running the query are set to red color by default.
4. Members – Displays the number of matching items that according to the query exist in the model.
Example category configuration:

Note: If the model contains objects that have no matching tags or objects that do not exist in the database, they will be listed as Uncategorized in the model viewer.
You can drag the rows to specify the order in which the categories are to be listed in the model viewer, or click the delete button to delete a category that is not needed.
Click Save.

Multiple tags in categorization data sources

The database that a categorization data source connects to might contain different types of objects that use a variety of tags to store values that can be seen as belonging to the same category. For example, you might want to create a query that finds all objects that have any kind of position id. In this case, you must define multiple tags for the query, and an object will be included in a category if it has any of those tags and the value of the tag matches the category name.

In the Tags field, you define multiple tags by entering each tag on separate line.

For example, if the query is to be matched against the four commonly used position id tags, namely Valve Position (vpo), Instrument Position (ipo), Equipment Position (.n5), and Structural Position (.no), the Tags definition would be:

vpo
ipo
.n5
.no

A query that looks for multiple tags basically functions in the same way as a query that looks for a single tag in that the system compares the query results to each tag separately.

Compound tags in categorization data sources

Some objects in a 3D model cannot be uniquely identified by a single tag, and a combination of tags must be used instead. You can define a compound tag in the Tags field of a categorization data source by entering the required tags as a comma-separated list.

For example, piping spools created with CADMATIC Plant Modeller can be identified by the combination of Isometric Drawing Number (Idn) and Spool Number (spn), and the Tags definition would be:

Idn, spn

A compound tag should only contain tags that are needed to identify the object. All values that the database query returns must match the tag combination, and adding unnecessary tags can have a negative impact on system performance.

You can even include multiple compound tags in a single Tags definition. Each subset must be entered on a separate row and consist of the same number of individual tags.

For example, if the first compound tag is Idn, spn, any additional compound tags must consist of two tags as well. If we add a second compound tag that is based on Pipeline (pli) and Spool Number (spn), the Tags definition would be:

Idn, spn
pli, spn

When using compound tags, the database query needs to refer to one column per included tag, instead of just a single column.

For example, if Isometric Drawing Number (Idn) and Spool Number (spn) are used to form a compound tag, the query could be something like this:

Tags: Idn, spn

Query: SELECT Status, DrawingNumber, SpoolNumber FROM SpoolTable

Categorization data source and hierarchy levels

When using a categorization data source, the top level that the user sees in the hierarchy drop-down menu of the Models tab is always a category name. At lower levels the menu items represent the tags that the queries use; the second level in the hierarchy is based on the first tags in the queries, and so on.

If only a single tag or multiple single tags are used, the objects are listed directly under the categories. If compound tags are used, the first tags in each compound tag represent the second hierarchy level, the second tags represent the third hierarchy level, and so on. If the same tag occurs multiple times, only the first occurrence is used as a hierarchy level.

For example, if the query uses Isometric Drawing Number and Spool Number, the hierarchy will have the category as the first level, Isometric Drawing Number as the second level, and Spool Number as the third level.