Creating a Self Registration Business Process

• Overview
• Description of process
• Create ProcessEntryPoint
• Create PageGenerator
• Create EventHandler
• Enter action diagram code in the ProcessEntryPoint
• Enter action diagram code in the EventHandler
• Generate and build
• Run template generators
• Deploy objects
• Define process

Overview

It is quite common in web applications that users are allowed to register themselves as registered users.

This feature is desirable because if users could not register automatically, then it could potentially create a huge workload for the administrator that had to register the users manually, and it would be inconvenient for the users (having to wait for an administrator to create the profile before gaining access to the site).

The most common solution for this, is to provide functionality, where the user can enter the necessary data to create the user account and confirm the account creation by pressing a button.

This guide will describe the steps necessary to create a business process with this functionality.

Description of process

Self registration functions can be made in many different ways. This guide only describes one type. However, by understanding the functionality of this version, it should be possible to understand which changes to make to get the exact functionality you need for your own application.

The process will contain a page with one button. The page will contain the input fields necessary to create a Websydian Express user account.

After a user has registered, he is automatically logged into the system.

All of the specified function names etc. are just examples and can be changed to fit to the application.

Create ProcessEntryPoint

Any business process used in Websydian Express must have a ProcessEntryPoint function defined. It is the implementation name of this function that is used when registering the business process in the Websydian Express administration interface.

Enter the following triples to define the ProcessEntryPoint function:

Source Object	Verb	Target Object
SelfRegister	is a FNC	WSYAPI/ProcessEntryPoint
	implement SYS	Yes
	impl name NME	REGISTER
	file name NME	REGISTER

Create PageGenerator

A Registration Page where the user can enter the information needed to create the user account must be defined.

The user might not always enter the correct values. If the validation returns any errors, the Registration Page will be reloaded with the error messages displayed as well as the previously entered values.

To make this possible the PageGenerator function must inherit from PageGeneratorErrorListForProcess and the input fields must be added to the WsyDetails variable.

Source Object	Verb	Target Object
SelfRegister	includes FNC	RegisterPage
SelfRegister.RegisterPage	is a FNC	WSYAPI/Abstract.PageGeneratorErrorListForProcess
	local FLD ...for VAR	WSYAPI/APIFields.LoginName
		WsyDetails
	local FLD ...for VAR	WSYAPI/APIFields.UserPassword
		WsyDetails
	local FLD ...for VAR	WSYAPI/APIFields.FullName
		WsyDetails
	local FLD ...for VAR	WSYAPI/APIFields.EmailAddress
		WsyDetails
	implement SYS	Yes
	impl name NME	REGPAGE
	filename NME	REGPAGE
SelfRegister.RegisterPage. _DocumentTemplateGenerator	implement SYS	Yes

Create EventHandler

The Registration Page will contain one html form where the user can specify the necessary information for creating a user account.

The EventHandler function for the form will validate the input, and if the validation is successful, the user account will be created.

To define the EventHandler function enter the following triples:

Source Object	Verb	Target Object
SelfRegister.RegisterPage	includes FNC	Register
SelfRegister.RegisterPage.Register	is a FNC	WSYAPI/EventHandlerForProcess
	implement SYS	Yes
	local FLD ...for VAR	WSYAPI/APIFields.LoginName
		WebInput
	local FLD ...for VAR	WSYAPI/APIFields.UserPassword
		WebInput
	local FLD ...for VAR	WSYAPI/APIFields.FullName
		WebInput
	local FLD ...for VAR	WSYAPI/APIFields.EmailAddress
		WebInput
	replaces FNC ...by FNC	WSYAPI/ErrorPageForProcess
		SelfRegister.RegisterPage
	local FLD ...for VAR	WSYAP/APIFields.UserFolderListID
		InputForInsert
	local FLD ...for VAR	WSYAP/APIFields.UserSitekey
		InputForInsert
	local FLD ...for VAR	WSYUSER/UserStatus
		InputForInsert
	local FLD ...for VAR	WSYAPI/APIFields.CrtByUserSgt
		InputForInsert
	variable VAR ...as SYS	InputForInsert
		Local
	local FLD ...for VAR	WSYAPI/APIFields.NumberOfErrors
		Local
SelfRegister.RegisterPage. _DocumentTemplateGenerator.Register	implement SYS	No

The fields specified for the WebInput variable is needed to create the user account in the Websydian Express database. If you need further information about the user for your own application, add these fields to WebInput.

Enter Action Diagram Code in the ProcessEntryPoint

The PageGenerator function for the Registration Page must be called from the ProcessEntryPoint function. Doing this means that the Registration Page will be shown when the business process is called.

Open the ProcessEntryPoint function SelfRegister and insert the following code:

Post point "Call to first PageGenerator":

Call SelfRegister.RegisterPage

// Map <ErrorMode.*No>

Enter Action Diagram code in the EventHandler

Set parameter mapping on call to error page (SelfRegister.RegisterPage):

Open the action diagram for SelfRegister.RegisterPage.Register.

Go to the subroutine "Error handler".

Double-click on the call to the page SelfRegister.RegisterPage and map with <ErrorMode.*Yes>.

Set default values

Before handling the request, certain default values must be set for the fields UserFolderListID, UserSiteKey, UserStatus, CrtByUserSgt, and UserAuthLevel found in the variable InputForInsert:

• UserFolderListID will typically be blank (the folder list for the user's sessions will be decided by the authorization of the user).
• UserSiteKey must be the same as for the current session.
• UserStatus must be Active (unless you want to have an administrator activate the account before accepting request from the user).
• CrtByUsrSgt is the unique identification of the user creating the new profile - it is meaningless in this context - and is set to *Zero.

Insert the following code to set the default values.

Post Point "0 Process of input"

Set InputForInsert<APIFields.UserFolderListID> = <APIFields.UserFolderListID.*Blank>

Set InputForInsert<APIFields.UserSitekey> = APIServer.GetBasicSessionData/Output<APIFields.SiteKey>

Set InputForInsert<UserStatus> = <UserStatus.Active>

Set InputForInsert<APIFields.CrtByUserSgt> = <APIFields.CrtByUserSgt.*Zero>

Create sub routines

Create the following subroutines:

Post Point "Subroutines"

Sub Validate user

Sub Create user

Sub Assign role

Sub Change session data

Enter the following code in Post Point "0 Process of input" - after the assignment of the default values:

Go Sub Validate user

If WsyBase<InstanceValid> == <InstanceValid.*Yes>

    Go Sub Create user

    Call WSYAPI/APIWebServer.ReloadSitePageGenerator

Else

    Go Sub Error handler

The ReloadSitePageGenerator reloads the site based on the current session settings (see more detail below).

To make the ReloadSitePageGenerator work, you need to ensure that the WSLOAD template file is present in a folder in the folder list that will be used.

Validate request

When a user presses the Register button, the entered data must be validated.

If the validation fails, the errors returned by the validation function must be shown to the user so the user can correct the entered data.

If the validation succeeds the database must be updated with the entered values.

The validation is done by calling the API APIWebServer.UserCreateValidation.

This API only validates whether the entered data are correct and does not update the Express user table.

If you have added your own input fields (additional information you want to obtain for the user) you should also do your own validation of these fields.

 

Subroutine "Validate user"

Set WsyBase<InstanceValid> = <InstanceValid.*Yes>

Call WSYAPI/APIWebServer.UserCreateValidation

//Map with Webinput

//Map with InputForInsert

Case

    When Environment<*Call status> != <*Call status.*Normal>

        Set WsyBase<InstanceValid> = <InstanceValid.*No>

        Name Function: WSYAPI/APIWebServer.UserCreateValidation,
            Environment<*Object>, .Scoped

        Format Message Message: FIELDS/FunctionCallFailed,
            Environment<*Message text>

        //Map with Environment

        Go Sub Send message

    When Environment<*Returned status> != <*Returned status.*Successful>

        Set WsyBase<InstanceValid> = <InstanceValid.*No>

        Set Local<APIFields.NumberOfErrors> = <APIFields.NumberOfErrors.*Zero>

        While Local<APIFields.NumberOfErrors> << Error<APIFields.NumberOfErrors>

            Set Local<APIFields.NumberOfErrors> = Local<APIFields.NumberOfErrors>
                + <APIFields.NumberOfErrors.*One>

            Use ErrorArray, Local<APIFields.NumberOfErrors>

            Cast Environment<*Message text>, ErrorArray<ErrorMessage>

            Go Sub Send message

After this code enter your own validation (if any is relevant). For each error you encounter, do the following:

• Set WsyBase<InstanceValid> to *No. This ensures that the update is not attempted and that the error page is called.
• Populate Environment<*Message text> with a suitable error message.
• Call the subroutine "Send message".

Create user

Insert the following code to create the user account.

Subroutine "Create user"

Call WSYAPI/APIWebServer.UserCreate

// Map WebInput

// Map InputForInsert

Case

    When Environment<*Call status> != <*Call status.*Normal>

        Set WsyBase<InstanceValid> = <InstanceValid.*No>

        Name Function: WSYAPI/APIWebServer.UserCreate,
            Environment<*Object>, .Scoped

        Format Message Message: FIELDS/FunctionCallFailed,
            Environment<*Message text>

        Go Sub Send message

    When Environment<*Returned status> != <*Returned status.*Successful>

        Set WsyBase<InstanceValid> = <InstanceValid.*No>

        Set Local<APIFields.NumberOfErrors> = <APIFields.NumberOfErrors.*Zero>

        While Local<APIFields.NumberOfErrors> <<
            APIWebServer.UserCreate/Error<APIFields.NumberOfErrors>

            Set Local<APIFields.NumberOfErrors> = Local<APIFields.NumberOfErrors>
                + <APIFields.NumberOfErrors.*One>

            Use APIWebServer.UserCreate/ErrorArray,
                Local<APIFields.NumberOfErrors>

            Cast Environment<*Message text>,
                APIWebServer.UserCreate/ErrorArray<ErrorMessage>

            Go Sub Send message

If WsyBase<InstanceValid> == <InstanceValid.*Yes>

    Comment Enter your own user creation here

    Go Sub Assign role

    Go Sub Change session data

Else

    Go Sub Error handler

Enter your own user creation where it is indicated by the comment.

Assign role

All Websydian Express users must have at least one role - or they will not be able to access the site. You can choose to assign all of the roles that the user should finally have at this point or you can make a special role for self registered users if you want to limit the access of the self registered users to specific parts of the site.

In most cases you will want to store information about which roles to assign to the user in a database table for easy maintenance - but to keep the example simple, only one role will be assigned to the user - and the name of this role will be stored as a literal for a value belonging to a Plex field.

To do this, a field with a value is created, the name of the role is specified as the literal for the value and the field is added to the EventHandler function as a local field:

Source Object	Verb	Target Object
MyRoleName	is a FLD	WSYAPI/APIFields.RoleName
	value VAL	User
SelfRegister.RegisterPage.Register	local FLD ...for	MyRoleName
		Local

Enter "User" as the literal of the value - if you want to assign another role to the user, enter the name of this role as the literal of the User value.

It is necessary to handle the case where the specified role does not exist - to be able to do this, a message is created:

Source Object	Verb	Target Object
SelfRegister.RegisterPage.Register	message MSG	Role Not Found
SelfRegister.RegisterPage.Register.Role Not Found	parameter FLD	MyRoleName

Specify the following text for the message:

    The role &(1:) does not exist.

 

Enter the following code in subroutine "Assign role":

Set Local<MyRoleName> = <MyRoleName.User>

Call WSYAPI/APIServer.Role.GetByName

//Map with Local<MyRoleName>

//Map with APIServer.GetBasicSessionData/Output<APIFields.SiteKey>

Case

    When Environment<*Call status> != <*Call status.*Normal>

        Name Function: WSYAPI/APIServer.Role.GetByName, Environment<*Object>, .Scoped

        Format Message Message: FIELDS/FunctionCallFailed, Environment<*Message text>

     //Map with Environment

        Go Sub Send message

        Go Sub Error handler

    When Environment<*Returned status> != <*Returned status.*Successful>

        Format Message Message: SelfRegister.RegisterPage.Register.Role Not Found, Environment<*Message text>

    //Map with Local<MyRoleName>

        Go Sub Send message

        Go Sub Error handler

 

Call WSYAPI/APIServer.User.AddRole

// Map with FetchedData<APIFields.RoleSurrogate>

// Map with Key<APIFields.UserSurrogate>

If Environment<*Call status> != <*Call status.*Normal>

    Name Function: WSYAPI/APIServer.User.AddRole, Environment<*Object>, .Scoped

    Format Message Message: FIELDS/FunctionCallFailed, Environment<*Message text>

//Map with Environment

    Go Sub Send message

    Go Sub Error handler

Change session data

After the user has been created, there are a number of options:

• You can just show the registration page again - maybe with a message stating that the user profile has been created.
• You can show a page stating that the user profile has been created - with a link to the login page.
• You can update the session with the entered information - and reload the site so that it corresponds to the new authorization for the user.

The example shows the third option.

Insert the following code to update the session.

Subroutine "Change session data"

Call WSYAPI/APIServer.Session.SetUserAndUpdate

// Map with WebInput<APIFields.SessionSurrogate>

// Map with Key<APIFields.UserSurrogate>

 

If Environment<*Call status> != <*Call status.*Normal>

    Name Function: WSYAPI/APIServer.Session.SetUserAndUpdate,
        Environment<*Object>, .Scoped

    Format Message Message: FIELDS/FunctionCallFailed,
        Environment<*Message text>

    Go Sub Send message

    Go Sub Error Handler

The SetUserAndUpdate API updates the session as it is done when the specified user logs into the application. The roles, folder list and user is updated.

When the sub routine returns the ReloadSitePageGenerator will be called and the site will be reloaded with the updated session settings.

Generate and build

Generate and build the SelfRegister function and its scoped functions.

Run template generators

Run the template generator function:

• SelfRegiser.RegisterPage._DocumentTemplateGenerator

Deploy objects

Move the generated program objects to your application library/folder.

Move the generated template to the folder containing the application templates.

For more details on how to deploy a business process please read Moving a process to a test environment.

Define Process in the administration interface

Create process and presentation

Administration Interface Menu item: Maintain Processes

Press "Insert" to create a new process of type Business Process..

Define the new process (Process ID = REGISTER). Keep the checkbox "Create default presentation" checked.

Insert the process in the site structure

Administration Interface Menu Item: Site Structure

Select the menu where you want the menu item "Self Register" to appear in. Press "Add".

Select Business Process / New on the first page.

On the second page, select the presentation for the process (Search For: REGISTER to find the record).

On the third page, specify "Register" for the menu text - select an unused combination of alignment/sequence.

On the last page assign the "Anonymous"  role to the menu item and press "Finish"

The menu item will now be available in the menu for all anonymous sessions, while it not be shown to sessions where a user has logged in.