# 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> 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 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>. 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;. If multiple <instance>'s are returned then the dest-dn of the current operation is set to the single character &#xFFFD; .

### 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>
>     </do-find-matching-object>

## 1. Allowed Content

> arg-dn
>   DN argument
> arg-match-attr
>   match attribute argument

## 2. Attributes

> Attribute | Value(s) | Default Value
> --- | --- | ---
> disabled | true | false true if this element is disabled | false
> notrace | true | false true if this element should not be traced during execution of policy | false
> scope | entry | subordinates | subtree the scope to be searched | subtree

## 3. Content Rule

> (( arg-dn ? , arg-match-attr + ) | ( arg-dn , arg-match-attr * ) )

## 4. Parent Elements

> actions
>   actions that are performed by a <rule>
> arg-actions
>   actions argument

Top Elements || All Elements || Tree