Schema Extensions

Overview of Schema Extensions

Creating Schema Extensions

Using the csrc_schema_add Program

Sample Object Entry

Schema Extensions

The Cisco Subscriber Registration Service (CSRC) Schema extensions allow you to extend CSRC without extensive programming.

You might extend the schema to do the following:

Have CSRC retain additional data associated with a subscriber, an account, or a cable modem
Have CSRC be responsible for both storing the data, and having it automatically available anytime the specific subscriber or account information is displayed or updated
Store subscriber-related information on another system, but have CSRC model or appear to manage the data while actually delegating the management of that information to another application or system, such as a billing or accounting system

All of these cases share the same requirement, which is that there is only one authoritative source for data items relating to CSRC data.

This chapter explains how to create extensions to extend CSRC. For a complete description of the CSRC schema, see "CSRC Schema."

Schema extensions provide a way for you to tell CSRC about additional attribute items that are not already defined and to change the authoritative source for any data item. To do this, you must manipulate a data file, which describes new attributes associated with existing CSRC storage objects.

To extend the schema in the Netscape Directory Service (NDS) server, do the following:

1. Make a copy of the data file and store it in a safe place.

2. Define the new data in the extended schema data file.

3. Run the csrc_schema_add.pl program, which creates additional data files, and informs both CSRC and the Netscape Directory Server of the new attributes.

4. If you want to install the changes, answer yes when the csrc_schema_add.pl program asks the question, "Do you want to install files to a permanent directory?"

5. Check the csrc_schema_add.pl program's error messages to verify that the CSRC object layer could successfully install, and integrate the changes into the CSRC and NDS environments.

6. If the program ran successfully and you want to install the changes:

(a) Make sure that no one is running CSRC.

(b) Stop the NDS.

(d) Restart NDS and CSRC.

You can also use the schema extensions with CSRC Customer Callout Modules (CCMs). The CSRC CCMs allow you to define extensions to the routines that retrieve data from persistent storage, as well as from routines that place attributes where they can be retrieved on demand.

The combined funtionality allows you to add new attributes, and to control the loading and storing of those attributes in the running CSRC application. For more information about CCMs, see "CSRC Callouts."

Note You can only run the csrc_schema_add.pl program against the original schema shipped with CSRC. If you anticipate making additions to the schema, keep a copy of the original schema and place all your cumulative additions into the new data file. If you want to remove an addition, simply omit it from the extended schema data file.

If you attempt to add attribute items to an already updated schema, the csrc_schema_add.pl program will tell you that the items already exist and refuse to write your changes.

Creating Schema Extensions

When you create a schema extension, CSRC does the following:

Configures NDS to support the new attributes
Updates the CSRC object layer about the new attributes
Makes the new attributes available to CSRC

To accomplish these tasks, the CSRC object layer reads the data file created by the csrc_schema_add.pl program, and appends the extended attributes to its built-in object/attribute tables.

Note CSRC provides a sample file (~conf/schema-ext.text.sample) containing all attributes for the limited set of released objects with clear notations as to where you can add new attributes.

Using the csrc_schema_add Program

The csrc_schema_add.pl program is a Perl script that uses the following syntax:

(perl /opt/csrc/conf/csrc_schema_add.pl <Input_File> <NDS Config_Directory> <csrc Config_Directory)

The program does the following:

Parses the data file you have edited
Validates your schema extensions
Appends the extension log to the log file
Prepares input files for the CSRC object layer and NDS

The csrc_schema_add.pl program validates your changes to reduce the likelihood of failure in NDS. The validation confirms the uniqueness of both the new attributes across the CSRC schema and the standard entries in the LDAP RFC schema.

Note You are making immediate modifications to the structure of NDS. If you define new required attributes then, as an immediate consequence, all objects of the specified class must contain that attribute. To avoid problems, ensure that your extensions use only allowed attributes.

The format of the data file follows these rules:

Written in ASCII
One line per attribute
A "#"character in the first character position of a line causes the line to be ignored
Fields in the line are space or tab delimited
All fields must be present on each line
Comments in the beginning of the file indicate the positioning and options for each field
Detected errors cause CSRC to display and log an informative message indicating the line number of the detected failure
If there are errors, CRSC does not create output files.

The csrc_schema_add.pl program takes three arguments: Input File, NDS config directory, and CSRC config directory.

For example:

perl csrc_schema_add.pl schema.txt /users/admin/netscape/server4/slapd_unixws/config /opt/csrc/conf

Sample Object Entry

Example 5-1 shows a sample object entry in the input file:

Example 5-1: Sample Object Entry in the Input File

#Fields: 1-Application Schema Class, 2- Application Schema Attribute,
#        5- Unique Key,
#        6- Required Attribute 7- Multi-valued 8- Attribute Source
#
#Account AccountNumber csrcaccount STRING YES YES NO csrc
#Account PIN csrcaccount STRING NO YES NO csrc
#Account LastName csrcaccount STRING NO YES NO csrc
#Account FirstName csrcaccount STRING NO YES NO csrc
#Account Dataset csrcaccount STRING NO NO NO csrc
#Account Version csrcaccount STRING NO NO NO csrc
#Account MI csrcaccount STRING NO NO NO csrc
#Account Salutation csrcaccount STRING NO NO NO csrc
#Account Telephone csrcaccount STRING NO NO NO csrc
#Account Address csrcaccount STRING NO NO csrc
#Account City csrcaccount STRING NO NO NO csrc
#Account State csrcaccount STRING NO NO NO csrc
#Account ZipCode csrcaccount STRING NO NO NO csrc
#Subscriber Username csrcsubscriber STRING YES YES NO csrc
#Subscriber AccountNumber csrcsubscriber STRING YES YES NO csrc
#Subscriber IsDisabled csrcsubscriber BOOLEAN NO YES NO csrc
#Subscriber Password csrcsubscriber STRING NO YES NO csrc
#Subscriber Dataset csrcsubscriber STRING NO NO NO csrc
#Subscriber Version csrcsubscriber STRING NO NO NO csrc
#Subscriber ModemList csrcsubscriber OBJID NO NO YES csrc
#Subscriber DisabledReason csrcsubscriber STRING NO NO NO csrc
#Modem MACAddress csrccablemodem MAC YES YES NO csrc
#Modem AccountNumber csrccablemodem STRING NO YES NO csrc
#Modem Dataset csrccablemodem STRING NO NO NO csrc
#Modem Version csrccablemodem STRING NO NO NO csrc
#Modem Description csrccablemodem STRING NO NO NO csrc
#Modem ComputerList csrccablemodem OBJID NO NO YES csrc
#Modem ServiceList csrccablemodem OBJID NO NO YES csrc
#Modem ServiceRuleList csrccablemodem OBJID NO NO YES csrc
#Modem ClientClass csrccablemodem STRING NO NO NO csrc
#Modem HostName csrccablemodem STRING NO NO NO csrc
#Modem DomainName csrccablemodem STRING NO NO NO csrc
#Modem PolicyName csrccablemodem STRING NO NO NO csrc
#Modem Action csrccablemodem STRING NO NO NO csrc
#Modem AuthenticateUntil csrccablemodem STRING NO NO NO csrc
#Modem UnauthenticatedClientClassName csrccablemodem STRING NO NO NO
#        csrc
#Modem UserDefined csrccablemodem STRING NO NO NO csrc
#Modem EnvironmentDictionary csrccablemodem STRING NO NO NO csrc
#Modem SelectionCriteria csrccablemodem STRING NO NO NO csrc
#Modem SelectionCriteriaExcluded csrccablemodem STRING NO NO NO csrc
#Modem LeaseVersion csrccablemodem STRING NO NO NO csrc
#Modem EmbeddedPolicy csrccablemodem STRING NO NO NO csrc
#Modem PreviousServiceList csrccablemodem OBJID NO NO csrc
#Modem ReadCommunityString csrccablemodem STRING NO NO NO csrc
#Modem WriteCommunityString csrccablemodem STRING NO NO NO csrc
#Computer AccountNumber csrccomputer STRING NO YES NO csrc
#Computer MACAddress csrccomputer MAC YES YES NO csrc
#Computer Dataset csrccomputer STRING NO NO NO csrc
#Computer Version csrccomputer STRING NO NO NO csrc
#Computer Description csrccomputer STRING NO NO NO csrc
#Computer ClientClass csrccomputer STRING NO NO NO csrc
#Computer HostName csrccomputer STRING NO NO NO csrc
#Computer DomainName csrccomputer STRING NO NO NO csrc
#Computer PolicyName csrccomputer STRING NO NO NO csrc
#Computer Action csrccomputer STRING NO NO NO csrc
#Computer AuthenticateUntil csrccomputer STRING NO NO NO csrc
#Computer UnauthenticatedClientClassName csrccomputer STRING NO NO NO
#        csrc
#Computer UserDefined csrccomputer STRING NO NO NO csrc
#Computer EnvironmentDictionary csrccomputer STRING NO NO NO csrc
#Computer SelectionCriteria csrccomputer STRING NO NO NO csrc
#Computer SelectionCriteriaExcluded csrccomputer STRING NO NO NO csrc
#Computer LeaseVersion csrccomputer STRING NO NO NO csrc
#Computer EmbeddedPolicy csrccomputer STRING NO NO NO csrc
 
 
Subscriber  VideoService csrcvideoservice  STRING  NO  NO  NO  csrc
Subscriber  VideoPPV  ccvideoppv   STRING  NO  NO  YES cc

Enter Yes in the Unique Key field if you want CSRC to ensure that only one instance of the indicated object (Subscriber above) contains an attribute with the given value. You will not want to do this for fields in which duplicates would cause serious consistency errors in the application.

CSRC uses the Attribute Source field to tell the CSRC object layer where the attribute permanently resides.

If the field contains the value csrc, the CSRC object layer stores the attribute in the CSRC LDAP Data Store.
If the field contains another value, then the CSRC object layer expects the attribute to be sourced from a Customer Callout Module (CCM).

: For all CCM-supplied attributes, you must specify No for the Required Attribute and the Unique Key fields. The CSRC object layer makes no attempt to read or write these attributes to the CSRC LDAP Data Store.

On a successful validation the script produces these files:

<csrc config directory>/conf/csrc_schema_ext.dat---A file that is similar to the data file with some substituted coded fields and comment lines stripped out. CSRC reads the file at startup and adds the attributes to the internal tables.

Note

~netscape/slapd-servername/config/csrc_ext.at.conf---CSRC formats this file according to standard NDS 4.0 attribute configuration files, and places it in the NDS config area. CSRC also adds a line to the "~netscape/slapd-servername/config/slapd.at.conf" file to #include the new attributes.
/opt/csrc/conf/CSRC_Attribute_Extension.log---CRSC appends this file with detailed timestamped records of attempted and completed attribute changes. The file remains in the /opt/csrc/conf/ directory, and is never truncated.

Table of Contents