SPMLv2 Parser

Introduction

SPML Version 2 (SPMLv2) defines a core protocol [SPMLv2] over which different data models can be used to define the actual provisioning data. The combination of a data model with the SPML core specification is referred to as a profile. The use of SPML requires that a specific profile is used, although the choice of which profile is used to negotiated out-of-band by the participating parties.

The DSML v2 protocol [DSMLV2] was designed to perform LDAP type operations using web services. The DSML V2 protocol defines synchronous request/response semantics and a data model based on attribute/value pairs. DSML V2 does not define an attribute/value pairs schema mechanism.

The SPMLv2 Parser supports the SPMLv2 DSMLv2 Profile. It is a Tivoli® Directory Integrator Parser component that parses and creates SPMLv2 messages, that is, it is intended to parse individual SPMLv2 requests and responses or write SPMLv2 requests and responses.

The SPMLv2 Parser supports core operations as specified in the "(SPML) v2 - DSML v2 Profile" specification. Explicit Tivoli Directory Integrator Entry schemas are defined for each of the supported operations.

The Parser extends the XML Parser and has the ability to read enormous requests/responses without creating all the SPML messages in the memory. In addition, it has been implemented on top of the OpenSPML 2.0 Toolkit.

The Parser is capable of reading/writing Batch messages. The following types from the toolkit have been used:

org.openspml.v2.msg.spmlbatch.BatchRequest;
org.openspml.v2.msg.spmlbatch.BatchResponse;

On each readEntry call the Parser will return an Entry representing the individual request(s) or response(s) contained in the batch message. On writeEntry the Parser will write individual request(s) or response(s) inside the appropriate batch message.

Operations

A conformant provider must implement all the operations defined in the Core XSD. The following are the core operations:

• Add (Add Request and Add Response)
• Modify (Modify Request and Modify Response)
• Delete (Delete Request and Delete Response)
• Lookup (Lookup Request and Lookup Response)

The Parser also supports Search operations:

• Search (Search Request and Search Response)

Add request

Entries with the following structure are parsed (on read) and created (on write) by the Parser for Add Requests:

Additionally, for each DSML attr element: an attribute named as the "name" XML attribute of the DSML "attr" element and as value(s) specified for the "attr" DSML element.

Add response

Entries with the following structure are parsed (on read) and created (on write) by the Parser for Add Response:

Modify request

One important thing to mention is that the modify operation may change the identifier of the modified object.

Entries with the following structure are parsed (on read) and created (on write) by the Parser for Modify Requests:

In addition, for each modification item: an attribute named as the "name" XML attribute of the DSML "modification" element, with the values specified for the "modification" DSML element and Tivoli Directory Integrator attribute's operation set as the "operation" XML attribute of the DSML "modification" element.

Modify response

Entries with the following structure are parsed (on read) and created (on write) by the Parser for Modify Responses:

Delete request

Entries with the following structure are parsed (on read) and created (on write) by the Parser for Delete Requests:

Delete response

Entries with the following structure are parsed (on read) and created (on write) by the Parser for Delete Responses:

Lookup request

Entries with the following structure are parsed (on read) and created (on write) by the Parser for Lookup Requests:

Lookup response

Entries with the following structure are parsed (on read) and created (on write) by the Parser for Lookup Response:

Search request

Entries with the following structure are parsed (on read) and created (on write) by the Parser for Search Requests:

See Search Filter capabilities for a more thorough discussion of search filters.

Search response

Entries with the following structure are parsed (on read) and created (on write) by the Parser for Search Responses:

Binary and non-String Attributes

When parsing SPML messages, attributes tagged as binary by the Binary Attributes Parser parameter are Base64 decoded, that is, the string value from the SPML message is Base64 decoded to Java byte array.

When creating SPML messages, all Attributes whose value is Java byte array are Base64 encoded to String before being written in the SPML message.

If when creating a SPML message an Attribute is passed whose value's type is neither String, nor Java byte array, the value is converted to String by calling the object's toString() method and this String value is stored in the SPML message.

Attribute operation tagging

The SPMLv2 Parser handles the different modification operations by tagging the Entry attributes according to the dsml:modification operation attribute value in the SPMLv2 document.

For example, when reading the following SPML structure:

<modifyRequest xmlns='urn:oasis:names:tc:SPML:2:0' returnData='everything'>
	<psoID ID='CN=DnsUpdateProxy,OU=Groups,DC=2k3,DC=dom'/>
	<modification>
		<dsml:modification xmlns:dsml='urn:oasis:names:tc:DSML:2:0:core' name='member' operation='delete'>
			<dsml:value>CN=Eric Clapton,CN=Users,DC=2k3,DC=dom</dsml:value>
		</dsml:modification>
		<dsml:modification xmlns:dsml='urn:oasis:names:tc:DSML:2:0:core' name='member2' operation='add'>
			<dsml:value>CN=Eric Adams,CN=Users,DC=2k3,DC=dom</dsml:value>
		</dsml:modification>
		<dsml:modification xmlns:dsml='urn:oasis:names:tc:DSML:2:0:core' name='member3' operation='replace'>
			<dsml:value>CN=Joey DeMaio,CN=Users,DC=2k3,DC=dom</dsml:value>
		</dsml:modification>
	</modification>
</modifyRequest>

If you parse this SPML extract into an Entry you will have to map three Attributes named "member", "member2 " and "member3"; each one will be tagged with the according operation (that is, delete, add , replace). The value of the modification operation can also be accessed via script:

work.getAttribute("member").getOperation();

When parsing an Entry to a SPML document the attribute will be tagged with the attribute operation provided in the work Entry. If this modification operation is not set, the default is used - "replace". Alternatively you can set it manually via script:

work.getAttribute("member").setOperation("add");

Search Filter capabilities

In earlier versions of Tivoli Directory Integrator, the SPMLv2 Parser supported the Substrings Filter element only in Search requests and used the following attributes: spml.filter.substrings.name, spml.filter.substrings.initial, spml.filter.substrings.final and spml.filter.substrings.any to contain the Substrings subelements values.

The current version of the SPMLv2 Parser can parse the other filtering features provided by DSMLv2:

• not - negation of contained filter item;
• and - logical 'and' containing several filter items
• or - logical 'or' containing several filter items
• equalityMatch - filter item indicating equal match
• approxMatch - filter item indicating approximate match
• extensibleMatch - filter item indicating extensible match
• greaterOrEqual - filter item indicating match if greater or equal
• lessOrEqual - filter item indicating match if less or equal
• present - filter item indicating presence of specified attribute

Reading

When reading a Filter element, the parser creates a corresponding hierarchical Attribute named "spml.filter". For every filter item a separate Attribute object is created and appended as a child; correspondingly, for every subelement or another filter item contained in a filter item separate Attributes are created and added as its children.

The following attributes: spml.filter.substrings.name, spml.filter.substrings.initial, spml.filter.substrings.final and spml.filter.substrings.any are created only when the Filter element contains a single Substrings element; otherwise a spml.filter hierarchical attribute is created.

Limitation: When reading the SPMLv2 Parser cannot read the matchingRule and dnAttributes (always has default value of false) attributes of the extensibleMatch element. This is caused by the underlying Open SPML 2.0 library that tries to read the matchingRule and dnAttributes as values instead of attributes. However when writing these attributes are written correctly.

Writing

When writing, if a smpl.filter attribute is present in the provided entry it is used and spml.filter.substrings.name, spml.filter.substrings.initial, spml.filter.substrings.final and spml.filter.substrings.any attributes are ignored. If a smpl.filter attribute is not present the spml.filter.* attributes are used (compatibility with earlier versions).

Here is an example hierarchical spml.filter attribute and the corresponding XML generated from it:

<dsml:filter xmlns:dsml='urn:oasis:names:tc:DSML:2:0:core'>
  <dsml:and>
    <dsml:or>
      <dsml:substrings name='cn'>
        <dsml:initial>J</dsml:initial>
      </dsml:substrings>
      <dsml:not>
        <dsml:and>
          <dsml:lessOrEqual name='roomnumber'>
            <dsml:value>2000</dsml:value>
          </dsml:lessOrEqual>
          <dsml:greaterOrEqual name='roomnumber'>
            <dsml:value>3000</dsml:value>
          </dsml:greaterOrEqual>
        </dsml:and>
        </dsml:not>
          <dsml:approxMatch name='sn'>
            <dsml:value>Smith</dsml:value>
          </dsml:approxMatch>
        </dsml:or>
    <dsml:equalityMatch name='objectClass'>
      <dsml:value>inetorgperson</dsml:value>
    </dsml:equalityMatch>
  </dsml:and>
</dsml:filter>

Configuration

The Parser needs the following configuration parameters:

Binary Attributes

Specifies a comma delimited list of attributes that will be treated by the Parser as binary attributes (Base64 decoded/encoded as required).

This parameter has the following default list of attributes that you can change: photo, personalSignature, audio, jpegPhoto, javaSerializedData, thumbnailPhoto, thumbnailLogo, userPassword, userCertificate, authorityRevocationList, certificateRevocationList, crossCertificatePair, x500UniqueIdentifier, objectGUID, objectSid.

Character Encoding

Character encoding to use when reading or writing. The default is UTF-8. Since this parser extends the XML Parser, the same considerations as for that Parser apply.

Detailed Log

Checking this item will cause detailed logs to be generated.

Example

Examples of how to use this Parser have been provided in the TDI_install_dir/examples/SPMLv2Parser directory.

See also

DSMLv2 Parser