| Oracle® BPEL Process Manager Developer's Guide 10g (10.1.3.1.0) Part Number B28981-03 |
|
|
View PDF |
| Oracle® BPEL Process Manager Developer's Guide 10g (10.1.3.1.0) Part Number B28981-03 |
|
|
View PDF |
This chapter describes how to build adaptive business processes by using a decision service to integrate BPEL processes with a business rule engine.
This chapter contains the following topics:
Use Cases for Integration of Business Processes and Business Rules
Methodology for Rule Set Modeling and Integration with a BPEL Process
See Also:
The AutoLoanDemo tutorial, which describes how to design a BPEL process that integrates with business rules and uses human workflow:
SOA_Oracle_Home\bpel\samples\demos\AutoLoanDemo
This section provides an overview of Oracle BPEL Process Manager support for business rules and business rule engines.
This section contains the following topics:
Business rules are statements that describe the policies of a company. Examples of business rules can include the following:
All customers that buy more than $100 worth of products at one time or who are over the age of 65 receive a 10% discount.
A sales department is notified when inventory quantity is lower than ten and there are more than five pending orders on a given day.
If the annual income of a customer is less than $10,000, a loan request is denied.
If a customer submitted a late payment for a previous purchase, an additional charge of 2% is added to their next purchase.
A business rule engine is a system that manages and executes business rules. A business rule system typically consists of a rule repository, rule author, and rule engine. The rule author allows business rules to be specified separately from application code. Separating the business rules from code allows business analysts to change business policies quickly with graphical tools. The rule engine evaluates the business rule and returns decisions or facts that are then used in the business process. The rules are typically stored in a rule repository in a database or file system.
Oracle BPEL Process Manager provides support for a decision service. A decision service is a mechanism for publishing rules and rule sets as a reusable service that can be invoked from multiple business processes. The decision service is a standalone deployment unit that consists of the following components:
A Web service that wraps the rule session to the underlying rule engine. This service lets business processes assert and retract facts as part of the process. In some cases, all facts can be asserted from the business process as one unit. In other cases, the business process can incrementally assert facts and eventually consult the rule engine for inferences. Therefore, the service has to support both stateless and stateful interactions.
Rules that are evaluated by the decision service using the rule engine. These are defined using the rule author and loaded into the rule repository.
Metadata that describes facts required for specific rules to be evaluated. Each rule exposed as a service uses different types of facts. These facts must be exposed through XSD definitions. Appropriate WSDL operations must be exposed for rule evaluation.
For example, a credit rating rule set may expect a customer's SSN, previous loan history, and so on as facts, but a pension payment rule may expect an employee's years of service, salary, age, and so on as facts.
See Also:
"Decision Service Architecture"Oracle BPEL Process Manager provides support for Oracle Business Rules. Oracle Business Rules is a component included with Oracle Application Server. Business analysts use Oracle Business Rules to create and change business rules that are separate from the application code. This enables analysts to change business rules without stopping business processes or having to involve programmers.
In Oracle Business Rules, facts are data objects asserted in the Oracle Business Rules Rules Engine. For example:
For a car rental company to create a rule to match a driver's age, the driver's age represents the fact used in the rule.
For a loan company to create a rule denying a loan request to customers whose incomes fall below a specific level, the income level represents the fact used in the rule.
Each data object instance corresponds to a single fact. Rules are expressions that can be evaluated on this factual information.
If an object is re-asserted (whether or not it has changed), the Oracle Business Rules Rules Engine is updated to reflect the new state of the object. Re-asserting the object does not create a new fact. In order to have multiple facts of a particular fact type, separate object instances must be asserted. Using the Oracle Business Rules Rule Author, you create rules that operate on facts that are part of a data model. You make business objects and their methods known to Oracle Business Rules using fact definitions.
Oracle Business Rules consist of the following key components:
Oracle Business Rules Rule Author — A Web browser-based tool that provides a point-and-click interface to create and edit rules.
Oracle Business Rules Rules Engine — A Java library that applies rules to facts and defines and processes rules. The Oracle Business Rules Rules Engine defines a declarative rule language, provides a language processing engine, and provides debugging tools.
Oracle BPEL Process Manager provides support for the following Oracle Business Rules Rules Engine repositories that store the business rules:
Oracle Rules Engine File Repository — Stores rules in a file repository.
Oracle Rules Engine WebDav Repository — Stores rules in a Web Distributed Authoring and Versioning (WebDAV) repository.
A repository stores dictionaries. A dictionary is a set of XML files that stores the application's rule sets and the data model. Rule sets are a group of business rules that are typically evaluated together and generated as one unit. Dictionaries can have different versions. Dictionaries and dictionary versions can be created, deleted, exported, and imported into a repository.
Oracle Business Rules SDK — A Java library that provides business rule management features to use for writing customized rules programs.
Oracle Business Rules RL Language —A language that defines the syntax for Oracle Business Rules Rules Engine programs. Oracle Business Rules RL Language includes an intuitive Java-like syntax for defining rules that supports Java semantics.
See Also:
The following documentation:
This section describes the components that comprise the decision service.
This section contains the following topics:
The decision service consists of the following components:
Rule Provider Interface (RPI) — An interface used by decision service design time clients such as Oracle JDeveloper. The RPI hides the details of a concrete rule engine implementation. This enables the RPI to interface with any rule engine from any provider. The main purpose of the RPI is to expose a uniform view of rule engine metadata such as fact types, rule sets, dictionaries, and so on.
A design time component (such as Oracle JDeveloper) can use the RPI to browse the metadata of a backend rule engine. According to what you model, metadata information for a decision service partner link can be materialized in the decision service configuration file.
Decision Service Builder — Reads the metadata information from a decision service configuration file and creates a self-contained J2EE enterprise archive that can be deployed to an application server.
Decision Service Runtime — A JAX-RPC Web service that is the Web service enabler for business rule engines such as Oracle Business Rules. The run time itself consists of the following components:
Decision Service Cache — Maintains metadata information about the rule data model used by the service. This includes metadata about the fact types, rule set, and decision service configuration. In addition, all stateful rule sessions are stored in that cache. Oracle Java Object Cache (JOC) is used. Therefore, the cache can be configured to run in clustered environments.
Fact Converter — Converts data coming from and going to Oracle BPEL Process Manager to a format understood by a rule engine. For the Oracle Business Rules Rules Engine, the fact converters use the JAXB 1.0 tech stack to convert BPEL variable data (XML) to and from Java objects.
Execution Unit — Executes the various steps defined by the interaction pattern at the backend rule engine. The execution unit uses the RPI for executions.
See Also:
Oracle Containers for J2EE Services Guide for cache configuration options to use in clustered environmentsFigure 18-1 shows how the decision service interacts with other components.
The rule author is used for rule modeling
The rule model is saved to a rule repository. The rule repository can be a file or a directory at a WebDav backend.
The RPI of the decision service is used by the Decision Service wizard to create a connection to the rule repository and browse the repository metadata.
The Decision Service wizard creates the decision service metadata configuration file. The metadata consists of information about the backend rule engine being used (rule provider) and the interaction patterns (together with fact type information) modeled for the partner link.
The decision service builder creates the decision service enterprise archive for deployment into an application server. As part of this, a WSDL is created with message types and operations adjusted to what you modeled in Step 3.
The decide activity uses decision service metadata information to present you with a list of available operations of the service and detailed information on the number and types of facts used for an interaction with the rule engine
The decide activity completes generation of a new BPEL scope in the BPEL process model. Appropriate assign activities are created to convert the data from BPEL variables to data that the decision service (and more importantly the backend rule engine) expects.
The BPEL process is deployed to Oracle BPEL Process Manager during deployment time.
The decision service enterprise archive is deployed to the application server.
The BPEL process instance invokes the JAX-RPC decision service at run time, which then interacts with the backend rule engine, executes rule sets, invokes functions, and so on. Results are eventually returned to the BPEL process.
The decision service configuration file (decisionservices.xml) defines the contract between the various components involved in the interaction of the decision service with the design time and a backend rule engine.The decision service configuration file consists of two parts:
The first part specifies metadata about the rule engine connections.
The second part provides the metadata for specific interaction patterns with a backend rule engine.
For example:
<decisionServices xmlns="http://xmlns.oracle.com/bpel/rules">
<ruleEngineProvider provider="Oracle" name="CreditRatingRuleRepository">
<repository type="File">
<file>
/D:/bpeldev/10.1.3/demo/LoanDemoPlusRules/repository/CreditRatingRepository
</file>
</repository>
</ruleEngineProvider>
<ruleEngineProvider provider="Oracle" name="LoanAdvisorRepository">
<repository type="File">
<file>
/D:/bpeldev/10.1.3/demo/LoanDemoPlusRules/repository/CarLoanBrokerRepository
</file>
</repository>
</ruleEngineProvider>
<decisionService name="CreditRatingAgent"
targetNamespace="http://cr.org/CreditRatingAgent"
ruleEngineProviderReference="CreditRatingRuleRepository">
<catalog>RatingFY06</catalog>
<catalogVersion>Approved_060205</catalogVersion>
<ruleset>PrivateCustomerRatingRules</ruleset>
<pattern name="AssertExecuteWatchStateless">
<arguments>
<assert>creditrating.Ratingrequest</assert>
<watch>creditrating.Rating</watch>
</arguments>
</pattern>
</decisionService>
<decisionService name="LoanAdvisorAgent"
targetNamespace="http://laa.org/LoanAdvisorAgent"
ruleEngineProviderReference="LoanAdvisorRepository">
<catalog>LoanOfferings</catalog>
<catalogVersion>REVIEWED_060518</catalogVersion>
<pattern name="CallFunctionStateless">
<arguments>
<call>DM.computeAdvisePrivateFinancing</call>
</arguments>
</pattern>
</decisionService>
</decisionServices>
The configuration file includes the following elements:
ruleEngineProvider — Specifies metadata about a backend rule engine connection. Apart from the rule engine provider, information on the rule repository is specified. You distinguish between these types of repositories:
File — The rule repository is stored in a file or directory.
WebDav — The rule repository is stored in a WebDav location.
decisionService — Consists of a name, an optional target namespace, and a mandatory reference to the rule engine to use for the interaction. A complete interaction with the rule engine is specified, which includes the catalog and catalog version to use, and the rule set to execute. Various interaction patterns are supported. Apart from the name of the pattern, the pattern signature is specified in terms of input and output facts or function names.
Oracle BPEL Process Manager and business rules are complementary technologies. Oracle BPEL Process Manager focuses on orchestration of systems, services, and people. Business rules focus on decision making and policies.
Some examples of where decision service can be used include:
Dynamic processing — Rules can perform intelligent routing within the business process based on service level agreements or other guidelines. For example, if the customer requires response within one day, send the loan application to the StarLoan loan agency only. If the customer can wait longer, then route the request to three different loan agencies.
Externalize decision points in the process — There are typically many conditions that must be evaluated as part of a business process. However, the parameters to these can be changed independent of the process. For example, you provide loans only to customers with a credit score of at least 650. This value may be changed dynamically based on new guidelines set by business analysts.
Data validation and constraint checks — Rules can validate input documents or apply additional constraints on requests. For example, a new customer request must always be accompanied with an employment verification letter and bank account details.
Human workflow — Rules are frequently used in the context of human tasks in the business process:
Policy-based task assignments dispatch tasks to specific roles or users. For example, a process that handles incoming requests from a portal can route loan requests and insurance quotes to a different set of roles.
Load balancing of tasks among users – When a task is assigned to a set of users or a role, each user in that role acquires a set of tasks and acts on them in a specified time. For new incoming tasks, policies may be applied to set priorities on the task and put them in specific user queues. For example, a specific loan agent is assigned a maximum of 10 loans at any time.
Oracle BPEL Process Manager provides the following design-time components that enable you to integrate BPEL processes with business rules.
The Create Rule Engine Connection wizard enables you to create a connection to a rule engine. This connection enables you to browse and select rule sets and functions available in rule dictionaries of a rule repository in the business rule engine. You only need to create one connection to the rule engine. Once created, this connection is shared between multiple BPEL projects.
Select Connection Navigator from the View main menu in Oracle JDeveloper.
Right-click Rule Engines and select New Rule Engine Connection.
Click Next on the Welcome window.
Enter a name. When creation of the rule engine connection is complete, this name displays in the Connection Navigator under Rule Engines.
Select the type of repository in which the rule sets and functions are stored in the repository of the business rule engine. For this release, the Oracle Business Rules Rules Engine is supported.
Click Next.
Click the folder icon to select a file repository directory. If you selected Oracle Rules Engine WebDav Repository, you are instead prompted to select a WebDav connection to the repository.
Note:
You can create a WebDav connection by right-clicking WebDAV Server and selecting New WebDAV Connection in the Connection Navigator.Click Next.
The Test Connection window appears.
Click Test.
If the connection to the business rule repository is successful, the following message appears:
Success
If the connection is unsuccessful, click Details to view the reason for failure. Take appropriate corrective actions.
Click Finish.
The connection name displays in the Connection Navigator under Rule Engines. If you need to edit the connection, double-click the connection name to display configuration details.
The Decision Service wizard enables you to integrate your BPEL process with a business rule (for example, a rule set or function) that you created in the Oracle Business Rules Rules Engine. This enables you to make business decisions based on these rules.
Figure 18-3 provides an overview of this integration process.
This wizard performs the following tasks:
Guides you through the selection of a rule set or function from a repository and the invocation pattern (operation) to perform
Converts your selection into a Web service to use in the BPEL process
A new decision service partner link for this Web service is automatically created that interfaces with the Oracle Business Rules Rules Engine. A WSDL file based on the rule set is generated.
The Decision Service wizard provides the following benefits:
Dynamic processing (provides for intelligent routing, validation of policies within a process, and constraint checks)
Integration with adhoc workflows (provides policy-based task assignment, various escalation policies, and load balancing of tasks)
Integration with business activity monitoring (sends alerts based on certain policies and dynamic processing-based key performance indicator (KPI) reasoning)
The following sections describe Decision Service wizard functionality in further detail:
The Decision Service wizard enables you to select an invocation pattern that describes how to interact with the business rule engine.
Drag and drop a Decision Service from the Services list of the Component Palette onto either side of the designer window beneath the header Services.
Enter a name in the Service Name field. When complete, this name is used as the partner link name. A WSDL file of the same name is also created.
The Namespace field is automatically completed with your entry from the Service Name field. You must have a unique namespace for each WSDL in your project. This is because some BPEL variables are generated from elements in the WSDL files.
Select an invocation pattern for invoking the rule set or function. The wizard creates rule sessions based on the invocation pattern you select. You do not have the option of selecting between stateful or stateless rule sessions.
The following invocation patterns are available for selection:
Execute Ruleset
Execute function
Click the flashlight next to the Ruleset or Function field. The name of this field is based on your selection in the Invocation Pattern field. This opens the Explorer window.
Click Show All Versions to display all the catalog versions of rule dictionaries in the rule repository of the business rule engine.
Expand and select the dictionary (RatingFY06), dictionary version (Approved_0600205), and rule set (PrivateCustomerRatingRules).
Notes:
If you have not created a connection to the rule engine, you cannot access the rule sets and functions in the rule repository. Click the first icon in the upper right to start the Create Rule Engine Connection wizard.
An alternative to creating a connection to a file-based rule repository is to directly import a file into a project. Note that each BPEL project must physically copy the repository file to the project at the time of Web service creation. After the file is copied, any changes to the original file are not reflected in the Web service. Click the second button in the upper right to browse for the file to import. The file must be a valid Oracle rule repository file. Otherwise, an error appears.
Click OK.
You are returned to the Select a Ruleset or a Function window.
Based on the type of invocation pattern you selected, the Select a Ruleset or a Function window displays a table with different details at the bottom of the window.
The table displays the facts in the data model of the catalog from which you selected the rule set. You select the facts to assert (that is, set the value from the BPEL variable to the fact) and retrieve the results to return. Note that the columns that appear are based on whether the selected pattern asserts facts, retrieves facts, or does both.
Specify the input (assert) and (optionally) the output (watch) facts. The assert facts enable you to assert a fact to the rule set or function (send factual data to the business rule engine). The watch facts enable you to return results from the rule set or function. Watch facts only appear if you selected an invocation pattern that retrieves results.
The Check here to assert all descendants from the top level element check box enables you to assert all the descendants of the selected rule set or function. For example, assume that a purchase order rule set contains three fact types. If this check box is selected, the purchase order and all three fact types are asserted. If this check box is not selected, only the purchase order is asserted.
Click Next.
The table displays the input parameters and parameter types to return.
Click Next.
Review the on-screen messages to ensure that all necessary XSD schema files for this project are imported from the repository by the wizard.
The wizard attempts to identify all the schema files in the repository that must be imported into this project. Based on this attempt, this window can display the following status messages:
If the Decision Service Wizard finds the schema files to import, the directory paths to the files display at the top of this window. No action is required on your part.
If the Decision Service Wizard cannot find the schema files to import, the directory paths to the files display at the top of this window. You must manually copy these files to the specified directory.
If this XSD schema file includes or imports other schema files, ensure that those files are copied into the bpel\rules\xsd subdirectory of your BPEL project indicated on-screen. Ensure that you use only relative directory paths for these schema files.
Click Next.
The decision service partner link is created. A directory named decisionservices is also created in the BPEL project. A directory with the same name as the service name is created inside the decisionservices directory.
See Also:
"Decision Service Partner Link Directory Structure" for specific details about directories and files created with the decision service partner linkThe decide activity enables you to create a BPEL process activity that invokes the decision service partner link you created with the Decision Service wizard. This activity also enables you to create copy operation assignments between the fact data in your rule set or function and BPEL variables.
When complete, a decide activity consisting of assign and invoke activities to the decision service partner link is created.
Figure 18-3 provides an overview of this integration process.
Drag and drop a Decide activity from the Process Activities list of the Component Palette into your BPEL process.
Enter a name.
Select the decision service partner link you created. If you have not created a decision service, click the first icon to the right of the Decision Service field.
Select the operation of the invocation pattern to perform. The operations available for selection are based on the invocation pattern you selected in Step 3.
If you selected Execute Ruleset
Assert facts only — Select the rule engine facts you want to assert (send factual data to the rule engine) in the future. You assign the required data for the facts with a BPEL assign activity. The underlying rule session must be stateful. Otherwise, the asserted facts are not visible to subsequent rule engine invocations.
Retrieve results — Retrieve a result from the business rule engine. The values of these results may have changed by past execution of a rule set acting on these facts. The wizard assumes that it has a stateful rule session in its cache from which a result can be retrieved. This is the case if the invocation pattern Assert facts and execute rule set operation was executed before in the BPEL process.
Assert facts and execute rule set — The same as Assert facts only, except that the rule set is executed after the facts are asserted. The wizard creates (or uses) a stateful rule session. Otherwise, the result of executing this pattern is lost. No results are retrieved from the business rule engine.
Assert facts, execute rule set, and retrieve results — The same as Assert facts and execute rule set, except that the results are retrieved from the business rule engine. You map the results of rule set execution to BPEL variables with an assign activity. The rules session remains active. This enables you to reuse previously asserted facts.
Assert facts, execute rule set, retrieve results, and reset the session — The same as Assert facts, execute rule set, and retrieve results, except that the results are reset for the next time that you invoke the Web service. Resetting the session clears the previously asserted fact values.
If you selected Execute function
Execute function — Executes a function. Functions are also defined in dictionaries. For rule sets, you select input and output facts. For functions, there are a fixed set of input parameters and a single return value.
Execute function and reset the session — The same as Execute function, except that a stateful rule session is created for this pattern. All fact values are reset after retrieving the return value of the function.
Click Assign Input Facts, then click Create to create mappings for the input facts. This enables you to assign BPEL variables to the facts to be asserted or to the function input parameters.
This enables you to create assignments that map BPEL input variables to automatically created BPEL variables that correspond to the input (assert) fact type shown in "Specifying Input and Output Facts" (for this example, Ratingrequest).
If you selected an invocation pattern that retrieves results, click Assign Output Facts, then click Create to create mappings for the output facts. This enables you to assign values from a function return value or rule set result to a BPEL variable.
This enables you to create assignments that map automatically created BPEL variables that correspond to the output (watch) fact type shown in "Specifying Input and Output Facts" (for this example, Rating) to BPEL input variables.
Click OK when complete.
A decide activity consisting of assign and invoke activities to the decision service partner link is created.
Rule sets are a group of business rules that are typically evaluated together and generated as a single unit. This section describes two methodologies for modeling rule sets in a rule author.
After you model a rule set, you can integrate it with a BPEL process in Oracle JDeveloper. You must have an existing rule repository prior to creating a decision service partner link in Oracle JDeveloper.
This section contains the following topics:
Oracle recommends that you follow these steps when modeling rule sets in a rule author.
Create a data model for rule authoring based on the XML schema.
Create a new rule repository and dictionary in the rule author.
Import the XML schema into the data model of the rule dictionary as XML facts.
Create a new rule set and model rules.
Use the Decision Service wizard to create a partner link.
This section describes how to model a simple rule for a credit rating:
Task 2: Create a New Rule Repository and Dictionary in the Rule Author
Task 3: Import the XML Schema into the Data Model of the Rule Dictionary
After completion, you use the Decision Service wizard to integrate your rule set with a BPEL process.
The first step in rule modeling is to define a data model. Data models based on XML schema are supported. This example begins with a simple data model for credit rating and defines two elements:
ratingrequest
<xsd:element name="ratingrequest">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="date" type="xsd:date" maxOccurs="1"/>
<xsd:element name="SSN" type="xsd:string" maxOccurs="1"/>
<xsd:element name="name" type="xsd:string" maxOccurs="1"/>
<xsd:element name="age" type="xsd:int" maxOccurs="1"/>
<xsd:element name="amount" type="xsd:double" maxOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
rating
<xsd:element name="rating">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="date" type="xsd:date" maxOccurs="1"/>
<xsd:element name="SSN" type="xsd:string" maxOccurs="1"/>
<xsd:element name="rating" type="xsd:int" maxOccurs="1"/>
<xsd:element name="risk" type="xsd:string" maxOccurs="1"/>
<xsd:element name="maxAmount" type="xsd:double" maxOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
Note:
It is important to understand that rule modeling is performed at the XML schema type level, whereas the data transfer from BPEL to the decision service is at the element level.An alternative model (with the same semantics) is to define the following XML schema:
<xsd:element name="ratingrequest" type="tRatingRequest"/> <xsd:element name="rating" type="tRating"/> <xsd:complexType name="tRatingRequest"> <xsd:sequence> <xsd:element name="date" type="xsd:date" maxOccurs="1"/> <xsd:element name="SSN" type="xsd:string" maxOccurs="1"/> <xsd:element name="name" type="xsd:string" maxOccurs="1"/> <xsd:element name="age" type="xsd:int" maxOccurs="1"/> <xsd:element name="amount" type="xsd:double" maxOccurs="1"/> </xsd:sequence> </xsd:complexType> <xsd:complexType name="tRating"> <xsd:sequence> <xsd:element name="date" type="xsd:date" maxOccurs="1"/> <xsd:element name="SSN" type="xsd:string" maxOccurs="1"/> <xsd:element name="rating" type="xsd:int" maxOccurs="1"/> <xsd:element name="risk" type="xsd:string" maxOccurs="1"/> <xsd:element name="maxAmount" type="xsd:double" maxOccurs="1"/> </xsd:sequence> </xsd:complexType>
You now create a new rule repository and dictionary in the rule author.
Copy the SOA_Oracle_Home\rules\fileRepositories\ruleRepository file to a location within your file system. For example:
C:\CreditRatingRules\model\CreditRatingRepository
You are now ready to open a new repository in the rule author, log in to the rule author, and connect to the new repository.
Log in to the rule author and connect to the new repository.
http://hostname:8888/ruleauthor
Enter oc4jadmin/password.
where password is the password you specified for the oc4jadmin user during installation.
Click Repository.
The Connect page appears.
Select File from the Repository Type list.
Click Browse to the right of the File Location field.
Select the repository file location specified in Step 1.
Click Create.
A message indicates that a repository connection has been created.
Click the Create subtab.
The Create Dictionary page appears.
Enter SampleDictionary in the New Dictionary Name field and click Create.
A message indicates that the dictionary has been imported.
You now import the XML schema data model into the rule dictionary.
For a given rule dictionary, you can define the underlying data model to use for rule authoring.
Click the Definitions tab.
Click XMLFact in the Definitions tree on the left.
The XMLFact Summary page appears.
Click Create.
The XML Schema Selector page appears.
Enter the following details:
| Field | Value |
|---|---|
| XML Schema | Enter the absolute path to the CreditRatingTypes.xsd file you created in Step 2 of "Task 1: Create a Data Model for Rule Authoring". For this example, the second schema file model described in that step was used. |
| JAXB Class Dictionary | Enter a directory in which to create the JAXB classes. |
| Target Package Name | Enter a Java package name to use for the XML fact types (for example, creditrating). |
Click Add Schema.
Expand the Generated JAXB Classes tree at the bottom.
Specify the objects in the schema to import. For this example, Ratingrequest, Rating, TRatingRequest, and TRating are selected.
Click Import.
A confirmation message displays indicating that four classes or packages have been imported.
You can now specify meaningful aliases for your data model. This action is optional, but considered a good practice for rule modeling.
Click XMLFact in the Definitions tree.
Select creditrating.TRatingRequest from the XML Fact Summary table.
Click Edit.
The Properties section appears.
Enter appropriate text in the Alias column for the SSN, age, amount, date, and name properties.
Click OK.
Notes:
Oracle Business Rules use Oracle JAXB 1.0 for XML fact types. As a result, certain limitations apply:Use different names for elements and complex types. Although the XML schema specification allows the same name for an element and a type, the JAXB class generator does not support it.
Use different target package names for every XML schema imported into the rule author. As part of JAXB class generation, a factory class ObjectFactory is created. If you import a second XML schema and specify the same target package name, the JAX generator overwrites the factory class from the first import. This results in unexpected behavior from the rule engine.
As a result of using JAXB for fact types, rule modeling needs to happen on the XML schema type level (complexType level). This is because for XML elements, JAXB generates marker interfaces only and the rule author cannot introspect the attributes and methods of these interfaces for rule modeling.
As part of the data model, RL functions can be specified. It is a convenient way to simplify rule action handling by externalizing the logic of a rule action into a RL function. In this case, the purpose of the rules is to accept a rating request for which rules are applied. The result of rule execution is a new rating object consisting of the data calculated by the rules. Therefore, it is convenient to create an RL function that creates a new rating object and asserts it with the rule engine.
Click RLFunction in the Definitions tree.
The RLFunction Summary page appears.
Click Create.
The RLFunction page appears.
Enter the following details:
| Field | Value |
|---|---|
| Name | DM.assertRating |
| Alias | assertRating |
| Return Type | void |
The page looks as follows:
Enter the following function in the Function Body section:
// Create a new Rating object using JAXB ObjectFactory creditrating.ObjectFactory of = new creditrating.ObjectFactory(); creditrating.Rating rating = of.createRating(); // Get a calendar instance for the current date java.util.Calendar calendar = java.util.Calendar.getInstance(); // Set Rating object attributes rating.setSSN(req.getSSN()); rating.setDate(calendar); rating.setRating(cr); rating.setRisk(crisk); rating.setMaxAmount(cmax); // Assert Rating object in working memory assert (rating);
Click Apply.
The following confirmation message appears:
This entity has been updated successfully.
After the data model is defined, you can create the rules for the credit rating.
Click the Rulesets tab.
Click Create in the RuleSet Summary page.
The Ruleset page appears.
Enter SampleRuleset in the Name field.
Enter an optional description in the Description field.
Click OK.
Select SampleRuleset in the RuleSets tree on the left.
Click Create in the Rules section.
Enter the following details:
| Field | Value |
|---|---|
| Name | YoungCustomers |
| Description | Rule for young customers |
| Priority | 0 |
When complete, the Rule page appears as follows:
Click New Pattern to define the If pattern of the rule (the rule matching part).
The Pattern Definition page appears asking for the pattern of the young customer rule.
Enter an optional name for the expected fact to match in the Choose Pattern section.
Select TRatingRequest from the drop-down list.
It now becomes clear what it means to model the rules on the XML schema type level, and not on the element level.
Click Create in the Define Test for Pattern section.
Select the appropriate operands from the Field column.
Specify several matching statements for the rule. For this example, the young customer rule is executed if the following statements are satisfied:
If the rating request comes from a customer at least 18 years of age and less than 35 years of age.
If the requested loan amount is less than 20,000.
Click Apply.
Specify the Then section of the rule.
As part of the action, you want to retract (remove) the original rating request object from the working memory of the rule engine and create and assert a new rating object.
Click New Action in the Then section of the Rule page to retract the original request object (the object that caused the rule to be invoked).
Select Retract from the Action Type list.
Select request from the Fact Instance list.
Click OK.
Click New Action again and select Call from the Action Type list.
Select assertRating from the Function list. This is the function created in Step 16.
Provide values for the function parameters. For this example, ratingrequest, credit_rating, credit_risk, and credit_max_amount). The values for ratingrequest and credit_max_amount cause the rule to be invoked and can be used in the rule action part.
Click OK.
The rule appears as follows:
Double-check the rule and confirm by clicking OK.
It is a good practice to model a rule with no if statement pattern (simply accepting the fact) and an action that generates a well-defined result for the case where no other rule is invoked. For example:
Set the priority to -10 in the Priority field to ensure that this rule is not invoked if other rules match the pattern of the fact instance.
Accept the fact (request is a TRatingRequest in the If section) without specifying any additional test pattern.
Provide a dummy result that can be checked later from Oracle BPEL Process Manager (Call assertRating(request, 0, "Unknown", 0.0) in the Then section).
Click Save Dictionary in the upper right corner.
Enter a name for the dictionary when prompted and click Save.
The rule set modeling process is now complete. The rules can now be used in a BPEL process.
See Also:
"Invoking the Sample Rule Set from a BPEL Process" to integrate the rule set with a BPEL processIn "Methodology One: Modeling Fact Types Based on an XML Schema", you modeled fact types based on an XML schema for integration with Oracle BPEL Process Manager. This methodology describes the case in which the rules are modeled already based on RL or JavaBean fact types.
The following methodology is taken:
Model the contract between BPEL and the business rules using an XML schema.
Create an RL function in the rule author that accepts parameters of the modeled XML schema. Then, perform the following procedures:
Convert the parameter values to RL or Java fact type objects.
Execute the rule set in question (rules are modeled on top of the RL or Java data model).
Convert the resulting fact object (RL or Java) to an object of the RL function return type.
Use the Call Function pattern (the invocation pattern you can select) from Oracle JDeveloper.
This section describes how to model a rule set in which the rules are already modeled based on RL or JavaBean fact types:
You must define a contract between the process modeled in BPEL and the business rules. Assume the contract is defined as follows:
Input — A rating request document of element ratingrequest
Output — A rating document of element rating
Rule set — Execute rules for the credit rating
The contract can be expressed in terms of an RL function calculateCreditRating with the following signature:
creditrating.Rating calculateCreditRating(creditrating.Ratingrequest request)
Before creating the function in the rule author, you define a new data model based on RL fact types and a new rule set based on the RL fact type data model.
You create a new data model for the credit rating using RL fact types.
Load the sample dictionary from the "Methodology One: Modeling Fact Types Based on an XML Schema" into the rule author.
Click the Definitions tab.
Select RLFact in the Definitions tree.
Create a new RL fact type named MyRatingRequest.
Create a new RL fact type named MyRating.
Click OK.
For the function to work properly, you must create a global variable to use as a placeholder to carry the result of rule execution.
Select Variable in the Definitions tree.
Select Create.
Create a variable named theResult of type mr.
This is the alias of RL fact type MyRating.
Click the Rulesets tab.
Click Create in the RuleSet Summary page.
Enter AlternateRuleset in the Name field.
Enter an optional description in the Description field.
Click OK.
Select AlternateRuleset in the RuleSets tree on the left.
Click Create in the Rules section.
Click New Pattern to enter the If pattern of the rule (the rule matching part).
Specify several matching statements for the rule. For this example:
If the rating request comes from a customer at least 18 years of age and less than 35 years of age.
If the requested loan amount is less than 20,000.
As part of the action, you want to retract (remove) the original request object.
Click OK.
Click New Action in the Then section.
Select Retract from the Action Type list.
Select req from the Fact Instance list.
Click OK.
Set the global variable to an appropriate value. For an overview of how to set global variables, see Step 7 through Step 9.
You now create an RL function.
Select Definitions.
Select RLFunction in the Definitions tree.
The RLFunction Summary window appears.
Click Create.
Enter the following details:
| Field | Value |
|---|---|
| Name | calculatCreditRating |
| Alias | calculateCreditRating |
| Return Type | Rating |
| Expand | Do not select. |
The page appears as follows:
Add the following function to the Function Body section:
// Create JAXB object factory and result object
creditrating.ObjectFactory of = new creditrating.ObjectFactory();
creditrating.Rating result = of.createRating();
// Get current calendar
java.util.Calendar calendar = java.util.Calendar.getInstance();
// Create new RL object and convert from JAXB to RL
MyRatingRequest mrr = new MyRatingRequest();
mrr.ssn = request.getSSN();
mrr.name = request.getName();
mrr.age = request.getAge();
mrr.amount = request.getAmount();
mrr.date = request.getDate().getTimeInMillis();
// Assert the RL object and run Alternate Ruleset
assert(mrr);
run("AlternateRuleset");
// Result is in variable theResult, convert back to JAXB and return
result.setRating(theResult.rating);
result.setRisk(theResult.risk);
result.setMaxAmount(theResult.maxAmount);
result.setDate(calendar);
return result;
Click OK.
This function can be used from Oracle BPEL Process Manager since it has an XML contract, although the underlying rule data model is based on RL fact types.
See Also:
"Invoking the Sample Rule Set from a BPEL Process" to integrate the rule set with a BPEL processThis section describes how to integrate the rule sets created with the Oracle Business Rules Rule Author with a BPEL process.
This section contains the following topics:
Restart Oracle JDeveloper.
Select Connection Navigator from the View main menu in Oracle JDeveloper.
Right-click Rule Engines and select New Rule Engine Connection.
Click Next on the Welcome window.
Enter SampleRuleRepository in the Connection Name field.
Select Oracle Rules Engine File Repository as the business rule engine to which to connect.
Click Next.
The Connection window appears.
Click the folder icon to select the directory in which the file repository is located.
Select the CreditRatingRepository file repository from the C:\CreditRatingRules\model\CreditRatingRepository directory. This is the repository you created in Step 1.
Click Open.
Click Next.
The Test Connection window appears.
Click Test.
If the connection to the business rule engine is successful, the following message appears:
Success
Click Finish.
See Also:
"Create Rule Engine Connection Wizard"Right-click your application in the Application Navigator section.
Select New Project to define a new BPEL process project.
Double-click BPEL Process Project in the Items window to display the BPEL Project Creation Wizard window.
Enter SampleProcess in the Name field.
Select Synchronous BPEL Process from the Template list.
Click Next.
Click the flashlight icon to the right of the Input Schema Element field.
In the Select Schema window, select CreditRatingTypes.xsd from the directory in which you saved it in Step 2 of "Task 1: Create a Data Model for Rule Authoring" and click Open.
The Type Chooser window appears.
Expand and select Imported Schemas > CreditRatingTypes.xsd > ratingrequest.
Click OK.
Click the flashlight icon to the right of the Output Schema Element field.
The Type Chooser window appears.
Expand and select Imported Schemas > CreditRatingTypes.xsd > rating.
Click OK.
Click Finish.
This completes the BPEL project creation wizard. A new BPEL process template is created for you with a receive activity accepting a ratingrequest element and a reply activity sending out a rating element.
Ensure that Services is selected in the drop-down list of the Component Palette section in the upper right section of Oracle JDeveloper.
Drag and drop a Decision Service onto the right side of the designer window anywhere beneath the header Services.
The Select a Ruleset or a Function window appears. This window enables you to select an invocation pattern.
Enter the following details:
| Field | Value |
|---|---|
| Service Name | CreditRatingService
Note: When complete, this becomes the name of the partner link. |
| Namespace | http://xmlns.oracle.com/myLoanProcess/CreditRatingService
Note: This field is automatically completed with your entry in the Service Name field. |
| Invocation Pattern | Execute Ruleset |
Click the flashlight icon next to the Ruleset field.
The Rule Explorer window appears.
This window enables you to browse and select the rule set in the dictionary of the repository you modified in Step 3 of "Task 4: Create a New Rule Set and Model Rules".
Click Show All Versions at the bottom of the window to display all versions of rule dictionaries in the specified repository in the business rule engine. Business rule engines can contain multiple rule dictionaries and versions.
Expand and select SampleRuleRepository > SampleDictionary > INITIAL > SampleRuleset.
Click OK.
You are returned to the Select a Ruleset or a Function window of the Decision Service wizard. All fact names for the SampleRuleset rule set now appear in the fact table.
Specify the details of the interaction pattern.
Select the Assert Fact check box for the Ratingrequest fact type.
This asserts a fact to the rule set (sends an input parameter of factual data to the business rule engine).
Select the Watch Fact check box for the Rating fact type.
This returns results created by the business rule engine as part of executing the rule set SampleRuleset.
Click Next.
The Copy XSD Files window shows the directory path to the CreditRatingTypes.xsd schema file for the wizard to import. If the wizard cannot find this file, you must manually copy it to the rules/xsd directory of the SampleProcess BPEL project.
Click Next, then Finish.
A partner link of the name you specified in Step 3 is created. This partner link provides the interface between the BPEL process and the business rule engine.
Select Save from the File main menu.
Drag and drop a Decide activity from the Process Activities list of the Component Palette to below the receiveInput receive activity in the designer window.
The Edit Decide window appears.
Enter the following values:
| Field | Value |
|---|---|
| Name | GetRating |
| Decision Service | CreditRatingService |
| Operation | Assert facts, execute rule set, retrieve results, and reset the session |
Click Assign Input Facts.
You now map BPEL input variables to automatically created BPEL variables that correspond to the Ratingrequest input (assert) fact type.
Click Create.
The From section shows the BPEL variables of the process and the To section shows the facts selected for the partner link interaction. Since you reused the XML schema file of the fact types in your BPEL process, you can assign the top level ratingrequest element from the BPEL input variable inputVariable to the fact to assert.
Enter the following details:
| Field | Value |
|---|---|
| From | |
|
Variable |
|
Expand and select Variables > inputVariable > payload > ns2:ratingrequest
Note: The namespace number values (for example, ns1, ns2) can vary. Use the namespace values that automatically appear. |
| To | |
|
Variable |
|
Expand and select Variables > creditrating_Ratingrequest_i > ns2:ratingrequest |
The window appears as follows:
Click OK.
Click Assign Output Facts.
You now assign the results of executing the rule set to a BPEL variable. For the assignment of output facts, the From section displays the facts as modeled in the decision service partner link interaction and the To section lists the variables of the BPEL process.
Enter the following details:
| Field | Value |
|---|---|
| From | |
|
Variable |
|
Expand and select Variables > creditrating_Rating_o > ns2:rating |
| To | |
|
Variable |
|
Expand and select Variables > outputVariable > payload > ns2:rating |
The window appears as follows:
Click OK to close the Decision Fact Map window and Edit Decide window.
This completes decide activity configuration. The BPEL process model is updated with the GetRating decide activity and the BPEL process is ready for deployment.
See Also:
"Decide Activity"This section provides a summary of issues to consider before designing a rule set.
Plan the data model before starting to model business rules.
Specify the data model using XML schema constructs.
Import the XML schema into the rule author as XML fact types.
Keep limitations of JAXB in mind (element and complex type naming, target package for multiple schemata, and so on).
Specify RL functions that can be used in rule patterns and actions.
Model a rule that does not include an if statement test pattern and set it to low priority to generate a default result in the case where no other rule starts as part of rule set execution.
Model your rules on the XML schema type level.
Be aware that the data exchange with the BPEL world is on the XML element level.
Be aware that an alternative approach using RL functions can be taken in the case of an existing data model based on RL or Java fact types.
This section describes decision service partner link creation, deployment, and run time issues.
This section contains the following topics:
As part of decision service partner link creation during design time, subdirectories and files are created under the following directory:
JDev_Oracle_Home\jdev\mywork\application_name\ process_name\decisionservices\DecisionService
ear — Top level directory for the J2EE enterprise archive (EAR)
war — Top level directory for the Web archive (WAR)
where DecisionService is the name you entered in the Service Name field of the Decision Service wizard.
Table 18-1 shows the subdirectories and files of the ear and war directories.
Table 18-1 Contents of ear and war directories
| ear/ META-INF | war/public_html | war/ WEB-INF/lib | war/ WEB-INF/wsdl | war/ WEB-INF/ | war/ WEB-INF/classes | war/WEB-INF/repository |
|---|---|---|---|---|---|---|
application.xml |
GetDecisionServiceInfo.jsp |
No files | common.xsd |
web.xml |
decisionservices.xml |
Oracle Business Rules file repository |
orion-application.xml |
BpelProcess.xsd |
webservices.xml |
Generated JAXB classes from XML fact types | |||
DecisionService.xsd |
oracle-webservices.xml |
|||||
DecisionServiceMessages.xsd |
java-wsdl-mapping.xml |
|||||
rpi.xsd |
||||||
DecisionService.wsdl |
||||||
| XML schema files for fact types |
The following steps are automatically performed as part of decision service partner link creation:
A new directory structure (see Table 18-1) is created in the following directory:
JDev_Oracle_Home\jdev\mywork\application_name\ process_name\decisionservices\DecisionService
EAR deployment descriptors are generated and stored in the META-INF subdirectory of the enterprise archive.
A Java server page file GetDecisionServiceInfo.jsp is generated and stored in the public_html directory of the Web archive.
The decision service-dependent WSDL file DecisionService.wsdl is generated and stored in the WEB-INF/wsdl directory of the Web archive. All dependent XML schema files are also copied to that directory. Dependent schema files include the definitions for the Web service messages and contract and the XML schema files for the XML fact types of the business rule engine.
The decision service configuration file decisionservices.xml is generated and copied to the directory WEB-INF/classes of the Web archive.
The rule repository location is resolved:
If the rule repository is a file repository, the repository file is copied from its original location to the WEB-INF/repository directory of the Web archive and the configuration file decisionservices.xml is modified to reference the new location.
If the rule repository is a WebDav repository, the configuration file is not edited.
JAXB generation steps:
A list of XML schema files for the XML fact types being used in the partner link is obtained.
Oracle JAXB generator is used to generate JAXB classes for the XML fact types in the directory WEB-INF/classes of the Web archive.
Web service deployment descriptors and the JAX-RPC mapping file are generated in the directory WEB-INF of the Web archive.
The decisionservices.xml decision service configuration file includes the necessary information to generate an interaction pattern-specific WSDL.
From the following information in the configuration file:
<pattern name="AssertExecuteWatchStateless">
<arguments>
<assert>creditrating.Ratingrequest</assert>
<watch>creditrating.Rating</watch>
</arguments>
</pattern>
you can understand the messages and operations for WSDL generation.
In the following section, the XML schema file of the XML fact types is imported into the decisionservices.wsdl file. This enables the fact elements to be referenced:
<types>
<schema xmlns="http://www.w3.org/2001/XMLSchema" ...>
<include schemaLocation="CreditRatingAgentTypes.xsd"/>
</schema>
<schema xmlns="http://www.w3.org/2001/XMLSchema" ...>
<import namespace="http://samples.otn.com/bpel/demo"
schemaLocation="CreditRatingTypes.xsd"/>
<import namespace="http://xmlns.oracle.com/bpel"/>
. . .
. . .
In this section, the XML schema element corresponding to the fact creditrating.Ratingrequest is shown:
. . .
. . .
<element name="assertExecuteWatchStateless">
<complexType>
<sequence>
<element name="configURL" type="string" maxOccurs="1"/>
<element name="bpelInstance" type="bpelpm:tBpelProcess"
maxOccurs="1"/>
<element name="assertList" minOccurs="1" maxOccurs="1">
<complexType>
<sequence>
<element ref="ns1:ratingrequest"/>
</sequence>
</complexType>
</element>
</sequence>
<attribute name="name" type="NCName" use="required"/>
</complexType>
</element>
. . .
. . .
In this section, the XML schema element corresponding to the fact creditrating.Rating is shown:
. . .
. . .
<element name="assertExecuteWatchStatelessDecision">
<complexType>
<sequence>
<element name="resultList" minOccurs="1" maxOccurs="1">
<complexType>
<sequence>
<element ref="ns1:rating"/>
</sequence>
</complexType>
</element>
</sequence>
</complexType>
</element>
</schema>
</types>
. . .
. . .
In this section, appropriate messages are created for the interaction pattern:
. . . . . . <message name="assertExecuteWatchStatelessMessage"> <part name="payload" element="tns:assertExecuteWatchStateless"/> </message> <message name="assertExecuteWatchStatelessDecisionMessage"> <part name="payload" element="tns:assertExecuteWatchStatelessDecision"/> </message> <message name="decisionServiceError"> <part name="payload" element="tns:errorInfo"/> </message> . . . . . .
In this section, an operation is created for the interaction pattern with input and output messages corresponding to the selected fact types:
. . .
. . .
<portType name="IDecisionService">
<operation name="assertExecuteWatchStateless">
<input name="assertExecuteWatchStatelessInput"
message="tns:assertExecuteWatchStatelessMessage"/>
<output name="assertExecuteWatchStatelessOutput"
message="tns:assertExecuteWatchStatelessDecisionMessage"/>
<fault name="operationErroredFault"
message="tns:decisionServiceError"/>
</operation>
</portType>
The decision services modeled in a BPEL project are deployed with the BPEL process. As part of BPEL process deployment, the following steps are performed for all decision services in the project:
The Java compiler (javac) is used and all Java classes are compiled in the subdirectory WEB-INF/classes.
A Web archive DecisionService.war file is created in the ear enterprise archive subdirectory of a decision service. The Web archive consists of all files under the war directory of a decision service.
An enterprise archive DecisionService.ear file is created in the top level directory of a decision service. The enterprise archive consists of all files in the ear directory of a decision service, plus the Web archive created above.
The enterprise archive DecisionService.ear is deployed to the underlying J2EE container using the administrator tools of the specific container.
The J2EE context root of a decision service DecisionService is as follows:
http://${hostname}:${http_port}/rules/${domain_id}/${process_id}/${process_revision}/DecisionService
The parameters for this syntax are defined as follows:
| Parameter | Description |
|---|---|
${hostname} |
The name of the host that on which the application server is installed |
${http_port} |
The HTTP port of the application server |
${domain_id} |
The BPEL domain |
${process_id} |
The BPEL process name |
${process_revision} |
The BPEL process version |
The decision services for a specific BPEL process and revision can be identified using Oracle Enterprise Manager 10g Grid Control Console.
See Also:
"Run Time"The decision service run time component is a standard J2EE JAX-RPC Web service.
This section describes how to manage the decision service from the following consoles:
Oracle Enterprise Manager 10g Application Server Control Console Support
See Also:
The AutoLoanDemo tutorial, which describes how to design a BPEL process that integrates with business rules and uses human workflow:SOA_Oracle_Home\bpel\samples\demos\AutoLoanDemo
There are several implications of deploying decision services as self-contained enterprise archives. The most important is that every decision service can be managed separately and independently of its invoking BPEL process using Oracle Enterprise Manager 10g Application Server Control Console.
For example, with the AutoLoanDemo sample included as part of Oracle BPEL Process Manager, the AutoLoanFlow BPEL process consists of two decision service partner links:
Loan advisor
Credit rating
Log into Oracle Enterprise Manager 10g Application Server Control Console.
http://hostname:port/em
Click Web Services.
The two decision services appear: LoanAdvisorAgent and CreditRatingAgent.
You can manage and diagnose the decision services as with any other Web service.
Click CreditRatingAgentPort to receive more details for the CreditRatingAgent decision service:
Click Operations to access additional details:
You can monitor and diagnose decision services through Oracle BPEL Control. A decisionServiceDetails property is added to the BPEL suitcase that refers to the configuration information of a decision service partner link.
Log into Oracle BPEL Control.
Click the AutoLoanFlow BPEL process in Oracle BPEL Control.
Click Descriptor.
The Descriptor tab shows the process descriptor of the AutoLoanFlow process included with the AutoLoanDemo sample:
The process has two decision service partner links configured:
CreditRatingAgentPL for credit rating
LoanAdvisorAgentPL for loan advisory
Access additional details about a decision service partner link by clicking Rule Service Details (for example, the details for CreditRatingAgentPL).
The information displayed includes the following:
Rule engine information
The backend rule engine provider (Oracle in this case)
The physical location of the rule repository
The name of the rule catalog being used for that partner link
(Optional) The version of the rule catalog being used
(Optional) The rule set used by the partner link
Interaction information
The interaction patterns used by the partner link
The input and output fact types used per interaction pattern
If you want to open the rule author and update the rule set, click Open Rule Author.
Decide activity details are also available in the Flow window.
Click the Instances tab.
Click a specific instance in the Instance list.
Click Flow.
Click a decide activity in the process instance flow to access the same information (for this example, named LoanAdvisorAgent).
This displays the following information:
This section describes advanced decision service features for which limited or no user interface support is provided. Instead, you manually edit deployment description and configuration files to use these features.
This section contains the following topics:
As described in "Decision Service Components", decision services are JAX-RPC Web services. Therefore, SOAP is the protocol to use with a decision service. However, you can configure the BPEL process to use the decision service in a WSIF context.
Perform the following procedures:
Remove the wsdlRuntimeLocation property for a decision service partner link from the bpel.xml deployment descriptor file of the BPEL process.
Add fact type Java classes to the classpath of Oracle BPEL Process Manager.
If the decision service partner link was deployed before, you can copy all the files from:
JDev_Oracle_Home\jdev\mywork\application_name\ process_name\decisionservices\DecisionService\war\WEB-INF\classes
to
SOA_Oracle_Home\bpel\system\classes
Otherwise, you must compile the Java classes located in the following directory:
JDev_Oracle_Home\jdev\mywork\application_name\ process_name\decisionservices\DecisionService\war\WEB-INF\classes
to
SOA_Oracle_Home\bpel\system\classes
Deploy the BPEL process.
The Oracle Business Rules Rules Engine defines several rule session events for monitoring. (See Oracle Business Rules Language Reference Guide for additional details.) The decision service provides the option to enable these events and log the output to the Oracle BPEL Process Manager log file.
The events are enabled through properties in the decision service configuration file (decisionservices.xml). Table 18-2 describes the properties that can be set.
Table 18-2 Decision Service Configuration File Parameters
| Property | Description |
|---|---|
watchRules |
Information about rule invocations (execution of activations) |
watchActivations |
Addition or removal of activations from the agenda |
watchFacts |
Assertion, retraction, or modification of facts in working memory |
watchFocus |
Pushing or popping of the rule set stack |
watchCompilations |
When a rule's conditions are added to the network, information about how the condition parts are shared with existing rules is printed. Ò=Ó indicates sharing. |
watchAll |
Includes information from all of the above events |
Open the file:
JDev_Oracle_Home\jdev\mywork\application_name\ process_name\decisionservices\DecisionService\war\WEB-INF\ classes\decisionservices.xml
Add the properties after the repository element in the ruleEngineProvider section.
<?xml version = '1.0' encoding = 'UTF-8'?>
<decisionServices xmlns="http://xmlns.oracle.com/bpel/rules">
<ruleEngineProvider name="CreditRatingRuleRepository"
provider="Oracle">
<repository type="File">
<file>repositoryresource:CreditRatingRepository</file>
</repository>
<properties>
<property name="watchRules">true</property>
<property name="watchActivations">true</property>
<property name="watchFacts">true</property>
<property name="watchCompilations">true</property>
</properties>
</ruleEngineProvider>
<decisionService name="CreditRatingAgent"
targetNamespace="http://xmlns.oracle.com/AutoLoanFlow/CreditRatingAgent"
ruleEngineProviderReference="CreditRatingRuleRepository">
<catalog>RatingFY06</catalog>
<catalogVersion>Approved_060205</catalogVersion>
<ruleset>PrivateCustomerRatingRules</ruleset>
<pattern name="AssertExecuteWatchStateless">
<arguments>
<assert>creditrating.Ratingrequest</assert>
<watch>creditrating.Rating</watch>
</arguments>
</pattern>
</decisionService>
</decisionServices>
Redeploy the decision service. The following is a sample output taken from the credit rating agent of the AutoLoanFlow process.
<2006-07-05 10:18:13,710> <DEBUG> <default.collaxa.cube.services> <OracleRuleSession::executeUnitOfWork> Execution plan for AutoLoanFlow:202 <2006-07-05 10:18:13,710> <DEBUG> <default.collaxa.cube.services> <OracleRuleSession::executeUnitOfWork> assert fact creditrating.Ratingrequest <2006-07-05 10:18:13,710> <DEBUG> <default.collaxa.cube.services> <OracleRuleSession::executeUnitOfWork> ==> f-1 creditrating.RatingrequestImpl(SSN : "12345", age : 41, amount : 60000.0, date : null, name : "Irving Stone", DOMNode : <ratingrequest xmlns="http://samples.otn.com/bpel/demo"> ..... <2006-07-05 10:18:13,750> <DEBUG> <default.collaxa.cube.services> <OracleRuleSession::executeUnitOfWork> ==> Activation: creditrating.__ xpath.retractDeadRatingrequest : f-1, <2006-07-05 10:18:13,750> <DEBUG> <default.collaxa.cube.services> <OracleRuleSession::executeUnitOfWork> ==> Activation: creditrating.__ xpath.retractDeadRatingrequestType : f-1, <2006-07-05 10:18:13,750> <DEBUG> <default.collaxa.cube.services> <OracleRuleSession::executeUnitOfWork> ==> Activation: PrivateCustomerRatingRules.Default : f-1 <2006-07-05 10:18:13,790> <DEBUG> <default.collaxa.cube.services> <OracleRuleSession::executeUnitOfWork> ==> Activation: PrivateCustomerRatingRules.YoungCustomers : f-1 <2006-07-05 10:18:13,790> <DEBUG> <default.collaxa.cube.services> <OracleRuleSession::executeUnitOfWork> ==> Activation: PrivateCustomerRatingRules.HighRiskCustomers : f-1 <2006-07-05 10:18:13,790> <DEBUG> <default.collaxa.cube.services> <OracleRuleSession::executeUnitOfWork> Execute rule set PrivateCustomerRatingRules <2006-07-05 10:18:13,790> <DEBUG> <default.collaxa.cube.services> <OracleRuleSession::executeUnitOfWork> Fire 1 PrivateCustomerRatingRules.YoungCustomers f-1 <2006-07-05 10:18:13,790> <DEBUG> <default.collaxa.cube.services> <OracleRuleSession::executeUnitOfWork> <== f-1 creditrating.RatingrequestImpl(SSN : "12345", age : 41, amount : 60000.0, date : null, name : "Irving Stone", DOMNode : <ratingrequest xmlns="http://samples.otn.com/bpel/demo"> .... <2006-07-05 10:18:13,820> <DEBUG> <default.collaxa.cube.services> <OracleRuleSession::executeUnitOfWork> <== Activation: creditrating.__ xpath.retractDeadRatingrequest : f-1, <2006-07-05 10:18:13,820> <DEBUG> <default.collaxa.cube.services> <OracleRuleSession::executeUnitOfWork> <== Activation: creditrating.__ xpath.retractDeadRatingrequestType : f-1, <2006-07-05 10:18:13,820> <DEBUG> <default.collaxa.cube.services> <OracleRuleSession::executeUnitOfWork> <== Activation: PrivateCustomerRatingRules.Default : f-1 <2006-07-05 10:18:13,820> <DEBUG> <default.collaxa.cube.services> <OracleRuleSession::executeUnitOfWork> <== Activation: PrivateCustomerRatingRules.HighRiskCustomers : f-1 <2006-07-05 10:18:13,830> <DEBUG> <default.collaxa.cube.services> <OracleRuleSession::executeUnitOfWork> ==> f-2 creditrating.RatingImpl(DOMNode : oracle.xml.parser.v2.XMLElement@1b1d896) <2006-07-05 10:18:13,830> <DEBUG> <default.collaxa.cube.services> <OracleRuleSession::executeUnitOfWork> ==> Activation: creditrating.__ xpath.retractDeadRating : f-2, <2006-07-05 10:18:13,830> <DEBUG> <default.collaxa.cube.services> <OracleRuleSession::executeUnitOfWork> ==> Activation: creditrating.__ xpath.retractDeadRatingType : f-2, <2006-07-05 10:18:13,830> <DEBUG> <default.collaxa.cube.services> <OracleRuleSession::executeUnitOfWork> Ruleset PrivateCustomerRatingRules executed, 1 rules fired.
Oracle Business Rules can specify an XPath expression when asserting facts. This reduces the number of assertions and provides a convenient mechanism to assert multiple facts with a single assert statement.
This functionality is available in Oracle JDeveloper. Select Check here to assert all descendants from the top level element on the Select a Ruleset or a Function window in the Decision Service wizard. When you select this option, a default XPath "//*" is created for the fact to assert. This causes all descendants of the fact element to assert during run time.
You can customize the XPath expression manually by modifying the decision service configuration located in the following file:
JDev_Oracle_Home\jdev\mywork\application_name\ process_name\decisionservices\DecisionService\war\WEB-INF\ classes\decisionservices.xml
The following example shows this option enabled for a fact type.
<?xml version = '1.0' encoding = 'UTF-8'?>
<decisionServices xmlns="http://xmlns.oracle.com/bpel/rules">
<ruleEngineProvider name="CreditRatingRuleRepository"
provider="Oracle">
<repository type="File">
<file>repositoryresource:CreditRatingRepository</file>
</repository>
</ruleEngineProvider>
<decisionService name="CreditRatingAgent"
targetNamespace="http://xmlns.oracle.com/AutoLoanFlow/CreditRatingAgent"
ruleEngineProviderReference="CreditRatingRuleRepository">
<catalog>RatingFY06</catalog>
<catalogVersion>Approved_060205</catalogVersion>
<ruleset>PrivateCustomerRatingRules</ruleset>
<pattern name="AssertExecuteWatchStateless">
<arguments>
<assert xpath="//*">creditrating.Ratingrequest</assert>
<watch>creditrating.Rating</watch>
</arguments>
</pattern>
</decisionService>
</decisionServices>
You can customize the attribute xpath="//*" before deploying the decision service.
The section describes how to design and integrate a BPEL process with the business rules of a business rule engine. This example is part of a larger tutorial that also describes how to design this BPEL process to use human workflow. Only the part describing BPEL process integration with business rules is included in this section.
This section contains the following topics:
See Also:
The complete AutoLoanDemo tutorial, which describes how to design a BPEL process that integrates with business rules and uses human workflow:SOA_Oracle_Home\bpel\samples\demos\AutoLoanDemo
This section describes how to access the Oracle Business Rules Rule Author and modify a business rule that you later integrate with your BPEL process.
Log into the Oracle Business Rules Rule Author.
http://hostname:port/ruleauthor
The Oracle Business Rules Rule Author is automatically installed with the SOA Suite Basic Install type.
Log in as oc4jadmin/password.
where password is the oc4jadmin password you entered during installation.
Click the Repository tab at the top.
Select File from the Repository Type list.
Click Browse and select the CreditRatingRepository file repository from the SOA_Oracle_Home\bpel\samples\demos\AutoLoanDemo\repository directory.
This page displays the following details:
Click Connect.
A message displays indicating that a connection has been made to the repository.
Click the Customization tab at the top.
Enter the following details to load the rule dictionary and its versions from the repository selected in Step 5:
| Field | Value |
|---|---|
| Existing Dictionaries | RatingFY06 |
| Version | Approved_060205 |
This page displays the following details:
Click Load.
A confirmation message appears:
Dictionary 'RatingFY06 (Approved_060205)' has been loaded
Click the Customization tab at the top. You now modify a rule in the rule set.
Click the YoungCustomers rule and change request.customer age < from 40 to 45.
This page displays the following details:
Click Apply.
A message displays indicating that the customization has been applied.
Click the HighRiskCustomers rule and change request.customer age >= from 40 to 45.
Click Apply.
Click Save Dictionary at the top.
Click Save.
This saves the current dictionary contents (including your updates) in the CreditRatingRepository repository.
Click Logout.
This section describes how to create a connection to the business rule repository.
Select Connection Navigator from the View main menu in Oracle JDeveloper.
Right-click Rule Engines and select New Rule Engine Connection.
Click Next on the Welcome window.
Enter CreditRatingRuleRepository in the Connection Name field.
Select Oracle Rules Engine File Repository as the type of business rule engine to which to connect.
Click Next.
The Connection window appears.
Click the folder icon to select the directory in which the file repository is located.
Select the CreditRatingRepository file repository from the SOA_Oracle_Home\bpel\samples\demos\AutoLoanDemo\repository directory. This is the repository you loaded in Step 5.
Click Open.
Click Next.
The Test Connection window appears.
Click Test.
If the connection to the business rule repository is successful, the following message appears:
Success
Click Finish.
You now create a BPEL process in which to integrate the business rules of the business rule engine you modified in "Task 1: Update a Rule Using Oracle Business Rules Rule Author".
Right-click your application in the Application Navigator section.
Select New Project to define a new BPEL process project.
Double-click BPEL Process Project in the Items window to display the BPEL Project Creation Wizard window.
Enter AutoLoanFlow in the Name field. All other fields default to the correct values for creating an asynchronous BPEL process.
Click Next.
Click the flashlight icon to the right of the Input Schema Element field.
In the Select Schema window, select AutoLoanTypes.xsd from the SOA_Oracle_Home\bpel\samples\demos\AutoLoanDemo\AutoLoanFlow\bpel directory and click Open.
The Type Chooser window appears.
Expand and select Imported Schemas > AutoLoanTypes.xsd > loanApplication.
Click OK.
Click the flashlight icon to the right of the Output Schema Element field.
The Type Chooser window appears.
Expand and select Imported Schemas > AutoLoanTypes.xsd > loanOffer.
Click OK.
Click Finish.
You now use the Decision Service Wizard to connect to the business rule engine and convert the rule set you modified in "Task 1: Update a Rule Using Oracle Business Rules Rule Author" into a Web service to use in the BPEL process. When complete, a decision service partner link is created.
Ensure that Services is selected in the drop-down list of the Component Palette section in the upper right section of Oracle JDeveloper.
Drag and drop a Decision Service onto the right side of the designer window anywhere beneath the header Services.
The Select a Ruleset or a Function window appears.
This window enables you to select an invocation pattern.
Enter the following details:
| Field | Value |
|---|---|
| Service Name | CreditRatingAgent
Note: When complete, this becomes the name of the partner link. |
| Namespace | http://xmlns.oracle.com/myLoanProcess/CreditRatingAgent
Note: This field is automatically completed with your entry in the Service Name field. |
| Invocation Pattern | Execute Ruleset |
The window now appears as follows:
Click the flashlight icon next to the Ruleset field.
The Rule Explorer window appears.
This window enables you to browse and select the rule set in the dictionary of the repository you modified in "Task 1: Update a Rule Using Oracle Business Rules Rule Author".
Click Show All Versions at the bottom of the window to display all catalog versions of rule dictionaries in the specified repository. Business rule repositories can contain multiple rule dictionaries and versions.
Expand and select CreditRatingRuleRepository > RatingFY06 > Approved_060205 > PrivateCustomerRatingRules.
Click OK.
You are returned to the Select a Ruleset or a Function window of the Decision Service wizard. Note that all fact names for the PrivateCustomerRatingRules rule set now appear in the fact table.
Select the input (Assert Fact) and output (Watch Fact) fact types:
Select the Assert Fact check box for the Ratingrequest fact type.
This asserts a fact to the rule set (sends factual data to the business rule engine).
Select the Watch Fact check box for the Rating fact type.
This returns results from the rule set. This table column only appears because you selected an invocation pattern that retrieves results in Step 3.
Click Next.
This window shows the schema file for the wizard to import.
Click Next, then Finish.
A partner link of the name you specified in Step 3 is created. This partner link provides the interface between the BPEL process and the business rule engine.
Select Save from the File main menu.
You now create a decide activity to invoke the decision service partner link you created with the Decision Service wizard. The decide activity enables you to create copy operation assignments between the fact types in your rule set (now included in the partner link) and BPEL variables. You provide an input fact to the rule set and then retrieve the results. This enables you to invoke rules from the BPEL process.When complete, a decide activity consisting of assign and invoke activities to the decision service partner link is created.
Drag and drop a Decide activity below the receiveInput receive activity in the designer window.
Enter the following values:
| Field | Value |
|---|---|
| Name | GetCreditRating |
| Decision Service | CreditRatingAgent |
| Operation | Assert facts, execute rule set, retrieve results, and reset the session |
Click Assign Input Facts.
You now map BPEL input variables to automatically created BPEL variables that correspond to the Ratingrequest input (assert) fact type.
Click Create.
Enter the following details:
| Field | Value |
|---|---|
| From | |
|
Variable |
|
Expand and select Variables > inputVariable > payload > ns1:loanApplication > ns1:SSN
Note: The namespace number values (for example, ns1, ns2) can vary. Use the namespace values that automatically appear. |
| To | |
|
Variable |
|
Expand and select Variables > creditrating_Ratingrequest_i > ns3:ratingrequest > ns3:SSN |
The window appears as follows:
Click OK.
Click Create again to create a second copy operation.
Enter the following details:
| Field | Value |
|---|---|
| From | |
|
Variable |
|
Expand and select Variables > inputVariable > payload > ns1:loanApplication > ns1:customerName |
| To | |
|
Variable |
|
Expand and select Variables > creditrating_Ratingrequest_i > ns3:ratingrequest > ns3:name |
Click OK.
Click Create again to create a third copy operation.
Enter the following details:
| Field | Value |
|---|---|
| From | |
|
Variable |
|
Expand and select Variables > inputVariable > payload > ns1:loanApplication > ns1:loanAmount |
| To | |
|
Variable |
|
Expand and select Variables > creditrating_Ratingrequest_i > ns3:ratingrequest > ns3:amount |
Click Apply.
The Edit Decide window displays the following input fact mappings:
Click Assign Output Facts.
You now map the automatically created BPEL variables that correspond to the Rating output fact type to BPEL input variables.
Click Create.
Enter the following details to create the output facts:
| Field | Value |
|---|---|
| From | |
|
Variable |
|
Expand and select Variables > creditrating_Rating_o > ns2:rating > ns2:rating
Note: The namespace number values (for example, ns1, ns2) can vary. Use the namespace values that automatically appear. |
| To | |
|
Variable |
|
Expand and select Variables > inputVariable > payload > ns3:loanApplication > ns3:creditRating |
The window appears as follows:
Click OK.
Click Create again to create a second copy operation.
Enter the following details:
| Field | Value |
|---|---|
| From | |
|
Variable |
|
Expand and select Variables > creditrating_Rating_o > ns2:rating > ns2:risk |
| To | |
|
Variable |
|
Expand and select Variables > inputVariable > payload > ns3:loanApplication > ns3:creditRisk |
Click OK.
Click Create again to create a third copy operation.
Enter the following details:
| Field | Value |
|---|---|
| From | |
|
Variable |
|
Expand and select Variables > creditrating_Rating_o > ns2:rating > ns2:maxAmount |
| To | |
|
Variable |
|
Expand and select Variables > inputVariable > payload > ns3:loanApplication > ns3:creditMaxAmount |
Click OK.
The Edit Decide window displays the following output fact mappings:
Click OK.
When complete, a decide activity consisting of assign and invoke activities to the decision service partner link is created.
Click the + sign to expand the GetCreditRating decide activity and view the assign and invoke activities.
The BPEL process is now integrated with the business rules of the business rule engine. If you later modify the contents of the business rule, you do not need to redesign your BPEL process.
Select Save from the File main menu.
