Using PowerShell to connect to Lotus Notes COM object

Sometimes you have to query and/or change certain data in a Domino Directory. There are in general 2 options to connect to Lotus Notes:

  1. via LDAP
  2. via the Notes COM Object

Querying via LDAP is a standardized and easy-to-understand way. But it has some disadvantages:

  • you cannot perform write operations
  • multi-value fields are hard to identify

So the alternative is using the COM object. For this the above mentioned disadvantages do not count. So the question is now – how to do this in PowerShell??

First of all, what you need is an installed Lotus Notes Client on the machine which will run the script. This Lotus Notes Client must be installed in Single User Mode (no Multi-User!) to work with the examples below. Single User install means that the Notes-Data folder is stored as a subfolder of the Notes installation directory, not in the users’s profile. Next I highly recommend a rich editor. I personally prefer Sapien PowerShell Studio, but others like the integrated ISE or PowerGUI work as well.

Before you can query anything, you must make sure, that the PowerShell window is running in 32-bit mode. There are several ways to do that and I saw each work or not – depending on client Operation system, .NET Framework versions, local permissions, … So try out what’s working best for you.

Option 1:

$PowerShellRunSpace = [System.Runtime.InterOpServices.Marshal]::SizeOf([System.IntPtr])

if (($PowerShellRunSpace -ne 4) -and ($PowerShellRunSpace -ne 2)) {exit} #because you have a 64-bit PowerShell

Option 2:

if([Environment]::Is64BitProcess -eq $true) {exit} #because you have a 64-bit PowerShell

Now after that is done, we can start connecting to Notes. To do that you have to understand how Notes “thinks” and works in the background. That’s the way the client behaves, too. To be able to work with Notes you need a Notes Session which can be opened by using your Notes ID and the corresponding password. Once this is open, you can do anything, which your ID is allowed to do, that means, open Notes databases, create Notes databases, read and modify documents, …. And how does all this work? With some kind of in-line LotusScript! Yes! That means if you can develop Lotus Script and PowerShell, then you can do anything with PowerShell which you can do with Lotus Script. So let’s look how the connection to the Domino Directory works:

$NotesSession = New-Object -ComObject Lotus.NotesSession #open the Notes Session

$NotesSession.Initialize(“mySecretNotesPassword”) #provide the password for the ID file

#$NotesSession.Initialize() #if no password is provided, Notes will ask for the password

$NotesAdressbook = $NotesSession.GetDatabase(“Domino01/NotesOrg”, names.nsf, 0)

You see the above Script code is Lotus Script which opens the names.nsf file from the Domino Server “Domino01/NotesOrg”. Now you can continue open Views, Documents, edit them, save your changes and do anything you want.

The COM object is really cool, but it has one very big disadvantage: It is very slow. So I highly recommend to use functions like GetDocumentByKey() and GetAllDocumentsByKey() as often as possible. This will drastically increase the performance of your script.

Happy Notes-PowerShell-Scripting!

Published by Andreas

Founder of M365 Evangelists Cloud-Architect, Strategy Consultant, Consultant for Microsoft technologies, Graph API enthusiast, PowerShell enthusiast