Online documentation - WebsydianExpress v3.5

Using Authorized Events

Overview

The authorized events feature provides a way to use the role-based authorization system of WebsydianExpress for specific events (buttons/links) in your own business processes.

This document describes the use of the feature for a simple maintenance suite. The functionality of the feature itself is described in more detail in the basic background document:

Authorized events - basic information

The case

A company has a customer maintenance suite; this consists of the following pages and events:

Grid page
- Page Up
- Page Down
- Insert
- Search
- Update (Grid event)
- Delete (Grid event)
- View (Grid event)
Insert Page
- Insert
- Cancel
Update Page
- Update
- Cancel
Delete Page
- Delete
- Cancel
View Page
- Cancel

In the company's administration, it is important that everyone can view all information about the customers.

However, it is equally important that only account managers can update the information about the customers.

It is even more important to protect the delete functionality - as deleting a customer, who has any kind of an active relationship with the company, will cause big problems. This means that only the head of the administration or his designated substitute are allowed to delete customers.

So there are three different roles to consider:

Administrative user
Account manager
Customer relations manager

Based on the above, the events must be available as follows:

	Administrative User	Account Manager	Customer Relations Manager
GridPage / PageUp	x	x	x
GridPage / PageDown	x	x	x
GridPage / Insert		x	x
GridPage / Update		x	x
GridPage / Delete			x
GridPage / View	x	x	x
InsertPage / Insert		x	x
InsertPage / Cancel	x	x	x
UpdatePage / Update		x	x
UpdatePage / Cancel	x	x	x
DeletePage / Delete			x
DeletePage / Cancel	x	x	x
ViewPage / Cancel	x	x	x

Implementing the authorization check

Create roles

In most cases, appropriate roles will already exist. To keep the complexity of the site down, it is always a good idea to try to use existing roles if possible.

If any of the three roles does not exist, they must be created.

Assign roles to users

All administrative users must have the "Administrative User" role, the Account Managers must have the "Account Manager" role, while the head of customer relations and his designated substitute must have the "Customer Relations Manager" role.

Assign role to business process

Assign the "Administrative user" to the maintain customer business process.

This means that all administrative users will have access to the business process itself - and to all non-authorized events. This also means that the PageUp, PageDown, View and Cancel events should not be declared as authorized events.

Define authorized events

In the Plex model, specify the triples:

Source Object	Verb	Target Object
MaintainCustomers.GridPage.Insert	is a FNC	WSYAPI/Abstract.AuthorizedEventHandlerForProcess
MaintainCustomers.GridPage.Update	is a FNC	WSYAPI/Abstract.AuthorizedEventHandlerForProcess
MaintainCustomers.GridPage.Delete	is a FNC	WSYAPI/Abstract.AuthorizedEventHandlerForProcess
MaintainCustomers.InsertPage.Insert	is a FNC	WSYAPI/Abstract.AuthorizedEventHandlerForProcess
MaintainCustomers.UpdatePage.Update	is a FNC	WSYAPI/Abstract.AuthorizedEventHandlerForProcess
MaintainCustomers.DeletePage.Delete	is a FNC	WSYAPI/Abstract.AuthorizedEventHandlerForProcess

Generate and build these EventHandlers and the _DocumentTemplateGenerator functions for GridPage, InsertPage, UpdatePage, and DeletePage.

Change template

Creating new templates

If you do not have existing HTML templates for the pages used by the business process, you can just generate them using the template generator. This will insert the special replacement markers that is used to control whether the buttons are shown or not.

Changing existing templates

In many cases, you will be changing an existing business process. To avoid having to re-implement the design of the templates, you will normally not want to create new templates using the template generator.

In this case, you must insert the special replacement markers yourself.

Insert the following markers around the HTML-form of the event to protect:

/(%IFAUTHEVENT-[eventname])

...

/(%ENDIF)

By doing so, you will ensure that the PageGenerator does not generate any of the source between the /(%IFAUTHEVENT-...) and the /(%ENDIF) markers unless the session is authorized for the event specified by the implementation name of the EventHandler ([eventname] ).

So if the HTML form for the GridPage.Insert EventHandler has the implementation name CUSTINS and the following HTML representation in the template:

You must enclose it as follows:

It is important that you enclose the entire form element (from <form action...> to </form>) in the replacement markers, if you only enclose the button (the line: <P><INPUT TYPE="SUBMIT" NAME="Insert" VALUE="Insert" ></P>), the data necessary to generate the request will still be available on the page, and the creative user will be able to create the request himself (without being authorized for it).

In some cases the html-form and the button used to call the form are separated - in these cases it is important to enclose both the form and the button.

So if you have the following HTML code in your page (where the first line is a link that is shown as an image, which when pressed submits the insert form):

... (more HTML)

You must enclose both the link and the FORM in the special replacement markers - like this:

... (more HTML)

This must be done for each of the authorized events.

Define authorized events and their roles

In the administration interface, use the Site Structure→Authorized Events menu item to create entries for the 6 authorized events.

Note that the name specified for each event must be the implementation name of the EventHandler you want to authorize.

Assign roles to the events as follows:

MaintainCustomers.GridPage.Insert, MaintainCustomers.GridPage.Update, MaintainCustomers.InsertPage.Insert, MaintainCustomers.UpdatePage.Update:

Assign the Account Manager and the Customer Relations Manager roles.

MaintainCustomers.GridPage.Delete, MaintainCustomers.DeletePage.Delete:

Assign the Customer Relations Manager roles.

Deploy

Deploy the generated EventHandlers and the new templates.

Restart the WebsydianExpress application services.