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. Backup the NDS database and save the file. Use the database backup or ldap export. Note that using ldap export is preferred. For more information about using these commands see the NDS documentation.

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. Perform the following steps when the program asks you to stop the Directory Service:

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

(b) Edit the CSRC Configuration File (csrc.cfg) and add the following line to the end of the file:
DataStore.ExtSchema-FileName = csrc_conf_dir/csrc_schema_ext.dat where csrc_conf_dir is the path to the CSRC Configuration directory.

(d) Stop the CSRC application.

(e) 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 6-1 shows a sample object entry in the input file:

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

#Fields: 1-Application Schema Class, 2- Application Schema Attribute,
#        3- Storage Schema Attribute 4- Storage Schema Attribute Type, 5- Unique Key,
#      6- Required Attribute 7- Multi-valued 8- Attribute Source
#
#Account AccountNumber csrcaccountnumber STRING YES YES NO csrc
#Account PIN csrcpin STRING NO YES NO csrc
#Account LastName csrclastname STRING NO YES NO csrc
#Account FirstName csrcfirstname STRING NO YES NO csrc
#Account Dataset csrcdataset STRING NO NO NO csrc
#Account Version csrcversion STRING NO NO NO csrc
#Account MI csrcmi STRING NO NO NO csrc
#Account Salutation csrcsalutation STRING NO NO NO csrc
#Account Telephone csrctelephone STRING NO NO NO csrc
#Account Address csrcaddress STRING NO NO csrc
#Account City csrccity STRING NO NO NO csrc
#Account State csrcstate STRING NO NO NO csrc
#Account ZipCode csrczipcode STRING NO NO NO csrc
#Subscriber Username csrcusername STRING YES YES NO csrc
#Subscriber AccountNumber csrcaccountnumber STRING YES YES NO csrc
#Subscriber IsDisabled csrcisdisabled BOOLEAN NO YES NO csrc
#Subscriber Password csrcpassword STRING NO YES NO csrc
#Subscriber Dataset csrcdataset STRING NO NO NO csrc
#Subscriber Version csrcversion STRING NO NO NO csrc
#Subscriber ModemList csrcmodemlist OBJID NO NO YES csrc
#Subscriber DisabledReason csrcdisabledreason STRING NO NO NO csrc
#Modem MACAddress csrcmacaddress MAC YES YES NO csrc
#Modem AccountNumber csrcaccountnumber STRING NO YES NO csrc
#Modem Dataset csrcdataset STRING NO NO NO csrc
#Modem Version csrcversion STRING NO NO NO csrc
#Modem Description csrcdescription STRING NO NO NO csrc
#Modem ComputerList csrccomputerlist OBJID NO NO YES csrc
#Modem ServiceList csrcservicelist OBJID NO NO YES csrc
#Modem ServiceRuleList csrcservicerulelist OBJID NO NO YES csrc
#Modem ClientClass csrcclientclass STRING NO NO NO csrc
#Modem HostName csrchostname STRING NO NO NO csrc
#Modem DomainName csrcdomainname STRING NO NO NO csrc
#Modem PolicyName csrcpolicyname STRING NO NO NO csrc
#Modem Action csrcaction STRING NO NO NO csrc
#Modem AuthenticateUntil csrcauthenticateuntil STRING NO NO NO csrc
#Modem UnauthenticatedClientClassName csrcunauthenticatedclientclassname STRING NO NO NO
#csrc
#Modem UserDefined csrcuserdefined STRING NO NO NO csrc
#Modem EnvironmentDictionary csrcenvironmentdictionary STRING NO NO NO csrc
#Modem SelectionCriteria csrcselectioncriteria STRING NO NO NO csrc
#Modem SelectionCriteriaExcluded csrcselectioncriteriaexcluded STRING NO NO NO csrc
#Modem LeaseVersion csrcleaseversion STRING NO NO NO csrc
#Modem EmbeddedPolicy csrcembeddedpolicy STRING NO NO NO csrc
#Modem PreviousServiceList csrcpreviousservicelist OBJID NO NO csrc
#Modem ReadCommunityString csrcreadcommunitystring STRING NO NO NO csrc
#Modem WriteCommunityString csrcwritecommunitystring STRING NO NO NO csrc
#Computer AccountNumber csrcaccountnumber STRING NO YES NO csrc
#Computer MACAddress csrcmacaddress MAC YES YES NO csrc
#Computer Dataset csrcdataset STRING NO NO NO csrc
#Computer Version csrcversion STRING NO NO NO csrc
#Computer Description csrcdescription STRING NO NO NO csrc
#Computer ClientClass csrcclientclass STRING NO NO NO csrc
#Computer HostName csrchostname STRING NO NO NO csrc
#Computer DomainName csrcdomainname STRING NO NO NO csrc
#Computer PolicyName csrcpolicyname STRING NO NO NO csrc
#Computer Action csrcaction STRING NO NO NO csrc
#Computer AuthenticateUntil csrcauthenticateuntil STRING NO NO NO csrc
#Computer UnauthenticatedClientClassName csrcunauthenticatedclientclassname STRING NO NO
#NO csrc
#Computer UserDefined csrcuserdefined STRING NO NO NO csrc
#Computer EnvironmentDictionary csrcenvironmentdictionary STRING NO NO NO csrc
#Computer SelectionCriteria csrcselectioncriteria STRING NO NO NO csrc
#Computer SelectionCriteriaExcluded csrcselectioncriteriaexcluded STRING NO NO NO csrc
#Computer LeaseVersion csrcleaseversion STRING NO NO NO csrc
#Computer EmbeddedPolicy csrcembeddedpolicy STRING NO NO NO csrc
 
#  New  Entries Here
Subscriber  Preferred1  desc1   STRING  NO  NO  NO  csrc
Subscriber  Preferred2  desc2   STRING  NO  NO  YES mcd

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. 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 any value other than csrc, 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