Configuring REST API categorization data source

Use the REST API categorization data source to categorize objects, for example, based on their status or risk level. For example, in a ship building project, you can categorize the model's objects based on the readiness. The categories have been defined and are maintained in the source system. eShare displays the data in the model.

The REST API categorization data source makes a request to a web server and queries for categorization information. The adapter extracts categorization or model information using JSON queries, and selects items from the response. The adapter maps the extracted data to eShare data using mappings.

Prerequisites

Create the REST API adapter. Familiarize yourself with the target system and its data structure. You also need to understand the basics of programming.

Open the project and the REST API adapter that should have the categorization data source. The REST API adapter is available in the Project Admin view, in the Adapters and Data Sources section.

Do the following:

  1. On the Adapters list, click the REST API adapter to which you want to add the data source.
  2. In the Data Sources section of the adapter settings, click Add data source.
  3. Select REST API Categorization Data Source from the list.
  4. Click Create Data Source.

  5. 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).

  6. 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.

  7. The Adapter Configuration section is read-only. Continue by configuring the categorization.

Configuring the categorization

When you configure the categorization, define a query where you specify:

  • The main list, or array, of the category/attribute data.
  • The data that you need from that list.
  • Mappings to define how the data relates to eShare model attributes. Mappings specify how model data is linked to the JSON data provided by the query. Specify one or more correspondences between selectors and the model attributes. The corresponding values of JSON data model object attributes must match, otherwise eShare cannot create the mapping.
  • The pieces of data that are relevant for the categorization.

A categorization can have one or more queries.

You can create the query either in basic mode or advanced mode.

  • If you use the basic mode, eShare assists you in selecting data.
  • In the advanced mode, you need to code the attribute in a custom selector language that is similar to JavaScript. The syntax is as follows:
    • parent.child
    • array[index]

Test your attribute with the Preview button.

If you need create several similar queries or selectors, you can copy them with the Copy button and modify them as needed.

Do the following:

  1. 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.
  2. 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.

  3. 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.

  4. HTTP request type — Define if the adapter should be able to read data from or also post data to the service.
    • If you select POST, you can specify a body that the system sends with the request. The body must be in JSON format and it its validated while you create it.
    • If you select GET, the adapter can only fetch data from the service.

  5. URL - Build the URL for the external service. The components are target-system-specific, and you can add both static and dynamic elements. Enter static elements of the URL as normal text.

  6. Validate the response by clicking Test.

  7. Custom headers (optional) — Build custom headers if you need to define custom headers to be sent with the data request; for example, for authorization purposes.

    The header is a name-value pair. The components are target-system-specific, and you can add both static and dynamic elements.

    Enter the static elements as normal text.

    Test the response by clicking Preview. eShare returns the JSON response defined in the query.

  8. Continue by creating the query for category data.

Creating the query

The query consists of the array selector, the data selectors, and the mapping-value selectors.

The array selector selects a JSON array, or list, that provides the categorization data. The data selectors select pieces of data from every element in the array. Mappings connect the data to the actual model data and the eShare categorization system.

When you build the query, proceed as follows:

  1. Specify the main array of category (or attribute) data.
  2. Specify the data that you need from the array.
  3. Specify how the data relates to eShare data by defining the mappings. Also define which pieces of data are relevant for the categorization by using the value selectors.

You can create one or more queries for the REST API categorization data source. If you need to define several similar queries, you can copy them with the Copy button and modify them as needed.

Do the following:

  1. Define the main array of the category data. By default, all data in the defined source system is included in the query, but you can limit it. To limit the data, click Select a child and define the list with properties, arrays, or conditions.

  2. Create the property selectors. The query can have one or more selectors. This is the actual data that the categorization needs from the main list. Enter the name in the Name field, and define the selectors with properties, arrays, and conditions.

    Test the response by clicking Preview. eShare returns the JSON response defined in the query. These selectors are available when you create mappings to the model.

  3. Add mappings to the model. Click Add mapping and create the selector–attribute pairs. Select the selector from the Selector drop-down menu and the attribute from the Attribute drop-down menu. Attributes have been defined when creating the eShare project.

    Select the value selector from the drop-down menu. The available values depend on the target system. For example, to categorize objects according to their status, select the value that is related to status.

  4. Create the categories.

    • Case sensitivity – Define if the match should be exact or if text in a different case is accepted. Note that case sensitivity does not apply to range and regular expression values.
    • Show to user – If you selected Listed categories, the eShare user can see only manually configured categories. If you select All categories, eShare creates categories dynamically for values that are not manually configured, and eShare user can see both dynamically created and manually configured categories.

    • From data – Creates a table that specifies how the data is categorized. You can sort and refresh the table, and remove unused categories.

      • The Value column specifies the value in the target system. eShare categorizes the values that match the given categories; other values are left uncategorized.
      • Display Value is the category name that the eShare user can see. If more than one categories have the same display value, eShare merges the categories and they appear as a single category to the user.
      • Color – If Visual style is enabled, select the color that you want to use with the color picker. This is the color that eShare uses to represent the elements in that category.
      • Members – Displays the number of matching items that, according to the query, exist in the model.
      • Special categories – The special categories are Multiple categories for objects that meet the criteria of more than one category, and Uncategorized for objects that do no meet any criteria.

  5. Click Save.