Skip to main content
Skip table of contents

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 below.

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. Selecting it displays the selection rule’s waterfall counts in the Waterfall Counts Window, which is described in the Rule Designer documentation.

  • Open Data Viewer: Selecting 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. Selecting 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: Selecting 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 when the current SQL database definition is AI enabled, 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.

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: selecting 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, regardless of 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 “No trace log entries were found for this selection rule”. 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: a tooltip saying “This file has never been published. This file can be published to the Realtime API manually”.

      • Published: a tooltip saying “This file is currently published. This file can be published to the Realtime API manually”. The tooltip also shows the latest published details:

        • Published version

        • Publish method

        • Last published

        • Published by

        • Instance ID

      • Unpublished: a tooltip saying “This file is currently unpublished. This file can be published to the Realtime API manually”. The tooltip also shows the latest published details:

        • Published version

        • Publish method

        • Last published

        • Published by

        • Instance ID

    • Refresh: you must select this button to manually refresh the file's latest Published Status (published status changes are not displayed automatically).

    • Publish to Realtime API: Selecting 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. Selecting 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 saying “There is no comment history available for this file”. 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 displays 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 selecting the green play 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.

Canvas

A basic selection rule’s canvas initially displays a message:

The following options are available when you right select 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).

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 selecting the Add New Criterion button (documented below). 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 stating “The element does not belong to this group” advises you 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: selecting this button puts the criterion into edit mode.

  • Actions: selecting 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, you’re advised “No values. Click to select”. 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 string criterion type, if predefined values exist for the decision criterion type, selecting 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.

      • “Equals” or “Does not equal”: 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.

      • “After”, “Before”, or “Within”

      • “Is”

    • If a Boolean decision criterion type, the following values are available. Note that if an Exists or Does not exist operator has been selected, Value is not shown.

      • Is True

      • Is False (the default)

  • Done: Selecting 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.

Add New Criterion button

This button allows you to add a criterion to a basic selection rule. Selecting 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 select 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 selected, 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.

Selecting 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 selected, 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.

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.

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: selecting 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-selecting 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

Add New Criteria List

This button is displayed below the basic selection rule’s canvas. Selecting 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.

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: selecting 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: selecting 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: selecting 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:

The Aggregate filter override allows you to 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:

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close