Contact TLCC

Change the ACL via LotusScript Click here to see all the Developer/Admin Tips

Date tip published:06/26/2006
Description:This tip demonstrates how to change the Access Control List using LotusScript code. The example code adds an entry into the ACL for all databases in a specified directory.

To learn more about LotusScript use the following links:

Beginner LotusScript for Notes Domino 7
Intermediate LotusScript for Notes and Domino 7
Advanced LotusScript for Notes Domino 7
Notes Domino 7 LotusScript Package

Change the ACL via LotusScript

The Domino Object Model contains classes to read, change, add or delete entries in the Access Control List (ACL) of a database. This can be very useful when a person/group must be added to all the databases on a server. One example would be to add an Admin group to all the databases on a server if that entry did not already exist. This tip will cover how to change the ACL for all databases in a directory. Corresponding Java classes also exist to allow similar code in a Java agent, servlet, or program.

Below is the user interface for changing the ACL.

NotesDatabase Class
The NotesDatabase class includes methods to read, create, modify or revoke access in a database ACL. However, the methods in the NotesDatabase class cannot be used to set ACL attributes. The methods in the NotesDatabase class to work with the ACL are:

Call notesDatabase.GrantAccess( name$, level% )Where name$ is the name of the person or group to grant access, and level% is a constant value representing the level of access to grant. The level% constants are:
Granting access to an already existing name will cause that entry to be modified to the new level.
Call notesDatabase.RevokeAccess( name$ )Removes the named entry from the ACL.
level% = notesDatabase.QueryAccess( name$ )Determines the access level for the named entry.

NotesACL Class

The NotesACL class includes several methods to return an ACL entry from the database's Access Control List. The following diagram shows the class hierarchy to access and work with a NotesACLEntry object in a Notes/Domino database.

In the diagram above, the CreateACLEntry method of the NotesACL class was used to create a new NotesACLEntry object. There are other ways to set the NotesACLEntry object. All of the methods in the NotesACL class to set the NotesACLEntry object are summarized in the following table:

Set notesACLEntry = notesACL.GetEntry( name$ )Returns the ACL entry for the specified name$. If the named entry does not exist in the ACL, then the NotesACLEntry object is set to Nothing.
Set notesACLEntry = notesACL.CreateACLEntry( name$, level% )Creates a new entry in the ACL with the specified access level.
Set notesACLEntry = notesACL.GetFirstEntryReturns the first entry in the ACL. Note that this may not be the same as the first entry listed in the ACL dialog box.
Set notesACLEntry = notesACL.GetNextEntry( entry )Returns the next entry in the ACL.
Call notesACL.RemoveACLEntry( name$ )This method will remove the named ACL entry.

NotesACLEntry Class

Use the properties in the NotesACLEntry class to set the ACL access level and attributes for an entry in the database ACL.

Some of the more useful properties in the NotesACLEntry class are:

Action DesiredProperty
To change the level of the entryLevel
To change the type of user in the entry. This corresponds to the User Type in the ACL dialog box.UserType
To set the attributes for the entry. Each of these properties is a boolean value (true or false.)CanCreateDocuments

Pulling It All Together - An Agent that Changes the ACL of Databases

Let's assume we have a Domino environment that was setup by a new Administrator who put his name in the ACL of all databases. We want to delete this entry from the ACL and add a new ACL entry for "Admins". This new entry is a group containing only people (not servers) and should have manager access. The code below is for an agent that will run on a Domino server or Notes client and change the ACL of all the databases in the "aclchange" directory.

This sample code has a If statement on line 13 to only change databases the "aclchange" directory (under the Notes data directory. Remove this If statement (and the corresponding End If on line 30) to run this code on all databases. This code is from an agent set to run from the actions menu. The agent can be in any database but the agent invoker must have manager access to the database being changed in order to run this code successfully. This code will run on both workstations and servers. Remember that changes to the ACL will propagate to other servers/workstations using replication.

Line 8 uses the NotesDBDirectory class to get access to all databases in the Notes data directory. Line 9 gets the first database on the computer and then loops through every database using the Do Until on line 11 and the getNextDatabase on line 31. Line 15 opens the database (which is required to get access to the ACL) and line 18 gets the ACL object (NotesACL class.) Line 19 creates a new entry for "Admins" and sets the level to manager. Line 20 sets the UserType to be a person group. Line 21 sets the ability to delete documents for this entry. Line 23 checks for the old admin's name, John Smith/MyCo. In this example it is in hierarchal format but the GetEntry also works with abbreviated names (John Smith/MyCo). It is not case sensitive. If this entry is found, than line 26 removes the entry for the old admin. Line 28 is important, it saves the changes to the ACL. Just like a document must be saved to save any changes made in LotusScript, the ACL must also be saved to save changes.

1.Sub Initialize
2. Dim session As New NotesSession
3. Dim db As NotesDatabase
4. Dim DBdir As NotesDbDirectory
5. Dim acl As NotesACL
6. Dim aclentry As NotesACLEntry
7. Dim badaclentry As NotesACLEntry
8. Set DBDir = session.GetDbDirectory("")
9. Set db = DBdir.GetFirstDatabase(Database)
10. Dim flag As Boolean
11. Do Until db Is Nothing
12. 'Only change what is in the aclchange directory, remove If statement to do all databases
13. If Instr(1, db.FilePath,"aclchange" , 4) Then
14.  'Open the database
15.   flag = db.Open("","")
16.   If flag Then
17.    'First create new entry for Admins, set UserType and allow deletion of documents
18.    Set acl =db.ACL
19.    Set aclentry =  acl.CreateACLEntry("Admins", ACLLEVEL_MANAGER)
20.    aclentry.UserType = ACLTYPE_PERSON_GROUP
21.    aclentry.CanDeleteDocuments = True
22.    'Search for the old admin's name
23.    Set badaclentry = acl.GetEntry("CN=John Smith/O=MyCo" )
24.    If Not badaclentry Is Nothing Then
25.      'remove the entry
26.      badaclentry.Remove
27.     End If
28.    acl.Save
29.   End If
30.  End If
31.  Set db = DBDir.GetNextDatabase
32. Loop
33.End Sub