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
| End Point | HTTP Method | Description and Example | Login Required |
|---|---|---|---|
| List | GET | List all available Actionlets./api/v1/system/ruleengine/actionlets | Yes |
| self | GET | Retrieve information about an Action on a site./api/v1/sites/[SITE ID]/ruleengine/actions/[ACTION ID] | Yes |
| add | POST | Add an Action to a site./api/v1/sites/[SITE ID]/ruleengine/actions | Yes |
| update | PUT | Update an Action on a site./api/v1/sites/[SITE ID]/ruleengine/actions/[ACTION ID] | Yes |
| remove | DELETE | Delete an Action from a site./api/v1/sites/[SITE ID]/ruleengine/actions/[ACTION ID] | Yes |
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
The output provides the id of the new Rule created:
{ "id": "509fab57-32ab-46d0-9ca8-ff4d5698d5e6" }
Saving Parameters in an Action
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
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}/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
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
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"}
