Engine Installation
===================

1. Additional Help
------------------

Please also read the entry "Engine Installation" in PapihelpV12.nsf.
This help database is included in the distribution package.


2. Requirements
---------------

- HCL Domino Server version 10 or later
  Older Domino versions are not approved or tested.
  Domino 14 is currently not yet approved.

- HCL Notes Client

- Server operating systems:
  Windows Server 2019 or later, Windows 10 or Windows 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 access to "Set config" through the remote console

- Visual Studio Code is only required for convenient editing of
  Engine scripts. It is not required to run the Engine.


3. Location of the System Databases
-----------------------------------

All Engine system databases should be placed in a subdirectory,
for example "Engine" or "System", below the Domino data directory
on the respective Domino server.

These databases are:

- APICTRL.NSF
- APILOG.NSF
- APIJOB.NSF
- SRVJOBS.NSF

The help database PapiHelpV12.nsf does not have to be placed in this
directory.


4. Access Control and Signing
-----------------------------

The ACLs of APICTRL.NSF, APIJOB.NSF, and SRVJOBS.NSF should generally
allow access only for administrators and developers.

APILOG.NSF may also contain confidential information and should therefore
also be restricted to administrators and developers.

Regular users should not have 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
to avoid execution prompts in the Notes client.


5. License File engine.aei
--------------------------

The engine.aei file included in the distribution package must be copied
to 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. First Installation
~~~~~~~~~~~~~~~~~~~~~~

For a first installation, the following steps are usually required:

- Stop the Domino server
- Create a backup of the Domino server
- Copy the system databases into a separate subdirectory, for example
  "Engine", below 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:

    load engine

  This starts the initialization run.


6b. Initialization Run
~~~~~~~~~~~~~~~~~~~~~~

After the files have been copied to the appropriate directories, the
Engine can be started from the Domino server console with 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 no APIKeyFilename entry exists in the Notes.INI
yet, an initialization run is performed.

During the initialization run, the Engine automatically sets a number of
entries. The Notes.INI is extended with several entries according to the
standard API Engine configuration.

If the databases use their default names:

- APICTRL.NSF
- APILOG.NSF
- APIJOB.NSF
- SRVJOBS.NSF

the Engine will find them during the first startup even if they are located
in a different subdirectory below the Domino data directory than "System".
The detected databases are then entered into the Notes.INI with their
current locations.

The API Engine also automatically adds itself to the "ServerTasks" entry in
the Notes.INI during this initialization run only, so that it is started
automatically when the server starts.

If this is not desired, the Engine entry should be removed from the
"ServerTasks" entry in the Notes.INI again.

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 on every startup, but a successful connection is required at
regular intervals to extend the license runtime.

No personal data and no data from any databases on the server are
transmitted to the activation server.


Important Notes.INI Entries
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The most important Notes.INI entries on the server are listed below:

    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 defines the license file for the Engine.
    After a completed initialization run, the license file may also be
    renamed, for example to testserver.aei. In that case, this Notes.INI
    entry must be adjusted accordingly.

APIControlDB:
    This entry defines the control database for the Engine.

APILogFileName:
    This entry defines the log database for the Engine.

APIJobDB:
    This entry defines the APIJOB database for the Engine.
    APIJOB is inactive by default. See the help for details.

APIToolBox:
    This entry defines the toolbox database for the Engine.
    The toolbox is the parameter database for a collection of
    out-of-the-box applications.

APIFunctionDLLs:
    This entry defines the @Functions libraries to be loaded by the
    Engine.

    In the example, the standard @Functions and the MySQL @Functions are
    loaded. Both are included in the evaluation distribution package.

    Attention:
    During the initialization run, only the standard @Functions DLL
    naefun1 is added automatically.

    Additional @Functions DLLs must be added manually, for example
    naemysql for the MySQL @Functions.


Example: Engine Start in the Server Log
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When the Engine starts successfully, 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
    06.07.2026 16:19:00   APICreateTemplateAPIControlDB=0
    06.07.2026 16:19:00   APIControlDB=Engine\APICTRL.NSF
    06.07.2026 16:19:00   SysDB Template Created :APILOG.NTF
    06.07.2026 16:19:01   APILogFileName=Engine\APILOG.NSF
    06.07.2026 16:19:01   APILogTmpFileName=Engine\TMPALOG.NSF
    06.07.2026 16:19:01   SysDB Template Created :APIJOB.NTF
    06.07.2026 16:19:01   APIJobDB=Engine\APIJOB.NSF
    06.07.2026 16:19:02   APIToolBox=Engine\SRVJOBS.NSF
    ...


Example: Engine Start in APILOG
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As soon as the Engine knows its own log file, usually APILOG.NSF, further
operations are logged there.

The first entries are written by the scheduler.
They can be found in the Scheduler\by Time view in APILOG.

Example for an installation with only the 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

Example for an installation with an additional MySQL @Functions DLL:

    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 contains the entries for the Engine scripts that
are currently running or have been executed.

This view also contains the initialization script that assigns individual
Replica IDs to the system databases, so that not all Engine installations
use the same Replica IDs.

The actual entry for this executed Engine script contains, for example,
the logged processing steps of the initialization run.


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 Net-Solutions through the usual process.

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


Design Updates for System Databases
-----------------------------------

If a database design update is available for the system databases, it is
recommended here as well to create a backup of the Engine system databases
first.

Then stop the Engine on the server:

    tell engine exit

After that, update the design using a Notes client via

    Application -> Update Design

with the new template.

Finally, restart the Engine from the server console:

    load engine


Notes
-----

The system databases are searched 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. For APIControlDB, the contained documents are copied
into the NTF as well.

Example:

    APICTRL.NSF -> APICTRL.NTF

Existing Notes.INI entries are not changed.

If APIKeyFileName is deleted from the Notes.INI of an already installed
Engine, only the AEI is searched again.

If one of the system database entries is deleted from the Notes.INI, the
corresponding database is searched again and entered. A new NTF for this
system database is also created.

If a system database entry in the Notes.INI points to a non-existing file,
the corresponding system database is recreated from the NTF created during
installation.
