Set Session Attribute Action - Documentation topics on: actionlet,rules,session attribute,.

This documentation is a static copy for this version. For current documentation, see: http://dotcms.com/docs/latest

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.

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

REST API Actions

Managing Actionlets Via REST API

End PointHTTP
Method
Description and ExampleLogin
Required
ListGETList all available Actionlets.
/api/v1/system/ruleengine/actionlets
Yes
selfGETRetrieve information about an Action on a site.
/api/v1/sites/[SITE ID]/ruleengine/actions/[ACTION ID]
Yes
addPOSTAdd an Action to a site.
/api/v1/sites/[SITE ID]/ruleengine/actions
Yes
updatePUTUpdate an Action on a site.
/api/v1/sites/[SITE ID]/ruleengine/actions/[ACTION ID]
Yes
removeDELETEDelete 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: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}}}}

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: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":{  

    }
}'

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: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" }

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: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"}