Change detection in asset structures
Many use cases require data modeling in asset structures. For example, in products and layouts. The change detection allows to detect changes in asset structures in the root assets of a structure and triggers a subsequent event.
Prerequisites
None
Introduction
Asset structures store data not only in the asset itself, but in child assets that are related to the root asset with specific asset relations. From the use case perspective, this asset structure can be considered one single asset. However, in the censhare data model, asset structures are not different from any related assets.
The change detection is a module that allows to treat asset structures as one single asset. The module detects, aggregates and propagates changes from the bottom of a structure to the root level.
The change detection can be configured for any type of child/parent assets and asset relation types, and to any depth.
Concept
The change detection module has a three-layer layout:
| Layer 3 | project-specific | The top layer represents the root asset of an asset structure. The root asset receives an Asset structure changed event. Triggered by this event, a generic asset action or a project-specific action can be performed. For example, a start a product export or recalculate a budget. |
|---|---|---|
| Layer 2 | censhare core (framework) | The middle layer works as a buffer. The layer aggregates the single-asset events received from the bottom layer. With a defined delay (cron pattern), aggregated asset events are forwarded to the root asset. The Asset structure changed event that is sent to the root asset does not contain the changes on the child assets in the structure. |
| Layer 1 | censhare core (framework) | The bottom layer monitors the various asset types at the various depths of asset structures, detects changes, and fires an event to the middle layer. This layer works unspecific on individual assets. This can cause a great number of single-asset events, that are triggered in real-time when they occur. |
Technical implementation
The Asset Structure Change Detection module comprises two components: the event emitter and the event batcher. The event emitter listens to changes of individual assets of a specific asset type. This is a standard asset automation that can be configured for any asset event.
If an asset event is detected, the event emitter queries the root asset of the asset structure. The root query can be a direct or indirect parent asset.
The change detection in asset structures can be selective to certain asset types and asset relation types. This is configured in the so-called scenarios. Scenarios contain a selective query to match all desired assets in an asset structure, and listen to any generic asset event.
If a configured event occurs in one of the assets that are matched in the query, the event emitter fires a Signal asset structure change event. This event is mapped to the root asset of the asset structure.
The Signal asset structure change event and the corresponding root asset ID are handed over to the event batcher. The event batcher aggregates all events with the same asset ID. When the configured cron expression (for example every five minutes) triggers the event batcher, it sends a single Asset structure changed event to the root asset. This event does not contain the change events on the child assets of the structure.
Additionally to the Asset structure changed event in the root asset, a third component calculates a hash code of the whole asset structure and compares it to the previous hash code. If the hash codes differ, the configured version feature is incremented by one. The hash code is stored in the root asset in a hashcode feature. This component can be used for development and test purposes and is not required to set up the asset structure change detection!
Default and custom events
In the censhare standard product, two default events are used to configure the asset structure change detection:
- The Signal asset structure change event is triggered by the Event emitter and handed over to the Event batcher.
- The Asset structure changed event is fired by the Event batcher and mapped to the root asset of an asset structure.
The Event emitter and the Event batcher must use distinct events to work correctly! We recommend using the default events whenever possible. For special use cases, you can define custom events.
Trigger follow-up actions
The change detection in asset structures comprises the layers and components described in the previous section. The Asset structure changed event (or your custom event) can be used to trigger project-specific follow-up actions.
Follow-up actions can be performed on the root asset of the structure only, or on the whole asset structure (for example: export a product with all assigned images and texts).
To perform an automated action on the root asset only, you can configure any action in the censhare Admin Client that listens to the event emitted by the event batcher. For more complex actions, you can implement an XSLT-based asset automation that comprises multiple or all assets of the structure.
Configuration
Event emitter
In the censhare Admin Client, open the Configuration/Modules/Asset structure change detection directory, and double click one of the two configurations to create a custom instance:
- Event emitter (event automation) - This configuration can be used for standard use cases where no context information of the source asset (attributes) is needed in the XML query. Especially in scenarios with many change events and a high server load/traffic, this configuration is recommended.
- Event emitter (asset automation) - This configuration can be used for use cases where you want to query context information of the source asset (for example: the language) in the XML query. Be aware that this configuration is less performant and can increase the server load significantly!
| Section/Field | Default value | Description |
|---|---|---|
| General setup | ||
| See Configure server actions. | ||
| Trigger events - the event(s) must occur on the child asset(s) to trigger an Signal asset structure change / Asset structure changed event on the root asset. | ||
| See Configure automatic server actions. | ||
| Scenarios - you can add multiple scenarios in one configuration file. Alternatively, create a configuration file for each scenario. | ||
| Scenario name | - | Enter a name for your scenario. |
| Event fired | Signal asset structure change | Alternatively, select a custom event. This event is handed over to the Event batcher. |
| Query transformation | - | Select a Module / Query asset that contains an XSLT. The XSLT returns the XML query definition. Use this option for complex cases that require more context information from the assets which trigger the event. If you enter the query in the Parent query field below, leave this field empty! |
| Parent query | - | Enter the XML query definition here. For more information, see the Example below. If you select the query in the Query transformation field above, leave this field empty! |
Example
The following snippet queries product assets that are not a template. Next, it queries product item groups and assigned product items. In the product items, it queries images that are assigned as main image. In the target asset, in the asset ID condition, the ID of the asset for which the event was triggered is injected with @ASSET_ID@. This is necessary to grab only the asset that changed in the structure (the asset that fired the event), not any image asset that is assigned to a product item:
<query type="asset">
<condition name="censhare:asset.type" op="=" value="product."/>
<condition name="censhare:asset.currversion" op="=" value="0"/>
<not>
<or>
<condition name="censhare:asset-flag" op="=" value="copy-template"/>
<condition name="censhare:asset-flag" op="=" value="is-template"/>
</or>
</not>
<relation target="child" type="user.product-item-group.">
<target>
<condition name="censhare:asset.type" op="=" value="product.item.group."/>
<condition name="censhare:asset.currversion" op="=" value="0"/>
<relation target="child" type="user.product-item.">
<target>
<condition name="censhare:asset.type" op="=" value="product.item."/>
<condition name="censhare:asset.currversion" op="=" value="0"/>
<relation target="child" type="user.main-picture.">
<target>
<condition name="censhare:asset.id" op="=" value="@ASSET_ID@"/>
<condition name="censhare:asset.type" op="=" value="picture.*"/>
<condition name="censhare:asset.currversion" op="=" value="0"/>
</target>
</relation>
</target>
</relation>
</target>
</relation>
</query>Event batcher
In the censhare Admin Client, open the Configuration/Modules/Asset structure change detection directory, and double click Event batcher to create a new configuration:
| Section/Field | Default value | Description |
|---|---|---|
| General setup | ||
| See Configure server actions. | ||
| Trigger events | ||
| Trigger events | Signal asset structure change | Select the event that you configured in the Event emitter. If you have multiple event emitters that fire different custom events, add all emitter events here or create an instance of the event batcher for each trigger event. |
| Special setup | ||
| Event fired | Asset structure changed | Alternatively, select Signal asset structure change or a custom event. This event is mapped to the root asset of the structure. |
| Cron pattern | * * * * * | By default, the event batcher runs every minute. The appropriate interval depends on the project requirements. For example, a product export can be triggered once a day at midnight, while a synchronization of a product data with an external system must be done every 5 minutes. |
| Events buffer size | 1000 | By default, the event batcher handles up to 1000 events in one run. The buffer size is adequate for high-traffic systems. Adjust the buffer size if you experience any overhead. |
Calculate structure hashcode
The hashcode component is not required for the change detection configuration. The component has some limitations. For example, the relation types to follow cannot be configured currently. However, the component can be used to test your queries and may be used in custom projects.
In the censhare Admin Client, open the Configuration/Modules/Asset structure change detection directory, and double click Calculate structure hashcode to create a new configuration:
| Section/Field | Default value | Description |
|---|---|---|
| General setup | ||
| See Configure server actions. | ||
| Trigger events | ||
| Trigger events | Asset structure change | Select the event that you configured in the Event batcher that is mapped to the root asset. |
| Generic asset events | Added automatically. Do not change. | |
| Special setup - define here how you handle the version increment and hashcode of the asset structure. | ||
| Hashcode feature | - | Select the asset feature, to which the calculated hashcode of the asset structure is written. |
| Version feature | - | Select the asset feature, to which the asset structure version is written. |
Next steps
Set up the Java-based or XSLT-based action to be performed on the root asset or the complete asset structure.