Table of Contents

Overview of the UCP Data Architecture
Overview of the Data Transfer Process
Performing a Bulk Transfer of SMS Data into UCP

Creating the NCPTransfer Table in the SMS Database
Populating User Data in the NCPTransfer Table for Bulk Transfer
Initiating the Transfer from the Network Control Console

Loading Database Information into UCP

After you have installed the User Control Point (UCP) software, you must perform an initial bulk transfer of user information stored in your organization's Subscriber Management System (SMS) into the UCP database. This chapter presents an overview of the UCP data architecture and describes the steps you must follow to perform the bulk transfer.

• Overview of the UCP Data Architecture

• Overview of the Data Transfer Process

• Performing a Bulk Transfer of SMS Data into UCP

Overview of the UCP Data Architecture

UCP provides an interface to an Oracle database. Your organization can use the specification for this interface to connect your SMS to UCP.

• Data transfer table in the SMS database

• ActiveWeb database adapter (dbAdapter)

• SMS adapter

UCP includes a Structured Query Language (SQL) script (CrtNCPTr.sql) that creates an NCPTransfer table in an Oracle database. Triggers defined in the table publish SMS Transfer events. If your SMS runs on an Oracle database, you can use this script to create a data transfer table in your database. If you have another type of database, you can modify the script to update your database to include a similar data transfer table. (See Table 3-1 for a description of the data transfer table.)

The ActiveWeb database adapter (dbAdapter) provided with UCP connects to your SMS database and translates data sent to it by means of SQL queries into events that encapsulate user information.

The SMS adapter receives data events from the dbAdapter and publishes them over the Information Bus. The DS Adapter subscribes to these data events and uses the data encapsulated in the events to update the UCP Data Store (DS). The DS is an Oracle database used by the CiscoSecure Access Control Server (ACS) component of UCP, which provides authentication, authorization, and accounting (AAA) services.

The DS is one of the most important components that resides at the Network Operations Center (NOC), because the DS serves as the central repository of user identification, provisioning, and accounting information for the entire system.

A user is defined in the DS as an individual who seeks services extended by an Internet service provider (ISP). A user subscribes to services offered by the ISP and is granted related access rights when accessing the system. Each user is unaware of internal access control, identification, provisioning, and metering mechanisms; however, by default, UCP follows an incremental provisioning methodology. Most users belong to a group, and as part of that group, inherit the group access rights. Therefore, an individual user's access rights depend on the rights granted to the group of which the user is a member. A group automatically has access to certain services and is denied access to others; however, individual users can own additional rights to services.

Overview of the Data Transfer Process

When UCP is first deployed, the system administrator uses the Network Control Console (the NCC, described in Chapter 4) to initiate a data transfer from the SMS to the DS. To perform this data transfer, an NCPTransfer table must be defined in the SMS database using the dbinstall utility.

For more information about the script, see the section "Creating the NCPTransfer Table in the SMS Database" later in this chapter. (Table 3-1 shows the structure of the NCPTransfer table.)

Data in the Services1, Services2 and Services3 fields is a text string. The SMS Adapter subscribes to the Discover event; when it receives the event, it publishes an SMSGetInfo event already defined and configured in the Active Software Oracle dbAdapter (dbAdapter). The SMSGetInfo event is a database query event and does not have any fields. The dbAdapter executes a pre-defined query related to this event on the NCPTransfer table. Consequently, when records are returned, the dbAdapter delivers them one at a time to the SMS Adapter via an SMSTransfer event. The fields of the SMSTransfer event are the same as the columns of the NCPTransfer table.

In addition to the Discover event with the type field set to SMS_BULK_DATA_TRANSFER, the dbAdapter issues the SMSTransfer event whenever a new record is added to the NCPTransfer table. User NCPTransfer table records are a subset of the SMS database and hold relevant user identification, provisioning, and metering data. Based on a predefined dictionary, and the format of the data in the three Services fields, the SMS adapter module processes the information and fills out an event. The SMSadapter module encapsulates the records in a Transfer event and publishes it on the Information Bus. The name of this event is DSTransfer, and its format is described in Table 3-2.

For user records you intend to transfer:

1. Verify that the attributes you specify belong to a dictionary that exists in the /opt/ucp/raddb directory (assuming you installed UCP in /opt/ucp) and in the CiscoSecure ACS. Note that the dictionary name in all three locations is case-sensitive.

2. Verify that all specified attributes exist in both dictionaries---the CiscoSecure ACS dictionary and the flat-file dictionary in the /opt/ucp/raddb directory.

3. If you change the flat-file dictionary, you must stop and restart the SMSadapter.

The following is an example of an SQL insert statement:

Also note that the third token must either be reply_attributes or check_items. You can specify several attribute-value pairs within a Services field. However, the AV pairs must be separated by semicolons, and the last AV pair structure must end with a semicolon.

• As an ASCII file /opt/ucp/raddb/dictionary

• In the CiscoSecure ACS database

The strAttributes field of the DSTransfer event, which is a sequence of structures, is described in Table 3-3.

The DS Adapter, which subscribes to this event with a filter on the Transfer event's guidTo field, receives these events and calls the command-line interface (CLI) to carry out user record operations such as insert, update, and delete. The DS Adapter's globally unique identifier (GUID) should be provided for the SMS Adapter in its configuration process so that the SMS Adapter knows which DS Adapter to send the events to.

The SMS Adapter translates NCPTransfer table data to a format that conforms to the UCP data architecture requirements. The DS Adapter is vendor- and dictionary-neutral. It relies on the self-descriptive nature of the DSTransfer event attribute structure to obtain attribute information to construct corresponding CLI commands.

All the data in the DSTransfer event should be valid for the CiscoSecure ACS. Because the DS Adapter is dictionary-neutral, (therefore, there is no data validation check by the DS Adapter) and the CLI is extremely lenient on invalid attribute names and values, any inconsistent data from the DSTransfer event will likely get into the CiscoSecure ACS DBServer without any warning and potentially cause serious problems later.

The DS Adapter carries out user record insert and delete operations in a very straightforward fashion. In the case of a user record update, because the CLI does not support record update operations, the DS Adapter first sends a query to the
CiscoSecure ACS DBServer via the CLI to get the user record using the FQDN as the key, deletes the user record from the CiscoSecure ACS DBServer, merges the attributes from the DSTransfer event to the newly obtained user record, and inserts the new user record back to the CiscoSecure ACS DBServer. When you replace a user record, the DS Adapter simply deletes the user record from the CiscoSecure ACS DBServer based on its FQDN and inserts a new user record with the attributes exclusively from the DSTransfer event.

Performing a Bulk Transfer of SMS Data into UCP

This section describes the procedure for setting up your SMS to support bulk data transfer into UCP, and the steps for performing the transfer.

Creating the NCPTransfer Table in the SMS Database

Use the dbinstall utility to create tables in the Data Store. For more information, see the Cisco User Control Point Software Installation Guide.

If you have an Oracle database, run the script against your database to create an NCPTransfer table. If you have a database from another vendor, modify the script to work with that vendor's database system.

(See Table 3-1 for a description of the fields in the NCPTransfer table.)

Populating User Data in the NCPTransfer Table for Bulk Transfer

The NCPTransfer table must be populated with user data from SMS or other sources. Under normal conditions, each insertion and modification of any row in the table is designed to trigger an immediate incremental transfer to UCP.

You must turn this behavior off temporarily at initial system configuration so the initial batch mode bulk transfer of information can occur. To restore normal behavior, you must turn the incremental transfers back on after the initial bulk load.

After you have created the NCPTransfer table (by running the CrtNCPTr.sql script), and the events are imported and saved---but before inserting anything into the table---you must enter the following command to disable the SMSTransfer event while the SMS data is being inserted into the NCPTransfer table:

After inserting the SMS data into the NCPTransfer table, you must enable the SMSTransfer event by entering the following command:

From this point on, the SMSTransfer event is published every time a new record is inserted or updated.

You must modify the database to update the fields in the table from the appropriate tables in your SMS.

In addition, Cisco provides the source code for the SMS Adapter provided with UCP. This code is contained in the following files included on the UCP installation CD-ROM:

• smsconst.h

• iserver.h

• cserverimp.cpp

• ceventreceiver.h

• smsadapter.cpp

If you do not have an Oracle database, you might need to develop your own ActiveWeb application to communicate with your database. To do this, you must obtain a copy of the ActiveWeb software and the ActiveWeb C Adapter. The ActiveWeb C Adapter package contains a copy of the ActiveWeb C Programmer's Guide and Reference, which explains how to develop an ActiveWeb application.

Initiating the Transfer from the Network Control Console

After you have modified your SMS database to populate the NCPTransfer table, you can initiate a transfer from the Network Control Console (NCC).

If the data transfer doesn't happen automatically following installation, follow these steps to initiate the data transfer:

Step 1 In the NCC directory tree display, select the icon for the SMS Adapter.

Step 2 From the Service menu, select Start SMS Bulk Transfer.

The system performs the data transfer. Any errors are described in an Exception event saved to the error log.