Ranking formulas create-ranking-formulas

About ranking formulas about-ranking-formulas

Ranking formulas allow you to define rules that will determine which offer should be presented first for a given placement, rather than taking into account the offers’ priority scores.

Ranking formulas are expressed in PQL syntax and can leverage profile attributes, context data and offer attributes. For more on how to use the PQL syntax, refer to the dedicated documentation.

Once a ranking formula has been created, you can assign it to a placement in a decision. For more on this, see Configure offers selection in decisions.

Create a ranking formula create-ranking-formula

To create a ranking formula, follow the steps below:

  1. Access the Components menu, then select the Ranking tab. The Formulas tab is selected by default. The list of previously created formulas is displayed.

  2. Click Create ranking to create a new ranking formula.

  3. Specify the formula name, description, and formula.

    In this example, we want to boost the priority of all offers with the “hot” attribute if the actual weather is hot. To do this, the contextData.weather=hot was passed in the decisioning call.

    note important
    When creating a ranking formula, looking back into a previous period of time is not supported. For instance, if you specify an experience event that occurred within the last month as a component of the formula. Any attempt to include a lookback period during formula creation will trigger an error when saving it.
  4. Click Save. Your ranking formula is created, you can select it from the list to get details and edit or delete it.

    It is now ready to be used in a decision to rank eligible offers for a placement (see Configure offers selection in decisions).

Ranking formula examples ranking-formula-examples

You can create many different ranking formulas according to your needs. Below are some examples.

Boost offers with certain offer attribute based on profile attribute

If the profile lives in the city corresponding to the offer, then double the priority for all offers in that city.

Ranking formula:

if( offer.characteristics.get("city") = homeAddress.city, offer.rank.priority * 2, offer.rank.priority)

Boost offers where the end date is less than 24 hours from now

Ranking formula:

if( offer.selectionConstraint.endDate occurs <= 24 hours after now, offer.rank.priority * 3, offer.rank.priority)

Boost offers with certain offer attribute based on context data

Boost certain offers based on the context data being passed in the decisioning call. For example, if the contextData.weather=hot is passed in the decisioning call, the priority of all offers with attribute=hot must be boosted.

Ranking formula:

if (@{_xdm.context.additionalParameters;version=1}.weather.isNotNull()
and offer.characteristics.get("weather")=@{_xdm.context.additionalParameters;version=1}.weather, offer.rank.priority + 5, offer.rank.priority)

Note that when using the decisioning API, the context data is added to the profile element in the request body, such as in the example below.

Snippet from request body:

"xdm:profiles": [
    "xdm:identityMap": {
        "crmid": [
            "xdm:id": "CRMID1"
    "xdm:contextData": [

Boost offers based on the customers propensity to purchase the product being offered

You can boost the score for an offer based on a customer propensity score.

In this example, the instance tenant is _salesvelocity and the profile schema contains a range of scores stored in an array:

Given this, for a profile such as:

{"_salesvelocity": {"individualScoring": [
                    {"core": {
                            "propensityScore": 96.9
                    {"core": {
                            "propensityScore": 45.3
                    {"core": {
                            "propensityScore": 78.1

The offers would contain an attribute for propensityType which matches the category from the scores:

Your ranking formula can then set the priority of each offer to equal the customers propensityScore for that propensityType. If no score is found, use the static priority set on the offer:

let score = (select _Individual_Scoring1 from _salesvelocity.individualScoring
             where _Individual_Scoring1.core.category.equals(offer.characteristics.get("propensityType"), false)).head().core.propensityScore
in if(score.isNotNull(), score, offer.rank.priority)