This article demonstrates how to create and modify a dynamic domain when working with business rules in WebSphere Operational Decision Management (ODM). The screenshots are taken using IBM ODM V7.5, but the article is equally applicable for IBM ODM V8. An example rule is defined to expect a value of type String. The rule is then converted so that the expected values are constrained by an enumerated domain. The domain is dynamically populated by an Excel file. This article takes you through the steps to convert and test the rule in Rule Designer, and shows how the domain can be modified or extended by a business user in the Decision Center.
This article assumes the following prerequisites:
- Familiarity with rule design and development in WebSphere Operational Decision Management V7.5.
- Practical experience with Rule Designer.
- A successful installation of IBM WebSphere Operational Decision management V7.5.
- An installed copy of Microsoft Excel 2003 or 2007.
What are dynamic domains?
WebSphere Operational Decision Management V7.5 supports the use of a variety of domains for rule development. A domain places a restriction on type elements in the Business Object Model (BOM). WebSphere ODM supports static, dynamic, enumerated, and complex domains. For example, enumerated domains can be used in rule editing to present valid choices to the rule author. A dynamic domain is an enumerated domain that makes use of values in an Excel file or other data source. The domain is dynamically populated from the data source. This provides the flexibility to make on-the-fly changes and then synchronize the domain and the data source.
Why use dynamic domains?
Dynamic domains offer a number of advantages to both rule developers and business users:
- By constraining a business user's selection to a predefined set of values, rule developers can help prevent errors.
- Dynamic domains can be easily extended or modified by business users, whereas static enumerations require IT support for changes.
- Adding a value to a dynamic domain does not require a change to a rule service contract.
Preventing errors. An important best practice in rule design is creating rules that ensure accuracy and consistency when they are used. Enforcing consistency upfront can prevent downstream validation errors during rule execution. For example, suppose that one clause of a rule expects the name of a language, specified as a string. The rule might state that if the language of a request is English, the response is to be transmitted in that language. Other language strings expected might be German or Italian, but unless the string is entered accurately the rule is invalid.
Figure 1. Specifying a string when defining a rule
During rule authoring, business users can accidentally misspell the string or use a mix of upper and lower cases. An exact match on the string is necessary for successful rule execution; user errors will result in the rule misfiring or not firing at all.
To tighten the constraints on a rule so that errors are less likely, a string can be replaced with an enumerated list. This improves rule accuracy, but extensions to the list require additional coding. This can cause a delay while business users wait for the change to be implemented, tested, and released for use.
The recommended best practice is to represent the expected values in a dynamic domain. A dynamic domain is a predefined set of values that can be easily extended by business users without the need for an additional cycle of development and test time. In this example, a domain is used to constrain the choices to a predefined list of languages for selection.
Figure 2. Selecting a language from a predefined list
Freeing business users to extend valid parameters for rules. If an Excel file is the underlying data source of a domain, business users authoring rules in the Decision Center can easily add or remove values. A change can be introduced by making a simple edit to the spreadsheet and then updating the corresponding decision table. This flexibility removes dependencies on developers to make required code changes and can result in reduced time for changes to be deployed.
Eliminating the need for changes to service contracts. An important benefit of using domains instead of static enumerations, apart from reduced dependency on developers, is that adding a domain value does not result in changes to service contracts. Therefore developers do not need to redeploy the rule service or change the service client(s). Conversely, when using dynamic domains, the service contract is less self-descriptive because it does not describe the possible domain values. The values would need to be communicated to the service client outside of the contract.
Creating a dynamic domain
This section introduces the example rule project (provided for download, and describes the steps needed to
convert a rule so that the expected parameter uses the enumerated type
LanguageType instead of the type string.
Step 1: Import package and review rules
- Open the Rule Designer. From the File menu, select Import.
- Expand General, select Existing Projects
into Workspace, and click Next.
Figure 3. Selecting an import source
- In the Import Projects dialog, select Select archive
file. Browse to the location of the downloaded hello-rules zip package provided with this
article. Click Open and then click
Figure 4. Selecting the archive file to import
The HelloRequest and HelloResponse classes
The Execution Object Model (XOM) in our example consists of two
Java™ classes, a request and a response. The
HelloRequest class takes a language (a string); the
HelloResponse class returns a message in the language
specified by the request.
Figure 5. The HelloRequest and HelloResponse classes
A Business Object Model (BOM) is generated from the XOM with these two classes.
Figure 6. The Business Object Model (BOM)
The Messages rule package (under the folder rules/messages) contains a Greetings decision table, as shown in Figure 7.
Figure 7. The Greetings decision table
There are six rules in the ruleset (each row corresponds to a rule). If the
language specified in the request is English, the greeting returned is
"Hello". If the language requested is German, the greeting is "Hallo". In
this initial decision table, the language is of type String. Later we'll
constrain the language to be a predefined set of values of type
The project includes a Decision Validation Services (DVS) test configuration with two scenarios and expected results (in hello-rules/testsuite.xlsx) as shown in Figure 8.
Figure 8. Decision Validation Services test scenarios
To execute the DVS test suite, right-click DVS test.launch in hello-rules and run as DVS test. Figure 9 shows the result of the test suite execution. To view the results, right-click the report.html file and select Open With => Web Browser.
Figure 9. Results of the DVS test execution
Step 2: Create a domains.xlsx file defining the domain
Next, create an Excel spreadsheet for the dynamic domain. For this article, the file domains.xlsx has already been created in the Resources folder with the following content:
Figure 10. The domains.xlsx file
The Excel domain provider handles the link between the values in the Excel spreadsheet and the BOM. The Excel file must have one row for each value of the domain provider. The file must conform to this structure:
- The Values column contains the values of the domain provider.
- The BOM to XOM mapping column indicates the BOM to XOM mapping for each domain value.
- The Label column lists each language as it will be displayed when authoring a rule (the verbalization of the domain value).
Step 3: Create new virtual BOM entry
- Right-click the bom directory and select New => BOM Entry.
- In the New BOM Entry dialog, enter
virtualfor the name and select Create an empty BOM entry, then click Finish.
Figure 11. Creating a new BOM entry
Step 4: Create new BOM class called LanguageType class
- From the Rule Explorer, double-click the virtual BOM entry you just
created, and select New Class.
Figure 12. Creating the LanguageType class
LanguageTypeas the name of the class, and click Finish. The result is shown in Figure 13.
Figure 13. The LanguageType class
Step 5: Create the domain for the class
- Double-click LanguageType. Under
Domain, click Create.
Figure 14. Creating a domain for the class
- In the Domains dialog, expand Dynamic Domains,
choose Excel, and click Next.
Figure 15. Selecting the domain type (Excel)
- Enter the name of the Excel file that defines the domain. Specify
Languagesas the name of the sheet. Be sure to select Table with header, then select Values for the Value column, BOM to XOM for the BOM to XOM column, and Label for the Label column, then click Finish.
Figure 16. Mapping the columns of the Excel file
The domain values now appear as members of the class.
Figure 17. The domain values
- Expand the BOM to XOM Mapping section. You may need to maximize the tab and scroll down to see this section.
java.lang.Stringas the Execution name for the BOM to XOM Mapping.
Figure 18. Mapping the BOM class to the XOM
- Save the project.
Step 6: Create a new member of HelloRequest class
- From the bom/hello-xom directory, navigate to the
HelloRequestclass, double-click language, and remove the verbalization. Select Ignore for DVS so that language is not used during testing.
Figure 19. Removing the original verbalization for the HelloRequest class
- Save your work.
Tip: You will see errors in the Rule Explorer view. However, these errors will be resolved when the remaining steps are completed.
- Create a new member of the
languageVirtual. Double-click the
HelloRequestclass. Under the Members section, click New. Specify
languageVirtualfor the name. Click Browse and select LanguageType (instead of string) for the Type field. Click OK and then Finish.
- Save your work.
Figure 20. Creating the languageVirtual member
- Double-click on the member languageVirtual.
Figure 21. Selecting the languageVirtual member
- Under the Member Verbalization section, click
Create to create a default verbalization.
Figure 22. Creating a default verbalization for languageVirtual
- Modify the verbalization by clicking Edit the subject used in
Figure 23. Editing the verbalization
- In the dialog box, change language virtual to
language, and click OK.
Figure 24. Editing the verbalization term
- Remove the word virtual from the Action clause so
that the final verbalization matches Figure 25.
Figure 25. The final verbalization
- Under the BOM to XOM Mapping section, define the
getter and setter for the new member as shown in Figure 26. You may need to maximize the tab and scroll down
to see this section.
Figure 26. Defining the getter and setter for the languageVirtual member
- Save your work.
Thus far, you created a new attribute that represents the underlying
language, defined getters and setters for it, verbalized it, and made it
LanguageType. You also removed the verbalization from
the original language.
Step 7: Modify the corresponding rules
The original rules are expecting a string. Therefore the rules must be
adjusted to expect input of type
- Under the rules/messages folder, double-click the
Greetings decision table. String is now an
Figure 27. The existing rule contains an invalid type (string)
- To correct this, right-click on the column header
Language and select Edit Condition
Figure 28. Selecting Edit Condition Column
- Edit the Condition Column and specify LanguageType
instead of string.
Figure 29. Replacing string with LanguageType
- Click Apply and then OK.
- Double-click each string in the Language column and choose the appropriate value from the dropdown (English for English, and so on).
- Save your work.
The resulting decision table should look like Figure 30.
Figure 30. The modified decision table
Step 8: Rerun the test
In this step, you rerun the DVS test as a regression test to ensure that the newly created dynamic domain does not impact the expected results.
- Right-click the hello-rules folder and select Run => Run Configurations.
- Select DVS test under DVS Excel file.
- Verify the path of the Excel file containing the test suite and
indicate the desired location of the new HTML output report. Click
Apply and then Run.
Figure 31. Setting up and running the DVS test
- Verify the test results by viewing the HTML report with a browser.
Step 9: Add new values to the spreadsheet
- First open the domains.xlsx spreadsheet and create a new row for each
new value. In this example, a row has been added for the Alsatian and
Figure 32. Adding new values in the Excel file
- Save the file and refresh the resources folder.
- Under the folder bom => virtual, double-click the
LanguageType class. Under Domain type:
Excel, click Synchronize. The new values
appear in the list of class members.
Figure 33. Synchronizing new domain values with the class
Tip: After any updates to a domain, refresh the resources folder containing the Excel file, and use the Synchronize link to synchronize the updates with the class.
- Return to the Greetings decision table in the rule package. Use the dropdown menu to select the new languages and then type the expected response in the Greeting column.
- Save the project.
Figure 34. Updating the decision table
You can then extend your test suite by adding scenarios to cover the newly added languages.
Step 10: Publish to Decision Center
- From the Start menu, start the Sample server if it
is not already started.
Figure 35. Starting the Sample server
- Right-click the hello-rules project folder and select
Decision Center => Connect. Enter the URL used
to access the Decision Center and supply your authentication
information, then click Connect.
Figure 36. Configuring the connection to the Decision Center
- When the remote operation and synchronization are complete, click OK.
- Click Finish.
Figure 37. Connecting to the Decision Center
Upon successful synchronization, you'll see the following message indicating that synchronization is complete.
Figure 38. A successful synchronization with Decision Center
Modifying dynamic domains in the Decision Center
Using dynamic domains allows business users to implement and deploy a change to a business rule quickly without the aid of IT support. Rules developed with enumerations would require code modifications to accommodate new values; with dynamic domains a business user can make simple edits to the underlying Excel spreadsheet that defines the domain. The new values are immediately available for testing and deployment, and eventual synchronization with the Rule Designer.
The following steps demonstrate how a business user can add a new value to a predefined list of languages. The steps assume that the hello-rules project has been synchronized with the Decision Center and is ready to use.
Step 1: Log into the Decision Center
- Enter your username and password on the Decision Center sign-in page.
Figure 39. Logging into the Decision Center
- On the Home tab, select your project from the
Project in use list.
Figure 40. Selecting a project in Decision Center
- On the Explore tab, under Business
Rules, review the values of the Greetings decision table
imported from Rule Designer. Click the Greetings
Figure 41. Accessing the Greetings decision table
The Greetings decision table is displayed in the Decision Center.
Figure 42. The Greetings decision table
Step 2: Create a Resources smart folder
- On the Explore tab, click the Create Smart
Folder icon and create a new smart folder called
Figure 43. The Create Smart Folder icon
- For Properties, specify
Resourcesas the folder name, and click Next.
Figure 44. Creating a Resources folder
- For Step 2. Query, indicate that all resources are
to be searched and displayed by clicking all business
rules and selecting all resources from
the dropdown menu. Click Finish.
Figure 45. Specifying a query for the Resources folder
The domains.xlsx file should be visible in the new folder.
Figure 46. The domains.xlsx file in the Resources folder
Step 3: Modify domains.xlsx in the Resources folder
In this step, we'll download the Excel file to the local disk and add a row for a new language, Swedish. We'll then upload the file to the Decision Center and refresh the project.
- Click the download icon next to the file name. Save the file to your
local disk and then open it for editing.
Figure 47. Downloading the domains.xlsx file
- Edit the file, adding a new row for the Swedish language, and save
Figure 48. Adding a new row to the Excel file
- Back in the Decision Center, click the domain.xlsx
link and click Edit.
Figure 49. Editing the link to the domains.xlsx file
- Click Browse, select the updated domains.xlsx file,
and click Open to upload the file to the Decision
Center, then click Finish.
Figure 50. Uploading the new domains.xlsx file
The Resources smart folder now displays the updated domains.xlsx.
Figure 51. The uploaded domains.xlsx file
Step 4: Reload dynamic domains
From the Project tab, select Reload Dynamic Domains to refresh the project. Click OK.
Figure 52. Reloading the dynamic domain
Step 5: Add the new value to the decision table
The new value Swedish can now be used when authoring a rule.
- On the Explorer tab, expand Business
Rules, click the Greetings link, and
then click Edit.
Figure 53. Selecting the Greetings decision table
Clicking Edit displays an editable view of the decision table.
Figure 54. Editing the decision table
- Select Step 2: Table and use the dropdown menu to
reveal the refreshed list of predefined values for languages. In the
Language column, select Swedish.
Figure 55. Selecting the new value in the Languages column
- In the Greeting column, indicate the translated value to be displayed
when Swedish is requested.
Figure 56. Entering the translated values in the Greeting column
- Click Finish and save your work.
The new value is immediately available for use in rule authoring.
Figure 57. Using the new value in rule definitions
This article demonstrated the advantages of using dynamic domains in WebSphere Operational Decision Management V7.5. The use of a dynamic domains ensures a measure of error prevention during rule authoring and offers benefits over use of static enumerations. By using a simple Excel file as the underlying data source for a domain, rule developers can provide business users with the flexibility to modify the domain from within the Decision Center without the need for IT support. And because adding a new domain value does not result in changes to service contracts, developers do not need to redeploy the rule service or change the service clients.
|Sample rule project||hello-rules.zip||63KB|
- IBM WebSphere Operational Decision Management V7.5 Information Center
- Making Better Decisions using WebSphere Operational Decision Management, IBM Redbook, Duncan Clark and Pierre Berlandier.
- developerWorks BPM zone: Get the latest technical resources on IBM BPM solutions, including downloads, demos, articles, tutorials, events, webcasts, and more.
- IBM BPM Journal: Get the latest articles and columns on BPM solutions in this quarterly journal, also available in both Kindle and PDF versions.