Getting Session and User Information
Session information tells you things about the current user, such as her name , the type of client she is using to access your application, what roles she has in a database, and what her mail file is. Table 12.9 lists some of these useful session and user information @Functions.
Table 12.9. @Functions for Session and User Information
| @Function | Result |
|---|---|
| @BrowserInfo() | Returns information about the Web browser |
| @ClientType | Returns the type of client for the user, Notes or Web |
| @UserName | Returns the username |
| @Name() | Returns components of the user's name when used in conjunction with @UserName |
| @MailDBName | Returns the current user's mail server name and path to the mail file |
| @UserAccess() | Returns the user's access level to a database |
| @UserNamesList | Returns a list containing the user's name, hierarchical name, ACL roles, and groups |
| @UserPrivileges | Returns a list of the user's privileges to the database |
| @UserRoles | Returns a list of the user's roles in a database |
To determine whether a user was a Web or a Notes client before R4.6, you used @UserRoles() in a formula such as the following:
@Contains(@UserRoles; "$$Web")
@ClientType , introduced in R4.6, returns Web or Notes without resorting to testing @UserRoles() . Nonetheless, @UserRoles() is very useful in its own right. Consider the following example that enables you to take actions based on the user's role assignment in a database:
@If(@Contains(@UserRoles; "Profile")...
NOTE
For an explanation of roles in a database, see Chapter 23, "Security and Domino Applications."
The @UserName function returns the name of the current user in canonical format if it is a hierarchical username. A hierarchical name contains components including the full name, the organization, organizational unit, and, if available, the country. Your Notes user ID is a hierarchical name. If the name is nonhierarchical, @UserName displays just the name. A Web user might have a nonhierarchical name, for example. Canonical format displays all the components of a name, including common name (CN), organizational unit (OU), organization (O), and country (C). A name displayed in full canonical format would look like the following:
CN=Steve Kern/OU=IT/O=MyCompany/C=US
As you can imagine, this isn't something you would want to display to users very often. The function @Name([ argument ]; notesname ) can be used to extract various pieces of canonical names . Table 12.10 lists the arguments for @Name() .
Table 12.10. Arguments for @Name()
| Argument | Returns |
|---|---|
| [A] | Returns the administration management domain name (ADMD) |
| [Abbreviate] | Displays the name in abbreviated format |
| [Address821] | Returns an address in the Internet-standard RFC 821 format |
| [C] | Returns the country |
| [Canonicalize] | Displays an abbreviated name in full canonical format |
| [CN] | Returns the common name |
| [G] | Returns the first (given) name |
| [HIERARCHYONLY] | Returns the hierarchy of a name without the common name component |
| [I] | Returns the initials |
| [LP] | Returns the local part of a standard Internet name |
| [O] | Returns the organization component |
| [OU N ] | Returns the N th organizational component (for example, [OU1] , [OU2] ) |
| [P] | Returns the private management domain name (PRMD) |
| [PHRASE] | Returns the phrase part of a standard Internet name |
| [Q] | Returns the generational qualifier |
| [S] | Returns the last name |
| [TOAT] | Returns the LDAP attribute type of a Domino field |
| [TODATATYPE] | Returns the Domino datatype name from an LDAP syntax name |
| [TOFIELD] | Returns the Domino field name when the LDAP attribute type is given |
| [TOFORM] | Returns the Domino form name from an LDAP object class |
| [TOKEYWORD] | Displays the name parts , except the common name, in reverse order with back slashes instead of forward slashes ( COOU ) |
| [TOOC] | Returns the LDAP object class |
| [TOSYNTAX] | Returns the LDAP syntax name from a Domino data type |
CAUTION
The components [A] , [G] , [I] , [P] , [Q] , and [S] were designed for use with gateways and other mail systems. They do not function with a Notes name.
The most frequently used arguments are [CN] , which returns the common name component, and [Abbreviate] , which returns the common name plus the organizational unit and organizational certifiers separated by forward slashes. Given the name John Smith, registered under the organizational unit IS of the organization MyCompany , the [CN] argument returns John Smith . [Abbreviate] returns John Smith/IS/MyCompany .
TIP
Use [Abbreviate] or [CN] to store names in fields that the users see. This is much more friendly than a canonical name.
You can use @Name and @UserName to build an edit history, as shown in Figure 12.8.
Figure 12.8. This subform tracks the edit history for a document.
The formula for the cEditors field uses the common name component to build a text list of the last five editors, as in the following example:
REM {If the doc is not being saved, exit } ; REM ; @If(@IsDocBeingSaved ; @Success ; @Return("") ) ; REM {If the doc is new, use @Name... etc. } ; @If(@IsNewDoc cEditors = "" ; @Name([CN];@UserName) ; @Subset( (@Name([CN]; @UserName) : cEditors) ; 5) )
The formula for the dEditDate field is the following:
REM {If the doc is not being saved, exit } ; @If(@IsDocBeingSaved ; @Success ; @Return("") ) ; REM {If the doc is new, or the edit date is blank use @Now} ; @If(@IsNewDoc dEditDate = "" ; @Now ; @Subset( ( @Now : dEditDate ) ; 5) )
Because the fields cEditors and dEditDate are placed beside each other in a table, the names of the users who edited the documents are placed right next to the dates on which the edit took place.