Click or drag to resize

Rules

Rules in CodeTwo Exchange Rules Pro are sets of actions, conditions, exceptions and additional options that apply to messages traveling through Exchange Server. When defined conditions are met, the associated actions are triggered and performed on messages. This section describes available operations that are related to rules themselves. A code example for these operations is also provided – it can be used to implement them in a custom app, via the provided API.

The example below shows how to create a new rule and upload it to the Settings Storage WCF Service using UploadChanges(String, ItemsSnapshotTRuleDesc).

C#
//Create a new rule
var rule = new Settings.RuleDesc();
rule.ID = Guid.NewGuid().ToString();
rule.Name = "Sample rule";

//Activate the rule
rule.Active = true;

//Create a snapshot and add the rule to this snapshot
var snapshot = new Settings.ItemsSnapshotT<Settings.RuleDesc>();
snapshot.NewItems = new Settings.RuleDesc[] { rule };
snapshot.AllItemsIds = snapshot.NewItems.Select(r => r.ID).ToArray();

//Upload the snapshot to SettingsStorage
var client = new ER.SDK.SettingsStorageClient("SettingsStorageHttpEndpoint");
client.UploadChanges(null, snapshot);

Besides using the UploadChanges(String, ItemsSnapshotTRuleDesc) method, you can also perform operations on rules using:

Learn more about configuration of rules in CodeTwo Exchange Rules Pro

Note

The recommended way to upload, edit and delete rules via a custom application is to use the UploadChanges(String, ItemsSnapshotTRuleDesc) method. It will let you upload all settings and changes in one transition (collected in ItemsSnapshotTT and RuleDesc as T) to the Settings Storage WCF Service. Therefore, in multi-server environments this approach decreases the number of processes responsible for propagation of settings across other instances of the Settings Storage WCF Service.

Operations performed on rules via API

The table below presents a list of all operations (available in the provided API) that may be performed on rules, with description and code entity references.

Operation

Description

Code entity reference

Downloading existing rules

The collections of existing rules are stored within the Settings Storage WCF Service. To download the collections and manage them via a custom application, you can use the DownloadRules(String) method. Therefore, use this method only if you want to work with the rules that already exist in the Exchange Rules Service installation.

The code example below shows how to download existing rules to a custom app:

C#
//Download existing rules from SettingsStorage to a custom application
var settingsStorage = new ER.SDK.SettingsStorageClient("SettingsStorageHttpEndpoint");
Settings.RuleDesc[] rules = settingsStorage.DownloadRules(null);

Creating a new rule

While creating a new instance of a rule, you first need to assign a unique identifier called GUID as the ID of your rule. Next, define whether the rule should be activated or not using the true or false value. Finally, use a preferred upload method to send the configuration back to the Settings Storage WCF Service.

The code example below shows how to create a new activated rule and upload it to the Settings Storage WCF Service using UploadChanges(String, ItemsSnapshotTRuleDesc):

C#
//Create a new rule
var rule = new Settings.RuleDesc();
rule.ID = Guid.NewGuid().ToString();
rule.Name = "Rule's name";

//Activate the rule
rule.Active = true;

//Create a new snapshot
var snapshot = new Settings.ItemsSnapshotT<Settings.RuleDesc>();

//Associate new items
snapshot.NewItems = new Settings.RuleDesc[] { rule };
snapshot.AllItemsIds = snapshot.NewItems.Select(r => r.ID).ToArray();

//Upload the changes to SettingsStorage
var settingsStorage = new ER.SDK.SettingsStorageClient("SettingsStorageHttpEndpoint");
settingsStorage.UploadChanges(null, snapshot);

Updating edited rules

The rules modified via the custom application need to be uploaded back to the Settings Storage WCF Service to take effect within your environment. To do that, create ItemsSnapshotTT (use RuleDesc type as T) and add the modified rules to ChangedItems.

The code example below shows how to create a rule via a custom app, upload it to the Settings Storage WCF Service, modify the rule on the app and upload the modified rule back to the Settings Storage WCF Service:

C#
//Download existing rules from SettingsStorage to a custom application
var settingsStorage = new ER.SDK.SettingsStorageClient("SettingsStorageHttpEndpoint");
Settings.RuleDesc[] rules = settingsStorage.DownloadRules(null);

//Choose a rule, e.g. the first one with 0 index
var rule = rules[0];

//Change the rule's name and activate the rule
rule.Name = "Name changed";
rule.Active = true;

//Create a snapshot for the changes
var snapshotUpdate = new Settings.ItemsSnapshotT<Settings.RuleDesc>();

//Add the changed rule to the snapshot
snapshotUpdate.ChangedItems = new Settings.RuleDesc[] { rule };
//Select all ID-s
snapshotUpdate.AllItemsIds = rules.Select(r => r.ID).ToArray();

//Upload the changes to SettingsStorage
settingsStorage.UploadChanges(null, snapshotUpdate);

Deleting rules

To delete the rule from the Settings Storage WCF Service using the custom app you need to assign the rule's ID to DeletedItemsIds.

The code example below shows how to create a new rule on the custom app, upload it to the Settings Storage WCF Service and delete it:

C#
//Download existing rules from SettingsStorage to a custom application
var settingsStorage = new ER.SDK.SettingsStorageClient("SettingsStorageHttpEndpoint");
Settings.RuleDesc[] rules = settingsStorage.DownloadRules(null);

//Choose a rule, e.g. the first one with 0 index
var rule = rules[0];

//Create a snapshot for deleting the rule
var snapshotDelete = new Settings.ItemsSnapshotT<Settings.RuleDesc>();
snapshotDelete.DeletedItemsIds = new string[] { rule.ID };
//Select all ID-s except the deleted rule
snapshotDelete.AllItemsIds = rules.Select(r => r.ID).Except(snapshotDelete.DeletedItemsIds).ToArray();

//Upload the changes to SettingsStorage
settingsStorage.UploadChanges(null, snapshotDelete);

Processing subsequent rules

ProcessingOptions property enables to force the application to process or stop processing other rules if the current one is applied or not.

The code example below shows how to create a rule via a custom app and include a processing option that will stop the processing of other rules if a current one has been applied and will process other rules if the current one has not been applied. Additionally, the rule will be uploaded to the Settings Storage WCF Service:

C#
//Create a new rule
var rule = new Settings.RuleDesc();
rule.ID = Guid.NewGuid().ToString();
rule.Name = "Sample rule";
rule.Description = "Sample rule description";

//Activate the rule
rule.Active = true;

//Stop processing if the rule is applied
rule.ProcessingOptions.StopIfApplied = true;

//Continue processing if the rule is not applied
rule.ProcessingOptions.StopIfNotApplied = false;

//Create a snapshot and add the rule to this snapshot
var snapshot = new Settings.ItemsSnapshotT<Settings.RuleDesc>();
snapshot.NewItems = new Settings.RuleDesc[] { rule };
snapshot.AllItemsIds = snapshot.NewItems.Select(r => r.ID).ToArray();

//Upload the snapshot to SettingsStorage
var client = new ER.SDK.SettingsStorageClient("SettingsStorageHttpEndpoint");
client.UploadChanges(null, snapshot);
See also

Actions - learn what actions can be added to rules and how to implement these actions in a custom app by using the provided API.