Session management

Session management is one of the most important aspects of developing a client that calls into Integration Server. Failing to re-use sessions properly will result in Perceptive Content Server having to create a brand new session for every call which will severely impact performance on both the server and database. On the other side, over-use of a single session between multiple accounts may limit the throughput of operations due to Integration Server only handling one call at a time per session. Finally, some aspects of Perceptive Content Server are based on session (such as Workflow locks) so failing to use sessions properly may prevent proper use of that functionality.

Initiating a session

A session is created any time an existing, valid session is not provided to an Integration Server request. In order to initiate a new session, user credentials must be provided in some way. They can be passed over via the Authorization header, the tandem of X-IntegrationServer-Username/X-IntegrationServer-Password headers, or through an SSO token (depends on the SSO provider). When a new session is initiated, a session hash will be returned via the X-IntegrationServer-Session-Hash header. Although a session may be established by making a GET /connection request, any call in Integration Server will establish a connection if appropriate credentials are provided.

Maintaining a session

To use a previously established session for a request, the session hash for that session should be provided to the X-IntegrationServer-Session-Hash request header. The X-IntegrationServer-Session-Hash response header will always contain the session hash that was used to process the call. By default, a session will automatically expire if it has not been used in the past 60 minutes (this is configurable within Perceptive Content Server). Whenever a session is no longer needed, it should be deleted by making a DELETE /connection request.

Session issues

If a session hash is provided but the session is invalid (never existed or has expired), there are two possible responses based on other headers. If credentials are provided in addition to the session hash, a new session will automatically be generated, the call will be processed as normal, and the new session hash will be returned. If credentials are not provided, a Status Code of 401, an X-IntegrationServer-Error-Code of UNAUTHORIZED_ERROR, and an X-IntegrationServer-Error-Message prompting for credentials will be returned. When maintaining sessions, invalid session hashes should be cleaned up immediately so that they are not repeatedly used (repeatedly using an invalid session hash will repeatedly create new sessions automatically if credentials are provided).

Best practices