Creating macro rules

Macro rules allow non-technical users to create macro conditions without any knowledge of K# macro syntax. The rules are internally implemented as predefined macro expressions, but appear as purely text-based clauses describing certain requirements. Users build conditions out of macro rules inside a dedicated Rule designer interface.

The system contains many different types of rules by default, and allows you to create custom rules to fulfill any requirements of your users. There are several categories of macro rules:

Defining macro rules

To prepare new macro rules for your users:

1. Navigate to the management interface for the appropriate type of rule (see the table above).

2. Click New macro rule.

3. Fill in the following properties:

   General
   Display name	Sets the name displayed to users in the list of macro rules in the rule designer. Also serves as a basic description of the rule’s purpose.
   Name	Serves as a unique identifier of the rule (for example in the API).
   Description	A text description of the rule’s purpose and parameters. The text appears as a tooltip when users hover over the rule in the rule designer.
   Enabled	If disabled, users cannot select the rule when building conditions. Note: Disabling a rule does not affect the functionality of existing conditions where users have added the given rule.
   Rule data
   User text	Defines the text displayed in the rule designer when users insert the rule into a condition. To add parameters into the text, enter the Column name of a specific parameter enclosed in curly brackets, for example {days}. In the rule designer, the parameter appears as an underlined section in the text. Users can set the parameter’s value by clicking the underlined text. See the Adding rule parameters section for more information.
   Condition	The actual condition represented by the rule. Define the condition through standard macro code (K#). The field provides autocomplete support. Add any parameters offered by the rule to the appropriate position in the code, using the same syntax as for the User text field, for example {days}. When the system resolves the condition, the parameter expression is replaced by the value set for the parameter by users in the rule designer.
   Required data	Limits for which conditions the macro rule is available. The rule only appears when building conditions that have the specified data items available in the resolving context. You can add multiple required data items separated by semicolons (;). Leave this property empty unless you are creating rules specifically for conditions with a customized resolving context.
   Requires context	Enable this property if the rule’s condition needs to access context data (information about the current user, the currently viewed page, etc.) in order to work correctly. This ensures that the rule only appears for conditions that have the context available when they are resolved. For example, the context is accessible when evaluating the conditions of Content personalization variants on the website’s page, but not when the system is building dynamic Contact groups.

4. Click Save.

Adding rule parameters

Parameters are variables inside macro rules that modify the resulting condition. By adding parameters, you can make flexible rules that are usable for a wide range of scenarios. For example, in a macro rule that requires the current user to be a member of certain roles, the names of the roles would be a parameter.

To create a parameter for a macro rule:

1. Edit the macro rule.

2. Open the Parameters tab.

3. Prepare the parameter as a form field. Every parameter has a certain data type and various other settings. The interface that users see when editing the parameter’s values depends on the selected Form control.

   Refer to Reference - Field editor for details about working with the field editor.

4. Click Save.

5. Switch to the rule’s General tab.

6. Place the parameter into the rule’s User text and Condition code.

   • The syntax for inserting parameters is the parameter’s Column name enclosed in curly brackets, for example {role}.
   • When the system resolves conditions containing the macro rule, the parameter expressions in the condition code are replaced by the values entered by users. You need to position the parameter expression accordingly.

7. Click Save.

Users can now set the values of the rule’s parameters when building conditions.

Modifying existing macro rules

When you make changes in the definition of a macro rule or its parameters, the system does NOT update the functionality of existing conditions. This may lead to incorrect behavior of conditions containing the modified rule.

To make sure your conditions are up-to-date, you need to manually perform the following steps after modifying an existing macro rule:

1. Find the condition fields that contain the rule. You can use the macro report tool to search.
2. Click Edit next to the field to open the rule designer.
3. If required, update the parameters for all occurrences of the modified rule.
4. Click Save & Close.

When you save the condition, the system uses the current definitions of the contained macro rules.