Workflow Engine rule governance sample details

Running this sample

In this sample, when you complete certain tasks, the Workflow Engine sends an email to the user who completes the next task in the Workflow Instance. This email is the start of the next step in the Workflow Instance. It contains a list of permanent links to the rules that you update, validate, or deploy in the task.

CAUTION:

The email process is virtualized in this sample. The Samples console displays a message indicating that the email is sent, and prints the contents of the email to a file. To read this email, use your browser to open the generated file.

Run this sample in the following sequence to illustrate the Workflow Instance:

Create and initiate a Workflow Instance
Associate rules with a Workflow Instance
Update or delete rules attached to a Workflow Instance
Verify the work of a policy manager
Fix errors identified by a business analyst
Verify rule fixes
Test updated rules
Deploy a ruleset
Detach a rule from a Workflow Instance

Tip:

Use the following step-by-step description to complete the creation task in this sample. For more information, see the Steps in the Workflow Model.

Create and initiate a Workflow Instance

To create a new Workflow Instance:

Open a Web browser and enter the following URL to access Decision Center:

http://localhost:<PORT>/teamserver/
Sign in to Decision Center as the configuration manager using the following details:
- User: rtsAdmin
- Password: rtsAdmin
Select the loanvalidation-rules project.
Click the Workflow tab.
Click Workflow Models.
Click New.

This creates a new Workflow Instance from the Workflow Model. Your browser is redirected to the Workflow Instance page automatically.
In the Name column of the Workflow Instance table, change the Workflow Instance name to myupdate.
Click Save to save your changes.
Click Preview to edit the Workflow Instance.
The business analyst tells the policy manager to delete a rule that is no longer used and update the default insurance rate from 0.02 to 0.04.

To do this, add the following to the Comment field:

Update the defaultInsurance rule to the new rate of 0.04.

When a person borrows more than a certain amount, insurance is required by the lender. This rule sets the insurance rate for such a loan.

Delete the checkSSNareanumber rule. We no longer check the SSN Number.
Click Save.

Decision Center has added the comments to the comments history. To view them in the Details section, select Comments History.
Click the Tasks tab and click Refresh.

You see that Decision Center has created and assigned a task to the business analyst. Note that this task is created when the workflow instance is created.

After you have created a Workflow Instance, you select items of the Details list at the bottom of the Workflow Instance page to view status information about the current Workflow Instance.

The Details list for the myupdate Workflow Instance contains the following information:

Detail list item	Description
Process Graph	The process graph opens. The progress icon shows the Workflow Instance is in the creation step.
Comments History	The comments added to the process and the name of the user who added the comment.
Tasks History	A list of the tasks created. At this stage, no tasks are created in the Workflow Instance.
Logs History	Displays the contents of the single log file that traces the creation of this Workflow Instance.

You now associate the rules with a Workflow Instance. In this step, the business analyst first creates a simple query which lists all the rules in the Decision Center, and then uses the result of this query to attach rules to a Workflow Instance.

Associate rules with a Workflow Instance

To create a basic query:

Select the loanvalidation-rules project.
Click the Query tab.
Create a new query called All Rules with the following definition:

Find all business rules
Click Save.
Click Run Query.

Decision Center displays the results of the All Rules query.

The business analyst now associates rules from the list with the Workflow Instance.

Select the checkSSNareanumber and defaultInsurance rules from the query list.
Click Add in the toolbar.

Decision Center attaches the rules that you selected to the myupdate Workflow Instance.
Click the Workflow tab.

You see the rules that you added.

Note:
To remove a rule from a Workflow Instance, click the remove icon in the toolbar.
Select the To Delete check box next to the checkSSNareanumber rule.
Click Save.

Decision Center creates one update task and one delete task for the policy manager.
Click the Tasks tab.
Click Apply in the Decision column to end this task.

The task ends for the business analyst and the workflow creates tasks for the policy manager.

Note:
In this sample, the policy manager is the Decision Center user that can update and delete tasks.
Click Sign Out in the upper corner of Decision Center.

After you have created a Workflow Instance, and initiated and associated rules with it, the policy manager receives an email from the Workflow Engine indicating that you have assigned them an update task. The policy manager uses the comments defined in the Create and initiate a Workflow Instance section to complete update or delete tasks.

Use the following step-by-step description to complete the update task in this sample. For more information, see the Steps in the Workflow Model.

Update or delete rules attached to a Workflow Instance

To update or delete the rules in this task:

Open a web browser and enter the following URL to access Decision Center:

http://localhost:<PORT>/teamserver/
Sign in to Decision Center as a policy manager using the following details:
- User: rtsUser1
- Password: rtsUser1
Select the loanvalidation-rules project.
Click the Tasks tab.

Two tasks are visible in the Desc. column of the task list. Both tasks are in plain text because the policy manager has not started them.
Select the check boxes in the first column for both of these tasks.
Click the start button in the toolbar.

The policy manager is the owner of the tasks, and the task description links are enabled.
Click Delete Rule : checkSSNareanumber.
Click Delete in the toolbar, and then click Yes to confirm the command.
Click the Tasks tab.
Click Apply in the Decision column for the Delete Rule task.

The task is removed from the list.
Click Update Rule : defaultInsurance.
Click Edit in the toolbar.
In the Compose tab, click Step 2: Content, and then change the rate from 0.02 to 0.05, and then click Finish.

Note:
In this step you create an error intentionally to see what happens when a rule update is rejected later in the Workflow Instance.
Click the Tasks tab, and then click Apply for the Update Rule task.

The task is removed from the list.
Click Sign Out in the upper corner of Decision Center.

Verify the work of a policy manager

To verify the work of a policy manager and start all tasks at the same time:

Open a Web browser and enter the following URL to access Decision Center:

http://localhost:<PORT>/teamserver/
Sign in to Decision Center as a business analyst using the following details:
- User: rtsAdmin
- Password: rtsAdmin
Ensure that loanvalidation-rules is the project in use.
Accept the delete task completed by the policy manager in 3. To do this:
1. Click the Tasks tab.
2. Select all tasks, and then click Start.
  
  By selecting all tasks and clicking start, all tasks are started at the same time. You can also select and start tasks one by one.
3. Click Check the rule: checkSSNareanumber.
  
  Decision Center displays the following error message: Cannot select item : The specified element was not found. This is the expected result, because Decision Center has deleted this rule.
4. Click Back.
5. In the Check the rule: checkSSNareanumber row, select End in the Decision drop-down list, and click Apply to end the task.
  
  The Workflow Engine sets the status for this task to Approved.
Reject the update task completed by the policy manager in 3. To do this:
1. Click Check the rule : defaultInsurance.
  
  The content definition shows the rate is set to 0.05 instead of the 0.04 requested in 1. You reject the work done by the policy manager.
2. Click the Workflow tab, and then click Workflow Instances.
3. Click the preview button for the myupdate task.
4. Add the following in the Comment field:
  
  Change incorrect. Set to 0.04 and not 0.05.
5. Click Save.
6. Click the Tasks tab, select Error in the Decision drop-down list, and click Apply to reject the task.
  
  The Workflow Engine sets the status property for the rule to Rejected.
Click Sign Out in the upper corner of Decision Center.

The policy manager fixes the errors that the business manager identified.

Use the following step-by-step description to complete the update task in this sample. For more information, see the Steps in the Workflow Model.

Fix errors identified by a business analyst

To fix errors identified previously:

Open a web browser and enter the following URL to access Decision Center:

http://localhost:<PORT>/teamserver/
Sign in to Decision Center as a policy manager using the following details:
- User: rtsUser1
- Password: rtsUser1
Ensure that loanvalidation-rules is the project in use.
Click the Tasks tab.
Click Apply to start the task.
Click Fix tasks : defaultInsurance.
Change the rate in the rule to 0.04.
Click the Tasks tab.
Select End in the Decision drop-down list, and click Apply to end the task.

Decision Center sets this task as Completed.
Click Sign Out in the upper corner of Decision Center.

The business analyst now verifies the work done by the policy manager. In this section, you assume that the business analyst considers the fix to be correct and ends the task.

Use the following step-by-step description to complete the validation task in this sample. For more information, see the Steps in the Workflow Model.

Verify rule fixes

To verify rule fixes:

Open a web browser and enter the following URL to access Decision Center:

http://localhost:<PORT>/teamserver/
Sign in to Decision Center as a policy manager using the following details:
- User: rtsAdmin
- Password: rtsAdmin
Ensure that loanvalidation-rules is the project in use.
Click the Tasks tab.
Click Apply to start the task.
Click Check the rule : defaultInsurance.
Validate the rule rate is 0.04.
Click the Tasks tab, and then click Apply to end the task.
Select End in the Decision drop-down list, and click Apply to end the task.

Decision Center sets this task as Approved.
Click Sign Out in the upper corner of Decision Center.

In this step, you assume that the issue found by the developer in testing updated rules is corrected by the policy manager and the fix is approved by the business analyst.

Use the following step-by-step description to complete the test task in this sample. For more information, see the Steps in the Workflow Model.

Test updated rules

To test and approve an updated rule:

Open a web browser and enter the following URL to access Decision Center:

http://localhost:<PORT>/teamserver/
Sign in to Decision Center as a developer using the following details:
- User: tesUser
- Password: tesUser
Select the loanvalidation-rules project.
Click the Tasks tab, and then click Apply to start the task.

The developer tests the changes to the rule, and then terminates the task.
Select End from the Decision drop-down list, and click Apply to end the Test the rules task.

The Workflow Engine sets the status property of the rule to Deployable and the developer has the task Deploy the ruleset.

You can now deploy the ruleset. In this step, you assume that the developer deploys the updated rules in the context of the Workflow Instance tasks.

Here you assume that a new ruleset is generated and deployed to Rule Execution Server. For more information, see the Steps in the Workflow Model.

Deploy a ruleset

To update the task:

Click Apply to end the Deploy the ruleset task.

The Workflow Engine sets the status property to Deployed.
Click Sign Out in the upper corner of Decision Center.

After all tasks are complete, the business analyst must terminate the Workflow Instance and remove the rules from the control of the Workflow Engine.

Use the following step-by-step description to perform the completion task in this sample. For more information, see the workflow diagram.

Detach a rule from a Workflow Instance

To detach rules from the Workflow Instance:

Open a web browser and enter the following URL to access Decision Center:

http://localhost:<PORT>/teamserver/
Sign in to Decision Center as a business analyst using the following details:
- User: rtsAdmin
- Password: rtsAdmin
Ensure that loanvalidation-rules is the project in use.
Click the Tasks tab, and then click Apply to end the task.
To validate that all rules have been detached, run the All Rule query created previously.

The defaultInsurance rule is no longer attached to a Workflow Instance, and the Process Id and Process Instance values are no longer set.

Rebuilding this sample

To rebuild this sample:

In the Samples Commands view, navigate to Samples Commands > Decision Center > Workflow Engine rule governance.
Execute the build command to recompile the code.

How this sample works

This sample uses:

An implementation of a wrapper around a Workflow Engine.
A customized Decision Center user interface.
A Workflow Model that defines the business process.
A custom code that uses the Decision Center API which responds to tasks in the Workflow Instance.

The Workflow Engine receives commands from the custom UI, and checks whether the command is valid for the current step and task. If the command is valid, the Workflow Engine calls the Java™ method designated by the Workflow Model and moves to the next task in the Workflow methods. The methods called use the Decision Center API to lock or unlock the rules attached to the Workflow Instance and inform the user who completes the next task.

The Decision Center data model is customized to add the following attributes:

owner: The user that can update the rule status.
processInstanceName: The process name to which the rule is attached.
processInstanceId: The process id to which the rule is attached.

The XML files contained in <InstallDir>/teamserver/samples/serverworkflow/data/process/osworkflow/Sample.xml define the steps in a Workflow Model. This sample uses the OSWorkflow workflow engine. For more information about how to design a process, see the OSWorkflow documentation.

For this sample, the business process describes the update, testing, and deployment of rules attached to a Workflow Instance in Decision Center. Each rule has a status to indicate the progression of the Workflow Instance to which it is attached. The Workflow Instance controls the interactions between three actors: a business analyst, a policy manager, and a developer. Actors can edit only rules attached to a Workflow Instance when a task is assigned to them. The process updates the rule status automatically whenever it moves from step to step.

The Workflow Model for this sample implements the following scenario:

Business analysts can attach or detach rules in a Workflow Instance.
You can update or delete only rules attached to a Workflow Instance.
Policy managers can update and delete only rules that they own.
You cannot associate a rule attached to one Workflow Instance with other Workflow Instances simultaneously.
Decision Center logs each task that you complete in the Workflow Instance and you can view the task.
The Workflow Engine manages the state of rules attached to the Workflow Instance, that is, the current owner and the status of the rule.

When you deploy this sample, the process uploads a Workflow Model that implements the scenario, to Decision Center. For information about how to upload a Workflow Model, see the list of useful procedures at the end of this topic.

The following figure shows the steps defined in the Workflow Model for this sample and the actor who works on each step:

At any time in a Workflow Instance, you can view a graph showing the status of a particular Workflow Instance, that is, the history of the tasks, comments, and actions that have occurred in the Workflow Instance.

The following table explains the steps in the Workflow Model in greater detail:

Table 1. Steps in the Workflow Model
Step overview	Step tasks
The business analyst creates a Workflow Instance in Decision Center and attaches rules to it.	The business analyst takes the following steps: Creation step tasks Creates a new Workflow Instance from a Workflow Model. Gives a name and a short description to the Workflow Instance. Adds comments to the Workflow Instance that describe the work that is required. Attaches rules to the Workflow Instance using the Explore or the Query pages. When this step is complete, the Workflow Engine: Sets the status of the rules to Assigned. Selects the policy manager completes the update tasks. Assigns the update tasks to a policy manager and sends an email that lists the tasks that are assigned. Note: Until the first business analyst task (Add rules to the Workflow Instance) is complete, the business analyst can add or remove rules to the workflow instance.
The policy manager updates or deletes the rules attached to the Workflow Instance.	The policy manager receives an email from the Workflow Engine, and then: Update step tasks Navigates to the tasks attached to the Workflow Instance using the permanent links in the task description email. Starts the tasks. Updates or deletes the rules attached to the Workflow Instance. Ends this task. Attention: In this sample, the email process is virtualized. The samples console displays message indicating that the email is sent and prints the content of the email to a file. To read this email, use your browser to open the file generated. When the policy manager completes all the tasks, the Workflow Engine: Sends an email to the business analyst requesting verification of the work done by the policy manager. The Workflow Engine the status of the rules to Defined. Creates a task to verify each rule attached to the Workflow Instance. The Workflow Engine assigns these verification tasks to the business analyst.
The business analyst validates or rejects work done by the policy manager.	The business analyst receives an email from the Workflow Engine, and then: Validation step tasks Navigates to the tasks attached to the Workflow Instance using the permanent links in the task description email. Note: When the business analyst clicks the link for a rule that was deleted previously, Decision Center displays an error message. Validates the work done by the policy manager: If the work done on a rule is correct: The business analyst completes the task by setting it to End. The Workflow Engine sets the task status to Validated. If the work done is incorrect: The business analyst rejects the rule and adds a comment to the Workflow Instance explaining the issues found. The Workflow Engine creates a task for the policy manager, and then sets the status of the rule to Rejected. No status is set for a deleted rule. The Workflow Engine creates an update task for the rules attached to the Workflow Instance. When all rules are correct, the Workflow Engine: Assigns a task to the developer. Sends an email to the developer requesting testing of the ruleset which includes the rules modified by the policy manager.
The developer tests the rules altered in previous steps.	The developer receives an email from the Workflow Engine, and then: Test step tasks Navigates to the tasks attached to the Workflow Instance using the permanent links in the task description email. Tests the rules: If the rules fail: The developer selects the rules that failed the tests. The Workflow Engine creates an update task for each failed rule in the Workflow Instance. The developer adds a comment to the Workflow Instance explaining the issue found. If the rules pass: The developer ends the task. When all the rules have passed the tests, the Workflow Engine: Assigns a new deployment task to the developer. Sets the status of the rules attached to the Workflow Instance to Deployable.
A developer deploys the updated ruleset.	The developer: Deployment step tasks Navigates to the tasks attached to the Workflow Instance using the permanent links in the task description email. Note that the task is started automatically. Deploys the new ruleset. Ends the tasks. When the task has ended, the Workflow Engine: Sends an email to the business analyst explaining that the new version of the ruleset is deployed. Sets the status of the rules attached to the Workflow Instance to Deployed. Creates a new task for the business analyst to end this Workflow Instance.
Business Analyst completes the Workflow Instance.	The business analyst receives an email from the Workflow Engine, and then: Completion step tasks Navigates to the tasks attached to the Workflow Instance using the permanent links in the task description email. Sets the Workflow Instance to End.

The following figure shows the status of the Workflow Instance for this sample:

The software layer that controls the graphical user interface (GUI) in this sample uses JSF beans. The layer is independent of the base business process management (BPM) engine implementation. All JSF beans interact with the ilog.rules.sample.rts.workflow.BPMEngine interface. The BPM implementation referenced by this sample is loaded at runtime by the ilog.rules.sample.rts.workflow.EngineService factory class.

The following figure shows the relationship between the different layers of this sample:

The relationship between the sample and third party technologies.

This sample uses the open source OSWORKFLOW engine. The BPM functionality is packaged in a Java library. This library includes a service to manage and execute processes.

To configure this sample:

Workflow Instance configuration

The configuration files for the current BPM engine are located here: <InstallDir>/teamserver/samples/serverworkflow/data/config/osworkflow. See the OSWORKFLOW documentation for more information about configurations.
To add and update new Workflow Instances:
- The Workflow Model is located here: <InstallDir>/teamserver/samples/serverworkflow/data/process/osworkflw/. For more information about OSWORKFLOW configuration process refer to the OSWORKFLOW documentation.
- You edit the Workflow Model with the OSWORKFLOW Designer.
To understand how to upload a process, see the list of useful procedures at the end of this topic.

Note:

This sample does not manage transactions between the Decision Center database and OSWORKFLOW database. You must adapt the sample or use another BPM Engine to implement this feature.

To modify or create a process of this sample:

Use the OSWORKFLOW Designer to modify or create it.
Create or modify the Java classes you require.
Upload the process.
Redeploy the Java classes to Decision Center.

To use another BPM Engine:

Implement a class implementing the ilog.rules.sample.rts.workflow.BPMEngine interface.

This class is the glue between Decision Center and the BPM Engine
Create a process with the tools coming along with the BPM engine.
Develop all Java classes required by the workflow model.
Redeploy the process and the Java classes.

All Decision Center project elements include additional information referred to as their properties. You can customize or extend rule projects to capture information specific to your company business domain. For this Workflow Engine sample, the Decision Center model is extended to with two new properties:

Table 2. Decision Center model customization
Property name	Description
`processInstanceName`	The name of the Workflow Instance to which a rule is attached.
`processInstanceId`	The ID of the Workflow Instance to which a rule is attached.

Decision Center is a JSF based application. Use the items in the following list to customize different graphical aspects of Decision Center:

Decision Center GUI customization

To configure JSF Bean declarations and String navigation, see:

<InstallDir>/teamserver/samples/serverworkflow/WebContent/WEB-INF/extended-faces-config.xml
To add tabs to the Decision Center main page, see:

<InstallDir>/teamserver/samples/serverworkflow/WebContent/custom/tabs.jsp
To include the Add button and drop-down list to the toolbar, see:

<InstallDir>/teamserver/samples/serverworkflow/WebContent/custom/tableToolbar.jsp
To add the Workflow Model tab to the Decision Center main page, see:

<InstallDir>/teamserver/samples/serverworkflow/WebContent/custom/extensions/processdefinitionpage.jsp
To add the Workflow Instance tab to the Decision Center main page, see:

<InstallDir>/teamserver/samples/serverworkflow/WebContent/custom/extensions/processinstancepage.jsp
To add the Tasks tab to the Decision Center main page, see:

<InstallDir>/teamserver/samples/serverworkflow/WebContent/custom/extensions/taskspage.jsp
To add the Workflow Instance management button to the Admin page, see:

<InstallDir>/teamserver/samples/serverworkflow/WebContent/custom/admin.jsp
To add the Workflow Instance management page to the Admin page, see:

<InstallDir>/teamserver/samples/serverworkflow/WebContent/configure/workflowpage.jsp

Useful procedures that are not used in this sample

This section lists small but useful procedures that are not used in this sample.

After you have created a Workflow Instance, you can select different members of the Details list at the bottom of the Workflow Instance page to view status information about the current Workflow Instance.

To view the activities of a Workflow Instance:
1. In Decision Center, select the workflow Instance.
2. Select Process Graph in the Details list to view where the current step of the workflow instance is.
3. Select Comments History in the Details list to view all comments added since the beginning of the workflow instance.
4. Select Tasks History in the Details list to view all tasks done or not done.
5. Select Logs History in the Details list to view all steps executed done since the beginning of the workflow instance.
To re-create the Workflow Engine database schema:
1. Open a web browser and enter the following URL to access Decision Center:
  
  http://localhost:<PORT>/teamserver/
2. Sign in to Decision Center as a business analyst using the following details:
  - User: rtsAdmin
  - Password: rtsAdmin
3. Select the loanvalidation-rules project.
4. Click the Configure tab.
5. In the Sample section, click Workflow Management Sample.
6. Click Create Database Schema, and then wait until Database successfully created displays on the page.
After the database schema is created, you add Workflow Models to the database. This is explained in the next list item.
A business process is a collection of related, structured activities that produce a service or product. A Workflow Model is a formal description of a business process. To initiate a custom Workflow Instance, you must upload the Workflow Model to the database.

To upload the sample Workflow Model to the database:
1. Open a web browser and enter the following URL to access Decision Center:
  
  http://localhost:<PORT>/teamserver/
2. Sign in to Decision Center as a business analyst using the following details:
  - User: rtsAdmin
  - Password: rtsAdmin
3. Select the loanvalidation-rules project.
4. Click the Configure tab.
5. In the Sample section, click Workflow Management Sample.
6. Click Browse and select the following files:
  - Definition: <InstallDir>/teamserver/samples/serverworkflow/data/process/osworkflow/Sample.xml
  - Graph: <InstallDir>/teamserver/samples/serverworkflow/data/process/osworkflow/Sample.lyt
  - Image: <InstallDir>/teamserver/samples/serverworkflow/data/process/osworkflow/Sample.png
7. Click Upload, and then wait until Process sucessfully uploaded displays on the page.
8. Click the Workflow Model tab.
9. Click Workflow Models.
  
  A process policy change is listed.

Source files

This sample is located in <InstallDir>/teamserver/samples/serverworkflow/src/ilog/rules/sample/rts.

You can also view and modify the sample source files in Rule Designer. To import the sample into your workspace, click the Import projects link in the Samples and Tutorials view, and switch to the Java perspective.