Getting started with basic selection rules - expanded mode
Overview
The following features are available at a basic selection rule when it is displayed in expanded mode.
Toolbox
The basic selection rule’s toolbox is shown to the left.
Its display is controlled using the Show/Hide Toolbox button. The toolbox is shown by default.
The toolbox contains three tabs – Tools, Options and Comments. Each is documented separately.
Toolbox – Tools Tab
The toolbox’s Tools tab exposes the following:
View Waterfall Counts: this button is enabled once a criterion has been added to a basic selection rule. Clicking it displays the selection rule’s waterfall counts in the Waterfall Counts Window, which is described in the Rule Designer documentation.
Open Data Viewer: clicking this button displays the Data Viewer Window. The Data Viewer allows you to view a sample of the records targeted by the current basic selection rule. For more information, please see the Rule Designer documentation.
View Insights: this button is available when a basic selection rule has been saved. Clicking it displays insights relating to the current basic selection rule in the Insights Window. For more information, please see the Rule Designer documentation.
Export this Rule: allows you to export the records that match the basic selection rule's criteria to a file. For more information, please see the Rule Designer documentation.
Manage Test Placeholders: clicking this button allows you to set placeholder attribute values to be used when the rule is run, using the [Selection Rule Name] - Test Attribute Placeholders dialog. Please see the Placeholder Attributes section in the Rule Designer documentation, and the Attribute Placeholders Dialog section in the Framework documentation, for more information.
Convert to Standard Selection Rule: this option allows you to convert the basic selection rule to a standard selection rule (thereby allowing you to take advantage of the latter's wider range of features - for further information, please see the Standard Selection Rule documentation). Access to Convert is controlled by the Selection Rule – Basic – Convert to Standard functional permission. Once you have converted to a standard selection rule, you cannot convert back to a basic selection rule. Invocation of the button is protected by an 'Are You Sure?' dialog:
After conversion, the basic selection rule becomes a standard selection rule. Its subtype is changed appropriately, and its contents mirror those in the basic selection rule. Criteria are created using attributes sourced from the rule’s SQL database definition. Any linked basic selection rules are created as criteria within the standard rule. Note that you cannot convert if the basic selection rule contains one or more contact rules.
Refine Criteria using AI: this option is only displayed if creation of rule criteria using AI is enabled in the current basic selection rule, and when the current user has the Selection Rule - Basic - AI functional permission. Invocation displays the ‘Tell me what you’d like to build’ overlay, which is discussed in detail elsewhere in this documentation.
At its display, the overlay contains the most-recently used AI prompt. When Build is invoked, an 'Are You Sure?' dialog is shown. If you elect to proceed, newly-generated criteria will replace all existing criteria.
Toolbox – Options Tab
The toolbox’s Options tab exposes the following:
View Generated SQL: clicking this button allows you to view the SQL that will be executed on running a rule in the '[Rule name] - Generated SQL' dialog. For more information, please see the Rule Designer documentation.
Copy Trace log to Clipboard: this option is always available, irrespective of as to whether the basic selection rule has been saved or contains outstanding changes. If the rule has not been run before, an informational message advises that:
If the rule has been run, a message advises that the SQL trace log has been copied to the clipboard. The content contains the trace logs associated with the basic selection rule's count execution. A maximum of 100 log entries are copied to the clipboard.
The following are captured for each log entry:
Execution type
Context
Query status
Query result
Started
Ended
Duration
File
Query string
Error Message (if applicable)
Open Linked Rules in Workspace: upon invocation, all selection rules linked to the current rule are opened in the same Rule Designer instance. Linked rules are opened in collapsed mode. Any rules that are already open in the workspace are ignored. A message is displayed to advise of any rules that are already open in other Rule Designer instances. A message is also shown if no rules are found to open.
Realtime API section: containing the following:
Published Status: read-only, and one of:
Never Published: the following information tooltip is provided:
Published: the following information tooltip is provided:
Unpublished: the following information tooltip is provided:
Refresh: you must click this button to manually refresh the file's latest Published Status (published status changes are not displayed automatically).
Publish to Realtime API: clicking this button allows you to publish the file for use with the RPI Realtime API. It is enabled when the file is valid and contains no unsaved changes. Invocation creates a Publish job and displays it in the My Jobs dialog. Following a successful publish, the file's Published Status is set to Published, and the Unpublish from the Realtime API button is displayed.
Note that you cannot publish a basic selection rule when its SQL database definition's Realtime Mode is set to one of 'Use NoSQL Aux...' or 'Use SQL Aux...' and one or more attributes in use within the same remains unmapped within the SQL database definition. If a rule smart asset makes use of such a basic selection rule, only Batch Outbound is supported.
Unpublish from Realtime API: this button is displayed and enabled when a file is Published. Clicking it unpublishes the file, meaning it can no longer be used by the RPI Realtime API, and is protected by an 'Are You Sure?' dialog. Upon invocation, an Unpublish job is created and displayed in the My Jobs dialog. Following a successful unpublish, the file's Published Status is set to Unpublished, and the Unpublish from the Realtime API button is hidden.
Publish ID: this read-only GUID is used to uniquely identify the rule during evaluation by the Realtime API. You can select it to copy it to the clipboard.
When a rule is evaluated using the Realtime API, if its criteria are satisfied, the returned ResultContent is true. If not satisfied, the returned ResultContent is false.
Toolbox – Comments Tab
The toolbox’s Comments tab exposes the following:
Comment: you can add optionally add comments to the rule, which will be persisted with the new version of the file created when it is next saved. Comments are added using a multi-line text field, and can be a maximum of 1000 characters in length.
Comment history: if no comments have been saved with the rule, a message is displayed:
If comments have been saved, they are displayed in reverse chronological order.
The following read-only information is displayed for each comment in the comment history:
Username
File version
Date/time added
Comment
Definition
This dropdown allows you to select a SQL database definition, which defines the attributes available when building criteria, and well as optionally providing access to contact rules.
Selection of a definition is mandatory. If you change a rule’s definition having added one or more criteria, any existing criteria are cleared without display of an ‘Are You Sure?’ dialog.
Resolution
This dropdown property allows you to choose a key to be used when selecting records matching the rule's criteria.
It lists the current definition's database key by default, and any additional database keys defined at the current SQL database definition. The count of records targeted by the rule reflects the value selected at this property.
Count
A basic selection rule’s count describes the number of records that matched the rule’s criteria at the point in time when the count was last refreshed.
The date and time at which the count was generated is display immediately below the count itself.
When you open a selection rule, if a count had been generated previously, the most recently-generated version thereof is displayed automatically at the panel. If the count is more than an hour old, an information icon is shown. A tooltip is shown on hovering over the same:
Refresh Count
You can refresh a basic selection rule's count by clicking the button shown to the right of its count.
A Refreshing count… indicator is displayed while the system determines the number of records that match the rule’s criteria.
The act of getting a basic selection rule count creates a Count job. The My Jobs Dialog is not shown automatically at such a job’s creation. You can view count jobs that match the current filter settings within the Dialog. Details of the job and Dialog are provided in the My Jobs documentation.
If an error occurs when refreshing a basic selection rule's count, exception details are written to the server and client logs.
When the current RPI installation is using a SQL Server data warehouse or auxiliary database, if the system is unable to connect when running a selection rule count (for example due to the database server not being found, the database login failing (due e.g. to the database being detached) or because of a deadlock), a series of attempts to reach the database are made (over a maximum of a 10-minute period). After this time the series of retries are abandoned. All retry details are logged to the server log.
A basic selection rule's Realtime Mode property is set in its SQL database definition. More details are provided in the Configuration documentation. Realtime modes other than 'Run as SQL' apply only when a rule is evaluated in a Realtime context. If a rule is configured with a SQL definition that is set up to use Realtime, on getting the rule's count in the Rule Designer, RPI will always query the database, rather than the RPI Realtime cache.
All/Any
This dropdown property is displayed just below a basic selection rule’s header.
It allows you to define how a basic selection rule’s criteria are to be treated when a rule’s count is generated. Two options are available – All (the default) and Any.
If All/Any is set to All, for a record to be targeted, all criteria in the rule must be satisfied. If set to Any, only one of the criteria need be met for the rule to be satisfied.
Note that All/Any is always displayed, even if a basic selection rule contains only a single criterion. In this case the property has no effect.
All/Any is also shown at a criteria list, to determine how the criteria listed therein are to be treated at the parent rule’s execution.
Add New Criterion Button
This button allows you to add a criterion to a basic selection rule.
Clicking the button displays a slide-out panel.
The panel's header initially reflects the currently-selected context at the point of its being displayed. If the rule as a whole was selected, the panel's header is set to the currently-selected SQL database definition's name. If a criteria list/table is selected, its name is displayed instead. A '<' button is displayed to the left of the panel's header. You can click the header to return to the parent context.
All criteria applicable to the current context are listed in the panel.
Nested tables are displayed alongside criteria and are shown with a '>' button to the right. If clicked, the contents of the panel are replaced with the contents of the nested table, and the panel's title is updated to reflect the same. Note that nested tables can contain nested child tables, if thus specified at the selected SQL database definition.
Clicking a criterion within the panel adds a matching criterion to the basic selection rule.
If appropriate, a new criterion is created within criteria lists representing the attribute's position in the table hierarchy defined at the selected SQL database definition.
If a criteria list is selected when a criterion is added, if the selected criterion fits within the criteria list's hierarchy, it is added (along with any criteria lists necessary to represent the table structure). If the selected criterion does not fit within the hierarchy, a warning is thrown.
A newly-added criterion is presented in Edit mode by default. If you were editing an existing criterion when Add New was clicked, Edit mode is exited in the former context, and the new criterion is shown in Edit mode.
If the currently-selected SQL database definition’s Enable contact rules property is checked, three additional nested sets of criteria (Contact Rules, Offer History - [Audience Definition] and Offer History Sandbox - [Audience Definition] are available when adding a new criterion. These are documented separately.
When adding a system variable placeholder criterion to a basic selection rule, on viewing the Test Attribute Placeholders dialog, the system variable's value is displayed as default only if exposing system variable values. For more information on system variables, please see the Framework documentation.
Canvas
A basic selection rule’s canvas initially displays a message:
Criteria, criteria lists and linked selection rules are described elsewhere in this documentation.
The following options are available when you right click a basic selection rule’s canvas:
Add New Criteria List: adds a new, empty criteria list to the basic selection rule.
Paste: only available if the clipboard contains something that may legitimately be pasted into the rule (e.g. a criterion or criteria list).
Add New Criteria List
This button is displayed below the basic selection rule’s canvas.
Clicking it adds a new, unconfigured criteria list to the basic selection rule. The criteria list is added to the root level of the currently-selected rule, after all existing criteria, criteria lists and linked selection rules.
Details on criteria lists are provided elsewhere in the basic selection rule documentation.
Contact Rules
If the currently-selected SQL database definition’s Enable contact rules property is checked, three additional sets of contact rule criteria are made available when adding a criterion:
Contact Rules: these criteria facilitate the selection of records that have previously been contacted via RPI. The following types of contact rules are supported:
You can choose a criterion type that satisfies your requirements – for example, choose ‘Any contact’ to target any records previously contacted via RPI, or choose ‘Offer name’ to target only those records that were in receipt of a specific RPI offer.
When presented in edit mode, a contact rule criterion has the following properties:
Textual description
‘Compares the attribute to a contact count’
Contacted: allows you to specify the number of times a record has been contacted. The following dropdown values are available:
Any number of times (the default)
Not contacted
Exactly - Has been contacted on a specific number of times
More than - Has been contacted more than a specific number of times
Less than - Has been contacted less than a specific number of times
time(s): this integer property accompanies [Dropdown 1] and is shown when that field's value is set to one of 'More than' or 'Less than'. It defaults to 1 and accepts a minimum value of 0 and a maximum value of 9,999.
Duration: allows you to specify the timeframe in which a contact needs to have taken place for the criterion to be satisfied. The following dropdown values are available:
At any time (the default)
In the last
day(s): this integer property accompanies [Dropdown 2] and is shown when that field's value is set to 'In the last'. It defaults to 7 and accepts a minimum value of 1 and a maximum value of 9,999.
Where the [Criterion Type] name is: this property is displayed for all contact rule criterion types other than 'Any contact', and allows you to specify the name of the context in which records were targeted (for example, in an Interaction name contact rule, this field would be used to specify the names of the interaction(s) in which records were contacted. Provision of a value at the field is mandatory when it is shown. You can select from a list of predefined values (if available) using the Choose Values dialog.
When presented in read-only mode, a contact rule criterion appears as per the following example:
The Metadata contact rules group is available when a basic selection rule’s audience definition is configured with one or more metadata attributes. The criteria available are defined by the configured metadata attributes:
A record is deemed to be targeted by a metadata contact rule criterion when at least one of its production offer history meta records satisfies the criterion's stipulations. Metadata contact rules can be used both when running in SQL and realtime modes.
Offer History - [Audience Definition]: these criteria allow you to target records on the presence of matching records in the selected SQL database definition’s Audience definition’s Offer History tables. The following criterion types are supported:
Activity name
Address key
Audience ID
Audience output ID
Audience output name
Channel execution ID
Channel name: predefined values available
Delivery method: predefined values available
First execution date
Interaction name
Is selected
Last execution date
Offer channel name
Offer name
RP contact ID
Seed count
State
State detail
State timestamp
Target count
Timestamp
Workflow ID
Offer History Attributes: as defined at the audience definition.
Offer History Sandbox - [Audience Definition]: the same set of criteria are also available to assist in the targeting of records previously contacted in Test mode, and for which offer history sandbox table entries exist.
Note that you can use basic selection rule contact rule criteria in a Realtime context when Realtime offer history output has been enabled at the Audience Definition specified at the rule’s SQL database definition. For more information, please see the Audience Definition configuration guide.
Criteria
Criteria define the records to be targeted by a basic selection rule. By adding criteria to a basic selection rule you limit the records to be counted when the rule is run. For example, adding a ‘Gender is female’ criterion causes only female records to be counted.
A dark border is displayed at a criterion when it is when selected.
Provision of criteria is optional. If you get a basic selection rule's count with no criteria specified, a count of all records at the SQL database definition’s resolution is returned.
You can add a criterion to a basic selection rule by clicking the Add New Criterion button (documented separately). You can also do so by dragging an attribute that is present in the rule’s SQL database definition from the toolbox and dropping it onto the rule.
When adding a criterion from a child table within the SQL database definition, if adding the criterion at the level of the basic selection rule itself, a parent criteria list is created automatically, and the new criteria created within. If a criteria list matching the level of the nested criterion is selected at its creation, the new criterion is added within the criteria list. If a criteria list with a level other than the new criterion's level is selected at the criterion's creation, a warning is thrown.
A validation error is raised if the attribute on which the criterion is based cannot be located in the currently-selected definition (this may occur if, for example, you change the definition after a criterion has been added).
You can re-order read-only criteria within a basic selection rule using drag and drop. If you attempt to drag a criterion into an incompatible parent criteria list, a message is displayed to advise that you are unable to do so.
You can also drag and drop criteria between basic selection rules. Drag and drop is not supported at criteria when in edit mode.
Criteria can be presented in either read-only or edit mode. Only a single criterion can be displayed in edit mode at a time.
When in read-only mode, the following are shown at a criterion:
Resolution level icon
Plain text interpretation of settings: consisting of the criterion name, operator and any specified values, e.g.:
Configure: clicking this button puts the criterion into edit mode.
Actions: clicking this button displays a context menu, which exposes the following:
Cut
Copy
Remove: removes the criterion without displaying an 'Are You Sure?' dialog.
Note that the same context menu is shown when right-clicking a criterion.
When in edit mode, the following are shown:
Textual criterion description.
Operator: a dropdown field, the values exposed by which are data type-appropriate.
Value(s): the values supported at a criterion are appropriate for its data type. If a criterion supports the provision of values, the following is initially displayed at its value:
If a string criterion type, if predefined values exist for the decision criterion type, clicking the value field displays the Choose Values dialog, in which you can select the values you require. More information on the Choose Values dialog can be found in the RPI Framework documentation.
If predefined values are not supported, values are supplied using the Specify Values dialog. More information on the Specify Values dialog can also be found in the RPI Framework documentation.
If a numeric criterion type, a masked field restricts data entry to a numeric value. If one of the ‘Is in list’ or ‘Is not in list’ operators is selected, multiple values can be supplied using the Specify values dialog (see above for details).
If a date criterion type, display depends on the selected operator.
If ‘Equals’ or ‘Does not equal’, the following are shown:
A date or datetime picker, defaulting to today/now, is shown. Selecting the button to its right sets the value to the Current date/time.
If ‘After’, ‘Before’ or ‘Within’, the following are shown:
If ‘Is’, the following are shown:
Note that if set, values are calculated using the time zone specified in system configuration setting RuleTimezoneOverride. If blank, the server time zone is used.
If a Boolean decision criterion type, the following values are available:
Is True
Is False (the default)
Note that if an Exists or Does not exist operator has been selected, Value is not shown.
Done: clicking this button returns the criterion to read-only mode.
The following keyboard shortcuts are supported at read-only criteria:
Ctrl-C: copy
Ctrl-X: cut
Delete: remove
Please note the following:
You can get a basic selection rule's count when one or more criteria are in edit mode.
You can put a read-only criterion into edit mode by double-clicking it.
Criteria List
A criteria list allows you to group related criteria, in order treat such criteria as independent blocks that must be entirely satisfied or not satisfied (using All/Any as required).
The following are displayed at a criteria list:
Include/Exclude: defines whether the criteria within the group must be satisfied or not satisfied for the criteria list itself to be satisfied.
All/Any: defines how the criteria within the criteria list are to be treated. If set to All, all criteria within the criteria list must be satisfied for the group as a whole to be satisfied. When set to Any, any of the criteria must be satisfied for the group to be satisfied.
List Definition: this can be set in accordance with the rule’s currently-selected Definition, or, if its criteria exist within a child table within the SQL database definition, to a value matching that table’s name.
Criteria List Description: this optional property can be a maximum of 1000 characters in length.
Actions: clicking this button displays a context menu, which exposes the following:
Cut
Copy
Remove: removes the criteria list without displaying an 'Are You Sure?' dialog.
Note that the same context menu is shown when right-clicking a criteria list.
You can re-order criteria lists within their peer criteria and criteria lists using drag and drop. You can also re-order criteria within a criteria list. You cannot drag a criterion out of its parent criteria list.
Nested criteria lists are supported; the maximum number of nested criteria lists that can be added is limited to 5.
The following keyboard shortcuts are supported at criteria lists:
Ctrl-C: copy
Ctrl-X: cut
Ctrl-V: paste
Delete: remove
Linked Basic Selection Rule
You can create a link to a basic selection rule within an outer basic selection rule by dragging a basic selection rule file from the toolbox and dropping it into the outer rule. You cannot create a link to a standard or NoSQL selection rule within a basic selection rule.
When a link is created to a basic selection rule within a basic selection rule, it is shown like this:
The following are shown:
Include/Exclude: this setting allows you to specify that the linked basic selection rule's criteria should be met or not met for its usage in this context to be satisfied.
Basic selection rule name
Open latest version: clicking this button opens the linked basic selection rule in the current Rule Designer tab.
Pop out: displays the linked rule in an independent, modeless Window. For more information, please see the Rule Designer documentation.
View Insights: clicking this button displays insights pertaining to the linked basic selection rule in the Insights Window. For more information, please see the Rule Designer documentation.
Actions: clicking this button displays a context menu, which exposes the following:
Cut
Copy
Remove: removes the linked selection rule without displaying an 'Are You Sure?' dialog.
Note that the same context menu is shown when right-clicking a linked selection rule.
The following keyboard shortcuts are supported at linked rules:
Ctrl-C: copy
Ctrl-X: cut
Delete: remove
Placeholder Criterion
If a basic selection rule's SQL database definition is configured with one or more Placeholder attributes, they can be used as criteria within the same. A basic selection rule placeholder criterion is presented in read-only mode as per the following example:
In edit mode, the following are shown at a placeholder attribute:
Operator
Value: set to the name of the placeholder criterion.
You can manage basic selection rule placeholders at the Test Attribute Placeholders dialog, which is shown on invocation of Manage Test Placeholders at the toolbox’s Tools tab. For more information on using placeholders in selection rules, please see the Rule Designer documentation.
Aggregate Filter Overrides
Having added a criterion based on an aggregation attribute to a basic selection rule, an additional property is available. When in Edit mode, the following is shown:
Aggregate filter override: you can optionally select another basic selection rule to apply a filter to the aggregate, such that when the rule's count is calculated, only records targeted by the filter rule are included in aggregate calculations. You can populate the property by browsing for a basic selection rule, or by using drag and drop. You can also initiate the creation of a new basic selection rule. Once populated, Open Latest Version, View Insights and Clear inline buttons are available. Context menu options are also available. Note that the selected rule must resolve to same table as the aggregation attribute's Aggregation table.
When viewed in read-only mode, a criterion at which an aggregate filter override has been applied appears as follows:
