The Connection namespace provides the methods for creating a connection to an IC server. The Licenses namespace is also very important, for acquiring the licenses that are required for certain operations.
This topic contains the following sections:
The following additional concepts are related to creating a connection to an IC server. The documentation can be useful to review for going beyond the initial steps of connecting.
In order to use most of the functionality in ICWS, a session must first be established. The POST /icws/connection method is used to create a session (see General Requests for endpoint information). There are two required items:
Accept-Language parameter in the request header.The Accept-Language header parameter specifies the language code that represents the primary language of the client application. The server will return human-readable text in this language and format time, dates, and money to conform to the locale preferences. The parameter may not be changed during a session. Valid values for this header follow the standards defined in the HTTP 1.1 definition in RFC 2616. For example, the language code could be "en-us":
POST https://server:8019/icws/connection HTTP/1.1 Accept-Language: en-us
The connection representation in the request body is used to define the type of connection, including parameters about that connection. The supported types include authTokenConnectionRequestSettings, icAuthConnectionRequestSettings, and singleSignOnTokenConnectionRequestSettings. One (and only one) of these must be included in the request body to establish the connection.
An example of using an icAuthConnectionRequestSettings appears below.
{
"__type":"urn:inin.com:connection:icAuthConnectionRequestSettings",
"applicationName":"ICWS Example Application",
"userID":"user1",
"password":"passwordOfUser1"
}
The I3_FEATURE_ICWS_SDK license must be available on the Interaction Center server for ICWS connections to be established.
If the POST to establish a connection was successful, the response will contain important security information
The response header includes the following information: ININ-ICWS-CSRF-Token, ININ-ICWS-Session-ID, Location, Set-Cookie. An example appears below.
ININ-ICWS-CSRF-Token: ABlcdeVnLmNhemFYCUlDV1MgVGVzdFgkOWVmYmNjMmYtNDViMS00OGU1LTljZDgtMmUwZTBlZDE3NzBhUzo6MQ== ININ-ICWS-Session-ID: 12345678 Location: /icws/12345678/connection Set-Cookie: icws_12345678=1234880c-039c-4199-8342-48e478f2b4a1; HttpOnly; Path=/icws/12345678
The response body includes the following information: csrfToken, sessionId. An example appears below.
{
"csrfToken":"ABlcdeVnLmNhemFYCUlDV1MgVGVzdFgkOWVmYmNjMmYtNDViMS00OGU1LTljZDgtMmUwZTBlZDE3NzBhUzo6MQ==",
"sessionId":"12345678",
"alternateHostList": ["server2", "server3"]
}
The CSRF Token is a PureConnect session token for the session that was just established. The Session ID is a PureConnect session identifier for the session that was just established. All authenticated calls to ICWS for this session must include the sessionId in the URI. All authenticated calls must include the CSRF token in the ININ-ICWS-CSRF-Token request header. For more information about the CSRF Token see Cross-site Request Forgery (CSRF).
The Set-Cookie is a cookie for the session that was just established. All authenticated calls must include this session cookie in the request header. Browsers will automatically consume this session cookie. Non-browser client applications need to pass it (as the parameter Cookie) in the header for all authenticated calls.
The alternateHostList property provides a list of other servers that can be used to reconnect to if the current server becomes unavailable. See Reconnecting for more information.
An example of an authenticated call would be to POST /icws/{sessionId}/licenses. A sample request header for such a call appears below. Note the use of the information that was returned from the POST /icws/connection.
POST https://server:8019/icws/12345678/licenses HTTP/1.1 Accept-Language: en-us Content-Type: application/vnd.inin.icws+JSON Cookie: icws_12345678=1234880c-039c-4199-8342-48e478f2b4a1 ININ-ICWS-CSRF-Token: ABlcdeVnLmNhemFYCUlDV1MgVGVzdFgkOWVmYmNjMmYtNDViMS00OGU1LTljZDgtMmUwZTBlZDE3NzBhUzo6MQ==
When connecting to an IC server that is part of a switchover pair or has off-server Session Managers associated with it, the initial call to POST /icws/connection can be made to any of those servers. If there is a better server to connect to, a 503 HTTP status code will be returned that includes an alternate host list. This list, provided by the alternateHostList property, is an ordered list of servers the client should connect to, with the preferred server included first. The order of the list will vary for each individual ICWS connection attempt and is determined by the server to allow the load of ICWS connections to be distributed among the available Session Managers.
When the client application receives a 503 HTTP status code in response to the connection request, the application should continue calling POST /icws/connection for each server in the list in order until a connection is created, as indicated by a 201 HTTP status code. Once the connection is established, all subsequent requests must be issued to the server to which the connection was established.
The client application issues the initial connection attempt to the IC server:
POST https://ICServer.example.com:8019/icws/connection HTTP/1.1 Accept-Language: en-us ...
The server is not currently accepting connections, so it responds with the 503 HTTP status code and the alternateHostList:
HTTP/1.1 503 Service Unavailable
...
{
"alternateHostList": [
"OSSM1.example.com",
"OSSM2.example.com"
],
"errorId": "error.server.notAcceptingConnections",
"message": "This Session Manager is not currently accepting connections."
}
If we are returning 503 when session manager is inactive, then the better or preferred order of alternate hosts will not be returned. Note that when a switchover occurs while session manager is currently the primary, then it is in the "backup" state only after it has been restarted. Until it is restarted, it is in the "inactive" state.
The client application tries to establish the connection with the alternate hosts in the order they are listed:
POST https://OSSM1.example.com:8019/icws/connection HTTP/1.1 Accept-Language: en-us ...
The server accepted the request, the connection has been established, and the session cookie is returned:
HTTP/1.1 201 Created ININ-ICWS-CSRF-Token: ABlcdeVnLmNhemFYCUlDV1MgVGVzdFgkOWVmYmNjMmYtNDViMS00OGU1LTljZDgtMmUwZTBlZDE3NzBhUzo6MQ== ININ-ICWS-Session-ID: 12345678 Location: /icws/12345678/connection Set-Cookie: icws_12345678=1234880c-039c-4199-8342-48e478f2b4a1; HttpOnly; Path=/icws/12345678 ...
All subsequent requests must be issued to the server to which the connection was established:
POST https://OSSM1.example.com:8019/icws/12345678/licenses HTTP/1.1 Cookie: icws_12345678=1234880c-039c-4199-8342-48e478f2b4a1 ININ-ICWS-CSRF-Token: ABlcdeVnLmNhemFYCUlDV1MgVGVzdFgkOWVmYmNjMmYtNDViMS00OGU1LTljZDgtMmUwZTBlZDE3NzBhUzo6MQ== ...
Single sign-on is a method by which a user can securely authenticate with an identity provider to access resources on a separate service provider without using credentials known to that service provider. Interaction Center and ICWS, as the service provider, support secure authentication with identity providers. At present, ICWS supports identity providers that implement Security Assertion Markup Language (SAML) 2.0.
Single sign-on has additional steps in order to establish an authenticated session with ICWS. Ensure that your system administrator has enabled one or more identity providers in Interaction Administrator that supports at least one of the following authentication types:
The client must first retrieve a list of identity providers that can be used for authentication. The GET /icws/connection/server-info method is used for accessing the list of the configured identity providers and various other pre-connection configuration information. The ICWS API supports multiple SAML 2.0 protocol bindings. Not all client applications will have support for all of the bindings that the ICWS API supports, therefore the singleSignOnCapabilities query string parameter must be specified as a comma-separated list of capabilities that the client supports. The API will only return identity providers that are configured for the specified protocol bindings and will not return any identity providers if the parameter is not specified. The capabilities should be listed in the order of preference. At present these are the supported values:
| Capability | Authentication Type | Notes |
|---|---|---|
saml2Post | SAML 2.0 HTTP POST (SAML 2 Web Browser Post in Interaction Administrator) | Communication between ICWS and the identity provider happens through the client as a series of HTML form posts. Recommended for web browser-based applications. |
saml2Redirect | SAML 2.0 HTTP Redirect (SAML 2 Web Browser Redirect in Interaction Administrator) | Communication between ICWS and the identity provider happens through the client as a series of HTTP redirects. Recommended for other types of applications. |
Most web browser-based applications will support both saml2Post and saml2Redirect but it is recommended that these applications indicate saml2Post first to indicate it as preferred binding.
A request to this API is:
GET /icws/connection/server-info?singleSignOnCapabilities=saml2Post,saml2Redirect
The response is a serverInfo data contract which contains the authentication configuration and other details. An example serverInfo response is:
{
"languages": [
{ "languageID": "en-US", "languageDisplayName": "English (United States)" }
],
"acceptLanguage": "en-US,en;q=0.8",
"authentication": {
"allowIcAuth": true,
"identityProviders": [
{ "identityProviderId": "e00b7273-269c-40f6-ad3c-5721f167dce3",
"displayName": "IC Server" },
{ "identityProviderId": "071753cd-1794-4f17-ac3f-67dce52417d8",
"displayName": "Active Directory Federation Services" },
]
}
}
If authentication.allowIcAuth is false, ICWS will not accept an icAuthConnectionRequestSettings when creating a connection.
Once the application has retrieved the list of identity providers, the application can present the list to the user for selection. Once the desired authentication method is selected, the SAML 2.0 authentication process is started by making a request to the GET /icws/connection/single-sign-on/identity-providers/{identityProviderId} method with the selected identityProviderId. Since an individual identity provider may be configured for multiple SAML 2.0 protocol bindings, the client application must again specify its capabilities by means of the singleSignOnCapabilities query string parameter to ensure a supported binding is selected.
There are two options for how a web browser-based application can perform the SAML 2.0 authentication: Option 1: Using a Pop-up Window and Option 2: Using Redirects. For desktop applications, Option 1: Using a Pop-up Window is the recommended option.
In order to use a pop-up window to perform the SAML process, web browser-based applications should open the GET /icws/connection/single-sign-on/identity-providers/{identityProviderId} URL in a separate frame and should not use XMLHttpRequest. In addition to the singleSignOnCapabilities parameter, web browser-based applications should specify the webBrowserApplicationOrigin query string parameter as the origin from which the application has been loaded. This is to ensure that the single sign-on token can be securely delivered to the application code as described below.
The response to the GET /icws/connection/single-sign-on/identity-providers/{identityProviderId} request is an HTML page as defined by the SAML 2.0 protocol and the specific binding that was negotiated. For web browser-based applications that open the request in a new frame, sequence of requests will be handled automatically following the binding specification.
The final HTML page of the SAML 2.0 process will be returned from the request to /icws/connection/single-sign-on/return. For applications that have access to the response headers, the single sign-on token will be provided in the ININ-STS-Token header. Web browser-based applications will not have access to the response headers, so instead, the final HTML page will call window.postMessage with the target origin specified as the value of the webBrowserApplicationOrigin query string parameter from the GET /icws/connection/single-sign-on/identity-providers/{identityProviderId} request. The message is a JSON object that has been converted to a string using JSON.stringify. An example of the JSON object for a successful authentication is as follows:
{
"key": "icwsSsoComplete",
"data": {
"token": "SomeSingleSignOnToken",
"errorMessage": "",
"errorId": "",
"httpStatus": 200
}
}
This JSON object will always contain this structure. The key property will always be icwsSsoComplete. If the authentication process was successful, the token property will contain the single sign-on token that can be used in the POST /icws/connection request. If the authentication process was unsuccessful, the token property will be an empty string, and the errorMessage and errorId properties will contain error information consistent with the other error responses in the ICWS API. The httpStatus property is always the status code of the HTTP response.
In order to perform the SAML process in the same window, web browser-based applications should navigate the browser to the GET /icws/connection/single-sign-on/identity-providers/{identityProviderId} URL. In addition to the singleSignOnCapabilities parameter, web browser-based applications should specify the redirectUri query string parameter. This value should be the absolute URL that the browser should be directed to once the SAML process is complete. Once navigated, the authentication process will begin as defined by the SAML 2.0 protocol and the specific binding that was negotiated.
Once the SAML process has been completed, the web browser will be directed to navigate back to the URL specified by the redirectUri query string parameter. In order for the application to retrieve the single sign-on token that can be used in the POST /icws/connection request, the web application must call GET /icws/connection/single-sign-on/response. If the authentication process was successful, the single sign-on token will be provided in the JSON body of the HTTP 200 response. If an error occurred, the error information will be included in the HTTP 400 response.
Once the single sign-on token has been obtained, a connection can be established using the POST /icws/connection method. This process is the same described by Establishing a Basic Connection but instead of using icAuthConnectionRequestSettings use singleSignOnTokenConnectionRequestSettings. An example of singleSignOnTokenConnectionRequestSettings appears below:
{
"__type":"urn:inin.com:connection:singleSignOnTokenConnectionRequestSettings",
"applicationName":"ICWS Example Application",
"singleSignOnToken":"SomeSingleSignOnToken"
}
For security reasons, SAML 2.0 identity providers require the URL of the service that will be consuming the claims provided by the identity provider. This precaution helps to ensure that claims do not get delivered to an untrusted 3rd party. Depending on the identity provider, this URL may be called the "assertion consumer service" or the "relying party". For Active Directory Federation Services (ADFS) this setting is "Relying Party Trusts".
The format for the service URL for ICWS is as follows substituting the {server} placeholder for the actual host name:
https://{server}:8019/icws/connection/single-sign-on/return
There will need to be an entry in the identity provider for all of the IC servers and off-server Session Managers so that the identity provider trusts all ICWS endpoints. If clients connect to ICWS by means of a reverse proxy, the URL will need to reflect the proxy URL. See Proxying HTTP Requests for more information about proxy URLs.
There are three different options that a client application can choose from to maintain a session with the server by using one of the messaging mechanisms.
Event messages are sent in the messaging queue on the ICWS server as they become available. As long as the server-sent events connection is open between the client and the server, the server will keep the session open. For more information on server-sent events see Retrieving Messages.
The client application uses short-polling to request queued messages through the GET /icws/{sessionId}/messaging/messages method. Since this request is done to an authenticated endpoint, the session timeout gets reset every time the short-polling request is received by the server. Please note that the session will timeout after 2 minutes if no other authenticated requests are made to the server. For more information on short polling see Retrieving Messages.
The heartbeat option is a lightweight way for a client to inform the server that a session using server-sent events is still alive and it should not be timed out due to inactivity. This should only be necessary in particular situations where the server-sent events connection might outlive the client's connection. In those rare instances, the heartbeat option can be used to help clean up sessions in a timely manner.
Since the server enforces session timeouts due to inactivity at least every 2 minutes, in some instances it may be desirable for a client to let the server know that a particular session is still alive and should not be timed out; or vice-versa, that a session is no longer active and it should be disconnected. A client can inform the server that it wishes to use a heartbeat by including the heartbeat query string on the messaging resource by using the GET /icws/{sessionId}/messaging/messages method. The client then would need to periodically send a heartbeat request to the server letting it know that the session is still alive. This is done through the POST /icws/{sessionId}/messaging/heartbeat method. The response to this POST request is an HTTP 204 response. It is recommended that the client sends a heartbeat request to the server every 90 seconds if there is no other authenticated request traffic being sent to the server within those 90 seconds. If requests to other authenticated endpoints are being made within at least 90 seconds of each other, there is no need to send a heartbeat request.
The connection to ICWS can be lost for a variety of reasons, including a switchover, a subsequent logon from another location, and the user's account being deleted. When the connection is lost, the ICWS server will begin rejecting requests with the 401 HTTP status code; however, for a limited time, the GET /icws/{sessionId}/connection method will continue to function. This provides client applications the chance to retrieve information about why the connection was lost. The reason property provides a localized textual description that can be displayed to the user. The shouldReconnect property will be true if the client application can attempt to automatically reconnect. It will be false when the client application should not attempt to automatically reconnect. If it is able, the ICWS server may also send the connectionStateChangeMessage to indicate the client has been disconnected. This message includes the same reason and shouldReconnect properties as the GET /icws/{sessionId}/connection response.
If the server indicates that automatically reconnecting is allowed, the client application should use the following logic to re-establish a connection. It should use the alternate host list provided in the response to the last POST /icws/connection request.
You can create custom applications and use ICWS to connect to PureConnect Cloud servers using an MPLS network connection, or using a non-MPLS internet connection. Over an MPLS network to PureConnect Cloud servers, ICWS connections are the same as if on a LAN. For non-MPLS (internet) connections to PureConnect Cloud servers, additional requirements and steps apply.
These instructions only apply to PureConnect Cloud customers who have purchased the ICWS Internet access license (CS-012-INET-ICWS) and who have received their own custom ICWS URL. The custom URL structure is: https://apps.caas.com/<friendlyname>/customICWS
This public URL is secured with the Genesys public Certificate Authority, so no additional certificate trust is required. If you do not have this URL, contact your Genesys partner or Technical Account Manager.
This section does not apply to PureConnect premises customers.
ICWS connections to PureConnect Cloud servers must first GET the servers.json file, then parse that file for the serviceURLTemplate value and use the server URL in subsequent ICWS calls.
servers.json file from your PureConnect server in the /config folder: https://apps.caas.com/<friendlyname>/customICWS/config/servers.json.servers.json file looks similar to the following example. Note that these server names are subject to change at any time and it is therefore important to always use the data from the servers.json file.
{
"version": 1,
"servers": [
{ "host": "indXXXgicYYY.cscp.inin.local", "displayName": "indXXXgicYYY.cscp.inin.local", "altHostHints": ["denXXXgicYYY.cscp.inin.local"], "order": 0 }
],
"serviceURLTemplate": "https://iw-145-den.us.cscp.hosted-inin.com/<friendlyname>/CustomICWS/api/{host}/",
"authType": "<ic-idp>"
}servers.json file and extract the serviceURLTemplate value to use with subsequent ICWS calls. For example:https://iw-145-den.us.cscp.hosted-inin.com/<friendlyname>/CustomICWS/api/indXXXgicYYY.cscp.inin.local/icws/connection/versionPOST messages do not automatically redirect after each new connection. Each time you make a new connection, you must GET the servers.json file and extract the serviceURLTemplate value to use for that connection. The reason is the server details (in the highlighted part of the example) could have changed since the previous connection.