do-find-matching-object

The <do-find-matching-object> action causes a query to be performed in the destination datastore and an appropriate dest-dn or an appropriate dest-dn <association> to be added to the current operation. It replaces the functionality available via <matching-rule> in DirXML 1.x. It is only valid when the current operation is <add>.

<arg-dn> is required when scope="entry" and optional otherwise.

At least one <arg-match-attr> or <arg-query-condition> is required when scope="subtree" or scope="subordinates". Note that since it is undefined what <query> does with <search-attr> when scope="entry", it is also undefined what <do-find-matching-object> will do.

The <query> generated will have a scope attribute based on the scope attribute of the <do-find-matching-object>. It will have a dest-dn attribute set to the content of <arg-dn>, if any. It will have a class-name attribute and <search-class> based on the class-name attribute from the current object. For each <arg-match-attr> there will be a <search-attr> for the same attribute, populated with either the <arg-value> content of <arg-match-attr> (if it exists) or the value(s) available in the current operation. If no value is available, then no query will be performed and the action will not find a match.

Any <instance> elements returned from the query will be considered matches.

If the destination datastore is the application, then an association will be added to the current operation for each <instance> that is returned. No query will be performed if the current operation already has a non-empty association, thus allowing multiple <do-find-matching-object> actions to be strung together in the same rule. If no more than one instance is returned, then the local variable error.do-find-matching-object will be unavailable. If more than one <instance> is returned, then the local variable error.do-find-matching-object will be set to a node-set containing the list of src-dn's from the instances if they are available, or the list of associations if the src-dn's are not available.

If the destination datastore is eDirectory, then the dest-dn attribute for the current operation will be set. No query will be performed if the current operation already has a non-empty dest-dn attribute, thus allowing multiple <do-find-matching-object> action to be strung together in the same rule. If only a single <instance> is returned and that <instance> is not already associated then the dest-dn of the current operation is set to the src-dn of the <instance> and the local variable error.do-find-matching-object will be unavailable. If only a single <instance> is returned and that <instance> is already associated then the dest-dn of the current operation is set to the single character &#xFFFC; and the local variable error.do-find-matching-object will be set to the src-dn from that <instance>. If multiple <instance>'s are returned then the dest-dn of the current operation is set to the single character &#xFFFD; and the local variable error.do-find-matching-object will be set to a node-set containing the src-dn's from those <instance>'s.

The operation property error.do-find-matching-object for the current operation will also be set to the value of the local variable error.do-find-matching-object.

When the attribute return-on-first-match = true , this attribute will be appended to the resultant <query>, the Driver Shim or Engine will interprest this query into multiple search criteria(i.e each of <search-condition> or <search-attr> will be treated as a seperate search criteria and expected to have the attribute search-criteria-id set) and are executed sequentially in the same order as received.
As and when a non-empty result is received for particular search criteria or sub query, the associated search-criteria-id will be appended to the instance documents and returned. We exit from the query execution i.e we will not proceed to the next search-criteria when a match has been found.
Note: The support for return-on-first-match depends on the implementation in the target Driver Shim.

Example

<do-find-matching-object scope="subordinates">
  <arg-dn>
	<token-text>Users/</token-text>
	<token-attr name="OU"/>
  </arg-dn>
  <arg-match-attr name="CN"/>
  <arg-match-attr name="L">
	<arg-value>
	  <token-text>Provo</token-text>
	</arg-value>
  </arg-match-attr>
  <arg-query-condition name="or">
	<arg-match-attr name="Given Name"/>
	<arg-query-condition name="not">
	  <arg-match-attr name="Title">
		<arg-value type="string">
		  <token-text xml:space="preserve">SSE</token-text>
		</arg-value>
	  </arg-match-attr>
	</arg-query-condition>
  </arg-query-condition>
</do-find-matching-object>

<do-find-matching-object return-on-first-match="true" scope="subtree">
  <arg-match-attr name="L" search-criteria-id="locationMatch">
	<arg-value type="string">
      <token-text xml:space="preserve">Bangalore</token-text>
	</arg-value>
  </arg-match-attr>
  <arg-query-condition name="and" search-criteria-id="requiredAttributeCombination">
	<arg-match-attr name="Surname"/>
	<arg-match-attr name="Given Name"/>
  </arg-query-condition>
</do-find-matching-object>