Controlling the PDX Channel for Product Onboarding - Validation Engine Attributes

Accelerator for Retail offers the ability to configure advanced category-specific data validations in the PDX channel via a 'configuration language' referred to in PDX as the Validation Engine.

The Validation Engine is a tool that can be used to build advanced ‘product data validations’ without requiring admins to write code. Instead, an expression language is used to create the validations.

As with conditionally mandatory attributes (described above), the Validation Engine is controlled using a metadata attribute on the ‘PDX: Validation Engine’ (STEP ID: PDX: Validation Engine) Product Attribute link. In this way, advanced category-specific data validations can be run on attributes. The ‘PDX: Validation Engine’ attribute is multi-valued and uses the ‘Regular Expression’ validation base type.

In a product hierarchy where an attribute is linked at multiple levels, it is possible to add validations on the Product Attribute link at all levels at which it is linked. Doing so generates multiple validations for the same attribute applied at different levels in the product hierarchy. Note that validations defined at a lower level will not overrule validations defined at a higher level, instead the validations are accumulated. This means that at the lower level, all the validations defined above will apply.

If there is a need to have a distinct set of category-specific validations for the same attribute, the attribute must be linked at the categories that need the distinct validations and then the different validations must be defined at these levels.

Configuration details

Every product data validation created in the ‘Validation Engine’ consists of two or three parts:

  1. Conditions

  2. Error Message

  3. Rule ID (optional)

Product data validations to create validations in PDX are written in the following format, with each element separated by a 'colon' delimiter. Below is a screenshot of the validation format with each element contained within a red box, each specified by a lower-case letter. Below the screenshot is a description of each element:

  1. The logic condition

  2. The keyword that indicates that what follows is the error message

  3. The error message

  4. Keyword that indicates that what follows is the name of the rule

  5. The name of the rule

Note: The error 'occurs' on the attribute if the condition is met.

To ensure each product data validation is unique in the system, all generated product data validations will have an ID with an incrementing number appended to it (e.g., ‘PMDMATShortitemDescription_2’ with ‘PMDMATShortitemDescription’ being the product data validation’s ID and the ‘_2’ the incrementing number appended to the ID).

If no ‘:ruleid:’ is provided in the product data validation, the ID will use a simplified version of the attribute (e.g., ‘PMDM.AT.IsBaseUnit’ becomes ‘PMDMATIsBaseUnit’ with an incrementing number appended to it).

Validation Example

To illustrate how a product data validation is written, a product data validation example, written in the STEP Workbench, is shown in the screenshot below and described in detail in this section.

In this example, the product data validation is written and applied to the ‘Short Item Description’ attribute.

When properly written, this product data validation presents an error to the PDX user when the ‘Short Item Description’ attribute either has no value, or the value for ‘Short Item Description’ is equal to the value for ‘Long Item Description’, meaning the values for both are the same.

Below is the example product data validation as it must be written to accomplish the validation task:

PMDM.AT.ShortItemDescription:==:PMDM.AT.LongItemDescription:||:PMDM.AT.ShortItem
Description:==:null:error:ShortItem Description is required and must be different from Long Item Description

In this example, the product data validation is made up of the following elements:

  • The condition -- This part of the product data validation specifies the data and which aspect of the data is being validated. 

    (<Condition>= PMDM.AT.ShortItemDescription:==:PMDM.AT.LongItemDescription:||:PMDM.AT.ShortItemDescription:==:null:

  • The error message -- If the conditions defined in the product data validation are not met, the text defined in this element are presented to the user. 

     <Error Message>= Short Item Description is required and must be different from Long Item Description

  • Product data validation ID -- In this example, no product data validation ID is set (the ‘:ruleid:’ element). As described previously, the PDX system will generate an ID for the rule that is a version of the validated attribute with an incrementing number appended to the product data validation to ensure the ID is unique in the system.

The error shown in PDX will display as shown in the screenshot below:

Product data validation elements

A product data validation, as described in the example above, is built using simple logical operators, attribute IDs, numbers, and text strings. These elements can be combined to produce advanced validations. In the table below, each element is listed and includes a description of the element and an example of how that element can be written into a product data validation.

Elements Example Description
STEP Attribute ID PMDM.AT.LongItemDescription Refers to a specific attribute value.
Fixed numbers or text strings

20

'Y'

'unsaturated fat'

Refers to a fixed value.

Note: When comparing with LOV values, the 'ValueID' should be used.

Literals should be enclosed in single quotes (').
Comparison

<

==

Simple comparisons can be done to compare numeric values and text strings. Only values from single-valued attributes are supported.

The full list includes:

< -- Less than

> -- Greater than

=< -- Less than or equal to

>= -- Greater than or equal to

== -- Equal to

|= -- Not equal to
Null  

The constant null is used to indicate ‘no value’ and can be used to check if an attribute has no value.

Only values from single-valued attributes are supported.

Logical operators

(

||

Logical operators can be used to group and combine conditions into more complex conditions.

The full list includes:

( -- Start grouping

) -- End grouping

|| -- Logical 'OR'

&& -- Logical 'AND'
Mathematical operators

+

_

The mathematical operators can be used to combine numeric values and produce a calculated value.

Only values from single-valued attributes are supported.

The full list includes:

+ -- Additional

-  -- Subtraction

* -- Multiplication
contains   The ‘contains’ method can be used to check if a value (numeric or textual) includes another value. Multivalued and single-valued attributes are supported.
notContains   The ‘notContains’ method can be used to check if a value (numeric or textual) does not include another value. Multi-valued and single-valued attributes are supported.
isEmpty   The ‘isEmpty’ method can be used to check if an attribute has no values. Multi-valued and single-valued attributes are supported.
isNotEmpty   The ‘isNotEmpty’ method can be used to check if an attribute has values. Multi-valued and single-valued attributes are supported.

To further illustrate how product data validations can be applied to ensure data supplied in PDX meets the configured requirements, listed below are a series of product data validation examples covering a variety of use cases:

  • PMDM.AT.CountryOfOrigin:==:'BS':&&:PMDM.AT.BrandName:==:null:error:If Country of Origin is equal to BAHAMAS, then Brand Name is required

    • In this example, 'BS' is the ValueID of the value ‘BAHAMAS’ in the list of values (LOV) for the ‘Country of Origin’ attribute.

  • (:PERCENTAGE_1:+: PERCENTAGE_2:+: PERCENTAGE_3):>:100:error:The total value of Percentage 1, Percentage 2 and Percentage 3 cannot be more than 100:ruleid:100 Percentage rule

  • SHOELACE_MATERIAL:==:'NOT_APPLICABLE':&&:(:ACCESSORIES_MULTY:contains:LACES:||:ACCESSORIES_ MULTY:contains:SHOELACE:):error:‘Not Applicable’ is NOT an acceptable value for Shoelace Material when Lace is selected for attribute Accessories List.

  • ALL_FEATURES_MULTI:contains:'ADDITIONAL_BURNERS':&&:isEmpty:ADDITIONAL_BURNER_TYPE:error:The Additional Burner Type is required when All Features contains Additional Burners

  • POWERED_MULTI:notContains:”BATTERY_POWERED”:&&:isNotEmpty:BATTERY_TYPE_MULTY:error:The list of Battery types must be empty, when product is not powered by batteries

When writing product data validations, it is important to note the following considerations and limitations:

  • Comparisons, such as ‘==’ and ‘contains‘ are case-sensitive.

  • The method ‘isEmpty’ can be either prepended or appended to the relevant [text] for the same result. This also applies to the function ‘isNotEmpty’. For example, the notation ‘isEmpty:ADDITIONAL_BURNER_TYPE:' and ‘:ADDITIONAL_BURNER_TYPE:isEmpty’ can be used interchangeably.

  • The ‘Validation Engine’ does not support product data validations that validate data containers or data container attributes.

  • Most operations and comparisons do not support attributes with units.

  • Product data validations can only be added and / or defined on attribute links to specification attributes.

  • Product data validations cannot be written to include assets.

  • When writing product data validations, it is important to note that the colon character (‘:’) is a reserved character and should be used only to separate elements in the product data validation. If the character is used in an attribute ID or in an error message, for instance, this may cause the product data validation to error.

Using expressions correctly

As mentioned previously, the ‘PDX: Validation Engine’ attribute uses the ‘Regular Expression’ validation base type. Regular expressions prevent product data validation writers from committing the most frequent notational errors when writing product data validations, but cannot address certain kinds of human error, like misspelled attribute names, for instance.

Listed in the table below are rules that must be followed:

Description

Invalid examples

Valid examples
“:error:” must be present and have non-empty message ATTRIB_A:<=:ATTRIB_B:error: ATTRIB_A:<=:ATTRIB_B ATTRIB_A:<=:ATTRIB_B:error:A should be greater than B
At least one truth valued operator must be present (i.e. + or - is not enough) and attribute names must be separated by operators or parentheses

ATTRIB_A:error:Some message

(:ATTRIB_A:ATTRIB_B:):error:Some message

(:ATTRIB_A:+:ATTRIB_B:):error:Some message

(:ATTRIB_A:+:ATTRIB_B:==:1):error:Some message
“(“ is matched by “)”

(ATTRIB_A:<=:ATTRIB_B:error:Some message

 (ATTRIB_A:<=:ATTRIB_B):error:Some message
if “:ruleid:” is present, then it has non-empty content ATTRIB_A:<=:ATTRIB_B:error:Some message:ruleid:

ATTRIB_A:<=:ATTRIB_B:error:Some message:ruleid:Rule 1
:ruleid can only contain alphanumeric characters and -_#:

width:*:height:>:1000:error:too large:ruleid:Unsanitized$ID

 width:*:height:>:1000:error:too large:ruleid:Unsanitized_ID

Some of the rules above will be caught by the regular expression check.

When product data validations fail, an error message displays that reads, ‘The validation for this rule has failed due to improper syntax. Review the syntax used in the rule.”