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.
| Item | Description |
|---|---|
| Host | Host name of the server. The host you are currently connected to has a green tick |
| Server ID | A unique ID for the server |
| Queue | The number of gateway messages waiting to be processed by this sever, see Queue Statistics |
| Done | The number of gateway messages that have been processed since this server was installed (or the counter reset) |
| Last | The date and time the last gateway message was processed |
| Running | The length of time the current message has taken to process |
| Errors | The number of errors that have occurred when processing messages |
| Timeouts | The number of gateway messages that took an excessive amount of time to process |
| Locks | The current number of locks held by the server |
Locks
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. See Queue Statistics.
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:
| Item | Description |
|---|---|
| Host | The name of the host that the API Server has been installed on |
| Server ID | This can be anything, but is visible in iCM, so should be a meaningful description |
| URL | The URL of the API Server. Avoid using 127.0.0.1 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 file | The 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>-worker.zip ). 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.
Troubleshooting
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:
- Stop the iCM v10 API Server Service
- Remove all of the lastGood*Config.json files from E:\iCM10\APIServer\data\ (or wherever your API Server is installed)
- Start the iCM v10 API Server Service again
- 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:
| Item | Description |
|---|---|
| Host | The host name of the server |
| Server ID | iCM will assign a random ID to the server |
| URL | A URL iCM can use to connect to the server |
Share this page
