RapidIdentity Product Guide: New UI

Notes Adapter Actions

Enter a request in the Administration Requests database to delete a Notes Group.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

adminpServer

text, expression, variable

the name of the server hosting the AdminP process (default: the agent server)

name*

text, expression, variable

the name of the Group to delete

immediate

boolean, expression, variable

delete Group from Domino Directory immediately (default: false)

deleteWindowsGroup

boolean, expression, variable

also delete the corresponding Windows Group (default: false)

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

deleted = adminpDeleteNotesGroup(sessionNotes, "cn=server1/o=org", 
    "MyGroup", true)

Enter a request in the Administration Requests database to delete a Notes User.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

adminpServer

text, expression, variable

the name of the server hosting the AdminP process (default: the agent server)

name*

text, expression, variable

the full hierarchical name of the Notes User to delete

immediate

boolean, expression, variable

delete Notes User from Domino Directory immediately (default: false)

mailFileAction*

choice (DELETE_ALL, DELETE_HOME, DELETE_NONE), text, expression, variable

disposition of the Notes User's mail file

denyGroup

text, expression, variable

name of an existing deny access group to which the name of the Notes User is added (default: none)

deleteWindowsUser

boolean, expression, variable

also delete the corresponding Windows User (default: false)

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

deleted = adminpDeleteNotesUser(sessionNotes, "cn=server1/o=org", 
    "John Doe", true, "DELETE_HOME", false)

Enter a request in the Administration Requests database to move a Notes User's mail file.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

adminpServer

text, expression, variable

the name of the server hosting the AdminP process (default: the agent server)

username*

text, expression, variable

the full hierarchical name of the Notes User to be moved

newHomeServer*

text, expression, variable

the name of the new home mail server

newHomeServerMailPath*

text, expression, variable

the path of the mail file on the new home mail server

useSCOS

boolean, expression, variable

the new mail file makes use of the shared mail feature (default: false)

newClusterReplicas

expression, variable

array of cluster replica server names and paths (e.g. [server1, server1Path, ....])

deleteOldClusterReplicas

boolean, expression, variable

delete old cluster replicas (default: false)

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

result = adminpMoveNotesMailUser(sessionNotes, "cn=server1/o=org", 
    "John Doe", "cn=server2/o=org", "/local/notesdata/jdoe.id", 
    false, false, false)

Enter a request in the Administration Requests database to move a Notes User's roaming files to another server.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

adminpServer

text, expression, variable

the name of the server hosting the AdminP process (default: the agent server)

username*

text, expression, variable

the full hierarchical name of the Notes User to be moved

newServer*

text, expression, variable

the new roaming server

newServerSubdir*

text, expression, variable

the new path on the roaming server

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

status = adminpMoveNotesRoamingUser(sessionNotes, 
    "cn=server1/o=org", "John Doe", "cn=server2/o=org", 
    "/local/notesdata/roaming/jdoe")

Enter requests in the Administration Requests database to move and optionally rename a Notes User's name in the hierarchy.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

adminpServer

text, expression, variable

the name of the server hosting the AdminP process (default: the agent server)

username*

text, expression, variable

the current full hierarchical name of the Notes User to be moved

oldCertifier*

expression, variable

the current Certifier (defined with defineNotesCertifier)

newCertifier*

expression, variable

the new Certifier (defined with defineNotesCertifier)

newLastName

text, expression, variable

the new last name if Notes User is also to be renamed (default: no change)

newFirstName

text, expression, variable

the new first name if Notes User is also to be renamed (default: no change)

newMiddleInitial

text, expression, variable

the new middle initial if Notes User is also to be renamed (default: no change)

newOrgUnit

text, expression, variable

the new org unit if Notes User is also to be renamed (default: no change)

newAltCommonName

text, expression, variable

the new alternate common name if Notes User is also to be renamed (default: no change)

newAltOrgUnit

text, expression, variable

the new alternate org unit if Notes User is also to be renamed (default: no change)

newAltLanguage

text, expression, variable

the new alternate language if Notes User is also to be renamed (default: no change)

renameWindowsUser

boolean, expression, variable

also rename the corresponding Windows Notes User (default: false)

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

status = adminpMoveNotesUserInHierarchy(sessionNotes, 
    "cn=server1/o=org", "John Doe", cert1, cert2, "movetest")

Enter a request in the Administration Requests database to recertify a Notes User.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

adminpServer

text, expression, variable

the name of the server hosting the AdminP process (default: the agent server)

username*

text, expression, variable

the full hierarchical name of the Notes User to be recertified

certifier*

expression, variable

the Certifier (defined with defineNotesCertifier)

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

status = adminpRecertifyNotesUser(sessionNotes, "cn=server1/o=org", 
    "John Doe", cert1)

Enter a request in the Administration Requests database to rename a Notes Group.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

adminpServer

text, expression, variable

the name of the server hosting the AdminP process (default: the agent server)

oldName*

text, expression, variable

the current Notes Group name

newName*

text, expression, variable

the new Notes Group name

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

status = adminpRenameNotesGroup(sessionNotes, "cn=server1/o=org", 
    "MyGroup, "YourGroup")

Enter a request in the Administration Requests database to rename a Notes User.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

adminpServer

text, expression, variable

the name of the server hosting the AdminP process (default: the agent server)

username*

text, expression, variable

the current full hierarchical name of the Notes User to be renamed

certifier*

expression, variable

the Certifier (defined with defineNotesCertifier)

newLastName

text, expression, variable

the new last name (default: no change)

newFirstName

text, expression, variable

the new first name (default: no change)

newMiddleInitial

text, expression, variable

the new middle initial (default: no change)

newOrgUnit

text, expression, variable

the new org unit (default: no change)

newAltCommonName

text, expression, variable

the new alternate common name (default: no change)

newAltOrgUnit

text, expression, variable

the new alternate org unit (default: no change)

newAltLanguage

text, expression, variable

the new alternate language (default: no change)

renameWindowsUser

boolean, expression, variable

also rename corresponding Windows User (default: false)

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

status = adminpRenameNotesUser(sessionNotes, "cn=server1/o=org", 
    "John Doe", cert1, "Doh", "Jack")

Enter a request in the Administration Requests database to rename a Notes Web User.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

adminpServer

text, expression, variable

the name of the server hosting the AdminP process (default: the agent server)

username*

text, expression, variable

the current full hierarchical name of the Notes User to be renamed

newFullName

text, expression, variable

the new full hierarchical name (default: no change)

newLastName

text, expression, variable

the new last name (default: no change)

newFirstName

text, expression, variable

the new first name (default: no change)

newMiddleInitial

text, expression, variable

the new middle initial (default: no change)

newShortName

text, expression, variable

the new short name (default: no change)

newInternetAddress

text, expression, variable

the new internet address (default: no change)

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

status = adminpRenameNotesWebUser(sessionNotes, "cn=server1/o=org", 
    "John Doe", "Jack Doh", "Doh", "Jack")

Enter a request in the Administration Requests database to change the password management settings of a Notes User.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

adminpServer

text, expression, variable

the name of the server hosting the AdminP process (default: the agent server)

username*

text, expression, variable

the full hierarchical name of the Notes User to be renamed

notesPasswordCheckSetting

choice(CHECK,DONTCHECK,LOCKOUT), text, expression, variable

the check password setting (default: no change)

notesPasswordChangeInterval

expression, variable

the password change required interval (default: no change)

notesPasswordGracePeriod

expression, variable

the password change grace period (default: no change)

internetPasswordForceChange

boolean, expression, variable

force the user to change the password on next login (default: no change)

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

status = adminpSetNotesUserPasswordSettings(sessionNotes, 
    "cn=server1/o=org", "John Doe", ""LOCKOUT")

Enter a request in the Administration Requests database to upgrade a Notes User from a flat ID to a hierarchical ID.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

adminpServer

text, expression, variable

the name of the server hosting the AdminP process (default: the agent server)

username*

text, expression, variable

current username

certifier*

expression, variable

the Certifier (defined with defineNotesCertifier)

newOrgUnit

text, expression, variable

the new org unit

newAltCommonName

text, expression, variable

the new alternate common name

newAltOrgUnit

text, expression, variable

the new alternate org unit

newAltLanguage

text, expression, variable

the new alternate language

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

status = adminpUpgradeNotesUserToHierarchical(sessionNotes, 
    "cn=server1/o=org", "John Doe", cert1)

Build a notes FullName.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

certifier*

expression, variable

the Certifier (defined with defineNotesCertifier)

lastName*

text, expression, variable

the last name

firstName

text, expression, variable

the first name

middleInitial

text, expression, variable

the middle initial

ou

text, expression, variable

additional OU beyond the certifier

returnVariable

expression, variable

name of the variable to be assigned to the return value

Note

fullName = buildNotesFullName(sessionNotes, cert1, "Doe", "John")

Compare the HTTPPassword field for a Notes Record.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

db*

text, expression, variable

the database name

unid*

text, expression, variable

the UNID of the record

password*

password, string, expression, variable

the password

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

passwordsEqual = compareNotesHTTPPassword(sessionNotes, "names", 
    userRecord['@UNID'], <Password>)

Define a connection to a Notes Agent.

Property

Value

Description

host*

text, expression, variable

the host name or ip address of the Domino server hosting the RapidIdentity Notes Agent

port

expression, variable

the https port of the Domino server hosting the RapidIdentity Notes Agent (default: 443)

adminUser*

text, expression, variable

the login name of Notes administrative User

password*

password, string, expression, variable

the password for adminUser

options

expression, variable

A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTime which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout.

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

Global.notesAgentServer = "mynotesserver"
Global.notesAdminUser = "administrator"
Global.notesAdminPwd = <Password>
sessionNotes = defineNotesAgentConnection(Global.notesAgentServer, 
    Global.notesAdminUser,<Password>)

Define Notes certifier.

Property

Value

Description

certifierName*

text, expression, variable

the name of the notes certifier (e.g. o=myorg)

certifierIDFile

text, expression, variable

the full path on the agent server of idfile for the notes certifier (default: none, use Certificate Authority instead)

certifierPassword

password, string, expression, variable

the password for certifierIDFile (default: none)

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

cert0 = defineNotesCertifier("o=org", "/local/notesdata/org.id",
    <Password>)
cert1 = defineNotesCertifier("ou=orgunit1/o=org", 
    "/local/notesdata/orgunit1.id",<Password>)
cert2 = defineNotesCertifier("ou=orgunit2/o=org", 
    "/local/notesdata/orgunit2.id",<Password>)

Delete an existing Notes Record.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

db*

text, expression, variable

the database name

unid*

text, expression, variable

the UNID of the record

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

status = deleteNotesRecord(sessionNotes, "mytestdb", record['@UNID'])

Get an existing Notes Record.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

db*

text, expression, variable

the database name

unid*

text, expression, variable

the UNID of the record

attributes

text, expression, variable

comma separated list of attributes to return (default: none)

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

group = getNotesRecord(sessionNotes, "names", record['@UNID'], "+")

Get Notes Records.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

db*

text, expression, variable

the database name

filter

text, expression, variable

the search filter formula (default: all records)

maxResults

expression, variable

maximum number of Records to return (default: the server maximum)

attributes

text, expression, variable

comma separated list of attributes to return (default: none)

since

expression, variable

Date object - return only records created or modified since (default: none)

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

people = getNotesRecords(sessionNotes, "names", 'Type="Person"', 5)

Parse a Notes name.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

name*

text, expression, variable

the name to parse

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

parsedUsernameRecord = parseNotesName(sessionNotes, username)

Registers a new Notes User.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

record*

expression, variable

Record containing the registration properties

certifier*

expression, variable

the Certifier (defined with defineNotesCertifier)

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

userTemplate = createRecord()
setRecordFieldValue(userTemplate, "FirstName", "John")
setRecordFieldValue(userTemplate, "LastName", "Doe")
setRecordFieldValue(userTemplate, "IdFile", "/local/notesdata/JohnDoe.id")
setRecordFieldValue(userTemplate, "Password",<Password>)
setRecordFieldValue(userTemplate, "MailServer", "cn=server1/o=org")
setRecordFieldValue(userTemplate, "MailDBPath", "mail/JohnDoe")
setRecordFieldValue(userTemplate, "MailSystem", 1)
user1 = registerNewNotesUser(sessionNotes, userTemplate, cert1)

Create or update a Notes Record.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

db*

text, expression, variable

the database name

record*

expression, variable

the Record to save

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

groupTemplate = createRecord()
setRecordFieldValue(groupTemplate, "ListName", "Group1")
setRecordFieldValue(groupTemplate, "Type", "Group")
setRecordFieldValue(groupTemplate, "Form", "Group")
setRecordFieldValue(groupTemplate, "LocalAdmin", "LocalDomainAdmins")
setRecordFieldValue(groupTemplate, "Members", username1)
addRecordFieldValue(groupTemplate, "Members", username2, true)
group = saveNotesRecord(sessionNotes, "names", groupTemplate)

Send a console command to a Domino server.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

server

text, expression, variable

the name of the target server

cmd*

text, expression, variable

the console command

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

sent = sendNotesConsoleCommand(sessionNotes, "tell adminp process all")

Set the HTTPPassword field for a Notes Record.

Property

Value

Description

notesConnection*

expression, variable

the Notes Agent connection

db*

text, expression, variable

the database name

unid*

text, expression, variable

the UNID of the record

password*

password, string, expression, variable

the password

returnVariable

expression, variable

name of the variable to be assigned to the return value

Example

passwordSet = setNotesHTTPPassword(sessionNotes, "names", 
    userRecord['@UNID'],<Password>)

Notes databases do not have a fixed schema, but rather any record can have pretty much any field that conforms to the field naming restrictions imposed by Notes. Fields that start with $ are usually considered reserved or system fields and the adapter currently treats them as read-only. Each record also has metadata that is not stored as a field in the database and are available as read-only on any record. This metadata is represented in the adapter as fields that start with @.

Name

Type

Description

@UNID

String

The Universal ID of the record

@CREATED

Date

The creation timestamp

@MODIFIED

Date

The modification timestamp

@AUTHORS

String(s)

Names of those who have edited the record

The @UNID field will be included in all records returned by getNotesRecord() and getNotesRecords(). The other @ fields will only be returned if explicitly specified the attribute list or the attribute list is “+”. When calling saveNotesRecord(), a record that contains @UNID will be considered to be an update, whereas one without @UNID will create a new record in the database.

When searching using getNotesRecords(), you may specify a filter expression using Notes Formula Language which is similar to the expressions used in Lotus 1-2-3 spreadsheets and provides very powerful selection capabilities.

While any record can have pretty much any field, the Form field associates the record with a Notes form definition which includes a predefined set of fields and rules for what can or must in each defined field. A database can also have a default form that applies to records that don't have an explicitly specified Form. Whenever the adapter saves a record, it asks Notes to apply any applicable form validation before it saves the record. In this respect a form definition can be thought of a kind of schema. As part of that validation, Notes may add fields, changes fields, or reject the save altogether if any validation requirements are not met. The easiest way to get a list of the fields that a form supports is to open a record that uses the given form in Notes or Domino Administrator, right click on the record, select Document Properties, and then select the second tab of the little dialog that pops up. Another way would be to use getNotesRecords() with filter = 'Form = “xxx”' and maxResults = 1 and log the results.

In Notes, Users and Groups live in what is known both as the Domino Directory and the Public Address Book, which is a database usually called “names”.

A User is associated with the Person form and has an associate ID file, and usually an associated mail file. While it a possible to create a Person record directly using saveNotesRecord(), in order to create a User (as opposed to e.g. a contact), you must use registerNewNotesUser(), which can also create and certify the User's ID file, and optionally create the User's mail file. There are also several operations on Users, such as rename, move, delete, etc., that must be performed via the adminpXXX() family of actions. Failure to do so will result in inconsistencies in Notes.

A Group is associated with the Group form. Unlike Users, Groups are created directly using saveNotesRecord(), but like Users,  renaming and deleting groups must be performed via the adminpXXX() family of actions. Failure to do so will result in inconsistencies in Notes.

Name

Type

Description

AltFullName

String

(default: none) An alternate User name

AltFullNameLanguage

String

(default: none) The language for the alternate User name

AltOrgUnit

String(s)

(default: none) Alternate name(s) for the organizational unit to use when creating ID files

AltOrgUnitLang

String(s)

(default: none) Languages associated with the alternate name(s) for the organizational unit to use when creating ID files

CreateMailDBInBackground

Boolean

(default: false) Create mail database in the background (via AdminP)

EnforceUniqueShortName

Boolean

(default: true) Indicates whether a short name must be unique

Expiration

Date

(default: system default) The expiration date to use when creating ID file

FirstName

String

(default: blank) A first name for the User

ForeignDN

String

(default: none) A foreign DN for the User

ForwardDomain

String

(default: none) The forwarding domain for the user's mail file

FullName

String

(default: calculated from other fields)

GroupList

String(s)

(default: none) The Groups(s) to which the User is assigned during registration

IDType

Number

(default: 173) The type of ID file to create 171 → FLAT, 172 → HIERARCHICAL, 173 → SAME AS CERTIFIER

IdFile

String

(default: none) The ID file to be created; specify the complete path, for example, c:\notes\data\user.id

LastName

String

(default: blank) A last name for the User to be registered

Location

String

(default: none) A value for the location field in the Domino Directory record

MailACLManager

String

(default: none) A name that is assigned Manager access in the mail database ACL

MailCreateFTIndex

Boolean

(default: false) Indicates the creation of a full-text index for the mail database

MailDBPath

String

(default: none) The path of the User's mail file relative to the data directory, e.g. “mail\jones.nsf”

MailInternetAddress

String

(default: blank) The user's Internet name for sending and receiving mail

MailOwnerAccess

Number

(default: 0) The mail database ACL setting for the owner 0 → Manager, 1 → Designer, 2 → Editor

MailQuotaSizeLimit

Number

(default: no limit) The maximum size of the user's mail database, in megabytes.

MailQuotaWarningThreshold

Number

(default: no limit) The size, in megabytes, at which the user's mail database issues a warning that it is getting too large

MailReplicaServers

String(s)

(default: none) The names of servers to which the mail database will replicate.

MailServer

String

(default: none) The canonical name of the server containing the User's mail file

MailSystem

String

(default: 0) The user's mail system 0 → Notes, 1 → POP, 2 → IMAP, 3 → INotes, 4→ Internet, 5 → Other, 6 → None

MailTemplateName

String

(default: system default) The name of the template for the design of the mail file

MiddleInitial

String

(default: blank) A middle initial for the User

MinPasswordLength

Number

(default: system default) The strength assigned to a password in an ID file

NorthAmerican

Boolean

(default: system default) Indicates whether an ID file is North American

OrgUnit

String

(default: none) The organizational unit to use when creating ID file

Password

String

(default: none) Password for the user ID file

PolicyName

String

(default: none) The name of an explicit policy

PublicKeySize

Number

(default: system default) Size of the public key when creating ID file 630, 1024, 2048

RegistrationLog

String

(default: “certlog.nsf”) The log file to use when creating ID

RegistrationServer

String

(default: the agent server) The server to use when creating ID and performing other registration functions

RoamingCleanupPeriod

Number

(default: none) The interval in days for cleaning up data on Notes clients set up for roaming users - only needed when RoamingCleanupSetting == 1

RoamingCleanupSetting

String

(default: 0) Indicates the clean-up process for data on Notes clients set up for roaming users 0 → NEVER, 1 → EVERY_NDAYS, 2 → AT_SHUTDOWN, 3 → PROMPT

RoamingServer

String

(default: none) The server on which the user's roaming data is stored

RoamingSubdir

String

(default: none) The subdirectory that contains the user's roaming data

RoamingUser

Boolean

(default: false) Indicates whether a user is a roaming user

ShortName

String

(default: calculated from other fields) The short name when creating user ID

StoreIDInAddressBook

Boolean

(default: true) Indicates whether the ID file is stored in the Address Boook

StoreIDInMailFile

Boolean

(default: false) Indicates whether the ID file is stored in the user's mail file

SynchInternetPassword

Boolean

(default: true) Synchronizes the user's Internet password with the password for the Notes client ID.

UpdateAddressBook

Boolean

(default: true) Indicates whether an ID document in the Domino Directory is created when the ID file is created

The Administration Process (AdminP) is a facility that runs on the Domino Server and handles complex tasks that involve possibly many steps, such as moving, renaming, or deleting Users and Groups. These tasks are considered complex because them may involve fixing up or removing references to the User or Group across the Notes infrastructure as well as performing tasks outside of the database such as deleting or moving other files. You make requests to AdminP via one of the actions prefixed with adminP.

Unlike direct Record access, requests to AdminP expect Users and Groups to be identified by name rather than by @UNID. The name for a User can be found as the first value of the FullName field and the name for a Group can be found as the first value of the ListName field.

Requests to AdminP are processed asynchronously after the action returns, so subsequent operations on the User or Group usually will need to be delayed until AdminP has finished processing the request. AdminP normally only wakes up periodically to process its queue of requests, but you can use a console command to tell AdminP to process new requests immediately:

sendNotesConsoleCommand("tell adminp process new")

Note that many requests happen in multiple phases so waking up AdminP may only start the first step of the process, with each subsequent step happening one at a time each time adminp runs through its queue.