Set Session Attribute Action

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

REST API Actions#

---

Managing Actionlets Via REST API#

Retrieve a list of available Actionlets via REST API#

GET Method:

/api/v1/system/ruleengine/actionlets

Curl Command:

curl -v -u admin@dotcms.com:admin -X GET http://localhost:8082/api/v1/system/ruleengine/actionlets -H "Content-Type:application/json"

Sample Return:

{"PersonaActionlet":{"id":"PersonaActionlet","i18nKey":"api.system.ruleengine.actionlet.SetPersona","parameterDefinitions":{"personaIdKey":{"key":"personaIdKey","i18nBaseKey":null,"defaultValue":"","inputType":{"id":"restDropdown","dataType":{"id":"text","errorMessageKey":"api.system.type.text","minLength":0,"maxLength":255,"defaultValue":""},"placeholder":"","optionUrl":"/api/v1/personas","jsonValueField":"key","jsonLabelField":"name","allowAdditions":false,"minSelections":1,"maxSelections":1},"priority":1}}},"SetRequestAttributeActionlet":{"id":"SetRequestAttributeActionlet","i18nKey":"api.system.ruleengine.actionlet.SetRequestAttribute","parameterDefinitions":{"requestKey":{"key":"requestKey","i18nBaseKey":null,"defaultValue":"","inputType":{"id":"text","dataType":{"id":"text","errorMessageKey":"api.system.type.text","minLength":0,"maxLength":255,"defaultValue":""},"placeholder":""},"priority":1},"requestValue":{"key":"requestValue","i18nBaseKey":null,"defaultValue":"","inputType":{"id":"text","dataType":{"id":"text","errorMessageKey":"api.system.type.text","minLength":0,"maxLength":255,"defaultValue":""},"placeholder":""},"priority":2}}},"CountRulesActionlet":{"id":"CountRulesActionlet","i18nKey":"Rule's Counter","parameterDefinitions":{}},"SetResponseHeaderActionlet":{"id":"SetResponseHeaderActionlet","i18nKey":"api.system.ruleengine.actionlet.SetResponseHeader","parameterDefinitions":{"headerKey":{"key":"headerKey","i18nBaseKey":null,"defaultValue":"","inputType":{"id":"text","dataType":{"id":"text","errorMessageKey":"api.system.type.text","minLength":1,"maxLength":255,"defaultValue":""},"placeholder":""},"priority":1},"headerValue":{"key":"headerValue","i18nBaseKey":null,"defaultValue":"","inputType":{"id":"text","dataType":{"id":"text","errorMessageKey":"api.system.type.text","minLength":0,"maxLength":255,"defaultValue":""},"placeholder":""},"priority":2}}},"SetSessionAttributeActionlet":{"id":"SetSessionAttributeActionlet","i18nKey":"api.system.ruleengine.actionlet.SetSessionAttribute","parameterDefinitions":{"sessionKey":{"key":"sessionKey","i18nBaseKey":null,"defaultValue":"","inputType":{"id":"text","dataType":{"id":"text","errorMessageKey":"api.system.type.text","minLength":0,"maxLength":255,"defaultValue":""},"placeholder":""},"priority":1},"sessionValue":{"key":"sessionValue","i18nBaseKey":null,"defaultValue":"","inputType":{"id":"text","dataType":{"id":"text","errorMessageKey":"api.system.type.text","minLength":0,"maxLength":255,"defaultValue":""},"placeholder":""},"priority":2}}}}

Save a Rule with an Empty Action List#

Before you can add any Actions to a Rule, you must first create a Rule. The following example creates a new Rule with no Condition Groups or Actions.

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/{siteId}/ruleengine/rules -H "Content-Type: application/json" -H "Accept: application/json" -d '{  
    "name":"My First Rule",
    "enabled":true,
    "priority":10,
    "fireOn":"EVERY_PAGE",
    "shortCircuit":false,
    "conditionGroups":{  

    },
    "actions":{  

    }
}'

###Example Output {#ExampleOutput}

The output provides the id of the new Rule created:

{ "id": "509fab57-32ab-46d0-9ca8-ff4d5698d5e6" }

###Saving Parameters in an Action {#SavingParameters}

URL Structure

POST /api/v1/sites/{siteId}/ruleengine/actions

Response

200 OK
{ "id": ACTION_ID }  
400 Bad Request

Keys and values are exposed in the Rules UI when creating specific actions, and can be retrieved from the session. These values can be set via REST by passing the actionlet parameters as in the example below:

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/actions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{  
    "name":"New Session Actionlet",
    "owningRule":"d4a8e5de-e130-462a-9f94-8cfe9f457222",
    "priority":10,
    "actionlet":"SetSessionAttributeActionlet",
    "parameters":{"sessionKey":{"key":"sessionKey","value":"company"}, "sessionValue":{"key":"sessionValue", "value":"dotCMS"}}
        }
}'

Sample Return:

{ "id": "83970f44-4d02-454c-9845-ca17a79da717" }

Saving an Action with ONLY required parameters#

How to save an action to a rule WITHOUT setting the actionlet parameters (if Parameters are NOT required)

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/actions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{  
    "name":"Test Action REST",
    "owningRule":"d4a8e5de-e130-462a-9f94-8cfe9f457222",
    "actionlet":"CountRulesActionlet"
        }
}'

Sample Return:

{ "id": "83970f44-4d02-454c-9845-ca17a79da717" }

###Get a Single Action {#GetAction}

URL Structure

GET /api/v1/sites/{siteId}/ruleengine/actions/{actionId}

Response

200 OK
{"name":,"owningRule":,"priority":,"actionlet":,"parameters":}  
404 Not found

Sample CURL

curl -v -u admin@dotcms.com:admin -X GET http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/actions/83970f44-4d02-454c-9845-ca17a79da717

Sample Return:

{"name":"New Session Actionlet Version 2","owningRule":"d4a8e5de-e130-462a-9f94-8cfe9f457222","priority":10,"actionlet":"SetSessionAttributeActionlet","parameters":{"sessionKey":{"id":"bff0360d-4e52-4700-b192-103852eedf21","ownerId":"65092d50-0927-41bb-a5fa-eb5e27b98698","key":"sessionKey","value":"corporation","priority":0},"sessionValue":{"id":"8f948797-4acc-4cad-bf77-1ef16e9d7334","ownerId":"65092d50-0927-41bb-a5fa-eb5e27b98698","key":"sessionValue","value":"dotCMS, Inc.","priority":0}}}

Update an Action#

URL Structure

PUT /api/v1/sites/{siteId}/</span>ruleengine/actions/{actionId}

Response

200 OK  
{"name":,"owningRule":,"priority":,"actionlet":,"parameters":}  
400 Bad Request  
404 Not found

Sample CURL

curl -v -u admin@dotcms.com:admin -X PUT http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/actions/65092d50-0927-41bb-a5fa-eb5e27b98698 -H "Content-Type: application/json" -H "Accept: application/json" -d '{  
    "name":"New Session Actionlet Version 2",
    "owningRule":"d4a8e5de-e130-462a-9f94-8cfe9f457222",
    "priority":10,
    "actionlet":"SetSessionAttributeActionlet",
    "parameters":{"sessionKey":{"key":"sessionKey","value":"corporation"}, "sessionValue":{"key":"sessionValue", "value":"dotCMS, Inc."}}
        }
}'

Sample Return:

{"name":"New Session Actionlet Version 2","owningRule":"d4a8e5de-e130-462a-9f94-8cfe9f457222","priority":10,"actionlet":"SetSessionAttributeActionlet","parameters":{"sessionKey":{"id":"bff0360d-4e52-4700-b192-103852eedf21","ownerId":null,"key":"sessionKey","value":"corporation","priority":0},"sessionValue":{"id":"8f948797-4acc-4cad-bf77-1ef16e9d7334","ownerId":null,"key":"sessionValue","value":"dotCMS, Inc.","priority":0}}}

Delete an Action#

URL Structure

DELETE /api/v1/sites/{siteId}/ruleengine/actions/{actionId}

Response

204 No Content  
404 Not found

Sample CURL

curl -v -u admin@dotcms.com:admin -X DELETE -H "Content-Type: application/json" -H "Accept: application/json" http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/actions/83970f44-4d02-454c-9845-ca17a79da717

Sample Return:

204 No Content

##REST API Actions

###Add Tags to a Visitor Action {#addTagsToVisitor}

This Action adds Tags to the Visitor object.

Actionlet ID: VisitorTagsActionlet

Available value choices: Comma separated list of Tags

Usage Via REST API#

To add an Add Tags to Visitor Action:

"owningRule": "0862904c-105d-4d8d-8991-e7ec34b132ae" - Rule ID

Example:

curl -v -u admin@dotcms.com:admin -X POST -H "Content-Type: application/json" 'http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/actions' -d '{
  "owningRule": "0862904c-105d-4d8d-8991-e7ec34b132ae",
  "priority": 5,
  "actionlet": "VisitorTagsActionlet",
  "parameters": {
    "tags": {
      "key": "tags",
      "value": "dotcms 3.5,united states"
    }
  }
}'

Example Output - ID of the Add Tags to Visitor Action added:

{ "id": "fe54043a-0af1-4bd0-bd6d-438e8ecb70c0" }

###Redirect Requests To Action {#redirectRequests}

This Action redirects requests to a specified site/URL.

Actionlet ID: SendRedirectActionlet

Value format: TEXT: a valid URL

Usage Via REST API#

To add an Redirect Requests To Action:

"owningRule": "0862904c-105d-4d8d-8991-e7ec34b132ae" - Rule ID

Example:

curl -v -u admin@dotcms.com:admin -X POST -H "Content-Type: application/json" 'http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/actions' -d '{
  "owningRule": "0862904c-105d-4d8d-8991-e7ec34b132ae",
  "priority": 1,
  "actionlet": "SendRedirectActionlet",
  "parameters": {
    "URL": {
      "key": "URL",
      "value":"/about-us/",
      "priority":1
    }
  }
}'

Example Output - ID of the Redirect Requests To Action added:

{ "id": "fe54043a-0af1-4bd0-bd6d-438e8ecb70c0" }

Error Handling Examples: All of the following Return a 400 error#

Return non-existent Action - returns 400 error#

curl -v -u admin@dotcms.com:admin -X GET http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/actions/223f3123-6315-40cc-b2e2-a184b8de28

Sample Return (400):

{"error":"dotcms.api.error.not_found: Rule Action not found: '223f3123-6315-40cc-b2e2-a184b8de28'"}

Save Action with a bad parameter 'name' empty - returns 400 error#

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/actions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{  
    "name":"",
    "owningRule":"d3085294-058e-431d-85d3-e349caedd321",
    "actionlet":"CountRequestsActionlet"
}'

Sample Return (400):

{"error":"dotcms.api.error.bad_request: One or more failures while validating RestRuleAction: \n\t 'name' may not be empty"}

Save Action with a bad parameter 'owningRule' non-existent - returns 400 error#

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/actions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{  
    "name":"Test Action REST",
    "owningRule":"6",
    "actionlet":"CountRequestsActionlet"
}'

Sample Return (400):

{"error":"dotcms.api.error.bad_request: One or more failures while validating RestRuleAction: \n\t 'owningRule' length must be between 36 and 36"}

Save Action with bad parameter 'actionlet' non-existent - returns 400 error#

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/actions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{  
    "name":"Test Action REST something",
    "owningRule":"78c95046-c4e3-43f3-9988-c83fad236197",
    "actionlet":"something"
}'

Sample Return (400):

{"error":"dotcms.api.error.bad_request: Actionlet with id 'something' not found: "}

Save Action with missing parameter 'name' - returns 400 error#

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/actions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{  
    "owningRule":"d3085294-058e-431d-85d3-e349caedd321",
    "actionlet":"something"
}'

Sample Return (400):

{"error":"dotcms.api.error.bad_request: One or more failures while validating RestRuleAction: \n\t 'name' may not be empty"}

Save Action with missing parameter 'owningRule' - returns 400 error#

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/actions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{  
    "name":"Test Action REST",
    "actionlet":"CountRequestsActionlet"
}'

Sample Return (400):

{"error":"dotcms.api.error.bad_request: One or more failures while validating RestRuleAction: \n\t 'owningRule' may not be null"}

Save Action with missing parameter 'actionlet' - returns 400 error#

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/actions/ -H "Content-Type: application/json" -H "Accept: application/json" -d '{  
    "name":"Test Action REST",
    "owningRule":"d3085294-058e-431d-85d3-e349caedd321"
}'

Sample Return (400):

{"error":"dotcms.api.error.bad_request: One or more failures while validating RestRuleAction: \n\t 'actionlet' may not be empty"}