Attribute Assignment in Order Rules

This article explains how to assign values to order attributes in DropStream order rules.

Overview

The DropStream rule language allows you to create rules that assign values to attributes, e.g., tax amount, sales representative name or shipping date. These may be attributes of orders or order items that did not have any values before, or attributes for which you would like to replace previously assigned values with new values.

For example, you may want to change the source ID of an order, or SKUs of order items.

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 order attributes disappears.

Attribute assignment is performed in DropStream by means of the assignment operator. In the GUI-based rule editor, the assignment operator manifests itself as the Set order attribute transformer rule and the Set order item attribute transformer rule for orders and order items, respectively. The rules are available from dropdown menus and their use with order attributes and order item attributes is described elsewhere. Attribute assignment in the Advanced Editor is explained further down in this article.

Attribute assignment can be applied unconditionally to the attributes of all orders or all order items, or be dependent on certain conditions. In the latter case, the condition is expressed in the IF statement and the assignment in the THEN statement.

Assignment depends also on the data type of the attribute value, i.e. whether it is a text string, number, date, or a truth value.

Assignment by data type

Text strings

Attributes that have textual values include e.g., product 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 assignment in DropStream is case-insensitive, e.g. FEDEX = FedEx = fedex.

A textual attribute value can be expressed either as

• text - a primitive text string, e.g. DHL.
• text expression - a concatenation of two or more text strings, e.g. "Ship" and "DHL". To concatenate more than two strings, enter the first string in the first text box, and choose text expression as the type of the second string.
• capture regex matches - a regular expression match with the following parameters:
  • capture - text string (a simple string or a concatenation of multiple strings), or an order attribute from which to to extract regex matches, e.g. Gift Message.
  • regex - a regular expression without surrounding forward slashes. The expression needs to contain one or more named variables in angle brackets (<>) which store the result of the regex, e.g. ^(?<var>.{0,8}), where var is the name of the variable with the first 8 characters of a text string or attribute value (e.g. Gift Message) as the value.
  • output - one or more variables defined in the regex match above, either on their own or concatenated to other variables or text strings, e.g. "important:" & var. Strings need to be in quotation marks (""), otherwise they are treated as variables. Unassigned variables trigger an error during rule execution time.
• variable - the result of a predefined regex match.
• order attribute or order_item attribute - an existing value of an attribute, e.g. Gift Message.

Numbers

Attributes that have numeric values are those that can be counted or added, like the monetary attributes unit value, subtotal or tax amount.

The numeric value can be expressed either as a

• 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 existing 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, and are expressed with the minute precision, so that seconds and milliseconds are ignored.

A date value can be expressed either as a

• Date, e.g. 07/21/2020 7:59 PM
• Now - the variable is assigned the date/time value of the rule execution time.
• (the result of) a temporal expression
  • after - x minutes, hours, days, weeks, months or years after a specified date, e.g. 3 months after the ordering date
  • before - x minutes, hours, days, weeks, months or years before a specified date, e.g. 48 hours before the shipping date
• order attribute - the existing value of another date attribute, e.g. shipping date

Boolean values

Attributes that have boolean values, or truth values, include attributes like Is signature required?, Is shipping address an apartment?

A boolean value can be either

• A primitive truth value.
  • true
  • false
• Compare order attribute or Compare order item attribute - a truth value that depends on attribute comparison of an existing attribute value to a specified attribute value of an order or an order item, true if the existing value is the same as the specified value, false otherwise.
• A truth value that depends on a boolean combination of conditions applied to an order.
  
  • OR - true if one of the specified conditions is met; false otherwise.
  • AND - true if all specified conditions are met; false otherwise.
  • NOT - true if the specified condition is not met; false otherwise, i.e. if the condition is met.
• A truth value that depends on conditions applied to a quantified list of order items (available only with value assignment to orders, not to order items).
  
  • any order_items match conditions - true if one of the order items meets the specified conditions; false otherwise.
  • all order_items match conditions - true if all order items meet the specified conditions; false otherwise.
  • no order_items match conditions - true if none of the order items meet the specified conditions; false otherwise, i.e. if at least one order item meets the conditions.

Assignment in Advanced Editor

The explanation above described attribute assignment in 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 circumfix assignment operator set object.attribute to value is used to assign a value to the attribute of 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 assignment of textual values are surrounded by forward slashes (/.../).
• The syntax of the matches operator is output | regex matches capture that is used for the value parameter of the assignment operator, e.g.
  • set order.notes to "order_id: " & var | /(?<var>.*)-/ matches order.external_id.
• 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.

Here is an example rule that assigns new values to order attributes:

rule "Assignment"
 set order.external_source_id to "DHL Express"
 set order.discount_amount to 10.0
 set order.requested_ship_date to @2020-07-28T17:21:00+00:00
 set order.signature_required to true
end