How to Extend the Schema in Microsoft Metadirectory Services 2.2 SP1 (329306)

MORE INFORMATION

Method 1 relies on Compass. When you use this method, you use Compass to add new definitions directly to the directory. This method is the quickest method, and it requires that the MMS server is online during the whole procedure. You do not have to run any special programs. However, the schema extensions exist only inside the directory. Therefore, you cannot reload these extensions from a disk or transfer them to another MMS server.

Method 2 is file-based. When you use this method, all customizations must be limited to Custom.poi and Custom.oid because Microsoft reserves the right to make unilateral changes to the DB5attr.oid and Poid files. Also, the MMS server must be offline to apply these changes to the database. The advantage of this method is that you can easily reload from a disk or upgrade another MMS server by using these extensions.

The following sections describe how to add two new schema groupings, one for the new attribute and a second for the new object. These sections describe how to add the definitions and how to add new category markers for NWTraders in both the object and the attribute definition sections of the directory schema. These markers help to organize the schema and partition the extensions. The markers are named "ZON=NWTraders" and "ZAN=NWTraders."

Method 1 (Interactive): Use Compass to Customize the Current Directory Schema

When you perform this procedure, the MMS server must be online for the whole procedure.

First, add two new object entries, ZON=NWTraders and ZON=NWTraderPerson. To do so, follow these steps:

1. Log on to MMS as an MMS administrator.
2. In the left pane, click Bookmarks.
3. Click Management Agents.
4. In the right pane, double-click Objects.
   
   A series of sphere-shaped icons and their labels appear. Each icon represents a logical division in the set of object definitions.
5. Right-click Objects, and then click Insert.
6. Click the Administrative tab.
7. In the Relative Name box, type NWTraders.
8. Click the second sphere-shaped icon (the ToolTip for this icon is "Object"), and then click Insert.
9. In the OID (MANDATORY) box, type 2.16.128.113533.1.1200.100.
   
   Note This object identifier (also known as OID) value is not registered and is used only as an example.
10. In the Purpose of this object class box, type NWTraders schema object customizations.
11. Make sure that Type of Object Class is set to Auxiliary, and then click OK.
12. Click Cancel.
    
    A new icon named "NWTraders" appears.
13. Right-click NWTraders, and then click Insert.
14. Click the Administrative tab.
15. In the Relative Name box, type NWTraderPerson.
16. Click the second sphere-shaped icon (the ToolTip for this icon is "Object"), and then click Insert.
17. In the Distinguished Attribute box, type cn.
18. In the OID (MANDATORY) box, type 2.16.128.113533.1.1200.100.1.
    
    Note This object identifier value is not registered and is used only as an example.
19. In the Parent Object's Name box, type person.
20. Make sure that Type of Object Class is set to Auxiliary.
21. Click OK.
22. Click Cancel.

Second, add two new attribute entries, ZAN=NWTraders and ZAN=NWTraderPerson:

1. In the left pane, click Bookmarks.
2. Click Management Agents.
3. In the right pane, double-click Attributes.
   
   A series of sphere-shaped icons and their labels appear. Each icon represents a logical division in the set of attribute definitions.
4. Right-click Attributes, and then click Insert.
5. Click the Administrative tab.
6. In the Relative Name box, type NWTraders.
7. Click the first sphere-shaped icon (the ToolTip for this icon is "Attribute"), and then click Insert.
8. In the Full Attribute Name box, type NWTraders.
9. In the OID (MANDATORY) box, type 2.16.128.113533.1.1200.100.
   
   Note This object identifier value is not registered and is used only as an example.
10. In the Description box, type NWTraders schema attribute customizations.
11. Make sure that Values is set to Single.
12. Click OK, and then click Cancel.
    
    A new icon named "NWTraders" appears.
13. Right-click NWTraders, and then click Insert.
14. Click the Administrative tab, and then type NWTraderTitle in the Relative Name box.
15. Click the first icon (a picture of a hand touching a folder). The ToolTip for this icon is "Attribute".
16. Click Insert.
17. In the Full Attribute Name box, type NWTraderTitle.
18. In the OID box, type 2.16.128.113533.1.1200.200.1.
    
    Note This object identifier value is not registered and is used only as an example.
19. In the Syntax box, click T61STRING.
20. Make sure that Values is set to Single.
21. Click OK, and then click Cancel.

Method 2 (File-Based): Use Custom.oid, Poid, and Updoid.bat to Customize the Current Directory Schema

The following method requires that the MMS server is offline for some of the procedure.

First, add two new object grouping entries, ZON=NWTraders and ZAN=NWTraders:

1. Start Notepad, and then open the Zoomserv\Bin\Init\Oid\Custom.poi file.
   
   If the file does not exist, create one.
2. Scroll to the last entry in the file (if the file already contains custom attribute definitions). This line uses the following format:

   INFO,ATT,xx,XXXXXXXXXXXXXXXXXXXXXXXX,,

3. Add the following data on a single new line:

   INFO,ATT,NWTraders,NWTraders schema attribute customizations,,2.16.128.113533.1.1200.200

4. Scroll to end of the file (if the file already contains custom object definitions). This line uses the following format:

   INFO,OBJECT,xx,XXXXXXXXXXXXXXXXXXXX,,

5. Add the following data on a single new line:

   INFO,OBJECT,NWTraders,NWTraders schema object customizations,, 2.16.128.113533.1.1200.100

6. Save the file.
7. Quit Notepad.

Second, add two new schema definitions, ZON=NWTraderPerson and ZAN=NWTraderTitle:

1. Start Notepad, and then open the Zoomserv\Data\Attribs\Custom.oid file. If the file does not exist, create one.
2. Insert the following data as new lines. It is best to add the new entries at the end of the file.

   NWTraderPerson * 2.16.128.113533.1.1200.100.1 * person * auxiliary *
   
   NWTraderTitle * 2.16.128.113533.1.1200.200.1 * * * T61String S *

3. Save the file.
4. Quit Notepad.
5. Make sure that the MMS server has stopped completely.
   
   Note It may take up to 90 seconds for the MMS server to release all its resources internally.
6. Open a command prompt.
7. Change to the Zoomserv\Bin\Init\Oid folder.
8. At the command prompt, run the updoid command.
9. When the program has completed, restart the MMS server, and then log on as an administrator.
10. Verify that there are 4 new objects in the schema: Two instances of NWTraders (one for attributes and one for objects), NWTraderPerson, and NWTraderTitle.

Additional Information About the MMS Schema

How the MMS Schema Is Written to the Directory When You Run the UPDOID Command

When MMS is installed, the directory schema is loaded from various disk files through the Importt.exe program. The Updoid.bat batch file is used during the initial load and all subsequent reloads of the schema. After a schema definition has been created and added to the directory, do not remove it. This recommendation is based on the premise that there is no way to know if a schema object or attribute is used in the directory. Without a complete definition of the attribute or object, the directory cannot give the data a correct context. For example, the definition indicates whether the attribute stores text or binary information or whether the attribute is single or multi-valued.

Updoid.bat is located in the Zoomserv\Bin\Init\Oid folder. It uses Zoid.exe to combine the schema definitions that are found in the original Poid file and in the Db5attr.oid file with the custom extensions that are found in the Custom.poi and Custom.oid files and the associated icon bitmaps that are described in the Aoid file.

Files That Are Used to Define the MMS Schema

• In the default configuration, the following files make up the MMS schema:
  • Zoomserv\Data\Attribs\Db5attr.oid
  • Zoomserv\Bin\Init\Poid
  • Zoomserv\Bin\Init\Aoid
• All extensions to the MMS schema must be limited to changes in the following files:
  • Zoomserv\Data\Attribs\Custom.oid
  • Zoomserv\Bin\Init\Custom.poi
• The following files are used to load and maintain the MMS schema:
  • Zoomserv\Bin\Init\Oid\Updoid.bat:
    This command file is run to load the five file-based definitions (Db5attr.oid, Poid, Aoid, Custom.oid and Custom.poi) into the MMS directory.
  • Zoid.exe:
    This executable file is used during UPDOID to combine the five individual input files into a single input. There is a 127-character limit to the definition line length in MMS 2.2 SP1.
  • Import.exe:
    This executable file applies the single input file (created by Zoid) and creates the actual object and attribute definitions in the directory.
  • Chkoids.exe:
    This executable file may be used to verify the uniqueness of the schema definitions as they exist in the MMS directory.

MMS Schema Definition Syntax

In the Zoomserv\Data\Attribs\Db5attr.oid file, the following syntax definition shows how the object identifier and attribute definitions are formatted in the Custom.oid file. You do not have to configure all the fields. Use an asterisk (*) if a value is not required. Also, the remaining fields after the last defined field may be left blank. This translates into a "not defined" value for all the remaining fields.

; *     Name:              MANDATORY - The name of the object or attribute   *
; *     Abbreviation:      OPTIONAL  - The abbreviation (if any )for the     *
; *                                    attribute; if unspecified use "*"     *
; *     OID:               MANDATORY - The numerical identifier for the      *
; *                                    object or attribute                   *
; *     Assoc_OID:         OPTIONAL  - Associated OID                        *
; *     Parent:            OPTIONAL  - The name of the parent object         *
; *     Storage:           OPTIONAL  - The type of storage unit if not held  *
; *                                    as part of the database               *
; *                        Values:     'F' - File-based object               *
; *                                    'T' - Transient object                *
; *                                    'C' - Control object                  *
; *     Syntax:            MANDATORY - The attribute syntax                  *
; *     Type:              MANDATORY - Type of attribute                     *
; *                        Values:     'S' - Single value attribute          *
; *                                    'M' - Multi-value attribute           *
; *                                    'C' - Collective attribute            *
; *     pluginName:        OPTIONAL  - The name of dll applied to the        *
; *                                    attribute                             *
; *     HashType:          OPTIONAL  - The type of hash applied to the       *
; *                                    object                                *
; *                        Values:     'TextHash'                            *
; *                                    'BinaryHash'                          *
; *                                    'AttrTypeHash'                        *
; *                                    'CaselessHash'                        *
; *                                    'Encrypted'                           *
; *                                                                          *
				

The following data is an example of an object identifier attribute definition from the Db5attr.oid file: This data translates to the following information:

Name:			person		// this is the common name of the object
Abbreviation:		* 		// set only if it differs from the name value
OID:			2.5.6.6		// this string must be unique
Assoc OID:		* 		// not used for object definitions
Parent:			Top 		// the class from which this object was derived
Storage:                * 		// not used for object definitions
Syntax:			structural 	// must be either structural or auxiliary
Type:			*		// not used for object definitions
pluginName:		no value        // not used
HashType:		no value	// not used for object definitions
				

The following data is an example of an object identifier object class definition from the Db5attr.oid file: This data translates to the following information:

Name:			ou 		  // this is the common name of the attribute
Abbreviation:		ou 		  // set only if it differs from the name value
OID:			2.5.4.11          // this string must be unique
Assoc OID:		2.5.6.5           // this must reference an existing object class
Parent:			* 		  // not used for attribute definitions
Storage:                *                 // must be F, T, or C
Syntax:			CaseIgnoreString  // defines the type of data in the attribute
Type:			S 		  // must be S, M or C
pluginName:		* 	          // not used
HashType:               CaselessExact     // the way the data is processed in the hash tables
				

The following is an example of a POI entry from the POID file: This data translates to the following information:

Header:			INFO
info type:		ATT
cn:			Ms
description:            Microsoft Corporation MMS Registered Attributes
unused:			
printOID:		1.2.840.113556.1.6.7.1.0

Troubleshooting

Using Chkoids.exe to Verify the MMS Schema

In Zoomserv\Bin, you can use Chkoids.exe to verify the current directory schema. You can use following command-line switches when you run the chkoids command:

• -q: Fully qualify object identifiers.
• -r: Generate a report of all object identifiers.
• -u: Verify unique object identifiers.

When you use -q and -r, the following files are created:

• Zoomserv\Bin\Oidrep.zan
• Zoomserv\Bin\Oidrep.zon

The Zoomserv\Bin\Oidrep.zan file contains a listing of all standard attribute definitions, the Zoomserv\Bin\Oidrep.zon file contains a listing of all standard object definitions. The term "standard" is used to define all schema definitions that are not automatically added by MMS when a management agent (MA) parsing template is evaluated. For more information about how MMS automatically extends its schema, see the "Working with Directory Entries - Creating New Attributes or Object Classes" topic in the Microsoft Metadirectory Services System Administration Manual.

The -r switch produces a schema list that includes all the standard schema objects plus all the automatically extended object and attribute definitions. When you use the -u switch, a report is created that lists all schema definitions that contain non-unique object identifier values (Oidrep.unq). The following data shows the program's progress as it runs:

C:\zoomserv\bin>chkoids -u

...Initializing MMS
...Done initialization
...Verifying oids are unique
...Number of non-unique oids [2]
...Look at report file (oidrep.unq)

C:\zoomserv\bin>
				

The following report is created:

*************************************
* NON UNIQUE OIDS IN MMS
*************************************

2.16.128.113533.1.508
   DN 1: ZAN=zcEmployeeNumberCopy,ZAN=Basic,ZAN=zc,F=Attributes,DsaName=MMSServer,ou=Applications,o=People,dc=NWTraders,dc=com
   DN 2: ZAN=zcEmployeeNumber,ZAN=Basic,ZAN=zc,F=Attributes,DsaName=MMSServer,ou=Applications,o=People,dc=NWTraders,dc=com

2.16.128.113533.2.4
   DN 1: ZON=zcPersonCopy,ZON=Basic,ZON=zc,F=Objects,DsaName=MMSServer,ou=Applications,o=People,dc=NWTraders,dc=com
   DN 2: ZON=zcPerson,ZON=Basic,ZON=zc,F=Objects,DsaName=MMSServer,ou=Applications,o=People,dc=NWTraders,dc=com

				

This report indicates there are two problems: a duplicate object identifier string was used in a pair of attribute definitions, and another duplicate object identifier string was used in a pair of object definitions. To resolve these problems, a new object identifier string must be selected for one of the attribute definitions, and another new object identifier string must be selected for the object definition.

Reviewing Previous Versions of the MMS Schema

As part of its startup process, the MMS server dumps a snapshot of its current schema to disk. There may be up to seven previous dump files of the schema. Each dump file is named "OIDBACK," and each dump file has a numeric tag. The tags correspond to the day of the week; for example, 000 is Monday, and 001 is Tuesday. The date is irrelevant with respect to the tag; the date only indicates the day of the week when the file was created. If the MMS server has only ever been restarted on Mondays, only a single OIDBACK.000 file exists. However, you may be able to use these files to trace the evolution of the schema by comparing various OIDBACK files. The content of each file corresponds to the content that is produced by the -r switch of Chkoids.exe.