This blog post is part of a series designed to demystify the process of understanding and writing your own business rules.
Every once in a while you need to write a rule longer than 2,000 characters, reference the same rule multiple times, or reference the same rule multiple times with different fields or parameters.
In some scenarios — where you reference the same rule multiple times within a single rule — functions like SET/GETCONTEXTVALUE will be the most appropriate function to use. However, when you’re in the kinds of scenarios noted above, a custom function is often your best bet to accomplish those goals.
What makes custom functions different from the GET/SETCONTEXTVALUE functions?
- Custom functions allow the use of variable parameters that can be defined each time you call the custom function, effectively making the function behave differently each time it is called.
- Custom functions will generate the same output and can be called from multiple different rules to generate that same output. While SET/GETCONTEXTVALUE functions do this as well, they require you to define the function with SETCONTEXTVALUE in every rule it’s used in, and this is where you lose a bit of efficiency if the underlying rule is referenced across multiple different rules.
- You would use SET/GETCONTEXTVALUE when you need to run a rule and set that value for use within that one rule (once or multiple times). As soon as you need to use the underlying rule in other rules, use of a custom function is recommended.
Limitations
Custom functions have a few limitations, so keep these in mind before starting:
- You cannot call one custom function with another custom function.
- You cannot nest a custom function inside another custom function.
- You cannot use custom functions within rules used on eBay templates.
- We have found some functionality issues with custom functions in outbound digital marketing custom templates.
Designing a Custom Function Without Variables
You write custom functions within the business rule editor, and it needs to follow a specific format to be identified as a custom function:
FUNCTION (VARS(@x,@y,@z),
INSERT A COMPLETE BUSINESS RULE
)
Parts of the Custom Function
FUNCTION: Required for our system to recognize that this is the start of a custom function. Without it, when you attempt to call this custom function, it won’t be recognized and will not execute.
VARS: Required as part of the structure of the custom function.
@x,@y,@z: Variables being defined for your custom function. A minimum of one value is required. Each is defined as a variable with the “@” and can be named however you see fit. If multiple variables are needed, separate them with commas as we’ve done in this example.
( ): Notice where parenthesis exist within the definition as they are required — missing one can cause the custom function to fail. You won’t be able to save the custom function until it’s properly closed.
Title of the Custom Function: in the business rule editor, you must name the custom function. We recommend doing so with a logical short name, all in caps (ie: CFNAME). The title should not include spaces or punctuation.
Calling on Custom Functions
You call custom functions within other business rules, so you need to create a new rule within the business rule editor and be prepared to use the title of your custom function in an appropriate location in this “outer” rule.
Amazon Product Type Rule (the Rule Calling the Custom Function)
Because you’ll know your goals when you’re writing the custom function, you’ll know how to structure the rule calling the custom function.
Example: The rule will call the custom function PRODUCTTYPE, and defines zero (0) as the variable. We should expect the custom function to evaluate and output a text string, as it’s being used to compare against the value “T-Shirts”.
Important Note: The “0” defined as the variable in the “Amazon Product Type” rule was chosen at random — any other single non-broken string, letter, or number could be placed in the same place and the rule will still work.
Custom Functions Without Variables
When custom functions are written, you may or may not need to include a variable within the custom function. In the example below, we define @x as the variable, but that variable is not included in the enclosed rule. The goal in creating a rule like this is to allow the custom function to execute start to finish. This is a good example of the functionality available when using custom functions to call this same enclosed rule across multiple rules.
PRODUCTTYPE Custom Function
This function is designed to evaluate four different fields with the IFBLANK function. The first of those not blank will be returned as the result of the custom function. If extracted from the custom function, the included business rule could stand on its own as a business rule.
Example: The rule will call the custom function PRODUCTTYPE, and defines zero (0) as the variable. We should expect the custom function to evaluate each field and return the first that is not blank:
Important Note: If the enclosed rule (starting with IFBLANK) needed to be called only within a single rule, then the SETGETCONTEXTVALUE function would be more appropriate as long as the length of the rule was still under 2,000 characters.
Design of Custom Functions With Variables
An advanced custom function will use the variables you define within the custom function business rule itself. This is one of the greatest strengths of custom functions and offers flexibility in data manipulation.
This is also where SET/GETCONTEXTVALUE sharply differs from custom functions, as you don’t have the option of including variables in those functions. Your only good option is to use custom functions. Below is a structural example:
FUNCTION (VARS(@x,@y,@z),
INSERT A COMPLETE BUSINESS RULE THAT REFERENCES VARIABLES
)
Example:
FUNCTION (VARS(@x,@y,@z),
SELECTCASE(
ISINLIST( “Lookup Color”,@x ),
LOOKUP( “Lookup Color”, @x ),
GETPART( @y, “|”, 2),
@z
)
Good, Not-So-Good and Bad Custom Function Examples (With Variables)
Just like the custom function without a variable, a minimum of one variable definition is required when creating the custom function, and you can name each as you see fit. To help you better understand the relationship between the variables, we’ve replaced the generic math variables (@x, @y, @z) with something logical based on the rule and goals of the rule calling the custom function:
Example 1: GOOD Custom Function
FUNCTION ( VARS ( @colorfield ),
IF (
ISINLIST(“Color Lookup List Name”, @colorfield),
LOOKUP(“Color Lookup List Name”, @colorfield),
“Blank” )
)
This is a good custom function because one variable is defined, and exists within the business rule, named exactly the same as inside the “VARS” section.
Example 2: Not-So-Good Custom Function
FUNCTION ( VARS ( @colorfield, @secondfieldname, @thirdfieldname ),
IF (
ISINLIST(“Color Lookup List Name”, @colorfield),
LOOKUP(“Color Lookup List Name”, @colorfield),
“Blank” )
)
This is a not-so-good custom function because three variables are defined, but only one is used in the business rule. This function can still be used, but when calling it, you need to call it with three variables defined, even though only one is used. This use of a custom function incorporates extraneous/unnecessary text. To fix this situation, simply remove the unused variables in the VARS section.
Example 3: BAD Custom Function
FUNCTION ( VARS ( @colorfield ),
IF (
ISINLIST(“Color Lookup List Name”, @colorattribute),
LOOKUP(“Color Lookup List Name”, @colorattribute),
“Blank” )
)
The variable in the VARS section doesn’t exist anywhere in the rule and the rule has a different variable defined. To fix this poorly constructed custom function, make sure the defined variable matches what’s used in the rule.
Custom Functions With Variables in Practice
In our example below, the seller populates a few fields for “Brand” data, and in some cases, the fields contain double hyphens, which the seller wants to replace with a single hyphen. The sellers may choose to use other brand fields with double hyphens in other rules, so we have created this custom function to accommodate that need for flexibility.
Structure Example: Clean Custom Function
In all cases where this custom function is used, the rule will look to the first non-blank entry among three fields: $itembrand, the @brandfield defined when the custom function is called, and $manufacturer. Since $itembrand isn’t consistently populated, we look to the defined field when calling the custom function, but if this @brandfield has double hyphens, they will be replaced with single hyphens:
Example 1: Title Rule
This is one of the rules that calls the custom function. The goal of this rule is to prepend the title with brand data and use the $brand field as our variable for potential cleanup when $itembrand is blank:
The referenced fields ultimately behave as they would if the function wasn’t a custom function, pulling in the data value for the defined field based on the SKU being processed. In processing the title rule, the $brand variable will be applied to the custom function as follows:
FUNCTION ( VARS ( $brand ),
IFBLANK(
$itembrand,
IF( CONTAINS( $brand, “ — “), REPLACE( $brand, “ — “, “ – “), “”),
$manufacturer
)
)
Example 2: Brand Rule
In this example, the goal is to output a brand field. We want to use the $nonstandardbrand field when the product is “Nike”.
The format and goal are completely different from the title rule in Example 1, but we still can reference and use the CLEANBRAND custom function in a similar way by encasing it in a different rule and referencing a different field for use in the custom function.
In processing the brand rule, the $nonstandardbrand variable will be applied to the custom function as follows:
FUNCTION ( VARS ( $nonstandardbrand ),
IFBLANK(
$itembrand,
IF( CONTAINS( $nonstandardbrand, “ — “), REPLACE( $nonstandardbrand, “ — “, “ – “), “”),
$manufacturer
)
)
Advanced Examples
Example 1: Without Variables
The overall length of this outer rule is only 276 characters — well below the maximum length of 2,000 characters. However, each one of the multiple custom functions defined for use in this rule has more than 1,000 characters. This format allows us to add/remove more labels easily, without the risk of breaking one of the other label rules. It also extends the maximum length of the rule calling the functions to more than 6,000 characters.
Note that the custom functions called use “1” as the variable definition, but no variables are used within each custom function — they will run on their own from start to finish, outputting the addition or removal of each designated marketplace label based on a large number of data evaluations.
Example 2: With One Variable
The color rule has two conditions to meet — the $producttype will ultimately determine which color attribute ($shirtcolor or $pantscolor) should be used within the custom function. The EXECUTERULE custom function then allows you to evaluate the input color field across the lookup lists defined. When no conversion can be located in those lists, it defaults to “Multi”.
Color Rule:
EXECUTERULE Custom Function:
Example 3: With Multiple Variables
Consider the following example.
The marketplace we are sending data to has 12 color fields across the different categories we’re listing in, and individual valid values for each field. We will call this custom function with 12 distinct business rules, varying lookup lists and color attributes, and we won’t always choose the same default field value.
These 12 different business rules can be written out individually and they will work without issue. That approach may be the better way to go in many cases — however, imagine you need to make a minor change to reference an override color field for all 12 rules. In this custom function design, we have the flexibility to effectively change multiple rules at once — we can make that change once to the custom function, and it will apply immediately to all 12 rules that call this function. If, instead, we create individual rules that execute independently, we would need to make the change to all 12 rules.
Within the example of the light bulb color rule given below, we need to define three variables that should be used in the COLORLOOKUP custom function when we call it. This example demonstrates how we might design a rule to call this custom function, which would satisfy one of the color field requirements associated with lights or light bulbs. The next use of this custom function will likely reference different fields and lookup lists.
Light Bulb Color:
COLORLOOKUP Custom Function:
Formatting Notes
When you define your variables, be sure to include quotes around text values and lookup list names (Example 1), to refrain from using quotes when the variable is an integer (and actually being used in reference to a number in the rule (see Example 2), and to use the $ symbol when referencing a stored field (Example 3).
Example 1: Text/Lookup List Reference
Calling on Custom Function:
PRICECOMPARE( “Color Lookup List”, “Multi-Colored” )
PRICECOMPARE Custom Function:
FUNCTION(VARS(@listname, @defaultcolor),
IF(
ISINLIST( @listname, $color ),
LOOKUP( @listname, $color ),
@defaultcolor
)
)
Example 2: Numeric Reference
Calling on Custom Function:
PRICECOMPARE( 10.99 )
PRICECOMPARE Custom Function:
FUNCTION(VARS(@number),
IF(
$buyitnowprice > @number,
$buyitnowprice,
@number
)
)
Example 3: Field Reference
Calling on Custom Function:
BACKUPPRICE( $retailprice )
BACKUPPRICE Custom Function:
FUNCTION(VARS(@backupprice),
IF(
$buyitnowprice > 50.00,
$buyitnowprice,
@backupprice
)
)
That’s all for today’s lesson. If you want to learn more and can’t wait two weeks for our next blog post, feel free to explore more about business rules on the Rithum Community. And if you’re struggling with a rule, remember that you can always open a case with support to assist you.
