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 the "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 do not 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 the "Using Locales" section.

In addition to the text in the template files, there is also a file containing all of the error messages that 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 CSRC-specific tags, which must be maintained for the proper functioning of the page. You can recognize these CSRC tags by the <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 do not change or delete any of the text between the <GX> and </GX> tags. Also, be aware that some <GX> tags can be nested inside other <GX> tags.

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.

The core attributes are those described in the CSRC Schema's Account Class, Subscriber Class, Modem Class, and Computer Class. For more information about these attributes, see the appropriate class in "CSRC Schema."

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 "Adding a New 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 "Adding a New 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 "Adding a New 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 "Adding a New 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 "Adding a New 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 page, 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 "Adding a New 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 "Adding a New 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 dormitory 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 to 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 you would use the ILocaleChoices page extension 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 must 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 must 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 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 and 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 ILocaleLookup 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."

Using Neighborhoods

You can use neighborhoods to segment subscribers based on a common geographic region and/or you can use neighborhoods to tailor the services, languages or locales presented to the user.

The following example describes a way you could use neighborhoods to support two different groups of customers. A cable provider serves both a university and a residential neighborhood. This is the same scenario presented in the locale section; however, using neighborhoods significantly increases the ease of configuration and the overall effectiveness of the CSRC installation. In addition, the creation of neighborhoods allows User Registrar to automatically provision shared modems for community neighborhoods, such as educational institutions or multifamily dwellings.

For residential customers, the cable provider offers multiple services, two locales (English and Spanish), and automatically provisions cable modems as private devices owned by each subscriber.

For university customers, the cable provider offers streamlined provisioning through a single service, a single locale, and automatically provisions cable modems as shared devices owned by the neighborhood.

The cable provider services both groups by configuring two neighborhoods: University and Residential.

The cable provider configures User Registrar to automatically determine which neighborhood subscribers are connecting from by associating the neighborhoods with subnets defined in Modem Registrar.

For residential subscribers, User Registrar presents the available locales to the users and then presents the auto-provisioning pages.
For university customers, the cable modems are automatically provisioned as shared devices the first time a subscriber connects.

After this initial activation, User Registrar only reboots the cable modem when the neighborhood's service level is changed.

Customizing Neighborhoods

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

Neighborhood Creation—You define each neighborhood through the User Registrar Administrator UI. You can choose to control aspects of the subscribers' experience, such as services presented, locales available, default provisioning method for the modem (shared or private), and contact information for the neighborhood. For more information, see the "Creating a New Neighborhood" section.
Subscriber Service Selection—You can control the services presented to the subscriber by specifying a subset of the services available. When limiting the services available, you can have a unique set of services for each neighborhood defined in a CSRC installation. When subscribers access the choose_service page, User Registrar uses the services specified in the neighborhood. If no services are defined, User Registrar presents all the user-visible services. For more information, see the "Specifying Subscriber Selection of a Service" section.
Subscriber Locale Selection—You can control the locales User Registrar presents to the subscriber by specifying a subset of the available locales. This technique allows you to have separately branded pages for each neighborhood. When new subscribers access User Registrar, it presents the default locale defined in the neighborhood. If that locale enables the select_locale page, User Registrar presents the subscriber with a list of the available locales as defined by the neighborhood. If no locales are defined in the neighborhood, User Registrar presents all of the available locales. For more information, see the "Specifying Subscriber Selection of a Locale" section.
Shared Modem Configuration—You can configure a neighborhood to automatically provision new modems as shared devices. In this case, you must configure the service and account number to associate with the shared devices. When a subscriber accesses User Registrar from behind an unknown shared modem, User Registrar presents the activate_shared_modem page before the subscriber has the opportunity to log in. User Registrar associates the new modem with the account number defined in the neighborhood and then configures it with the shared modem service level defined in the neighborhood. Once properly configured, the shared modem is rebooted to ensure that all of the new subscribers behind the shared device have the expected network capabilities. For more information, see the "Configuring a Neighborhood for Shared Modems" section.
Automatic Neighborhood Determination—You can use the provisioning elements defined in Modem Registrar to control the neighborhood used when a subscriber first accesses User Registrar. In particular, each scoping policy defined in Modem Registrar can have a default neighborhood associated with it. You could associate a specific CMTS with a broad residential neighborhood and have a specific subnet serviced by that CMTS tied to a university. When a subscriber first accesses CSRC, User Registrar scans the current hierarchy of provisioning elements to determine the neighborhood to use. The most specific provisioning policies have precedence over the more general policies. For example, subnets take precedence over CMTS policies. For more information, see the "Determining a Subscriber's Neighborhood Automatically" section.
Manually Provisioning Special Devices—You can manually provision modems that are in the opposite provisioning mode of the neighborhood. For example, in a shared modem configuration, such as an university, you may wish to configure private modems for the faculty. For more information, see the "Overriding the Modem's Default Provisioning Mode" section.

Creating a New Neighborhood

The default User Registrar configuration has no neighborhoods configured. To segment subscribers in a CSRC installation by type, you must create the appropriate neighborhoods. In User Registrar Administrator, the Manage Defaults page contains a list of neighborhoods.

To create a new neighborhood, do the following:

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

Step 2 Click Add Neighborhood.

User Registrar redisplays the page adding the new neighborhood to the list of available neighborhoods. After you have created a new neighborhood, you need to configure the default settings for that neighborhood.

To edit the neighborhood, do the following:

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

Step 2 From the Edit Neighborhood page, select or enter the configuration options for this neighborhood.

On this page, you can also control the provisioning mode for new cable modems. When specifying shared provisioning, you must specify an account number and service level for the shared modems. For more information, see the "Configuring a Neighborhood for Shared Modems" section.

Specifying Subscriber Selection of a Service

One use of neighborhoods is to control the available services User Registrar presents to a subscriber. When proceeding through the auto-provisioning pages, the subscriber must select a service level on the Choose Service Selections page.

To control the available services, do the following:

Step 1 From the Manage Defaults page, click Edit next to the name of the neighborhood you want to edit.

Step 2 From the Edit Neighborhood page, select the services to be presented to the subscriber by selecting one or more services on the Available Subscriber Services option. To select multiple services, hold down the control or option key while clicking on each desired entry.

Step 3 Click OK to use the selected services.

By default, the Choose Service Selections page lists all of the user-visible services configured in the system.

Specifying Subscriber Selection of a Locale

For each neighborhood you have defined, you may want to make a subset of the system locales available. For example, in residential neighborhoods, you may want to offer multiple languages branded for specific neighborhoods.

When using multiple locales, the default locale specified for the neighborhood must have the select_locale option enabled. After it is enabled, User Registrar presents new subscribers with a page allowing them to select their desired locale. Then, User Registrar stores the locale the subscriber selected in the subscriber object. If the subscriber makes changes to his or her account, User Registrar uses that selected locale.

To enable selection of a locale, do the following:

Step 1 From the Manage Defaults page, click Edit next to the name of the neighborhood you want to edit.

Step 2 From the Edit Neighborhood page, choose the default locale for the neighborhood. This is the locale that User Registrar presents with the select_locale page.

Step 3 Select the list of locales to present to new subscribers. If you select a single locale, User Registrar skips the select_locale page and uses the single locale. To select multiple locales, hold down the control or option key while clicking on each desired entry.

Step 4 Click OK to use the selected locales.

For more information on configuring locales, see the "Using Locales" section.

Note After you have activated these settings, only new subscribers will see the change. Any existing subscribers that have already selected a locale will continue to use the previously chosen locale. If the default locale for a neighborhood is changed and a subscriber was not previously presented the list, User Registrar will use the current default locale setting for account maintenance.

Configuring a Neighborhood for Shared Modems

There are two different modes available for provisioning modems in a neighborhood.

The standard mode is private, which means that for every subscriber there is a corresponding modem.
The alternate mode is shared, which means that multiple subscribers access the Internet through a single modem. You can use this mode in campus situations in which a single cable modem can be used for an entire dormitory floor. When you specify shared mode, User Registrar automatically configures new modems for shared access. As part of this configuration, you must associate the new modem with the neighborhood's account and service level.

To configure a neighborhood for shared access, do the following:

Step 1 From the Manage Defaults page, click Edit next to the name of the neighborhood you wish to edit.

Step 2 From the Edit Neighborhood page, change the default modem usage from private to shared.

Step 3 Enter the account number to associate the neighborhood with. This setting only affects shared modems registered from now on.

Step 4 Select the service level for shared modem. When subscribers access the system over unrecognized modems, User Registrar automatically configures the modems for this level.

Step 5 Click OK to change the neighborhood to the shared modem.

Once a neighborhood is configured for shared access, the User Registrar Administrator UI allows you to list all of the modems associated with a neighborhood and to reset modems as needed.

Determining a Subscriber's Neighborhood Automatically

User Registrar attempts to determine the neighborhood for a subscriber automatically. This algorithm is based on the provisioning elements defined in Modem Registrar. To base the determination of a neighborhood on subnets, configure the necessary subnet relationships in Modem Registrar.

To associate a neighborhood with a subnet, do the following:

Step 1 In Modem Registrar, click Option Sets from the Main Menu page.

Step 2 From the Configure Option Set list page, click Subnet.

Step 3 From the Subnet Option Set List page, locate the subnet option set you want to modify in the list of option sets and click its hypertext link.

Step 4 On the Edit Subnet Option Set page, select the desired neighborhood in the Default Neighborhood drop-down list.

Step 5 Click OK.

Repeat this process for all of subnets associated with neighborhoods. If a more general scoping can be used to define the default neighborhood for a portion of the network, the same steps apply to all of the Option pages.

In the example of a CSRC installation serving both residential and university neighborhoods, the residential neighborhood would likely be defined at a very broad level, for example, the Default Option Set of the CSRC Group Option Set, while the particular subnet (or subnets) used by the university would override that default setting.

Overriding the Modem's Default Provisioning Mode

Even though you typically configure the neighborhood modem usage to address the majority of configurations, you can still provision devices for the opposite usage mode. If the current mode is private, you can provision a shared asset in the neighborhood. If the current mode is shared, you can provision a private modem. Because these scenarios are, by definition, breaking the rules defined by the configuration, they cannot be accomplished automatically.

Creating a Shared Modem in a Private Neighborhood

To create a shared modem in a private neighborhood, do the following:

Step 1 From the Manage Defaults page, click Edit next to the name of the neighborhood you want to override.

Step 2 From the Edit Neighborhood page, supply the shared cable modem settings, that is, the account number and service.

Step 3 Click Shared Modems.

Step 4 From the Manage Shared Modems page, specify a MAC address and description.

Step 5 Click Add Modem.

Step 6 Repeat steps 4 and 5 for each shared modem.

Creating a Private Modem in a Shared Neighborhood

To create a private modem in a shared neighborhood, do the following:

Step 1 From the Manage Subscribers page, click Edit next to the subscriber whose modem setting you want to override.

Step 2 From the Edit Subscriber page, click private for Modem usage.

Step 3 Enter the Private modem MAC address, if you know it or leave it blank.

Step 4 Click OK.

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 of 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. For more information on extending the underlying CSRC object layer, refer to the "Schema Extensions," and "CSRC Schema."

Note 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 User Registrar attributes.

Table of Contents

Configuring User Registrar