How To

Creating Custom Functions and Using Rules Within Rules

This page will detail the following related to custom functions: 

Prerequisites


You should be familiar with the following topics:

 

Creating Custom Functions and Using Rules Within Rules


Have you ever written several business rules that are quite similar?  For example, maybe you've written a business rule that uses a regular expression to remove text from your description field, and another that uses the same regular expression to remove that text from your title field.  Or maybe you've written a business rule that you'd like to embed within another business rule; for example, let's say you've create a rule that prepends your brand onto your title, and you'd like to prepend the output of THAT onto your description.  In both these cases, you've come up with some business rules, or pieces of a business rule, that you'd like to re-use.  The way to do that is to create a custom function .


Custom functions are special business rules that you create and can use inside your other business rules.  They act just like the built-in functions that you're familiar with, such as IF, CONCATENATE, REPLACE, and so on.  That is, they have one or more  inputs and they output a value.  In this article, we'll discuss how to create and use custom functions.

Look at this business rule:

using custom functions

Note that this rule is using two functions you've never seen before: "CLEANUP" and "APPENDSKU."   These are custom functions that have been created for that account.  Here's the definition of "CLEANUP" :

cleanup function

 

Creating a Custom Function


  • Usually you've decided to create a custom function because you're re-writing the same part of a business rule over and over.  Let's say we have these two rules:

REGEXREPLACE($itemtitle,"\{.+?\}","")
REGEXREPLACE($itemdescription,"\{.+?\}","")

  • Notice that the only difference between these two rules is one uses $itemtitle and the other $itemdescription.  If we abstract away this difference:

REGEXREPLACE( x ,"\{.+?\}","")

  • We've put an x where $itemtitle and $itemdescription were.  This is a lot like algebra: x can be anything.  Now all we do is create a new rule with the proper syntax:

FUNCTION(VARS(@X),REGEXREPLACE(@X,"\{.+?\}",""))

  • We've replaced the x with @X, which is the proper way for indicating a parameter in a custom function.  You don't have to use "X."  You can use any combination of letters.  I'm partial to X and Y because I just love algebra so much. 
     
  • Save your custom function.  You have to give it a name, of course, and it's probably a good idea to put some information in the description about what the function does.  Now you can use your custom function in any of your other business rules.  Just call it by name.  Let's say we name the function above "Clean Text."  Then you'd use it in a rule like this:

CLEANTEXT($itemdescription)

Note that we've removed the space from the name.

Technical Info and Warnings


As you can see, the syntax for a custom function is:

FUNCTION(VARS(@v1,@v2,...@vn),expression)

  • Do NOT use a number as the first character of a function name. 
  • Your custom functions show up in the Business Rules list view just like the regular business rules. HOWEVER, we do not show them as being used by other rules (i.e., you can delete a custom function you're using in a business rule, which could be bad)
  • You should NOT assign a custom function to a field in a template
  • The function must have at least one parameter (e.g., @X), but can have more
  • The expression can be, just as with a regular business rule, any combination of text, numbers, inventory fields, function calls, and also parameters.
  • However, the expression can NOT contain calls to ANY custom function---only to the standard functions
  • You can name the function whatever you want; however, the name will be "cleaned" of spaces and non-alphanumeric characters, just as inventory field names are
  • The custom functions are account-specific
  • You can use as many custom functions in your "regular" business rules as you like; they act just like the standard functions

Back to Top  

Calling a Rule Within a Rule


Often users want to call one rule from another rule.  This can be done by turning the "inner" rule into a custom function with one parameter; the expression just doesn't use the parameter at all, though.  The downside is that the "inner" rule can no longer be used as a rule.  For example, suppose you have a rule called "Clean Title" that removes the brand from the title:

REGEXREPLACE($ITEMTITLE,$BRAND,"")

You're using this rule for the title field in several of your feeds.  You also want to create a "Description plus Title" rule that appends this clean title to your description:

JOIN(" ",$ITEMDESCRIPTION, TBD)

If you change the "Clean Title" rule to the following:

FUNCTION(VARS(@X),REGEXREPLACE($ITEMTITLE,$BRAND,""))

Then your "Description plus Title" rule can be:

JOIN(" ",$ITEMDESCRIPTION, CLEANTITLE(0))

However, you can no longer use the "Clean Title" rule on your templates.  You would have to create a new rule that just calls CLEANTITLE, and use that on your templates:

CLEANTITLE(0)

Back to Top  
 

Eval to Indicate Brand Differences



Quite frequently I've had requests to help write a business rule something like this:

For each of my brand, I want my rule to do something slightly different.  Can I create a lookup list that has brand in the left-hand column, and then the right-hand is basically a business rule that I want to use for that brand.  For example:

Brand X    JOIN(" ",$title,$brand,$manufacturer)
Brand Y    REPLACE($title,$brand,"")

Then, the "real" rule would look like this:

SOMETHING(LOOKUP("The List",$brand))

The problem was that the "SOMETHING" function just didn't exist.  Until now!

Introducing a new function called "EVAL."  EVAL has one parameter: a text value.  As with all functions, this value can come from anywhere: you can "hardcode" it directly, you can pull it from an inventory attribute, or from the output of another function.  Just remember that the text MUST be something that would be valid as a business rule, and that text is going to be "run" as a business rule.

Here's how to think about it:  create a rule that "writes" a rule.  That is, create a business rule whose output is some text that "looks" like a business rule.  So for our example above, the rule that writes a rule is:

LOOKUP("The List",$brand)

Then you just wrap an EVAL around that:

EVAL(LOOKUP("The List",$brand))

Some technical notes:

  • *EVAL doesn't know how to call your custom functions, so avoid these in your input text 
  • *If your input text have a syntax error, EVAL will "drop" the item from feeds

 

Back to Top

This page will detail the following related to custom functions: 

Prerequisites


You should be familiar with the following topics:

 

Creating Custom Functions and Using Rules Within Rules


Have you ever written several business rules that are quite similar?  For example, maybe you've written a business rule that uses a regular expression to remove text from your description field, and another that uses the same regular expression to remove that text from your title field.  Or maybe you've written a business rule that you'd like to embed within another business rule; for example, let's say you've create a rule that prepends your brand onto your title, and you'd like to prepend the output of THAT onto your description.  In both these cases, you've come up with some business rules, or pieces of a business rule, that you'd like to re-use.  The way to do that is to create a custom function .


Custom functions are special business rules that you create and can use inside your other business rules.  They act just like the built-in functions that you're familiar with, such as IF, CONCATENATE, REPLACE, and so on.  That is, they have one or more  inputs and they output a value.  In this article, we'll discuss how to create and use custom functions.

Look at this business rule:

using custom functions

Note that this rule is using two functions you've never seen before: "CLEANUP" and "APPENDSKU."   These are custom functions that have been created for that account.  Here's the definition of "CLEANUP" :

cleanup function

 

Creating a Custom Function


  • Usually you've decided to create a custom function because you're re-writing the same part of a business rule over and over.  Let's say we have these two rules:

REGEXREPLACE($itemtitle,"\{.+?\}","")
REGEXREPLACE($itemdescription,"\{.+?\}","")

  • Notice that the only difference between these two rules is one uses $itemtitle and the other $itemdescription.  If we abstract away this difference:

REGEXREPLACE( x ,"\{.+?\}","")

  • We've put an x where $itemtitle and $itemdescription were.  This is a lot like algebra: x can be anything.  Now all we do is create a new rule with the proper syntax:

FUNCTION(VARS(@X),REGEXREPLACE(@X,"\{.+?\}",""))

  • We've replaced the x with @X, which is the proper way for indicating a parameter in a custom function.  You don't have to use "X."  You can use any combination of letters.  I'm partial to X and Y because I just love algebra so much. 
     
  • Save your custom function.  You have to give it a name, of course, and it's probably a good idea to put some information in the description about what the function does.  Now you can use your custom function in any of your other business rules.  Just call it by name.  Let's say we name the function above "Clean Text."  Then you'd use it in a rule like this:

CLEANTEXT($itemdescription)

Note that we've removed the space from the name.

Technical Info and Warnings


As you can see, the syntax for a custom function is:

FUNCTION(VARS(@v1,@v2,...@vn),expression)

  • Do NOT use a number as the first character of a function name. 
  • Your custom functions show up in the Business Rules list view just like the regular business rules. HOWEVER, we do not show them as being used by other rules (i.e., you can delete a custom function you're using in a business rule, which could be bad)
  • You should NOT assign a custom function to a field in a template
  • The function must have at least one parameter (e.g., @X), but can have more
  • The expression can be, just as with a regular business rule, any combination of text, numbers, inventory fields, function calls, and also parameters.
  • However, the expression can NOT contain calls to ANY custom function---only to the standard functions
  • You can name the function whatever you want; however, the name will be "cleaned" of spaces and non-alphanumeric characters, just as inventory field names are
  • The custom functions are account-specific
  • You can use as many custom functions in your "regular" business rules as you like; they act just like the standard functions

Back to Top  

Calling a Rule Within a Rule


Often users want to call one rule from another rule.  This can be done by turning the "inner" rule into a custom function with one parameter; the expression just doesn't use the parameter at all, though.  The downside is that the "inner" rule can no longer be used as a rule.  For example, suppose you have a rule called "Clean Title" that removes the brand from the title:

REGEXREPLACE($ITEMTITLE,$BRAND,"")

You're using this rule for the title field in several of your feeds.  You also want to create a "Description plus Title" rule that appends this clean title to your description:

JOIN(" ",$ITEMDESCRIPTION, TBD)

If you change the "Clean Title" rule to the following:

FUNCTION(VARS(@X),REGEXREPLACE($ITEMTITLE,$BRAND,""))

Then your "Description plus Title" rule can be:

JOIN(" ",$ITEMDESCRIPTION, CLEANTITLE(0))

However, you can no longer use the "Clean Title" rule on your templates.  You would have to create a new rule that just calls CLEANTITLE, and use that on your templates:

CLEANTITLE(0)

Back to Top  
 

Eval to Indicate Brand Differences



Quite frequently I've had requests to help write a business rule something like this:

For each of my brand, I want my rule to do something slightly different.  Can I create a lookup list that has brand in the left-hand column, and then the right-hand is basically a business rule that I want to use for that brand.  For example:

Brand X    JOIN(" ",$title,$brand,$manufacturer)
Brand Y    REPLACE($title,$brand,"")

Then, the "real" rule would look like this:

SOMETHING(LOOKUP("The List",$brand))

The problem was that the "SOMETHING" function just didn't exist.  Until now!

Introducing a new function called "EVAL."  EVAL has one parameter: a text value.  As with all functions, this value can come from anywhere: you can "hardcode" it directly, you can pull it from an inventory attribute, or from the output of another function.  Just remember that the text MUST be something that would be valid as a business rule, and that text is going to be "run" as a business rule.

Here's how to think about it:  create a rule that "writes" a rule.  That is, create a business rule whose output is some text that "looks" like a business rule.  So for our example above, the rule that writes a rule is:

LOOKUP("The List",$brand)

Then you just wrap an EVAL around that:

EVAL(LOOKUP("The List",$brand))

Some technical notes:

  • *EVAL doesn't know how to call your custom functions, so avoid these in your input text 
  • *If your input text have a syntax error, EVAL will "drop" the item from feeds

 

Back to Top

0
Your rating: None Average: 1.7 (3 votes)
0
Your rating: None Average: 1.7 (3 votes)