# token-unique-name

<token-unique-name> expands to a pattern based name that is unique in the destination datastore according to the criteria specified.

Each <arg-string> provides a pattern to be used to create a proposed name.

A proposed name is tested by performing a query for that value in the name attribute against the destination datastore using <arg-dn> or <arg-association> as the base of the query and scope as the scope of the query. If the destination datastore is eDirectory and name is omitted, then a search is performed against the pseudo-attribute "[Entry].rdn", which represents the RDN of an object without respect to what the naming attribute might be. If the destination datastore is the application, then name is required.

A pattern may be tested with and/or without a counter as indicated by counter-use and counter-pattern. When a pattern is tested with a counter, the pattern is tested repeatedly with an appended counter until a name is found that does not return any instances or the counter is exhausted. The counter starting value is specified by counter-start and the counter maximum value is specified in terms of the maximum number of digits as specified by counter-digits. If the number of digits is less than those specified, then the counter will be right padded with zeros unless the counter-pad attribute is set to false. The counter is considered exhausted when the counter can no longer be represented by the specified number of digits.

As soon as a proposed name is determined to be unique, the testing of names is stopped and the unique name is returned.

The order of proposed names is tested as follows:

- Each pattern is tested in the order specified. If counter-use="always" and the pattern is one of the patterns indicated by counter-pattern then the pattern is tested with a counter, otherwise it is tested without a counter.
- If no unique name has been found after the patterns have been exhausted and counter-use="fallback", then the pattern(s) indicated by counter-pattern are retried with a counter.

If all specified combinations of patterns and counters are exhausted, then the action specified by on-unavailable is taken,

### Example

>     <token-unique-name counter-digits="2" counter-pad="true" counter-pattern="first" counter-start="1" counter-use="fallback" name="CN" on-unavailable="error" scope="subtree">
>       <arg-string>
>         <token-upper-case>
>           <token-substring length="1" start="0">
>             <token-attr name="Given Name"/>
>           </token-substring>
>           <token-attr name="Surname"/>
>         </token-upper-case>
>       </arg-string>
>       <arg-string>
>         <token-upper-case>
>           <token-substring length="1" start="0">
>             <token-attr name="Given Name"/>
>           </token-substring>
>           <token-substring length="1" start="0">
>             <token-attr name="MI"/>
>           </token-substring>
>           <token-attr name="Surname"/>
>         </token-upper-case>
>       </arg-string>
>       <arg-string>
>         <token-upper-case>
>           <token-attr name="Given Name"/>
>           <token-attr name="Surname"/>
>         </token-upper-case>
>       </arg-string>
>     </token-unique-name>

## 1. Allowed Content

> arg-dn
>   DN argument
> arg-association
>   association argument
> arg-string
>   string argument

## 2. Attributes

> Attribute | Value(s) | Default Value
> --- | --- | ---
> counter-digits | CDATA width in digits of counter | #IMPLIED
> counter-pad | true | false enable/disable right zero padding of counter | true
> counter-pattern | first | last | all which pattern(s) to use counter with first - use counter only with the first pattern last - use counter only with the last pattern all - use counter with all patterns | last
> counter-start | CDATA number to start counter | 1
> counter-use | always | never | fallback when to use counters never - don't use counters always - always use counters on the patterns indicated by counter-pattern fallback - use counters counter the patterns indicated by counter-pattern only after all patterns have failed without counters | fallback
> name | CDATA name of attribute to check for uniqueness | #IMPLIED
> notrace | true | false true if this element should not be traced during execution of policy | false
> on-unavailable | ignore | warning | error | fatal action to take if unique name cannot be constructed ignore - ignore and return empty name warning - issue warning and return empty name error - generate error and abort current transaction fatal - generate fatal error and shut down driver | error
> scope | subordinates | subtree scope in which to check uniqueness | subtree

## 3. Content Rule

> (( arg-dn | arg-association ) ? , arg-string + )

## 4. Parent Elements

> arg-association
>   association argument
> arg-component
>   component argument
> arg-dn
>   DN argument
> arg-node-set
>   node set argument
> arg-password
>   password argument
> arg-string
>   string argument
> arg-value
>   value argument
> token-base64-decode
>   decode base64 data into a string
> token-base64-encode
>   encode a string into base64 data
> token-convert-time
>   convert a date/time from one format to another
> token-escape-for-dest-dn
>   convert a string for use in a destination DN
> token-escape-for-src-dn
>   convert a string for use in a source DN
> token-join
>   join a node-set into a string
> token-lower-case
>   convert a string to lower case
> token-map
>   map a string through a mapping table
> token-parse-dn
>   parse and/or convert a DN
> token-replace-all
>   replace all instances of a substring within a string
> token-replace-first
>   replace a single instance of a substring within a string
> token-split
>   split a string into a node-set
> token-substring
>   substring of a string
> token-upper-case
>   convert a string to upper case
> token-xml-parse
>   parse XML
> token-xml-serialize
>   serialize XML

Top Elements || All Elements || Tree