Conditions REST API

Last Updated: Sep 25, 2024
documentation for the dotCMS Content Management System

Admin users and any other users with Rule permissions can add Rules, Rule Conditions, and Rule Actions via the REST API.

The following REST API commands/examples show how to add Conditions to existing Rules and Condition Groups. Please see the Rules REST API! documentation for more information on how to add Rules using the REST api.

In the curl examples below, admin passwords are assumed to be admin, as on the demo site and starters prior to version 22.06. For versions 22.06 or later, this is no longer the default; now, admin passwords default to a random string generated on first startup and displayed in the server logs. This starter password can also be pre-configured through the DOT_INITIAL_ADMIN_PASSWORD environment variable.

Conditions and Condition Groups

Conditions can only be added to a Condition Group that has already been added to the Rule. You can use the conditionGroups REST endpoint to add a Condition Group via REST API.

Example

The following curl command adds a new condition group to the specified Rule. Note: You must replace the {Rule-Id} portion of this command with the identifier of the Rule to add the Condition Group to.

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/rules/{Rule-Id}/conditionGroups -H "Content-Type: application/json" -H "Accept: application/json" -d '{
    "conditions": {},
    "operator": "AND",
    "priority": 2
}'

Example Output

The output provides the id of the new Condition group created:

{ "id": "b44a72c2-5b16-4fee-b71e-cfe964d5cde3" }

This new id should be used as the owningGroup parameter when adding new Conditions via REST API as shown in each of the examples below.

Condition Types

The following examples show how to add Conditions of each specific Condition Type. For more information on the Condition Types, please see the Condition Types documentation.

Example Output

When you create any Condition Type using the REST API, the output displays the id of the Condition created, as in the following example:

{ "id": "dd4eb360-852d-48b0-9e36-295756f5def8" }

List of Condition Types

The following table lists each of the Condition Types and provides links to information about the parameters (in the Condition Types documentation) and an example REST API call (in the Examples, below).

Note: For a descriptions of each condition type, please see the Condition Types documentation.

Condition TypeParametersExample (below)
BrowserLinkLink
Current URLLinkLink
DeviceTypeLinkLink
Logged InLinkLink
Number of VisitsLinkLink
PersonaLinkLink
Referring URLLinkLink
Request AttributeLinkLink
Session AttributeLinkLink
Visitor's CountryLinkLink
Visitor's Date-TimeLinkLink
Visitor's LocationLinkLink

Examples

The following examples demonstrate how to add each of the different condition types to a condition group using a curl command. In each example, you must replace {Condition Group ID} with the (string) id of the condition group (please see the Condition Groups and Conditions section, above for more information).

Browser

Parameters

ParameterAccepted Values
"conditionlet""UsersBrowserConditionlet"
"comparison""is", "isNot"
"browser"String (from values available in the Browser selection drop-down)

Example

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/conditions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{
  "owningGroup": {Condition Group ID},
  "conditionlet": "UsersBrowserConditionlet",
  "priority": 3,
  "operator": "AND",
  "values": {
    "comparison": {
      "key": "comparison",
      "value": "is",
      "priority": 0
    },
    "browser": {
      "key": "browser",
      "value": "Chrome",
      "priority": 1
    }`
  }
}'

Current URL

Parameters

ParameterAccepted Values
"conditionlet""UsersCurrentUrlConditionlet"
"comparison""is", "isNot", "startsWith", "endsWith", "contains", "regex"
"current-url"String (URL value)

Example

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/conditions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{
  "owningGroup": "0a2dbd0e-d8ba-446b-a573-976a88d51b95",
  "conditionlet": "VisitorsCurrentUrlConditionlet",
  "priority": 3,
  "operator": "AND",
  "values": {
    "comparison": {
      "key": "comparison",
      "value": "is",
      "priority": 2
    },
    "current-url": {
      "key": "current-url",
      "value": "/products/",
      "priority": 1
    }
  }
}'

Device Type

Parameters

ParameterAccepted Values
"conditionlet""UsersPlatformConditionlet"
"comparison""is", "isNot"
"platform"Platform (String, from among the following choices:
"COMPUTER", "MOBILE", "TABLET", "WEARABLE", "DMR, GAME_CONSOLE")

Example

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/conditions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{
  "owningGroup": "0a2dbd0e-d8ba-446b-a573-976a88d51b95",
  "conditionlet": "UsersPlatformConditionlet",
  "priority": 3,
  "operator": "AND",
  "values": {
    "comparison": {
      "key": "comparison",
      "value": "is",
      "priority": 2
    },
    "platform": {
      "key": "platform",
      "value": "GAME_CONSOLE",
      "priority": 1
    }
  }
}'

LoggedIn

Parameters

ParameterAccepted Values
"conditionlet""UsersLogInConditionlet"
"comparison""is", "isNot"

Example

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/conditions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{
  "owningGroup": "0a2dbd0e-d8ba-446b-a573-976a88d51b95",
  "conditionlet": "UsersLogInConditionlet",
  "priority": 3,
  "operator": "AND",
  "values": {
    "comparison": {
      "key": "comparison",
      "value": "isNot",
      "priority": 2
    }
  }
}'

Number of Visits

Parameters

ParameterAccepted Values
"conditionlet""UsersSiteVisitsConditionlet"
"comparison""equal", "lessThan", "greaterThan", "lessThanOrEqual", "greaterThanOrEqual"
"site-visits"Number of site visits (Integer value entered as a string)

Example

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/conditions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{
    "owningGroup":"0a2dbd0e-d8ba-446b-a573-976a88d51b95",
    "conditionlet":"UsersSiteVisitsConditionlet",
    "values": {
        "comparison": {
            "key":"comparison",
            "value":"equal",
            "priority":0
        },
        "site-visits": {
            "key":"site-visits",
            "value":"3",
            "priority":0
            }
        },
    "operator":"AND",
    "priority":1
}'

Persona

Parameters

ParameterAccepted Values
"conditionlet""PersonaConditionlet"
"comparison""is", "isNot"
"personaIdKey"String (ID or Key Tag of a Persona content item)

Example

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/conditions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{
    "owningGroup":"0df750da-80a5-4f11-ac4b-cae7331f3d8c",
    "conditionlet":"PersonaConditionlet",
    "priority": 0,
    "operator": "AND",
    "values": {
        "comparison":{
            "key":"comparison",
            "value":"is",
            "priority":1
        },
        "personaIdKey":{
            "key":"personaIdKey",
            "value":"34c720cd-4b46-4a67-9e4b-2117071d01f1",
            "priority":0
        }
    }
}'

Referring URL

Parameters

ParameterAccepted Values
"conditionlet""UsersReferringURLConditionlet"
"comparison""is", "isNot", "startsWith", "endsWith", "contains", "regex"
"referring-url"String (URL value)

Example

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/conditions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{
  "owningGroup": "0a2dbd0e-d8ba-446b-a573-976a88d51b95",
  "conditionlet": "ReferringURLConditionlet",
  "priority": 1,
  "operator": "AND",
  "values": {
    "comparison": {
      "key": "comparison",
      "value": "is",
      "priority": 0
    },
    "referring-url": {
      "key": "referring-url",
      "value": "www.google.com",
      "priority": 1
    }
  }
}'

Request Attribute

Parameters

ParameterAccepted Values
"conditionlet""RequestAttributeConditionlet"
"comparison""is", "isNot"
"request-attribute"String (from values available in the selection drop-down)
"request-attribute-value"String (any value appropriate for the specified request attribute)

Example

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/conditions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{
    "owningGroup": "0a2dbd0e-d8ba-446b-a573-976a88d51b95",
      "conditionlet": "RequestAttributeConditionlet",
    "priority": 3,
    "operator": "AND",
    "values": {
        "request-attribute":{
            "key":"request-attribute",
            "value":"testAttribute",
            "priority":1
        },
        "comparison":{
            "key":"comparison",
            "value":"is",
            "priority":2
        },
        "request-attribute-value":{
            "key":"request-attribute-value",
            "value”:”testValue”,
            ”priority":1}
        }
    }
}'

Session Attribute

Parameters

ParameterAccepted Values
"conditionlet""SessionAttributeConditionlet"
"sessionKey"String (Any key stored in the session)
"comparison""is", "isNot", "Exists", "startsWith", "endsWith", "contains", "regex"
"seesionValue"String (Any appropriate value for the specified session key)

Example

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/conditions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{
    "owningGroup": "0a2dbd0e-d8ba-446b-a573-976a88d51b95",
    "conditionlet": "SessionAttributeConditionlet",
    "priority": 3,
    "operator": "AND",
    "values": {
        "sessionKey":{
            "key":"sessionKey",
            "value":"company",
            "priority":0
        },
        "comparison":{
            "key":"comparison",
            "value":"is",
            "priority":0
        },
        "sessionValue":{
            "key":"sessionValue",
            "value":"google",
            "priority":1
        }
    }
}'

Visitor's Country

Parameters

ParameterAccepted Values
"conditionlet""UsersCountryConditionlet"
"comparison""is", "isNot"
"country"Country code (String, 2-letter ISO country code)

Example

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/conditions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{
  "owningGroup": "0a2dbd0e-d8ba-446b-a573-976a88d51b95",
  "conditionlet": "UsersCountryConditionlet",
  "priority": 3,
  "operator": "AND",
  "values": {
    "comparison": {
      "key": "comparison",
      "value": "is",
      "priority": 2
    },
    "country": {
      "key": "country",
      "value": "ES",
      "priority": 1
    }
  }
}'

Visitor's Date-Time

Parameters

ParameterAccepted Values
"conditionlet""DateTimeConditionlet"
"comparison""between", "greaterThan", "lessThan"
"datetime-1"Date and Time (as a String, in the format "2016-01-01T00:00")
Start time for "between" comparison; Comparison time for "greaterThan" and "lessThan" comparisons
"datetime-2"Date and Time (as a String, in the format "2016-01-01T00:00")
End time for "between" comparison

Example

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/conditions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{
  "owningGroup": "0a2dbd0e-d8ba-446b-a573-976a88d51b95",
  "conditionlet": "DateTimeConditionlet",
  "priority": 1,
  "operator": "AND",
  "values": {
    "comparison": {
      "key": "comparison",
      "value": "between",
      "priority": 1
    },
    "datetime-1": {
      "key": "datetime-1",
      "value": "2017-05-01T00:00",  
      "priority": 0
    },
    "datetime-2": {
      "key": "datetime-2",
      "value": "2017-06-01T00:00",  
      "priority": 1
    }
  }
}'

Visitor's Location

Parameters

ParameterAccepted Values
"conditionlet""VisitorsGeolocationConditionlet"
"comparison""withinDistance", "notWithinDistance"
"radius"Real, entered as a String
"preferredDisplayUnits""mi", "km"
"latitude"Real, entered as a String
"longitude"Real, entered as a String

Example

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/conditions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{
    "owningGroup":"612460ad-b566-4790-9b2e-1c28c1950dd0",
    "conditionlet":"VisitorsGeolocationConditionlet",
    "operator":"AND",
    "priority":1
    "values":{
        "comparison":{
            "key":"comparison",
            "value":"withinDistance",
            "priority":2
        },
        "radius":{
                "key":"radius",
                "value":"90029.3723824678",
                "priority":1
        },
        "preferredDisplayUnits":{
                "key":"preferredDisplayUnits",
                "value":"mi",
                "priority":0
        },
        "latitude":{
            "key":"latitude",
            "value":"10.4883717",
            "priority":5
        },
        "longitude":{
            "key":"longitude",
            "value":"-66.8799873",
            "priority":6
        }
    },
}' 

On this page

×

We Dig Feedback

Selected excerpt:

×