📘

Learning Objectives

• Understand automatic links to associate assets with product sheets or variants.
• Set up a rule based on naming conventions and regular expressions.
• Simplify assets management by automating their linking to products.

Introduction

With automatic links, you can save time and ensure consistency in assets management by defining rules suited to your business needs. This optimizes both the time required and the accuracy when enriching product sheets with assets in the PIM.

This course will guide you step-by-step to set up automatic links between assets and documents or variants. You will learn to define rules to automatically associate assets based on their file names.

👍

Good to know

Programming skills are required to create automatic link rules, as the process involves:

• creating a regular expression (regex),
• JSON declarations.

For support in implementing this feature, reach out to your integration partner.

Understanding the Principle of Automatic Links

Quable PIM's rule engine allows you to establish a match between an asset item and a document or variant, based on a naming convention and regular expressions (regex).

1. An asset item is uploaded to Quable PIM from the DAM, imports, or via API,
2. The rule engine analyzes the file name to extract specific information (such as a product code),
3. An automatic link rule checks if a matching object (product sheet or variant, as appropriate) exists,
4. If a match is found, the asset item is automatically linked to the target.

👍

Good to know

Automatic links are only applied when a asset sheet is created, during the upload of assets in the DAM. They are not triggered when an existing asset sheet is updated or modified.

Definingn a asset Naming Convention

Linking rules work by interpreting the asset name using a regular expression. It is essential to adopt a consistent naming convention so that assets can be correctly associated with documents or variants.

👍

Best practices

• Include a unique identifier of the document in the file name (e.g., product code).
• Use a simple and structured naming format.
• Separate key elements with specific characters (e.g., _, (), -).

Examples of valid file names:

tshirt_1234.jpg
product-5678.png
(item)jeans-42.svg

In these examples, 1234, 5678, and jeans-42 are the identifiers of the documents to link.

Creating an Automatic Link Rule

Access Rule Management

• From the administration menu, under the System section go to Automatic Links.

• Click Create Automatic Link to create a new automatic link rule.

Fill in Rule Parameters

You must define several key elements:

1. Configuration Name (Slug)

• A readable identifier for the rule (e.g., product_images_link).

2. Event

• Indicates the event that triggers the rule.
• Value to always use: mediaupload (corresponds to the creation of a new asset sheet).

3. Define Conditions: Rule if

The conditions that must be met for the rule to be applied. These should be written in the format below, exactly as shown. These conditions identify:

• The type of document to which the rule applies,
• How to identify the correct document type,
• How to interpret the asset name,
• The part of the asset name to use.

Example of JSON Rule if

{
  "target_document_type": "product",
  "target_value_type": "code",
  "target_value": "",
  "rule": "equal",
  "from_value_regex": "/^(\\w+)_([0-9]+)\\.\\w+$/",
  "from_value_regex_group": 2,
  "from_value_type": "originalfilename",
  "from_value": ""
}

🔍 Breaking Down the Parameters

• "target_document_type": "product" → Assets will be linked to documents of type "product".
• "target_value_type": "code" → Linking is done using the document code.
• "from_value_regex": "/^(\\w+)_([0-9]+)\\.\\w+$/" → Regular expression used to extract the document code.
  • Example Match: tshirt_1234.jpg
  • \w+ → Alphanumeric text (e.g., tshirt).
  • _ → Separator.
  • ([0-9]+) → Numeric product code (1234).
• "from_value_regex_group": 2 → The second capture group (1234) is used to identify the document.

👍

Good to know

• When "target_value_type": "eav" is used for a rule based on an attribute value, the default language of the PIM is considered for localized attributes.
• "rule": ”equal”, "from_value_type": "originalfilename" and "from_value": "" must always be written as indicated.

4. Defining the Action: Rule then

This section describes the actions to take when the rule conditions are met. They must be written in the format below, exactly as shown:

Example of JSON Rule then

{
  "action": "createXObject",
  "document_type": "product_images_media",
  "side_entity": "target"
}

🔍 Breaking Down the Parameters

• "action": "createXObject" → Tells Quable PIM to create a link between the asset and the document.
• "document_type": "product_images_media" → Link type (here, linking between a product and its images).
• "side_entity": "target" → Defines the asset as a child of the document.

👍🏼

Good to know

"action": "createXObject" and "side_entity": ”target” must always be written as indicated.

Test and Validate the Rule

Once the rule is created:

• Upload an asset file into Quable PIM, following the defined naming convention.
• Check if the link is created correctly by reviewing the corresponding document's details.

🚧

Warning

• Each rule is specific to a document type. If multiple document types need to be automatically linked, you must create multiple rules, one for each document type.
• The uploaded files must strictly adhere to the defined naming convention.

Edit or Delete a Rule

Edit a Rule

• Access the list of existing rules.
• Select a rule and click Edit.

• Modify the parameters and then click Save.

Delete a Rule

• Access the list of existing rules.
• Select the rule to delete.
• Click Delete and confirm the action.

❗

Attention

This action is irreversible. A deleted rule cannot be recovered.

Best Practices

• Define a clear naming convention and communicate it to the teams.
• Test the rules with different files before large-scale deployment.
• Use precise regular expressions to avoid incorrect associations.
• Create separate rules for each document type.
• Ensure that the asset files strictly follow the syntax defined in the rule.

📘

In Summary

• How automatic linking works: A rule engine analyzes the asset file name and automatically links it to a document or variant if it matches the defined criteria.
• Configuration: The link relies on a regular expression that extracts a key piece of information (e.g., product code) from the file name.
• Creating a rule: Via the administration interface, defining conditions (Rule if) and actions (Rule then) in JSON format.
• Best practices:
  • Adopt a clear naming convention, test rules before deployment, and ensure correct assets file syntax.
  • After creation, test asset uploads to ensure that associations work correctly.

Next Chapter

Congratulations! You've completed the "Setting Up Automatic Links on Assets Import" course. Continue your learning by exploring the next module in the Administrator Training.