Dimensions

Dimensions allow you to store values for a field in several dimensions, these dimensions are fixed in the configuration.

A dimension can run in two modes. "explicit"(enabled) and "not explicit"(disabled). This always applies per record(pid), as in the following. The dimensions must always be considered independently of each other. So it can be locale "explicit" and channel "not explicit". There is no "order of dimensions".

1. explicit(activated): Within the dimension null cannot exist. All values must be explicitly assigned to this dimension.
2. not explicit(deactivated): In this dimension all entries must be null.

These modes can vary from record to record and can be changed via the API.

Set or Update Dimensions for an Object

Saving beans with dimensions is done using the same methods as normal saving. See PATCH.

Conditions for Saving

• For fields that support dimensions, all dimensions must always be set, otherwise an error occurs.

  Example of error because not all dimensions are set. For field with dimensions channel and locale.

{
  "dimension_field": [
    {
      "value": null,
      "dimensions": {
        "channel": null
      }
    }
  ]
}

• For fields that do not support dimensions, dimensions can be skipped.

  Example:

{
  "not_a_dimension_field": [
    {
      "value": "text"
    }
  ]
}

• Delete all records for a field (all dimensions) from the database

  • When value=null is transferred in the map.

    Example:

{
  "dimension_field": [
    {
      "value": null
    }
  ]
}

{
  "dimension_field": [
    {
      "value": null,
      "dimensions": {}
    }
  ]
}

• Delete the record with channel=web and locale=zero

  Example:

{
  "dimension_field": [
    {
      "value": null,
      "dimensions": {
        "channel": "web",
        "locale": null
      }
    }
  ]
}

WARNING

Warning

The PATCH method deletes all records from the other mode. If an explicit value is set, all entries with null are deleted. If a non-explicit value (null) is set, all explicit values are deleted.

Get Dimensions of an Object

The methods GET return the content of dimensions.

With the GET method, all dimensions in the parameter map under query parameter dimensions should be specified or none. If dimensions are specified, they apply to all fields.

channel = 'web' AND locale = 'de_DE'

If no dimensions are specified, respond to all dimensions.

Rules for the Return of Values

The following always applies in the context of a single data record:

1. If there are no records for the entire field, "dimension_field": null is returned. This means for the GUI that all dimensions are "disabled".
2. If an explicit value is requested, it must be delivered with dimension output if found. If there are only NULL entries in other dimensions, this is also delivered accordingly:

{
  "dimension_field": [
    {
      "value": "text",
      "dimensions": {
        "channel": "web",  // The GUI detects that this dimension is "enabled"
        "locale": null // null or copied from the query, depending on the mode of this dimension. The GUI detects whether this dimension is "disabled" or "enabled"
      }
    }
  ]
}

3. If a field is in "explicit" mode, the <span class="title-ref">null</span> dimension value must never be returned. If no value is found, the value from the query must be copied to the result.
   Example: Request for <span class="title-ref">locale=en\_US;channel=web</span>, but the database only contains values for `fr_FR`:

{
  "dimension_field": [
    {
      "value": null, // Nothing suitable is being found
      "dimensions": {
        "locale": "en_US", // Copied from the query: The GUI detects that the dimension is "enabled"
        "channel": null // null or copied from the query, depending on the mode of this dimension
      }
    }
  ]
}

Configuration of Dimensions

Configuration in the Admin Snap-in

Dimensions can be created and configured in admin snap-in General system configurations \> System settings \> Dimensions:

Here, you can create new dimensions and define the values you require:

Examples:

• You can create a locale dimension if you operate across multiple languages and departments in different countries. For each required country, you can add a dimension value, e.g. en_US, de_DE and fr_FR.
• Or you can create a channel dimension, if you want to store the metadata based on the channel like website or print.

After saving your dimension and clearing the configuration cache, you can add your new dimension to the fields where you require it, e.g. a field "Product Description" or "Retail price". For that, go to admin snap-in Module configurations \> {module} \> Fields. Open the required field and activate your dimension:

in admin snap-in "Fields", you can activate a dimension in a field's detail view

After you have activated your new dimension for at least one field, it will automatically appear as a drop-down with all set dimension values on the system header:

In admin snap-in General system configurations \> System settings \> Dimensions, you can also activate role-based dimensions.

WARNING

Existing Dimensions

Changes to existing dimensions (e.g., changing the dimension name or deleting a dimension value) should be carefully considered in advance, as they may affect existing metadata and configurations, such as workflows.

Configuration in the File System

Alternatively, dimensions can be defined directly in the file system. For this, a file dimensions.xml must be created in folder custom/global/defaults:

The file is structured as follows:

<dimensions enablePermissions="false">
  <dimension type="CEVarchar">channel</dimension><!-- Default: Varchar 20 -->
  <dimension type="CEVarchar" length="20">locale</dimension>
  <!-- <dimension type="CETimestamp">valid_from</dimension> -->
  <!-- CETimestamp wird erst bei Bedarf implementiert. -->
</dimensions>

Currently only the type CEVarchar is supported. Fallback is CEVarchar(20). It follows from this:

• If type not set -> CEVarchar with length 20
• If type CEVarchar -> CEVarchar with length 20
• If type CEVarchar and length=25) -> CEVarchar with length 25

Labels and icon keys are generated for the dimensions created here:

• Label: L-D-<DIMENSION-NAME>
• Icon: D-<DIMENSION-NAME>

Role-based dimensions are per default disabled (enablePermissions=false), see Role-based Dimensions.

Value Options for Dimensions

Value options must be defined for all configured dimensions. For this, a file dimensions{dimension_name}.xml must be created in folder custom/global/value_options:

Example file: dimension_channel.xml for dimension channel:

<?xml version="1.0" encoding="UTF-8"?>
<keys>
        <key>web</key>
        <key>print</key>
</keys>

The value option dimension_channel is generated from this configuration. Value option Key: global.dimension_channel

The translations for key web

• translation=L-V-DIMENSION_CHANNEL-WEB
• info=L-V-DIMENSION_CHANNEL-WEB-INFO
• icon=V-DIMENSION_LOCALE-DE_DE

Presets

Presets are generated for the Value options so that the set dimensions of the user can be saved.

Example: Dimension channel
Preset with the key global.dimension_channel

Role-based Dimensions

Dimensions can be made role-dependent to support a role-based access control for dimensioned metadata fields. This can help prevent incorrect or unauthorized changes to production data.
To enable, activate the "Enable role permissions for dimensions" field (enablePermissions=true) in the admin snap-in General system configurations \> System settings \> Dimensions:

After activation, the "Dimension permissions" tab is available in the role configuration. In this tab, all dimensions are listed and can be assigned read, write or no permissions for the selected role. If your system works with two or more dimensions, all possible combinations are listed and can be handled separately:

• Read permission: Fields in the corresponding dimension are displayed as greyed out (read only).
• Write permission: Fields in the corresponding dimension are displayed as editable.
• No permission: If the user does not have read or write permissions, the field is disabled for them in the interface within the corresponding dimension.

Rights After Activation

By default, role-based dimensions are disabled and all roles have complete access to all dimensions. As soon as you set "Enable role permissions for dimensions" to true, all roles have no access to any dimension, so you need to configure the required permissions per role right away. Use the checkbox in the header to set a value for the entire list:

With active role-based dimensions, you need to consider the following:

• New roles: When you add a new role, its users have no dimension permissions by default.
• New dimensions: When you add a new dimension, the dimension matrix will automatically expand.

In both cases, you need to check the "Dimension permissions" tab immediately and update your settings if necessary.

Primary Key

The primary key no longer works in tables with dimensions. This would have to contain the dimension fields in addition. Then these should not become NULL. For Dimension not set we want to set the value to NULL. The solution is to convert the primary key into a unique constraint that also contains the dimension fields.

NULL values in unique constraints do not work in MySQL. We have to make sure in the source code that no duplicate values are inserted.