Configuring User Registrar

To change the layout of the page, you need to have knowledge of basic HTML tags to successfully change the pages. For more information, see "Changing Layout" section.

While the template files primarily contain layout and text, these files also determine which input fields the user must complete. In the case of a registration screen, the template determines what information a new subscriber must enter.

Note Each locale has its own directory located under the <csrc-root>/csrc/html/csrc-ur-sub directory.

Changing Images

The template files reference external images for each of the buttons in the UI. These files are referenced with the HTML tag <IMG SRC=xxx>. To change the image, replace the xxx with the new file name.

For example, change <IMG SRC='/csrc/images/ciscologo.gif'> to <IMG SRC='/csrc/images/MSO.gif'>.

If you have an existing image, you can simply replace it. Otherwise, use a standard image editor to create the image and then specify the new image by file name.

The template files contain the width and height of every image. If you replace or update an image with one of a different size, you need to update every <IMG> tag that references the modified image. The images are stored in the <csrc-root>/csrc/images directory.

Tips Make sure that you enter the correct width and height for each image. Having specified dimensions is critical to increasing the perceived performance of any Web page displayed to end users. This is particularly noticeable when using the Netscape browsers. If the template does not contain the dimensions, Netscape browsers wait to display a page until they have loaded all the images.

Changing Text

Each template file contains text that describes user actions. You can edit the source templates to modify the text in these template files. Remember, however, if you add or delete significant amounts of text you may need to adjust the layout of the page.

The default installation of the User Registrar Subscriber application specifies the English language. The files that support the English language are located in the <csrc-root>/csrc/html/csrc-ur-sub/en directory.

If you plan to use another language or multiple languages, see "Using Locales" section.

In addition to the text in the template files, there is also a file containing all of the error messages the system displays. This file contains a mapping from the message code to the message text. The English version of this file is <csrc-root>/csrc/html/csrc-ur-sub/en/messages.cwaf.

For example, the following two lines are messages for the known_login page:

page:known_login:missing:Username=Username, please re-enter.
page:known_login:missing:Password=Password, please re-enter.

Each line contains a message key defining the type of message. There are two categories of messages: system and page. Using this unique identifier for a message, the interpreter extracts everything from the right of the equals sign to the end of the line for substitution when the message is required. User Registrar automatically truncates any white space at the end of the line.

System messages apply across all pages whereas page messages are specific to each page.

C hanging Layout

The template files rely upon tables to layout the components of each page. You may want to change the order of components or to completely redo the page. In either case, you should use standard HTML formatting guidelines to modify the template.

Note Do not modify the NAS-specific tags, which must be maintained for the proper functioning of the page. You can recognize these NAS tags by the <GX> or %GX% syntax. For example, during template rendering, User Registrar replaces <GX TYPE=cell ID=Subscriber.Username></GX> with the current subscriber's username.

When modifying templates, make sure you follow all of the NAS rules. In particular, make sure to maintain the relationship between <GX TYPE=tile...> and <GX TYPE=cell...> tags. For more information about templates, see the NAS developer documentation

Tips When working with tables, Internet Explorer is more lenient about beginning and ending table tags than Navigator. Thus, to ensure the correct functioning of any HTML table, view any page you change in both Netscape and Internet Explorer and preferably against multiple browser versions.

Adding Display Fields

For each data object in the system, there are attributes that are available after installation called the core attributes, and there are attributes configurers create that extend the basic application schema called extension attributes. For more information about extension attributes, see "Schema Extensions."

The default User Registrar template files use a subset of the core attributes, however you can change these files to show any attribute.

For example, to display a hint for the user's password on the login page, create an extension attribute named Hint and add it to the Subscriber object with the line <GX TYPE=cell ID=Subscriber.Hint></GX> in the login template page. Then every time the user accesses the login page, User Registrar displays the hint.

Note For more information about creating attributes, see "Extending the Application Schema" section and "Creating Schema Extensions" section.

Similarly, you do not need to make code changes to access extension attributes of referenced objects. If you extended the Account object with a LastPayment attribute, you could access it indirectly through a Subscriber object by <GX TYPE=cell ID=Subscriber.AccountNumber.LastPayment></GX>.

Adding Input Fields

The User Registrar page logic application schema performs dynamic input processing so that you can easily add attribute inputs. Each page has the required object attributes for self-provisioning already requested from the user.

In the choose_username page, User Registrar expects a Subscriber object. In the default User Registrar Subscriber application, this page asks for a username and password. Without modifying the logic, you can request an additional attribute input for the Subscriber object.

For example, to have users enter a hint for their password, add an input box to the choose_username page using a special syntax<INPUT> tag. In the case of the hint, it looks like: <INPUT type=text name=NewSubscriber.Hint>.

The new_login page expects a NewSubscriber object of type Subscriber to be created and passed in as an input. The addition of new attribute extensions is discussed in "Extending the Application Schema" section and "Creating Schema Extensions" section.

To support additional extension input fields, the application schema has the concept of required and optional flags for attributes. These flags allow User Registrar to dynamically determine what error messages should be returned when setting values for arbitrary objects.

The CSRC schema also employs required and optional attributes. In this case, required means that the attribute must have a value in the database. Whereas, in the application specification file, required means the subscriber must enter the value.

For example, to add a new field to a Subscriber object, specify in the page whether this is a required or optional attribute. The application specification file defines the required attributes for a given page in contrast to those required by the CSRC schema. For example, the schema may require 10 subscriber attributes, but the application specification file might require only five attributes. For User Registrar to successfully write the page attribute values to the database, the balance of the attributes need to be present.

If the new field specifies a required attribute, then attempting to submit the page without a hint results in User Registrar displaying in an error.
If the new field specifies an optional attribute, then attempting to submit the page without the attribute does not result in an error. If, however, the CSRC schema requires the attribute, the page logic code must specify the value before User Registrar can write the page to the database.

Placing User Registrar in Frames

One of the easiest changes you can make to the User Registrar Subscriber application is to put the application inside frames. User Registrar is based on the assumption that the content in the surrounding frame panes do not need to change in association with the current application context.

Example for Placing User Registrar in Frames

Example 4-1 shows an index page that loads CSRC in the bottom portion of the window and has a menu frame along the top of the page.

Example 4-1: Using Framesets

[index.html]
<FRAMESET ROWS="50,*">
  <FRAME 
    SRC="/menu.html" 
    NAME="menu">
  <FRAME 
    SRC="/cgi-bin/gx.cgi/GUIDGX-{75BBB960-C80E-11D2-8207-0060B0FC247E}" 
    NAME="csrc">
</FRAMESET>

One result of placing the User Registrar Subscriber application inside frames is that the Web browser will not display the cryptic URLs that Netscape Application Server uses. Instead, the browser displays only the first URL that contains the <FRAMESET> tag. This hides the lower-level implementation from the subscriber.

Changing Page Headers and Footers

Each page has a common header and footer that the application defines.The application's header and footer are defined in the CSRCURSubscriber.tmpl file. Modifying this file allows you to change the application's header and footer. You do not need to change the source code to make these changes.

Example 4-2 shows example headers and footers that you might use in the User Registrar Subscriber application:

Example 4-2: Example Headers and Footers

<!-- HEADER START -->
 
<!-- Setup the header -->
<IMG SRC='/csrc/images/CiscoLogo.gif'>&nbsp
<B>User Registrar 1.0 </B>(Subscriber)
 
<!-- If appropriate, show the help button -->
<GX type=tile id=UseHelpButton max=1>
    <FORM Method=POST
    Action="/cgi-bin/gx.cgi/GUIDGX-<GX Type=cell Id=_GUID>(guid)</GX>">
    <INPUT Type=hidden Name='_goto' Value='urhelp'>
    <INPUT type=image src=/csrc/images/nbHelp.gif
    border=0 name=helpButton></FORM>
</GX>
 
<!-- If appropriate, show the exit help button -->
<GX type=tile id="ExitHelpButton" max=1>
    <FORM Method=POST
    Action="/cgi-bin/gx.cgi/GUIDGX-<GX Type=cell Id=_GUID>(guid)</GX>">
    <INPUT Type=hidden Name='_goto' Value='urhelp'>
    <INPUT type=image src=/csrc/images/nbExitHelp.gif
    border=0 name='Exit Help' value='Exit Help'></FORM>
</GX>
 
<!-- If appropriate, show the logout button -->
<GX type=tile id="LogoutButton" max=1>
    <FORM Method=POST
    Action="/cgi-bin/gx.cgi/GUIDGX-<GX Type=cell Id=_GUID>(guid)</GX>">
    <INPUT Type=hidden Name='_logout'
    Value="<GX Type=cell Id=_PageName>(pagename)</GX>">
    <INPUT Type=image Src=/csrc/images/nbLogout.gif
    Border=0 Name=logout_button></FORM>
</GX>
 
<!-- End the header section -->
<HR>
 
<!-- HEADER END -->
<!-- BODY START -->
 
<!-- Include the current page template file -->
<GX Type=Include Id=PageTemplate></GX>
 
<!-- BODY END -->
<!-- FOOTER START -->
 
<!-- Common application footer -->
<HR>
<FONT SIZE='-2'>Copyright (C) 1999 by Cisco Systems.</FONT>
 
<!-- FOOTER END -->

Example 4-2 contains three primary sections:

The header
The footer
The page body

Since the page body is simply the location of the current page the user is viewing, you should not modify this section. In the header and footer sections, you can change the header and footer presentation. In particular, you can use any regular HTML tags, including graphics and fonts, to alter the presentation.

Note The page template file does not contain a <HEAD> or <BODY> tag. The application framework provides these tags as part of its execution.

You can also change the location and order of the system buttons. For example, if a certain UI design calls for the logout button to be located in the footer instead of in the header, simply move the entire section that defines the logout button behavior.

Customizing Subscriber Pages

You can change the User Registrar Subscriber configuration options through the User Administrator UI. These customizations are grouped by locale. For example you can choose to have a specific set of customizations for a college and another for a residential neighborhood. You can use locales to automatically determine the look and workflow of the pages, or to allow subscribers a language choice, such as whether they want pages in English or Spanish.

You can customize User Registrar Subscriber pages in three ways:

Changing workflow
Using optional pages
Using locales

Changing Workflow

You can customize the workflow which affect the subscriber's self-provisioning experience. For example, you might want to offer a single service package, allow subscribers to login by PIN, or skip user specification of a user and host name.

The following configuration options control the User Registrar Subscriber pages. You specify them through the User Registrar Administrator UI.

Single Service

If you choose SingleService, User Registrar disables the service selection page and automatically configurers the subscriber for the specified service. If User Registrar cannot locate the service, it displays the normal service selection page. By default, SingleService is disabled. To enable or disable this option, see the "Editing Locale" section.

For more information about these pages, see the "Choosing a Service" section.

New Login Mode

You can choose to have User Registrar display the new_login_pinonly page, which allows subscribers to login with just their PIN. User Registrar logs in the subscriber if it can find a matching PIN in an LDAP Account object.

Choose pinonly mode only if your Account objects are indexed by PIN. The default login page is normal, which requires a subscriber to enter an account number and PIN. To enable or disable this option, see the "Editing Locale" section.

For more information about these pages, see the "Logging to User Registrar" section.

For more information about the username lookup class, see the "Username Lookup" section.

Skip Hostname Selection

When using a hostname lookup class, this option causes User Registrar to skip the activate_device page and instead use the output of the lookup class. User Registrar, however, still uses the looked-up value to populate the Computer object. By default, this option is disabled. If you set this value to true and do not specify a hostname-lookup-class, User Registrar displays the activate_device page.

To enable or disable this option, see the "Editing Locale" section.

For more information about the hostname lookup class, see the "Hostname Lookup" section.

Using Optional Pages

You can choose to add additional optional pages. For example, you might want User Registrar to display a welcome page that greets the subscriber; a steps page that outlines the self-provisioning steps, or a select locale page that lets the subscriber select a language.

The following configuration options control the User Registrar Subscriber pages.

Use Welcome Page

You can choose to have User Registrar display the welcome page as an introductory page to the self-registration process. If you use the welcome page, User Registrar determines if subscribers are new or known users. If the subscriber is known, User Registrar displays the known_login page. If the subscriber is new, User Registrar displays the welcome page. By default User Registrar does not display this page.

To enable or disable this option, see the "Editing Locale" section.

For more information about this page, see the "Accessing User Registrar" section.

Use Steps Page

You can choose to have User Registrar display the steps page. This page provides a description of the self-registration process. If you choose to use this page, User Registrar displays it only for new subscribers. By default User Registrar does not display this page.

To enable or disable this option, see the "Editing Locale" section.

For more information about this page, see the "Accessing User Registrar" section.

Use Service Agreement Page

You can choose to have User Registrar display the accept_svc_agreement page, which requires the subscriber to accept the service agreement before beginning the self-registration process. If the subscriber declines the service agreement terms, User Registrar displays the declined_svc_agreement page, which updates the Account object's AcceptedServiceAgreement attribute so that you can track subscriber service agreement acceptance.

The confirm_svc_agr page works in conjunction with the accept_svc_agreement page. If the subscriber declines the service agreement terms, User Registrar displays this page. The subscriber can choose to either accept or decline. If the subscriber accepts, User Registrar displays the next page in the workflow. If the subscriber declines, User Registrar displays the declined_svc_agreement page.

The declined_svc_agreement page works in conjunction with the accept_svc_agreement page. If the subscriber declines and confirms the decline, User Registrar displays this page and sets the AcceptedServiceAgreement flag to false. From the declined_svc_agreement pag, the subscriber can only logout and close the browser.

By default User Registrar does not display these pages. To enable or disable this option, see the "Editing Locale" section.

For more information about this page, see the "Enabling Service Agreement" section.

Use Select Locale

You can choose to have User Registrar display the select_locale page. This page allows a subscriber to choose the language, such as English or Spanish for the User Registrar pages. After the subscriber has chosen the language, User Registrar updates the Subscriber's object local attribute with that language value. When the subscriber logs in again, User Registrar automatically displays the correct language pages.

To enable or disable this option, see the "Editing Locale" section.

For more information about this page, see the "Accessing User Registrar" section.

Using the Default Subscriber Locale

This option determines the locale to present to a new subscriber. If you have enabled LocaleLookup, User Registrar uses its value otherwise it uses the Default subscriber locale. User Registrar learns the value for LocaleLookup when the subscriber selects a locale from the select_locale page. The default value is en for English.

To enable or disable this option, see the "Editing Global Settings" section.

For more information about this page, see the "Editing Global Settings" section.

Using Locales

You can use locales to offer multiple language support or customized pages based on the customer's geographic region or a combination of both. For each locale you create, you can define a specific workflow, set of page extensions, and customized pages.

The following example describes one way you could use locales to support different types of customers. A cable provider serves both a university and a residential neighborhood.

For residential customers, the cable provider offers User Registrar Subscriber pages in both English and Spanish.
For university customers, the cable provider offers a single service package and customized text that includes the dorm name and room number.

The cable provider services both groups by configuring three locales: University, Residential_English, and Residential_Spanish.

The cable provider configures User Registrar to automatically determine which locale customers are connecting from and to display the corresponding locale pages. For residential subscribers, User Registrar displays a language choice, allowing subscribers to choose between English and Spanish. After subscribers have chosen the language, User Registrar displays that language for all subsequent interactions with User Registrar.

The following are the areas in which you can customize locale use:

Locale Creation---You define each locale through the User Registrar Administrator UI. When defining a locale, you can choose to define the name and description of the locale, as well as tailor the workflow and basic page characteristics (page title and background color).

Custom Locale Presentation---Each locale has its own set of template files. This allows each locale to have a different presentation and language, as well as to be branded for the particular use. For example, a university locale might have the university name listed whereas the residential locale might have only the cable provider's name.

Automatic Locale Determination---You can use the ILocaleLookup page extension to automatically select the appropriate locale for a new subscriber. In the previous example, the cable provider could implement a locale lookup that determines whether the subscriber is connecting from the university network or from the residential neighborhood.
Subscriber Locale Selection---Since languages are mainly subscriber preference, you can use a select_locale page to allow the subscriber to select the locale. In the previous example, only residential customers would need language selection so the ILocaleChoices page extension would be used to limit selection to Residential_English and Residential_Spanish.
Default Locale Configuration---While the above settings define the locale behavior, the default locale controls where the processing starts. In User Registrar Administrator, the default locale is defined in the Edit Global Settings page. This locale controls the initial workflow. If you use any page extensions or the select_locale page, you must enable them in this default locale.

Creating a new Locale

User Registrar comes with only the en locale (English language) available. Although you could customize this locale and use it in a single locale system, if you need multiple locales, you need to create them. In User Registrar Administrator, the Manage Defaults page contains a list of locales.

To create a new locale, do the following:

Step 1 From the Manage Defaults page, enter the name and description of the new locale.

Step 2 Click Add Locale.

User Registrar redisplays the page adding the new locale to the list of locales. After you have created a locale, you need to initialize the workflow settings.

Note If you want to have two locales using the same workflow, you must set all of the workflow options in both locales.

To edit the workflow, do the following:

Step 1 From the Manage Defaults page, click Edit next to the name of the locale you have just created.

Step 2 From the Edit Locale page, select or enter the workflow options for this locale.

On this page, you can also control the usage of the locale selection page and enable the desired locale-specific page extensions. For more information about these options, see Table 3-26.

Customizing the Page Presentations

When you create a new locale, User Registrar copies a set of template files into the /csrc-root/html/csrc-ur-sub/locale-name directory where locale-name is the name of the locale you just created. These template files define the appearance of the pages User Registrar displays to the subscriber.

Tips If you want to base one locale on another locale, first create the new locale, then copy all of the template files from the old locale into the new locale directory overwriting the files User Registrar placed there as part of locale creation.

To customize the page presentation, do the following:

Step 1 From the Manage Defaults page, click Edit next to the name of the locale you have just created.

Step 2 From the Edit Locale page, click Edit Page Presentations.

Step 3 From the Edit Page Presentations page, accept the defaults or enter the background color (in hexadecimal, for example, #003366) and page title for each User Registrar Subscriber page. For more information about these pages, see "Using User Registrar."

Determining a Subscriber's Locale Automatically

User Registrar displays the default locale when a new subscriber connects to the User Registrar Subscriber application. In the default locale, you can define a locale lookup page extension that automatically configures the subscriber to use a different locale. For example, in the scenario described above, User Registrar automatically determines whether the user is connecting from the university or residential neighborhood.

To create a page extension that uses the ILocaleLookup interface, do the following:

1. Create a new Java class that implements the ILocaleLookup interface with the getLocale() method returning the name of the locale for the given subscriber.

2. In the User Registrar Administrator Edit Locale page, specify the newly created Java class in the Locale lookup class field.

The following is a simple class that implements locale determination using the modem's IP address.

public class SampleLocaleLookup 
    implements com.cisco.csrc.ursub.ILocaleLookup
{
  public String getLocale(String computerIP, String modemIP)
  {
    if (modemIP.startsWith("123.123."))
      return "University";
    else
      return "Residential_English";
  }
}

After CSRC has determined the subscriber's locale, User Registrar displays the appropriate pages.

Note For more information about creating page extensions, see the "Creating Page Extensions."

Subscriber Selection of a Locale

Although you can use locales to support geographic regions, the primary reasons for using locales is for language selection. When a subscriber begins the self-registration process, the first page User Registrar displays can be the select_locale page. This page presents the subscriber with a list of locales.

Note If you have enabled the select_locale option, the locale the subscriber selects is automatically stored in LDAP and used when the subscriber returns to perform account maintenance.

To use the select_locale page, do the following:

Step 1 From the Manage Defaults page, click Edit next to the name of the locale you have just created.

Step 2 From the Edit Locale page, enable the Use select locale page option.

By default, the select_locale page lists all of the available locales configured in the system.

There may be times when you want to present the subscriber with only a subset of available locales. For example, in the scenario described above the residential customers should only be presented with Residential_English and Residential_Spanish.

To display a subset of locales available for a subscriber, create a the ILocaleChoices page extension by doing the following:

1. Create a new Java class that implements the ILocaleLookup interface with the getLocaleChoices() method returning a string array containing the two desired locale names.

2. In the User Registrar Administrator Edit Locale page, specify the newly created Java class in the Locale lookup class field for the Residential_English & Residential_Spanish locales.

The following is a simple class that constrains the available locale choices for a certain subscriber group.

public class ResidentialLocaleChoices 
    implements com.cisco.csrc.ursub.ILocaleChoices
{
  public String[] getLocaleChoices(String computerIP, String modemIP)
  {
    return new String[] 
      { "Residential_English", "Residential_Spanish" };
  }
}

Note For more information about creating page extensions, see the "Creating Page Extensions."

Configuring the Default Locale

The locale and workflow logic used when a subscriber initially accesses User Registrar is controlled by the default locale specified in User Registrar Administrator. If you use a ILocalLookup page extension, you must specify the class on the default locale's settings page.

Note For more information about creating page extensions, see the "Creating Page Extensions."

Extending the Application Schema

User Registrar is based on an application schema that abstracts the underlying data stores from the development of the user interface. The application schema defines all the objects and attributes that are available to you as the User Interface configurer.

Example 4-3 shows the Account and Subscriber objects from the User Registrar Subscriber application's schema:

Example 4-3: Account and Subscriber Objects

class Account{
	string AccountNumber, unique;
	string PIN;
	string LastName;
	string FirstName;
	string MI;
	string Salutation;
	string Telephone;
	string Address, multi;
	string City;
	string State;
	string ZipCode;
	string SecurityQuestion, optional;
	string SecurityAnswer; optional;
	boolean AcceptedServiceAgreement, optional;
}
 
class Subscriber {
	string UserName;
	string LocalityName;
	string StateOrProvinceName;
	string AccountNumber, ref(Account.AccountNumber), unique;
	boolean Isdisabled;
	string Password;
	objid ModemList, ref(Modem.ObjectID), multi;
	objid ComputerList, ref(Computer.ObjectID), multi;
	objid ServiceList, ref(Service.ObjectID), multi;
}

In Example 4-3, the class { } sections define objects and the various lines in each object define the attributes available. For each attribute, you can configure various properties.

The AccountNumber attribute of Subscriber is a reference to an Account object. This relationship is represented by ref(Account.AccountNumber). Similarly, an attribute can be multivalued (multi), unique across all instances (unique), and have default values. Unlike normal properties, specify default values by placing an equal sign to the right of the attribute name and then specify a value. For example, string IsDisabled=false; ensures that newly created Subscriber objects are not disabled by default.

Using the Service Agreement Flag

If you choose to use the service agreement pages, CSRC uses the AcceptedServiceAgreement flag to store whether the subscriber has agreed to the service agreement. Note that the callouts that address the Account object must be able to return the accepted service agreement flag, must be registered for updates to the Account object, and must be able to update the callout's store with the new value after the agreement is accepted.

For example, when CSRC first access your callout to retrieve the Account object for a given subscriber, the AcceptedServiceAgreement will have no value if that subscriber has not accepted the agreement (a CSR registered the subscriber).

If the subscriber has already agreed to the service agreement during qualification, the AcceptedServiceAgreement value will be true.
If the subscriber accepts the service agreement, CSRC writes the value of true to AcceptedServiceAgreement at the end of the self-registration process (at the same time it writes the Subscriber object).
If the subscriber declines and confirms the decline, CSRC updates the AcceptedServiceAgreement to false.

Extending the Schema

Working in conjunction with extension configurers, you can augment the schema with new attributes. After an extension has been properly configured to provide a new attribute, you must update the application schema to reflect this change. Additions to the application schema require a corresponding change to either an extension callout or an additional storage attribute.

Edit the schema file located in <csrc-root>/conf/cwafmw.spec to contain the new attributes and then provide the values using extension attributes or callouts. The order of the attributes in the schema is not significant to the operation of the application, though for consistency add the extension attributes after the core attributes User Registrar installed. For more information on extending the underlying CSRC object layer, refer to the "Schema Extensions," and "CSRC Schema."

Table of Contents

Configuring User Registrar