Web Service Connectors

Overview

Totalview 2016 SP2 can be extended by implementing connectors that handle the specific communications with external systems.

This document gives you a description of the web service connectors and how Totalview 2016 SP2 interacts with web service consumers.

The web service connector handles the communication between external systems (web service consumers) and the Totalview 2016 SP2 server. The web service delivers functionality such as SetState and GetUsers to the external system, to enable the external system to interact with the Totalview 2016 SP2 server.

Abbreviations used in this document

WS	The web service connector that handles the communication between the Totalview 2016 SP2 server and the external system.
TV3	The Totalview 2016 SP2 system. If not otherwise stated it identifies the Totalview 2016 SP2 server.

General description of the web service interaction

The interface between the Totalview 2016 SP2 server and WS connector is generalized and is independent of the WS consumer.

It is the responsibility of the TV3 server and the WS to send real-time notifications, when changes are made in user’s data from the web service consumer.

Data updates

The TV3 server notifies the WS about changes in user’s data by using XML data packets. The WS buffers the information to serve the web service consumers when needed.

This eliminates the need to access the TV3 for every consumer request.

WCF (SOAP) requests

The web service connector is set up to listen for request on a specific port (default 8000). When requests arrive from the consumers, the web service connector checks to see if the consumer has rights for the request and then returns the result.

The requests can be data requests such as GetUsers or command requests such as SetState. Most data requests are handled without any roundtrip to the TV3 server, while most command requests are sent to TV3 to be executed.

The communication between the WS and the consumer is based on Windows Communication Foundation. Currently the communication is set to use the SOAP protocol.

The web service is hosted in the connector itself and does not need an IIS to be executed.

Use the Totalview 2016 SP2 Admin module to set up, register and start the WS connector.

Execute requests

Requests from the WS consumers can be divided into data requests and command requests. Data requests such as GetUsers are mostly handled by the WS connector, while WS commands such as SetCurrentState are sent to the TV3 to be executed. The result is then relayed back to the consumer.

The web service connectors life cycle

The Totalview3 (TV3) server receives real-time notifications from the web service connector (WS) when a consumer has requested some modification of data. Also the WS receives real-time notifications from the TV3 server when data of interest to the WS is changed in TV3.

Exchanged data

The WS allow external consumer to request data and to execute commands. Some of the requests and commands available are:

Login	Verifies the user and the user’s permission to use the WS
SetCurrentState	Changed the users current state
SearchUser	Get a list of users and their current state
GetUsers	Get a list of all active users
ChangePwd	Change the users current web password

Connector start up

The WS runs as a service and at start up, the connector connects to the TV3 server to verify the license and to receive information about the external consumer system and a list of basic data.

The WS then listens for request on the specified port.

Connector execution

When executing the WS listens for requests from the consumer to be executed on the TV3 system. The requests are processed by the WS if possible, or sent to the TV3 server for execution. Any result is sent back to the consumer.

In case of error when processing the request, an exception is sent back to the consumer. It is the responsibility of the consumer to display an appropriate error message to the user.

Communication model between the WS and TV3

• When the connector service starts, using the IP address and port from its settings, it opens a socket communication channel sending an authentication request to the TV3 server

• If the communication channel cannot be opened, the operation is repeated according to a maximum number of retries which is a setting of the connector

• The same retry mechanism will be issued if for any reasons if the connector loses connection with TV3 server

• If the connector is accepted by TV3 then an accept message is sent back to the connector, otherwise a deny response is issued and the communication channel is closed

• The accept message contains settings configuring the connector such as the address and port to listen for requests from consumers.

How requests from WS consumers are processed

When a request from consumers arrives, the WS verifies that the consumer has rights to the requests. If the consumer has rights to the request, the request is processed and the result is sent back to the consumer.

Installed files

The following files are installed with the Web service calendar connector:

Config.xml,

Totalview3WCF.exe and

Totalview3WCF.exe.config

The config.xml file

The config.xml file, located in the same directory as the web service connector files contains the start-up parameters for the service.

The config file is maintained by the Admin and should not be updated manually.

The config file contains the following parameters:

<startparameters>
    <ServerIpAddress>127.0.0.1</ServerIpAddress>
    <Serverport>3333</Serverport>
    <ConnectorName>WCF</ConnectorName>
    <ConnectorType>MobileWeb</ConnectorType>
    <MaximumRetries>-1</MaximumRetries>
    <ConnectionTimeout>30</ConnectionTimeout>
    <FileLogLevel>4</FileLogLevel>
    <ReconnecInterval>60</ReconnectInterval>
</startparameters>

ServerIpAddress and ServerPort	The address and port of the TV3 server. When the WS starts, it connects to the TV3 server using these settings
ConnectorName	The name of connector defined in Totalview Admin. The connector must be created in Admin before the connector is allowed to connect to the Totalview server. When connected, parameters defined in Admin for the connector is sent to the Web Service connector
ConnectorType	The type of the connector. Used by TV3 to differentiate between the various connector types
ConnectionTimeout	Timeout setting used when the WS tries to connect to the TV3 server
ReconnecIinterval	If the WS is disconnected from the TV3 server, this setting defines how many seconds to wait until the next reconnection is tried
MaximumRetries	If the WS is disconnected from the TV3 server, this settings defines how often reconnection should be tried before abandoned. If setting is -1, the reconnection continues forever
FileLogLevel	0 = disabled 1 = error and start/stop events 2 = 1 + in and out message dates 3 = 2 + full in and out message bodies