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.

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 and date 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 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 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:
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:

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
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:

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
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:

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