Anatomy of Sitecore Business Rule - Macros

In previous posts, we talked about field syntax and the basic structure of business rules. This time we are going to dive into macros in the business rules. Macros are used as part of the business rule syntax. The syntax looks like this and calls for 4 parameters. [Property to set, Operator/Macro, AdditionalParameters, Display text].

When I first started working with business rules the difference between operator and macro was confusing. To add to this confusion some of the out-of-the-box macros are named with the term "operator" (like ListOperator who's configuration points to a class called ListMacro and the class implements IRuleMacro). Anything under the path /sitecore/system/Settings/Rules/Definitions/Macros should be a macro and should implement IRuleMacro.

Macros have the follow characteristics:

• They inherit the IRuleMacro interface
• The interface requires this execute method void Execute(XElement element, string name, UrlString parameters, string value)
• The execute method returns a sheer response for showing a dialogue the user can select from. SheerResponse.ShowModalDialog(selectItemOptions.ToUrlString().ToString(), "1200px", "700px", string.Empty, true);

One of the most challenging things about Macros is knowing what parameters you can pass in on the "AdditionalParameters" field. In order to know what additional parameters you can pass in you have to look at the macro code in a tool a decompiler like dotPeek so you can see what the code is doing. Just click on the macro and use the "Type" field to find the correct assembly and class in that assembly. 

Here is an example of the Boost Macro. The green highlight shows the 3 parameters the code is looking for. 

I am not going to list all the Macros, their use and their parameters here. I thought about it but as soon as I list them out I simply created documentation that will go stale. Most of the Macros by name start to explain what they do. So first start by going off the name, plug it into your new rule and see what type of dialogue it produces. Then you can use a decompiler to dig deeper if you need to customize and understand all the parameters. To be honest, some of the parameters options are hard to explain without looking at the code. Hopefully, this post gives you some idea on how the macros come together though and the ability to really understand what is going on and how to use them.

We have not talked about creating your own custom macro yet but for those of you that take this information and run with it, I wanted to mention dependency injection. Macros, Operators, and Rules cannot do dependency injection. So to use dependant classes you will need to use the service locator pattern. Kam Figgy has covered where dependency injection works in Sitecore in a good post here.