Governance sample details

Running this sample

Before running this sample, note that:

• autUser is an author user, whose job is to write rules

• revUser is a reviewer user, whose job is to review defined rules written by autUser

• tesUser is a tester user, whose job is to test reviewed rules

• depUser is a deployer user, whose job is to deploy rules

• admUser is an administrator user, whose job is to administrate the project

You run this sample using the following steps:

• Step 1: View project security settings

• Step 2: Manage a rule lifecycle

• Step 3: Control query actions

• Step 4: View rule status changes using RSS

First, you look at the current security settings for the user roles. This example uses the author role.

To view the current project security settings:

Step 1: View project security settings

1. Open a web browser and enter the following URL to access Decision Center: http://localhost:<PORT>/teamserver.

2. Sign in to Decision Center using the following details:

   Username: rtsAdmin

   Password: rtsAdmin

3. On the Home page, select loanvalidation-rules as the Project in use.

4. Click the Configure tab.

5. Click Edit Branch Security.

   Notice how Enforce and configure security for this branch is selected, and a number of groups are associated with this main branch of the project.

6. Click Cancel to return to the Configure tab.

7. In the Configure tab, click Edit Permissions.

8. Select author from the drop-down list and view the security settings for that role.

9. Sign out of Decision Center.

Next, you investigate how each user role processes rules at each stage of the rule lifecycle. You sign in as an author, a reviewer, a tester, a deployer, and an administrator.

To sign in as an author:

Step 2: Manage a rule lifecycle

1. Connect to Decision Center using the following URL: http://localhost:<PORT>/teamserver

2. Sign in to Decision Center using the following details:

   Username: autUser

   Password: autUser

3. On the Home page, select loanvalidation-rules as the Project in use.

4. Click the Explore tab.

   Notice that the author role has access only to the New Rules and Refused Rules smart folders.

5. Hover your mouse over New Rules smart folder and click the Details icon to access the Details page. Then click Edit or Delete.

   Notice that you cannot update or delete smart folders.

6. Click the Explore tab.

7. In the table, select the approval rule and click Edit.

8. In the Properties step, click the Status list box.

   Decision Center displays two values. These are the only transitions available for an author when a rule has a status of new.

9. Select Defined.

10. Type a comment in Status Comment.

11. Click Next.

    Notice that you can edit the contents of the rule.

12. Click Finish. The rule now has a status of Defined.

13. Click Edit, and then click the Properties step.

    Notice that the rule is now read-only.

14. Sign out of Decision Center.

To sign in as a reviewer with defined status:

1. Connect to Decision Center using the following URL: http://localhost:<PORT>/teamserver/

2. Sign in to Decision Center using the following details:

   Username: revUser

   Password: revUser

3. On the Home page, select loanvalidation-rules as the Project in use.

4. Click the Explore tab.

   Notice that the reviewer role has access to the Defined Rules, Deployed Rules, Deprecated Rules, and Inactive Rules smart folders.

5. Select the approval rule and click Edit.

6. In the Properties step, click the Status list box.

   Decision Center displays three values. These are the only transitions available for a reviewer when a rule has a status of Defined.

7. Select Reviewed.

8. Type a comment in Status Comment.

9. Click Next.

   Notice that you cannot edit the contents of the rule.

10. Click the Documentation step.

    You can enter data in this field because the reviewer role can update the documentation property when the status of the rule is Defined, Deprecated, or Inactive.

11. Click Finish. The rule now has a status of Reviewed.

12. Click the Edit button, and then click the Properties step.

    Notice that the rule properties are now read-only.

13. Click the Documentation step.

    Notice that the documentation property is now read only.

14. Click Cancel.

    On the Explore tab you notice that the approval rule is no longer displayed and Defined Rules is empty.

15. Sign out of Decision Center.

To sign in as a tester:

1. Connect to Decision Center using the following URL: http://localhost:<PORT>/teamserver/

2. Sign in to Decision Center using the following details:

   Username: tesUser

   Password: tesUser

3. On the Home page, select loanvalidation-rules as the Project in use.

4. Click the Explore tab.

   Notice that a tester can see only Reviewed Rules.

5. Select the approval rule and click Edit.

6. In the Properties step, click the Status list box.

   Decision Center displays three values. These are the only transitions available for a tester when a rule has a status of Reviewed.

7. Select Tested.

8. Enter a comment in Status Comment.

9. Click Next.

   Notice that you cannot edit the contents of the rule.

10. Click Finish. The rule now has a status of Tested.

11. Click the Edit button, and then click the Properties step.

    Notice that the rule properties are now read-only.

12. Click Cancel.

    In the Explore tab, notice that the approval rule is no longer displayed and Reviewed Rules is empty.

13. Sign out of Decision Center.

To sign in as a deployer:

1. Connect to Decision Center using the following URL: http://localhost:<PORT>/teamserver/

2. Sign in to Decision Center using the following details:

   Username: depUser

   Password: depUser

3. On the Home page, select loanvalidation-rules as the Project in use.

4. Click the Explore tab.

   Notice that as a deployer, you can see only Tested Rules.

5. Select the approval rule and click Edit.

6. In the Properties step, click the Status list box.

   Decision Center displays three values. These are the only transitions available for a deployer when a rule has a status of Tested.

7. Select Deployed.

8. Type a comment in Status Comment.

9. Click Next.

   Notice that you cannot edit the contents of the rule.

10. Click Finish. The rule now has a status of Deployed.

11. Click the Edit button, and then click the Properties step.

    Notice that the rule properties are now read-only.

12. Click Cancel.

    In the Explore tab, notice that the approval rule is no longer displayed and Tested Rules is empty.

13. Sign out of Decision Center.

To sign in as a reviewer with deployed rule status:

1. Connect to Decision Center using the following URL: http://localhost:<PORT>/teamserver/

2. Sign in to Decision Center using the following details:

   Username: revUser

   Password: revUser

3. On the Home page, select loanvalidation-rules as the Project in use.

4. Click the Explore tab.

5. Click Deployed Rules.

6. Select the approval rule, and then click Delete.

   Decision Center displays a message stating that you cannot delete the item because of its status, because reviewers can only delete rules that have a status of Deprecated or Inactive. To demonstrate this, change the status to Inactive and then try to delete the item again.

7. Click Back.

8. Select the approval rule and click Edit.

9. In the Properties step, set the Status to Inactive.

10. Click Finish.

11. Click Explore to return to the main page of the Explore tab.

12. Click the Inactive Rules smart folder.

13. Select the approval rule.

14. Click Delete, but do not confirm the deletion to keep the project clean.

    You notice that you can now delete this rule because it has a status of Inactive.

15. Sign out of Decision Center.

By going through each role, you have completed the rule approval lifecycle.

This sample also uses a special role: the administrator.

To sign in as the administrator:

1. Connect to Decision Center using the following URL: http://localhost:<PORT>/teamserver/

2. Sign in to Decision Center using the following details:

   Username: admUser

   Password: admUser

3. On the Home page, select loanvalidation-rules as the Project in use.

4. Click the Explore tab.

   Notice that an administrator can see all rule statuses: Defined, Deployed, Deprecated, Inactive, New, Refused, Reviewed, and Tested.

5. Click Inactive Rules. The approval rule is available.

6. Sign out of Decision Center.

Then, you look at the controls that restrict the actions that an author role can perform.

To control query actions:

Step 3: Control query actions

1. Connect to Decision Center using the following URL: http://localhost:<PORT>/teamserver/.

2. Sign in using the following details:

   Username: autUser

   Password: autUser

3. On the Home page, select loanvalidation-rules as the Project in use.

4. Click the Query tab.

5. Click New.

6. Create the following query:

   Find all business rules 
     [such that]
   Do
     set the status of each business rule to validated 

7. Click Run Query.

8. On the table displayed, select the approval rule.

9. Click Apply Actions.

   Decision Center displays the message Cannot apply actions : You cannot update this element, because as an author you cannot set the status to validated.

10. Sign out of Decision Center.

The sample generates RSS data whenever the status value changes, and makes it available from the web server. A URL pointing to the updated rule is attached to the RSS data so that the user can edit the rule directly.

Step 4: View rule status changes using RSS

• To display the RSS data, open your browser and enter the following URL:

  http://localhost:<PORT>/teamserver/RSSRawProvider.jsp?project=loanvalidation-rules

  The URL is built partially with information from the serverrulegovernance/data/server.properties file.

• You can use any RSS reader to subscribe to the RSS feeds. To view loanvalidation-rules, configure it to point to http://localhost:<PORT>/teamserver/RSSRawProvider.jsp?project=loanvalidation-rules.

Rebuilding and customizing this sample

To rebuild this sample, you compile the sample and modify the configuration file. You can also customize the sample.

To compile this sample, execute the build command in the samples console.

Modify the configuration file

1. Using a text editor, open the file <INSTALL_DIR>/teamserver/samples/serverrulegovernance/data/configuration.properties.

   The configuration syntax is fully explained in the configuration file.

2. Update and save the file.

3. If you have modified roles, status, or user configurations:

   1. In the samples console, execute the run.printprofiles command to print the application server roles configuration.

   2. Use the WebSphere® Application Server administration console to define the groups and users shown by the run.printprofiles command.

   3. Restart the server to apply the changes.

4. In the samples console, execute the run command to redeploy and reconfigure Decision Center.

Customize the sample

1. Modify the configuration file, as described earlier in this section.

2. To add a role:

   1. Locate the following line: roles = administrator;author;reviewer;deployer;tester

   2. Add the role newrole, as follows: roles = administrator;author;reviewer;deployer;tester;newrole

   3. In the samples console, execute the run.generatepermission command to generate default permission templates for all defined roles.

   4. Copy <INSTALL_DIR>/teamserver/samples/serverrulegovernance/newpermissions/newrole.permissions to:

      <INSTALL_DIR>/teamserver/samples/serverrulegovernance/data/permission/role.

   5. Remove the <INSTALL_DIR>/teamserver/samples/serverrulegovernance/newpermissions directory.

   6. Modify the newrole.permission file, as required.

3. To add a user newUser with 1 role (newrole):

   1. Locate the line user.XXXXX=YYYYY.

   2. Add the user newUser as follows: user.newUser=newrole.

4. To add a new status newstatus to the rules:

   1. Locate the line status.property.BusinessRule.status.values = new;defined ...

   2. Add the new status newstatus as follows:

      * status.property.BusinessRule.status.values = newstatus;new;defined...

5. To give a new role named newrole permissions to delete:

   1. Add the following line to grant permission to delete an item to any status value: BusinessRule.delete.newrole = *

   2. Add the following line to restrict the permission to delete an item to a status value of inactive or newstatus: BusinessRule.delete.reviewer = inactive;newstatus

6. To define the status for which a property can be updated for a new role named newrole:

   1. Add the following line to allow updates to any property, regardless of its status: BusinessRule.update.*.newrole = *

   2. Add the following line allow any updates to any property when its status is new: BusinessRule.update.*.newrole = new

   3. Add the following line to allow updates to a specific property when its status is newstatus: BusinessRule.update.XXXXX.newrole = newstatus

7. To define the initial status of a rule as newstatus, change the line transition.BusinessRule.status.initial...' to: transition.BusinessRule.status.initial = newstatus

8. To define the status transition for a given role (newrole), add the following line for each allowed transaction. Here, the newrole role is authorized to change the status from new to new, defined, or newstatus: transition.BusinessRule.status.newrole.new = new;defined;newstatus

How this sample works

In this sample, you manage the rule lifecycle of the loanvalidation-rules project. The data used for controlling the lifecycle is read from the <INSTALL_DIR>/teamserver/samples/serverrulegovernance/data/configuration.properties file.

To customize Decision Center and deploy it to the application server:

Install the custom controller

1. Execute the ant targets set-extensions and upload-messages of the build.xml.

   1. The set-extensions target modifies the Decision Center model. The status and statuscomment properties of the model manage the lifecycle of the rule. See extensionModel.brmx and extensionModel.brdx in <INSTALL_DIR>/teamserver/samples/serverrulegovernance/data/model/

   2. The upload-messages target adds a label to these properties which are displayed in the UI when editing the status or the statuscomment. See the file:

      <INSTALL_DIR>/teamserver/samples/serverrulegovernance/data/message/serverrulegovernance_en_US.properties

2. To deploy, execute the deploy command of the build.xml.

To configure the target project by executing the run.install command of build.xml:

Configure the target project (loanvalidation-rules)

1. Connect to Decision Center.

2. Create a group for each possible status value (newGroup, reviewedGroup, THE_STATUS_VALUEGroup) defined in the configuration file.

3. Create a smart folder for each possible status value.

   1. Syntax: Find all business rules such that the status of each business rule is THE_STATUS_VALUE.

   2. Group: THE_STATUS_VALUEGroup.

4. Create a group for each role defined in the configuration file.

5. Set the security for the target project to ON.

6. Assign all created groups to the target project.

7. Install permission reads from data/permission/ROLE_NAME.permissions.

8. Sign out of Decision Center.

When you start using Decision Center, the CustomController class is loaded and it reads the configuration file. The controller is now ready to manage the rule lifecycle, processed as follows:

Connect to Decision Center

• When you edit a rule, for each rule property, Decision Center calls IlrSessionController.checkUpdate(IlrElementHandle handle, IlrElementDetails details, EStructuralFeature feature). The property is read only when this method throws an IlrPermissionException, otherwise it is editable. You use getPossibleValues(IlrElementHandle element, org.eclipse.emf.ecore.EStructuralFeature feature) to return the list of possible values for the status.

• When you persist a modification after editing a rule:

  • Decision Center calls IlrSessionController.checkUpdate(IlrElementHandle handle, IlrElementDetails details, EStructuralFeature feature). For each property, the method verifies whether the property can be updated. This authorization depends on the user role and on the current status of the rule.

  • Decision Center calls IlrSessionController.onCommitElement(IlrCommitableObject cobject). This method prepares a modification event. If you had entered a comment, the comment is appended to the comment history of the rule.

  • The IlrSessionController.elementCommitted(IlrCommitableObject cobject,IlrElementHandle newHandle) method records the modification event when you modify the status of a rule. Otherwise, the method releases the event. The default implementation of a modification event consumer is an RSS feeder (NotificationListenerDefaultImpl class). This class translates a modification event into RSS entries.

• When you try to delete a rule, Decision Center calls IlrSessionController.checkDelete(IlrElementHandle element). The controller verifies that the delete operation is authorized. The authorization depends on the user role and on the current status of the rule. If the user is not authorized to delete, an IlrPermissionException is thrown.

• An RSS Reader requests the RSS raw data for a project, that is, the list of rules with a changed status.

  • The RSSRawProvider.jsp receives the request.

  • The JSP calls NotificationListenerDefaultImpl.getRSSStream(the project).

  • The getRSSStream (..) method returns all modification events recorded on the day as RSS raw data.

Source files

This sample is located in: <InstallDir>/teamserver/samples/serverrulegovernance/src/rulegovernance.

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.