Working with rule sets
You can use the REST interface to work with rule sets and their rules on the appliance where you are currently working.
When working with rule sets, you include the rulesets parameter in all requests.
With rule sets, you can:
- Retrieve a list of rule sets
- Retrieve a rule set
- Export rule sets
- Export a rule set
- Import a rule set into a top-level position
- Import a rule set into a nested position
- Enable a rule set
- Disable a rule set
- Move a rule set
- Delete a rule set
Retrieving a list of rule sets
Request formats
<URL>/rulesets?topLevelOnly=<Boolean>
<URL>/rulesets?topLevelOnly=<Boolean>&page=<int>&pageSize=<int>
You can retrieve a list of all rule sets on the appliance where you are currently working.
When retrieving this list, set the value of the topLevelOnly parameter to true to include only top-level rule sets. Rule sets that are nested in a top-level rule set are not shown on the list.
You can request a particular page of the feed that is returned and specify the page size.
The feed provides a list in xml format with an ID for each rule set. This ID allows you to identify a rule set that you want to work with.
Sample commands
Retrieve a list of all rule sets on the appliance where you are currently working:
curl -i -b cookies.txt -X GET "$REST/rulesets?topLevelOnly=false"
Retrieve a list of all top-level rule sets on the appliance where you are currently working, omitting nested rule sets:
curl -i -b cookies.txt -X GET "$REST/rulesets?topLevelOnly=true"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| topLevelOnly | Boolean | If true, only top-level rule sets are shown on a list of rule sets. Otherwise, also nested rule sets are shown. Default: false |
| page | Integer | Number of a page in a feed with a list of rule sets Default: 1 |
| pageSize | Integer | Size of a page in a feed Default: –1 |
Retrieving a rule set
Request formats
<URL>/rulesets/rulegroups/<rule set ID>
<URL>/rulesets/rulegroups/<rule set ID>/successor?topLevelOnly=<Boolean>
<URL>/rulesets/rulegroups/<rule set ID>/successor?
topLevelOnly=<Boolean>&page=<int>&pageSize=<int>
You can retrieve a rule set on the appliance where you are currently working.
When retrieving a rule set, you append the rulegroups parameter in addition to the rulesets parameter and provide the rule set ID. You can look up rule set IDs in the feed that is returned when you retrieve a list of all rule sets.
You can retrieve a rule set with all rule sets following it on the rule sets tree by appending the successor parameter.
To retrieve a top-level rule set without nested rule sets, set the value of the topLevelOnly parameter to true.
You can request a particular page of the feed that is returned and also specify the page size.
The feed provides the rule set in xml format with nested rule sets and successors according to what you specified.
Sample commands
Retrieve an individual rule set on the appliance where you are currently working:
curl -i -b cookies.txt -X GET "$REST/rulesets/rulegroups/5234"
Retrieve an individual rule set on the appliance where you are currently working, including its successors and nested rule sets:
curl -i -b cookies.txt -X GET "$REST/rulesets/rulegroups/5234/successor?topLevelOnly=false"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| rule set ID | Integer | Rule set identifier, for example, 5234 Rule set IDs are included in the feed that is returned when you retrieve a list of all rule sets. Default: None |
| topLevelOnly | Boolean | If true, only top-level rule sets are shown on a list of rule sets Otherwise, also nested rule sets are shown. Default: false |
| page | Integer | Number of a page in a feed with a list of rule sets Default: 1 |
| pageSize | Integer | Size of a page in a feed Default: –1 |
Exporting rule sets
Request format
<URL>/rulesets/export
You can export all rule sets that exist on the appliance where you are currently working. The exported data includes all rules, lists, settings, and properties pertaining to each of the rule sets.
When exporting rule sets, you append the export parameter in addition to the rulesets parameter.
The exported data is stored in a file with the name that you provide using the -o parameter.
The feed that is returned contains the exported data in xml format under the file name that you provided.
Sample command
Export all rule sets that exist on the appliance where you are currently working:
curl -b cookies.txt -X POST "$REST/rulesets/export" -o rulesetInMWGLibraryXMLForm.xml
Variable request parameters
None
Exporting a rule set
Request format
<URL>/rulesets/rulegroups/<rule set ID>/export
You can export a rule set from the appliance where you are currently working. The exported data includes all rules, lists, settings, and properties pertaining to the rule set. Nested rule sets are also included.
When exporting a rule set, you append the export and rulegroups parameters in addition to the rulesets parameter and provide the rule set ID. You can look up rule set IDs in the feed that is returned when you retrieve a list of all rule sets.
The exported data is stored in a file with the name that you provide, using the -o parameter.
The xml file that you receive as a feed in response to your request contains the exported data under the file name that you provided.
Sample command
Export an individual rule set that exists on the appliance where you are currently working:
curl -b cookies.txt -X POST "$REST/rulesets/rulegroups/5234/export" -o rulesetInMWGLibraryXMLForm.xml
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| rule set ID | Integer | Rule set identifier, for example, 5234 Rule set IDs are included in the feed that is returned when you retrieve a list of all rule sets. Default: None |
Importing a rule set into a top-level position
Request formats
<URL>/rulesets/import
<URL>/rulesets/import?position=<int>&autoResolveBy=<string>
You can import an individual rule set into a top-level position of the rule set system on the appliance where you are currently working. The imported data includes all rules, lists, settings, and properties pertaining to the rule set.
When importing a rule set into a top-level position, you append the import parameter in addition to the rulesets parameter.
You can specify a position for the rule set and the method of resolving conflicts with existing configuration items, for example, lists and settings. If you do not specify a position or method, default values are applied.
You must also specify a Content-Type header and provide the name of the xml file that contains the rule set data, using the -d parameter.
The feed that is returned contains the imported rule set data in xml format.
Sample command
Import a rule set into a top-level position on the appliance where you are currently working:
curl -i -b cookies.txt H "Content-Type: application/xml" -d @rulesetInMWGLibraryXMLForm.xml -X POST "$REST/rulesets/import?position=3&autoResolveBy=copy"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| position | Integer | Number of the position that an imported top-level rule set takes in the rule set system The rule set system can be viewed on the standard Web Gateway interface. Numbering begins with 0, which means if you specify 0, the rule set is imported into first position among the existing top-level rule sets. If you specify –1 or nothing at all, the rule set is imported into the last position. Default: –1 |
| autoResolveBy | String | Method used for resolving conflicts that might arise when a rule set is imported Conflicts arise when a rule set uses configuration items, such as lists or settings, that already exist in the rule set system on your appliance. The resolution method can be:
Usually, this solves all conflicts. Default: off If not all conflicts could be solved by applying the selected method, an error message with code number 409 is sent in response to your request. The response body then includes the conflicting data. |
Importing a rule set into a nested position
Request formats
<URL>/rulesets/rulegroups/<parent rule set ID>/import
<URL>/rulesets/rulegroups/<parent rule set ID>import?position=<int>&autoResolveBy=<string>
You can import a rule set into a nested position of the rule set system on the appliance where you are currently working. The imported data includes all rules, lists, settings, and properties pertaining to the rule set.
When importing a rule set into a nested position, you append the import and rulegroups parameters in addition to the rulesets parameter and provide the ID of the rule set that serves as parent of the nested ruleset. You can look up rule set IDs in the feed that is returned when you retrieve a list of all rule sets.
You can specify a position among the nested rule sets for the imported rule set and the method of resolving conflicts with existing configuration items, for example, lists and settings. If you do not specify a position or method, default values are applied.
You must also specify a Content-Type header and provide the name of the xml file that contains the rule set data, using the -d parameter.
The feed that is returned contains the imported rule set data in xml format.
Sample command
Import a rule set into a nested position on the appliance where you are currently working:
curl -i -b cookies.txt H "Content-Type: application/xml" -d @rulesetInMWGLibraryXMLForm.xml -X POST "$REST/rulesets/rulegroups/4224/import?position=0&autoResolveBy=auto"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| parent rule set ID |
Integer | Rule set identifier for a parent rule set, for example, 4224 Rule set IDs are included in the feed that is returned when you retrieve a list of all rule sets. Default: None |
| position | Integer | Number of the position that an imported rule set takes among the existing nested rule sets of its parent rule set. Numbering begins with 0, which means if you specify 0, the rule set is imported into first position among the existing nested rule sets. If you specify –1 or nothing at all, the rule set is imported into the last position. Default: –1 |
| autoResolveBy | String | Method used for resolving conflicts that might arise when a rule set is imported Conflicts arise when a rule set uses configuration items, such as lists or settings, that already exist in the rule set system on your appliance. The resolution method can be:
Usually, this solves all conflicts. Default: off If not all conflicts could be solved by applying the selected method, an error message with code number 409 is sent in response to your request. The response body then includes the conflicting data. |
Enabling a rule set
Request format
<URL>/rulesets/rulegroups/<rule set ID>/enable
You can enable a rule set on the appliance where you are currently working.
If this rule set is nested within a parent rule set, make sure this rule set is also enabled before enabling the nested rule set.
When enabling a rule set, you append the enable and rulegroups parameters in addition to the rulesets parameter and provide the rule set ID. You can look up rule set IDs in the feed that is returned when you retrieve a list of all rule sets.
You must also specify a Content-Type header.
After enabling the rule set, you must commit this change using a separate command.
Sample command
Enable a rule set on the appliance where you are currently working:
curl -i -b cookies.txt H "Content-Type: application/xml" -X POST "$REST/rulesets/rulegroups/1929/enable"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| rule set ID | Integer | Rule set identifier, for example, 5234 Rule set IDs are included in the feed that is returned when you retrieve a list of all rule sets. Default: None |
Disabling a rule set
Request format
<URL>/rulesets/rulegroups/<rule set ID>/disable
You can disable a rule set on the appliance where you are currently working.
When disabling a rule set, you append the disable and rulegroups parameters in addition to the rulesets parameter and provide the rule set ID. You can look up rule set IDs in the feed that is returned when you retrieve a list of all rule sets.
You must also specify a Content-Type header.
After disabling the rule set, you must commit this change using a separate command.
Sample command
Disable a rule set on the appliance where you are currently working:
curl -i -b cookies.txt H "Content-Type: application/xml" -X POST "$REST/rulesets/rulegroups/1929/disable"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| rule set ID | Integer | Rule set identifier, for example, 5234 Rule set IDs are included in the feed that is returned when you retrieve a list of all rule sets. Default: None |
Moving a rule set
Request formats
<URL>/rulesets/rulegroups/<rule set ID>/move?position=<int>
<URL>/rulesets/rulegroups/<rule set ID>/move?parentId=<int>&position=<int>
You can move a rule set to a different position within the rule set system on the appliance where you are currently working. You can move it to a top-level or a nested position.
When moving a rule set to a top-level position, you append the move and rulegroups parameters in addition to the rulesets parameter and provide the rule set ID. You can look up rule set IDs in the feed that is returned when you retrieve a list of all rule sets.
You must also provide a position number to specify the top-level position, for example, the first position among all existing top-level rule sets.
When moving a rule set to a nested position, you append the move and rulegroups parameters in addition to the rulesets parameter and provide the rule set IDs of the moved rule set and the rule set that serves as its parent.
You must also provide a position number to specify the position of the moved rule set among the existing nested rule sets of the parent rule set.
After moving the rule set, you must commit this change using a separate command.
Sample commands
Move a rule set to a top-level position on the appliance where you are currently working:
curl -i -b cookies.txt -X POST "$REST/rulesets/rulegroups/4224/move?position=2"
Move a rule set to a nested position on the appliance where you are currently working:
curl -i -b cookies.txt -X POST "$REST/rulesets/rulegroups/6326/move?parentId=2159&position=4"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| rule set ID | Integer | Rule set identifier, for example, 5234 Rule set IDs are included in the feed that is returned when you retrieve a list of all rule sets. Default: None |
| parentId | Integer | Rule set identifier for a parent rule set, for example, 4224 Default: None |
| position | Integer | Number of the position that an moved rule set takes among the existing top-level rule sets or nested rule sets of its parent rule set. Numbering begins with 0, which means if you specify 0, the rule set is moved into first position among the existing top-level or nested rule sets. If you specify –1 or nothing at all, the rule set is imported into the last position. Default: –1 |
Deleting a rule set
Request format
<URL>/rulesets/rulegroups/<rule set ID>
You can delete a rule set on the appliance where you are currently working.
When deleting a rule set, you append the rulegroups parameter to the rulesets parameter and provide the rule set ID. You can look up rule set IDs in the feed that is returned when you retrieve a list of all rule sets.
After deleting the rule set, you must commit this change using a separate command.
Sample command
Delete a rule set on the appliance where you are currently working:
curl -i -b cookies.txt H "Content-Type: application/xml" -X DELETE "$REST/rulesets/rulegroups/2037"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| rule set ID | Integer | Rule set identifier, for example, 5234 Rule set IDs are included in the feed that is returned when you retrieve a list of all rule sets. Default: None |
Sample script for working with rule sets
The following bash script deletes a rule set on the appliance you are currently working on.
Before performing this operation, the script sets a URL variable for accessing the REST interface.
#!/bin/bash ## Set URL variable for accessing REST interface REST=http://localhost:4711/Konfigurator/REST ## Log on and authenticate curl -i -c cookies.txt -X POST "$REST/login?userName=myUserName&pass=myPassword" ## Delete rule set curl -i -b cookies.txt -X DELETE "$REST/rulesets/rulegroups/com.scur.type.regex.4537/entry/3" ## Commit deletion curl -b cookies.txt -X POST "$REST/commit" ## Log off curl -b cookies.txt -X POST "$REST/logout"