Use the Rules Engine
What are Rules?
A Rule is an instruction that modifies EDI data as it passes through the Orderful platform. A Rule can be applied to a property or an entire object (or element, segment, or entire loop in X12): For example, you could have a Rule that specifies that every time an inbound transaction contains a countryCode
with value USA
it is changed to US
.
How are Rules used?
By writing rules, you can adjust your outbound transactions to meet your Trading Partner's requirements or adjust your inbound transactions to meet the needs of your own System of Record (SOR).
For example:
- You send
1.99
, but your Trading Partner uses implied decimals and wants199
- You send a vendor number in the
REF
, but your Trading Partner wants it in theN1
- Your Trading Partner sends weight in kilograms, but you want pounds
- Your Trading Partner only needs the last 4 characters of a
DUNS+4
location number
Rules are associated based on three criteria. Every Rule is applied to:
- a particular transaction type (ex. 850 Purchase Orders)
- in a specific direction (Inbound or Outbound)
- for a particular Trading Partner (ex. Costco)
Orderful will check whether a transaction is valid after it applies Rules. If a transaction is invalid, Orderful will notify the sender. Consequently, we recommend that Rules should not be used to mark a transaction as invalid because the trading partner will not be notified.
Creating Rules
Rules are created using the Rules Editor which can be found in the Transaction Details page.
- Go to your Transactions page.
- Select a Transaction, which will bring you the Transaction Details page.
- Near the top, select the Rules Editor tab.
- Select the property or element that you would like to create a Rule for, or search for it using the search field at the top of the payload. Once you have selected it a prompt will appear on the right that says "A relationship rule does not exist". If you click the link in that prompt, it will open the "Add a rule" pane. Example rules can be found in the following section.
Example Rules
The example Rules below show possible uses of Rules.
- Format date and time: Use a Simple Rule to change the format of a date in a document.
- Modify qualifier codes: Use a Conditional Rule to replace one specified property value with another specified value.
- Copy data from one property to another: Use a Conditional Rule to replace a value with another value from the same document.
- Convert data with a lookup table: Use a Simple Rule with a Lookup Table to replace one value with another based on a pre-existing mapping. Also shows how to add simple error handling.
- Delete data: Use a Conditional Rule to remove an entire loop if it contains a particular value.
The names of properties are just examples, your transactions will not necessarily contain any of these.
1. Format date and time
Simple Rules can be used to change dates from one format to another. For example, if your Trading Partner sends you dates in a YYYMMDD
format and your SOR expects them in MMDDYYYY
format.
We will create a Rule with the following structure:
FORMATDATE(date, "YYYYMMDD", "MMDDYYYY")
- Go to your Transactions page.
- Select a Transaction you'd like to create a Rule for. This will bring you the Transaction Details page.
- Near the top, select the Rules Editor tab.
- At the top of the payload, click on Search JSON payload and enter "$date" which is the date property that we are interested in reformatting.
- Hit Enter and the
date
property will be highlighted. A prompt will appear on the right that says "A relationship rule does not exist". If you click the link in that prompt, it will open the "Add a rule" pane. - From the "Add a rule" pane, select Simple Rule.
- Under "Rule Details" you can enter in:
FORMATDATE($date
. Orderful will autocomplete the name of the element. You must click on the autocomplete selection to confirm the property that you are modifying. - Next we must add the old format and the new format:
"YYYYMMDD","MMDDYYYY")
- At the bottom of the "Add a rule" pane, click on Save.
At the end you should have a Rule that looks like this:

Once you save the Rule, Orderful will update they payload to show the old value crossed out and the new value in its place:

2. Modify qualifier codes
You can use a Conditional Rule to modify qualifier codes that are equal in meaning. For example, if you know that your Trading Partner measures their shipments by the case, they might send you a transaction with a property with a value of CA
. If your system expects the code to be CAS
then you can tell Orderful to convert the value from CA
to CAS
.
We will create a Rule with the following structure:
IF EQUALS(unitOrBasisForMeasurementCode, "CA")
THEN SET("CAS")
- Go to your Transactions page.
- Select a Transaction you'd like to create a Rule for. This will bring you the Transaction Details page.
- Near the top, select the Rules Editor tab.
- At the top of the payload, use the search bar to find the property you are interested in reformatting:
unitOrBasisForMeasurementCode
. - Hit the Enter key. A prompt will appear on the right that says "A relationship rule does not exist". If you click the link in that prompt, it will open the "Add a rule" pane.
- From the "Add a rule" pane, select Conditional Rule.
- Click on IF which will open the "Add a condition" pane.
- Under "IF Statement" enter
EQUALS(
. Orderful will suggest autocomplete options as you type. - You will need to specify the property that your condition acts on. Enter
$unitOrBasisForMeasurementCode
which Orderful will autocomplete. You must click on the autocomplete selection to confirm the property that you are modifying. - Next enter a comma, then enter the value for this property:
"CA"
. Then close the parenthesis)
. Press Tab twice to move on to the next section. - Now you will have to enter the "THEN Statement":
SET("CAS")
. - Click on Done, and you will return to the "Add a rule" screen.
- Now click on the box under "Default Expression", this will open the "Update default expression" pane.
- The Default Expression specifies what occurs if the "IF Statement" is not met. In this case, we can just tell Orderful to keep the existing value for this property by setting the Default Expression to
$unitOrBasisForMeasurementCode
.
At the end you should have a Rule that looks like this:

Once you save the Rule, Orderful will update they payload to show the old value crossed out and the new value in its place:

3. Copy data from one property to another
You can use a LOOKUP()
function to find the value of one property and copy it to another property. For example, you can ensure that the "Requested Ship Date" is always equal to the "Purchase Order Created Date" by copying one value to the other.
Expressed as a Rule:
IF EQUALS(dateTimeQualifier,"010")
THEN LOOKUP(beginningSegmentForPurchaseOrder,"*","date")
Note that the LOOKUP
function here both retrieves and sets the value.
- Go to your Transactions page.
- Select a Transaction you'd like to create a Rule for. This will bring you the Transaction Details page.
- Near the top, select the Rules Editor tab.
- At the top of the payload, use the search bar to find the property you are interested in reformatting:
dateTimeQualifier
. - Hit the Enter key. A prompt will appear on the right that says "A relationship rule does not exist". If you click the link in that prompt, it will open the "Add a rule" pane.
- From the "Add a rule" pane, select Conditional Rule.
- Click on IF which will open the "Add a condition" pane.
- Under "IF Statement" enter
EQUALS(
. Orderful will suggest autocomplete options as you type. - You will need to specify the property that your condition acts on. Enter
$dateTimeQualifier
which Orderful will autocomplete. You must click on the autocomplete selection to confirm the property that you are modifying. - Next enter a comma, then enter the value for this property:
"010"
. Then close the parenthesis)
. Press Tab twice to move on to the next section. - Now you will have to enter the "THEN Statement":
LOOKUP(
. - You will need to specify the property that your functions acts on. Enter
$beginningSegmentForPurchaseOrder
which Orderful will autocomplete. You must click on the autocomplete selection to confirm the property that you are modifying. - Add a comma, then add
"_"
as your lookup value anddate
as your lookup element:LOOKUP(beginningSegmentForPurchaseOrder,"_","date")
. Hit Tab three times. - Click on Done, and you will return to the "Add a rule" screen.
- Now click on the box under "Default Expression", this will open the "Update default expression" pane.
- The Default Expression specifies what occurs if the "IF Statement" is not met. In this case, we can tell Orderful that if the
dateTimeQualifier
does not have a value of010
to just copy the existing value ofdate
and use that value instead.
Here is the Rule:

Once you save the Rule, Orderful will update the payload to show the old value crossed out and the new value in its place. In this case you can see both what happens when the condition is met, and when it is not met:

4. Convert data with a lookup table
It is possible to use a Simple Rule combined with a Lookup Table to replace one value with another based on a pre-existing mapping. For example, if your Trading Partner sends you UPC codes but you'd like to replace them with equivalent VN codes. So we want to look up the value of the productServiceId
in the UPC_TO_VN
lookup table.
Expressed as a Rule:
LOOKUPDATA("UPC_TO_VN", productServiceId)
First we will have to create the Lookup Table:
- Go to your Organization's Settings then click on Lookup Tables on the left hand side, or click here: https://ui.orderful.com/settings/lookup-tables
- Click New Lookup Table
- A dialogue will pop up where you have to enter:
- Domain Name: A unique name for this Lookup Table. In this example
UPC_TO_VN
. - Key Name: The value that will be searched for. In this example
UPC
. - Value Name: The mapped value that the searched value will be replaced with. In this example
VN
.
- Domain Name: A unique name for this Lookup Table. In this example
- This will bring you to the details page for your new Lookup Table. Here you can enter one or more values for UPC and VN, or upload a CSV file. In this case we will only enter one entry for our example. Under UPC:
711719100246
and under VNVNEXAMPLE
. - Click Save Lookup Data
Next we will create the Rule:
- Go to your Transactions page.
- Select a Transaction you'd like to create a Rule for. This will bring you the Transaction Details page.
- Near the top, select the Rules Editor tab.
- At the top of the payload, click on Search JSON payload and input
productServiceID
. - Hit the Enter key. A prompt will appear on the right that says "A relationship rule does not exist". If you click the link in that prompt, it will open the "Add a rule" pane.
- From the "Add a rule" pane, select Simple Rule.
- Enter the
LOOKUPDATA
function:LOOKUPDATA("UPC_TO_VN",
- Next enter
($productServiceId)
and click on the autocomplete result. You must click on the autocomplete selection to confirm the property that you are modifying.
At the end you should have a Rule that looks like this:

However, you can see there is an associated error.
If you click on **See Associated Error(s) you will see: No lookup data matching lookup key "611719100245" in domain "UPC_TO_VN".
Error handling
To account for situations where a value is missing from our Lookup Table we can add some error handling, so that if an error is encountered at the end of the LOOKUPDATA
function, we can tell Orderful to do something else instead.
IFERROR(LOOKUPDATA("UPC_TO_VN", productServiceId) SET(productServiceID1))
In this case we are telling Orderful that, if an error is encountered, to set the value of productServiceId
to be the same as the value of productServiceID1
.
The new Rule looks like this:

And if we save it, we can see the error being handled in the payload:

5. Delete a Loop
You can use the DELETE()
function to delete some an entire Loop or Segment. For example, if you do not use "Remit To" contact information Loop in a particular Relationship you can remove it when it's present in the payload.
Expressed as a Rule:
IF INCLUDES(entityIdentifierCode, "RT")
THEN DELETE()
- Go to your Transactions page.
- Select a Transaction you'd like to create a Rule for. This will bring you the Transaction Details page.
- Near the top, select the Rules Editor tab.
- Scroll down into the payload and
- If you are viewing as JSON: click the first
{
under theN1_loop
array. At the top of the pane on the right you should seeN1_loop.*
- If you are viewing as X12: click the bracket on the left extended from the
N1
segment toN4
. At the top of the pane on the right you should seeN1_loop.*
- If you are viewing as JSON: click the first
- A prompt will appear on the right that says "A relationship rule does not exist". If you click the link in that prompt, it will open the "Add a rule" pane.
- From the "Add a rule" pane, select Conditional Rule.
- Click on IF which will open the "Add a condition" pane.
- Under "IF Statement" enter
INCLUDES(
. Orderful will suggest autocomplete options as you type. - You will need to specify the property that your condition acts on. Enter
$entityIdentifierCode
which Orderful will autocomplete. You must click on the autocomplete selection to confirm the property that you are modifying. - Next enter a comma, then enter the value for this property:
"RT"
. Then close the parenthesis)
. Press Tab twice to move on to the next section. - Now you will have to enter the "DELETE Statement":
DELETE()
. - Click on Done, and you will return to the "Add a rule" screen.
At the end you should have a Rule that looks like this:

Once you save the Rule, Orderful will update they payload to show the loop crossed out:

6. Delete a Segment
You can use the DELETE()
function to delete a Loop or Segment. For example, if you do not use the "Vendor Number" segment you can remove it when it's present in the payload.
Expressed as a Rule:
IF EQUALS(referenceIdentificationQualifier, "VN")
THEN DELETE()
- Go to your Transactions page.
- Select a Transaction you'd like to create a Rule for. This will bring you the Transaction Details page.
- Near the top, select the Rules Editor tab.
- Scroll down into the payload and
- If you are viewing as JSON: click the first
{
under thebusinessInstructionsAndReferenceNumber
array. At the top of the pane on the right you should seebusinessInstructionsAndReferenceNumber.*
- If you are viewing as X12: click on the
L11
segment. At the top of the pane on the right you should seeL11.*
- If you are viewing as JSON: click the first
- A prompt will appear on the right that says "A relationship rule does not exist". If you click the link in that prompt, it will open the "Add a rule" pane.
- From the "Add a rule" pane, select Conditional Rule.
- Click on IF which will open the "Add a condition" pane.
- Under "IF Statement" enter
EQUALS(
. Orderful will suggest autocomplete options as you type. - You will need to specify the property that your condition acts on. Enter
$referenceIdentificationQualifier
which Orderful will autocomplete. You must click on the autocomplete selection to confirm the property that you are modifying. - Next enter a comma, then enter the value for this property:
"VN"
. Then close the parenthesis)
. Press Tab twice to move on to the next section. - Now you will have to enter the "DELETE Statement":
DELETE()
. - Click on Done, and you will return to the "Add a rule" screen.
At the end you should have a Rule that looks like this:

Once you save the Rule, Orderful will update they payload to show the segment crossed out:

Grouping Rules
Rules that contain nested functions are evaluated from the inside out.
For example, this Rule, set on the identificationCode
property:
IF AND(EQUALS(entityIdentifierCode,"BT"), NOT(EXISTS(identificationCode)))
THEN SET("9011135")
This Rule says that if the entityIdentifierCode
has a value of BT
, and identificationCode
is not found, then set the identificationCode
to 9011135
.
The functions are evaluated in the following order:
EXISTS
NOT
EQUALS
AND
SET
Updated 2 months ago