Managing Rules via REST - Documentation topics on: rest,rules,.

Managing Rules via REST

A dotCMS Admin user, or any other user with Rule permissions, you can access several endpoints of the Rules REST API. Different methods for managing Rules via the REST API are shown below.

Create a Rule

The database table used to create store Rules is called “dot_Rule”. The Rule name must be unique for each site/host.

Note: Condition Groups and Actions must reference a Rule, so none of these can be created until after the Rule is created.

URL Structure

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

Response

{
    "id":"<generated_id>"
}

Status

200 : OK
400 : Bad request (error during Rule creation, duplicates or bad parameters)

Parameters

NameTypeRequiredDefaultValidationDescription
nametextYesNoneLength: min 1 max 100. Spaces allowed.The name of the Rule (not unique).
enabledbooleanNofalsetrue/false.Determines whether or not the Rule is active.
prioritynumericNo0Minimum value: 0.Used for sorting in the backend UI.
fireOntextNoEveryPagePlease see below.Determines when the Rule is evaluated.
shortCircuitbooleanNofalsetrue/falseEnables Condition short circuit behaviour.
ConditionGroupsgroupNoemptyMust contain condition groups or be empty.Rule Condition Groups.
actionsgroupNoemptyMust contain Actions or be empty.Rule Actions.

FireOn Values

The possible fireOn values are:

  • EveryPage
  • OncePerVisit
  • OncePerVisitor
  • EveryRequest

Example JSON structure

{
   "name":"My First Rule",
   "enabled":true,
   "priority":10,
   "fireOn":"EveryPage",
   "shortCircuit":false,
   "ConditionGroups":{},
   "actions":{}
}

Sample Response

{"id":"fa29ec8a-8ea8-4a4f-a765-3c93bd506b40"}

Example API Command 1

This API call creates a Rule titled “My First Rule 1”, as enabled, and priority 10, meaning either that this is 10th Rule on the Condition list or there are Rules with lower priority but not necessarily that 9 other Rules exist.

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8080/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/rules -H "Content-Type: application/json" -H "Accept: application/json" -d '{  
    "name":"My First Rule 1"
}'

Sample Response

{"id":"fa29ec8a-8ea8-4a4f-a765-3c22bd50634"}

Example API Command 2

This example API call creates a Rule named “Real Rule 1”, as enabled, and priority 10, meaning either that this is 10th Rule on the Condition list or there are Rules with lower priority but not necessarily that 9 other Rules exist. This Rule fires on every page. No short circuit behavior is set on the Rule.

curl -v -u admin@dotcms.com:admin -X POST http://localhost:8080/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/rules -H "Content-Type: application/json" -H "Accept: application/json" -d '{  
    "name":"Real Rule 1",
    "enabled":true,
    "priority":10,
    "fireOn":"EveryPage",
    "shortCircuit":false
}'

Sample Response

{"id":"fa29ec8a-8ea8-4a4f-a765-3c123753063"}

Update a Rule

URL Structure /api/v1/sites/{siteId}/ruleengine/rules

PUT **/api/v1/sites/{siteId}**/ruleengine/rules/{Rule_id}

Status

200 : OK
400 : Bad request (error during Rule creation, duplicates or bad parameters)
404 : Not found

Example Input JSON structure

{
   "name":"New Name",
   "enabled":true,
   "priority":10,
   "fireOn":"EveryPage",
   "shortCircuit":false,
   "ConditionGroups":{},
   "actions":{}
}

Delete a Rule

You may use the REST API to delete a rule based on the Rule ID (UUID).

Note: The Condition Groups and Actions in a Rule reference the Rule ID, so deleting the Rule automatically deletes the associated Condition Groups and Actions as well.

URL Structure

DELETE /api/v1/sites/{siteId}/ruleengine/rules/{Rule_id}

Example Curl Command

curl -v -u admin@dotcms.com:admin -X DELETE -H "Content-Type: application/json" -H "Accept: application/json" "Cache-Control: no-cache" 'http://localhost:8080/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/rules/e10bdf72-3d11-4051-a213-376029c9bc78'

Status

204 : No Content
404 : Not found

Get a Single Rule

In this case we are going to show how to retrieve the information of a specific Rule as JSON:

Steps to retrieving a Single Rule list:

  • You can use any REST tool you want.
  • You will need the Rule ID (UUID).
  • See below for the command structure and examples for both curl and Postman.

Examples

Curl command structure to retrieve a Rule list:

    curl -v -u {user}:{password} -X GET -H "Content-Type: application/json" -H "Accept: application/json" "Cache-Control: no-cache" '{host}:{port}/api/v1/sites/{site-id}/ruleengine/rules/{Rule-id}'

Example curl command with most parameters specified:

    curl -v -u admin@dotcms.com:admin -X GET -H "Content-Type: application/json" -H "Accept: application/json" "Cache-Control: no-cache" 'http://localhost:8080/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/rules/{RuleId}'

Example response:

    { "key": "c1e0b4f3-ff72-41a4-bd01-0c03cf05427d", "name": "CoreWeb created this Rule. 2015-08-17T16:44:45.301Z", "fireOn": "EVERY_PAGE", "shortCircuit": false, "priority": 10, "enabled": true, "ConditionGroups": { "0972cbf2-1702-499c-a91e-d03deb4284e8": { "id": "0972cbf2-1702-499c-a91e-d03deb4284e8", "operator": "AND", "priority": 0, "Conditions": { "ca594642-225d-46be-9ec6-0d2671132377": true } } }, "actions": {} }

Example using Postman:

Postman Screenshot

List All Rules

URL Structure

GET /api/v1/sites/{siteId}/ruleengine/rules/

Example Curl Command

curl -v -u admin@dotcms.com:admin -X GET -H "Content-Type: application/json" -H "Accept: application/json" "Cache-Control: no-cache" 'http://localhost:8080/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/rules/'

Status

200 : OK

Example Input JSON structure

{
   "3fac009e-39ce-4167-a4a1-5ba319fefb3d":{
      "ConditionGroups":{},
      "actions":{},
      "name":"testListRule3",
      "priority":0,
      "key":"3fac009e-39ce-4167-a4a1-5ba319fefb3d",
      "fireOn":"EVERY_PAGE",
      "shortCircuit":false,
      "enabled":false
   },
   "e10bdf72-3d11-4051-a213-376029c9bc78":{
      "ConditionGroups":{},
      "actions":{},
      "name":"testListRule2",
      "priority":0,
      "key":"e10bdf72-3d11-4051-a213-376029c9bc78",
      "fireOn":"EVERY_PAGE",
      "shortCircuit":false,
      "enabled":true
   },
   "3bb80a03-b092-4d87-bff8-d8b96f96a52a":{
      "ConditionGroups":{},
      "actions":{},
      "name":"testListRule1",
      "priority":0,
      "key":"3bb80a03-b092-4d87-bff8-d8b96f96a52a",
      "fireOn":"EVERY_PAGE",
      "shortCircuit":false,
      "enabled":true
   }
}