IBM Tivoli Directory Integrator
The DSMLv2 SOAP Connector implements the DSMLv2 standard. The Connector
is able to:
- Execute DSMLv2 requests against a DSML Server.
- Provide the option to use DSML SOAP binding.
- Internally instantiate, configure and use the HTTP Parser to create
HTTP requests and parse HTTP responses.
- Internally instantiate, configure and use the DSMLv2 Parser to
create DSMLv2 request messages and parse DSMLv2 response messages.
The Connector mode determines the type of DSML operation the Connector
requests. The DSMLv2 SOAP Connector supports the following modes:
- AddOnly
- The DSMLv2 SOAP Connector sends DSMLv2 addRequest and receives
a DSMLv2 addResponse message.
- Iterator
- The DSMLv2 SOAP Connector sends a DSMLv2 searchRequest operation
with a Search Base, Search Filter and Search Scope taken from the
current Connector configuration. The DSML server returns a DSMLv2
searchResponse message with multiple searchResultEntry elements. The
Connector cycles through the DSML searchResultEntry elements and delivers
each one in a separate AssemblyLine iteration.
- Lookup
- The DSMLv2 SOAP Connector sends a DSMLv2 searchRequest with
a Search Filter constructed from the Connector's Link Criteria. The
DSML server returns a DSMLv2 searchResponse message that is returned
as the Entry found. If there are multiple searchResultEntry elements
in the searchResponse message, process them in an On
Multiple Entries hook.
- Delete
- The Connector creates and sends a DSML deleteRequest as per
the Link Criteria. The DSML server returns a deleteResponse message.
- Update
- If the $dn Attribute in the work Entry is equal to
the $dn Attribute of the Entry to be updated, the Connector
sends a modifyRequest DSMLv2 request and receives a modifyResponse
response; otherwise a modDnRequest request is sent to the DSML server
and a modDnResponse response is received.
- Delta
- In Delta mode, it is the AssemblyLine that, depending on the
Entry tagging, decides which Connector method to invoke and what DSMLv2
request will be sent. Delta tagging at the Attribute level is handled
by the DSMLv2 Parser and delta information is incorporated into the
resulting DSMLv2 request.
The DSMLv2 SOAP Connector detects
in its modEntry method if the "newrdn" attribute exists and if yes
it replaces the rdn in the target $dn with the new value. Then a modDnRequest
request is sent to the DSML server and a modDnResponse response is
received.
- CallReply
- In CallReply mode, the Connector provides the work Entry to
the DSMLv2 Parser and sends the DSMLv2 message produced by the DSMLv2
Parser. The response from the DSMLv2 Server is passed directly to
the DSMLv2 Parser, and the Entry produced is returned by the Connector.
You must assign the correct request type, because the Connector will
not automatically set any DSMLv2 element. In particular, the CallReply
mode can be used to send DSMLv2 extended operations. See Extended Operations for more information.
In CallReply mode, the DSMLv2 SOAP Connector can send DSMLv2 extended
operations. Extended operations are identified by their Operation
Identifier (OIDs). For example, the OID of the extended operation
for retrieving a part of the log file of the IBM Tivoli Directory Server is 1.3.18.0.2.12.22.
Extended operations can also have a value property, which is a
data structure containing input data for the corresponding operation.
The value property of the extended operation must be Basic
Encoding Rules (BER) encoded and then base-64 encoded in the
DSMLv2 message. The user of the DSMLv2 SOAP Connector is responsible
only for BER encoding the value property. The Connector will automatically
base-64 encode the data when creating the DSMLv2 message.
Two classes are used for BER encoding and decoding: BEREncoder
and BERDecoder, located in thecom.ibm.asn1 package.
The following example illustrates sending a DSMLv2 extended operation
request and the processing of the response:
- Place the following script code in Output Map for attribute dsml.extended.requestvalue:
enc = new Packages.com.ibm.asn1.BEREncoder();
serverFile = 1; //slapdErrors log file
nFirstLine = new java.lang.Integer(7200);
nLastLine = new java.lang.Integer(7220);
seq_nr = enc.encodeSequence();
enc.encodeEnumeration(serverFile);
enc.encodeInteger(nFirstLine);
enc.encodeInteger(nLastLine);
enc.endOf(seq_nr);
var myByte = enc.toByteArray();
ret.value = myByte;
- Place the following script code in the After CallReply hook
of the Connector:
var ba = conn.getAttribute("dsml.response").getValue(0);
bd = new Packages.com.ibm.asn1.BERDecoder(ba);
main.logmsg("SLAPD log file:");
main.logmsg(new java.lang.String(bd.decodeOctetString()));
The DSMLv2 SOAP Connector by default always sends an empty header
for the SOAPAction header. The OASIS Standard around SOAP states the
this: "Each SOAP request body contains a single batchRequest. A SOAP
node SHOULD indicate in the 'SOAPAction' header field the element
name of the top-level element in the <body> of the SOAP request."
It is valid for this header to be empty but it should optionally
be something that can be set. Additionally, some vendors have defined
the header to be mandatory in their DSML definitions (Sun is an example, see http://docs.sun.com/source/816-6700-10/DSML.html).
If needed, we can set the SOAPAction Header yourself by means
of the SOAPAction Header parameter.
The DSMLv2 SOAP Connector uses the following parameters:
- DSMLv2 Server URL
- Specifies the URL of the DSMLv2 Server.
- Authentication Method
- Specifies the type of HTTP authentication. If the type of HTTP
authentication is set to Anonymous, then no authentication
is performed. If HTTP basic authentication is specified, HTTP basic authentication is used with user name and password as specified
by the username and password parameters.
- Username
- The user name used for HTTP basic authentication.
- Password
- The password used for HTTP basic authentication.
- Binary Attributes
- Specifies a comma-delimited list of attributes that will
be treated by the Connector as binary attributes. This parameter
has the following default list of attributes that we can change:
- photo
- personalSignature
- audio
- jpegPhoto
- javaSerializedData
- thumbnailPhoto
- thumbnailLogo
- userPassword
- userCertificate
- authorityRevocationList
- certificateRevocationList
- crossCertificatePair
- x500UniqueIdentifier
- objectGUID
- objectSid
- Search Base
- Specifies the starting point for searches when iterating.
- Search Filter
- Specifies the LDAP filter used when iterating.
- Search Scope
- The search scope to be used when iterating. Possible values
are:
The default is subtree.
- Soap Binding
- When this parameter is enabled, the Connector sends and receives
SOAP DSML messages. Otherwise, the DSML messages are not wrapped in
SOAP.
- SOAPAction Header
- The SOAPAction header value to include when SOAP binding is
enabled. The default header value is empty.
- Detailed Log
- Turns on debug messages. This parameter is common to all TDI components.