# Rules
Rules are one of the most powerful features in Orderwave. They allow you to set specific business-rules around your data, which respond to triggers, and result in actions. Actions can be simple, like changing the value of something, or adding an order/shipment/payment to a queue. They can tag data, lock data, send an email, or even run a webhook.
WARNING
Rules are powerful. Due to their power and flexibility, it is highly recommended that you test your rule before applying triggers like create, created, update, updated, i.e. triggers that run on many items. A simple way to test a rule is to only enable the button trigger, and use the button to test it on an individual item.
# Creating a rule
To create a rule, navigate to .
TERMINOLOGY ⚡
The different types of data in Orderwave are called Buckets. For example, orders are in a bucket called oms/orders. The first part of the bucket is the category of the data ("oms" stands for "Order Management System"), and the second part is the name of the data, and is usually self-explanatory.
Create a rule by clicking the ➕ button.
Fill in the fields for the rule meta-data. This is information about the rule, which be helpful, not only for you later on, but for your team members too. Try and be specific about what your rule aims to do. You can always update these fields later (except the Rule Code, which is static and cannot be updated later).
Here are the rule fields:
| Field | Description |
|---|---|
| Rule Code | This is the unique identifier for this rule. It will be used to identify the rule in other parts of the application. |
| Rule Name | This is your user-friendly name for this rule. Try and be informative. |
| Rule Description | This is where you describe what this rule accomplishes in plain language. If you or a team member need to refer to this rule later on, having a well-thought-out description of the rule is very helpful. |
| Sort by | When you begin to create a lot of rules on the same bucket, Orderwave will run them in order, based on this value. This is a character value, so a value like "0" comes before "A", and "A" comes before "AAA". |
# Rule Parameters
If you have just created a rule, the Rule Parameters window will appear automatically. If you need to access this window again, click the Set Rules button when viewing the rule detail screen.
# Choose the bucket
Step one is setting the rule parameters is to choose the bucket. The first thing you may notice is that there are a lot of choices. Because Orderwave is a (first and foremost) a data-management platform, rules can be created for any bucket in the application. As a rule of thumb, choose the bucket that reacts to the triggering action you'd like to choose.
For example, it is very common to place orders into a specific queue when they are created. For this, you'd choose the oms/orders bucket, and the trigger you'd choose would be created. However, you don't have to only use the oms/orders bucket (although it is the most commonly used), you could create rules around wms/inventory, merch/products, and "deeper" buckets that relate to other buckets, like txn/payments and txn/refunds.
# Choose the trigger
The trigger is the action that will initiate your rule. All buckets support these triggers:
| Trigger | Description |
|---|---|
| create | This will fire your rule in the creation stage of the item, effectively before the item is created. This is a great option if you want to change something, like change a merchant account name on an oms/order. |
| created | This will fire your trigger after the item has been created. This is the ideal trigger for tagging or queuing your item, since now the item exists in the bucket. |
| update | This will fire your rule in the right before the item is updated. This is a great option if you want to react to the update process and change something, or even make sure that a value is set. |
| updated | This will fire the trigger right after the item has been updated. For example, if you were queuing changes to be sent to an external system, you could use this trigger to place the item in a queue. |
| tag | This trigger will fire when your item is tagged. When users tag your item, this rule will run. However, remember that your rules can fire other rules; if another rule tags an item, that will fire this trigger. You can access the tag that was tagged using the property tagged.tag in your matching properties. |
| untag | Just like tag, this will fire your rule whenever a tag is removed from your item. You can access the tag that was untagged using the property untagged.tag in your matching properties. |
| queued | This will fire your rule whenever your item is placed in a queue. Like tags, your other rules can trigger rules based on queues. If a different rules places your item into a queue, this rule will run. You can access the queue-code that was used with the property queued.queueCode in your matching properties. |
| dequeue | This fires your trigger when an item is about to be removed from a queue. You can access the queue-code of the removed queue with the property dequeued.queueCode in your matching properties. This is particularly useful for "No permission" actions. |
| dequeued | This fires your trigger when an item is removed from a queue. You can access the queue-code of the removed queue with the property dequeued.queueCode in your matching properties. |
| on demand | This is a special trigger that is used with Automated Tasks - Rules Jobs |
| button | Create a button on bucket items that appear like normal buttons. You can make your button available just on the "detail" screens, or the "list" screens so that your users can run the rule on lots of items at once. |
Some buckets expose custom triggers to rules, so that you can build rules around them. These custom triggers are listed after the core triggers listed above.
# Matching properties
It's likely that your rule doesn't qualify to run on every item that it encounters. For this reason, you implement matching properties. Matching properties let you specify the specific conditions that must be met in order to apply the actions from your rule. For example, if you want to send an email to team members for orders that are shipping to Alaska, your rule can have matching properties that evaluate that the shipping-state equals "AK" or "Alaska".
# Match groups
To start, Orderwave gives you a blank matching property that all of your properties must be true. You have multiple match types to choose from, and they are color coded as groups so that matching properties can be nested into groups. You can change the option of the Match field to indicate any of the following:
| Match type | Color | Description |
|---|---|---|
| All | Purple | All of the conditions in the purple box must be true in order for the group to be considered "true". |
| Any | Teal | One or more of the conditions in the teal box must be true in order for the group to be considered true. |
| Not | Orange | Any of the conditions in the orange area should collectively be "not true". |
# Nested match groups
By nesting your conditional logic, you can build some very complex conditions for your rules. If you have any computer programming experience, think of the match groups as parentheses around your if() conditions. Nesting match groups allows you to mix "ANDs", "ORs", and "NOTs" to get the perfect conditional logic for your rule.
There is no limit to the amount of nesting that you can implement in a rule. Some general advice:
- Try and keep your logic clear and simple. Others may build upon your work later, so make it make sense.
- Consider using other rules to build upon.
- Create a simple rule that runs early that tags the item in a particular way
- Use another rule that runs after that sees if
tagscontains(some tag)as a condition, so that you do not need to replicate conditional logic in separate rules. (Tags are nice anyway - they're searchable and serve as a great categorization system) - You can also do this with Queues instead of tags.
# Field or JSON paths to match
When creating rules, you need to compare the data in the bucket item to certain conditions, so in this first field, you specify the field name of the data to compare. Field naming follows the camelCase naming convention for each bucket. A very simple JSON path on a oms/order may be:
orderNumber
This will compare the order number on an order (provided you are working with the oms/orders bucket).
Another simple but useful path could be:
orderState.canceled
This is a true/false field, and you can compare it to the value "true" or "false" in the "value to compare" field.
Orderwave will pre-generate a list of fields in a drop-down menu at the base-level of the bucket for your convenience, but you can take it many steps further but providing a JSON path to related buckets. For example, a common business rule is to perform an action if an order contains a specific SKU. This would be accomplished by using the following JSON path:
shipments[any].lineItems[any].items[any].inventory.SKU
The above JSON path may look somewhat familiar to you if you have programming experience, however, you may be surprised by the keyword any. This is a special keyword for rules that looks into nested buckets (that can be more than one) for "any" match. For example, orders can have more than one shipment. Shipments can have more than one line item. Line items can have more than one inventory mapping. You can also use zero-based indexes instead of the any keyword if you need to look for data in specific positions.
# Matching operators
When comparing data, you have the following operators to choose from:
| Operator | Analogous to | Description |
|---|---|---|
| is | = | The value exactly equals the value you are comparing it to. |
| more | > | The value is numerically or lexically greater than the value you are comparing it to. |
| less | < | The value is numerically or lexically less than the value you are comparing it to. |
| is or more | >= | The value is numerically or lexically more than or equal to the value you are comparing it to. |
| is or less | <= | The value is numerically or lexically less than or equal to the value you are comparing it to. |
| contains | includes(...) | If your left-side value is tags (which is a group of tags), Orderwave will look at your right-side value and see if any of the options you specified are in that tag group. If your left-side value is any other property, and your right-side value is a single value, Orderwave will see if the value you provided is inside of the property on the left-side. If your right-side property is a list (you've clicked the ➕ next to the field), Orderwave will check to see if the left-side value is included in the list from the right-side. |
| starts with | startsWith(...) | Compares your left-side value to see if it starts with the value you provided on the right-side. |
| ends with | endsWith(...) | Compares your left-side value to see if the characters on the end of it matches what you provided on the right-side. |
| in the range | (left-side) >= (right-side-start) and (left-side) <= (left-side-end) | This operator changes the right-side to provide two fields: the first is for the starting value of the range, and the second is for the ending value of the range. It will compare values inclusive of the values in your starting and ending range. |
| is empty | "" == "" | Checks to see if the left-side value is empty. Empty strings, null values, no-tags, etc will be matched. |
Orderwave will attempt to coerce the types of the data that you are comparing. If the type of value in Orderwave is a number, your value will be compared as a number.
# Values to compare
When providing values to compare to fields or JSON paths, you can provide basic string-based values, or you can compare values to other fields or JSON paths.
# Comparing to basic values
Basic comparisons are the most simple form of comparisons. Examples include, when an order number starts with certain characters, or when the order state is canceled. Simply type in the characters to compare into the field.
# Comparing to fields
You can compare one field to another by wrapping your right-side value in brackets ([myField]). For example, if the totals.grandTotal is less than the [totals.originalOrderTotal], you may want to queue the order for review.
# Actions to perform
The last step in configuring a rule is to choose the actions that happen if the matching properties are all true. Actions are the resulting "things that happen" when everything in your rule matches.
All buckets contain the following actions:
| Action | Description |
|---|---|
| Add it to a queue | Put the item into a queue that is defined on the bucket. |
| Remove it from a queue | Take the item out of the queue it is in. If it is currently not in this queue, it will encounter an error, so you may consider ignoring errors on this action. |
| Lock it | Lock the item from actions, updates, or both. |
| Unlock it | Remove locks from the item (actions, updates or both). |
| Tag it | Tag the item with a tag that is defined on the bucket. |
| Un-tag it | Remove a tag from the item that is currently on it. If it is currently not tagged with this tag, it will encounter an error, so you may consider ignoring errors on this action. |
| Send Email | Send an email to user groups or a particular email address. Email templates should already be defined. |
| Send to Webhook | Send the JSON representation of this item to a web-service that you have already defined. |
| No permission | Present a "no permission" error if the current user is in the list of groups you supply. |
| Delete it | Delete the item from Orderwave. |
Specific buckets expose even more actions to this list, for example oms/orders exposes "Cancel order".
# Error handling
Actions can cause errors. As stated in the table above, trying to remove something from a queue that it is not in, will cause an error. Webhooks can generate errors for a variety of reasons, especially if your webhook experiences an outage. For this reason, Orderwave gives you the ability to ignore those errors, or abort the process and return the error.
WARNING
You must be very careful with these error-handling options. Choosing to abort on an error could be costly. For example, if you create a rule with the create or created triggers that changes the warehouse routing code to a warehouse code that does not exist (or you create the rule properly, and subsequently delete the warehouse), that rule will encounter an error. If you have chosen to abort processing as your error handling option, new orders that match that rule will be rejected. If you do not have a method to correct the rule and resubmit the orders, you will have lost orders.
It is arguably better to let the error be ignored, so that the order can be created in Orderwave, and deal with the data-mapping issue later on.
# Enabling your rule
If this is a new rule, and it's not currently enabled, after saving the rule configuration, you will be prompted to enable the rule. Only enabled rules will automatically run.
If you ever need to disable the rule, edit the rule properties by clicking the ✏ icon on the top-right of the screen, and flip the "Rule Is Active" toggle switch.