Tweaking Kentico (3): Macro rules


Today we’ll learn a bit about macro rules in Kentico.

Macro rules become very useful when it comes to defining further conditions for your discounts, marketing automation processes, workflows, reports, validation of forms and many others. They allow you to take advantage of macros with no actual knowledge of their syntax. Marco rules are simply predefined sets of macros in given macro syntax (K#) re-written in common language to make them easier to use.

When a macro is possible to add to one of the mentioned objects, Kentico offers you a macro editor with 2 default options:

  1. Rule designer
  2. Code

The Rule designer loads all possible macro rules that could be applied in given context and you just use predefined UI to configure them, while the Code tab loads just a simple editor that enables you to enter the pure K# macro code.

Macro rules can be defined in 6 categories and according to the category the macro rule belongs to, it appears in a different administration interface. The following table shows what context is available for particular rule category (the table doesn’t contain all properties – just those important ones):


Available context

Available collections

Available properties



form validation






ActionResource, Metafiles, Thumbnail

ActionAllowedObjects, ActionAssemblyName, ActionClass, ActionDescription, ActionDisplayName, ActionEnabled, ActionID, ActionName, ActionResourceID



StepAction, StepWorkflow

StepActionID, StepAllowPublish, StepAllowReject, StepApporvedTemplateName, StepDisplayName, StepHasTimeout, StepIsAction, StepIsAllowed, StepIsArchived, StepIsDefault, StepIsDeleteable, StepIsEdit, StepIsFinished, StepIsPublished, StepIsStart, StepName, StepOrder, StepRolesSecurity, StepSendEmails, StepType, StepWorkflowID, StepActionID



Memberships, Orders, Personalizations, PurchasedProducts

IsMale, IsFemale, Email, FirstName, LastName, FullName, LastLogon, PreferredCultureCode, PreferredUICultureCode, UserAvatarID, UserGender, UserIsDomain, USerISEditor, UserISHidden, UserName, UserPhone, UserPicture, UserPosition, UserSignature, UserVisibility



Attachments, Categories, CultureVersions, DocumentAliases, DocumentContent, EventAttendees, NodeACLs, NodeClass, NodeTemplate, Personalization, RelatedDocuments

HasSKU, IsLink, IsLastVersion, SiteID, RelativeURL, AbsoluteURL, DocumentID, DocumentName, NodeAliasPath, NodeHasChildren, NodeLevel, NodeOrder, NodeSKUID



WorkflowScopes, WorkflowSteps

WorkflowAllowedObjects, WorkflowEnabled, WorkflowDisplayName, WorkflowNotificationTemplateName, WorkflowSendApproveEmails, WorkflowSendEmails, WorkflowType

on-line marketing


ActivityOriginalContact, Board, Form, Newsletter, Issue, Poll,

ActivityId, ActivityComment, ActivityCampaign, ActivityCulture, ActivityIPAddress, ActivityNodeID, ActivityOriginalContactID, ActivityTitle, ActivityURL, ActivityValue



Accounts, Activities, ContactCountry, ContactPersona, ContactState, Contact, Status, IPs, Orders, Processes, PurchasedProducts, Roles, UserAgents

ContactAddress, ContactCity, ContactCountryID, ContactGender, ContactID, ContactIsAnonymous, ContactLastLogon, ContactNotes, ContactFirstName, ContactLastName



catalog rules



order rules


AddressCountry, AddressState

AdressCity, AddressCountryID, AddressLine1, AddressLine2, AddressPersonalName, AddressPhone, AddressStateID, AddressZip






CurrencyCode, CurrencyDisplayName, CurrencyEnabled, CurrencyID, CurrencyIsMain, CurrencyNAme, CurrencyRoundTo



Addresses, AllOlders, CreditEvents, Customercountry, CustomerState, CustomerUser, Memberships, Orders, PurchasedProducts, Whishlist

CustomerCompany, CustomerFirstName, CustomerLastName, CustomerPhone, CustomerID, CustomerUserID, CustomerStateID, CustomerPrefferedCurencyID, CurrencyPrefferedShippingOptionID, CustomerPreferredPaymentOptionID









CartProducts, ShoppingCartItems, ShoppingCartDiscountCoupon, ShoppingCartUser

HasUsableCoupon, IsEmpty, IsDiscountApplied, IsShippingNeeded, ItemsDiscount, OrderDiscount,


Except for the table above, any macro rule can also be extended by any number of custom properties. You can do this while editing your macro rule in the Parameters section and the parameter is then available in the rule using {parameterCodeName} syntax. There are also automatic parameters available for all macro rules.

Now, let’s create some macro rules because working examples are the best way to learn how things work. Here are two macro rule examples:

1. Form validation

Let’s say we want to have a validation rule that checks if entered email address is from a particular top level domain (.com, .net or .org). We need to create a macro rule first:

  • Display name: Top level domain
  • User text: E-mail address ends with {topleveldomain}
  • Condition: Value.EndsWith("{topleveldomain}")

The most important part is the Condition that takes the value of the field you apply this condition to and checks whether it ends with selected parameter. Those 3 options would be a parameter for our validation rule and we make it as a dropdown list:

  • Field name: topleveldomain
  • Data type: Text
  • Size: 4
  • Required: true
  • Field caption: select top level domain
  • Form control: Drop-down list
  • Data source: List of options
    • .com
    • .net
    • .org

Now you can use this new validation rule for instance in your on-line form.

2. Catalog rules

As you probably know a product in Kentico is made out of two objects -> an SKU and a Page. The SKU object holds the information about the price, inventory, product image, etc., while the page has all the other details containing product specific custom properties.

Here is an example of applying a discount to a product based on a custom page property (e.g. discount for all laptops with LED display type).

First, we can create the macro rule:

  • Display name: Product field contains
  • User text: Product's field {field} of {classname} contains {value}
  • Condition: Documents.ClassNames("{classname}").WithAllData.Where("NodeSKUID="+SKU.SKUID).FirstItem.GetValue("{field}").Contains("{value}")

As we learned in previous macro rule, we need to specify parameters used in our condition:

  • Field name: classname
  • Data type: Text
  • Size: 200
  • Required: true
  • Field caption: select page type
  • Form control: Page types selector
  • Field name: field
  • Data type: Text
  • Size: 1000
  • Required: true
  • Field caption: enter field name
  • Form control: Text box
  • Field name: value
  • Data type: Text
  • Size: 1000
  • Required: true
  • Field caption: enter value
  • Form control: Text box

The Apply to condition for a catalog discount would look like this:

Product's field LaptopDisplayType of Laptop (CMS.Laptop) contains LED

Share this article on   LinkedIn

Jan Hermann

I am a support engineer in Kentico and I take care of any issue you have!