# Squirrel for HCL Domino (Freeware)

Internet Mail Collector for HCL Domino

Similar to squirrels gathering food like nuts, seeds, acorns and berries, this server program collects email messages from Internet mail servers and forwards them to the HCL Domino server.

<a href="/pages/-MR9FN6lxb6JIjc7Z2xh" class="button primary">Free Download</a>

{% hint style="info" %}
Follow development at Mastodon [#Squirrel4Domino](https://swiss.social/tags/squirrel4domino)

This tool is also shown on the [*HCL Domino Marketplace*](https://hclsofy.com/domino)
{% endhint %}

```
> Load RunJava JAddin Squirrel
03.04.2026 17:07:50   JVM: Java Virtual Machine initialized.
03.04.2026 17:07:50   RunJava: Started JAddin Java task.
03.04.2026 17:07:50   Squirrel: The Internet Mail Collector for HCL Domino - Version 2026.04.02
03.04.2026 17:07:50   Squirrel: Copyright iota systems GmbH / andy.brunner@k43.ch - All Rights Reserved
03.04.2026 17:07:50   Squirrel: Java VM heap size configuration: Maxiumum: 256 MiB / Used: 22 MiB / Free: 233 MiB
03.04.2026 17:07:50   Squirrel: License key valid for 10 mail account subscriptions until 2026-12-31
03.04.2026 17:07:50   Squirrel: IMAPS message forwarded to Joe Smith/ACME from jsmith@hotmail.com (Size 689 KB)
03.04.2026 17:07:50   Squirrel: POP3S message forwarded to Lee Chu/ACME from lchx815@gmx.net (Size 286 KB)
```

## Use Cases

1. Company A - a long-time HCL Domino customer - buys company B, which uses Exchange. During the migration, Squirrel allows the administrator to merge all Exchange/MIME emails from company B into HCL Domino of company A.
2. In addition to his own HCL Notes email, the HCL Domino administrator is responsible for several external MIME mail boxes he needs to monitor. To be able to process these MIME emails in his HCL Domino in-box, he uses Squirrel to consolidate message boxes.

## Description

There is no built-in function in HCL Domino to collect messages from an Internet mail server and to forward them to the user mail database. This server add-in allows the administrator to define the Internet mail servers which are allowed to be used for mail retrieval. The user or the administrator then defines the mail account subscriptions based on these connections. Squirrel works completely in the background while periodically connecting to Internet mail servers and processing the messages for users.

Squirrel reads POP3 and IMAP mail servers through standard Java Mail API calls. After processing the message, Squirrel creates a Notes mail document and stores it in the mailbox of the HCL Domino server it is running on without accessing the users mail database. All further processing and delivery of these email message is handled by the HCL Domino mail router.

## Features

* Runs on all server platforms supported by HCL Domino 9.0.1 FP8 or higher
* Support for multiple HCL Domino servers in a domain
* Support for IMAPS, IMAP, POP3S and POP3 Internet mail servers
* Support for OAuth 2.0 authentication with XOAUTH2 login (see [OAuth 2.0 Support](/oauth-2.0-support))
* HCL Domino password encryption enforced for all email accounts
* Freeware version for up to three active email accounts

## Freeware / Community Edition

* Squirrel may be used as a freeware version with a limit of three active mail accounts.
* You may contact us for a “Community Edition” license. This license is restricted to private or non-commercial use only.

## Credits

Foto by [Shane Young](https://unsplash.com/@shane_young?utm_source=unsplash\&utm_medium=referral\&utm_content=creditCopyText) on [Unsplash](https://unsplash.com/de/s/fotos/shane-young-squirrel?utm_source=unsplash\&utm_medium=referral\&utm_content=creditCopyText)

## Authors

Squirrel is a joint development of [iota systems GmbH](https://iota.ch) (HCL Notes Front-End) and [Andy Brunner](https://k43.ch/andy-brunner) (HCL Domino Back-End). They both cooperate in the future development, maintenance and support. If you encounter any issue or if you have a suggestion, please [let us know](/quick-start/contact-problem-reporting).

Created with love and passion in the beautiful country of 🇨🇭 Switzerland. This software shall be used for Good, not Evil. As far as we know, no squirrel or any other animal was harmed in the making of this software 😊

Copyright (c) iota systems GmbH / <andy.brunner@k43.ch> - All Rights Reserved.

![iota systems GmbH](/files/-MR4ql7luk4f5wlf-Rjl)

<figure><img src="/files/gFBTtmOP7i891baa1LFW" alt=""><figcaption><p>andy.brunner@k43.ch</p></figcaption></figure>


# Installation / Update

A short guide on how to install or upgrade Squirrel

## Prerequisites

* HCL Domino 9.0.1 FP8 or higher (requires Java Virtual Machine 1.8 or higher)
* Connection to the Internet mail server(s) from the HCL Domino server
* Root (and intermediate) certificates of the Internet mail server(s) in the CACert keystore file (see [Administrator Tips](/tips-for-the-administrator))
* Java Virtual Machine heap size with 256MB or more

## Installation / Update

### Step 1: Check Java VM Heap Size

To avoid out-of-memory errors in the Java Virtual Machine, make sure that the JVM heap size is set to at least 256 MB in the Notes.ini on the HCL Domino server, e.g. *JavaMaxHeapSize=256MB*

### Step 2: Copy distribution files

After [downloading](/quick-start/download) and unzipping the installation package, the distribution files must be copied as follows:

| File Name                   | Target Directory      | Description                                                                    |
| --------------------------- | --------------------- | ------------------------------------------------------------------------------ |
| SOFA-Logging.properties     | Domino                | *Only needed to enable OAUTH debugging (see* [*Debugging*](/debugging-tips)*)* |
| Squirrel.jar                | Domino/ndext/         | Server add-in                                                                  |
| 1-Squirrel-Jakarta-Mail.jar | Domino/ndext/         | Eclipse Jakarta Mail                                                           |
| Squirrel.ntf                | Domino data directory | Database template                                                              |

{% hint style="warning" %}
Under Linux/Unix/AIX, make sure that the JAR files are marked with executable rights thru 'chmod +rx‘
{% endhint %}

{% hint style="info" %}
The file name prefix '1-' ensures that the newer Eclipse Jakarta Mail is loaded in favor of the standard mail.jar included in HCL Domino (required for OAuth 2.0)
{% endhint %}

### Step 3: Create / Update Squirrel Database

* Sign the database template *Squirrel.ntf* with the HCL Domino server-id
* Create a new database *Squirrel.nsf* in the root data directory or replace the design of the existing database using the signed template
* Create, edit or verify the configuration, connection and account documents

The database access control (ACL) must be set as follows:

| User types     | Role                                         |
| -------------- | -------------------------------------------- |
| Users          | EditAcc                                      |
| Administrators | EditConfigSrv, EditConn                      |
| Servers        | EditConfigSrv, EditConn, EditAcc, ReadAllAcc |

The HCL Domino database *Squirrel.nsf* contains configuration and status information. There are three types of documents:

* One Configuration Document per Domino server is used to define the Squirrel add-in running on a server (ACL Role *EditConfigSrv*).
* One Host Connection Document must be defined for each Internet mail server referenced in the mail account documents (ACL Role *EditConn*).
* One Mail Account Subscription Document must be defined for each mail account to be processed (ACL Role *EditAcc*) .

### Step 4: Post-installation

* If you plan to process all folders from the IMAP host, check the [Developer Tips](/developer-tips) on how to move the messages in the users mail box to the corresponding folders after processing.
* If any RunJava task is running on the server,  it is necessary to restart RunJava to load the newly installed Java containers.

### Step 5: Start the Application

Now you are ready to [start the Application](/quick-start/start-stop-squirrel).


# Start / Stop Squirrel

How to start or stop Squirrel

## Start Application

In HCL Domino 14.0/14.5/14.5.1, the Domino JVM writes out the following warning message for any Java tasks (RunJava, HTTP, etc). As written out in the release notes of HCL Domino, this warning may be ignored.

```
WARNING: A terminally deprecated method in java.lang.System has been called
WARNING: System::setSecurityManager has been called by lotus.notes.AgentSecurityManager (file:/D:/D-Programme/HCL/Domino/ndext/Notes.jar)
WARNING: Please consider reporting this to the maintainers of lotus.notes.AgentSecurityManager
WARNING: System::setSecurityManager will be removed in a future release
```

### Option 1: Program Document

The easiest and recommended way is to add a program document in the HCL Domino directory.

![Program document to start Squirrel at server startup](/files/-MRFDCjBVRcqY19V6YpX)

To reduce memory usage in the Domino JVM, the “SingleRun” parameter can be specified to stop Squirrel after all subscription documents have been processed. The “Repeat interval of” parameter in the program document schedules Squirrel to run at the specified intervals.

<figure><img src="/files/zVn6TJYxJF84hj1Kuwj8" alt=""><figcaption><p>Program document to start Squirrel at specific intervals</p></figcaption></figure>

### Option 2: Console Command

Enter the command *Load RunJava JAddin Squirrel* in the HCL Domino console:

```
> Load RunJava JAddin Squirrel
03.04.2026 17:07:50   JVM: Java Virtual Machine initialized.
03.04.2026 17:07:50   RunJava: Started JAddin Java task.
03.04.2026 17:07:50   Squirrel: The Internet Mail Collector for HCL Domino - Version 2026.04.02
03.04.2026 17:07:50   Squirrel: Copyright iota systems GmbH / andy.brunner@k43.ch - All Rights Reserved
03.04.2026 17:07:50   Squirrel: Java VM heap size configuration: Maxiumum: 256 MiB / Used: 22 MiB / Free: 233 MiB
03.04.2026 17:07:50   Squirrel: License key valid for 10 mail account subscriptions until 2026-12-31
03.04.2026 17:07:50   Squirrel: IMAPS message forwarded to Joe Smith/ACME from jsmith@hotmail.com (Size 689 KB)
03.04.2026 17:07:50   Squirrel: POP3S message forwarded to Lee Chu/ACME from lchx815@gmx.net (Size 286 KB)
```

### Option 3: Notes.ini

You may change the line starting with *ServerTasks=* to include the task to be started, e.g.

```
ServerTasks=Replica,Router,Update,RunJava JAddin Squirrel,AMgr,...
```

{% hint style="danger" %}
Please note that the Java class names *JAddin* and *Squirrel* are both case-sensitive and must be coded with exact case during startup.
{% endhint %}

### Startup Parameters

These parameters may be used during startup of Squirrel:

```
> Load RunJava JAddin Squirrel Help
22.05.2026 14:59:57   Squirrel: SingleRun          Perform POP3/IMAP processing only once and terminate
22.05.2026 14:59:57   Squirrel: Help/?             Show this help screen
```

### Runtime Commands

These parameters may be used while Squirrel is running:

```
> Tell Squirrel Help
22.05.2026 15:02:12   Squirrel: ShowMemory  Show JVM heap space usage
22.05.2026 15:02:12   Squirrel: Help/?      Display this help screen
22.05.2026 15:02:12   Squirrel: Quit/Q      Terminate this add-in
22.05.2026 15:02:12   Squirrel: Help!       Display help screen from JAddin framework
```

## Stop Application

To terminate Squirrel, enter *Tell Squirrel Quit* on the HCL Domino console.

```
> Tell Squirrel Quit
03.04.2026 17:08:49   Squirrel: Termination in progress
03.04.2026 17:08:52   Squirrel: Terminated
03.04.2026 17:08:52   RunJava: Finalized JAddin Java task.
03.04.2026 17:08:53   RunJava shutdown.
```


# Contact / Problem Reporting

How to contact the authors

Please do not hesitate to contact the authors <bodo.wetzel@iota.ch> or <andy.brunner@k43.ch> if you encounter any issues or if you have a suggestion.

In case of an errors, please include the following information for our problem determination:

* Recreate the problem while the Squirrel [debugging](/debugging-tips) is active.
* Save the HCL Domino log (console or log.nsf) during the error.
* Enter the console command *Show Stat Squirrel* and save the output (console or log.nsf).
* Save the file *Squirrel-Debug-YYYY-MM.DD.log* in the Domino data directory.
* For OAuth 2.0 connections, save the file *Squirrel-Debug-OAuth-{n}.log* in the program directory.
* Send this information to us with a short description of the error and the steps needed to reproduce.

Thank you.


# Download

All available Squirrel downloads

<details>

<summary>Planned for next version</summary>

* Experimental Support for HCL Traveler running on the same server as Squirrel (Tested with HCL Domino 14.5.1/HCL Traveler 14.5.1). Please send feedback to <andy.brunner@k43.ch>.
* Remove old Squirrel debug files except the newest 5 files
* Added startup parameter "Help"
* Added command "Tell Squirrel ShowMemory" to display JVM heap space usage
* Minor code and documentation changes
* Changed file in this release: Squirrel.jar

</details>

### Version 2026.03.26

{% file src="/files/NNyY4d1HDpxPu9458x9r" %}

* Major internal rewrite to improve mail rendering of POP3/IMAP messages
* Some minor memory optimizations
* Fix character set conversion bug in 2026.03.14
* Preserve message id in item $MessageID
* Minor code and documentation changes
* Changed files in this release: 1-Squirrel-Jakarta-Mail.jar and Squirrel.jar

### Version 2026.03.14

{% hint style="info" %}
Download of this version has been disabled due to a bug found in the code. Please use version 2026.03.03 or wait for the next version arriving soon.
{% endhint %}

* Changed Java Mail API to new Jakarta Mail/Eclipse Angus
* Changed connect/read/write timeout from 10 to 30 seconds
* Treat "java.net.SocketTimeoutException: Read timed out" as temporary error
* Minor code and documentation changes
* Changed files in this release: 1-Squirrel-Jakarta-Mail.jar and Squirrel.jar

### Version 2026.03.03

{% file src="/files/hpY9a32WKJYe7kLhIBW9" %}

* Support for emails which are represented in Java as javax.mail.util.SharedByteArrayInputStream
* Minor code and documentation changes
* Changed file in this release: Squirrel.jar

### Version 2025.12.09

{% file src="/files/0Rork3z7I9qLXJGKFtCT" %}

* Include JAddin version 2025.11.27
* Change version number scheme from n.n.n to yyyy.mm.dd
* Treat "Login failed: Read timed out" as temporary error
* Minor code and documentation changes
* Changed file in this release: Squirrel.jar

### Version 1.6.13 (2025-09-26)

{% file src="/files/ofivXQillx2s5Vyb6PD2" %}

* Backend: Enforce timeout in connection test to avoid possible connection hangups
* Minor code and documentation changes
* Changed file in this release: Squirrel.jar

### Version 1.6.12 (2025-09-23)

{% file src="/files/SGGZl8X1WhiiyKn670I6" %}

* Backend: Remove BATV header from recipient address (see <https://en.wikipedia.org/wiki/Bounce_Address_Tag_Validation>)
* Backend: Sort mail properties in Jakarta debug log
* Minor code and documentation changes
* Changed file in this release: Squirrel.jar

### Version 1.6.11 (2025-08-11)

{% file src="/files/PwuGxvlyY931RRbav2Ka" %}

* Backend: Create new Jakarta Mail Session for each Connection (instead of using previous Connection)
* Backend: More cleanup code added to avoid rare connection hangups in Jakarta Mail API
* Backend: Force the use of a 10 second timeout for session connect/read
* Minor code and documentation changes
* Changed file in this release: Squirrel.jar

### Version 1.6.10 (2025-06-21)

{% file src="/files/2UZcOgJdPsh0y1rznH8W" %}

* Include updated [JAddin 2.2.1](https://jaddin.k43.ch/) framework
* Backend: Treat connection error "\* BYE Connection closed" as temporary error
* Minor code and documentation changes
* Changed file in this release: Squirrel.jar

### Version 1.6.9 (2025-06-20)

{% file src="/files/sJLPgVKGO9vfQvKPqgKq" %}

* Backend: Support "SingleRun" parameter to terminate Squirrel after processing all subscription documents (see [Start / Stop Squirrel](/quick-start/start-stop-squirrel))
* Changed file in this release: Squirrel.jar

### Version 1.6.8 (2025-05-05)

{% file src="/files/7UTOWJIvgfKZM9b0tzhv" %}

* Backend: Add message to connection errors with link to website with debugging information.
* Backend: Add connect timeout (10 secs) to avoid infinite hang-up
* Backend: Added more recovery for temporary mail server errors
* Backend: Improved performance and resilience during shutdown
* Changed file in this release: Squirrel.jar

### Version 1.6.7 (2024-09-03)

{% file src="/files/onrOuxPNhPfOQmb4YRZp" %}

* Include [JAddin 2.1.4](https://jaddin.k43.ch) framework to support HCL Domino 14.5 and higher (JVM with Java 17)

### Version 1.6.6 (2024-05-28)

{% file src="/files/A9WpomfgBMfFf5iBJbFt" %}

* Debug mode: Show HCL Domino JVM classpath during startup
* Treat server error "\[SYS/TEMP] Internal error occurred" as temporary error
* Some minor code changes and optimizations

### Version 1.6.5 (2023-12-22)

{% file src="/files/tMD7l2KYRJMPFo29fwiU" %}

* Prevent logging of user credentials in Jakarta Mail debug log (Squirrel-Debug-yyyy-mm-dd.log)
* Check connection to POP3/IMAP host before processing messages

### Version 1.6.4 (2023-12-16)

{% file src="/files/U08dDwSnLk8hKOd4tE20" %}

* Check if correct Java Mail API classes are installed
* Minor code changes during connection cleanup
* Add special handling for invalid formatted messages causing errors, e.g. "Unable to load BODYSTRUCTURE"
* Include [JAddin](https://jaddin.k43.ch) 2.1.3 framework

### Version 1.6.3 (2023-08-05)

{% file src="/files/06TCMhY60QGst8k58S8C" %}

* Support for emails which are represented in Java as java.io.ByteArraylnputStream
* Prevent log message "duplex close of socket"

### Version 1.6.2 (2023-06-21)

{% file src="/files/lLcN5U6g8sy2JykDaLas" %}

* Use envelope \<Return-Path> or \<X-Envelope-From> if no valid sender found in mail body
* Fix for duplicate cc: and bcc: recipients
* Connection error "BAD User is authenticated but not connected" is now handled as temporary to avoid disabling the subscription document (occurs often in Microsoft 365)
* Enhance server licensing
* Minor text changes in Jakarta Mail debug log
* Include [SOFA 1.0.1](https://sofa.k43.ch/) (minor fixes)
* Documentation: Product website moved to <https://squirrel.k43.ch>

### Version 1.6.1 (2022-10-24)

{% file src="/files/60GMo97793nxkwAVP5tG" %}

* Minor adjustments in debug logging
* Treat errors during OAuth 2.0 authentication as temporary errors to prevent disabling of subscription documents
* Field validation error for OAuth 2.0 fixed
* Encrypt client value/secret field for OAuth 2.0

### Version 1.6.0 (2022-10-19)

{% file src="/files/5MyxN9brRFUjT8zTZzoE" %}

* Add additional fields in account document for OAuth 2.0
* OAuth 2.0 support for IMAP and POP3
* Include the freeware [SOFA](https://sofa.k43.ch) 1.0.0 framework for OAuth 2.0 authentication
* Added file SOFA-Logging.properties to the distribution packet to parameterize the OAuth 2.0 debug logging (see [Debugging Tips](/debugging-tips))

### Version 1.5.2 2022-08-15

{% file src="/files/A8Uv8cWnIBpT4RW3RNuG" %}

* Handle X.509 Internet encrypted messages
* Add more detailed debugging information
* Do not automatically convert to UTF-8 charset
* Ignore MIME encoding errors for invalid Internet messages
* Ignore unknown/unsupported MIME encoding specifications

### Version 1.5.1 2021-04-13

{% file src="/files/-MY8jPv6wIEwXptrB7YB" %}
Download
{% endfile %}

{% hint style="warning" %}
If you are upgrading from Squirrel version 1.5.0, you need to delete the two files

* 1-Squirrel-Activation.jar
* 1-Squirrel-Jakarta.jar

from the directory 'Domino/ndext'
{% endhint %}

* Add free version with a limit of three active mail subscriptions
* Support coexistence with HCL Traveler

### Version 1.5.0 2021-03-23

{% file src="/files/-MWUXFUqLQI3BmQ0y7qH" %}
Download
{% endfile %}

* Option in configuration document to send all user account errors to the administrator
* Include [JAddin](https://jaddin.abdata.ch) 2.1.2 framework (minor fixes)
* Include [Eclipse Jakarta Mail](https://eclipse-ee4j.github.io/mail/) and Eclipse Jakarta Activation to replace older JavaMail API
* Write logging from Jakarta Mail API during active debugging to file 'Squirrel-Debug-YYYY-MM-DD.log' (see [Debugging Tips](/debugging-tips))
* Squirrel documentation updated and moved to GitBook
* **Experimental support for** [**OAuth 2.0 authentication**](/oauth-2.0-support) **(Client XOAUTH2). This feature is currently in a beta phase. Please send any feedback to** [**andy.brunner@abdata.ch**](mailto:andy.brunner@abdata.ch)

### **Version 1.4.2 2021-01-01**

{% file src="/files/-MREStVFci4bKImX5MAX" %}
Download
{% endfile %}

* Show warning message at startup if defined maximum Java heap size is less than 256MB
* Add Domino statistic 'Squirrel.Messages.LastConnectTime' with time of last successful POP3/IMAP server connection
* Remove some original MIME headers to avoid duplicate MIME headers (RFC 5322)
* Added several code enhancements in processing MIME message content
* Minor documentation changes

### **Version 1.4.1 2020-10-18**

{% file src="/files/-MREWi-2Mdo50oqAuxHT" %}
Download
{% endfile %}

* Preserve original recipient fields (To, Cc, Bcc)
* Disable adding Domino domain name (e.g. @ACME) in recipient address
* Handle empty To/From address
* Support RFC 2047 encoded header fields
* Minor documentation changes

### **Version 1.4.0 2020-09-17**

{% file src="/files/-MREWl7qaEqA32oYMV\_m" %}
Download
{% endfile %}

* Support recipient lookup for large Domino directories
* Support manual entry of recipients (e.g. for group names or mail-in databases)
* Minor documentation changes

### **Version 1.3.4 2020-08-02**

{% file src="/files/-MREWl7pmmJ-XdHV6Q9O" %}
Download
{% endfile %}

* Support Domino mail rule "Don't accept message"

### **Version 1.3.3 2020-07-28**

{% file src="/files/-MREWl7o13GVJzo-PvPs" %}
Download
{% endfile %}

* Fix regression error in 1.3.1/1.3.2 "Folder not open"

### **Version 1.3.2 2020-07-13**

{% file src="/files/-MREWl7nKhOeVMzSqfoJ" %}
Download
{% endfile %}

* Retry server login after receiving "EOF on socket"

### **Version 1.3.1 2020-07-11**

{% file src="/files/-MREWl7mRXxBP0-q4i-k" %}
Download
{% endfile %}

* Retry server login after receiving "Temporary authentication failure"

### **Version 1.3.0 2019-12-02**

{% file src="/files/-MREWl7lNFjQ3dxUm4zi" %}
Download
{% endfile %}

* Add option to select all folders to be processed (IMAP servers only)
* Add option to process all messages (read and unread) once for complete mailbox migration (see Administrator Tips)
* Change product references to reflect re-branding (IBM to HCL)
* Code performance enhancements during Domino MIME message body creation
* Show 1 KB message size (instead of 0 KB) on console log for message size < 1 KB
* Add Notes item $SquirrelFolder with the folder name of the original message (see Developer Tips)
* Add check for required ACL roles to be active in configuration database (see Installation)
* Shortened the length of log and debug message to the console

### **Version 1.2.3 2019-08-12**

* Correct bug when receiving Internet messages with text/html and base64 encoding

### **Version 1.2.2 2019-07-01**

* Add 125ms delay between message fetching to avoid race conditions on the Internet mail server
* Set the Notes message item PostedDate to the original time of the message (see Developer Tips)
* Rename the Notes item $SquirrelSentDate to $SquirrelPostedDate and set it to the time of the Squirrel message processing
* Support encoded subject lines, which do not completely follow the RFC 2047 standard.

### **Version 1.2.1 2019-03-18**

* Back-End: Correct display of encoded Internet sender addresses (e.g. "=?utf-8?..")
* Back-End: Minor code cleanup

### **Version 1.2.0 2019-03-09**

* Remove unused action menu
* Mark Sqirrel.ntf as template in database properties&#x20;
* Include JAddin 2.1.1 framework
* Use Domino router database mail1.box if mail.box is not present
* Correct possible loop while encountering startup errors
* Correct NullPointerException for missing sent date in MIME mail
* Support MIME messages which are mapped in Java API as com.sun.mail.util.BASE64DecoderStream
* Add Domino console log message every hour if no mail account document is active
* Force UTF-8 for all MIME character set conversions

### **Version 1.1.0 2019-02-22**

* Configuration document: "Send sys msg to" is now a Domino directory names lookup field
* Internet mail account subscription: New field for comments
* Internet mail account views: Action button for set active/inactive
* Internet mail account views: Include columns for used connections and comments
* Squirrel.ntf template: Set default ACLs
* Minor code changes and cleanups

### **Version 1.0.0 2019-02-10**

* First official release

### **Version 0.8.0 2019-02-05**

* Third internal beta version - Feature completed
* Add all notification email for the administrator

### **Version 0.6.0 2019-01-19**

* Second internal beta version
* Add support for POP3S and POP3

### **Version 0.5.0 2019-01-07**

* First internal beta version

### **Version 0.1.0 2019-01-02**

* First alpha version (Proof of concept)


# Licenses

How to license the product

## License Types

### Freeware Edition

If no valid license key is found in the configuration, the add-in runs as a free version with a limit of three active mail account subscription.

### Standard Edition

The standard Squirrel license is valid for one year and covers one HCL Domino server for the purchased number of mail account subscriptions. Within the time of a valid license, all version upgrades are free. The license key will be sent to you after the purchase and must be copied to the configuration document.

### Community Edition

You may contact us for a Community Edition license. This free license is restricted to private or non-commercial use only.

## Pricing

<table><thead><tr><th width="163">Subscription</th><th>Price (1.00 CHF ≅ 1.25 USD ≅ 1.10 EUR)</th></tr></thead><tbody><tr><td>None</td><td>Freeware version (3 active mail subscriptions)</td></tr><tr><td>10</td><td>CHF 7.60 per Subscription/Year</td></tr><tr><td>25</td><td>CHF 7.20 per Subscription/Year</td></tr><tr><td>50</td><td>CHF 6.80 per Subscription/Year</td></tr><tr><td>100</td><td>CHF 6.40 per Subscription/Year</td></tr><tr><td>250</td><td>CHF 6.00 per Subscription/Year</td></tr><tr><td>500</td><td>CHF 5.60 per Subscription/Year</td></tr><tr><td>>500</td><td>For larger deployments please contact <a href="mailto:bodo.wetzel@iota.ch">bodo.wetzel@iota.ch</a></td></tr></tbody></table>

### Order via email

To purchase a Squirrel license please contact <bodo.wetzel@iota.ch> and include the following information:

* Exact hierarchical HCL Domino server name (e.g. *CN=Server/O=ACME*)
* Required number of mail account subscriptions
* Your billing contact and address


# OAuth 2.0 Support

Some information about the support for OAuth 2.0 in Squirrel

Several Internet mail providers are rolling out support for OAuth2 user authentication. Starting with version 1.6.0, Squirrel supports user authentication with OAuth 2.0. Before using OAuth 2.0, you will need to setup the OAuth 2.0 authentication with your Internet hosting provider to obtain an OAuth 2.0 access token.

As Squirrel for Domino runs in the background on the HCL Domino server, it can only use OAuth 2.0 authentication methods which do not need any user interactions. These OAuth 2.0 access methods are called machine-to-machine (M2M) communications.

### Microsoft 365 Outlook Mail / Google Gmail

For information on how to setup MS 365 and Gmail, see the page [Mail Server Settings](/mail-server-settings).

### Other Email Providers

Basically, any email provider should be able to be used as long as it supports the OAuth 2.0 Client Credential flow.

{% hint style="info" %}
If you know any other OAuth 2.0 provider which support a machine-to-machine authentication (without prompting the user) please let us know. We will be glad to implement them in Squirrel for Domino.
{% endhint %}


# Mail Server Settings

Various information about configuring Squirrel for well known mail providers

### Gmail / Google Mail: POP3 / IMAP

1. Enable POP3 and/or IMAP in your Gmail settings:
\
   See <https://support.google.com/a/answer/105694?hl=en>
2. Create an Google *App Password* for Squirrel:\
   See <https://support.google.com/accounts/answer/185833>
3. Use the *App Password* instead of the normal Gmail user password in your Squirrel subscription document

| Protocol | Mail Server    | Port |
| -------- | -------------- | ---- |
| POP3S    | pop.gmail.com  | 995  |
| IMAPS    | imap.gmail.com | 993  |

### Microsoft 365 Outlook Mail: POP3 / IMAP with OAuth 2.0

The support for OAuth 2.0 *Client Credentials* grant type with IMAP and POP3 access on the Azure platform is available as of July 1st, 2022. Please follow the steps carefully in setting up the application id and the client credentials:

* [Microsoft identity platform and the OAuth 2.0 client credentials flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow)
* [Authenticate an IMAP, POP or SMTP connection using OAuth](https://docs.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth)

#### Important Notes

* Add the *Application* *Type* API permission *Office 365 Exchange Online* > **I***MAP.AccessAsApp* or *POP.AccessAsApp* depending on the protocol to be used.
* These API permissions do require admin consent.
* Do not forget to issue the required PowerShell commands (see below).
* Use the hostname *outlook.office365.com* in the connection document.

<figure><img src="/files/z7umQ8Rtaaa0pAdTYoK5" alt=""><figcaption><p>Microsoft Entra</p></figcaption></figure>

#### PowerShell Command Example

{% code overflow="wrap" lineNumbers="true" %}

```powershell
Install-Module -Name ExchangeOnlineManagement
Import-module ExchangeOnlineManagement
Connect-ExchangeOnline -Organization {Azure-Tenant-ID}
New-ServicePrincipal -AppId {Enterprise-Application-ID} -ServiceId {Enterprise-Object-ID}
Add-MailboxPermission -Identity "{Email-Address}" -User {Enterprise-Application-ID} -AccessRights FullAccess
```

{% endcode %}

{% hint style="warning" %}
The client secret generated by Microsoft 365 will expire after the specified period and will have to be renewed.
{% endhint %}

#### Field Assignments

<table><thead><tr><th width="294">Subscription Document</th><th>Example value</th></tr></thead><tbody><tr><td>Authorization Token Endpoint</td><td>https://login.microsoftonline.com/11111111-2222-3333-4444-55555555555/oauth2/v2.0/token</td></tr><tr><td>Authorization Scope</td><td>https://outlook.office365.com/.default</td></tr><tr><td>Client/Application ID</td><td>66666666-7777-888-9999-11111111111</td></tr><tr><td>Client Value/Secret</td><td>puG8Qak340dhfnskfrieuhnfe3dr.456saa.O</td></tr></tbody></table>


# Debugging Tips

Some hints and tips to help your problem determination

## Common Error Messages

| Error Message                                                                                                                                         | Possible Reason                                                                                                                                                            |
| ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p><em>RunJava: Can't find class JAddIn</em> </p><p><em>lotus/notes/addins/jaddin/Squirrel in the classpath. Class names are case-sensitive</em>.</p> | The RunJava task was unable to load the class. Make sure that it is written with exact upper and lower case characters and it can be found by the RunJava class loader     |
| *JAddin: Unable to load Java class Squirrel*                                                                                                          | The JAddin framework was unable to load Squirrel.jar. Make sure that it is written with exact upper and lower case characters.                                             |
| *RunJava: Can't find stopAddin method for class Squirrel.*                                                                                            | The Squirrel class must be loaded thru the JAddin framework and not directly from RunJava. Use the command *Load RunJava JAddin Squirrel* to start Squirrel.               |
| *RunJava JVM: java.lang.NoClassDefFoundError: Squirrel (wrong name: sqirrel)*                                                                         | The user class name in the command and the internal name do not match. Most likely you have not typed the name with correct upper and lower case characters.               |
| *Out of memory*                                                                                                                                       | All Java add-ins execute in a single Java Virtual Machine (JVM) in RunJava. The Domino Notes.Ini parameter *JavaMaxHeapSize=xxxxMB* may be used to increase the heap space |
| *User is authenticated but not connected*                                                                                                             | This is a know temporary error in Microsoft Exchange.                                                                                                                      |

## Connection Problems

### Basic Connection Test

If Squirrel is unable to connect to the Internet mail server, check if a direct connection from the HCL Domino server to the specified Internet mail server is possible. This can be done with Telnet or NetCat (nc).

```
> nc -v imap.gmail.com 993
Connection to imap.gmail.com port 993 [tcp/imaps] succeeded!
```

{% hint style="info" %}
Starting with version 1.6.5, Squirrel performs a basic connection test to the configured mail server before processing messages. Any error found during this test is written to the HCL Domino console (and in log.nsf). The correponding subscription document is not disabled as connection errors are often temporary.
{% endhint %}

### TLS Connection Test

To check which TLS certificate the Internet mail server is using, you may issue the *openssl* command:

```
> openssl s_client -connect imap.gmail.com:993
CONNECTED(00000006)
depth=2 OU = GlobalSign Root CA - R2, O = GlobalSign, CN = GlobalSign
verify return:1
depth=1 C = US, O = Google Trust Services, CN = Google Internet Authority G3
verify return:1
depth=0 C = US, ST = California, L = Mountain View, O = Google LLC, CN = imap.gmail.com
verify return:1
---
Certificate chain
 0 s:/C=US/ST=California/L=Mountain View/O=Google LLC/CN=imap.gmail.com
   i:/C=US/O=Google Trust Services/CN=Google Internet Authority G3
 1 s:/C=US/O=Google Trust Services/CN=Google Internet Authority G3
   i:/OU=GlobalSign Root CA - R2/O=GlobalSign/CN=GlobalSign
...
```

Secure connections are supported by using the TLS variant of the IMAP and POP3 protocol (IMAPS and POP3S). The JVM of the HCL Domino server is using the keystore file *domino/jvm/lib/security/cacert* to validate the TLS certificates. If the root certificate is not found in the keystore file, you need to add the root (and intermediate) certificates from the connecting mail server into this *cacert* file.

## Add Certificate to Keystore File

To import the missing root and/or intermediate certificates:

### HCL Domino 11+:

1. Open command prompt window with administrator priviledge on the HCL Domino server
2. *cd domino\jvm\bin* to change to the directory
3. Add the certificate to the 'cacert' file, e.g.\
   *keytool -import -trustcacerts -keystore jvm/lib/security/cacerts -storepass changeit -alias "New Root CA" -import -file NewRootCA.pem*&#x20;
4. Restart the HCL Domino server

### HCL Domino 9 and 10:

1. Open command prompt window with administrator privilege on the HCL Domino server
2. *cd domino\jvm\bin* to change to the directory
3. Enter *ikeyman* to start the IBM Key Management utility
4. Click Key Database File and then *Open*. Select the file *cacerts* in the directory *domino\jvm\lib\security*. You need to have *All files* selected to see it. The password to open the file is *changeit*.
5. Change to *Signer Certificates*
6. Click *Add* and select the root (or intermediate) certificate you need to import. Click *OK* and enter any descriptive text for this certificate.
7. Restart the HCL Domino server.

{% hint style="success" %}
The following command convers a certificate to PEM format:\
*openssl pkcs12 -in filename.pfx -out cert.pem -nodes*
{% endhint %}

## Debugging <a href="#debugging" id="debugging"></a>

For a detailed problem determination, you may use the built-in debugging features.

### Enable/Disable Debug

| Domino Console Command                | Description                                      |
| ------------------------------------- | ------------------------------------------------ |
| *Load RunJava JAddin Squirrel Debug!* | Start Squirrel add-in in debug mode              |
| *Tell Squirrel Debug!*                | Start the debug mode while the add-in is running |
| *Tell Squirrel NoDebug!*              | Stop the debug mode while the add-in is running  |

#### Squirrel Debug

When activated, the HCL Domino console shows debugging information from the Squirrel add-in and the underlying JAddin framework. The output includes the name of the Java method with the source line number issuing the message. This debuggin information is written to the HCL Domino Console.

{% hint style="warning" %}
While active debugging adds a significant amount of data to the console log and to the log.nsf database, it can be helpful in finding the root of a problem.&#x20;
{% endhint %}

```
> Load RunJava JAddin Squirrel Debug!
05.02.2019 07:44:15   JVM: Java Virtual Machine initialized.
05.02.2019 07:44:15   RunJava: Started JAddin Java task.
05.02.2019 07:44:15   JAddin: Debug logging enabled - Enter 'Tell Squirrel NoDebug!' to disable
05.02.2019 07:44:15   DEBUG: JAddin.runNotes(144)                JAddin framework version 2.1.0
05.02.2019 07:44:15   DEBUG: JAddin.runNotes(145)                Squirrel will be called with parameters null
05.02.2019 07:44:15   DEBUG: JAddin.runNotes(148)                Creating the Domino message queue
05.02.2019 07:44:15   DEBUG: JAddin.runNotes(166)                Opening the Domino message queue
05.02.2019 07:44:15   DEBUG: JAddin.runNotes(184)                Loading the user Java class Squirrel
05.02.2019 07:44:15   DEBUG: JAddin.runNotes(196)                User Java class Squirrel successfully loaded
05.02.2019 07:44:15   DEBUG: JAddin.runNotes(208)                => Squirrel.addinInitialize()
05.02.2019 07:44:15   DEBUG: Squirrel.addinInitialize(80)        -- addinInitialize()
05.02.2019 07:44:15   DEBUG: Squirrel.addinInitialize(94)        Creating the Domino session
05.02.2019 07:44:15   DEBUG: JAddin.runNotes(210)                <= Squirrel.addinInitialize()
05.02.2019 07:44:15   DEBUG: JAddin.runNotes(221)                => Squirrel.start()
05.02.2019 07:44:15   DEBUG: JAddin.runNotes(223)                <= Squirrel.start()
05.02.2019 07:44:15   DEBUG: Squirrel.runNotes(117)              -- runNotes()
05.02.2019 07:44:15   DEBUG: Squirrel.runNotes(130)              => Squirrel.addinStart()
05.02.2019 07:44:15   Squirrel: The Internet Mail Collector for HCL Domino - Version 1.0.0 2019-02-01
05.02.2019 07:44:15   Squirrel: Copyright iota systems GmbH 2019 / ABdata, Andy Brunner 2019. All Rights Reserved.
05.02.2019 07:44:15   DEBUG: Squirrel.addinStart(182)            Configuration database Squirrel.nsf successfully opened
05.02.2019 07:44:15   DEBUG: Squirrel.readConfiguration(384)     Reading configuration document
05.02.2019 07:44:15   DEBUG: Squirrel.checkServerLicense(461)    License key: null
05.02.2019 07:44:15   Squirrel: No valid license key found - Running in test mode (1 active subscription, 3 messages)
05.02.2019 07:44:15   DEBUG: Squirrel.readConfiguration(417)     Configuration document successfully processed
05.02.2019 07:44:15   DEBUG: Squirrel.newVersionCheck(311)       -- newVersionCheck()
05.02.2019 07:44:16   DEBUG: Squirrel.newVersionCheck(321)       Available version on website: 1.0.0
05.02.2019 07:44:16   DEBUG: Squirrel.readSubscriptions(431)     Read all subscription documents
05.02.2019 07:44:16   DEBUG: Squirrel.dbGetAllDocuments(633)     View Squirrel.nsf/($Accounts) entries: 1
05.02.2019 07:44:16   DEBUG: Squirrel.addinStart(196)            Subscription documents: 1
05.02.2019 07:44:16   DEBUG: Squirrel.addinStart(239)            Subscription jsmith@acme.com: POP3S pop.acme.com:995 => John Smith/ACME
05.02.2019 07:44:16   DEBUG: Squirrel.addinStart(242)            Subscription jsmith@acme.com: Keep mail on server: 1
05.02.2019 07:44:16   DEBUG: Squirrel.readInbox(607)             Subscription jsmith@acme.com: Last POP3 Time stamp: 2019-02-03T11:56:46Z
05.02.2019 07:44:17   DEBUG: Squirrel.readInbox(623)             Subscription jsmith@acme.com: Login successful
05.02.2019 07:44:17   DEBUG: Squirrel.readInbox(675)             Subscription jsmith@acme.com: Messages in inbox: 4
05.02.2019 07:44:17   DEBUG: Squirrel.readInbox(706)             Subscription jsmith@acme.com: Unread POP3 messages: 4
05.02.2019 07:44:17   DEBUG: Squirrel.addinStart(256)            Subscription jsmith@acme.com: Processing next message
05.02.2019 07:44:17   DEBUG: Squirrel.addinStart(270)            Subscription jsmith@acme.com: Message object: com.sun.mail.pop3.POP3Message@c0923a6c
...
```

#### Eclipse Jakarta Mail Debug

In addition to the debugging information sent to the HCL Domino console, the Eclipse Jakarta Mail is instructed to create debugging output. Due to the amount of information, the data is written to a separate file with the name *Squirrel-Debug-YYYY-MM-YY.log* in the HCL Domino data directory.

```
Squirrel for Domino - Version 1.5.0 - Jakarta mail debug log started 2021-04-10 14:03:49

Mail property mail.imaps.port: 993
Mail property mail.store.protocol: imaps
Mail property mail.imaps.partialfetch: false
Mail property mail.mime.decodetext.strict: false
Mail property mail.imaps.peek: true
Mail property mail.mime.charset: UTF-8

DEBUG: setDebug: Jakarta Mail version 1.6.6-SNAPSHOT
DEBUG: getProvider() returning javax.mail.Provider[STORE,imaps,com.sun.mail.imap.IMAPSSLStore,Oracle]
DEBUG IMAPS: mail.imap.partialfetch: false
DEBUG IMAPS: mail.imap.ignorebodystructuresize: false
DEBUG IMAPS: mail.imap.statuscachetimeout: 1000
DEBUG IMAPS: mail.imap.appendbuffersize: -1
DEBUG IMAPS: mail.imap.minidletime: 10
DEBUG IMAPS: peek
DEBUG IMAPS: closeFoldersOnStoreFailure
DEBUG IMAPS: trying to connect to host "imap.servicehoster.ch", port 993, isSSL true
* OK [CAPABILITY IMAP4rev1 SASL-IR LOGIN-REFERRALS ID ENABLE IDLE LITERAL+ AUTH=PLAIN AUTH=LOGIN] Dovecot ready.
DEBUG IMAPS: AUTH: PLAIN
DEBUG IMAPS: AUTH: LOGIN
DEBUG IMAPS: protocolConnect login, host=imap.servicehoster.ch, user=xxx@abdata.ch, password=<non-null>
DEBUG IMAPS: AUTHENTICATE PLAIN command trace suppressed
DEBUG IMAPS: AUTHENTICATE PLAIN command result: A0 OK [CAPABILITY IMAP4rev1 SASL-IR LOGIN-REFERRALS ID ENABLE IDLE SORT SORT=DISPLAY THREAD=REFERENCES THREAD=REFS THREAD=ORDEREDSUBJECT MULTIAPPEND URL-PARTIAL CATENATE UNSELECT CHILDREN NAMESPACE UIDPLUS LIST-EXTENDED I18NLEVEL=1 CONDSTORE QRESYNC ESEARCH ESORT SEARCHRES WITHIN CONTEXT=SEARCH LIST-STATUS BINARY MOVE SNIPPET=FUZZY PREVIEW=FUZZY LITERAL+ NOTIFY SPECIAL-USE QUOTA] Logged in
DEBUG IMAPS: connection available -- size: 1
A1 SELECT INBOX
* FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
* OK [PERMANENTFLAGS (\Answered \Flagged \Deleted \Seen \Draft \*)] Flags permitted.
* 0 EXISTS
* 0 RECENT
* OK [UIDVALIDITY 1614859984] UIDs valid
* OK [UIDNEXT 2] Predicted next UID
A1 OK [READ-WRITE] Select completed (0.001 + 0.000 + 0.001 secs).
A2 SEARCH UNSEEN ALL
* SEARCH
A2 OK Search completed (0.001 + 0.000 secs).
A3 CLOSE
```

{% hint style="warning" %}
Jakarta mail debug files are automatically deleted except the most recent 5 files.
{% endhint %}

### Debugging OAuth 2.0

Starting with version 1.6.0, Squirrel is using the freeware [SOFA](https://sofa.k43.ch) for OAuth 2.0 authentication. This framework writes his own detailed logging, which can be configured in the file *SOFA-Logging.properties* located in the HCP Domino program directory. The resulting log files *Squirrel-Debug-OAuth-{n}.log* are created in the HCL Domino program directory.

{% hint style="info" %}
Use the sample file in the distribution package to configure and activate the SOFA debug log.
{% endhint %}

```
2022-08-20T11:44:23.071 FEIN        SOFA (Simple OAuth 2.0 Framework for Authentication) Version 0.8.1 (2022-03-03) initialization called  
2022-08-20T11:44:23.102 FEIN        SOFA running on OS platform <Windows 8 6.2/amd64>  
2022-08-20T11:44:23.102 FEIN        SOFA running on JVM version <International Business Machines Corporation openj9-0.29.0>  
2022-08-20T11:44:23.258 FEIN        SOFA AES-256 cipher initialized  
2022-08-20T11:44:23.258 FEIN        SOFA authenticate() called  
2022-08-20T11:44:23.305 FEIN        OAuth grant type <client_credentials>  
2022-08-20T11:44:23.305 FEIN        OAuth scope <https://graph.microsoft.com/.default>  
2022-08-20T11:44:23.305 FEIN        OAuth client ID <aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa>  
2022-08-20T11:44:23.305 FEIN        SOFA executeHttpTransaction() called  
2022-08-20T11:44:23.305 FEIN        HTTP connecting to URL <https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx/oauth2/v2.0/token>  
2022-08-20T11:44:23.524 FEIN        HTTP method <POST>  
2022-08-20T11:44:23.540 FEIN        HTTP header sent <Date: Sat, 20 Aug 2022 09:44:23 GMT>  
2022-08-20T11:44:23.540 FEIN        HTTP header sent <User-Agent: SOFA/0.8.1 (Simple OAuth 2.0 Framework for Authentication)>  
2022-08-20T11:44:23.540 FEIN        HTTP header sent <Accept: application/json>  
2022-08-20T11:44:23.540 FEIN        HTTP header sent <Content-Type: application/x-www-form-urlencoded>  
2022-08-20T11:44:23.540 FEIN        HTTP header sent <Content-Length: 178>  
2022-08-20T11:44:23.852 FEIN        HTTP data size sent <178 bytes>  
2022-08-20T11:44:23.852 FEIN        HTTP connection established with cipher <TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384>  
2022-08-20T11:44:23.915 FEIN        HTTP header received <HTTP/1.1 400 Bad Request>  
2022-08-20T11:44:23.915 FEIN        HTTP header received <x-ms-ests-server: 2.1.13481.11 - NEULR1 ProdSlices>  
2022-08-20T11:44:23.915 FEIN        HTTP header received <X-Content-Type-Options: nosniff>  
2022-08-20T11:44:23.915 FEIN        HTTP header received <Pragma: no-cache>  
2022-08-20T11:44:23.915 FEIN        HTTP header received <P3P: CP="DSP CUR OTPi IND OTRi ONL FIN">  
2022-08-20T11:44:23.915 FEIN        HTTP header received <Date: Sat, 20 Aug 2022 09:44:23 GMT>  
2022-08-20T11:44:23.915 FEIN        HTTP header received <Strict-Transport-Security: max-age=31536000; includeSubDomains>  
2022-08-20T11:44:23.915 FEIN        HTTP header received <Cache-Control: no-store, no-cache>  
2022-08-20T11:44:23.915 FEIN        HTTP header received <Set-Cookie: stsservicecookie=estsfd; path=/; secure; samesite=none; httponly>  
2022-08-20T11:44:23.915 FEIN        HTTP header received <Expires: -1>  
2022-08-20T11:44:23.915 FEIN        HTTP header received <Content-Length: 554>  
2022-08-20T11:44:23.915 FEIN        HTTP header received <X-XSS-Protection: 0>  
2022-08-20T11:44:23.915 FEIN        HTTP header received <x-ms-request-id: 572b6d8d-f54d-42a2-a12d-66c527c50b00>  
2022-08-20T11:44:23.915 FEIN        HTTP header received <Content-Type: application/json; charset=utf-8>  
2022-08-20T11:44:23.915 FEIN        HTTP response code <400>  
2022-08-20T11:44:23.915 FEIN        HTTP data size received <554 bytes>  
2022-08-20T11:44:23.915 FEIN        SOFA executeHttpTransaction() elapsed time <610 ms>  
```


# Administrator Tips

Tips for the HCL Domino administrator to install and maintain Squirrel on the server

## HCL Domino Statistics

During execution, the Squirrel add-in maintains statistics and status information. They can be displayed with the *Show Stat Squirrel* command:

```
> Show Stat Squirrel
  Squirrel.Config.IntervalMin = 3
  Squirrel.Config.Subscriptions.Limit = 5
  Squirrel.Config.Subscriptions.Used = 2
  Squirrel.Domino.Platform = 6.2 (Windows 8)
  Squirrel.Domino.Version = Release 11.0.1FP2|October 20, 2020 (Windows/64)
  Squirrel.JAddin.StartedTime = 2021-01-25T15:39:48Z
  Squirrel.JAddin.VersionDate = 2021-01-25
  Squirrel.JAddin.VersionNumber = 2.1.2
  Squirrel.JVM.GCCount = 0
  Squirrel.JVM.HeapLimitKB = 262'144
  Squirrel.JVM.HeapUsedKB = 19'482
  Squirrel.JVM.Version = 1.8.0_265 (Eclipse OpenJ9)
  Squirrel.Messages.IMAP.Processed = 32
  Squirrel.Messages.LastConnectTime = 2021-01-25T15:39:49Z
  Squirrel.Messages.POP3.Processed = 2
  Squirrel.VersionDate = 2021-01-01
  Squirrel.VersionNumber = 1.4.3
```

## IMAP versus POP3

Whenever possible, use the TLS-secured version of the IMAP protocol (IMAPS). IMAP is generally more modern and more reliable to access your emails on the remote mail servers. TLS encryption (used in IMAPS and POP3S) prevent that the user password and the message content is sent in clear text.

The POP3 protocol does not include a specification for message read or unread indicators. To overcome this limitation, any POP3 client must access all messages at every interval and select the messages to be processed based on a last message processed indicator. This is done in Squirrel with a hidden time stamp field added to the mail account subscription document.

## Full Mailbox Migration

To support customers migrating entire POP3 or IMAP mailboxes to Domino, the option *Mail Migration* may be used to read all messages once during the next interval. This option is then reset at the next message fetch interval.

## Error Handling

If Squirrel encounters an uncorrectable error while processing a mail account subscription, it will disable this document to prevent future error messages. The last error message is saved in the mail account subscription document and an HCL Notes email message is sent to the user to inform of the error. After the error has been corrected (e.g. wrong password), the mail account subscription document must be manually enabled again to resume the processing for this subscription. Other errors (e.g. connection timeouts) are reported on the console and the operation is retried at the next interval.


# Developer Tips

Tips for the HCL Notes developer implementing Squirrel for the end users

## Implementation

The Squirrel server add-in is written entirely in Java which includes the open source Java framework [JAddin](https://jaddin.abdata.ch) (for HCL Domino server add-in) and the freeware [SOFA](https://sofa.k43.ch) (for OAuth 2.0 authentication). The HCL Notes front-end is a pure HCL Notes application distributed in a single NTF database template..

## Email Document

The original body of the Internet mail will be saved in the Notes document as a Notes MIME type item. The original MIME headers are preserved and saved in the Notes document.

## Additional Notes Items

Before forwarding messages to HCL Domino, the following items are added to preserve the original fields from the Internet email message. These items may be used to process messages in the users in-box with agents or to create new views or additional columns.

| Notes Item          | Item Type | Description                                                                   |
| ------------------- | --------- | ----------------------------------------------------------------------------- |
| $SquirrelVersion    | String    | Squirrel program version (e.g. 1.0.0)                                         |
| $SquirrelRecipient  | String    | Original IMAP/POP3 recipient name (e.g. <jsmith@gmail.com>)                   |
| $SquirrelPostedDate | DateTime  | Date and time of the Squirrel message processing                              |
| $SquirrelHostname   | String    | Internet host name of the mail server (e.g. imap.gmail.com)                   |
| $SquirrelProtocol   | String    | Protocol used to retrieve the email messages (IMAPS, IMAP, POP3S or POP3)     |
| $SquirrelFolder     | String    | Folder name of the original email messages (e.g. *INBOX*, *Office\ToDo*, etc) |

## Notes Delivered Time / Posted Time

Squirrel will set the Notes item *PostedDate* to the original date and time of the message. The Notes item *DeliveredDate* is set by the Domino router to the date and time when the message was actually processed by the router task (stored in the users mail database). If you want the user to see the original date and time of the message, you must change the formula of the Inbox folder column to show the *PostedDate* instead of the *DeliveredDate*.

## Folder Processing

The Notes item *$SquirrelFolder* contains the folder name of the original message. POP3 messages always return the name of the inbox where IMAP messages will contain the full name of the folder. This item may be used in a Notes pre-delivery agent (*Before new mail arrives*) to add the message to the corresponding folder, e.g.

```
Sub Initialize
    Dim Session As New NotesSession
    Dim Document As NotesDocument
    Dim FolderName As String

    Set Document = Session.DocumentContext
    FolderName = Document.getItemValue("$SquirrelFolder")(0)

    ' Move the message to the original folder
    If ((FolderName <> "") And (UCase(FolderName) <> "INBOX")) Then
        Call Document.PutInFolder(FolderName)
        Call Document.RemoveFromFolder("($Inbox)")
    End If
End Sub
```