Actions REST API - Documentation topics on: actions,rules,ruleset actions,.

Actions REST API

Admin dotCMS users, or any other user with Rule Permissions, can hit several endpoints of the Rules REST API. Rules, Rule Conditions, and Rule Actions can be added via the REST API. The following documentation shows how to add Rule Actions via the REST API.

REST API Actions

Retrieve a List of Available Actions
Saving a Rule
Save an Action with All Parameters
Save an Action with Required Parameters
Retrieve an Action
Update an Action
Delete an Action
Error Handling

Add Tags to Visitor Action
Redirect Requests Action

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:8080/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}}}}

Saving a Rule (pre-requisite before Ruleset Actions can be assigned)

Saves a rule with an empty ruleset - which needs to be done before actions can be set on the rule

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8080/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":{  

    }
}'

Sample Return:

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

Saving an Action with All Parameters being set

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. Keys/Values 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:8080/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:8080/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" }

Retrieve an 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:8080/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:8080/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:8080/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:8080/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:8080/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:8080/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:8080/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:8080/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:8080/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:8080/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:8080/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:8080/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"}