Attribute Comparison in Order Rules

This article explains how to compare order attributes in DropStream order rules.

Overview

The DropStream rule language allows you to create rules where the rule action depends on the value of an attribute, e.g., SKU number, tax amount, sales representative name or shipping date. In this way, the attribute values of an actual order are compared to the values that you provide, and determine the action to be taken.

For example, if the order cancellation date is on a Sunday, do something, if it is not on a Sunday, do something else.

The actions may include filtering out certain orders, assigning new values to order attributes, shipping the orders using a specific postal service, and others.

Note: Orders and order items have different attributes. For example, the unit price, SKU number and gift wrap are attributes of order items (the customer may wish to gift-wrap only some items, not all), while the subtotal amount, retailer ID and order date are attributes of an order, and shared by all, potentially many, items in an order. If an order contains only one item, the order item attributes apply to the whole order, and the difference between the order item attributes and the order attributes disappears.

Attribute comparison is done in DropStream by means of comparison operators - predicates that are used to compare the values of one attribute to another.

The operators are available in the GUI-based rule editor as drop-down values for the conditions (IF parts) of rules, and as predicate constants in the Advanced Editor. The use of the GUI Editor is explained elsewhere for order attributes and order item attributes. The use of the Advanced Editor is explained further down in this article.

Comparison of attribute values can be absolute (the actual value is identical to the value that you provide), or relative (the actual value is similar the value that you provide).

Comparison also depends on the data type of an attribute value, i.e. whether it is a text string, number, date, or a non-empty value.

Comparison by data types

The following comparison operators can be used in DropStream order rules for different types of attribute values.

Text strings

Attributes that have textual values include e.g., Company name, Shipping address and Lead source. Values which can contain both letters, numbers, and delimiters or punctuation marks, are treated as text strings. Such "alphanumeric" values are frequently used for street addresses, discount codes, part numbers, etc.

String comparison is case-insensitive, e.g. FEDEX = FedEx = fedex.

Comparison operators for text strings

• is - the actual value is identical to the specified value.
• is_not - the actual value differs from the specified value. The expression A is_not x is equivalent to not(A is x).
• starts_with- the actual value starts with the specified value.
• ends_with- the actual value ends with the specified value.
• contains- the actual value contains the specified value.
• matches - the actual value matches the specified value that is expressed as a regular expression (without surrounding forward slashes).
• is blank - the actual value is empty.
• is not blank - the actual value is not empty.

Numbers

Attributes that have numeric values are those that can be counted or added, like the monetary attributes Unit price, Subtotal, or Tax amount.

Comparison operators that can be used with numbers include

• = - the actual value is equal to the specified value.
• <> - the actual value is different from the specified value (either less than the specified value or greater than the specified value). The expression A <> x is equivalent to not(A = x).
• < - the actual value is less than the specified value.
• > - the actual value is greater than the specified value.
• =< - the actual value is less than the specified value or equal to it.
• >= - the actual value is greater than the specified value or equal to it.
• is blank - the actual value is empty.
• is not blank - the actual value is not empty.

The specified numeric value can be expressed as:

• number - a primitive integer or a real number, e.g. 10 or 5.55
• (the result of) a numeric expression on integers or reals:
  • + - sum, e.g. 10+5 or 10.01 + 5.55
  • - - difference, e.g. 10-5 or 10.01 - 5.55
  • * - product, e.g. 10*5 or 10.01 * 5.55
  • / - quotient, e.g. 10/5 or 10.01 / 5.55
  • - (inverse) - inverse, e.g. -10 or -5.55
• order attribute - an actual value of a (different) attribute, e.g. shipping amount

Date/time values

Attributes that have date/time values include Order date, Cancel date and Shipping date. Order items do not have date/time attributes.

Date/time values are expressed with minute precision by default, so that seconds and milliseconds are ignored, but they can be added to rules in the Advanced rule editor (see below).

All time values use UTC time, which means that you will need to convert the time in your or your store's time zone to UTC. Time zone can be added to rules in the Advanced Editor.

Comparison operators that can be used with temporal values are

• in/on - the actual value is the same as the specified value, which is either a year (e.g. 2020), a month (e.g. January) or a day of the week (e.g. Monday).
• = - the actual value is identical to the specified value.
• <> - the actual value is different from the specified value (either less than the specified value or greater than the specified value). The expression A <> x is equivalent to not(A = x).
• < - the actual value is less than the specified value.
• > - the actual value is greater than the specified value.
• =< - the actual value is less than the specified value or equal to it.
• >= - the actual value is greater than the specified value or equal to it.
• is blank - the actual value is empty.
• is not blank - the actual value is not empty.

The specified date value can be expressed as:

• date - a date in MM-DD-YYYY hh:mm A format, e.g. 07/21/2020 7:59 PM .
• now - the time when the rule is executed, which is for orders after they are received from a store, before going to a warehouse for fulfillment, and for shipments after they are received from a warehouse to be delivered to customers (no rules are executed on inventory items).
• (the result of) a temporal expression:
  • + - following the specified date/time by x minutes, hours, days, weeks, months or years, e.g. 3 months after the ordering date.
  • - - preceding the specified date/time by x minutes, hours, days, weeks, months or years, e.g. 48 hours before the shipping date.
• order attribute - the actual value of another date attribute, e.g. shipping date.

Non-empty values

This group does not correspond to any classic data type, rather, it is a class of attributes whose value is not evaluated, the rule engine only checks whether any value has been assigned to the attribute or not. In this type of "dummy" comparison, the actual value of an order or order item is compared to an arbitrary (specified) value, or to its opposite, empty value ("blank"). Attributes that belong to this class include attributes like Signature required, Shipping address is an apartment, and Gift wrap required.

A value of this type can be either

• is not blank - the actual value is empty. The expression A is not blanks x is equivalent to not(A is blank).
• is blank - the actual value is not empty.

Comparison in Advanced Editor

The explanation above described attribute comparison in the GUI-based rule editor. The same principles apply also in the Advanced Editor, with the following caveats:

• Dot-notation is used to associate an order or order item with an attribute , e.g. order.subtotal or order_item.name.
• The infix notation object.attribute comparison_operator value is used for comparison operators, which are placed after the attribute and before the specified value of an object, either an order or order_item.
• Spaces in attribute names are replaced by underscores.
• Lower-case is used throughout, except for specified text strings, which are displayed in quotation marks the way you input.
• Regular expressions that are used with the matches comparison operator are surrounded by forward slashes (/.../).
• All numbers are displayed as reals.
• A variation of the ISO 8601 format, YYYY-MM-DDTHH:mm:ss.SS+Z is used for date/time values; +Z stands for time zone difference from UTC. Date/time values are prefixed by @, e.g. @2020-07-22T21:38:00+00:00.  Time can be referenced without date, e.g. @11:59:00+08:00 with time zone or @T11:59:00 without (defaults to UTC).
• Comparison operators that are used with non-empty values are represented as follows:
  • is blank → blank.
  • is not blank → nothing.

Here is an example rule with attribute comparison:

rule "Comparison"
 when
   order.external_shipping_description is "Free" and order.discount_amount = 0.0 and order.requested_ship_date = @2020-07-22T21:38:00+00:00 and order.signature_required blank
 then
   reject order
 end
end