Actions

Generally, actions are the tasks the engine executes if the conditions of a rule evaluate to TRUE. Rules can also contain only actions if required.

The following sections cover in detail the various actions available throughout InRule:

• Set Value
• Execute Rule Set
• Declare Variable
• Map Data
• Fire Notification
• Set Field Invalid
• Execute SQL Query
• Execute XPath Query
• Execute Method
• Execute Web Service
• Execute REST Service
• Execute Workflow
• Send Mail
• Refresh Fields
• Halt Rule Set
• Activate Rule Set
• Deactivate Rule Set
• Activate Rule Sets by Category
• Deactivate Rule Set by Category
• Add Collection Member
• Remove Collection Member
• Clear Collection
• Copy Collection
• Sort Collection
• Execute Member Rule Set
• Copy Entity

Set Value

The Set Value action is similar to a calculation but can be nested within other rules to be made conditional.

Name

Specifies the name of the Set Value action. If the action is defined at the "Entity scope" level (in an Actions folder), this name is used when executing an action by name (from either an Execute Action / Rule Set action or the irSDK).

Field

Specifies the name of the field or rule  set variable to set.

Expression

Specifies the calculation of the value for the field you are setting. Please see About Expressions for more information on expression syntax.

Clicking on the  button will display the Expression editor.

Clicking on the  button will switch between InRule syntax and Business Language syntax.

One entity field may be set to reference the same entity instance as another entity field.

A entity field may be set null by using the null keyword as the expression.

Execute Rule Set

The Execute action provides the ability to invoke an existing Rule Set. An existing Rule Set might include a set of actions to be executed together.

Name

Specifies the name of the Execute rule set action.

Target Rule Set

Specifies the name of the rule set to execute. The values in this drop down combo box are the combination of Rule Sets and "Entity scope" rule sets defined in the Rules folder.

Only Rule Sets that having a fire mode of "Explicit" will be included in this list.

Rows will appear in the table only if the explicit rule set being executed is an independent rule set requiring one or more entities as an input argument.

Fields

The “Fields” interface allows users to pass decimal, Boolean, date, datetime, integer, text, and entity values from the calling rule set into the Target rule set for runtime use.

The Target rule set must be defined to accept parameters. These values can be hard-coded literals, or Fields, Calculations, Variables, or Expressions.

Declare Variable

The Declare Variable action specifies a local "Rule Set scope" variable to use as an alternative to an Entity Field for storing intermediate values. Note that Fields having the "Temporary" Storage setting checked serve as "Entity scope" variables.

A Variable will be accessible only within the Rule Set, and only from the level declared and below.

Name

Specifies the name of the variable.

Data type

Specifies the data type of the variable.

Entity

If data type is Entity, then the particular entity this variable will be the type of.

Default value If checked, then the default value that will be assigned to the variable when it is created.

Map Data

The Map Data action allows you to map XML or JSON documents into entities and fields.

Name

Specifies the name of the Map Data action.

Source Type

Specifies the type of text referenced by Source Expression.

Source Expression

Specifies the expression that references the field that contains the source data. Please see About Expressions for more information on expression syntax.

Clicking on the  button will display the Expression editor.

Clicking on the  button will switch between InRule syntax and Business Language syntax.

The Source Expression must resolve to a text field or variable.

Target Expression

Specifies the expression that resolves to the field or variable that the data will mapped into. Please see About Expressions for more information on expression syntax.

Clicking on the  button will display the Expression editor.

Clicking on the  button will switch between InRule syntax and Business Language syntax.

Fire Notification

When executed as an action, Fire Notification creates a message and adds it to a collection of Notifications that were created based on a Rule Set execution or input value change. Active Notifications are displayed in an irVerify window. Developers can also easily leverage these notifications from the development environment through irSDK.

Name

Specifies the name of the notification. This name will be available in the drop down combo boxes when selecting from a list of existing notifications for a Fire Notification action.

Type

Specifies the severity-level of the notification.

Mode

If "Allow Multiple Notifications" is checked, each execution of this action results in a runtime Notification. Otherwise ("Single Notification Mode"), only one runtime Notification can occur for a given notification runtime element ID.

Use Multiple Notification Mode for logging / tracing or cumulative output, Single Notification Mode for condition flagging (such as "This invoice qualifies for a discount").

"Multiple Notification Mode" is not available under Auto-Optimized Rule Sets - a compile error will result if it is used in that context.

Associated field

This checkbox when checked allows the user to associate a field with the notification. This enables runtime notifications to return element-id of the associated field.

Message

Specifies the actual message text. This text may contain embedded fields or rule expressions to provide context sensitive information in the message. For example, to refer to the "ItemQuantity" field, specify <%ItemQuantity%>.

Set Field Invalid

The Set Field Invalid action associates an invalid message with a field.

Field-invalid messages are displayed in irVerify to the right of the field in red.

They may also be retrieved using irSDK from the rule session state after rules are applied. Field validations may alternatively be set on a per-field basis using Constraints on a Field or Calculation. This action is the Syntax equivalent of the Business Language template Mark field as invalid.

The Validity Templates can then be used to reference the validity of a field.

Name

Specifies the name of the Set Field Invalid action.

Field

Specifies what field the invalid message will be associated with.

Message

Specifies the invalid message to be associated with the field. The message may include one or more embedded rule expressions, such as <%RecID%> in the above example.

Execute SQL Query

The Execute SQL Query action allows running an Execute SQL query to update data, or a Select SQL Query to query data and set a field, variable or collection.

Name

Specifies the name of the Execute SQL Query action. If the action is defined at the "Entity scope" level (in an Actions folder), this name is used when executing an action by name (from either an Execute Action / Rule Set action or the irSDK).

SQL query

Specifies the SQL Query to use.

Command type

Displays the Command Type of the underlying SQL Query.

Return type

Displays the Return Type of the underlying SQL Query.

Assign return to

Optionally specifies a Field or variable to assign the return value of a Select Query or an Execute query that returns a value.

When the query returns 0 rows, the following occurs:

• Value-type field: Is set to null (unless a Default Value is specified).
• Complex / Entity field: Value-type member fields set to null
• Collection: 0 rows appended

Settings…

Specifies optional settings including:

• Replace / Append (applicable only when assigning to a Collection).
• Default Value (applicable only when assigning to a value-type Field or Variable).
• Return First Row: if multiple rows returned, uses the first one.
• Mappings - Specifies one or more query-result column names or positions to map to Complex / Collection member fields. When a Value-type field is being assigned to, only the query-result column name or position is specified. When no mappings are specified, query-result columns are assigned in order to the value-type field or complex / collection member fields.

Parameters

Each parameter specified by the underlying SQL Query specifies a data type, an expression to use, and the parameter direction.

If the parameter expression evaluates to no value, a default value will be assigned as follows:

• No Boolean value, assigned FALSE
• No decimal value, assigned 0
• No integer value, assigned 0
• No date value, assigned 1/1/1900
• No datetime value, assigned 1/1/1900 00:00:00
• No text value, assigned NULL

Execute XPath Query

The Execute XPath Query action allows running an XPath Query to query XML data and set a field, variable or collection.

Name

Specifies the name of the Execute XPath Query action. If the action is defined at the "Entity scope" level (in an Actions folder), this name is used when executing an action by name (from either an Execute Action / Rule Set action or the irSDK).

XPath query

Specifies the XPath Query to use.

Assign return to Optionally specifies a Field or variable to assign the return value of the Query

When the query returns 0 nodes, the following occurs:

• Value-type field: Is set to null (unless a Default Value is specified).
• Complex / Entity field: Value-type member fields set to null
• Collection: 0 rows appended

Settings…

Specifies optional settings including:

• Replace / Append (applicable only when assigning to a Collection).
• Default Value (applicable only when assigning to a value-type Field or Variable).
• Return First Row: (applicable only when assigning to a Field) - if multiple nodes returned, uses the first one.
• Mappings - Specifies one or more query-result column names or positions to map to Complex / Collection member fields. When a Value-type field is being assigned to, only the query-result attribute / element name or position is specified. When no mappings are specified, query-result attributes then elements are assigned in order to the value- type field or complex / collection member fields.

Parameters

For each parameter specified by the underlying XPath Query, specifies an expression to use.

Execute Method

The Execute Method action allows running a static (Function Library) or instance method defined via a .NET Assembly EndPoint or .NET Assembly Schema, respectively.

Name

Specifies the name of the Execute Method action. If the action is defined at the "Entity scope" level (in an Actions folder), this name is used when executing an action by name (from either an Execute Action / Rule Set action or the irSDK).

Function library/entity

Specifies the alias name of the static Function Library class or instance Entity to use.

Method

Specifies the Method to run.

Return type

Displays the Return Type of the Method. "Void" means the method does not return a value.

Assign return to

Optionally specifies a Field or variable to assign the return value of a Method.

Parameters

For each parameter specified by the Method, specifies an expression to use.

Fields Name, Type and Out are automatically populated from the .NET Assembly EndPoint.

If "Out" is checked, a Field or variable must be specified that may be assigned to.

Execute Web Service

The Execute Web Service action allows executing a web service operation defined via a Web Service EndPoint.

Name

Specifies the name of the Execute Web Service action. If the action is defined at the "Entity scope" level (in an Actions folder), this name is used when executing an action by name (from either an Execute Action / Rule Set action or the irSDK).

Web service

Specifies the Web Service to use.

Operation

Specifies the operation to execute on the selected Web Service. Input Mapping Optionally specifies input parameters to be passed to the web service as well as SOAP header parameters, using "Field Mapping", where one or more web service input parameters may be assigned, element by element, to matching schema hierarchies within the rule application. Unused web service input parameters may be left unassigned if the web service allows this.

Output Mapping

Optionally specifies where web service output as well as SOAP header output should be stored, using "Field Mapping", where one or more web service output elements may be assigned, element by element, to matching schema hierarchies with the rule application. Unused web service output element may always be left unassigned.

Timeout

Specifies the duration (in milliseconds) to try executing the web service operation before it times out. Retry

Specifies the number of retries. If the connection is not established even after the specified timeout and retries, an error is thrown indicating the web service operation could not be executed.

Execute REST Service

The Execute REST Service action allows you to pull in data from a REST resource during the rule execution. A valid defined REST service endpoint and REST resource must already exist.

Name

Define the name of the Execute REST Service action.

REST Operation

Specify the name of the REST Operation to use.

Inputs

For each parameter specified by the REST Operation, specify an expression to use.

Name and Type will be automatically populated from the REST Operation. Any function or field that returns the type specified is acceptable.

Assign return to

Optionally specify a Field or variable to assign the return value of REST call. This value can be mapped into an entity field or collection with a subsequent action.

To troubleshoot 500 error responses from a REST service endpoint, you can enable Debug logging by editing your InRule Runtime configuration file.

Find the "<group />" element under "<inrule.logging />" and set the "level" attribute to "Debug". Now when a 500 server error is encountered the request and response will be written to a temporary file, the location of which will be returned in the exception from the InRule Runtime.

For more information on how to set InRule logging levels, please refer to the "InRule Logging Config File Settings" section of the Developer Help file, located at C:\Program Files (x86)\InRule\doc \InRuleSdkHelp.chm.

Execute Workflow

The Execute Workflow action allows for executing a workflow configured from a Workflow Endpoint.

Name

The name of the Execute Workflow action.

Workflow

The workflow to execute.

Timeout

• No timeout - the action runs indefinitely until the workflow completes or generates an error condition.
• Use timeout - a user-specified period for the workflow.

Send Mail

The Send Mail action sends an Email to one or more recipients.

Name

Specifies the name of the Send Mail action. If the action is defined at the "Entity scope" level (in an Actions folder), this name is used when executing an action by name (from either an Execute Action / Rule Set action or the irSDK).

Mail server

Specifies the Send Mail Server endpoint to use.

'From' address

Specifies the from EMail address. Note that a rule expression (which might simply be a fieldname) may be referenced via <% RuleAppElementName%> for this and the remaining parameters below.

'From' name

Specifies the "friendly name" for the from address.

'To' addresses

Specifies one or more recipient EMail addresses, separated by commas.

Is HTML

Sets whether the email is HTML or a plain-text email

Subject

Specifies the subject line.

Message

Optionally specifies a message body.

Attachments

Optionally specifies one or more attachment filenames.

Refresh Fields

The Refresh Fields action provides a means to specify one or more fields to be placed back onto the rule execution agenda along with rules which depend upon them. This is useful when a field's value may have been modified external to rule execution and the new value needs to be taken into account during rule execution.

Name

Specifies the name of the Refresh Fields action. If the action is defined at the "Entity scope" level (in an Actions folder), this name is used when executing an action by name (from either an Execute Action / Rule Set action or the irSDK).

Field Name(s)

Specifies one or more Fields in the current context which need to be placed, along with any dependencies, back on the rule execution agenda.

Halt Rule Set

This action causes execution of a particular rule set or all executing rule sets to halt processing within the rule engine.

Name

Specifies a name for the Halt Rule Set action. If the action is defined at the "Entity scope" level (in an Actions folder), this name is used when executing an action by name (from either an Execute Action / Rule Set action or the irSDK).

Scope

Specifies either 'halt this rule set' to halt the currently executing rule set or 'halt all rule execution' to stop all rule sets being executed by the rule engine.

This action is not supported within an optimized rule set.

Message

Specifies the message returned by the rule engine describing the reason execution halted.

Activate and Deactivate Rule Set Actions

Activate Rule Set

This action activates a rule set to include it for execution by the rule engine.

Name

Specifies a name for the Activate Rule Set action. If the action is defined at the "Entity scope" level (in an Actions folder), this name is used when executing an action by name (from either an Execute Action / Rule Set action or the irSDK). 

Rule set

Specifies the name of the rule set to activate.

Activate by instance Indicates the rule set should be activated for just the Entity instance to which it applies. If not selected, the rule set will be activated in all applicable Entity instances.

Deactivate Rule Set

This action deactivates a rule set to exclude it from execution by the rule engine.

Name

Specifies a name for the Deactivate Rule Set action. If the action is defined at the "Entity scope" level (in an Actions folder), this name is used when executing an action by name (from either an Execute Action / Rule Set action or the irSDK).

Rule set

Specifies the name of the rule set to deactivate.

Deactivate by instance

Indicates the rule set should be deactivated for just the Entity instance to which it applies. If not selected, the rule set will be deactivated in all applicable Entity instances.

Activate Rule Sets by Category

This action activates all rule sets within a particular category to include them for execution by the rule engine.

Name

Specifies a name for the Activate Rule Set action. If the action is defined at the "Entity scope" level (in an Actions folder), this name is used when executing an action by name (from either an Execute Action / Rule Set action or the irSDK).

Category

Specifies the name of the category of rule sets to activate.

Deactivate Rule Sets by Category

This action deactivates all rule sets within a particular category to exclude them from execution by the rule engine.

Name

Specifies a name for the Deactivate Rule Set action. If the action is defined at the "Entity scope" level (in an Actions folder), this name is used when executing an action by name (from either an Execute Action / Rule Set action or the irSDK).

Category

Specifies the name of the category of rule sets to deactivate.

Add Collection Member

Provides the ability to add a new member to a collection.

Name

Specifies the name of the action. If the action is defined at the "Entity scope" level (in an Actions folder), this name is used when executing an action by name (from either an Execute Action / Rule Set action or the irSDK).

Collection

Specifies the name of the collection to which a member can be added.

You may not add a member to a collection while you are looping through that collection. For more information, see Looping Through a Collection

Initial field values

Optionally assign initial values to one or more collection member fields.

Entity collection options

A collection member may be either created new or created by copying from an entity field or specific entity collection member. Only if "Existing" is selected will the following options be applicable:

• By reference: Creates a new reference at the target location pointing to the source of the copy operation. This results in no new Entities being created.
• Shallow copy: Creates a new Entity at the target location, copying over all primitive Field values. However, child Entity Field and Entity Collection values keep a reference to the existing Entities in the source location. This results in one new Entity being created.
• Deep copy: Creates a new Entity at the target location, copying over all primitive Field values and creates new Entities for each child Entity Field and Entity Collection in the source location. If duplicate Entities are encountered, the copied Entity reference will be used. This results in a new Entity being created for each unique Entity in the source.

When choosing to source the new collection member from an "Existing entity field" with "By reference" as the selected copy mode, there cannot be any field values specified in the "Initial field values" section as all of the values will reference the specified source. However, if initial field values are defined along with the "Shallow copy" or "Deep copy" options, the copy operation will occur first and then initial field values will be set. Therefore, if values exist on the copied entity that are also defined in the initial field values grid, the initial field value defined will overwrite the copied data.

When using an entity collection member as the source in "Existing entity field", you may not see the expected options in the "..." pick list. You must refer to the specific member of the collection by using the CollectionName(index).

Remove Collection Member

Provides the ability to remove a member from a collection.

Name

Specifies the name of the action. If the action is defined at the "Entity scope" level (in an Actions folder), this name is used when executing an action by name (from either an Execute Action / Rule Set action or the irSDK).

Collection

Specifies the name of the collection to remove an item from.

You may not remove a member from a collection while you are looping through that collection. For more information, see Looping Through a Collection.

Remove index

Specifies which item in the collection to remove. The value can either be a static value (like 2) or an expression that the rule engine will evaluate.

Please see About Expressions for more information on expression syntax.

Clear Collection

Provides the ability to clear all members of a collection.

Name

Specifies the name of the action. If the action is defined at the "Entity scope" level (in an Actions folder), this name is used when executing an action by name (from either an Execute Action / Rule Set action or the irSDK).

Collection

Specifies the name of the collection to remove all members from.

You may not clear a collection while you are looping through that collection. For more information, see Looping Through a Collection.

Copy Collection

Provides the ability to copy all or selected members of a collection.

Name

Specifies the name of the action. If the action is defined at the "Entity scope" level (in an Actions folder), this name is used when executing an action by name (from either an Execute Action / Rule Set action or the irSDK).

Action

Specifies whether to replace target collection or append to it.

From

The collection to copy from.

To

The collection to copy to.

You may not copy members to a collection while you are looping through that collection. For more information, see Looping Through a Collection.

Filter

Optional filter expression specifying what members in the from-collection should be copied to the to- collection. Expressions are evaluated in the context of each from-collection member. CurrentContext(expression) function may be used to evaluate an expression in the context of the node where the Copy Collection Action is located, and OuterContext() may be used to evaluate in the context of the from collection member from within an aggregate function such as Count().

Entity copy mode

Is applicable only when copying one Entity Collection to another Entity Collection. (Complex Collections are always Deep copied)

• By reference: Creates a new reference at the target ("To" collection) location pointing to the source ("From" collection) location of the copy operation. This results in no new Entity Collection Members being created.
• Shallow copy: Creates a new Entity Collection Member at the target ("To" collection) location, copying over all primitive Field values. However, child Entity Field and Entity Collection values keep a reference to the existing Entities in the source ("From" collection) location. If duplicate Entity Collection Members are encountered, the copied reference will be used. This results in a new Entity Collection Member being created for each unique Entity Collection Member in the source ("From" collection).
• Deep copy: Creates a new Entity Collection Member at the target ("To" collection) location, copying over all primitive Field values and creates new Entities for each child Entity Field and Entity Collection in the source ("From" collection) location. If duplicate Entities are encountered, the copied Entity reference will be used. This results in a new Entity being created for each unique Entity in the source ("From" collection).

Sort

Optional sort order on one or more collection fields, each in ascending / descending order as specified.

Sort Collection

Sorts a collection by a user-specified field order.

To configure the sort collection action:

1. Optionally specify the name of the sort collection action
2. Use the syntax field to designate the collection to sort. Users can also select to open the expression editor window or toggle the syntax view to Business Language mode.
3. Under fields, use the drop-down list to select fields from the collection to sort on. Specify the ascending or descending sort order for the chosen field.
4. Optionally select the Add Row button to designate additional fields to sort on.

You may not sort a collection while you are looping through that collection. For more information, see Looping Through a Collection. 

Execute Member Rule Set

This action iterates over members in a collection and for each member which satisfies the [optional] filter expression, executes the specified explicit rule set in the context of that member.

Name

Specifies a name for the Execute Member Rule Set action. If the action is defined at the "Entity scope" level (in an Actions folder), this name is used when executing an action by name (from either an Execute Action / Rule Set action or the irSDK).

Collection

Specifies the collection over which to iterate. While looping through the collection, rules in the target rule set may not modify the collection (add member, remove member, sort, clear, or copy into). For more information, see Looping Through a Collection.

Target Rule Set

Specifies an explicit rule set to execute for each member of the collection which satisfies the specified [optional] filter expression. Rule sets executed by this action must exist in the context of the specified collection's items.

Parameters

The “parameters” interface allows users to pass decimal, Boolean, date, datetime, integer, text, and entity values from the calling rule set into the Target rule set for runtime use. The Target rule set must be configured to accept a parameter.

The parameters table will only appear with populated rows if the Target rule set is configured to accept parameters. When populated rule authors will use the "Value" column of the interface to provide the specific value for each parameter. These values can be hard coded literals or Fields, Calculations, Variables, or Expressions.

Filter Expression

[Optional] Specifies additional criteria to filter members which will have the specified rule set executed in their context.

Copy Entity

The Copy Entity action supports copying the contents of an entity-field to another entity-field.

Name

Specifies a name for the Copy Entity action. If the action is defined at the "Entity scope" level (in an Actions folder), this name is used when executing an action by name (from either an Execute Action / Rule Set action or the irSDK).

Entity copy mode

• By reference: Creates a new reference at the target ("To") location pointing to the source ("From") location of the copy operation. This results in no new Entities being created.
• Shallow copy: Creates a new Entity at the target ("To") location, copying over all primitive Field values. However, child Entity Field and Entity Collection values keep a reference to the existing Entities in the source ("From") location. This results in one new Entity being created.
• Deep copy: Creates a new Entity at the target ("To") location, copying over all primitive Field values and creates new Entities for each child Entity Field and Entity Collection in the source ("From") location. If duplicate Entities are encountered, the copied Entity reference will be used. This results in a new Entity being created for each unique Entity in the source ("From").

From

From entity field.

To

To entity field.