Engine Installation
Description
1. Read the README in the distribution file!
2. Requirements
– HCL Domino Server version 10 or higher. Older Domino versions are not approved or have not been tested. Domino 14 is currently not yet approved.
– HCL Notes Client
– Server operating systems: Windows Server 2019 or higher, Windows 10 or 11
– Client operating systems: Windows / macOS
– Sufficient permissions to copy files into the Domino data directory
– Sufficient permissions to copy files into the Domino program directory
– Administrator rights to modify the Notes.INI on the Domino server, or "Set config" via the remote console
– Visual Studio Code is only required for convenient editing of Engine scripts, not for running the Engine.
3. All Engine system databases should be located in a subdirectory, for example "Engine" or "System", of the Domino data directory on the respective Domino server.
These are: APICTRL.NSF, APILOG.NSF, APIJOB.NSF and SRVJOBS.NSF. The help database PApiHelpV12.NSF does not have to be placed in this directory.
4. The ACLs of APICTRL.NSF, APIJOB.NSF and SRVJOBS.NSF should generally allow access only to administrators and developers.
APILOG.NSF may also contain confidential information and should therefore also be restricted to administrators and developers.
Regular users should not be granted direct access to APICTRL.NSF, APIJOB.NSF, APILOG.NSF or SRVJOBS.NSF.
Optional: The databases should be signed with a trusted server or administrator ID in order to avoid execution prompts in the Notes client.
5. The engine.aei file included in the distribution file is copied into the Domino data directory on the respective Domino server.
This is the license file for the Engine. After the first start, this license file is permanently bound to the Domino server and can no longer be transferred to another Domino server.
6. Installation:
6a. For an initial installation:
– Stop the Domino server
– Create a backup of the Domino server
– Copy the system databases into a dedicated subdirectory, for example Engine, in the Domino data directory
– Copy the license file engine.aei into the Domino data directory
– Copy the binaries from the distribution package into the Domino program directory
– Start the Domino server
– Start the API Engine from the Domino server console using load engine. The initialization run will then be performed.
6b. The initialization run
After copying the files into the appropriate directories, the Engine can be started from the Domino server console using the following command:
load engine
For a new installation, the Engine expects the license file to be named engine.aei and to be located in the Domino data directory.
If this is the case, and if there is not yet an APIKeyFilename entry in the Notes.INI, this is an initialization run.
During the initialization run, the Engine automatically creates a whole series of entries.
The Notes.INI is extended with numerous entries according to a standard API Engine configuration.
If the databases have their standard names, APICTRL.NSF, APILOG.NSF, APIJOB.NSF and SRVJOBS.NSF, the Engine will also find them during the first startup if they are located in a subdirectory below the Domino data directory other than "System".
They are then immediately entered into the Notes.INI with their current location.
In addition, the API Engine automatically adds itself, but only during this initialization run, to the "ServerTasks" entry in the Notes.INI so that it is started automatically when the server starts.
If this is not desired, the Engine entry should be removed again from this Notes.INI entry.
For API licenses that require internet activation, the activation server is contacted automatically during this first startup and the license is bound to the server.
For API licenses that require internet activation, the activation server is also contacted each time the server starts. A connection does not have to be established every time, but a successful connection is required at regular intervals in order to extend the license during runtime.
No personal data and no data from any databases on the server is transmitted to our activation server.
Below are the most important Notes.INI entries on the server.
APIKeyFilename=C:\domino\data\engine.AEI
APIControlDB=SYSTEM\APICTRL.NSF
APILogFileName=SYSTEM\APILOG.NSF
APIJobDB=SYSTEM\APIJOB.NSF
APIToolBox=SYSTEM\SRVJOBS.NSF
APIFunctionDLLs=naefun1,naemysql
…
APIKeyFilename:
This entry specifies the license file for the Engine.
After a completed initialization run, the license file can also be renamed, for example to testserver.aei. In that case, this entry in the Notes.INI must of course be adjusted accordingly.
APIControlDB:
This entry specifies the control database for the Engine.
APILogFileName:
This entry specifies the log database for the Engine.
APIJobDB:
This entry specifies the APIJOB database for the Engine. APIJOB is inactive by default; see the help documentation.
APIToolBox:
This entry specifies the Toolbox database for the Engine. The Toolbox is the parameter database for a collection of out-of-the-box applications.
APIFunctionDLLs:
This entry specifies the @Functions libraries to be loaded by the Engine.
Note: During the initialization run, only the standard @Functions DLL, naefun1, is entered automatically.
Additional @Functions DLLs must be added manually, as shown here with naemysql for the MySQL @Functions.
When the Engine starts successfully, the following log entries are written:
The first operations are logged in the Domino server log:
> load engine
06.07.2026 16:19:00 APIKeyFilename=C:\Program Files\HCL\Domino\Data\ENGINE.AEI (This is the Engine ID FILE (including Path))
06.07.2026 16:19:00 APICreateTemplateAPIControlDB=0 (Create Engine Control DB Template on Boot if necessary (=1) or not (=0))
06.07.2026 16:19:00 APIControlDB=Engine\APICTRL.NSF (Place here the Path of the Engine Control DB File (including relative Notes Path))
06.07.2026 16:19:00 SysDB Template Created :APILOG.NTF
06.07.2026 16:19:01 APILogFileName=Engine\APILOG.NSF (Place here the Path of the Engine APILog DB File (including relative Notes Path))
06.07.2026 16:19:01 APILogTmpFileName=Engine\TMPALOG.NSF (Place here the Path of the Engine TMP APILog DB File (including relative Notes Path))
06.07.2026 16:19:01 SysDB Template Created :APIJOB.NTF
06.07.2026 16:19:01 APIJobDB=Engine\APIJOB.NSF (Place here the Path of the Engine APIJob DB File (including relative Notes Path))
06.07.2026 16:19:02 APIToolBox=Engine\SRVJOBS.NSF (Place here the Path of the Engine ToolBox DB File (including relative Notes Path))
…
As soon as the Engine knows its own log file, usually APILOG.NSF, the subsequent operations are logged there.
The first entries in this log are written by the Scheduler, in the `Scheduler\by Time` view in APILOG.
For an installation with only the standard @Functions DLL, this looks as follows:
06.07.2026 16:32:20 Engine V12.11 B562 [c]2026 SL-NetSolutions, started with (Engine Scheduler)
06.07.2026 16:32:20 Engine-Modus is ENGINE
06.07.2026 16:32:21 Engine License activated
06.07.2026 16:32:21 Engine License valid until 07.10.2026 13:29:03
06.07.2026 16:32:21 Engine Standard @Functions V12.11 B562 LOADED
06.07.2026 16:32:21 Engine Hook Manager not available in this Version
If the MySQL @Functions DLL is also loaded, it may look as follows:
06.07.2026 16:46:40 Engine V12.11 B562 [c]2026 SL-NetSolutions, started with (Engine Scheduler)
06.07.2026 16:46:40 Engine-Modus is ENGINE
06.07.2026 16:46:40 Engine License activated
06.07.2026 16:46:40 Engine License valid until 07.10.2026 13:43:22
06.07.2026 16:46:40 Engine Standard @Functions V12.11 B562 LOADED
06.07.2026 16:46:40 Register new Datatype:MYSH (0)
06.07.2026 16:46:40 Register new Datatype:MYRH (1)
06.07.2026 16:46:40 Register new Datatype:MYPH (2)
06.07.2026 16:46:40 Engine MySQL @Functions V12.11.06 LOADED
06.07.2026 16:46:40 Engine Hook Manager not available in this Version
The `Protocol\by Time` view then contains the entries for the respective running Engine scripts.
Shown here is the initialization script used to assign individual replica IDs to the system databases, so that not all Engine installations have the same replica IDs.
The actual entry for this executed Engine script then looks, for example, as follows:
6c. Engine updates
The Engine never installs updates automatically.
If the activation and update server reports that an update is available, see the Scheduler entry in APILOG, a new update is available and can be obtained from SL NetSolutions through the usual channel.
An update is again provided as a distribution package.
For an update, the following steps are usually required:
– Stop the Domino server
– Create a backup of the Domino server
– Copy the binaries from the distribution package into the Domino program directory
– Start the Domino server
If a database design update is available for the system databases:
Here, too, it is recommended to create a backup of the Engine system databases first.
Then stop the Engine on the server, using the server console command:
tell engine exit
After that, update the design from a Notes client via "Application -> Refresh Design" using the new template.
Finally, start the Engine again from the server console using:
load engine
—
7. Notes is not particularly well suited as a code editor, so an extension for Visual Studio Code is available.
Download Visual Studio Code (VS Code) from Microsoft: https://code.visualstudio.com/download?_exp_download=fb315fc982
Install the Engine Script extension in VS Code via File -> Preferences -> Extensions. Then click the three dots next to "EXTENSION", select "Install from VSIX", and install one of the VSIX files from the distribution package.
Afterwards, add the Engine folder for VS Code as a trusted folder.
Windows:
%LOCALAPPDATA%\SLNet\API-Engine\VSCode
macOS:
~/Library/Application Support/HCL Notes Data/SLNet/API-Engine/VSCode
(On macOS, the Library folder is often hidden in Finder. In the selection dialog, the path can be entered directly using Cmd + Shift + G.)
At the top of an Engine Script document in the APICTRL database, the two buttons "Open in VS Code" and "Get back from VS Code" are available in edit mode.
Using the first button, "Open in VS Code", the Engine Script from this document can be transferred to VS Code, edited there, saved, and then retrieved back into the document using the second button, "Get back from VS Code".
The document is then closed again automatically.
Before using "Get back from VS Code", the file must always be saved in VS Code.
The "Get back from VS Code" button completely replaces the contents of the Engine Script field with the contents of the file in the VS Code working folder.
Unsaved changes in other fields of the open Notes document may be lost in the process.
If something goes wrong, the Engine Script will still be available in the respective folder; it is not deleted automatically.
However, the next time the "Open in VS Code" button is used in the same Engine Script document, on the same client, any older version of this Engine Script that may still exist in this folder will be overwritten.
Screenshot showing the relevant buttons from the Engine Script document:
Notes:
The system databases are searched for by their default names and entered into the Notes.INI.
NTFs with the current default names are created from the databases in the Domino data directory. In the case of APIControlDB, the contained documents are also copied into the NTF. Example: APICTRL.NSF -> APICTRL.NTF.
Existing Notes.INI entries are not changed.
If APIKeyFileName is deleted from the Notes.INI for an already installed Engine, only the AEI is searched for again.
If one of the system database entries is deleted from the Notes.INI, the corresponding database is searched for again and entered. A new NTF of this system database is also created.
If a system database entry in the Notes.INI points to a file that does not exist, the corresponding system database is recreated from the NTF that was created during installation.
Note : This text was machine-translated and may contain inaccuracies.