Automation Documentation

Zuletzt geändert von prodexa Admin am 06.06.2024, 11:45

Automation

Introduction

There are many use cases when product data must be validated, cleaned, enriched etc. in automated way based on a customer/user needs.

Today, most of the customers have to do this tasks manually or they did coded customization (not changeable by a customer via UI, not maintainable, problematic for easy upgrades of the software). The users, admins or partners spend a lot of efforts and time into coding rules and actions manually (e.g. using Script Runner, Bulk Actions, Save Event, manual work). In the worst case they export and re-import product data to clean up and validate it externally.

Customer want to define such kind of automation in easy and flexible way inside of PIM. Therefore, we add a new module into PIM which allows users to set up and maintain automated validation, enrichment and cleansing in PIM in an easy and comfortable way.

Goals of the Automation

  • validate product information in an automated process and get a report or notification
  • help to notify users or coworkers about bad data and needed manual enrichment, changes or approvals
  • change product information data based on rules to auto-correct errors, enrich data or create cross-references
  • measure quality of their data (completeness, missing data, level of enrichment, in general or also per sales channel)
  • provide predefined conditions and actions to define automated data improvements
  • make automation reusable in multiple places, e.g. editing process as well as in a bulk operation
  • make easy for users/admins to add additional rules and use different actions

Solution Summary

  • The Automation is organized in Rules Lists.
  • Each Rule List contains the list of Rules.
  • A Rule is defined as a kind of if-then-statement. It contains a Condition (If) and list of Actions (Then) which are performed if the Condition was met.
  • A Rule List is run by user or triggered by events in the system.
  • Depending on the Rule the Actions may update the product or notify users (e.g. via email or notification on UI).
  • The Automation works on one product at a time, not working on other products or updating them.

Examples for a Rule used in Automation:

If required attributes in a product are empty
then set product status to “edit”

If width, length and height exist
then calculate volume

User story

  1. A User can create or update Rule List with necessary Rules. Each Rule contains a Condition and list of Actions.
  2. A User can search the products and select the Rule List to execute it immediately or schedule when it shall run.

Conditions

This list gives an overview on the available conditions.

ConditionDescription
Always true 

Always matches any product so that actions are performed on it

Class: AlwaysTrue

Attributes values are missing

Checks if product doesn't have values or all values are empty for specified Attributes

NOTE: It doesn't check if multi-language Attribute value is missed for the Language, use Translations are missing condition to check that Attributes don't have values for Languages.

Class: AttributesAreMissing

Parameters

  • Attributes - the attributes to check, required, multiple attributes are possible

Result

The involvedObject field of condition contains attributes that don't have values or all values are empty for them. This attributes can be used in Actions.

For example, Add Attribute Value for missing Attributes and Set Attribute Value Status actions use attributes stored in the condition result to modify the product attributes' values for these attributes only.

Also, these attributes can be referenced in such actions as Send Email and Write To Log File by using Freemarker expressions.

Attributes values contain string

Checks if product has attribute values for specified Attributes which contain at least one of specified Strings

Class: AttributeContainsString

Parameters

  • Attributes - the attributes to check, required, multiple attributes are possible
  • Strings - the strings to check, required, multiple values are possible

Result

The involvedObject field of condition evaluation result contains a map with a key corresponding to the attribute object and value - to the set of strings, that attribute value contains respectively. This map can be referenced in such actions as Send Email and Write To Log File by using Freemarker expressions.

Attribute Value has invalid chars

Checks if any of the values of the selected products attributes has any of the invalid chars.

Parameters

  • Attributes - the attributes to check, required, multiple attributes are possible.
  • Chars to be detected - the invalid chars to look for, required, multiple chars are possible, the possible values are:
    •         [^\x00-\x7F] - looks for non Ascii chars.
    •         [\p{C}] - looks for non-printable chars.
    •         [\p{Cc}\p{Cf}\p{Co}\p{Cn}] - looks for control chars.
    •         [\r\n\t] - looks for delimiter chars.
  • Adjustable chars to be detected - the invalid chars to look for defined by a customer, optional.
Classified in ClassificationChecks if the product is assigned to at least one of the Classification Groups of the given Classification
Classification assignment is missing

Checks if product is not assigned to any group from specified Classification

Class: ClassificationAssignmentIsMissing

Parameters

  • Classification - the classification to check, required
Data violates the type definitions

Checks if there are violations in attribute values and compatibility attribute values
(also called "Dirty Data")

  • value does not fit Attribute type
    • boolean must be true or false
    • date must be date stored in the yyyy-MM-dd format
    • decimal must be numeric and with correct decimal separator (internally no thousand's separator)
    • integer must be numeric, no decimals and in integer range
    • long must be numeric, no decimals and in long range
    • text-table is markdown table (so it can be rendered as HTML table)
  • value does not fit Attribute type extension
    • date must be in from/to date range
    • decimal must be in min/max range
    • integer must be in min/max range
    • long must be in min/max range
    • string must match regular expression pattern and has to have length in minLength/minLength range
  • value is not from values in value list specified for type extension
  • there is a multi-valued value in DB (JSON array) for a non-multi-valued Attribute, e.g. ["Value 1", "Value 2"]
  • AttributeValue or CompatibilityAttributeValue has languageID although Attribute was declared as non-multi-language

Class: DataTypeViolations

Result

The list of violations is stored in involvedObject field of condition evaluation result, these violations can be referenced in such actions as Send Email and Write To Log File.

Document assignments are missing

Checks if product doesn't have assignments to document at least for one of with specified View Types

Checks if the product doesn't have assignments to at least for one document with specified View Types.

Class: DocumentsAreMissing

Parameters

  • View Types - the view types to check, required, multiple view types are possible
  • Languages - languages to check, optional, multiple languages are possible

    NOTE: Languages can contain no language item value besides concrete names of languages. That's mean, that condition checks for specified View Types if the product doesn't have the assignment to document with null value in the LanguageId field.

Result

The involvedObject field of condition evaluation result contains a map with:

  • key corresponding to the view type for which there are no assignments for this product
  • value corresponding to the set of languages, that are missed for the specified view Type, if language parameter is not empty, otherwise - to null value. Can contain no language item.

These view types can be referenced in such actions as Send Email and Write To Log File by using expressions.

Prices are missingChecks if a product doesn't have prices of a given type in a given contract. Checking prices is useful to check data completeness and data quality inside PIM. If the product doesn't have prices of a given type in a given contract than all its variants will be checked: all of them should have certain prices.
Product is assigned to Classification GroupChecks if the product is assigned to specified Classification Group
Product header information is missing

Checks if at least one of the specified product's Fields is missing

Class: ProductHeaderInfosMissing

Parameters

  • Fields - the fields to check, required, multiple values are possible, the possible values are
    • Keywords
    • Manufacturer
    • Manufacturer Name
    • Sales Unit Of Measure
    • Unit Of Measure
    • Product ID Extension
    • Valid From/To

Result

The involvedObject field of condition evaluation result contains the set of fields' names for which there are not value. These fields' names can be referenced in such actions as Send Email and Write To Log File by using expressions.

Product Status is

Checks if product is in specified Status

Class: ProductStatusIs

Parameters

  • Status - the status to check, required
Product Status is in range of

Checks if product is in specified Statuses Range

Class: ProductStatusIsInRange

Parameters

  • from - the from part of range, if not specified then not limited by the from part
  • to - the to part of range, if not specified then not limited by the to part

NOTE: both, from and to, can be empty, it means that any status is allowed, practically it means that any product matches the condition

Referenced data is missing

Checks if product contains data which references other objects which do not exist in system

Master Data (Product)

  • catalogId
  • supplierId
  • manufacturerId
  • statusId
  • unitOfMeasureId
  • salesUnitOfMeasureId

Classifications (Product2ClassificationGroup)

  • variant
  • group

Attributes (AttributeValue)

  • attribute
  • status
  • variant
  • language

Documents (ProductDocAssociation)

  • documentViewTypeId
  • languageId
  • status
  • variant

Prices (Price)

  • contractId
  • statusId
  • variant
  • currencyId
  • unitOfMeasureId
  • priceTypeId

Assortments (ContractedProduct)

  • contractId
  • statusId
  • variant
  • currencyId
  • unitOfMeasureId
  • salesUnitOfMeasureId
  • timePeriod
  • visibility

Relations (ProductRelation, direct and reverse)

  • statusId
  • typeId
  • languageId
  • variant
  • relatedVariant
  • relatedProduct

Variants (Variant)

  • statusId

Compatibilities

  • Compatibility
    • variant
    • group
  • CompatibilityAttributeValue
    • attribute
    • language
    • status
  • CompatibilityDocAssociation
    • status
    • languageId
    • documentViewTypeId

Class: ReferencedDataIsMissing

Parameters

  • Cases of - the cases to check, required, multiple values are possible, the possible values are (all cases are selected by default)
    • Master Data - checks references for product master data
    • Classifications - checks references for product groups assignments
    • Attributes - checks references for attribute values
    • Documents - checks references for document assignments
    • Prices - checks references for prices
    • Assortments - checks references for contracted products
    • Relations - checks references for relations (RelatedProduct), direct and reverse are considered
    • Variants - checks references for variants
    • Compatibilities - checks references for compatibilities, including CompatibilityAttributeValue and CompatibilityDocAssociation

Result

The involvedObject field of condition evaluation result contains the map of missed references. This map can be referenced in such actions as Send Email and Write To Log File by using expressions.

Relation to Product or Group existsChecks if the product has or doesn't have a Relation to other products or Classification Group. In case several fields of Relation Types need to be checked it has 'AND' logical operator: all conditions for Product should match.
Required Attribute Values are missing

Checks if the product is

  • assigned to at least one of the Classification Groups of the given Classification. In other case 'Product is not classified in {classificationId} classification' message will appear;
  • these Classification Groups have at least one attribute with parameter 'Required' = true ('Is Required' parameter can be changed in Settings -> Attributes or Settings -> Classifications -> View Groups -> Attributes section). In other case 'There aren't required attributes in the Classification Groups' message will appear;
  • product doesn't have values or all values are empty for attributes which assigned to Classification Groups in specified Classification

Composite attributes and their nested attributes are not checked.

Translations are missing

Checks if the product doesn't have values or all values are empty for at least one combination of attribute and language for specified Attributes and Languages.

NOTE: This condition is similar to Attributes values are missing but also takes into account specified Languages.

Class: TranslationsAreMissing

Parameters

  • Attributes - the attributes to check, required, multiple attributes are possible
  • Languages - the languages to check, required, multiple attributes are possible

Result

involvedObject field of condition evaluation result contains a map with a key which refers to an attribute, and a value - to a set of languages for which there are not values or all values are empty. This values can be used in Actions.

For example, Add Attribute Value for missing Attributes and Set Attribute Value Status actions use this map stored in the condition result to modify the product attributes' values for the attributes and languages in the map.

Also, these attributes can be referenced in such actions as Send Email and Write To Log File by using expressions.

Translations contain stringChecks if product has attribute values for specific Languages which contain at least one of specified Strings.

Actions

This list shows available actions.

ActionDescription
Add Attribute Value

Adds the Value to Product Attribute Value for specified Attribute and Language if value is empty

If Attribute Value exists and Value is empty then just sets Value.
If Attribute Value doesn't exist then creates Attribute Value with specified Attribute, Language and Value.

Supports Freemarker expression in the Value parameter, so it is possible to calculate Value based on the product data.
For example:

<#-- calculate the area -->
${(attributeValues['MC_Depth']!0) * (attributeValues['MC_Width']!0) * (attributeValues['MC_Height']!0)}

<#-- calculate new value based on other attributeValue -->
${(attributeValues['MC_Width']!0) + (involvedObject?size)}
${rules[1].conditionResult.involvedObject[0]}

Class: AddAttributeValue

Parameters

  • Attributes - the attribute to find or create Attribute Value, required
  • Value - the value(s) to add or Freemarker expression to calculate and add calculated value, required, several values/expressions are possible
Add Attribute Value for missing Attributes

Adds the Value to Product Attribute Value for the missed attributes and specified Language

This action only works if Attributes values are missing or Translations are missing condition is used in the Rule, the action uses the missed attributes collected by those conditions to add specified Value.

Supports Freemarker expression in the Value parameter, so it is possible to calculate Value based on the product data.
For example:

<#-- calculate the area -->
${(attributeValues['MC_Depth']!0) * (attributeValues['MC_Width']!0) * (attributeValues['MC_Height']!0)}

<#-- calculate new value based on other attributeValue -->
${(attributeValues['MC_Width']!0) + (involvedObject?size)}
${rules[1].conditionResult.involvedObject[0]}

Class: AddAttributeValueForMissingAttributes

Parameters

  • Language - the language to create Attribute Value, if specified and missed attribute is non-multi-language then it is not used
  • Value - the value(s) to add or Freemarker expression to calculate and add calculated value, required, several values/expressions are possible 
Add Translation

Adds Value to Product Attribute Value for specified Attribute and Language if value is empty.

If Attribute Value exists and Value is empty then just sets Value.
If Attribute Value doesn't exist then creates Attribute Value with specified Attribute, Language and Value.

Supports Freemarker expression in the Value parameter, so it is possible to calculate Value based on the product data.
For example:

<#-- calculate the area -->
${(attributeValues['MC_Depth']!0) * (attributeValues['MC_Width']!0) * (attributeValues['MC_Height']!0)}

<#-- calculate new value based on other attributeValue -->
${(attributeValues['MC_Width']!0) + (involvedObject?size)}
${rules[1].conditionResult.involvedObject[0]}

Class: AddTranslation

Parameters

  • Attributes - the multi-language attribute to find or create Attribute Value, required.
  • Language - the language to find or create Attribute Value, required.
  • Value - the value(s) to add or Freemarker expression to calculate and add calculated value, required, several values/expressions are possible
Assign Classification Group

Assigns the specified Classification Group to product if assignment doesn't exist

Class: AssignClassificationGroup

Parameters

  • Classification Group - the Classification Group to assign, required
Assign Classification Group through Mapping

Assigns Classification Group to product by using specified Classification Group Mapping

Practically if the product has a group that is a source group in a mapping, then a target group is assigned if it is not assigned to a product.

See also value-mapping.

Class: AssignClassificationGroupByMapping

Parameters

  • Classification Group Mapping - the mapping to use, required
Delete Attribute Values

Deletes the Product Attribute Values for specified Attributes

If Attribute is multi-valued the old list of values will be fully deleted.

Class: DeleteAttributeValues

Parameters

  • Attributes - the non-multi-language attributes to delete Attribute Values, required.
Delete Document Associations

Deletes the Document Associations for a list of products in the scope of the given View Types, Status and Languages

Class: DeleteDocumentAssociations

Parameters

  • View Types - the view types to delete Document Associations, required.
  • Status - the status to delete Document Associations.
  • Languages - the languages to delete Document Associations.
Delete Prodct Relations

Delete Product Relations of a given Type and optional Status.

Class: DeleteProductRelations

Parameters

  • Type - the type of Product Relation expected to be removed, required.
  • Status - the status of Product Relation expected to be removed, optional.
Delete Translation

Deletes the Product Attribute Values for the defined Attributes in the scope of the given Languages

If Attribute is multi-valued the old list of values will be fully deleted.

Class: DeleteTranslations

Parameters

  • Attributes - the multi-language attributes to delete Attribute Values, required.
  • Languages - the languages to delete Attribute Value, required.
Replace Attribute IDs using a Mapping

Replaces product Attribute IDs by using specified Attribute Mapping.

Practically if the product has an attribute that is a source attribute ID in a mapping, then the current attribute ID is replaced by target attribute ID.

See also value-mapping.

Class: ReplaceAttributeIdByMapping

Parameters

  • Attribute Mapping - the mapping to use, required
Replace Classification Group through Mapping

Replaces Classification Group product assignments by using specified Classification Group Mapping

Practically if the product has a group that is a source group in a mapping, then the current group is removed and a target group is assigned if it is not assigned to a product.

See also value-mapping.

Class: ReplaceClassificationGroupByMapping

Parameters

  • Classification Group Mapping - the mapping to use, required
Replace Units of Measure using a Mapping

Replaces product Units of Measure by using specified Value Mapping.

Practically if the product has a value that is a source unit type value ID in a mapping, then the current value is replaced by target unit type value ID.

See also value-mapping.

Class: ReplaceUnitOfMeasureByMapping

Parameters

  • Value Mapping - the mapping to use, required
  • Unit types - unit types for replacing, optional (all unit types by default)
  • Contract - products with such contracts for replacing, optional (all contracts by default)

Unit types

  • Unit of Measure (Product)
  • Sales Unit of Measure (Product)
  • Unit of Measure (Price)
  • Unit of Measure (Assortment)
  • Sales Unit of Measure (Assortment)
Send Email

Sends email to specified recipient (To) with specified subject (With Subject) and message (With Message).

The subject and message support Freemarker expressions to access the product data. For example, if it is necessary to mention the Product's ID then use ${product.productId} in subject (With Subject) or message (With Message).

Class: SendEmail

<#if rules[0].conditionResult.success>
<li> attributes are missing:
<#list rules[0].conditionResult.involvedObject as attribute>
- ${attribute}
</#list>
</#if>

Parameters

  • To - the recipient to send email, required
  • With Subject - the email's subject, required
  • With Message - the email's message, required
Set Attribute Value Status

Sets the specified status to Product Attribute Value for the missed attributes and specified Language

This action only works if Attributes values are missing or Translations are missing condition is used in the Rule. The action uses the missed attributes collected by those conditions to set the specified status (To Status).

Class: SetAttributeValueStatus

Parameters

  • Language - the language to create Attribute Value, if specified and missed attribute is non-multi-language then it is not used
  • To Status - the status to set, required
Set Translation Status

Sets the specified status (To Status) to Product Attribute Value for the specified Attributes and Languages.

Class: SetTranslationStatus

Parameters

  • Attributes - the multi-language attributes to update Attribute Value, required.
  • Languages - the languages to update Attribute Value, required.
  • To Status - the status to set, required.
Update Product Status

Updates the product's status to the specified one

Class: UpdateStatus

Parameters

  • To - the status to set, required
Update Attribute Value

Updates Value of Product Attribute Value for specified Attribute.

Supports Freemarker expression in the Value parameter, so it is possible to calculate Value based on the product data.
For example:

<#-- calculate the area -->
${(attributeValues['MC_Depth']!0) * (attributeValues['MC_Width']!0) * (attributeValues['MC_Height']!0)}

<#-- calculate new value based on other attributeValue -->
${(attributeValues['MC_Width']!0) + (involvedObject?size)}
${rules[1].conditionResult.involvedObject[0]}

Class: UpdateAttributeValue

Parameters

  • Attribute - the non-multi-language attribute to update Attribute Value, required.
  • Value - the new attribute value, required.
Update Attribute Value using a Mapping

Updates product Attribute value by using specified Value Mapping for specified Attributes.

Practically if the product has a value that is a source value in a mapping, then the current attribute value is updated by target attribute value.

See also value-mapping.

Class: UpdateAttributeValueByMapping

Parameters

  • Attributes - the attributes to update Attribute Value, optional.
  • Value Mapping - the mapping to use, required.
Update Product Status

Updates the product's status to the specified one (To parameter).

Class: UpdateStatus

Parameters

  • To - the status to set, required
Update Translation

Updates Value of Product Attribute Value for specified Attribute and Language.

Supports Freemarker expression in the Value parameter, so it is possible to calculate Value based on the product data.
For example:

<#-- calculate the area -->
${(attributeValues['MC_Depth']!0) * (attributeValues['MC_Width']!0) * (attributeValues['MC_Height']!0)}

<#-- calculate new value based on other attributeValue -->
${(attributeValues['MC_Width']!0) + (involvedObject?size)}
${rules[1].conditionResult.involvedObject[0]}

Class: UpdateTranslation

Parameters

  • Attribute - the multi-language attribute to update Attribute Value, required.
  • Language - the language to update Attribute Value, required.
  • Value - the new attribute value, required.
Write To Log File

Writes the specified Message into the system log file under the specified log level

<#if involvedObject??>
attributes are missing:
<#list involvedObject as attrId>
- ${attrId}
</#list>
</#if>

Class: WriteToLogFile

Parameters

  • Message - the log message, required
  • With log level - the log level message is written to log file, one of [error, warn, info, debug], required
Create Notification (experimental ⚗️)

Creates Notification for the specified User with specified Type, Subject, Message and Expired date.

The subject and message support Freemarker expressions to access the product data. For example, if it is necessary to mention the Product's ID then use ${product.productId} in subject or message.

See also Notifications and Notifications & Tasks features toggling.

Class: CreateNotification

Parameters

  • User - the user in system who receives notification, optional.
  • Type - the one of info, warning, error or task types, required.
  • Subject - the notification's subject, required.
  • Message - the notification's message, required.
  • Expired In - the time interval when notification expires since action execution, optional.
Create Task (experimental ⚗️)

Creates Task to specified User with specified Subject, Description and Deadline date.

The subject and description support Freemarker expressions to access the product data. For example, if it is necessary to mention the Product's ID then use ${product.productId} in subject or description.

See also Tasks and Notifications & Tasks features toggling.

Class: CreateTask

Parameters

  • User - the user in system who will be assigned to task, optional.
  • Subject - the task's subject, optional.
  • Description - the task's description, required.
  • Deadline In - the time interval which defines the task's deadline since action execution, optional.
Tags:

Navigation