DOMS Toolkit

Arno Schwalb Lucas Wedekind könnten wir hier noch eine generelle Erklärung des DOMS Toolkit hinzufügen?

Introduction

Introduction lorem ipsum ...

Please go to the Developer Docs for more information on managing the DOMS via API. The API documentation can be found here.

Toolkit Fences

ToolkitFence fields in detail

Click to see what each field does

entity1

This describes the entity type for the left-hand side. In case of conditional rules this is the entity that gets evaluated first.

entity2

This describes the entity type for the right-hand side. In case of conditional rules this is the entity that gets evaluated second (or never), but more to that later..

active

Whether this fence is active or not

name

The name, has to be unique

nameLocalized

An object containing the localized names for different languages

description - [optional]

An optional description to say what the fence has to do. Although optional, it is strongly recommended that you do give it a meaningful description.

descriptionLocalized - [optional]

An object containing the localized descriptions for different languages

order

A number determining whether the fence should be executed before or after different fences. Lower numbers have precedence over higher numbers.

Rules for toolkit fences

There are two rule types which can be defined:

Conditional Rule

Use "rule" to set up a conditional rule. Can be used for comparing each side against a fixed value (e.g., order line item quantity > 3). Incompatible with using the comparisonRule field. Conditional rules test a certain property of an entity (Order, Facility) against a pre-defined static value.

Steps for defining a conditional rule

operator

What the positive evaluation of the left hand side means for the execution of the fence as a whole. For now, there is only the equality-operator.

leftPart - ToolkitRulePart

The first part that is evaluated. Its evaluation result determines whether the right part gets evaluated.

rightPart - ToolkitRulePart

The second part that is evaluated if the first evaluation passes. Its evaluation result determines the final outcome of the fence.

How to define a ToolkitRulePart

A ToolkitRulePart consists of an array of predicates and a connector that determines how they are connected together.

predicateConnector

OR will make the rule part true if any of the predicates evaluate to true. AND will only make the expression true if all predicates evaluate to true.

predicates

An array of one or more ToolkitPredicates. A predicate consists of the following fields:

• propertyPath

• entityOperator

• expectedValue

• transformation (optional)

• transformationArgs (optional, depends on transformation used)

How to define a ToolkitPredicate

You have to define at least one predicate. In the following we'll explain what each field is used for.

propertyPath

A JSONPath defining the property to look at.

entityOperator

The operators determine how a property of an entity should be compared against a given value. They can be divided up into two groups: Single value entity operators and array entity operators.

Single value entity operators

These operators can only be used for single values, not for arrays, such as VALUE_EQUALS

• VALUE_EQUALS -> actual value equals expected value (e.g. 2 == 2)

• VALUE_NOT_EQUALS -> actual value unequals expected value (e.g. 2 != 3)

• VALUE_CONTAINS -> actual value contains expected value (e.g. "HELLO WORLD" contains "HELLO")

• VALUE_NOT_CONTAINS -> actual value does not contain expected value (e.g. "HELLO WORLD" does not contain "HI")

• LESS_THAN -> actual value less than expected value (e.g. 2 < 3)

• LESS_EQUALS -> actual value less than or equals expected value (e.g. 2 <= 3, 3 <= 3)

• GREATER_THAN -> actual value greater than expected value (e.g. 3 > 2)

• GREATER_EQUALS -> actual value greater than or equals expected value (e.g. 3 >= 2, 2 >= 2)

Array entity operators

These operators can only be used for arrays, not for single values. They can be grouped into three categories: ANY, EVERY, NONE. Within each category, either any, every or no value has meet the criteria. The condition may be anything of the aforementioned single value entity operators. Here are some examples on how this may look:

• ANY_VALUE_EQUALS

• EVERY_VALUE_GREATER_EQUALS (which is equivalent to NO_VALUE_LESS_THAN)

• NO_VALUE_CONTAINS (which is equivalent to EVERY_VALUE_NOT_CONTAINS)

ANY, EVERY and NONE..

ANY

Requires that at least one element of the array satisfies the following condition. It is not required that more than one element match but if the array is empty this condition will NOT be fulfilled.

EVERY

Requires that every element of the array satisfies the following condition. If the array is empty, this condition will be true because there is no element that does not fulfill the condition.

NONE

Requires that no element satisfies the following condition, meaning that every element does not satisfy the condition. This condition will always be fulfilled, unless there is an element that satisfies the condition, including for empty arrays.

Single value operators vs array operators

If your actual value is an array, you have to use an array operator. When is that the case? - If you use a wildcard operator (* or ?()) you get an array of elements (such as $.orderLineItems[*]). However, if you do use a transformer (such as COUNT to get the number of elements or SUM to add the quantities of each OrderLineItem), then you will get a single value and must use a single value operator.

transformation - [optional]

A transformation

transformationArgs -[optional]

The args for the transformation, if required.

expectedValue

The expected value the property should match Examples:

• 2 - a number

• "WAREHOUSE" - a string

• "2024-02-19T16:16:38.107Z" - a date-string

Comparison Rule

Use "comparisonRule" to set up a comparison rule. Comparison rules compare a certain property of the left-hand side (Order) to a certain property of the right-hand side (Facility). Incompatible with using the rule field.

An example of this could be an order with products of a certain brand demanding a facility tagged with the same brand.

Steps for defining a comparison rule

predicateConnector

OR will make the rule part true if any of the predicates evaluate to true. AND will only make the expression true if all predicates evaluate to true.

predicates

An array of one or more ToolkitComparisonPredicates.

How to define a ToolkitComparisonPredicate?

rightPropertyPath

A string containing a JSONPath for the right side entity.

leftPropertyPath

A string containing a JSONPath for the right side entity.

entityOperator

One of the following:

• LEFT_CONTAINS_RIGHT - the left hand side should contain all values from the right hand side

• RIGHT_CONTAINS_LEFT - the right hand side should contain all values from the left hand side

• ALL_MATCHES - the arrays of values should be exactly equal

leftTransformation - [optional]

The transformation for the left hand side.

leftTransformationArgs - [optional]

---

The transformation arguments for the left transformation, if required.

rightTransformation - [optional]

The transformation for the right hand side.

rightTransformationArgs - [optional]

The transformation arguments for the right transformation, if required.

Toolkit Ratings

Toolkit ratings follow nearly exact same syntax as toolkit fences with a few key differences:

• order: since all ratings get evaluated either way the order field does not exist for ratings

• maxPenalty: the penalty which determines the weight of the rating in comparison to other ratings

Introduction to JSONPath

It always begins with $ referring to the entity, followed by a path to the nested property. (e.g. $.orderLineItems[*].quantity) Used in:

• ToolkitPredicate

• ToolkitComparisonPredicate

Steps for using a JSON path to define rules

• $.tenantOrderId -> $ refers to the order entity while tenantOrderId refers to the tenantOrderId. The . indicates that tenantOrderId is a nested property of Order

• $.orderLineItems[*].article -> Gets the articles from all orderLineItems, resulting in an array

• $.orderLineItems[?(@.quantity > 3)].article -> Same as last time but only gets the articles from OrderLineItems with a quantity greater than 3

To sum up we can say the following: nested properties can be accessed using the . while nested array properties such as orderLineItems, tags or stickers can be accessed using the array brackets [ and ] with an asterisk * to indicate a wildcard.

If you want to be more specific, instead of a wildcard * you can use the ?() syntax. Inside the parentheses (, ) you can then define an arbitrary expression using the @ symbol to refer to the entity being tested.

If you are for instance on an OrderLineItem such as in our example, the @ refers to the OrderLineItem that is just being evaluated. You can then access all of its nested attributes and test for an arbitrary condition. This could be the quantity as in our previous example but it could also be more complex such as the following expression:

$.orderLineItems[?(@.tags.find(tag => tag.id === 'color' && tag.value === 'red'))].article

This gets us the articles of all OrderLineItems that have at least one tag of type color with the value red.

Note: It is recommended though to keep your expressions as simple as they can possibly be without compromising on their functionality to avoid mistakes leading to misbehaviour of the fence/rating.

• The JSONPath documentation can be found here

• A helpful tool for testing JSONPath expressions can be found here

Introduction to Transformers

Transformers allow to modify the input of a ToolkitPredicate before it gets evaluated. This can serve multiple purposes, maybe you only want to look at the number of elements, get the total price of all OrderLineItems or just want to consider the beginning of the tenantOrderId.

These are the transformations currently available in the platform.

• SUM : sums the number values of each element - requires an array of elements

• COUNT : counts the number of elements - requires an array of elements

• SUBSTRING : gets a substring of a value, requires start and end parameters

• LAST: gets the last n chars of a string - required length parameter

Count Transformation

{
"propertyPath": "$.orderLineItems[*]",
"transformation": "COUNT",
"entityOperator": "GREATER_THAN",
"expectedValue": 10
}

Applies to orders with 10 OrderLineItems or more.

Sum Transformation

{
"propertyPath": "$.orderLineItems[*].quantity",
"transformation": "SUM",
"entityOperator": "GREATER_THAN",
"expectedValue": 100
}

Applies to orders where all OrderLineItems in sum have a total quantity of 100.

Substring Transformation

{
"propertyPath": "$.orderLineItems[*].article.tenantArticleId",
"transformation": "SUBSTRING",
"entityOperator": "ANY_VALUE_EQUALS",
"expectedValue": "Coca",
"transformationArgs": [0, 4]
}

Applies to orders where any OrderLineItem has a tenantArticleId that begins with "Coca".

Last Chars Transformation

{
"propertyPath": "$.orderLineItems[*].article.tenantArticleId",
"transformation": "LAST",
"entityOperator": "ANY_VALUE_EQUALS",
"expectedValue": "Christmas Special"
}

Applies to orders where any OrderLineItem has a tenantArticleId that ends with "Christmas Special"