Automatically Link Assets

In the Administration > System > Automatic links page, you can use Quable’s rule engine to specify the conditions for automatically linking uploaded assets to your existing documents.

❗️
An automatic link only works for a single document type. You must create individual automatic links for each document type that you want to automatically link your assets to.

Naming Convention

Automatic links require that your assets use a specific naming convention. This naming convention is interpreted by the defined rule to know which documents to link the assets to. Therefore, all assets that should be linked via a specific automatic rule must follow the same naming convention.

👍
To make the process as easy as possible, we highly recommend keeping your naming convention simple. Your Quable PIM Product Manager can provide you a template to help you create your own naming convention.

In order to link an asset to a document, Quable PIM needs one piece of information in the asset's name:

Required Information	Data Type	Description
Document identifier	Alphanumeric characters	A string of characters that identify a document (document's code or attribute value)

Example 1

You need to automatically link assets to your product document type with the product_main_pictures link type. Your Quable PIM administrator has created an automatic rule to look for this naming convention:

random stringdocument code1.file extension

The rule looks for:

segments with specific data types,
separated by underscores ( _ ), and
a file extension.

The following table provides a breakdown of the segments in this example.

Segment	Data Type	Description
random string	alphanumber characters	This can be any text. The rule only checks that there is some kind of alphanumeric content here.
`document code`	alphanumber characters	This identifies the document to link the asset to. In this case, the target document must be of the document type defined in the Rule If statement (`"target_document_type`).
`1`	number	(optional) This indicates the asset's sequence.
file extension	alphanumber characters	This can be any file extion. The rule only checks that there is some kind of extension is here (e.g., jpg, png, svg).

To comply with this rule for an automatic link, your assets could be named:

	picture_bluejean_1.jpg
	abc123_bluejean_1.png
	random_bluejean_1.svg

As long as the name of the assets are in the correct format and include the document type code and the number 1, the assets will automatically be linked to the correct documents.

Example 2

You need to automatically link assets to to your product document type with the product_pictures link type. Your Quable PIM administrator has created an automatic rule to look for this naming convention:

(random string)document code-8.file extension

The rule looks for:

segments with specific data types,
separated by parenthesis ( ( ) ) and a hyphen (- ), and
a file extension.

The following table provides a breakdown of the segments in this example.

Segment	Data Type	Description
random string	alphanumber characters	This can be any text. The rule only checks that there is some kind of alphanumeric content here.
`document code`	alphanumber characters	This identifies the document to link the asset to. In this case, the target document must be of the document type defined in the Rule If statement (`"target_document_type`).
`8`	number	(optional) This indicates the asset's sequence.
file extension	alphanumber characters	This can be any file extion. The rule only checks that there is some kind of extension is here (e.g., jpg, png, svg).

To comply with this rule for an automatic link, your assets could be named:

	[picture]bluejean-8.jpg
	[abc123]bluejean-8.png
	[random]bluejean-8.svg

Create Automatic Link Rule

🚧
Prerequisite
Coding skills may be required since the process includes creating a regular expression (regex) and two JSON (JavaScript Object Notation) statements.

Step 1: New Rule Form

In the Administration > System > Automatic links page, click the New Rule button. A form is displayed to define the automatic link rule.

Step 2: Rule Name

Define a name for the automatic link rule. The name should be as descriptive as possible.

Information	Request Body Code	Description
Slug	`rule_name`	Enter the name of the rule.

Step 3: Rule Event

When an asset is imported into Quable PIM, it's a mediaupload event. This is the type of event that triggers the initiates the automatic link rule.

Information	Request Body Code	Description
Event	`mediaupload`	This must be entered exactly as shown.

Information

Request

Body

Code

Description

Event

mediaupload

This must be entered exactly as shown.

Step 4: Rule Conditions

Define a JSON statement with the conditions that must be met for the rule to apply:

Information	Request Body Code	Description
Rule if		The conditions that must be met for the rule to be applied. It must be written in the format shown in the example (below). These conditions identify: the type of document the rule applies to, how to identify the correct document type, how to interpret the asset name, and which part of the asset name to use.
	`target_document_type`	The unique code of the document that should be linked.
	`target_value_type=”code”` OR \ `target_value_type=”eav”`	"code" - indicates that the rule uses a document code. "eav" - indicates that the rule uses an attribute value.
	`rule="equal"`	This indicates that the isolated part of the asset name must exactly match the document type or attribute code.
	`from_value_regex`	A regular expression (regex) enabling the isolation of the assets name segments (in parenthesis, also known as capturing groups). The characters needing to be escaped must be escaped twice with a back slash (i.e., \\. for a point instead of .) By default, the first capturing group is looked at unless `from_value_regex_group` is used to specify a group. If you're new to regular expressions, you can refer to this site.
	`from_value_regex_group`	(optional) An integer (number) indicating the capture group to be used for the document search (1 = first group, 2 = second group, etc.).
	`from_value_type="originalfilename”`	This must be entered exactly as shown.
	`from_value=””`	This must be entered exactly as shown.

Step 5: Rule Action

Define a JSON statement with the action to take if the conditions defined in the Rule if statement are met:

Information	Request Body Code	Description
Rule then		The actions to take when the conditions for the rule are met. It must be written in the format shown in the example below.
	`action=createXObject`	This must be used exactly as written. It tells Quable to create a link between the asset and the document.
	`document_type`	The unique code of the doc_type > assetlink to use. The default link type is article_images_media. See Link Types to learn more about creating additional link types.
	`sequence_regex`	(optional) A regular expression (regex) defining the order of the asset. Note*: the sequence number must be included in the asset's `originalfilename`.
	`target_property="originalfilename"`	(optional) Specifies that `sequence_regex` is in the asset's name.
	`side_entity=”target”`	This must be used exactly as written. It makes the asset a child entity of the document it’s linked to.

Example

You have a product document type with an attribute whose code is color. The attribute has two possible values (red, blue). To link the blue.jpg asset to all documents of the product type with blue as the value for the color attribute, your rule would look like:

This is a closer look at a Rule if statement:

{
    "target_document_type": "product",
    "target_value_type": "eav",
    "target_value": "color",
    "rule": "equal",
    "from_value_regex": "\/^([a-zA-Z0-9]*)\\.[jpg|png]\/",
    "from_value_type": "originalfilename",
    "from_value": ""
}

	Rule if logic:
	`"target_document_type": "product"`	The asset should link to a product document type.
	`"target_value_type": "eav"`	The link should be based on an attribute.
	`"target_value": "color"`	Use this specific attribute code.
	`"rule": "equal"`	The asset name must be an exact match to an attribute value.
	`"from_value_regex": "/^([a-zA-Z0-9]*)\\.[jpg\|png]/"`	The name of the asset must be like this: ([a-zA-Z0-9]*) specifies that the asset name must be a string of alphanumeric characters, and [jpg\|png] specifies that the asset must be have a jpg or png extension.

🚧
"from_value_type": "originalfilename" and "from_value": "" should always be written as shown.

This is a closer look at a Rule then statement:

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

	Rule then logic:
	`"action": "createXObject"`	Create a connection object.
	`"document_type": "article_images_media"`	Use the article_images_media link type.
	`"side_entity": "target"`	Use the `"target"` in the Rule if statement.

Use Cases

1. Link to multiple documents

Scenario Response

Can I link an asset to multiple documents?

Yes, if you link on an attribute value. The asset's name must comply with your naming convention and include a segment that's an exact match with the value of the attribute.

Example
To link a video to all the documents that have the design attribute with a value "modern". The video's name could be "modern_video.mp4" if your naming convention is: value_xxxx.extension

In this case, the following parts of the Rule if statement would be changed to indicate that an attribute value should be used:

Rule if	Description
`target_value_type=”eav”`	This indicates that the rule uses an attribute value.
`target_value: "design"`	The attribute code. The required value must be in the asset’s name.
`"from_value_regex": "/^([a-zA-Z0-9])+[a-zA-Z0-9]\.[mp4\|wav]/"`	This indicates that the asset's name should have two alphanumeric segments separated by an underscore and the file extension must be either an .mp4 or .wav.

{
    "target_document_type": "finished_product",
    "target_value_type": "eav",
    "target_value": "design",
    "rule": "equal",
    "from_value_regex": "/^([a-zA-Z0-9]*)+_[a-zA-Z0-9_]*\\.[mp4|wav]/",
    "from_value_type": "originalfilename",
    "from_value": ""
}

The Rule then statement indicates that the "picto_image" link type should be used to link the asset to the "target".

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

2. Link to document and variant

Scenario	Response
Can I link an asset to a document and its variant?	Yes. In this case, you can create two rules that will be executed sequentially: a rule for documents and a rule for the document's variants. If there is no corresponding document, the second rule will check whether or not there is a variant. The asset’s naming convention could be like this: `document_code__variant_code__xxxx.extension`

Scenario

Response

Can I link an asset to a document and its variant?

Yes. In this case, you can create two rules that will be executed sequentially:

a rule for documents and
a rule for the document's variants.

If there is no corresponding document, the second rule will check whether or not there is a variant.

The asset’s naming convention could be like this:

document_code__variant_code__xxxx.extension

2.a Use specific link

Scenario	Response
Can I link an asset to a document and its variant via a specific link (e.g., "texture")?	Yes, you can specify the link in the Rule then statement. Using the previous example, the asset’s naming convention could be: `document_code__variant_code__text1889_xxxx.extension` In this case, the rule logic would be: IF `document_code` is found, THEN use the "texture" link (`"document_type":"texture"`).

Scenario

Response

Can I link an asset to a document and its variant via a specific link (e.g., "texture")?

Yes, you can specify the link in the Rule then statement.

Using the previous example, the asset’s naming convention could be:

document_code__variant_code__text1889_xxxx.extension

In this case, the rule logic would be:

IF document_code is found,
THEN use the "texture" link ("document_type":"texture").

Scenario	Response
Can I link an asset to several document types via a single automatic link rule?	No. It’s not possible to declare multiple automatic links via the same rule. If an asset needs to be linked to multiple document types, individual links must be created for each document type.

Scenario

Response

Can I link an asset to several document types via a single automatic link rule?

No. It’s not possible to declare multiple automatic links via the same rule.

If an asset needs to be linked to multiple document types, individual links must be created for each document type.