Bookshelf Home | Contents | Index | PDF     

Siebel Business Rules Administration Guide > Configuring and Activating Rule Modules >

About the Business Rule Service Business Service

The Business Rule Service business service is prepackaged in your Siebel Repository. Irrespective of the implementation strategy you choose, Business Rule Service is the underlying service that provides the interface to the Siebel rule engine.

The implementation strategies that can be configured to invoke the Business Rule Service business service are:

For information on the implementation strategies that can be configured to invoke the Business Rule Service business service, see:

About the Input Property Set to Business Rule Service

RunRules is the only method invoked by the Business Rule Service business service.

Business Rule Service requires an input property set that consists of the input properties in Table 6.

Table 6. Business Rule Service Input Property Set Structure
Input Property
Data Type
Description

BusCompList

Hierarchy

This input property identifies and provides the hierarchical structure and data of the business components and fields that are required for the rule module that is run by the RunRules method.

For each record on which to act, an element in this list includes:

  • The name of the top-level business component in the business object hierarchy on which this rules module acts
  • The Row_ID for the specific record of the top-level business component
  • If applicable, child elements that include names of required child and further descendent business components and field values that are required to evaluate the rule

GetMoreData

String

The default value of Y indicates that the BusCompList input property set needs only to specify the top-level business components. All descendent business components and fields that have been imported are automatically included in BusCompList implicitly. In addition, specific input field values are also included implicitly.

A value of N indicates that all descendent business components, fields, and field values must be provided explicitly in the BusCompList property set.

A value of Y minimizes the amount of script required to define the BusCompList input property. However, all of the top-level business components' descendent business components and fields that have been imported into the knowledge base are included in the input property set, instead of the minimal set required for the rule module to execute. Thus performance is not optimal.

A value of N optimizes performance by providing only the minimal set of descendent business components and fields for the BusCompList input property that is required by the rule module to execute. However, you must provide the structure and data for this hierarchy explicitly, such as with script or as XML.

RuleModuleName

String

The names of the rule modules to invoke. Multiple rule module names must be separated by commas.

Each rule module must first be deployed from HaleyAuthority, configured, and activated in the Siebel application.

The input property set for Business Rule Service is generated differently in different contexts.

  • Runtime event. When you configure a runtime event to invoke rule modules, the Siebel runtime framework implicitly generates the input property set based on the values you enter in the Administration - Runtime Events screen when you configure the runtime event. You cannot control the structure of the BusCompList input property or the values of the other input properties.

    For information on configuring a rules module to run in a runtime event, see Integrating Rules with Siebel Runtime Events..

    The input property set that is implicitly provided to Business Rule Service consists of:

    • BusCompList includes the top-level business components you specified in Administration - Runtime Events and all descendent business components and fields that have been imported into HaleyAuthority. In addition, field values in the current record are provided.
    • GetMoreData = Y, to allow for implicitly building the entire BusCompList property set, given only its top-level business components.
    • PerformAction = Y.
    • RuleModuleName is one or more names of rule modules that you specify in the Administration - Runtime Events screen.
  • Script, Task UI step, or workflow step. The RunRules input property set must be provided explicitly, such as in script or in an XML file. Unlike the static structure of the input property set that is set implicitly for a runtime event, the actions that your rules execute and performance considerations determine your settings for GetMoreData, PerformAction, and the structure for BusCompList.

    Instruction for generating the input property set are provided in the following examples:

To see the complete schema for the input property set, see Input Property Set Schema for Business Rule Service.

For requirements for setting the GetMoreData and PerformAction input properties, see Setting the GetMoreData Input Property and Setting the PerformAction Input Property.

Setting the GetMoreData Input Property

Business Rule Service must be provided with data that it in turn asserts to the rule engine. Without data, rules do not execute.

Business Rule Service is provided data in one of the following ways:

  • If GetMoreData = Y, then Business Rule Service gets data from an existing database record that is identified by the current business component rowid.
  • If GetMoreData = N, then data is provided to Business Rule Service by its caller, typically script. That is, the caller must construct the data that is provided to Business Rule Service.

The following guidelines specify when setting GetMoreData=Y is allowed and when it is mandatory or highly recommended to set GetMoreData=N.

  • Direct invocation by a runtime event. A runtime event invokes Business Rule Service directly when you declaratively configure the runtime event in the Administration - Runtime Events screen. When Business Rule Service is invoked directly by a runtime event, GetMoreData = Y by default and cannot be modified.

    The Siebel runtime event functionality controls the provision of data to Business Rule Service. Data is provided from the current record in the business component as needed. In the case of a pre event, such as PreWriteRecord, new data that is not yet written to the database is also provided as needed and where it is appropriate. For example, if a field value is changed in a PreWriteRecord, and the new field value is tested when a rule is executed, the rule evaluates the new, unwritten value instead of the existing value in the database.

    This allows a pre event to execute on an existing record that is modified or on a new record.

  • Indirect invocation by a runtime event. A runtime event invokes Business Rule Service indirectly when a script attached to the runtime event calls Business Rule Service.
    • Indirect invocation by a pre runtime event. If the script is attached to a pre runtime event, such as PreWriteRecord, then:
      • If the rule module ever acts on a new record, then GetMoredata=N is mandatory. The script must construct and provide the data for the new record. GetMoreData=Y cannot be used because there is no existing record in the database from which to get the needed data.
      • If the rule module acts on existing records, then GetMoredata=N is highly recommended. GetMoredata=Y should not be used if there is any possibility that the rule should act on new, unwritten data because GetMoreData=Y forces Business Rule Service to act only on existing data in the database. Thus incorrect data could be evaluated.
    • Indirect invocation by a post runtime event. If the script is attached to a post runtime event, such as WriteRecord, then the script can define GetMoreData=Y. There is no danger that the wrong data is provided to Business Rule Service because a post runtime event acts only on data that is already written to the database.

      NOTE:  Setting GetMoreData=N is also allowed for this scenario.

  • Other scripted invocations. Business Rule Service may be invoked by scripts in other contexts, such as a scripted business service or a script attached to a Siebel Workflow step.
    • If the script or workflow writes a record to the database before invoking Business Rule Service to act on the record, then the script may set GetMoreData=Y. There is no danger that the wrong data is provided to Business Rule Service because there is no choice to be made between written and new, unwritten data.

      NOTE:  Setting GetMoreData=N is also allowed for this scenario.

    • If the script or workflow does not finish writing a record to the database before calling Business Rule Service, then the script must set GetMoreData = N and provide the data to Business Rule Service.

      GetMoredata=Y cannot be used if there is any possibility that the rule should act on new, unwritten data because GetMoreData=Y causes Business Rule Service to act only on existing data in the database. Thus incorrect data could be evaluated.

Setting the PerformAction Input Property

The Perform Action input property determines the entity that is responsible for performing actions, such as setting a field value, when a rule is executed.

  • If PerformAction = Y, then Business Rule Service is responsible for performing an action.
  • If PerformAction = N, then the caller of the Business Rule Service, such as a scripted runtime event or a script in a Siebel workflow, must take the responsibility for performing an action.

The following guidelines specify when setting PerformAction=Y is allowed and when it is mandatory or highly recommended to set PerformAction=N.

  • Direct invocation by a runtime event. A runtime event invokes Business Rule Service directly when you declaratively configure the runtime event in the Administration - Runtime Events screen. When Business Rule Service is invoked directly by a runtime event, PerformAction = Y by default and cannot be modified.
  • Indirect invocation by a runtime event. A runtime event invokes Business Rule Service indirectly when a script attached to the runtime event calls Business Rule Service.
    • Indirect invocation by a pre runtime event. If the script is attached to a pre runtime event, such as PreWriteRecord, then:
      • If the rule module ever acts on a new record, then PerformAction=N is mandatory. The script must perform any actions based on the output property set that is returned by Business Rule Service. If PerformAction = Y, then an error message is thrown.
      • If the rule module acts on existing records, then you can use PerformAction=Y, but it is highly recommended that you use PerformAction=N instead. If you use PerformAction=Y, then you must be careful that your rules do not result in an infinite loop.

        For example, assume a PreWriteRecord event calls a script which invokes Business Rules Service with PerformAction=Y. A user clicks to save a record, thereby invoking the PreWriteRecord event. The script calls Business Rule Service, which sets a field value. Because a field is modified, the PreWriteRecord event is invoked again, Business Rule Service sets the field again, and so on.

        To remedy the possible infinite loop that could be caused by a rule such as:
        if an account's name contains "ABC Company" then set "Location" to "San Jose"
        instead write a rule that does not unconditionally set a field value, such as:
        if an account's name contains "ABC Company" and the account's location is unknown then set "Location" to "San Jose"
    • Indirect invocation by a post runtime event. If the script is attached to a post runtime event, such as WriteRecord, and the event acts on existing records, then you can use PerformAction=Y, but it is highly recommended that you use PerformAction=N instead. If you use PerformAction=Y, then you must be careful that your rules do not result in an infinite loop.

      For example, assume a WriteRecord event calls a script which invokes Business Rules Service with PerformAction=Y. A user clicks to save a record, thereby invoking the WriteRecord event. The script calls Business Rule Service, which sets a field value. The record is then saved, triggering the WriteRecord event again, Business Rule Service sets the field again, and so on.

      To remedy the possible infinite loop that could be caused by a rule such as:
      if an account's name contains "ABC Company" then set "Location" to "San Jose"
      instead write a rule that does not unconditionally set a field value, such as:
      if an account's name contains "ABC Company" and the account's location is unknown then set "Location" to "San Jose"
  • Other scripted invocations. Business Rule Service may be invoked by scripts in other contexts, such as a scripted business service or a script attached to a Siebel Workflow step.
    • If the script or workflow writes a record to the database before invoking Business Rule Service to act on the record, then the script may set PerformAction=Y or to N.
    • If the script or workflow does not finish writing a record to the database before calling Business Rule Service, then:
      • You must use PerformAction=N if there is any possibility that the rule should act on new, unwritten data.
      • If the rule always acts on existing records, then you can use PerformAction=Y or N.

About the Output Property Set of Business Rule Service

The Business Rule Service business service generates an output property set that includes a record of actions that are executed by the rules engine at runtime. These actions are of the following types:

  • Validation. Lists valid or invalid that are set for the business component record by HaleyAuthority actions validate and invalidate.
  • Derivation. Lists ad hoc strings that are associated with the business component record by the HaleyAuthority actions add-value, add-currency-value, and add-currency-literal.
  • SetFieldValue. Identifies field values that are set on the business component record by HaleyAuthority actions set-field-value, set-currency-field-value, and set-currency-field-value-literal.
  • RaiseErrorText. Lists error strings generated by the HaleyAuthority action raise-error-text.
  • SetProfileAttribute. Lists ad hoc name-value pairs set by the HaleyAuthority action set-profile-value for use globally during one invocation of the rule module.

Programmatic access to the output property set of the Business Rules Service business service differs in different contexts.

To see the complete schema and examples for the Business Rule Service output property set, see Output Property Set Schema for Business Rule Service.

  
Siebel Business Rules Administration Guide Copyright © 2007, Oracle. All rights reserved.