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.

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 End Points

The following table lists the REST end points available to manage Rules. For additional end points used to manage Conditions and Actions, please see the Conditions REST API and Actions REST API documentation.

Note: You must be logged into the dotCMS backend with a user ID with appropriate permissions to use any of these end points.

| End Point | Description | HTTP
Method | URL Structure | | list | List All Rules | GET |

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

/api/v1/sites/{site-id}/ruleengine/rules/{Rule-id}

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

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

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

List All 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:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/rules/'

Return 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
   }
}

Get a Single Rule

This end point retrieves information about a single Rule, specified by the Rule ID.

Note:

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

Curl Command Structure

    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}'

Curl Example

The following example retrieves the information of a specific Rule as JSON:

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

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

Postman Example

Create a Rule

Notes:

• Condition Groups and Actions must reference a Rule, so they can't be created until after the Rule is created.
• The database table used to create store Rules is called “dot_Rule”.
• The Rule name must be unique for each site/host.

Response

{
    "id":"<generated_id>"
}

Status

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

Parameters

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:8082/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:8082/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:8082/api/v1/sites/48190c8c-42c4-46af-8d1a-0cd5db894797/ruleengine/rules/e10bdf72-3d11-4051-a213-376029c9bc78'

Status

204 : No Content
404 : Not found