Using Developer Mode
This section contains guidance on how to use Developer Mode to write queries within your actions using Infinity Query Language (IQL).
In this topic:
What is Developer Mode?
Developer Mode allows you to express your action rules as code by giving you access to the underlying Infinity Query Language (IQL). IQL uses SQL-like clauses such as SELECT and WHERE to allow you to build queries in Developer Mode to express your actions quickly.
Tip: See Developer Mode - Example Queries for examples of queries you can use for your Actions.
Accessing Developer Mode
When creating or editing your action, you can view the underlying query for your activation rules by clicking Switch the Developer Mode to write Rule queries.
Important: If you save your rule whilst in Developer Mode, it cannot be reverted back into a standard rule. However, as long as you click cancel without saving - your original rule will be returned to be a visual rule.
Viewing the underlying query for your rule
Below is an example of an action that has been converted into its underlying query through Developer Mode. The action will:
-
Trigger at the end of a user's session who has added an item to their cart and has not purchased within the session.
-
Additionally, it will only trigger the action if an item was added to their cart with the Product SKU of SKU-1234-R.
Sample Action - Created in standard User Interface
Sample Action - Developer Mode Query exposed through Developer Mode
Tip: Before you Continue to the next step, you must Validate your query to ensure there are no syntax errors.
Writing Queries in Developer Mode
Tip: See Developer Mode - IQL Reference and Developer Mode - Example Queries for full syntax reference and examples.
Once you are in the Developer Mode user interface, you can write your own queries by leveraging the following key Clauses:
-
ON TRIGGER - When would you like your session to qualify for an action?
-
SELECT - Which parameters would you like to pass to your Destination from your Action?
-
WHERE - What further conditions or restrictions would you like to apply to when your action should trigger?
ON TRIGGER()
ON TRIGGER() defines whether a session should qualify for an Action. For example, the following trigger will execute the action when the session is closed if a user has performed an Add product to cart event within the session (see Behaviors for Behavior definitions):
Example Syntax
Sample Developer Mode ON TRIGGER
Note: What's the difference between WHERE and ON TRIGGER()?
Broadly speaking, you should use ON TRIGGER() to decide what behaviors should qualify a session for the action to trigger and then WHERE to further refine whether the action should trigger. Please see the Frequently Asked Questions for the difference between WHERE and ON TRIGGER()and advice on when you should use each. Additionally, you can view some Example Queries.
Tip: Working with open sessions
Please note that once the ON TRIGGER() conditions are met - the session will be in a qualified state. From that point on, all further events within the session will trigger your action. To ensure that actions are only triggered for the specific events you want - you should use a WHERE clause to define when the action should trigger.
This is particularly important if you are triggering actions for an open session (using NOT behavior.[Close session]). For closed sessions (behavior.[Close session]), this doesn't really matter as this is the final event within the session.
Please see Using WHERE to work with Open Sessions for further details.
ON TRIGGER() maps to the defined Scenario within the behaviors section of the standard Rules in the user interface. For example, here is how a Scenario is translated to an ON TRIGGER clause in IQL:
Example Scenario
Resulting ON TRIGGER in IQL
Sample Developer Mode ON TRIGGER
Tip: How do I refer to parameters and behavior attributes in my IQL syntax?
Learn how to refer to parameters and behavior attributes in your IQL syntax.
SELECT
SELECT allows you to surface additional parameters which you may wish to map to your destination:
Example Syntax
Simple SELECT statement
Tip: How do I refer to parameters and behavior attributes in my IQL syntax?
Learn how to refer to parameters and behavior attributes in your IQL syntax.
Tip: You can use Aliases to give your selections user-friendly names when mapping selections within the destinations screen.
Examples
Simple
Below is a relatively simple SELECT statement:
Simple SELECT statement
Tip: Aliases
You may wish to optionally use Aliases to give your selections a friendly name by using the AS syntax (e.g. LATEST(parameter.[City]) AS 'My City').
It selects:
-
The Product SKU of any products added to the cart (leveraging the Add product to cart behavior).
-
The Content Group of any products added to the user's cart (leveraging the Add product to cart behavior).
-
The latest City parameter that was captured within my session.
Typically, these types of selections are not necessary as they are usually available to map to your destination by default.
Advanced
If you have selections which are not typically available in the destination mapping screen by default then you can define these as selections for you to later map to your destination. For example, the following query will select the latest Product SKU parameter seen when the user visited the view cart page (my.website.com/cart):
Complex SELECT statement
Tip: Selecting items with multiple values
If your query selects something with multiple items (for example, all of the SKUs added to your cart within a session) then they will sent as a delimited list to your desired destination. The destination will decide on which delimiter is used (for example, for Oracle Responsys will use a comma delimiter).
See How are selections with multiple values sent to your destination? for further information.
WHERE
SELECT allows you to further refine when your action should be executed. For example, if you wanted to your action to be executed on Product View of a Closed Session but only if the Product SKU of the viewed product was SKU123 then you can use the WHERE clause to add this condition:
Example Syntax
Sample Developer Mode WHERE
Tip: How do I refer to parameters and behavior attributes in my IQL syntax?
Learn how to refer to parameters and behavior attributes in your IQL syntax.
WHERE maps to the Filter section within your Rule in the standard user interface. For example:
Example Filter
Resulting WHERE in IQL
Example Filter as WHERE statement
Using WHERE to work with Open Sessions
When working with open sessions (that is, NOT behavior.[Close session]) it is important that you use the appropriate WHERE clause to ensure only the events you wish to emit an action will do so. For example, if you wished to trigger an action each time someone adds an item to their cart then you could use the following query:
Example Syntax - working with open sessions
Sample Developer Mode WHERE
The above WHERE clause will ensure that once the ON TRIGGER() clause has been met upon the first add product to cart event, further events (for example, viewing another page) do not trigger another action (the WHERE clause ensures that the action will only be emitted if the event is an add to cart event). Without this WHERE clause, every subsequent event within the session would emit an action.
Mapping Selections to your Destination
When you reach the Destinations screen within your action, you can select not only the standard parameters/behaviors available in the user interface but also any selections you may have made:
Sample Selections - IQL Query
Destinations - Available Parameters
Tip: You can use Aliases to give your selections user-friendly names in the destinations screen above.
Frequently Asked Questions
What's the difference between ON TRIGGER() and WHERE?
ON TRIGGER() and WHERE are potentially interchangeable within Developer Mode but there are best practices to follow to avoid potential issues. In particular, with open sessions you should be aware that once the ON TRIGGER() criteria has been met - all further events in the session will trigger your action unless you have a WHERE condition to restrict which events should trigger an action (see Using WHERE to work with Open Sessions for more information).
As a result, in general you will see that the Actions user interface doesn't refer to values for behaviors and doesn't refer to parameters directly - it will use WHERE (or filters) to add more granularity to queries. For example
Example Scenario
Resulting ON TRIGGER in IQL
Sample Developer Mode ON TRIGGER
If you wished to further refine the above action to only trigger if the session included a pause video behavior where the video name equalled 'this video' then you would do this using a WHERE clause (or filter in the user interface) as follows:
Using Filters (or WHERE)
Underlying IQL
Working with ON TRIGGER and WHERE
However, it is technically possible to write the following IQL query to achieve the same (without using WHERE at all):
Working with ON TRIGGER and WHERE
Do I need to use Behaviors in my IQL Syntax?
You don't have to use behaviors - you can use the underlying parameter syntax to refer to the desired behavior. For example, to refer to customers adding items to their cart you can use either behavior.[Add Product to Cart] or data.wt.tx_e = 'a':
Working with ON TRIGGER and WHERE
Do I need to use Parameter.[Parameter] syntax to refer to parameters in my IQL Syntax?
You can use either the underlying parameter syntax or the friendly name of your parameter in your IQL syntax. For example, you can use either parameter.[Page Title] or data.wt.ti to refer to the Page Title parameter in your query. In order to refer to a parameter using Parameter.[PARAMETER DISPLAY NAME] syntax you will need to ensure it has been given a display name.
How are selections with multiple values sent to your destination?
Some selections can have return multiple values. For example, if you select behavior.[Add product to cart].[Product SKU], it will return all of the Product SKU values seen within the session for the add to cart events:
Selections with multiple values
If the user were to have added multiple product SKUs within the session, the selection will return all of them in an array:
["SKU1", "SKU3", "SKU5"]
If you mapped this selection to somewhere within your desired the destination then it will be delimited according to the logic predetermined within that destination (for example, for Oracle Responsys destinations this will be comma delimited as SKU1,SKU3,SKU5).
Note: Working with delimiters:
You cannot choose the delimiters for parameters and behaviors with multiple values. However, if you choose to construct a delimited value yourself you can control the delimiter yourself. See toString() for further information.
Legacy Stream Syntax (including HAVING)
Some of the syntax previously available in the legacy Streams syntax is now unavailable and unnecessary due to the simplicity and power of using IQL for queries. For example, HAVING is no longer necessary as the same results can be achieved using a combination of ON TRIGGER(), WHERE and SELECT clauses.
Developer Mode - IQL Reference