Syntax for communication rules

Each communication rule consists of a "match condition" and one or more "rule actions." If the "match condition" is satisfied, the "rule actions" are applied, one by one. If not, the rules have no effect.

The "match condition" can either be MatchCommunication or MatchAllCommunications.
The "rule actions" can either be SelectSlots, DeselectSlots, AddCoverLetter, SelectRecipientType, SetChannel, InitializeAllowedChannels, FilterAllowedChannels, RemoveAllowedChannels, SortAllowedChannels, or ModifyOrganisationalMetadata.

The rules may contain XPath expressions that are evaluated on the input correspondence. XML context is selected based on the communication (root)node as defined in the CcmBomCommunicationInput XSD. The expressions are evaluated according to the XPath 1.0 standard and must use the following fixed name spaces to navigate through the correspondence.

Namespace	Prefix	Nodes
http://www.kofax.com/ccm	ccm	All nodes, except the next three nodes
http://www.kofax.com/ccm/data	data	Keys of OrganisationalMetadata
http://www.kofax.com/ccm/contact	ct	Contact data of Senders and Recipients
http://www.kofax.com/ccm/slottype	st	Customization of SlotType

For example, to navigate to the Name field of the sender of the input correspondence, use ccm:Sender/ct:Name.

The following elements are part of the syntax:

MatchCommunication (match condition)
```
<MatchCommunicationWhenXPath="…"/>
```
The MatchCommunication condition evaluates the XPath expression on the input communication. If the result is true, the condition succeeds. Otherwise, the condition fails.
Attribute:
WhenXPath. XPath expression to be evaluated on the input communication as a whole.

The MatchCommunication condition throws an error when the result of the XPath expression is not a boolean value.
MatchAllCommunications (match condition)
```
<MatchAllCommunications/>
```
The MatchAllCommunications condition always succeeds. You can use it to express communication rules that must be applied unconditionally.

The condition has no attributes.
SelectSlots (rule action)
```
<SelectSlots WhenXPath="…"SetOverlay="…"/>
```
The SelectSlots action sets the selected flag to true for the slots for which the given XPath expression evaluates to true. When specified, the given overlay is also applied to these slots, replacing any existing overlay. SelectSlots does not consider slots that are already selected.
Attributes:
- WhenXPath. XPath expression to be evaluated on ccm:Slot nodes.
- SetOverlay. Optional. Object name of an overlay in the B&OM Repository.
SelectSlots throws an error when the result of the XPath expression is not a boolean value, or when the overlay parameter does not refer to an overlay object name in the B&OM Repository.
DeselectSlots (rule action)
```
<DeselectSlots WhenXPath="…"/>
```
The DeselectSlots action sets the selected flag to false for the slots for which the given XPath expression evaluates to true. DeselectSlots does not consider slots that are already not selected.
Attributes:
WhenXPath XPath expression to be evaluated on ccm:Slot nodes.

The DeselectSlots action raises an error when the result of the XPath expression is not a boolean value.
AddCoverLetter (rule action)
```
<AddCoverLetter Project="…" Template="…" Disposable="…"/>
```
The AddCoverLetter action adds a cover letter to the communication, by composing a Document Pack Template and selecting the cover letter slot from it. The cover letter is inserted as the first slot of the communication and gets the parameter value for its Disposable flag.

The cover letter is only added to the communication at the end of the communication creation, so it has access to the final content of the communication, but it is not affected by the other rule actions.

You can only call AddCoverLetter once for each communication.

Attributes:
- Project String. The name of the project in KCM where the Document Pack Template of the cover letter is located. A correspondence type must exist for this Document Pack Template (see Define a correspondence type).
- Template String. The name of the Document Pack Template with this cover letter. The Document Pack Template is given a Data Backbone that will be used to compose the cover letter. This Data Backbone is defined by the CcmBomCoverLetterBackbone XSD.
- Disposable Boolean flag. Indicates whether the cover letter must be disposed in case another cover letter is added later by the bundling process.
AddCoverLetter throws an error in the following cases:
- When no correspondence type is defined for the given Document Pack Template.
- When composition of the Document Pack Template fails.
- When the composed Document Pack contains other slots than the cover letter.
- When another communication cover letter was added earlier.
- When the slot identifier of the added cover letter is already used by one of the selected slots of the communication. This check is delayed until all slot selections are finished.
SelectRecipientType (rule action)
```
<SelectRecipientType>…</SelectRecipientType>
```
The SelectRecipientType action evaluates the subelement expression to a string, and verifies that it is the type of one of the allowed recipients of the communication. Then, it sets this type as the selected recipient type of the communication.

SelectRecipient must be called exactly once for each communication: if it is not called at all, the created communication is rejected by the CreateCommunication correspondence rule: if it is called more than once, it fails the second time.
The condition has no attributes, but must instead have an XML subelement of type expression. This expression must compute the recipient type to set.
SelectRecipient throws an error when the expression cannot be evaluated to a valid recipient type, or when the recipient type is set already.
SetChannel (rule action)
```
<SetChannel>…</SetChannel>
```
The SetChannel action evaluates the subelement expression to a string, and verifies that it is an object name that refers to a channel object in the B&OM Repository. Then, it sets this channel as the selected channel of the communication.

SetChannel must be called exactly once for each communication: if it is not called at all, the created communication is rejected by the CreateCommunication correspondence rule; if it is called more than once, it fails the second time.
The action has no attributes, but must instead have an XML subelement of type expression. This expression must compute the object name of the channel to set.
SetChannel throws an error in the following cases.
- The expression cannot be evaluated to a valid channel object name.
- The channel is already set.
InitializeAllowedChannels (rule action)
```
<InitializeAllowedChannels>…</InitializeAllowedChannels> 
```
The InitializeAllowedChannels action evaluates the subelement expression to a string, and verifies that it is a colon-separated list of object names of channel objects in the B&OM Repository. Then, it sets the allowed channels of the communication to this list of object names. You can only call InitializeAllowedChannels once for each communication.
The action has no attributes, but must instead have an XML subelement of type expression. This expression must compute a colon-separated list of channel object names.
InitializeAllowedChannels throws an error when the expression cannot be evaluated to a valid colon-separated list of channel object names, or when the allowed channels are already initialized.
FilterAllowedChannels (rule action)
```
<FilterAllowedChannels>…</FilterAllowedChannels> 
```
The FilterAllowedChannels action evaluates the subelement expression to a string, and verifies that it is a colon-separated list of object names of channel objects in the B&OM Repository. Then, it filters the allowed channels from the communication, only keeping the channels that appear in the computed list.
The action has no attributes, but must instead have an XML subelement of type expression. This expression must compute a colon-separated list of channel object names.
FilterAllowedChannels throws an error when the expression cannot be evaluated to a valid colon-separated list of channel object names, or when the allowed channels are not yet initialized.
RemoveAllowedChannels (rule action)
```
<RemoveAllowedChannels>…</RemoveAllowedChannels>
```
The RemoveAllowedChannels action evaluates the subelement expression to a string, and verifies that it is a colon-separated list of object names of channel objects in the B&OM Repository. Then, it removes the channels on the computed list from the allowed channels of the communication.
The action has no attributes, but must instead have an XML subelement of type expression. This expression must compute a colon-separated list of channel object names.
RemoveAllowedChannels throws an error when the expression cannot be evaluated to a valid colon-separated list of channel object names, or when the allowed channels are not yet initialized.
SortAllowedChannels (rule action)
```
<SortAllowedChannels>…</SortAllowedChannels>
```
The SortAllowedChannels action evaluates the subelement expression to a string, and verifies that it is a valid colon-separated list of object names of channel objects in the B&OM Repository. Then, it sorts the allowed channels of the communication, using the computed list as the preferred order. Channels that do not appear in the computed list are moved at the end of the allowed channels list. For example, if the current allowed channels are C:X:A, and they are sorted by the list A:B:C:D, then the end result would be A:C:X.
The action has no attributes, but must instead have an XML subelement of type expression. This expression must compute a colon-separated list of channel object names.
SortAllowedChannels raises an error when the expression cannot be evaluated to a valid colon-separated list of channel object names, or when the allowed channels are not yet initialized.
ModifyOrganisationalMetadata (rule action)
```
 <ModifyOrganisationalMetadataKey="…">…</ModifyOrganisationalMetadata>
```
ModifyOrganisationalMetadata evaluates the subelement expression to a string, and sets the given key in the organizational metadata of the communication to the computed value.
Attribute:
Key. String. The key to set in the organizational metadata of the communication.

The action also has an XML subelement of type expression. This expression must compute the value to set in the organizational metadata.
ModifyOrganisationalMetadata throws an error when the expression cannot be evaluated to a string, or when the given key does not appear in the organizational metadata configuration.

Expressions

Expressions are used in rules to denote either a static value that does not depend on the input, or a dynamic value that is computed out of the input. A dynamic value is based on concatenations of XPath expressions and constant values.

An XML node of type expression can be one of the following:

<Text Value="…"/> Denotes a constant value.
<Eval XPath="…"/> Denotes a dynamic value computed by an XPath expression.
<Concat>…</Concat> Denotes a concatenation, and must contain two or more subnodes of type expression.

Examples of expressions:

```
<Text Value="A"/>
```

<Eval XPath="ccm:OrganisationalMetadata/data:Field"/>

<Concat>
<Eval XPath="ccm:OrganisationalMetadata/data:Field1"/>
<Text Value=";"/>
<Eval XPath="ccm:OrganisationalMetadata/data:Field2"/>
</Concat>

Example

<CommunicationRuleSet xmlns="http://www.kofax.com/ccm">
 
  <CommunicationRule Reference="E1">
    <MatchCommunication WhenXPath="(@Label = 'Original') or (@Label = 'CopyForPortal')"/>
    <SelectSlots WhenXPath="ccm:SlotType/ccm:Customs/st:RecipientType = 'Customer'"/>
    <DeselectSlots WhenXPath="ccm:SlotType/ccm:Customs/st:SupplyOnce = 'true'"/>
  </CommunicationRule>
  
  <CommunicationRule Reference="E2">
    <MatchCommunication WhenXPath="(@Label = 'Original') and (ccm:OrganisationalMetadata/data:ReturnToDepartment = 'true')"/>
    <SelectRecipientType><Text Value="Department"/></SelectRecipientType>
    <SetChannel><Text Value="Print"/></SetChannel>
    <AddCoverLetter Project="X" Template="CoverLetterDepartment" Disposable="false"/>
  </CommunicationRule>

  <CommunicationRule Reference="E3">
    <MatchCommunication WhenXPath="@Label = 'CustomerOriginal'"/>
    <SelectRecipientType><Text Value="Customer"/></SelectRecipientType>
    <AddCoverLetter Project="X" Template="CoverLetterCustomer" Disposable="false"/>
  </CommunicationRule>
  
  <CommunicationRule Reference="E4">
    <MatchAllCommunications/>
    <InitializeAllowedChannels><Text Value="Print:Emal"/></InitializeAllowedChannels>
  </CommunicationRule>

  <CommunicationRule Reference="E5">
    <MatchCommunication WhenXPath="exists(ccm:Slots/ccm:Slot/ccm:SlotType[@Name='OLA']) and (ccm:OrganisationalMetadata/data:OLA_Must_Print = 'true')"/>
    <FilterAllowedChannels><Eval XPath="metadata2"/></FilterAllowedChannels>
    <RemoveAllowedChannels><Eval XPath="metadata"/></RemoveAllowedChannels>
    <SortAllowedChannels><Text Value="Print:Email""/></SortAllowedChannels>
    <SetChannel><Eval XPath="ccm:AllowedChannels/ccm:First"/></SetChannel>
  </CommunicationRule>
  
  <CommunicationRule Reference="E6">
    <MatchCommunication WhenXPath="none"/>
    <ModifyOrganisationalMetadata Key="A"><Text Value="A"/></ModifyOrganisationalMetadata>
    <ModifyOrganisationalMetadata Key="B"><Eval XPath="B"/></ModifyOrganisationalMetadata>
  </CommunicationRule>
  
</CommunicationRuleSet>