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 wants 199
You send a vendor number in the REF, but your Trading Partner wants it in the N1
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.

Add empty objects

If required, you can add a new object to an array, and then write rules to populate that new object. This is only available for transactions in JSON format. For more information about how to use this feature, see Add data to a JSON transaction. For example uses, see [Example 8 and [Example 9 below.

AI Rule suggestions

For some validation errors, Orderful is able to suggest Rules that could fix the error.

When you select an element that is experiencing this validation error, a "Suggest Rule" prompt will appear on the bottom right of the page:

In some cases, multiple Rules may be suggested to fix one or more errors. For example, one Rule will be suggested to move a property, and another will be suggested to move its qualifier.

When you click Apply Rule this will apply all of the suggested Rules across all of the specified paths. Some Rules will be on different element paths than the original validation error.

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 a value from one property to another: Use a Conditional Rule to replace a value with another value from the same document.
Copy an object from one array to another: Use a Rule to copy an object (segment, loop) from one location to another within 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 a Loop: Use a Conditional Rule to remove an entire Loop if it contains a particular value.
Delete a Segment: Use a Conditional Rule to remove a Segment if it contains a particular value.
Add an object and copy a value: Add an empty object and copy an existing value into it.
Add an object and calculate a new value: Add an empty object and add a new value into it based on another 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 a value from one property to another

You can use a LOOKUPV2() 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 LOOKUPV2($beginningSegmentForPurchaseOrder,"*",$date, $date)

Note that the LOOKUPV2 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": LOOKUPV2(.
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 and $date as your lookup element: LOOKUPV2($beginningSegmentForPurchaseOrder,"_",$date,$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 of 010 to just copy the existing value of date 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 whe500n it is not met:

4. Copy an object from one array to another

You can use a LOOKUPV2() function to find an object in an array based on a condition. For example: you can copy and paste the specific object in the N1_loop array where entityIdentifierCode equals "ST".

Expressed as a Rule:

LOOKUPV2($transactionSets, "ST", $entityIdentifierCode, $N1_loop.*)

Note that the LOOKUPV2() 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 to the Transaction Details page.
Near the top, select the Rules Editor tab.
Scroll down into the payload and
1. If you are viewing as JSON: click the first { under the N1_loop array. At the top of the pane on the right you should see N1_loop.*
2. If you are viewing as X12: click the bracket on the left extended from the N1 segment to N4. At the top of the pane on the right you should see N1_loop.*
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.
You will have to enter the "LOOKUP Statement": LOOKUPV2($transactionSets, "ST", $entityIdentifierCode, $N1_loop.*).
1. Note: The Lookup scope (array) defined in the 1st argument must contain the object containing the lookup element. So, when looking up an object at the header level of a transaction, the lookup scope must be $transactionSets.
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 object pasted in its new location:

5. 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:
1. Domain Name: A unique name for this Lookup Table. In this example UPC_TO_VN.
2. Key Name: The value that will be searched for. In this example UPC.
3. Value Name: The mapped value that the searched value will be replaced with. In this example VN.
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 VN VNEXAMPLE.
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:

6. 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
1. If you are viewing as JSON: click the first { under the N1_loop array. At the top of the pane on the right you should see N1_loop.*
2. If you are viewing as X12: click the bracket on the left extended from the N1 segment to N4. At the top of the pane on the right you should see N1_loop.*
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:

7. 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
1. If you are viewing as JSON: click the first { under the businessInstructionsAndReferenceNumber array. At the top of the pane on the right you should see businessInstructionsAndReferenceNumber.*
2. If you are viewing as X12: click on the L11 segment. At the top of the pane on the right you should see L11.*
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:

8. Add an object and copy a value

You can use the Rules Engine to add a new object to an array, and then copy a value from an existing property into a property within this new object. For example, you can copy the Purchase Order Number from the beginningSegmentForPurchaseOrder into the referenceIdentification property inside a new object within the referenceInformation array.

Expressed as a Rule:

LOOKUPV2(beginningSegmentForPurchaseOrder, "*", purchaseOrderNumber, purchaseOrderNumber)

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 array to which you want to add an object: referenceInformation.
Hit the Enter key. You will see the array highlighted in the JSON payload. If you hover over the array you will see a button: Add {} to Array
Click on Add {} to Array. This will add a new blank object to the array, with three properties with empty values. Two of these, the description and the qualifier, we will just SET values for, and for the referenceIdentification we use LOOKUPV2 to copy the value of the Purchase Order number.
Click on description. 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”, enter SET(“This is the PO number”).
Repeat the above steps for referenceIdentificationQualifier and enter SET("ZZ").
Now click on referenceIdentification, follow the link on the right to the “Add a rule” pane, and make sure Simple Rule is selected.
Now enter the “LOOKUP Statement”: LOOKUPV2(beginningSegmentForPurchaseOrder, "*", purchaseOrderNumber, purchaseOrderNumber)

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 new object and its values:

9. Add an object and calculate a new value

You can add a new object, then use a combination of Rules to populate it with a new value based on an existing value. For example, you can create a dateTimeReference object that finds the “Do Not Deliver Before” date and uses it to create a new “Do Not Deliver After” date.

We will create a Rule with the following structure:

ADDTIME(LOOKUPV2(dateTimeReference, "064", dateTimeQualifier, date), "YYYYMMDD", 5, "days")

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 array to which you want to add an object: dateTimeReference.
Hit the Enter key. You will see the array highlighted in the JSON payload. If you hover over the array you will see a button: Add {} to Array
Click on Add {} to Array. This will add a new blank object to the array, with three properties with empty values. We will leave the time value empty. The dateTimeQualifier we will SET a value for. For date we will use LOOKUPV2 to copy the value existing date and use the ADDTIME Rule to add 5 days to it.
Click on dateTimeQualifier. 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”, enter SET(“063”). This is the qualifier for the “Do Not Deliver After” date.
Now click on date, follow the link on the right to the “Add a rule” pane, and make sure Simple Rule is selected.
Now enter the “LOOKUP Statement”: LOOKUPV2(dateTimeReference, "064", dateTimeQualifier, date) and save the Rule. The date field should now populate with the same value as the existing date field.
Click the three-dot menu to the right of your Rule and select Edit
Go to the start of your Rule and add the ADDTIME rule, then the correct parameters. The finished rule should read: ADDTIME(LOOKUPV2(dateTimeReference, "064", dateTimeQualifier, date), "YYYYMMDD", 5, "days").

At the end you should have a Rule that looks like this:

Once you save the Rule, Orderful will update the payload to show the new object and its values:

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