tacticalRules configuration

This article describes the content of the tacticalRules configuration.

Grammar

The schema of the rules XML file is: rules.xsd.

Content of the rules file

A rules file contains several rule elements. Each of the rule element defines one rule which must be applied by the module. A rule has three parts:

• A mandatory trigger which defines what will trigger the rule
• One or more conditions which specify additional conditions for the rule to be executed
• One or more actions which define the results of the rule execution

Note that more than one rule can be triggered at the same time.

Trigger

The trigger is the external or internal event which will trigger the rule. There are several possible trigger types:

• The reception of a service with specified data values
• The change of state for an internal value

Service trigger

This type of trigger will be triggered if:

• A specified service is received
• This service has specified data values

For example, the following declaration specifies that the rule will be triggered if the nextWaypoint service is received and the waypointID value is "WP10":

      <trigger name="nextWaypoint">
         <data name="waypointID" value="WP10" />
      </trigger>

It is not mandatory to declare all the datas in the Service. You may even not declare any data at all, in that case it will mean that the rule will be triggered each time the service is received. For example, this declaration for the same service is valid:

      <trigger name="nextWaypoint"/>

Note that if you want to use more elaborate conditions for data values in the service to be triggered, you can define them in the conditions.

Using complex data types in triggers

You can use complex data types in triggers:

• The dataStruct element declares that the data you specify is a structure and that you look for something inside this structure
• The dataArray element declares that the data you specify is an array and that you look for something inside this array

When you declare one of these elements, you need to declare the path leading to the terminal element for which you will look for the value:

• The field element declares a field in a structure
• The index element declares an index in an array

Internal value trigger

This type of trigger is applied with the value of an internal data and will be triggered if:

• The specified internal data exists
• This data has a specified value

For example, the following declaration specifies that the rule will be triggered if the myData data exists and its value is "WP10":

      <valueTrigger name="myData" value="WP10"/>

If you don't specify a value, the trigger will be triggered if the internal data is created. For example:

      <valueTrigger name="myData"/>

Note that if you want to use more elaborate conditions for internal data values, you can define them in the conditions.

Conditions

The rule conditions specify additional conditions for the parent rule to be executed. There are several possible conditions types:

• exists: the data exists
• notExists: the data does not exist
• equals: the data is equal with a specified value
• notEquals: the data is not equal with a specified value
• greater: the data is greater than a specified value
• less: the data is less than a specified value
• greaterOrEqual: the data is greater or equal than a specified value
• lessOrEqual: the data is less or equal than a specified value
• between: the data is between two values

The data can be either a data of the service trigger, or an internal data.

Example

The following conditions will be true if both of the conditions are true:

• The "waypointID" data in the service trigger exists and has the "WP10" value
• The "myData" internal data exists and is true

      <conditions>
         <equals name="waypointID" value="WP10" />
         <equals name="myData" value="true" type="boolean" />
      </conditions>

Actions

Actions define the actions to execute if a trigger is received and its associated conditions are true. There are several possible actions types:

• event: an internal data value is set
• service: the datas for a provider service are set and the service is invoked
• copyService: the content of the service trigger is copied to an output service, and this service is invoked
• copyValue: the value of a data of the service trigger is copied to an internal data
• startTimer: a timer is started. At the end of the timer a value will be set

Using complex data types in service actions

You can use complex data types in service actions:

• The dataStruct element declares that the data you specify is a structure and that you look for something inside this structure
• The dataArray element declares that the data you specify is an array and that you look for something inside this array

When you declare one of these elements, you need to declare the path leading to the terminal element for which you will look for the value:

• The field element declares a field in a structure
• The index element declares an index in an array

Internal datas

Internal datas are simple type datas defined in the content of the tacticalRules module. Note that you don't explicitly declare datas, but you can assign a value to a data. if this data does not exist, it will be created.

For example, the following event declarations set the value of the internal data myData:

• If myData already existed before the application of the event, its value will be set to 10
• If myData did not already existed before the application of the event, it will be created and its value will be set to 10

      <event name="myData" value="10" type="int" />

It is possible to use internal datas in:

• Triggers
• Conditions
• Actions

Invocation configuration

Several configuration parameters allow to configure how the services will be invoked:

• invokeBlock specifies that the service invocation is blocking
• cloneService specifies that the service will be cloned prior to the invocation

These parameters can be set globally for all the rules configuration file, or for one action.

Example

Both these examples will perform a blocking invocation, and copy the service priori to the call:

      <rules invokeBlock="true" cloneService="true">
         <rule>
            <trigger name="trigger">
               <data name="boolData" value="true" />
            </trigger>
            <copyService name="triggeredEvent"/>
         </rule>
      </rules>

and:

      <rules>
         <rule>
            <trigger name="trigger">
               <data name="boolData" value="true" />
            </trigger>
            <copyService name="triggeredEvent" invokeBlock="true" cloneService="true"/>
         </rule>
      </rules>