@NameLookup (Formula Language)

Syntax

@NameLookup( [ lookupType ] ; username; itemtoreturn )

Parameters

[ lookupType ]

Keyword. Specifies the type of lookup to perform. Supply one or more of the following keywords, separated from each other with a colon:

[NoUpdate]

Default. Returns a list of user names. Corresponds to NAME_LOOKUP_NOUPDATE flag for Notes® API. You can specify this keyword along with the other keywords excluding [ForceUpdate].

[ForceUpdate]

Forces the name space (view) to be updated. Corresponds to NAME_LOOKUP_UPDATE flag for Notes® API. You can specify this keyword along with the other keywords excluding [NoUpdate].

The following keywords can be used along with the [NoUpdate] or [ForceUpdate].

[NoSearching]

Searches only the first Domino® Directory containing the "($Users)" view, which is the local Names.nsf database, and returns a list of single text values for each specified user name. This keyword specifies to not retrieve values from the mail server's directory. An empty string is returned for no match found. Corresponds to NAME_LOOKUP_NOSEARCHING flag for Notes® API.

[Exhaustive]

Searches for each value in the username argument through all directories, even after a matching username has been found. Without this option, the search for each username ends with the first directory that contains a match. However, multiple matches may still be returned from that directory. This keyword returns values from the local Names.nsf database as well as the mail server's directory. If the mail server is unavailable, or the Recipient name type ahead setting in the current location document is Disabled or Local Only, it retrieves values from the current name server. If you are using LDAP, it also retrieves values from the LDAP directory. The user's value is omitted if there is no match found.

Without the [Exhaustive] argument, a value in the user's local address book may hide values in the server directories. For instance, suppose usernames = "Smith", and your local address book has a "Mary Smith" in it. Unless you specify [Exhaustive], @NameLookup will not notice the entry for "George Smith" in the server address book, and will only return information for Mary.

[TrustedOnly]

Searches only those Domino® Directories that contain trust information and returns a list of single text values for each specified user name. An empty string is returned for no match found. Corresponds to NAME_LOOKUP_TRUSTED_NAMESPACES flag for Notes® API.

username

Text or text list. Specify primary or alternate Notes/Domino user names to retrieve their information from the Domino® Directory.

itemtoreturn

Text. Item or field name from the Domino® Directory Contact record that you would like to retrieve information from.

Return value

valuelist

Text list. @NameLookup returns a list of single values for each matching user. If a given username value matches multiple users, one entry will be returned for each matching user. Unless [Exhaustive] has been specified, an empty string is returned for usernames for which no match was found.

In no case will more than one value be returned from each matching contact document. If the requested field is multivalued (e.g. the FullName field), only the first value in the field is returned.

Usage

@NameLookup cannot be used in form selection and view column formulas.

To enable server directory data to be included in this function's return value, the Recipient name type ahead setting in the Mail tab of the current location document must be set to Local Then Server.

All the users from secondary directories, including the LDAP directory, need to be authenticated first, and then authorized to access a Notes/Domino database administered by the Domino® server. The Directory Assistance derived from the Master Domino® Directory uses trusted name rules to authenticate users. Once a user name is authenticated, it is added to the list of trusted names. This user name is then compared to the ACL for authorization.

For more information on searching the LDAP directory, see "Setting up Notes® to search an Internet directory for addresses" in the Notes® Help.

Examples

1. The following formulas return "Katsushi_B" : "Jones_B1" : "Smith_C" : ""

   @NameLookup ( [NoUpdate]; "Katsushi":"Jones":"Smith": 
                "Yoshito"; "Item")
   @NameLookup ( [ForceUpdate]; "Katsushi":"Jones":"Smith": 
              "Yoshito"; "Item")

2. The following formula returns "Katsushi_B" : "Jones_B1" :"" : ""

   @NameLookup ( [NoSearching]; "Katsushi":"Jones":"Smith": 
              "Yoshito"; "Item")

3. The following formula returns "Katsushi_B" : "Katsushi_C" : "Jones_B1" : "Jones_B2" : "Smith_C"

   @NameLookup ( [Exhaustive]; "Katsushi":"Jones":"Smith": 
              "Yoshito"; "Item")

4. If the current user is a software engineer, the following code, when added as the default value for a field, displays SOFTWARE ENGINEER.

   @NameLookup([Exhaustive];@UserName;"JobTitle")