Engine Installation
Beschreibung
1. Lesen Sie die README im Distributions-File!
2. Voraussetzungen
– HCL Domino Server ab Version 10 (ältere Domino-Versionen sind nicht freigegeben bzw. nicht getestet., Domino 14 ist derzeit noch nicht freigegeben)
– HCL Notes Client
– Betriebssysteme Server: Windows Server 2019 oder höher, Windows 10 oder 11
– Betriebssysteme Client: Windows / macOS
– Ausreichende Rechte zum Kopieren von Dateien ins Domino-Data-Verzeichnis
– Ausreichende Rechte zum Kopieren von Dateien ins Domino-Program-Verzeichnis
– Administratorrechte zur Änderung der Notes.INI auf dem Domino-Server (oder "Set config" über die Remote Konsole)
– Visual Studio Code wird nur für die komfortable Bearbeitung von Engine-Scripts benötigt, nicht für den Betrieb der Engine.
3. Alle System-Datenbanken der Engine sollten in einem Unterverzeichnis (z.B. "Engine" oder "System") des Domino-Data-Verzeichnis auf dem jeweiligen Domino-Servers liegen.
Dies sind: APICTRL.NSF, APILOG.NSF, APIJOB.NSF und SRVJOBS.NSF, die Hilfe PApiHelpV12.NSF muss nicht in dieses Verzeichnis.
4. Die ACLs von APICTRL.NSF, APIJOB.NSF und SRVJOBS.NSF sollten grundsätzlich nur Administratoren und Entwicklern Zugriff ermöglichen!
Auch die APILOG.NSF kann durchaus vertrauliche Informationen enthalten und sollte deshalb auch auf Administratoren und Entwickler beschränkt sein.
Normale Anwender sollten keinen direkten Zugriff auf APICTRL.NSF, APIJOB.NSF, APILOG.NSF und SRVJOBS.NSF erhalten!
Optional: Die Datenbanken sollten mit einer vertrauenswürdigen Server-/Administrator-ID signiert werden um die Ausführungs-Prompts des Notes-Clients zu vermeiden.
5. Die engine.aei, die im Distributions-File mitgeliefert wurde wird ins Domino-Data-Verzeichnis auf dem jeweiligen Domino-Server kopiert.
Dies ist die Lizenz-Datei für die Engine. Nach dem ersten Start ist diese Lizenz-Datei fest an den Domino-Server gebunden und kann nicht mehr auf einen anderen Domino-Server übertragen werden.
6. Installation:
6a. Für eine Erstinstallation:
– Domino-Server beenden
– Backup des Domino-Servers
– Die System-Datenbanken in ein eigenes Unterverzeichnis (z.B. Engine) im Domino-Data-Verzeichnis kopieren
– Die Lizenz-Datei engine.aei in das Domino-Data-Verzeichnis kopieren
– Die Binaries aus dem Distributions-Paket in das Domino-Program-Verzeichnis kopieren.
– Domino-Server starten
– Über load engine auf der Domino-Server-Konsole die API Engine starten (es folgt der Initialisierungslauf)
6b. Der Initialisierungslauf
Nach dem Kopieren der Files in die entsprechenden Verzeichnisse kann die Engine über die Domino-Server-Konsole über folgendes Kommando gestartet werden:
load engine
Die Engine erwartet bei einer Neuinstallation, dass die Lizenz-Datei engine.aei heißt und im Domino-Data-Verzeichnis zu finden ist.
Wenn dies so ist, und bisher kein Eintrag APIKeyFilename in der Notes.INI vorhanden ist, ist dies eine Initialisierungslauf!
Die Engine setzt beim Initialisierungslauf selbständig eine ganze Reihe von Einträgen.
Die Notes.INI wird entsprechend einer API Engine Standardkonfiguration um zahlreiche Einträge ergänzt.
Wenn die Datenbanken ihre Standardbezeichnung haben (APICTRL.NSF, APILOG.NSF, APIJOB.NSF & SRVJOBS.NSF) findet die Engine diese beim ersten Startup auch dann, wenn sie in einem anderen Subverzeichnis
unterhalb des Domino-Data-Verzeichnis liegen als "System".
Diese werden dann auch gleich korrekt mit ihrem aktuellem Ort in die Notes.INI eingetragen.
Außerdem trägt sich die API Engine automatisch (aber nur bei diesem Initialisierungslauf) selbst in den Eintrag "ServerTasks" in der Notes.INI ein, damit diese beim Start des Servers automatisch mit gestartet wird.
Wenn das nicht gewünscht ist, sollte dieser Eintrag in der Notes.INI wieder um den Engine-Eintrag bereinigt werden.
Bei API Lizenzen die an eine Internet-Aktivierung gebunden sind wird der Aktivierungsserver bei diesem ersten Startup automatisch kontaktiert und die Lizenz an den Server gebunden.
Bei API Lizenzen die an eine Internet-Aktivierung gebunden sind wird außerdem bei jedem Serverstart der Aktivierungsserver kontaktiert. Es muss nicht jedes Mal ein Kontakt hergestellt werden können, aber in regelmäßigen
Abständen ist eine erfolgreiche Verbindung erforderlich um die Lizenz in der Laufzeit zu verlängern.
Es werden dabei keine persönlichen Daten oder Daten aus irgendwelchen Datenbanken auf dem Server an unseren Aktivierungsserver übermittelt.
Nachfolgend die wichtigsten Notes.INI Einträge auf dem 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:
Dieser Eintrag legt die Lizenz-Datei für die Engine fest.
Nach einem abgeschlossenem Initialisierungslauf kann die Lizenz-Datei auch umbenannt werden (z.B. testserver.aei), dann muss dieser Eintrag in der Notes.INI natürlich angepasst werden.
APIControlDB:
Dieser Eintrag legt die Steuerdatenbank für die Engine fest.
APILogFileName:
Dieser Eintrag legt die Log-Datenbank für die Engine fest.
APIJobDB:
Dieser Eintrag legt die APIJOB-Datenbank für die Engine fest, die APIJOB ist per default inaktiv, siehe Hilfe!
APIToolBox:
Dieser Eintrag legt die Toolbox-Datenbank für die Engine fest. Die Toolbox ist die Parameter-Datenbank für eine Sammlung von out-of-the-box-Anwendungen.
APIFunctionDLLs:
Über diesen Eintrag werden die von der Engine zu ladenden @Functions-Bibliotheken festgelegt. Hier die Standard-@Functions und die MySQL-@Functions (auch im Evaluations-Distributions-Paket enthalten).
Achtung: Es wird beim Initialisierungslauf nur die Standard-@Functions-DLL (naefun1) automatisch eingetragen!
Weitere @Functions-DLLs müssen manuell hinzugefügt werden, so wie hier die naemysql für die MySQL-@Functions.
Bei einem erfolgreichem Engine Start werden folgende Log-Einträge geschrieben:
Die ersten Vorgänge werden im Domino-Server-Log protokolliert:
> 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))
…
Sobald die Engine ihr eigenes Log-File kennt (in der Regel APILOG.NSF) werden die weiteren Vorgänge in diesem protokolliert:
Die ersten Einträge dort schreibt der Scheduler (Ansicht : Scheduler\by Time im APILOG):
Hier für eine Installation mit nur der Standard-@Functions-DLL:
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
Wenn auch die MySQL-@Functions-DLL geladen wird sieht es z.B. so aus:
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
In der Ansicht Protocol\by Time finden sich dann die Einträge zu den jeweilig laufenden Engine-Scripts.
Hier das Initialisierungs-Script um den System-Datenbanken eigene Replik-IDs zu geben, damit nicht alle Engine-Installationen die selben Replik-IDs haben.
Der eigentliche Eintrag für dieses gelaufene Engine-Script sieht dann z.B. wie folgt aus:
6c. Engine-Updates
Die Engine spielt niemals automatisch Updates ein!
Wenn der Aktivierungs- und Update-Server über die Verfügbarkeit eines Updates informiert (siehe Scheduler Eintrag im APILOG), dann ist ein neues Update verfügbar und kann über den üblichen Weg bei SL NetSolutions bezogen werden.
Ein Update wird wieder als Distributions-Paket zur Verfügung gestellt.
Für ein Update sind (in der Regel) folgende Schritte notwendig:
– Domino-Server beenden
– Backup des Domino-Servers
– Die Binaries aus dem Distributions-Paket in das Domino-Program-Verzeichnis kopieren.
– Domino-Server starten
Wenn ein Datenbank-Design-Update für die System-Datenbanken vorliegt:
Auch hier wird empfohlen zuerst ein Backup der Engine-System-Datenbanken durchzuführen.
Danach die Engine auf dem Server beenden (Server-Konsole: tell engine exit)
Anschließend das Design über einen Notes-Client über "Anwendung->Gestaltung aktualisieren" durch die neue Schablone aktualisieren.
Abschließend die Engine über die Server-Konsole load engine wieder starten.
7. Notes ist als Code-Editor eher nicht so geeignet, daher gibt es eine Extension für Visual Studio Code.
Download von Visual Studio Code (VS Code) bei Microsoft: https://code.visualstudio.com/download?_exp_download=fb315fc982
Die Extension für Engine-Script in VS Code über File -> Preferences -> Extensions dann bei "EXTENSION" auf die drei Punkte klicken und "Install from VSIX" wählen und eine der VSIX-Dateien aus dem Distributions-Paket installieren.
Danach noch den Engine-Folder für VS Code als Trusted Folder hinzufügen.
Windows:
%LOCALAPPDATA%\SLNet\API-Engine\VSCode
macOS:
~/Library/Application Support/HCL Notes Data/SLNet/API-Engine/VSCode
(Unter macOS ist der Library-Ordner im Finder oft ausgeblendet. Im Auswahldialog kann der Pfad über Cmd + Shift + G direkt eingegeben werden.)
Oben in einem Engine-Script Dokument in der APICTRL-Datenbank befinden sich im Bearbeitenmodus die beiden Buttons "Open in VS Code" und "Get back from VS Code".
Über den ersten Button "Open in VS Code" kann das Engine-Script aus diesem Dokument in VS Code übertragen, dort bearbeitet, gespeichert und über den zweiten Button Get back from VS Code wieder in das Dokument zurückgeholt werden.
Das Dokument wird dann automatisch wieder geschlossen.
Vor der Verwendung von "Get back from VS Code" muss die Datei in VS Code unbedingt gespeichert werden!
Der Button "Get back from VS Code" ersetzt den Inhalt des Engine-Script-Feldes vollständig durch den Inhalt der Datei im VS-Code-Arbeitsordner.
Nicht gespeicherte Änderungen in anderen Feldern des geöffneten Notes-Dokuments können dabei verloren gehen.
Sollte etwas schief gehen findet sich das Engine-Script weiterhin in dem jeweiligen Ordner, es wird nicht automatisch wieder gelöscht.
Bei der nächsten Betätigung des Buttons "Open in VS Code" im selben Engine-Script Dokument (auf dem selben Client) wird eine möglicherweise noch vorhandene ältere Version dieses Engine-Scripts in diesem Ordner jedoch überschrieben.
Screenshot mit den relevanten Buttons aus dem Engine-Script-Dokument:
Hinweise:
Die System-Datenbanken werden anhand ihrer Default Namen gesucht und in die Notes.INI eingetragen.
Von den Datenbanken werden NTF’s mit den aktuellen Default Namen im Domino-Data-Verzeichnis angelegt (bei APIControlDB werden die enthaltenen Dokumente in das NTF mit kopiert). Beispiel APICTRL.NSF -> APICTRL.NTF.
Bereits vorhandene Notes.INI Einträge werden nicht geändert.
Wird bei einer bereits installierten Engine APIKeyFileName aus der Notes.INI gelöscht, wird nur die AEI neu gesucht.
Wird einer der System-Datenbank-Einträge aus der Notes.INI gelöscht wird die betreffende DB neu gesucht und eingetragen (es wird auch ein neues NTF dieser System-Datenbank angelegt).
Verweist ein System-Datenbank-Eintrag der Notes.INI auf ein nicht existierendes File, wird, von dem bei der Installation angelegten NTF, die betreffende System-Datenbank neu erzeugt.