Toggle menu

API Server and Worker Configuration

The API Server and it's workers are supplied with a default configuration. This can be managed from iCM.

Viewing the Current Configuration

You can view server and worker configuration from the API Server Console. The values you see are a combination of the server and worker default configuration (found in the worker.conf of each worker and the APIServer.conf file) plus the configuration sent to the API Server from iCM.

API Server configuration is visible in the "Settings" tab of the console menu.

API Server Settings Menu

To see the configuration of a worker, select it form the "Overview" page of the console, then press the cog icon next to the worker name. Here's the full configuration for a typical Ajax Library worker.

AJAX Library Configuration

Environment Configuration

When you send configuration to the API Server from iCM, as well as the custom configuration for workers and the server described below, iCM also sends environment configuration.

If you make changes to autoconfig or the iCM Settings section (in particular website user profile mappings) you'll need to resend the API Server configuration from iCM so these changes are propagated throughout your platform.

Custom Configuration

API Server configuration files are held in the iCM custom folder, accessed using the File Manager.

API Server Config File


The "workers" array in the configuration file sets up each worker that should be started, the number of instances of it, and the threads per instance of threaded workers. You can override the value of any property in a worker's default configuration by including it in this file. For example:

    "name": "ajaxlibrary",
    "instances": 4,
    "displayName": "new name"

Which would make the Ajax Library appear like this in the console:

Override Display Name

Not a very practical example! More useful is the "version" property. By default the API Server will use the latest installed version of a worker. You can roll back to an earlier version by explicitly setting the version to start, for example "version": "1.7.1" (assuming that version actually exists).

Additional options for each worker, like the providers used by the Authentication worker or the service the Postcode worker should connect to, are also set here. The documentation for each worker looks at these options in more detail.

API Server

In exceptional circumstances you may need to modify the configuration of the API Server itself. This is done in exactly the same way as workers, adding the properties you'd like to set at the top level of the file, like this:

    "workerKillTimeout": 6000,
    "enableHttp": true,
    "workers": [{...}, {...}]

The full configuration structure is described below.

Time intervals can either be expressed as integers representing milliseconds, or as objects with time and value properties. For example, one minute could be set as

"cacheSweepInterval": 60000


"cacheSweepInterval": { "T":"time", "V":"00:01:00" }

Where "V" represents hours, minutes and seconds. This is useful for longer intervals, like the lifetime of files in the tmp directory, which defaults to { "T":"time", "V":"120:00:00" } rather than the slightly harder to read 432000000.

${APISERVER} provides the path to the root installation directory of the API Server.

tmpPathStringThe path to the tmp directory. Default: "${APISERVER}/tmp"
staticFileServerRootsArrayAn array of objects, each defining a root directory. The children of these directories will be served by node as static files. See the staticFormCacheRootPath in the API Server console for an example
excludedUpdateItemsArrayFiles or directories that have these names will be excluded from the update process. Default: ["log", "tmp", "workers"]
workerKillTimeoutInteger (milliseconds)How long the APIServer will wait to SIGKILL a process if it is still alive after the specified amount of time. Default: 5000
enableHttpBooleanEnable or disable HTTP access. Default: true
serverPortInterger (port number)The HTTP port number. Default: 5706
enableHttpsBooleanEnable or disable HTTPS access. Default: false (note this does not affect proxied access to the console through iCM or access to publicly available workers like the AJAX library which are rooted through the site frameworks. Both of these will use HTTPS if enabled in those environments)
httpsPortInteger (port number)Only relevant if HTTPS is enabled. Default: 5707
httpsCertificateStringRequired if enableHttps is true. Path to a .cer file, relative to the API server data directory. Default: null
httpsKeyStringRequired if enableHttps is true. Path to a .pkcs8 file, relative to the API server data directory. Default: null
httpsCaStringAn optional path to a file containing CA certificates to trust. If not supplied the Mozilla CA Certificate Store is used
hostStringInterface to listen on ( indicates all interfaces). Default: ""
localhostStringThe IP address to use for local access to the API Server. (May need to be changed to ::1 on some installations). Default: ""
requestTimeoutInteger (milliseconds)The number of milliseconds of inactivity before a request is forcibly ended at socket level. Default: two minutes
cacheSweepIntervalInteger (milliseconds)User data cache sweep interval in milliseconds. Default: one minute
staleRequestCleanupIntervalInteger (milliseconds)Stale request cleanup interval for multithreaded workers in milliseconds. Default: one hour
tmpFileCleanupIntervalInteger (milliseconds)How often in milliseconds the /tmp cleanup task should run. Default: one hour
tmpFileLifeTimeInteger (milliseconds)The maximum lifetime of files in /tmp. Default: five days
httpLogCleanupIntervalInteger (milliseconds)How often the http log cleanup task should run. Default: one hour
httpLogHistorialFilesKeptIntegerNumber of historical http logs to keep, excluding the current log file. Default: 5
statLogEnabledBooleanWhether the stat log should be written to. Default: true
statLogHistoricalFilesKeptIntegerNumber of historical stat logs to keep, excluding the current log file. Default: 5
statLogWriteIntervalInteger (milliseconds)How often to write to the stat log CSV. Default: one minute
statLogDirStringThe directory to which stat log CSV files are written. Default: "${APISERVER}/log"
debugWebPortInteger (port number)The port that node-inspector binds to. Default: 18080
serverLogBooleanWhether or not to enable server logging. Default: true
logPathStringThe path to the log directory. Default: "${APISERVER}/log"
accessLogFormatStringThe format of the logs. Don't change this
formidableObjectConfiguration for the formidable node module. The defaults should not be changed
    "encoding": "utf-8",
    "uploadDir": {
        "T": "path",
        "V": "${APISERVER}/tmp"
    "keepExtensions": true,
    "maxFieldsSize": 65536,
    "hash": false
consoleTraceLevelStringThe default worker trace level. Options are "debug", "verbose", "info", "warn" and "error". Can be set to "off" to disable. Default: "info" (this can be changed by a user in the console when turning worker tracing on)
fileTraceLevelStringAs above
logNameStringThe name prepended to the log files. Default: "apiserver"
logPathStringDefault: "${APISERVER}/log"
maxLogFileSizeIntegerThe maximum size of each the log file in bytes. Default: 1000000
maxLogFilesIntegerThe number of log files to keep. Default: 10
enablePasswordRedactionBooleanCertain requests (the Gatekeeper for example) include usernames and passwords at some trace levels. Setting this property as true replaces any passwords with the value "[REDACTED]". You may want to disable this in some troubleshooting situations. Default: true
monitorObjectThe API Server's monitor for heavy load and long running requests. See API Server Console. We don't recommend changing the defaults
excludePathsFromHttpLogObjectEach of the paths in this object will be excluded from the HTTP log. This is to prevent the log filling up with background noise (for example web/ajax is called every two seconds). Default: {"^\/web\/.*": "i"}
traceAllRequestsBooleanIf enabled, traces all calls and responses to the API Server at debug level, regardless of the status of any other settings. This will result in a lot of logging building up very quickly. Default: false
workerRequestTracingMasterSwitchBooleanThis setting makes no difference to the temporary tracing enabled in the console. It can be used to globally turn tracing on or off for any worker that has traceWorkerRequests set as true (which will be none unless you've set that up in your worker config). Default: true
traceWorkerRequestsBooleanWhether to enable tracing for the API Server's "manager worker". This property can also be set at the config level for individual workers and saves you having to turn temporary tracing on and off in the console. Default: false
temporaryTracingPeriodInteger (milliseconds)The duration of temporary tracing when enabled in the console. Default: fifteen minutes
checkDbConnOnStartupBooleanWhether or not to check the API Server can access the default database (eg iCM) before starting the workers. If the query fails the API Server will not start any of its workers. Instead, it will wait for "checkDbConnOnStartupIntervalMs" (see below) and try again on repeat until it connects. This setting guards against situations where a web server may be restarted and the API Server started before the database server is ready.

If configuring a 'remote' API Server within a client's DMZ, communicated with over a VPN, this setting will probably need to be false.

Default: true
checkDbConnOnStartupIntervalMsInteger (milliseconds)Default: 60000
checkDbConnOnStartupConnectionTimeoutMsInteger (milliseconds)How long the driver will wait for a database connection. Note: Only respected by the PostgreSQL driver. Default: 5000
checkDbConnOnStartupRequestTimeoutMsInteger (milliseconds)How long the driver will wait for a response from the SQL query request made to the database server. Default: 5000
checkDbConnOnStartupDatasourceNamesArrayAn optional array of datasource names to check before starting the API Server. All must be reachable before any workers are started. If null only the default database (usually icm) will be checked. Default: null
synchroniseWorkerStartupBooleanDefault false. If true workers will start one at a time. This is significantly slower than the standard start-up but has less impact on CPU


It's also possible to define additional datasources in the API Server configuration, allowing your forms, End Points and workers like the FormUtils Worker to interact with data in external (ie not the iCM) databases.

To do this, add the top level environmentConfig object with the details of your database. The "default" should be left as "icm".

"environmentConfig": {
    "dataBases": {
        "default": "icm",
        "dataSources": {
            "mydatabase": {
                "databaseDriverClass": "",
                "databaseUserName": "theusername",
                "databaseConnectionString": "jdbc:sqlserver://GI00645:1433;DATABASENAME=mydatabase;sendStringParametersAsUnicode=true;SelectMethod=direct",
                "databasePassword": "thepassword"

Last modified on 09 June 2022

Share this page

Facebook icon Twitter icon email icon


print icon