Toggle menu

iCM/API Servers

The iCM/API Servers home page lists all hosts serving iCM, the details of the gateway messages they process, any errors that have occurred and any cluster locks they hold.

The "Any host" iCM Server shows messages that can be processed by any host in the cluster.

Servers add themselves to the list automatically when their scheduled task processes gateway messages. Removing a server will delete all of its messages and reset the counters. If the server is active it will add itself back into the list after a short delay.

This section also lists all installed API Servers and is where you configure and manage the workers that run on those servers. All API Servers, including "remote servers" that iCM or the site communicates with are configured from here.

Access to this section of iCM can be granted to an iCM user via their System Configuration Privileges.

iCM Servers

The list of iCM servers shows every server in this cluster that hosts an iCM installation connected to the current iCM database. Each server includes the following information.

HostHost name of the server. The host you are currently connected to has a green tick
Server IDA unique ID for the server
QueueThe number of gateway messages waiting to be processed by this sever
DoneThe number of gateway messages that have been processed since this server was installed (or the counter reset)
LastThe date and time the last gateway message was processed
RunningThe length of time the current message has taken to process
ErrorsThe number of errors that have occurred when processing messages
TimeoutsThe number of gateway messages that took an excessive amount of time to process
LocksThe current number of locks held by the server

What is the iCM Gateway?

To speed up the performance of iCM, various events are queued up to be processed later. Some tasks will need to be processed by all hosts, some by a specific host and others by any host.

iCM gateway messages are generated after you take an action in iCM, like submitting an article, publishing a form or indexing a search collection. They are processed by a scheduled task that runs on each iCM server every fifteen seconds.

Should there ever be a large queue of messages (say, over a few hundred) that doesn't appear to be going down, this may indicate a problem with the gateway task on that server. The task is scheduled automatically when you complete iCM's Autoconfig. Running through Autoconfig will recreate the task and should get things moving again.

Activities like reindexing large amounts of data into the search collections can cause many gateway messages to be generated and slow down performance. You may notice this when other gateway messages, like the article decaching requests, appear not to be working.


The locks held by an iCM server are nothing to worry about. They are not the same as content locks applied to items in iCM visible in the Locked Items section. Rather they are locks applied by iCM preventing concurrent access to certain database resources.

Context Actions

Right-click on an iCM Server to do the following.

Reset Counters

Resets the counters.

Clear Locks

Clears any current locks.

Queue Statistics

View information about queued gateway messages including message types, actions, origin server and the oldest messages in the queue.

Remove Server

If you remove a server, it will be automatically added back in the next time it processes a message.

Action Panel

The action panel lets you send a ping message to the iCM Servers to check iCM's ability to communicate with them, refresh the server lists and update the icons iCM uses.

API Servers

Every server that has iCM installed on it, and every web server that delivers an iCM powered website, must also have an accompanying API Server. If your site and iCM run on the same server, you'll just have the one API Server.

It is also possible to install "remote" API Servers, perhaps on an internal network communicating with back-office systems. These remote servers are generally communicated with via a VPN connection. These remote servers are also managed from this section of iCM.

Creating an API Server

API Servers are installed using the appropriate Windows or Linux installer provided by us here at GOSS. API Servers run as a service.

Once installed each API Server needs to be registered in iCM. To register a new API Server click "Create an API Server" in the action panel. You'll need to set the following:

HostThe name of the host that the API Server has been installed on
Server IDThis can be anything, but is visible in iCM, so should be a meaningful description
URLThe URL of the API Server. Avoid using or localhost unless you are working in a local development environment.

In a clustered environment a hostname for the server that is resolvable by other servers in the cluster should be used.

You need to include the default API Server port, 5706.
Config fileThe file that holds the configuration you'd like to send to the API Server. The drop-down will list all of the .conf files found in the icm\custom\apiserverconfigs directory

Standard configuration can be found in the icm-<VERSION>-standard.conf file, although site and environment specific versions may be present in your installation

Note, when working in a clustered environment, or with a remote API Server, the IP addresses of all API Servers that iCM has to manage should be added to the MANAGER key in API Server Security. When installing a new server these IP addresses need to be added before the configuration is sent for the first time.

Editing an API Server and Configuring Workers

To edit an API Server, right-click and choose "Edit Server", or double-click on it.

The edit server screen displays a list of currently running services (workers) as well as services that are available but not in use.

Note that in a clustered environment each API Server will need to be managed in turn.

Running Services

Services listed as "Running" are those that were defined in the last configuration file sent to the API Server.

If any of these workers have updates available, the name of the update version is listed in bold. The updates available are those files that exist in the icm\custom\apiserverupdates directory that have not yet been deployed. 

Updates can be deployed individually (right-click on them) or all at once from the action panel.

Restarting Workers

To restart a worker, right-click on it in the list of running services and pick "Restart Worker".

Available Services

Services listed as "Available" are either:

  • Workers that exist on the file system in the APIServer\workers directory but have not been configured to run
  • Uninstalled workers found in the icm\custom\apiserverupdates directory (for a file to show up here it must be a zip with a name in the format <name>-<version> Uninstalled workers can be installed by right clicking on them, extracting your zip into the API Server's worker directory

If you are developing a new worker, adding a correctly named zipped copy of it to the apiserverupdates directory in the custom folder (often accessible via the File manager in iCM) will allow you to deploy it to the API Server. You'll then need to include appropriate configuration for it in the API Server configuration file.

Configuration Files

As already mentioned, the configuration you send to the API Server is held in a file in the icm\custom\apiserverconfigs directory. Use this file to set up your workers and supply them with any optional or additional configuration.

We've included an annotated version of our standard configuration file, which contains information about the workers and how their various parameters. There's also lots of information in the API Server and Worker Configuration section of this site.

Once changes have been made to an API Server, including changing the configuration file that it uses, select "Save this server" from the action panel then right click and "Send Configuration" to the server for the changes to take effect.


Checking Configuration

If you encounter a problem with an API Server, you should first check the configuration it is using. The easiest way to see the actual configuration being used is from within the API Server Console. The top level menu item "Settings" shows the configuration for the API Server. Clicking on a worker and then the cog icon shows the configuration for that worker.

First Install

When an API Server is first installed it is in an open state with no running workers. The first configuration file you send to it not only starts up your chosen workers, but also sets up environment information, security, and IP restrictions (using the addresses set in your security keys). A common mistake made during installation is to send the configuration to the API Server before setting up the security, effectively locking iCM out of the API Server's management access.

If you do lock iCM out of an API Server, you will need to manually delete the configuration files. To do this you'll need access to the file system where the API Server is installed, then:

  1. Stop the iCM v10 API Server Service
  2. Remove all of the lastGood*Config.json files from E:\iCM10\APIServer\data\ (or wherever your API Server is installed)
  3. Start the iCM v10 API Server Service again
  4. Send the configuration to the API Server from iCM, with the correct IP addresses added to the MANAGER security key (all the previously removed lastGood* files will be recreated)

Connection Failure

Mistakes in your configuration, or errors when deploying and developing brand new workers, may also cause connection failures. To restore an API Server to a working state follow the four steps above, removing the configuration, restarting, then sending known working configuration to it.

Delivery Servers

The delivery servers section should list all servers serving iCM subsites managed by this installation. The URLs entered for these subsites can be used by iCM to clear the cache on those servers. Further functionality may be added to this area in future releases.

Creating Delivery Servers

To add a delivery server to the list click "Create a delivery server" in the action panel. You'll need to set the following:

HostThe host name of the server
Server IDiCM will assign a random ID to the server
URLA URL iCM can use to connect to the server
Last modified on 22 February 2024

Share this page

Facebook icon Twitter icon email icon


print icon