Expresso Registration and Login

Expresso provides a sophisticated and customizable solution for registration of users into the Expresso framework and, therefore, the Expresso-based applications. This document explains the various features available with the Expresso registration system and details the procedures for customizing the features.

Expresso Components Listing

• Express Registration
• Email Validation
• Registration Domains
• Registration Object Map and Detailed/Extended Registration
• Default Domain and Registration Object Map
• Extended Domain and Sample regsitration Objects
• Customization of Registration
  

If you decide to write your own registration and login controllers, all Expresso needs for it core functionality is : login-name, uid (integer) and email-address, and that the user be put in a user-group. If you write your own login controller, then even the password is optional since your controller will provide the password checking/email-validation/change-password/etc. functions on its own.

Express Registration

Express registration deals with getting the bare minimum information required to identify and authenticate an user on the site. As such, it requires a "Login Name" and a password. In addition, to communicate with the user, an email address is required. The site has control over whether the user specifies the "Login Name" she prefers, or alternatively, if the email address is used also as the "Login Name". As detailed below, the site has also a choice in specifying whether the user specifies her password, or alternatively, if Expresso generates a random initial password for the user. In either case, the user has a choice to change the password after the registration process is complete.

If extended registration is specified for a domain , then, upon completion of express registration the user is temporarily placed in a Expresso user group call "NotReg - Users Not Fully Registered Yet". The registration controller, when all extended information is provided, moves the user into the proper user group for the domain. When the user completes the registration the Admin is emailed an email that provides a link to access the registration information and approve or deny the registration.

Email Validation

How do you know that the email the user provided, in fact, really does belong to the user? The way Expresso does this is to send an email containing an authorization code to the email address provided by the user at registration. Once the user clicks on the link provided, Expresso will validate the user with the assumption that if the user is able to access email sent to that address, then the user owns that email address (it's your call whether this is a valid assumption or not). Once validated, in the securest form, only then is an email sent to the user containing her password.

Of course, there are various levels of customization in the authentication process. The site can choose whether the user provides the password, or whether Expresso generates one for the user. The site can choose whether an authentication step, as detailed above, is used before the password is emailed to the user. Or, the site can choose simply to assume that the user provided a valid email address to begin with and to simply send the password to that email address. In all cases, the password is stored internally in Expresso in encrypted form and the cleartext is not only never displayed on the browser, it is simply not available.

Registration Domains

Do you have requirements for different sorts of registration information based on the type of user? For instance, on your site, you might have a type of user that is simply interested in using the forums. For these users, maybe you decided that only express registration is sufficient (i.e. all you need is a login name, a password and an email address). The next step up maybe someone that will buy somethig, and so you need contact information in additon to express registration. Finally, you might want to have suppliers register on your site and you might have requirements for completely different types of registration information that they need to provide.

Expresso provides a way to easily handle these situations without having to write a whole bunch of custom controllers. All you need is to provide different Registration Domains, one each for each type of user. Registration domains are implemented as a regular Expresso DBObject, in com.jcorporate.expresso.services.dbobj.RegistrationDomain . As such, you can use the DBMaint controller to manipulate the records in RegistrationDomain. In fact, a link to do that is already provided to you on the Expresso "Security" page.

So, what are the various fields in a registration domain?

• Name - This is the name of the domain. This is what you sepcify in the "domain=" parameter to the Login controller to point a registration screen to be built for this domain.
• Description - A short and sweet description for this domain
• Default Group - The name of an Expresso user security group, as defined in com.jcorporate.expresso.services.dbobj.UserGroup. Once registered, the user is made a member of this group.
• Registration Controller Class Name - If extended registration is required, the name of the controller class that will handle the extended registration process. The default registration controller is com.jcorporate.expresso.services.controller.Registration.
• Registration Required Prior to Login? - A "Y"/"N" field that determines whethere this domain requires the user to go through extended registration or not.
• Approval required prior to Login? - A "Y"/"N" field that specifies that after the user completes registration, a site administrator has to approve the registration before the user can log in. This feature is not fully implemented, set this field to "N" for now
• User specifies password? - A "Y'/"N" field that specifies whether the user specifies their preferred password or whether Expresso randomly generates a password for the user.
• Validate email? - A "Y"/"N" field that specifies whether an authentication code/link is sent to the user's email address to verify correct email address before the password is sent.
• Email as login name? - A "Y"/"N" field that specifies whether the email address of the user is also used as the login name or whether the user has to specify a login name.

Registration Object Map And Detailed/Extended Registration

If a registration domain specifies extended registration, then the question arises as to which set of DBObjects are to be used for the user to provide registration information for? That's where the registration object map comes in. Again, it is another plain, vanilla Expresso DBObject, in com.jcorporate.expresso.services.dbobj.RegistrationObjectMap . As such, you can use the DBMaint controller to manipulate the records in RegistrationObjectMap. In fact, a link to do that is already provided to you on the Expresso "Security" page.

A registration object map provides a one-to-many relationship between a RegistrationDomain to DBObjects. Put another way, for each domain defined in RegistrationDomain, one or more entries are provided for DBObjects in RegistrationObjectMap, each tied back to the RegistrationDomain by its DomainID. Note that the DBObjects are completely independent of the domain, i.e. a DBObject can be reused for as many different domains as needed.

Here are the fields in RegistrationObjectMap:

• Registration Domain ID - The ID of the domain for which this DBObject will be used (the same DBOBject can be repeated for multiple domains).
• Registration Object Class Name - The name of the DBObject class that is to be used. The only requirements are that the class be derived from com.jcorporate.expresso.core.dbobj.DBObject and that it define one field to store a reference back to the "ExpUid" user-id field in com.jcorporate.expresso.core.security.User/UserInfo.
• Uid Field Name - The name of the field that is to store the reference to ExpUid.
• Minimum records per user - The minimum number of records of this DBObject that the user has to supply before registration is considered complete. A 0 means that this information is optional.
• Maximum records per user - The maximum number of records of this DBObject that the user has to supply before registration is considered complete. A 0 means that there is no upper bound.
• Fields in auto-generated forms - A comma-separated list of field names to display on pages automatically generated by the registration controller. If the fieldname is preceded by a "!", then that denotes that the field is marked for no-display. A "+" character is pre-fixed to a fieldname for display in listing multiple records of that DBObject, so that a particular record can be selected for Update/Delete.
• Display order in menu - If the domain has multiple DBObjects in the object map, then this field determines the order this database will be listed in the menu generated by the registration controller.
• User can edit - A "Y"/"N" field that specifies whether the user can alter the information he/she entered.
• User can delete - A "Y"/"N" field that specifies whether the user can delete the registration records.

Default domain and registration object map

Expresso comes pre-configured for a domain called "default". If no "regDomain=" parameter is supplied when the Login controller is invoked, or if "regDomain=default" is supplied, then the default domain is used for user registration. With this domain, the following behavior is seen:

• Default Group - Everybody
• Registration Controller - com.jcorporate.expresso.services.controller.Registration
• Registration required prior to login - No
• Approval required prior to login - No
• User specifies password - Yes
• Validate email - No
• Email as login name - No

The corresponding registration domain map entry has the following characteristics:

• Registration Domain ID - default
• Registration object class name - com.jcorporate.expresso.services.dbobj.RegisteredUser You'll note that RegisteredUser does not have a Uid key field as required by the registration controller. However, for backwards compatibility, the registration controller allows an exception in only this one specific case
• Uid Field Name - ExpUid
• Minimum records per user - 1
• Maximum records per user - 1
• Fields not shown - IsActive,UserName,InternalComment,AddedOn,UpdatedOn,URL,EmailPrivate,Occupation,Location,Expertise,OtherProjects,Contributions,Address,Phone,Testimonial,IPAddress
• Display Order in Menu - 999
• User can Edit - Yes
• User can delete - No

Extended domain and registration object map

Expresso also comes pre-configured for a domain called "extended". This domain is primarily intended as an example of how to deal with multiple registration databases.

The extended domain also comes with some sample registration objects in the package com.jcorporate.expresso.ext.dbobj.regobj. These DBObjects are Person, Address, Phone, Contact. Please note that these classes are not meant to be of use to every site. These are example objects. The point is that Expresso does not care at all what registration objects are used, or even if any are used. It is upto the site to either use these sample objects or define new ones to suit local needs

Worthy of note here, the sample DBObjects were created with the WebAppWriter app-generator, available at DataFundamentals.com.

Having read this document, the best way to see how the extended domain is setup is to go to Expresso's Security page and to list the records in the Registration Domain and Registration Object Map records.

To get a taste of how it all works, go to Expresso's Security page and using the "Users" link, modify a test-user's registration domain to "extended". Then login as the test-user and from the Login page click on "Update Registration".

Customization of registration

There are several ways Expresso's behavior in this regard can be customized:

• The "default" registration domain, is after all, a record in a DBObject. One quick way to modify the registration behavior is to use DBMaint to mmodify the various fields of the "default" domain. The default registration domain is used in this way:

  <a href="<%=contextPath%>/Login.do?state=promptRegister">Register</a>
  				

  In this case, since no registration domain is specified using the "regDomain" parameter, the Login controller will check to see if the Setup database contains a value for "defaultRegDomain". If a value is found, that will be used for the name of the registration domain. Otherwise, the name "default" will be used.
  
  If I wanted a registration process that does not requires the extra information supplied by com.jcorporate.expresso.ext.dbobj.RegisteredUser then... login as Admin, go to Security, Registration Object Map, edit default, and set the minRecords and maxRecords to zero (the default is one). Or creating your own registration domain is a good course
  of action in the long run.
  
• Another way is to create a new registration domain . A typical way might be to do this in the otherSetup(...) method of your applications Schema class. The advantage of doing this is that it leaves the Expresso defaults alone. Here's a fragment of sample code to achieve this:

  .....
  	/* Create the domain */
  	RegistrationDomain rd = new RegistrationDomain();
  	rd.setDBName(getDBName());
  	rd.setField("Name", "myCustomDomain");
  	if (!rd.find()) {
  		rd.setField("Description", "My Valued Customers");
  		rd.setField("ReqRequired", "Y");
  		rd.setField("GroupName", "myValuedCustomers"); // Assume this group indeed exists
  		rd.setField("ControllerClass",
  		"com.jcorporate.expresso.services.controller.Registration");
  		rd.add();
  	}
  
  	/* Map a DBObject to the domain */
  	RegistrationObjectMap rdm = new RegistrationObjectMap();
  	rdm.setDBName(getDBName());
  	rdm.setField("RegDomId", rd.getField("RegDomId"));
  	rdm.setField("RegObj", "com.mycompany.dbobj.MyCustomer");
  	rdm.setField("UidField", "CustomerId");
  	if (!rdm.find()) {
  		rdm.add();
  	}
  
  	/* Map another DBObject to the same domain */
  	rdm.clear();
  	rdm.setField("RegDomId", rd.getField("RegDomId"));
  	rdm.setField("RegObj", "com.mycompany.dbobj.MyCustomerAddr");
  	rdm.setField("UidField", "CustomerId");
  	if (!rdm.find()) {
  			rdm.add();
  	}
  	.........
  			  

• The login/registration JSP's must be modified to take advantage of the custom registration domain(s). The JSPs are in /expresso/jsp/register/*.jsp. In particular, the links to the registration controller are defined in the file header.inc. The registration domain name must now be supplied to the Login controller as follows:

  				
  <a href="<%=contextPath%>/Login.do?state=promptRegister&regDomain=myCustomDomain">Register As A Customer</a>
  <a href="<%=contextPath%>/Login.do?state=promptRegister&regDomain=myCustomDomain2">Register As A Supplier</a>
  				
  				

• If you'd rather not change the Expresso-supplied JSPs, then another option might be to copy the JSPs over to another directory and then modify the "forward" definitions for the "Login" action in struts-config.xml.

Conclusion

For technical information about how to use registration, please refer to the Expresso Developers Guide (EDG) or the Javadocs.