Have you ever had the need to send a query to a different system than the one your driver was connected to? Maybe not, but this is how to do it. This tip is based upon the information provided by Father Ramon in the Identity Manager forums.

Lets get on with the needed steps.

Create a new policy and add the conditions that will trigger the rules that send the query.

Create a new namespace definition

Add a new namespace definition that points to com.novell.nds.dirxml.driver.cmd.DriverCmd and check the "Java" checkbox. My namespace was named dircmd and it looks like this in the final DirXML Script policy:

<namespace-def name="dircmd" value="http://www.novell.com/nxsl/java/com.novell.nds.dirxml.driver.cmd.DriverCmd"/>

The next step is to create a query document in XDS format that will be sent to your driver.

The easy way is to create a new node-set variable that contains your query document, in it you can use variable expansion to dynamically create some parts of the query.

This is how my variable looks like:

<do-set-local-variable name="lv-query" notrace="true" scope="policy">
	<arg-node-set>
		<token-xml-parse>
			<token-text xml:space="preserve"><nds dtdversion="3.5" ndsversion="8.x">
<source>
<product version="3.5.11.20080307 ">DirXML</product>
<contact>Novell, Inc.</contact>
</source>
<input>
<query class-name="User" dest-dn="Myorg\Users" scope="subtree">
<search-class class-name="User"/>
<search-attr attr-name="Surname">
<value>Doe</value>
</search-attr>
<read-attr/>
</query>
</input>
</nds></token-text>
		</token-xml-parse>
	</arg-node-set>
</do-set-local-variable>

Sending the query

The next step is to sending the query to the driver, I'll create another variable containing the DN of the driver.

<do-set-local-variable name="lv-driverdn" scope="policy">
	<arg-string>
		<token-text xml:space="preserve">\ACME-META-TREE\ACME\System\DriverSet01\eDirectory_ACME-RES-TREE</token-text>
	</arg-string>
</do-set-local-variable>

Here we create a variable that sends the query, the variable is a node-set because the answer we get back is a node-set, notice the syntax: "$lv-query/nds", you must add the /nds after the variable name.

<do-set-local-variable name="lv-sendquery" scope="policy">
	<arg-node-set>
		<token-xpath expression="dircmd:sendDriverCommand($lv-driverdn, $lv-query/nds)"/>
	</arg-node-set>
</do-set-local-variable>

You can also type in the DN of the driver directly instead of using a variable, then you need to put ' (apostrophes) around the driver DN string.

Checking the response

To check the response in the trace I'll create another local variable using XML Serialize token (This variable is NOT used for accessing the content of the result, I use it here as an example on how to see the result in the trace in case of an error):

<do-set-local-variable name="lv-checkquery" scope="policy">
	<arg-node-set>
		<token-xml-serialize>
			<token-local-variable name="lv-sendquery"/>
		</token-xml-serialize>
	</arg-node-set>
</do-set-local-variable>

This allows me to see the entire XDS document that is sent back by the query and any error messages.

If we now deploy our policy and a event triggers the rules we should see something like this:

eDirectory_ACME-RES-TREE ST:Injecting User Agent XDS command document into Subscriber channel.

After that we should see the query being processed by the driver:

<nds dtdversion="3.5" ndsversion="8.x">
<source>
<product version="3.5.11.20080307 ">DirXML</product>
<contact>Novell, Inc.</contact>
</source>
<input>
<query class-name="User" dest-dn="Myorg\Users" event-id="0" scope="subtree">
<search-class class-name="User"/>
<search-attr attr-name="Surname">
<value>Doe</value>
</search-attr>
<read-attr/>
</query>
</input>
</nds> 

Eventually we should see an instance returned with the results we want.

<nds dtdversion="3.5" ndsversion="8.x">
<source>
<product version="3.5.11.20080307 ">DirXML</product>
<contact>Novell, Inc.</contact>

</source>
<output>
<instance class-name="User" event-id="0" qualified-src-dn="O=Myorg\OU=Acme\OU=Eko\OU=Users\CN=elmma" src-dn="\ACME-RES-TREE\Myorg\Acme\Eko\Users\elmma" src-entry-id="35488"/>
<status event-id="0" level="success"></status>
</output>
</nds> 

Using XPath we can access part of the instance that is now stored in the lv-sendquery variable.

Using our lv-checkquery variable we can see the result of the query, this is good if we don't get back an instance, when we get an error returned.

HRdriver PT: Token Value: {<nds> @dtdversion = "3.5" @ndsversion = "8.x"}.
00:59:01 68865BB0 Drvrs: HRdriver PT: Arg Value: {<nds> @dtdversion = "3.5" @ndsversion = "8.x"}.
00:59:01 68865BB0 Drvrs: HRdriver PT: Action: do-set-local-variable("lv-checkquery",scope="policy",arg-node-set(token-xml-serialize(token-local-variable("lv-sendquery")))).
00:59:01 68865BB0 Drvrs: HRdriver PT: arg-node-set(token-xml-serialize(token-local-variable("lv-sendquery")))
00:59:01 68865BB0 Drvrs: HRdriver PT: token-xml-serialize(token-local-variable("lv-sendquery"))
00:59:01 68865BB0 Drvrs: HRdriver PT: token-xml-serialize(token-local-variable("lv-sendquery"))
00:59:01 68865BB0 Drvrs: HRdriver PT: token-local-variable("lv-sendquery")
00:59:01 68865BB0 Drvrs: HRdriver PT: Token Value: {<nds> @dtdversion = "3.5" @ndsversion = "8.x"}.
00:59:01 68865BB0 Drvrs: HRdriver PT: Arg Value: {<nds> @dtdversion = "3.5" @ndsversion = "8.x"}.
00:59:01 68865BB0 Drvrs: HRdriver PT: Token Value: "<nds dtdversion="3.5" ndsversion="8.x">
   <source>
      <product version="3.5.11.20080307 ">DirXML</product>
      <contact>Novell, Inc.</contact>
   </source>
   <output>
    <instance class-name="User" event-id="0" qualified-src-dn="O=Myorg\OU=Acme\OU=Eko\OU=Users\CN=elmma" src-dn="\ACME-RES-TREE\Myorg\Acme\Eko\Users\elmma" src-entry-id="35488"/>
      <status event-id="0" level="success"/>
   </output>
</nds>". 

In this example I'm querying from a driver connected to the Identity Vault, let's call it driver "HR", the query is sent to an eDirectory drivers subscriber channel, it travels through the subscriber channel and is then sent to the eDirectory driver that is connected to the other Identity Vault, to it's publisher channel.

This is what happens if the driver on "our" side is stopped when we send the query, we get this response to our command.

<nds dtdversion="3.5" ndsversion="8.x">
   <source>
      <product version="3.5.11.20080307 ">DirXML</product>
      <contact>Novell, Inc.</contact>
   </source>
   <output>
      <status level="error">Code(-9010) An exception occurred: novell.jclient.JCException: request -641 ERR_INVALID_REQUEST</status>
   </output>
</nds> 

Additionally we'll see this in the trace:

 ENG ET:
DirXML Log Event -------------------
Status: Error
Message: Code(-9139) Unable to process DirXML sub-verb DSVR_OPEN_DRIVER_ACTION because driver \ACME-META-TREE\ACME\System\DriverSet01\eDirectory_ACME-RES-TREE is not running.
21:49:09 68C6DBB0 Drvrs: ENG ET:
DirXML Log Event -------------------
Status: Error
Message: Code(-9140) Error processing DirXML sub-verb DSVR_OPEN_DRIVER_ACTION: com.novell.nds.dhutil.DSErr: invalid request (-641)
   at com.novell.nds.dirxml.engine.verb.OpenDriverAction.processSubVerb(OpenDriverAction.java:109)
   at com.novell.nds.dirxml.engine.verb.DirXMLVerbs$SetVerbHandler.processVerb(DirXMLVerbs.java:477)
   at com.novell.nds.dhutil.VerbProcessor$HandlerThread.run(VerbProcessor.java:507)
   at java.lang.Thread.run(Unknown Source)
   
   

If the driver on the other side is not running we get this response:

<nds dtdversion="3.5" ndsversion="8.x">
   <source>
      <product version="3.5.11.20080307 ">DirXML</product>
      <contact>Novell, Inc.</contact>
   </source>
   <output>
      <status level="retry">Code(-9006) The driver returned a "retry" status indicating that the operation should be retried later. Detail from driver: java.net.ConnectException: Connection refused</status>
   </output>
</nds>

So it's a good idea to check the query variable with XPath to see if it contains what we expect and not just assume it went through fine.

We can for example access the src-dn attribute of our (first) instance that is stored in the lv-sendquery variable using this XPath expression in policy builder:

$lv-sendquery/nds/output/instance/@src-dn