Previous     Contents     Index          Next     
Directory Server Access Management Edition Programmer's Guide



Chapter 2   DSAME And XML


iPlanet Directory Server Access Management Edition (DSAME) uses Extensible Markup Language (XML) files for the integration and management of services. This chapter provides information on the XML service files installed with DSAME and the Document Type Definition (DTD) files used for creating new XML service files for the management of custom services. It contains the following sections:



Overview

A service is a group of attributes, defined in an XML file, that are managed together by the DSAME console. The attributes can be the configuration parameters of a software module or they might just be related information with no relation to a software configuration. As an example of the first scenario, after creating a payroll module, a developer defines an XML service file that might include attributes to define an employee name, an hourly pay rate and a tax percentage. This file is imported into the iPlanet Directory Server (DS) so the attributes and their values can be stored. When the service is registered to an organization in DSAME, the attributes can be managed using the DSAME console.


Note Throughout this chapter, the term attribute is used as a modifier for two different concepts. A DSAME or service attribute refers to the configuration parameters of a defined service. An XML attribute refers to the parameters that qualify an XML element in the XML service files.



XML Service Files

XML service files enable DSAME to manage attributes that are stored in DS. DSAME does not implement any behavior or dynamically generate any code to interpret the attributes; it can only set or get attribute values. Out-of-the-box, DSAME loads a number of services to manage the attributes of its own internal modules. This includes, but is not limited to, the Logging, Authentication and User services. In addition to managing these attributes, DSAME provides code implementations to use them. For example, the URL Policy Access attributes are displayed and managed in the DSAME console, but the web agent itself is the code implementation using them to check user access to URLs. All DSAME-internal XML service files are located in Install_Directory/SUNWam/config/xml. For more specific information on the internal XML service files, see "Internal XML Service Files".


Note Any application with LDAP attributes can have data managed using the DSAME console by configuring a custom XML service file and loading it into the DS. For more information, see "Defining A Service".



Document Type Definition Files

The format of an XML file is based on a structure defined in a DTD file. In general, a DTD file defines the elements and qualifying attributes needed to write a well-formed and valid XML document. DSAME exposes two DTD files which are used to define the structure for different types of XML files: sms.dtd and amadmin.dtd. The sms.dtd defines the structure for XML service files and the amAdmin.dtd defines the structure for XML files that are used to perform batch LDAP operations on the directory information tree (DIT) using the command line executable amAdmin. The DTDs are located in Install_Directory/SUNWam/dtd.


Note Knowledge of XML is necessary to understand the DTD elements and how they are integrated into DSAME. When creating an XML file, it might be helpful to print out the relevant DTD and a sample XML file made from the DTD.




Service Definition and Integration


Service Management in DSAME provides a mechanism for administrators to define, integrate and manage groups of attributes as a DSAME service. Readying a service for management involves creating an XML service file, configuring an LDIF file with any new object classes and importing both, the XML service file and the new LDIF schema, into the DS. Administrators can then register multiple services to organizations or sub-organizations using the DSAME console. Once registered, the attributes can be managed and customized per organization.


Note The only reason to create an XML service file is to group attributes to be managed using DSAME. If, for example, a software module has no attributes that need to be configured, no file is needed.


The following sections contain general information on DSAME service attributes as well as steps on how to define a service from configuration to registration.


Service Attributes

Services have different types of attributes. The sms.dtd structure enforces a service developer to define attributes as one of five types. The following sections provide descriptions of the five attribute types.


Global Attributes

Global attributes are defined for the DSAME installation and are common to all data trees, service instances and integrated applications within the configuration. Global attributes can not be applied to users, roles or organizations as their purpose is to configure the DSAME itself. Server names, port numbers, service plug-ins, cache size, and maximum number of threads are examples of global attributes that are configured with one value. For example, when DSAME performs logging functions, the log files are written into a directory. The location of this directory is defined as a globally in the Logging service and all DSAME logs, independent of their purpose, are written to it. DSAME administrators can modify these default values through the Service Management page in the DSAME console. Global attributes are stored as an XML blob within an attribute of an LDAP object. Therefore, they do not need to be defined with a DS LDAP schema.


Note If a service has only global attributes, it can not be registered to an organization nor can a service template be created.



Organization Attributes

Organization attributes are defined and assigned at the organization level. Attributes for an Authentication service are a good example. When an Authentication service is registered, the attributes are configured depending on the organization to which it is registered. The LDAP Server and the DN To Start User Search would be defined at the organization level as this information would be different depending on the address of an organization's LDAP server and the structure of their DIT, respectively. Organization attributes are stored as an XML blob within an attribute of an LDAP object. Therefore, they do not need to be defined with a DS LDAP schema.


Note Organization attributes are not inherited by sub-organizations. Only dynamic and policy attributes can be inherited. For additional information, see "Attribute Inheritance".



Dynamic Attributes

Dynamic attributes are inheritable attributes that work at the role and organization levels as well as the sub-organization and organizational unit levels. Services are assigned to organizations; roles have access to any service assigned to its parent organization. The dynamic attributes are then inherited by users that possess the role or belong to the organization. Because the attributes are assigned to roles or organizations instead of set in a user entry, they are virtual attributes inherited by users using Class of Service (CoS). When these attributes change, the administrator only has to change them once, in the role or organization, instead of a multitude of times in each user entry.


Note Dynamic attributes are modeled using class of service (CoS) and roles, both features of the iPlanet Directory Server. For information on these features, see Chapter 8 "iPlanet Directory Server And DSAME" or refer to the iPlanet Directory Server documentation.


An example of a dynamic attribute might be the address of a common mail server. Typically, an entire building might have one mail server so each user would have a mail server attribute in their entry. If the mail server changed, every mail server attribute would have to be updated. If the attribute was in a role that each user in the building possessed, only the attribute in the role would need to be updated. Another example might be the organization's address. Dynamic attributes are stored within the DS as LDAP objects, making it feasible to use traditional LDAP tools to manage them. A DS LDAP schema needs to be defined for these attributes.


Policy Attributes

Policy attributes are a special type of dynamic attribute. The main difference is that policy attributes provide a way to control resource access by defining a user's permissions. These defined permission attributes are then used to create named policy. For example, allowURLList is a named policy that defines a list of URLs a user is allowed to access; *.red.iplanet.com, *.eng.sun.com are the permitted URLs defined as policy attributes. Named policies are assigned to roles or organizations; once assigned, the policy attribute is available in the user entry as an LDAP attribute, making it feasible to use traditional LDAP tools to manage them. (Named policies are not stored within the DS as LDAP objects.) A DS LDAP schema needs to be defined for these attributes.

Currently, DSAME has only two services that use policy attributes: URL Policy Agent and URL Domain Access. (Additionally, there is a sample mail service that uses policy attributes. For information on this sample, see "SampleMailService Files".)


Caution

Do not use the policy.dtd to define policy schema for a service. It is used internally for Policy Management.



User Attributes

User attributes belong specifically to a single user. User attributes are not inherited from the role, organization, or sub-organization levels. They are typically different for each user, and any changes to them would affect only the particular user. Examples of user attributes could be an office telephone number, a password or an employee ID. The values of these attributes would be set in the user entry and not in a role or organization. User attributes can be a part of any service although DSAME has grouped a number of them into their own service defined by the amUser.xml service file. User attributes are stored within the DS as LDAP objects, making it feasible to use traditional LDAP tools to manage them. A DS LDAP schema needs to be defined for these attributes.


Note When defining user attributes in an XML service file other than amUser.xml, the service must be explicitly assigned to the user in order to display the attributes on the User's Profile page. In addition, the User Profile Display Option (defined in the Administration service) must be set to Combined. For more information, see the iPlanet Directory Server Access Management Edition Administration Guide.



Default Values

When a developer is writing an XML service file, default values can be defined for each attribute. After an XML service file is loaded into the DS, the default values can be displayed in the Service Management console. An organization can then register the service and create a service template where the default values can be modified. For example, all templates for the LDAP Authentication service use the port attribute. A default value of 389 could be defined in the XML service file and displayed on the LDAP Authentication Service Management page. Once registered to an organization, this value can be modified for the organization using the DSAME console. Default values are also used by integrated applications when a service template has not been created for an organization's registered service. For more information, see the "ChoiceValues Sub-Element" and the "DefaultValues Sub-Element".


Attribute Inheritance

After creating and loading an XML service file, an administrator can assign the service's organization, dynamic and policy attributes by registering the service to an organization and creating a service template. The service, once registered, can be assigned to sub-organizations or a role. (Any number of services can be assigned to these objects.) When a user possesses a role or belongs to an organization which possesses a service, the user inherits the dynamic and policy attributes or the organization, dynamic and policy attributes, respectively. Inheritance only occurs, though, if the service possessed is also explicitly assigned to the user. A user can inherit attributes from multiple roles or parent organizations.


Note Attributes defined as User have no inheritance; they are set and modified in each User entry. For example, if 70 attributes are defined as User and an organization has two million users, each attribute is stored two million times.



ContainerDefaultTemplateRole

Dynamic and policy attributes are used in an XML service file if an administrator wants to define a service in which all DSAME user objects, with the specified service assigned to them, would inherit those attributes. After uploading the XML service file and assigning the service to an organization or role, all users in the sub-trees, with the specified service assigned to them, will inherit the dynamic and policy attributes. To accomplish this, DSAME uses classic CoS (as described in Chapter 8 "iPlanet Directory Server And DSAME) and role templates. ContainerDefaultTemplateRole is a default filtered role configured for each organization. The filter is objectClass=iplanet-am-managed-person. Since every user object in DSAME carries this attribute, every person in the organization possesses this role. DSAME then creates a separate CoS template for each registered service which points to the service's default attributes. Any user who has the role will then get all the dynamic and policy attributes.


Defining A Service

The following procedures must be completed in order to use the DSAME console to integrate and manage a new service. They include creating or modifying XML files and registering these files using the amadmin command line executable.

  1. Create an XML service file for the component.

    This XML file must conform to the sms.dtd. A simple way to create a new XML service file would be to copy and modify an existing one. The file syntax can be found in "The sms.dtd Structure".

  2. Extend the LDAP schema in the DS using ldapmodify, if necessary.

    Loading an LDIF file into the DS will add any new or modified object classes and attributes to the DIT. This step is only necessary when defining dynamic, policy and user attributes. Instructions on extending the LDAP schema can be found in "Extending The Directory Server Schema". See the Directory Server documentation for additional information.

  3. Import the XML service file into DS using amadmin using the --schema or -S option.

    Information on importing an XML service file can be found in "Importing the XML Service File".

  4. Configure a localization properties file and copy it into the Install_Directory/SUNWam/locale directory.

    The localization properties file must be created with accurate i18nKey fields that map to names defined in the XML service file. If no localization properties file exists, DSAME will display the actual attribute names. More information on the localization properties file can be found in "Configuring Localization Properties".

  5. Update the amEntrySpecific.xml or amUser.xml files, if necessary.

    The amEntrySpecific.xml file defines the attributes that will display on the Create, Properties and Search pages specific to each of the DSAME abstract objects. Information on updating amEntrySpecific.xml can be found in "Abstract Objects and amEntrySpecific.xml". The amUser.xml file can be modified to add User attributes to the User service; alternately, User attributes can be defined in the actual XML service file. In the latter case, amUser.xml would not need to be modified. Information on modifying amUser.xml can be found in "Modifying An Internal XML Service File".

  6. Register the service.

    After importing the service into DS, it can be registered and the attributes managed through the DSAME console. Information on how this can be done is in the iPlanet Directory Server Access Management Edition Administration Guide. Information on how to register using the command line can be found in "Registering the Service".


Extending The Directory Server Schema

When configuring an XML service file for DSAME, it might also be necessary to extend the DS schema. Any dynamic, policy or user attributes defined in a DSAME service that are not already in the DS schema need to be added as LDAP object classes in order to store the data. This is done using the ldapmodify command line executable and an LDIF file as input.


Note The order in which the LDAP schema is extended or the XML service file is loaded into DS is not important. Just remember that when a new service is loaded into DS, a complementary LDIF file should be created to load any new LDAP object classes.


  1. Change to the DSAME bin directory.

    cd Install_Directory/SUNWam/bin

  2. Create an LDIF file to define any new or modified LDAP object classes.

  3. Run ldapmodify using the LDIF file as input.

    ldapmodify -D userid_of_DSmanager -w password -f path_to_LDIF_file

    By default, userid_of_DSmanager is cn=Directory Manager. If the schema was created correctly, the result of this command would be Modifying entry cn=schema.


    Note After extending the schema using ldapmodify, it is not necessary to restart the DS. But, as ldapmodify is server-specific, the schema will not replicate and therefore needs to be extended on all configured servers. Additional information can be found in the iPlanet Directory Server documentation.


  4. Run ldapsearch to ensure that the schema has been created.

    ldapsearch -b "cn=schema" -s base -D userid_of_DSmanager -w password "(objectclass=*)" | grep -i "servicename"

    If the schema was created correctly, the result of this command would be an LDIF listing of the object classes as displayed in Code Example 2-1 below.

    Code Example 2-1    Sample Mail Service LDAP Object Class


Adding Object Classes To Existing Users
If a new service is created and the service's users already exist, the object classes need to be added to the user entries. In order to do this, DSAME provides migration scripts for performing batch updates to user entries in the DIT. No LDIF file need be created when using them. These scripts are described in the iPlanet Directory Server Access Management Edition Installation and Configuration Guide. Additionally, registered services can be added to each user by selecting the service from the specific user's Properties page.

To modify user entries using ldapmodify, an LDIF file would need to be created. Code Example 2-2 shows how a user entry would be formatted in the LDIF file. This entry is having the object class iplanet-am-sample-mail-service and its attributes added.

Code Example 2-2    Sample LDIF File To Modify User Object
changetype:modify
add:objectclass
objectclass:iplanet-am-sample-mail-service
...

After creating the LDIF file, run ldapmodify as shown:

Install_Directory/SUNWam/bin/ldapmodify -D userid_of_DSmanager -w password -f path_to_LDIF_file.

For more information on ldapmodify and user entries, see the iPlanet Directory Server documentation.


Note It is not recommended to use ldapmodify to create any entries for DSAME other than user entries.



Verifying The Directory Server Modification
To verify that the DIT has been populated correctly, an administrator can use ldapsearch or the following:

  1. Change to the DS install directory:

    cd /DS_Install_Directory/slapd-DShostname

  2. Export the DS contents into an LDIF file using:

    db2ldif -s orgnamingattribute=top_level_org_name

    This command results in the name of the LDIF file stored under DS_Install_Directory/slapd-DShostname/ldif. This file can be viewed to ensure that the objects described in the LDIF file have been created.


Importing the XML Service File

After creating an XML service file following the instructions in "DSAME DTD Files", the new service file needs to be imported into the DS.

  1. Change to the DSAME install directory:

    cd Install_Directory/SUNWam/bin

  2. Run:

    ./amadmin --runasdn DNofDSadministrator --password passwordDSadministrator --verbose --schema xmlservicefilepath


    Note If changing an existing service, the original XML service file needs to be deleted before importing the modified XML service file.



Configuring Localization Properties

A localization properties file specifies the locale-specific screen text and messages that an administrator or user will see when directed to a service's attribute configuration page. The files are located in the Install_Directory/SUNWam/locale/ directory.

Code Example 2-3    Sample Mail Service Localization Properties File
a1=Mail Status
a2=Root Folder
a3=Sent Messages Folder
a4=Reply Prefix
a5=Initial Headers to Load
a6=Check New Mail Interval (minutes)
a7=Automatic Message Load at Disconnect
a8=Headers Per Page
p1=Mail Quota
p2=Auto-download Maximum Attachment Length
p3=Save Address Book on Server

The localization properties files consist of a series of key/value pairs. The value of each pair will be displayed on the service's Properties page in the DSAME console. The keys (a1, a2, etc.) map to the i18nKey attribute fields defined for a service. Code Example 2-3 is the localization properties file for DSAME's sample mail service. The keys also determine the order in which the fields are displayed, taken in alphabetical and then numerical order (a1, a2 is followed by b1, b2 and so forth). Note that the keys are strings, so a10 comes before a2.


Note If modifying a localization properties file, DSAME needs to be restarted. If importing a new service, DSAME does not need to be restarted to recognize the localization properties file.



Identifying The Localization Properties File
DSAME also needs to be able to locate the localization properties file. An administrator needs to ensure that it is located in the default Install_Directory/SUNWam/locale directory. If the file is kept in another directory, the jvm.classpath= entry in the jvm12.conf file needs to be modified to include the new directory pathname.


Note If the jvm12.conf file is modified, the DSAME server needs to be restarted.



Registering the Service

The preferred way to register a service is to use the DSAME console. Information on how this is done can be found in the iPlanet Directory Server Access Management Edition Administration Guide. Alternately, services can be registered using the amadmin command line executable.

  1. Change to the DSAME install directory:

    cd Install_Directory/SUNWam/bin

  2. Run:

    amadmin --runasdn DNofDSAMEadministrator --password passwordDSAMEadministrator --schema path_to_xmlservicefile



DSAME DTD Files

DSAME contains two DTD files which are used to define the structure for XML files used within the configuration. The sms.dtd defines the structure for XML service files and the amAdmin.dtd defines the structure for XML files that are used to perform batch LDAP operations on the directory information tree (DIT) using the command line executable amAdmin. The DTDs are located in Install_Directory/SUNWam/dtd.


Caution

Neither of these DTD files should be modified in any way. They contain rules and definitions that control how certain operations are performed on the DIT and any alterations might hinder them.


Code Examples. DSAME comes with the files needed to integrate a mail service into the configuration. These sample files are used throughout this section to illustrate the DTD concepts. For more information on these files, see SampleMailService Files"SampleMailService Files".


The sms.dtd Structure

The sms.dtd defines the data structure for all XML service files. It is located in the Install_Directory/SUNWam/dtd directory. The sms.dtd enforces the developer to define each attributes as one of five schema types which are then stored and managed differently. For instance, some of the attributes are applicable to an entire DSAME installation (such as a port number or server name), while others are applicable only to individual users (such as a password). The attribute types are:

  • Global

  • Organization

  • Dynamic

  • User

  • Policy

An explanation of the elements defined by the sms.dtd follows. Each element includes a number of XML attributes which are also explained. DSAME currently supports only about 20% of the elements contained in sms.dtd; this section discusses only those elements.


Note Customized attribute names in XML service files should be written in lower case as DSAME converts all attribute names to lower case when reading from the DS.



ServicesConfiguration Element

ServicesConfiguration is the root element of the XML service file. It's immediate sub-element is Service. Code Example 2-4 is the ServicesConfiguration element as defined in the sampleMailService.xml.

Code Example 2-4    Element ServicesConfiguration and Element Service
<Service name="sampleMailService" version="1.0">
<Schema...>
...


Service Element

The Service element defines the schema for a given service. Multiple services can be defined in a single XML file with this element, but it is recommended that only one be defined per XML service file. Currently, DSAME supports the sub-element Schema which, in turn, defines DSAME attributes as either Global, Organization, Dynamic, User or Policy. The required XML service attributes for the Service element are the name of the service, such as iPlanetAMLoggingService, and the version number of the XML service file itself. Code Example 2-4 illustrates the Service element and its attributes as defined in the sampleMailService.xml.


Schema Element

The Schema element is the parent of the elements that define the service's specific DSAME attributes (global, organization, dynamic, user or policy) and their default values. The sub-elements can be Global, Organization, Dynamic, User or Policy. The required XML attributes of the Schema element include serviceHierarchy which defines where the service will be displayed in the DSAME console, i18nFileName which defines the name of the localization properties file, and i18nKey which defines the attribute in the localization properties file from which this particular defined value will be taken.


Note The Schema element is required in XML service files.



serviceHierarchy Attribute
When adding a service, this attribute must be defined in order to display the service in the DSAME console. When a new service is registered, it is dynamically displayed based on this value. The value is a "/" separated string. Code Example 2-5 illustrates the serviceHierarchy attribute as defined in the sampleMailService.xml. The name sampleMailService is used to find the localization properties file which defines what will be displayed below the Other Configuration header in the DSAME console.

Code Example 2-5    i18nFileName, i18nKey and serviceHierarchy Attributes
...
<Schema
serviceHierarchy="/other.configuration/sampleMailService"
i18nFileName="sampleMailService"
i18nKey="iplanet-am-sample-mail-service-description">
...


i18nFileName And i18nKey Attributes
These two XML attributes both refer to the localization properties files. The i18nFileName attribute takes a value equal to the name of the localization properties file for the defined service (minus the .properties file extension). The i18nKey is a text string that maps to a property value defined in the localization properties file (specified, as discussed, in the i18nFileName attribute.) For example, Code Example 2-5 defines the name of the properties file as sampleMailservice and the text-based value of the i18nKey maps to its final value as defined in sampleMailservice.properties. The final value is the name of the service as it will be displayed in the DSAME console; in this case, Sample Mail Service Profile is the name defined in sampleMailservice.properties. More information on the localization properties file can be found in Configuring Localization PropertiesConfiguring Localization Properties"Configuring Localization Properties" of Chapter 3 "User Authentication With DSAME."


Schema Sub-Elements

The next five elements are sub-elements of Schema; they are the declarations of the service's DSAME attributes. When defining a service, each attribute must be defined as one of these types: Global, Organization, Dynamic, Policy and User. Any configuration (all or none) of these elements can be used depending on the service. Each DSAME attribute defined within these elements is itself defined by the sub-element AttributeSchema or, in the case of Policy, the ActionSchema.


Global Element
The Global element defines DSAME attributes that are modifiable on a platform-wide basis and applicable to all instances of the service in which they are defined. They can define information such as port number, cache size, or number of threads, but Global elements also define a service's LDAP object classes. For additional information, see "Global Attributes".

serviceObjectClasses Attribute. The serviceObjectClasses attribute is a global attribute in each XML service file that contains dynamic or policy attributes. This optional attribute is used by the SDK to set the object class for the service in the user entries. When an organization registers a service with the serviceObjectClasses attribute defined, the service's dynamic or policy attributes, if any exist, are automatically assigned to any user object which has been assigned the service. If the serviceObjectClasses attribute is not specified and the service has defined dynamic or policy attributes, an object class violation is called when an administrator tries to create a user under that organization.

Multiple values can be defined for the serviceObjectClasses attribute. For example, if a service is created with two attributes each from three different object classes, the serviceObjectClasses attribute would need to list all three object classes as DefaultValues. Code Example 2-6 has two defined object classes.

Code Example 2-6    serviceObjectClass Defined As Global Element
<AttributeSchema name="serviceObjectClasses"
type="list"
syntax="string"
i18nKey="">
<DefaultValues>
<Value>iplanet-am-sample-mail-service</Value>
<Value>iplanet-am-other-sample-service</Value>
</DefaultValues>
</AttributeSchema>
</Global>
...


Organization Element
The Organization element defines DSAME attributes that are modifiable per organization or sub-organization. For example, a web hosting environment using DSAME would have different configuration data defined for each organization it hosts. A service developer would define different values for each organization attribute per organization. These attributes are only accessible using the DSAME SDK. For additional information, see "Organization Attributes".


Dynamic Element
The Dynamic element defines DSAME attributes that can be inherited by all user objects. Examples of Dynamic elements would be user-specific session attributes, a building number, or a company mailing address. Dynamic attributes always use the DS features, CoS (Class Of Service) and Roles. For additional information, see "Dynamic Attributes".


User Element
The User element defines DSAME attributes that exist physically in the user entry. User attributes are not inherited by roles or organizations. Examples include password and employee identification number. They are applied to a specific user only. For additional information, see "User Attributes".


Policy Element
The Policy element defines DSAME attributes intended to provide privileges. This is the only attribute element that uses the ActionSchema element to define its parameters as opposed to the AttributeSchema element. Generally, privileges are get, post, and put; examples include canChangeSalaryInformation and canForwardEmailAddress. See Code Example 2-8 for an example of a Policy schema definition from the sampleMailService.xml file. For additional information, see "Policy Attributes".


SubSchema Element

The SubSchema element can specify multiple subschemas of global information for different defined applications. For example, logging for a calendar application could be separated from logging for a mail service application. Another example would be a service developer defining choice values for different logging levels. For logging type, choice values can be defined to specify output that goes to a file, JDBC, or some other LDAP output mechanism. The attribute multiple_choice represents a list of choice values. The choice values could represent multiple values, so that if the attribute values do not contain multiple choice values, then the SMS parsing would fail.


Note The Service SubSchema element is used only in the amEntrySpecific.xml file. It should not be used in any external XML service files.



AttributeSchema Element

The AttributeSchema element is a sub-element of the five schema elements discussed in "Schema Sub-Elements". It defines the structure of each attribute. The sub-elements that qualify the AttributeSchema can include IsOptional?, IsServiceIdentifier?, IsStatusAttribute?, ChoiceValues?, BooleanValues?, DefaultValues?, or Condition. The XML attributes that define each portion of the attribute value are name, type, syntax, cosQualifier, rangeStart, rangeEnd, validator, any, and %i18nIndex. Code Example 2-7 illustrates the AttributeSchema element, its attributes and their corresponding values. Note that this example attribute is a Dynamic attribute.

Code Example 2-7    AttributeSchema Element With XML Attributes
...

<Dynamic>

<AttributeSchema name="iplanet-am-sample-mail-service-status"

type="single_choice"

syntax="string"

i18nKey="a1">

<ChoiceValues>

<ChoiceValue>Active</ChoiceValue>

<ChoiceValue>Inactive</ChoiceValue>

<ChoiceValue>Deleted</ChoiceValue>

</ChoiceValues>

<DefaultValues>

<Value>Active</Value>

</DefaultValues>

</AttributeSchema>

</Dynamic>

...



name Attribute
This required XML attribute defines the LDAP name for the attribute. Any string format can be used but attribute names must be in lower-case. Code Example 2-7 defines it with a value of iplanet-am-sample-mail-service-status.


type Attribute
This attribute specifies the kind of value the attribute will take. The default value for type is list but it can be defined as one of the following:

  • single specifies that the user can define one value.

  • list specifies that the user can define a list of values.

  • single_choice specifies that the user can chose a single value from a list of options.

  • multiple_choice specifies that the user can chose multiple values from a list of options.

ChoiceValues Sub-Element. If the type attribute is specified as either single_choice or multiple_choice, the ChoiceValues sub-element must also be defined in the AttributeSchema. Depending on the type specified, the administrator or user would choose either one or more values from the choices defined. The possible choices are defined in the ChoiceValue element. Code Example 2-7 defines the attribute type as single_choice so the ChoiceValues attribute defines the list of options as Active, Inactive and Deleted.


syntax Attribute
The syntax attribute defines the format of the value. The default value for syntax is string but, it can be defined as one of the following:

  • boolean specifies that the value is either true or false.

  • string specifies that the value can be any string.

  • password specifies that user must enter a password, which will be encrypted.

  • dn specifies that the value is a LDAP Distinguish Name.

  • email specifies that the value is an email address.

  • url specifies that the value is a URL address.

  • numeric specifies that the value is a number.

  • percent specifies that the value is a .

  • number specifies that the value is a number.

  • decimal_number specifies that the value is a number with a decimal point.

  • number_range specifies that the value is a range of numbers.

  • decimal_range specifies that the value is a range of numbers that might include a decimal figure.

DefaultValues Sub-Element. Defining any of these syntax values also necessitates defining a value for the DefaultValue sub-element. A default value will then be displayed in the DSAME console but can be changed for each organization when creating a new template for the service. In the Code Example 2-8, for example, the Save Address Book On Server field will display a default value of false. The user has the option to change the value to true, if desired. (The default value for password would be an encrypted password, generally the same as the one used for DSAME.)

Code Example 2-8    ActionSchema Element With Boolean Syntax
...
<ActionSchema name="iplanet-am-sample-mail-can-save-address-book-on-server"
type="single"
syntax="boolean"
i18nKey="p3">
<DefaultValues>
<Value>false</Value>
</DefaultValues>
</ActionSchema>
...

The ActionSchema as displayed in Code Example 2-8 is discussed in "ActionSchema Element".


cosQualifier Attribute
This attribute defines how DSAME will resolve conflicting cosQualifier attributes assigned to the same user object. This value will appear as a qualifier to the cosAttribute in the LDAP entry of the CoS definition. It can be defined as:

  • default indicates that if there are two conflicting cosQualifier attributes assigned to the same user object, the one with the lowest priority number (0) takes precedence. (The priority level is set in the cosPriority attribute when a new CoS template entry is created for an organization or role. For more information, see "Conflicts and CoS" of Chapter 8 "iPlanet Directory Server And DSAME.")

  • override indicates that the CoS template value overrides any value already present in the user entry; that is, CoS takes precedence over the user entry value.

  • merge-schemes indicates that if there are two CoS templates assigned to the same user, then they are merged so that the values are combined and the user gets an aggregation of the CoS templates.


    Note The URL Policy Agent service uses merge-schemes to obtain aggregated values for the Allow and Deny attributes. For example, if the Employee Role allows access to */employee.html and the HR Role allows access to */hr.html, a user possessing both of these roles is allowed access to both.


If this attribute is not defined, the default behavior is for the user entry value to override the CoS value in the organization or role. The default value is default. (The operational value is reserved for future use.)


any Attribute
The any attribute specifies whether the attribute for which it is defined will display in the DSAME console. It has six possible values that can be multiply defined using the "|" (pipe) construct:

  • display specifies that the attribute will display on the user profile page. The attribute is read/write for administrators and regular users.

  • adminDisplay specifies that the attribute will display on the user profile page. It will not appear on an end user page; the attribute is read/write for administrators only.

  • userReadOnly specifies that the attribute is read/write for administrators but is read only for regular users. It is displayed on the user profile pages as a non-editable label for regular users.

  • required specifies that a value for the attribute is required in order for the object to be created. The attribute will display on the Create page with an asterisk.

  • optional specifies that a value for the attribute is not required in order for the object to be created.

  • filter specifies that the attribute will display on the Search page.

The required or optional keywords and the filter and display keyword can be specified with a pipe symbol separating the options (any=required|display or any=optional|display|filter). If the any attribute is set to display, the qualified attribute will display in DSAME console when the properties for the Create page are displayed. If the any attribute is set to required, an asterisk will display in that attribute's field, thus the administrator or user is required to enter a value for the object to be created in DSAME console. If the any attribute is set to optional, it will display on the Create page, but users are not required to enter a value in order for the object to be created. If the any attribute is set to filter, the qualified attribute will display as a criteria attribute when Search is clicked from the User page.


%i18nIndex Attribute (i18nKey)
The i18nKey attribute, as defined in "i18nFileName And i18nKey Attributes", is referenced as an entity in the sms.dtd.


Note If the i18nKey value is blank (that is, " "), the DSAME console will not display the attribute.



ActionSchema Element

The ActionSchema element is a sub-element of the Policy attribute element discussed in "Policy Element". It defines the structure of Policy attributes only. The sub-elements that qualify the ActionSchema can include IsOptional?, ActionValue?, BooleanValues?, and DefaultValues? The XML attributes that define each portion of the attribute value are name, type, syntax, cosQualifier, rangeStart, rangeEnd, validator, any, and %i18nIndex. Code Example 2-8 illustrates the ActionSchema element, its attributes and their corresponding values.


Note The difference between AttributeSchema and ActionSchema is that the ActionSchema element has Policy-specific attributes, such as ActionValue, and the AttributeSchema has attributes not applicable to Policy, such as IsStatusAttribute?



ResourceName Element

The ResourceName element specifies if the service has resources associated with it, for example, URLs in the case of URL Policy Agent service.


The amAdmin.dtd Structure

The amAdmin.dtd defines the data structure for all XML files which will be used to perform batch LDAP operations on the DIT using amAdmin. It is located in the Install_Directory/SUNWam/dtd directory. The command line operations include reads and gets on the attributes as well as creations and deletions of user objects (roles, organizations, users, people containers, and groups). The following sections discuss the elements and attributes of the amAdmin.dtd as well as the sample XML templates installed with DSAME that use this structure. These samples can be found in Install_Directory/SUNWam/samples/admin/cli/bulk-ops and will be used to illustrate these sections.


Requests Element

The Requests element is the root element of the batch processing XML file. It must contain at least one child element which defines the DSAME identity objects (Organization, Container, People Container, Role and Group) onto which the actual requests are performed. To enable batch processing, the root element can take more than one set of requests. The Requests element must contain at least one of the following sub-elements:

  • OrganizationRequests

  • ContainerRequests

  • PeopleContainerRequests

  • RoleRequests

  • GroupRequests

  • SchemaRequests

  • ServiceConfigurationRequests

Based on the defined request, the corresponding DSAME API will be called to perform the operation.


OrganizationRequests Element

The OrganizationRequests element consists of all requests that can be performed on Organization objects. The required XML attribute for this element is the LDAP Distinguished Name (DN) of the organization on which all of the sub-element requests will be performed. This element can have one or more sub-elements which perform their operations on the defined instance of the Organization object. (Different OrganizationRequests elements can be defined in one document to modify more than one Organization DN.) Code Example 2-9 defines a myriad of objects to be created from the top level organization, o=isp. The sub-elements of OrganizationRequests are:

  • CreateSubOrganization

  • CreatePeopleContainer

  • CreateRole

  • CreateGroup

  • CreatePolicy

  • AssignPolicy

  • UnAssignPolicy

  • CreateServiceTemplate

  • ModifySubOrganization

  • ModifyServiceTemplate

  • DeleteServiceTemplate

  • ModifyPeopleContainer

  • ModifyRole

  • ModifyGroup

  • ModifyPolicy

  • GetSubOrganizations

  • GetPeopleContainers

  • GetRoles

  • GetGroups

  • GetUsers

  • RegisterServices

  • UnregisterServices

  • GetRegisteredServiceNames

  • GetNumberOfServices

  • DeleteRoles

  • DeleteGroups

  • DeletePolicy

  • DeletePeopleContainers

  • DeleteSubOrganizations


ContainerRequests Element

The ContainerRequests element consists of all requests that can be performed on Container objects. The required XML attribute for this element is the DN of the container on which the sub-element requests will be performed. This element can have one or more sub-elements which perform their operations on the same instance of the container. (Different ContainerRequests elements can be defined in one document to modify more than one Container DN.) Code Example 2-9 illustrates how this element can be modeled. The sub-elements of ContainerRequests are:

  • CreateSubContainer

  • CreatePeopleContainer

  • CreateRole

  • CreateGroup

  • CreatePolicy

  • AssignPolicy

  • UnAssignPolicy

  • CreateServiceTemplate

  • ModifyServiceTemplate

  • ModifySubContainer

  • ModifyPeopleContainer

  • ModifyRole

  • GetSubContainers

  • GetPeopleContainers

  • GetRoles

  • GetGroups

  • GetUsers

  • RegisterServices

  • UnregisterServices

  • GetRegisteredServiceNames

  • GetNumberOfServices

  • DeleteRoles

  • DeleteGroups

  • DeletePolicy

  • DeletePeopleContainers

  • DeleteSubContainers


PeopleContainerRequests Element

The PeopleContainerRequests element consists of all requests that can be performed on People Container objects. The required XML attribute for this element is the DN of the container on which the sub-element requests will be performed. This element can have one or more sub-elements which perform their operations on the same instance of the people container. (Different PeopleContainerRequests elements can be defined in one document to modify more than one People Container DN.) Code Example 2-9 illustrates how this element can be modeled. The sub-elements of PeopleContainerRequests are:

  • CreateSubPeopleContainer

  • ModifyPeopleContainer

  • CreateUser

  • ModifyUser

  • GetNumberOfUsers

  • GetUsers

  • GetSubPeopleContainers

  • DeleteUsers

  • DeleteSubPeopleContainers


RoleRequests Element

The RoleRequests element consists of all requests that can be performed on roles. The required XML attribute for this element is the DN of the role on which the sub-element requests will be performed. This element can have one or more sub-elements which perform their operations on the same instance of the role. (Different RoleRequests elements can be defined in one document to modify more than one Role DN.) Code Example 2-9 illustrates how this element can be modeled. The sub-elements of RoleRequests are:

  • CreateServiceTemplate

  • ModifyServiceTemplate

  • AssignPolicy

  • UnAssignPolicy

  • GetNumberOfUsers

  • GetUsers

  • AddUsers


GroupRequests Element

The GroupRequests element consists of all requests that can be performed on group objects. The required XML attribute for this element is the DN of the group on which the sub-element requests will be performed. This element can have one or more sub-elements which perform their operations on the same instance of the group. (Different GroupRequests elements can be defined in one document to modify more than one Group DN.) Code Example 2-9 illustrates how this element can be modeled. The sub-elements of GroupRequests are:

  • CreateSubGroup

  • GetSubGroups

  • GetNumberOfUsers

  • GetUsers

  • AddUsers

  • DeleteSubGroups


AttributeValuePair Element

The AttributeValuePair element can be a sub-element of many of the following batch processing requests. It can have two sub-elements, neither of which can themselves have sub-elements. The Attribute sub-element must be empty while the Value sub-element takes a default value to display in the DSAME console. The Attribute sub-element takes a required XML attribute called name. The value of name is the attribute name which is equal to one string without spaces; no sub-elements are allowed. Code Example 2-14 illustrates how an attribute/value pair would be added to a sub-organization.


CreateObject Elements

The CreateSubOrganization, CreateUser, CreateGroup, CreateSubContainer, CreatePeopleContainer, CreateSubGroup, CreateSubPeopleContainer and CreateRole elements create a sub-organization, user, group, sub-container, people container, sub-group, sub-people container and role, respectively. The object is created in the DN that is defined in the second-level <Object>Requests element under which the Create<Object> element is defined. AttributeValuePair may be defined as a sub-element (or not). The required XML attribute for each element is createDN; it takes the DN of the object to be created. Code Example 2-9 illustrates an example of some of these elements.

Code Example 2-9    Portion of Batch Processing File createRequests.xml
<Requests>
<OrganizationRequests DN="o=isp">

<CreateSubOrganization createDN="sun.com"/>
<CreatePeopleContainer createDN="People1,o=sun.com"/>
<CreateRole createDN="ManagerRole,o=sun.com"/>
<CreateRole createDN="EmployeeRole,o=sun.com"/>
<CreateGroup createDN="ContractorsGroup,o=sun.com"/>
<CreateGroup createDN="EmployeesGroup,o=sun.com"/>

</Requests>   


CreatePolicy Element
The CreatePolicy element creates one or more policy attributes. The Policy sub-element defines the named policy. The required XML attribute is createDN which takes the DN of the organization where the policy will be created. This and the following nested elements are all illustrated in Code Example 2-10.

Policy Element. The Policy sub-element defines the permissions or rules of the policy. It can take one or more of the Rule sub-elements. The required XML attribute is name which specifies the name of the policy. The serviceName attribute, which identifies the service to which the named policy applies, is an optional XML attribute.

Rule Element. The Rule sub-element defines a specific permission of the policy. Rule can take three sub-elements. The required XML attribute is name which defines a name for the rule. The three sub-elements are:

  • ServiceName Element

    The ServiceName sub-element defines the service for which a rule has been created. There are no sub-elements; the ServiceName element itself must be empty. The required XML attribute is name which takes a string value.

  • ResourceName Element

    The ResourceName sub-element defines the domain for which this permission is being defined. There are no sub-elements; the ResourceName element itself must be empty. The required XML attribute is name which takes a string value.

  • AttributeValuePair Element

    The AttributeValuePair sub-element defines the action names and corresponding action values of the rule. For additional information, see "DeleteObject Elements".

    Code Example 2-10    Portion of Batch Processing File createPolicyOrg.xml  
    ...
    <Requests>

    <OrganizationRequests DN="o=isp">

    <CreatePolicy createDN="o=iplanet.com,o=isp">
    <Policy name="urlpolicy" serviceName="iPlanetAMWebAgentService">
    <Rule name="Manager Rule">
    <ServiceName name="iPlanetAMWebAgentService"/>
    <ResourceName name="*.red.iplanet.com"/>
    <AttributeValuePair>
    <Attribute name="permission"/>
    <Value>iplanet-am-web-agent-access-allow-list</Value>
    </AttributeValuePair>
    </Rule>
    <Rule name="engManager Rule">
    <ServiceName name="iPlanetAMWebAgentService"/>
    <ResourceName name="*.eng.iplanet.com"/>
    <AttributeValuePair>
    <Attribute name="permission"/>
    <Value>iplanet-am-web-agent-access-allow-list</Value>
    </AttributeValuePair>
    </Rule>
    </Policy>
    </CreatePolicy>
    </OrganizationRequests>
    </Requests>


CreateServiceTemplate Element
The CreateServiceTemplate element creates a service template for the organization defined in the second-level Requests element. There are no sub-elements; the CreateServiceTemplate element itself must be empty. The required XML attribute is serviceName which takes a string value. Code Example 2-11 illustrates a service template being created for sun.com.

Code Example 2-11    Portion of Batch Processing File createServiceTemplates.xml
<Requests>
<OrganizationRequests DN="o=sun.com,o=isp">

<CreateServiceTemplate serviceName="sampleMailService"/>

</OrganizationRequests>
</Requests>   
...


DeleteObject Elements

The DeleteSubOrganizations, DeleteUsers, DeleteGroups, DeleteSubContainers, DeletePeopleContainers, DeleteSubGroups, DeleteSubPeopleContainers, and DeleteRoles elements delete a sub-organization, user, group, sub-container, people container, sub-group, sub-people container and role, respectively. The object is deleted from the DN that is defined in the second-level <Object>Requests element under which the Delete<Object> element is defined. DeleteSubOrganizations, DeleteUsers, DeleteGroups, DeleteSubContainers, DeletePeopleContainers, DeleteSubGroups, DeleteSubPeopleContainers and DeleteRoles take a sub-element DN; only six of the listed elements have the XML attribute deleteRecursively. (DeleteUsers and DeleteRoles do not have this option; they have no qualifying XML attribute.) If deleteRecursively is set to false, accidental deletion of all subtrees can be avoided; it's default value is false. The DN sub-element takes a character value equal to the DN of the object to be deleted. Code Example 2-12 illustrates an example of some of these elements.

Code Example 2-12    Portion of Batch Processing File deleteOrgRequests.xml
<OrganizationRequests DN="o=isp">

<DeleteRoles>
<DN>cn=ManagerRole,o=sun.com,o=isp</DN>
<DN>cn=EmployeeRole,o=sun.com,o=isp</DN>
</DeleteRoles>

<DeleteGroups deleteRecursively="true">
<DN>cn=EmployeesGroup,o=sun.com,o=isp</DN>
<DN>cn=ContractorsGroup,o=sun.com,o=isp</DN>
</DeleteGroups>

<DeletePeopleContainers deleteRecursively="true">
<DN>ou=People1,o=sun.com,o=isp</DN>
</DeletePeopleContainers>

<DeleteSubOrganizations deleteRecursively="true">
<DN>o=sun.com,o=isp</DN>
</DeleteSubOrganizations>

</OrganizationRequests>
</Requests>   
...


DeletePolicy Element
The DeletePolicy element takes the sub-element PolicyName. The PolicyName element has no sub-elements; it must be empty. It has a required XML attribute name which takes a character value equal to the name of the policy. The DeletePolicy element itself takes a required XML attribute: deleteDN. It takes a value equal to the DN of the policy to be deleted.


DeleteServiceTemplate Element
The DeleteServiceTemplate element deletes the specified service template. There are no sub-elements; the DeleteServiceTemplate element itself must be empty. The required XML attributes are serviceName which takes a string value and schemaType which defines the attribute group (Global, Organization, Dynamic, User or Policy). Code Example 2-13 illustrates how this element is formatted.

Code Example 2-13    Portion of Batch Processing File deleteServiceTemplates.xml
<OrganizationRequests DN="o=iplanet.com,o=isp">
<DeleteServiceTemplate serviceName="iPlanetAMAuthLDAPService"
schemaType="organization">

</DeleteServiceTemplate>
</OrganizationRequests>
</Requests>   


ModifyObject Elements

The ModifyPeopleContainer, ModifySubContainer, ModifySubOrganization and ModifyRole, ModifyGroup elements change the specified object. AttributeValuePair can be defined as a sub-element of the first four listed elements. (The ModifyGroup element can have no sub-elements; it must be empty.) The required XML attribute is modifyDN which takes the DN of the object to be modified. Code Example 2-14 illustrates how these elements can be modeled.

Code Example 2-14    Portion of Batch Processing File modifyRequests1.xml
<OrganizationRequests DN="o=isp">

<ModifySubOrganization modifyDN="o=sun.com,o=isp">
<AttributeValuePair>
<Attribute name="Description"/>
<Value>DSAME Modify</Value>
</AttributeValuePair>
</ModifySubOrganization>

<ModifyPeopleContainer modifyDN="People1,o=sun.com">
<AttributeValuePair>
<Attribute name="Description"/>
<Value>DSAME Modify</Value>
</AttributeValuePair>
</ModifyPeopleContainer>

<ModifyRole modifyDN="ManagerRole,o=sun.com">
<AttributeValuePair>
<Attribute name="iplanet-am-role-description"/>
<Value>DSAME Modify</Value>
</AttributeValuePair>
</ModifyRole>


</OrganizationRequests>
</Requests>   


ModifyServiceTemplate Element
The ModifyServiceTemplate element changes a specified service template. AttributeValuePair must be defined as a sub-element of ModifyServiceTemplate to change the values. The required XML attribute is serviceName which takes a string value and schemaType. Code Example 2-15 illustrates this element.

Code Example 2-15    Portion of Batch Processing File modifyServiceTemplates.xml
...
<Requests>
<OrganizationRequests DN="o=sun.com,o=isp">

<ModifyServiceTemplate serviceName="sampleMailService">
<AttributeValuePair>
<Attribute name="iplanet-am-sample-mail-sentmessages-folder"/>
<Value>Hello Mail Sent</Value>
</AttributeValuePair>
</ModifyServiceTemplate>
</OrganizationRequests>
</Requests>   


GetObject Elements

The GetSubOrganizations, GetUsers, GetGroups, GetSubContainers, GetPeopleContainers and GetRoles elements get the specified object. A DN may be defined as a sub-element (or not). If none is specified, ALL of the specified objects at all levels within the organization defined in the second-level Requests element will be returned. The required XML attribute for all but GetGroups and GetRoles is DNsOnly and takes a true or false value. The required XML attribute of GetGroups and GetRoles is level which takes a value of either ONE_LEVEL or SUB_TREE. ONE_LEVEL will retrieve just the groups at that node level; SUB-TREE gets groups at the node level and all those underneath it. Code Example 2-16 illustrates how these elements can be modeled.


DNs Only Attribute
For all objects using the DNsOnly attribute, the Get elements work as stated below:

  • If the element has the required XML attribute DNsOnly set to true and no sub-element DN is specified, only the DNs of the objects asked for will be returned.

  • If the element has the required XML attribute DNsOnly set to false and no sub-element DN is specified, the entire object (a DN with attribute/value pairs) will be returned.

  • If sub-element DNs are specified, the entire object will always be returned whether the required XML attribute DNsOnly is set to true or false.

    Code Example 2-16    Portion of Batch Processing File getRequests.xml

    <OrganizationRequests DN="o=isp">
       
       <GetSubOrganizations DNsOnly="false">
        <DN>o=iplanet.com,o=isp</DN>
        <DN>o=sun.com,o=isp</DN>
       </GetSubOrganizations>
       
       <GetPeopleContainers DNsOnly="false">
        <DN>ou=People,o=iplanet.com,o=isp</DN>
        <DN>ou=People,o=sun.com,o=isp</DN>
       </GetPeopleContainers>
       
       <GetRoles level="SUB_TREE"/>
       
       <GetGroups level="SUB_TREE"/>
       
       <GetUsers DNsOnly="false">
        <DN>cn=puser,ou=People,o=iplanet.com,o=isp</DN>
       </GetUsers>
       
    </OrganizationRequests>
    ...


GetService Elements

The GetRegisteredServiceNames and GetNumberOfServices elements retrieve registered services and total number of registered services, respectively. The organization from which this information is retrieved is specified in the OrganizationRequests element. All three elements have no sub-elements or attributes; the elements themselves must be empty. Code Example 2-17 illustrates how the GetRegisteredServiceNames element is modeled.

Code Example 2-17    Batch Processing File getRegisteredServiceNames.xml

<OrganizationRequests DN="o=sun.com,o=isp">
<GetRegisteredServiceNames/>
</OrganizationRequests>

</Requests>   


ActionServices Elements

The RegisterServices and UnregisterServices elements perform the requested action on the service defined in the OrganizationRequests element. All elements take a sub-element Service_Name but have no XML attribute. The Service_Name element takes a character value equal to the name of the service. One or more Service_Name sub-elements can be specified.


Service Action Caveats

  • The XML service file for the service must be loaded using the command line interface amadmin before a service can be acted upon.

  • If no Service_Name element is specified or, in the case of UnregisterServices, the service was not previously registered, the request is ignored.

  • If no Service_Name element is specified, the request will be ignored.

Code Example 2-18 illustrates how these elements can be modeled.

Code Example 2-18    Portion of Batch Processing File registerRequests.xml
<OrganizationRequests DN="o=sun.com,o=isp">

<RegisterServices>
<Service_Name>sampleMailService</Service_Name>
</RegisterServices>

</OrganizationRequests>
</Requests>   


AssignPolicy and UnAssignPolicy Elements

The AssignPolicy and UnAssignPolicy elements take the sub-element PolicyName. The PolicyName element has no sub-elements; it must be empty. It has a required XML attribute name which takes a character value equal to the name of the policy. The required XML attribute of AssignPolicy and UnAssignPolicy is policyDN which takes a value equal to the DN of the policy to be acted upon.


SchemaRequests Element

The SchemaRequests element consists of all requests that can be performed on the default values of the DSAME schema. It has two required XML attributes: serviceName and SchemaType. serviceName takes a value equal to the name of the service where the schema lives and SchemaType defines the attribute group (Global, Organization, Dynamic, User or Policy). This element can have zero or more sub-elements. The sub-elements of SchemaRequests are:

  • RemoveDefaultValues Element

  • ModifyDefaultValues Element

  • AddDefaultValues Element

  • GetServiceDefaultValues


RemoveDefaultValues Element
The RemoveDefaultValues element removes the default values from the schema specified in the parent SchemaRequests element. It takes a sub-element of Attribute which specifies the name of the attribute to be removed. The Attribute sub-element itself must be empty; it takes no sub-element. There is no required XML attribute.

Code Example 2-19    Portion of Batch Processing File removeschemaRequests.xml
<SchemaRequests serviceName="iPlanetAMUserService"
    SchemaType="dynamic">
<RemoveDefaultValues>
<Attribute name="preferredlanguage"/>
</RemoveDefaultValues>
</SchemaRequests>
</Requests>   


AddDefaultValues and ModifyDefaultValues Elements
The AddDefaultValues and ModifyDefaultValues elements add or change the default values from the specified schema, respectively. They take a sub-element of AttributeValuePair which specifies the name of the attribute and the new default value; one or more attribute/value pairs can be defined. Code Example 2-20 illustrates how this element can be modeled.

Code Example 2-20    Portion of Batch Processing File addschemaRequests.xml
<SchemaRequests serviceName="iPlanetAMUserService"
    SchemaType="dynamic">
<AddDefaultValues>

<AttributeValuePair>
<Attribute name="iplanet-am-user-auth-modules"/>
<Value>Cert</Value>
</AttributeValuePair>

</AddDefaultValues>
</SchemaRequests>
</Requests>   


GetServiceDefaultValues Element
The GetServiceDefaultValues element retrieves the default values from the schema specified in the parent SchemaRequests element. There are no sub-elements; the GetServiceDefaultValues element itself must be empty. There is also no required XML attribute.


ServiceConfigurationRequests Element

The ServiceConfigurationRequests element is reserved for future use.



DSAME XML Files


DSAME uses XML files to manage attributes that are stored in DS. It does not implement any behavior or dynamically generate any code to interpret the attributes; it can only set or get attribute values. In addition to XML files that define service attributes, DSAME also includes XML templates that can be used for batch processing. This section contains information on these types of XML files.


Internal XML Service Files

DSAME installs internal services that manage the attributes of its internal software components. The DSAME console manages the attributes for these services; in addition, DSAME provides code implementations to use them. These internal XML service files are based on the sms.dtd. All internal XML service files are located in Install_Directory/SUNWam/config/xml. They include:

  • amAdminConsole.xml—Defines attributes for the Administration service.

  • amAuth.xml—Defines attributes for the Core Authentication service.

  • amAuthAnonymous.xml—Defines attributes for the Anonymous Authentication service.

  • amAuthCert.xml—Defines attributes for the Certificate-based Authentication service.

  • amAuthLDAP.xml—Defines attributes for the LDAP Authentication service.

  • amAuthRadius.xml—Defines attributes for the Radius Authentication service.

  • amAuthSafeWord.xml—Defines attributes for the SafeWord Authentication service.

  • amAuthSecurID.xml—Defines attributes for the SecurID Authentication service.

  • amAuthUnix.xml—Defines attributes for the Unix Authentication service.

  • amClientDetection.xml—Defines attributes for the Client Detection service.

  • amDomainURLAccess.xml—Defines attributes for the URL Access Policy service.

  • amEntrySpecific.xml—Defines attributes for the displaying attributes on the Create, Properties and Search pages for a custom service.

  • amLogging.xml—Defines attributes for the Logging service.

  • amMembership.xml—Defines attributes for the Membership Authentication service.

  • amNaming.xml—Defines attributes for the Naming service.

  • amPlatform.xml—Defines attributes for the Platform service.

  • amPolicy.xml—Defines attributes for the Policy service.

  • amSession.xml—Defines attributes for the Session service.

  • amUser.xml—Defines attributes for the User service.

  • amWebAgent.xml—Defines attributes for the web agents.


Modifying An Internal XML Service File

Administrators can display and manage any attribute in the DSAME console using XML service files. The new attribute(s) would need to be added to an existing XML service file. Alternately, they can be grouped into a new service by creating a new XML service file although the simplest way to add an attribute is just to extend an existing XML service file. For example, an administrator wants to manage the nsaccountlock attribute; this attribute will give users the option of locking the account it defines. To manage it through DSAME, nsaccountlock must be described in a service. One option would be to add it to the amUser.xml service, iPlanetAMUserService. This is the service that, by default, includes many common attributes from the inetOrgPerson and inetUser object classes. Following is an example of how to add the nsaccountlock attribute to the amUser.xml service file.


Note When modifying an internal XML service file, be sure to also modify the DS by extending the LDAP schema, if necessary. For more information, see "Defining A Service".


  1. Add the following code to the SubSchema name=User element in Install_Directory/SUNWam/config/xml/amUser.xml.

    Code Example 2-21    nsaccountlock Example Attribute
    type="single_choice"
    syntax="string"
    any="filter"
    isChangeableByUser="yes"
    i18nKey="u13">
    <ChoiceValues>
    <Value>true</Value>
    <Value>false</Value>
    </ChoiceValues>
    <DefaultValues>
    <Value>false</Value>
    </DefaultValues>
    </AttributeSchema>
    ...

  2. Update the Install_Directory/SUNWam/locale/en_US/amUser.properties file with the new i18nKey tag u13 including the text to be used for display.

    Code Example 2-22    User Account Locked Example i18nKey

  3. Remove the service ou=iPlanetAMUserService,ou=services,dc=sun,dc=com with amadmin.

    For information on the amadmin syntax, see "The amAdmin Command Line Executable".

  4. Reload the user service, amUser.xml, with amadmin.

    For more information on the amadmin syntax, see "The amAdmin Command Line Executable".


Batch Processing XML Files

The --data or -t option of amadmin is used to perform batch processing using the command line. Batch processing XML templates have been installed and can be used to help an administrator to:

  • Create, delete and read roles, users, organizations, groups, people containers and services.

  • Get roles, people containers, and users.

  • Get the number of users for groups, people containers, and roles.

  • Import, register and unregister services.

  • Get registered service names or the total number of registered services for an existing organization.

  • Execute requests in multiple XML files.

The preferred way to perform most of these functions singularly is to use the DSAME console. The batch processing templates have been provided for ease of use with bulk updates although they can also be used for single configuration updates. This section provides an overview of the batch processing templates which can be modified to perform batch updates on user objects (groups, users, roles, people containers, etc.) in the DS.


Note Only XML files can be used as input for the amadmin tool. If an administrator wants to populate the DIT in DS with user objects, or perform batch reads (gets) or deletes on the DIT, then the necessary XML input files, based on the amadmin.dtd or sms.dtd, must be written.



Batch Processing XML Templates

All of the batch processing XML files perform operations on the DIT; they create, delete, or get attribute information on user objects. The batch processing XML templates provided with DSAME include:

  • ContCreateServiceTemplate.xml—Creates a service template for a specific container object.

  • ContModifyRequests1.xml—Adds new attributes for a sub-container object.

  • ContModifyRequests2.xml—Adds new attributes for a people container object.

  • ContModifyRequests3.xml—Adds new attributes for a sub-container object.

  • ContModifyRequests4.xml—Adds new attributes to a role object.

  • ContassignPolicyRequests.xml—Assigns policy to a specific container object.

  • ContunassignPolicyRequests.xml—Removes an assigned policy from a specific container object.

  • PCModifyRequests1.xml—Adds new attributes to a people container object.

  • PCModifyUserRequests.xml—Adds new attributes to users in a people container object.

  • RoleCreateServiceTemplates.xml—Creates a service template for a role object.

  • RoleassignPolicyRequests.xml—Assigns policy to a role object.

  • RolemodifyServiceTemplates.xml—Adds new attributes to a service template for a specific role object.

  • RoleunassignPolicyRequests.xml—Removes policy from a specific role object.

  • addChoiceValuesRequest.xml—Adds a selection of values the user can chose from to an existing service attribute.

  • addschemaRequests.xml—Adds a default value to an existing service attribute.

  • addserviceConfigurationRequests.xml—This is reserved for future use.

  • createPolicyOrg.xml—Creates policy for an organization object.

  • createRequests.xml—Creates a multitude of objects in the DS.

  • createServiceTemplates.xml—Creates a service template for an organization object.

  • deleteGroupRequests.xml—Deletes all objects under a specific group container.

  • deleteOrgRequests.xml—Deletes a multitude of objects under a specific organization.

  • deletePCRequests.xml—Deletes a multitude of objects under a specific people container.

  • deleteServiceTemplates.xml—Deletes a service template under a specific organization.

  • deleteserviceConfigurationRequests.xml—This is reserved for future use.

  • getNumOfServices.xml—Passes a listing of an organization's total number of registered services.

  • getRegisteredServices.xml—Passes a listing of an organization's registered services.

  • getRequests.xml—Passes information about a multitude of objects in a specific organization.

  • modifyRequests1.xml—Adds new attributes to a number of objects in a specific organization.

  • modifyRequests2.xml—Adds new attributes to a people container object in a specific organization.

  • modifyRequests3.xml—Adds new attributes to a role object in a specific organization.

  • modifyServiceTemplates.xml—Modifies existing attributes in a service registered to a specific organization.

  • modifyschemaRequests.xml—Adds new attributes to a number of objects in a specific organization.

  • registerRequests.xml—Registers a service to an existing organization. (This service must have been previously imported.)

  • removeChoiceValueRequests.xml—Removes the values a user can choose from in an existing attribute in a specific service.

  • removeschemaRequests.xml—Removes the default value of an existing attribute in a specific service.

  • unassignPolicyRequests.xml—Removes an assigned policy from a specific organization.

  • unregisterRequests.xml—Unregisters a service from an existing organization. (This service must have been previously imported and registered.)

These XML templates follow the structure defined by the amAdmin.dtd. They are located in Install_Directory/SUNWam/samples/admin/cli/bulk-ops.


Modifying A Batch Processing XML Template

Any of the templates discussed above can be modified to best suit the desired operation. Choose the file that performs the request, modify the elements and attributes according to the service and use the amadmin executable to upload the changes to the DS.


Note Be aware that creations of roles, groups, and organizations is a time-intensive operation.



XML Schema Files

The ums.xml file is the schema that defines the parameters of identity-related objects. More information on this file and how it relates to the DSAME SDK can be found in Chapter 4 "Identity Management And The SDK."


Customizing User Pages

The User entry page and what it displays will vary, depending on what the service developer defines. By default, every attribute in the amUser.xml file that has an i18nKey attribute specified and the any attribute set to display (any=display) will display in the DSAME console. Alternately, if an attribute is specified to be of type User in another XML service file, the DSAME console will display it if the service is assigned to the user. The DSAME console gets attributes to display from both, XML service files that have a defined schema attribute type of User and the User XML service file, amUser.xml. Thus, User display pages in the DSAME console can be modified to add new attributes in either of two ways:

  • The User attribute schema definition in the specific XML service file can be modified.

  • A new User schema attribute definition can be added to the User service (the amUser.xml service file).

For information on modifying XML service files, see "Modifying An Internal XML Service File".


Note Any service can describe an attribute that is for a user only. The amUser.xml file is just the default placeholder for user attributes that are not tied to a particular service.




Abstract Objects and amEntrySpecific.xml


The purpose of this XML service file is to define the attributes that will display on the Create, Properties and Search pages specific to each of the DSAME abstract objects. Each DSAME abstract object can have its own schema definition in the amEntrySpecific.xml file which is based on the sms.dtd as described in "DSAME DTD Files".


Abstract Objects

DSAME represents the objects it manages abstractly; in other words, an organization in DSAME does not necessarily map to an LDAP organization in the DS. The abstract objects are:

  • organization

  • organizational unit

  • people container

  • static group

  • filtered group

  • assignable dynamic group

  • group container


Marker Object Classes

Abstract objects are identified in the DS by marker object classes that are defined in a DSAME schema and used in LDAP object entries. For example, the DS may use organizational units for their first level structure; by adding the DSAME organization marker object class, iplanet-am-managed-org, to the LDAP entries of these organizational units, DSAME will manage them as organizations. It is the use of marker object classes that allows DSAME to manage most directory structures, regardless of the object classes and naming attributes deployed. The marker object classes are:

  • iplanet-am-managed-filtered-group

  • iplanet-am-managed-assignable-group

  • iplanet-am-managed-static-group

  • iplanet-am-managed-org

  • iplanet-am-managed-org-unit

  • iplanet-am-managed-people-container

  • iplanet-am-managed-group-container


    Note The marker object classes are defined in the DSAME-specific LDAP schema named 95am-schema.ldif and located in Install_Directory/SUNWam/config/ums. It is loaded into the DS when DSAME is installed.



amEntrySpecific.xml Schema

Each abstract object can have a schema defined in the amEntrySpecific.xml file. The schema defines what attributes will be displayed on the function pages used to manage abstract type objects:

  • Create—The Create page is displayed when the administrator clicks New.

  • Properties—The Properties Page is displayed when the Properties icon (an arrow in a box) next to an abstract type object is clicked.

  • Search—The Search link is in the top left frame of the DSAME console.

If a service developer wants to customize these DSAME function pages for any of the abstract objects, they would need to modify the amEntrySpecific.xml. For example, to display an attribute on the group page, the new attribute needs to be added to the amEntrySpecific.xml file. Any abstract object with customized attributes in the DS would need to have those attributes reflected in the amEntrySpecific.xml file also. (Most often, a service developer would only be customizing the organization pages.) Code Example 2-23 is the organization attribute subschema that defines the display of an organization's Organization Status and its choice values.

Code Example 2-23    Organization Subschema of amEntrySpecific.xml
<AttributeSchema name="inetdomainstatus"
type="single_choice"
syntax="string"
any="optional|filter"
i18nKey="o2">
<ChoiceValues>
<ChoiceValue>Active</ChoiceValue>
<ChoiceValue>Inactive</ChoiceValue>
</ChoiceValues>
</AttributeSchema>
</SubSchema>
...

If the type attribute is not specified in amEntrySpecific.xml, the defaults will be used. A default setting means that only the name of the entry will display on the object function pages in the DSAME console.

All the attributes listed in the schema definitions in the amEntrySpecific.xml file are displayed when the abstract type object pages are displayed. If the attribute is not listed in a schema definition in the amEntrySpecific.xml file, the DSAME console will not display the attribute. For additional information on the DSAME abstract objects and marker object classes, see the iPlanet Directory Server Access Management Edition Installation and Configuration Guide.


Note Note that the User service is not configured in the amEntrySpecific.xml file but in its own amUser.xml file.




The amAdmin Command Line Executable


The primary purposes of the command line executable amadmin is to load XML service files into the DS and to perform batch administrative tasks on the DIT. amadmin can be found in Install_Directory/SUNWam/bin and is used to:

  • Load XML service files—Administrators load services into DSAME that use the XML service file format defined in the sms.dtd. All services must be loaded using amadmin; they cannot be imported through the DSAME console.


    Note XML service files are stored in the DS as static blobs of XML data that is referenced by DSAME. This information is not used by the DS which only understands LDAP.


  • Perform batch updates to the DIT—Administrators can perform batch updates to the DS DIT using the batch processing XML file format defined in the amadmin.dtd. For example, if an administrator wants to create 10 organizations, 100 people containers, 1000 users, and 100 groups, it can be done in one attempt by putting the requests in one or more batch processing XML files and loading them using amadmin. More information on this can be found in "DSAME DTD Files".


    Note amadmin only supports a subset of features that the DSAME console supports and is not intended as a replacement. It is recommended that the console be used for small administrative tasks while amadmin is used for larger administrative tasks.



The amadmin Syntax

There are a number of structural rules that must be followed in order to use amadmin. The generic syntaxes for using the tool are:

  • amadmin -u | --runasdn dnname -w | --password password [-l | --locale localename] [[-v | --verbose] | [-d |--debug]] -t | --data xmlfile1 [xmlfile2 ...]

  • amadmin -u | --runasdn dnname -w | --password password [-l | --locale localename] [[-v | --verbose] | [-d | --debug]] -s | --schema xmlfile1 [xmlfile2 ...]

  • amadmin -u | --runasdn dnname -w | --password password [-l | --locale localename] [[-v | --verbose] | [-d | --debug]] -r | --deleteService serviceName1 [serviceName2 ...]

  • amadmin -h | --help

  • amadmin -n | --version


    Note Two hyphens must be entered exactly as shown in the generic syntax.



amadmin Options

Following are definitions of the amadmin command line options:


--runasdn
--runasdn is used to authenticate the user to the LDAP server. The argument is a value equal to that of the Distinguished Name (DN) of the user authorized to run amadmin; as in --runasdn uid=amAdmin,ou=People,o=iplanet.com,o=isp. The DN can also be formatted by inserting spaces between the domain components and double quoting the entire DN such as: --runasdn "uid=amAdmin, ou=People, o=iplanet.com, o=isp".


--password
--password is a mandatory option and takes a value equal to that of the password of the DN specified with the --runasdn option.


--locale
--locale is an option that takes a value equal to that of the name of the locale. This option can be used for the customization of the message language. If not provided, the default locale, en_US, is used.


--debug
--debug is an option that will write messages to the amAdmin file created under the Install_Directory/SUNWam/web-apps/services/debug directory. These messages are technically-detailed but not i18n-compliant.


--verbose
--verbose is an option that prints to the screen the overall progress of the amadmin command. It does not print to a file the detailed information. Messages output to the command line are i18n- compliant.


--data
--data is an option that takes as its value the name of the batch processing XML file being imported. One or more XML files can be specified. This XML file can create, delete and read various directory objects as well as register and unregister services. For more information on what types of XML files can be passed to this option, see "DSAME DTD Files".


--schema
--schema is an option that loads the attributes of a DSAME service into the DS. It takes as an argument an XML service file in which the service attributes are defined. This XML service file is based on the sms.dtd. One or more XML files can be specified.


Note Either the --data or --schema option must be specified, depending on whether configuring batch updates to the DIT, or loading service schema and configuration data.



--deleteService
--deleteService is an option for deleting a service and its schema only.


--serviceName
--serviceName is an option that takes a value equal to the service name which is defined under the Service name=... tag of an XML service file. This portion is displayed in Code Example 2-24.

Code Example 2-24    Portion of sampleMailService.xml
<Service name="sampleMailService" version="1.0">
<Schema
serviceHierarchy="/other.configuration/sampleMailService"
i18nFileName="sampleMailService"
i18nKey="iplanet-am-sample-mail-service-description">
...


--help
--help is an argument that displays the syntax for the amadmin command.


--version
--version is an argument that displays the utility name, product name, product version and legal notice.



SampleMailService Files


DSAME comes with the files needed to integrate a mail service into the configuration. These sample files are provided as guidelines for creating custom services and applications and illustrate how the service might be configured. The files included are:

  • sampleMailServiceSchema.ldif—This LDAP Data Interchange Format (LDIF) file contains the LDAP schema (LDAP object classes and attribute names) for the sample mail service. The LDIF file for the service needs to be loaded into the DS using the ldapmodify command line tool. For more information, see the iPlanet Directory Server documentation.

  • sampleMailService.xml—This XML service file contains the service schema and configuration parameters for the sample mail service based on the structure defined in the sms.dtd. It defines the mail service attributes, among them i18Nkey which maps to fields in the service's corresponding localization properties files.

  • sampleMailService.properties—This localization properties file defines the object class name for the mail service profile as well as the values for the localization keys defined in sampleMailService.xml. The localization keys point to actual fields that display on DSAME console. For example, i18nKey="a1" defines a localization key in sampleMailService.xml file. a1=Mail Status, defined in sampleMailService.properties, tells the DSAME console to display Mail Status on the Sample Mail Service profile page in the DSAME console. For more information, see "Configuring Localization Properties".

The files can be found in Install_Directory/SUNWam/samples/admin/cli/sampleMailService. These files are used throughout this chapter to illustrate service definition concepts.


Note DSAME provides sample mail service files for instructional purposes only. Integrating DSAME with the iPlanet Messenger service is not supported.



Previous     Contents     Index          Next     
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated May 14, 2002