Sometimes you'll need your website and iCM, both hosted in the GOSS Datacentre, to communicate and interact with various back-office systems, hosted either by yourself or a third party.
Direct Access via a VPN
Our preferred method for connecting the platform hosted with us to non-hosted systems is via a VPN. This would allow the GOSS-hosted services to communicate directly with your environment.
This approach means simpler API Server configuration, developers having less to consider when writing End Points, and gives your infrastructure team control over what can be accessed.
Remote API Server
We no longer recommend remote API Servers due to the fact they still require VPN connections and add extra complications in setup, support and maintenance.
A remote API Server is an API Server service installed in the non-GOSS environment, linked to the GOSS platform via a VPN, through which communication between the platform and external system passes. The remote service hosts some API Workers of its own, and proxies requests to others back to the GOSS hosted platform.
The configuration and initial setup of the API Servers is more complicated than direct access. Our ability to support and monitor the remote API Server will also be limited (see below). As communication is handled by the single API Server it can also become a single point of failure.
Configuring a Remote API Server
The following diagram shows a typical remote API Server installation.
The things to note are:
- Not all workers are shown, the GOSS-hosted API Server would typically contain many more
- HTTP requests are made in both directions over the VPN, using the standard API Server port 5706
- There is no direct access to the iCM database over the VPN
- If the remote API Server is running any End Point capable workers, it must have the iCM API worker defined as a proxy
Typically only the workers needed for the integration should be deployed to the remote API Server.
Proxied Workers
The proxied workers on the remote API Server can be invoked locally using http://localhost:5706. The API Server will automatically proxy the request to the corresponding worker in the GOSS-hosted environment. This includes requests made by End Points deployed to the remotelibrary.
End Points
In the example above the Server Library is running on both API Severs. This means that any End Points published to this worker are available locally in both environments.
The Remote Library is only running on the remote server. End Points published to it are available locally on the remote server. They can be invoked from the GOSS-hosted environment by making a direct request to http://remotehost:5706/remotelibrary.
Configuration
Remote API Severs are managed from within the System Configuration section of iCM Management, in exactly the same way as any other API Server. Their configuration script should be held in the standard icm\custom\apiserverconfigs directory.
Each proxied worker should have the following configuration, entered as an object in the "proxies" array:
{
"proxies": [{
"name": "<<worker_name>> Proxy",
"pathRegex": "^/<<worker_URL>>",
"targetHostReplacementPattern": "http://<<GOSS_server_host>>:5706",
"servicePaths": [{
"name": "<<worker_name>>",
"urlPath": "<<worker_URL>>"
}],
"apiKey": "<<generated_API_key>>"
}]
}
Where:
The workers you need to proxy should be bound to an API key. This key can be restricted using IP rules to only allow requests that originate from the VPN.
This screenshot shows a dedicated key for the remote API Server and the workers we are planning to proxy.
Example Setup Steps
Once an API Server has been installed remotely, the following steps should be carried out.
- Make a note of the local API Server's hostname/IP, visible in the iCM/API Servers section of iCM
- In the API Server Security section, add both the local server's and remote server's IP addresses to the MANAGER key (as allowed IPs)
- In the API Server Security section, create a new API key. Add each worker you would like to proxy to this key. Add the IP address of the remote server as an allowed IP. Make a note of the key
- Create a new remote API Server .conf file. Add every worker you would like to proxy to it, plus the workers you would like to run on the remote server. An example file is shown below
- In the iCM/API servers section, create a new API Server. Enter the host and URL of the remote server and choose the remote config file created in the previous step
- Save the server and send the configuration to it
Example Configuration File
In the example below, substitute
{
"proxies": [
{
"name": "gatekeeper Proxy",
"pathRegex": "^/gk",
"targetHostReplacementPattern": "http://GOSSHostedApiServer:5706",
"servicePaths": [{"name": "gatekeeper", "urlPath": "gk"}],
"apiKey": "xxxxxx-xxxx-xxxx-xxxx-xxxxxx"
},
{
"name": "icmapi Proxy",
"pathRegex": "^/icmapi",
"targetHostReplacementPattern": "http://GOSSHostedApiServer:5706",
"servicePaths": [{"name": "icmapi", "urlPath": "icmapi"}],
"apiKey": "xxxxxx-xxxx-xxxx-xxxx-xxxxxx"
},
{
"name": "formutils Proxy",
"pathRegex": "^/formutils",
"targetHostReplacementPattern": "http://GOSSHostedApiServer:5706",
"servicePaths": [{"name": "formutils", "urlPath": "formutils"}],
"apiKey": "xxxxxx-xxxx-xxxx-xxxx-xxxxxx"
},
{
"name": "workflow Proxy",
"pathRegex": "^/workflow",
"targetHostReplacementPattern": "http://GOSSHostedApiServer:5706",
"servicePaths": [{"name": "workflow", "urlPath": "workflow"}],
"apiKey": "xxxxxx-xxxx-xxxx-xxxx-xxxxxx"
},
{
"name": "formsservice Proxy",
"pathRegex": "^/formsservice",
"targetHostReplacementPattern": "http://GOSSHostedApiServer:5706",
"servicePaths": [{"name": "formsservice", "urlPath": "formsservice"}],
"apiKey": "xxxxxx-xxxx-xxxx-xxxx-xxxxxx"
},
{
"name": "filestore Proxy",
"pathRegex": "^/filestore",
"targetHostReplacementPattern": "http://GOSSHostedApiServer:5706",
"servicePaths": [{"name": "filestore", "urlPath": "filestore"}],
"apiKey": "xxxxxx-xxxx-xxxx-xxxx-xxxxxx"
},
{
"name": "email Proxy",
"pathRegex": "^/email",
"targetHostReplacementPattern": "http://GOSSHostedApiServer:5706",
"servicePaths": [{"name": "email", "urlPath": "email"}],
"apiKey": "xxxxxx-xxxx-xxxx-xxxx-xxxxxx"
},
{
"name": "history Proxy",
"pathRegex": "^/history",
"targetHostReplacementPattern": "http://GOSSHostedApiServer:5706",
"servicePaths": [{"name": "history", "urlPath": "history"}],
"apiKey": "xxxxxx-xxxx-xxxx-xxxx-xxxxxx"
}
],
"workers" : [
{
"name": "remotelibrary",
"instances": 4
}
]
}
Requesting Services on Remote API Servers
Once remote services have been set up, requests to those services need to include the correct URL. Remember that if you are working remotely, proxied workers are accessible using http://localhost:5706.
Requests to an API Server are most commonly made using the apiclient library. A standard request in an End Point, to a local service, will look something like:
function( params, credentials ) {
var apiclient = require("apiclient");
var client = new apiclient.ApiClient({
});
var request = client.invoke("service", "method", {"parameters"});
return request;
}
To make a request to a remote API Server, provide its URL as the server value:
function( params, credentials ) {
var apiclient = require("apiclient");
var client = new apiclient.ApiClient({
server : "http://remoteServer:5706"
});
var request = client.invoke("service", "method", {"parameters"});
return request;
}
Multiple Environments
Where you have development, test, pre-production and production environments hosted with us, we recommend replicating this in the systems you would like to integrate with.
For example, if your production website integrates with a live back-office system, your test environment, to allow thorough testing, should be able to connect to a test version of the system, so that testing can be carried out without the risk of interfering with live data.
Maintenance and Monitoring
The GOSS Network Team are responsible for monitoring and ensuring the availability of the VPN connection. This availability also depends upon the remote/client end of the connection, which is outside of our control.
Remote API Servers are managed from within iCM, so can be maintained by any user with suitable security privileges. The API Server Consoles of remotely installed servers are also accessible from the GOSS-hosted iCM via the standard proxy.
During patches, upgrades, and their initial installation, the API server installer will need to run on the remote server. With sufficient access a member of the GOSS Network Team will be able to do this, or alternatively installation instructions can be provided.
Note that during the initial installation, when first configuring the security of the remote API Server, it may be necessary to access the API Server's installation directory.
We are unable to monitor or guarantee the availability of non-hosted API Servers.
Share this page
