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.

Current web consumers are the mobile web application.

Abbreviations used in this document

WS The web service connector that handles the communication between the Totalview 2016 SP2 server and the external system.
MWA The mobile web application that enables mobile users to interact with the Totalview 2016 SP2 server to search users, set state etc.
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.

Mobile Web Application

The Mobile Web Application (MWA) is designed to run in browsers on mobile devices. Using the MWA the user can query other users, make remote call, set current state etc.

The MWA communicates with the web service through the defined port. The MWA can be installed on an IIS on any machine, but there must be access to the machine where the web service connector is installed.

The MWA installation kit can be found in the installation zip file.

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

Mobile Web Application

The Mobile Web Application is a web application that is designed to run in a browser on mobile devices.

The MWA enables the user to search other users to see their current state and contact information, execute remote calls, set current state etc.

Communication using SOAP

The MWA in an ASP.NET application and is installed on an IIS. The MWA communicates with the WS connector through the defined servername:port.

Installing the Mobile Web Application

The installation procedure installs the files on the specified machine and creates a virtual directory on the IIS that point to the folder containing the installed files.

Execute the Totalview3MobileWebSetup.exe file located in the setup zip file.

Follow the direction on the screen.

  • Select folder to install the files. Default is [program files]\Formula.fo\Mobile Web.
  • Configure the server connection. If the MWA is installed on the same machine as the WS connector, then leave the current settings (localhost:8000). If the MWA is installed on a different machine than the WS connector, then add the name or IP of the machine where the WS connector is installed. Do notice that if installed on different machines, then the various firewalls must be updated to allow communication between the machines on the specified port.
  • Set the name of the virtual directory on the IIS. Default is TVMobileWebApp and if using this name, the MWA can be accessed using http://localhost/TVMobileWebApp.

IIS and Web Service Extensions

The MWA is built using ASP.NET and thus requires that the ASP.NET web extension is set to Allowed.

The web.config file

The installation kit creates the file web.config that contains the address of the WS connector. If that address of the WS connector changes, the address can be modified in this file.

The address is located at the bottom of the file. Search for “endpoint address”

The MWA can be installed on any machine that has access to the machine where the WS connector is installed.

Communication description

The MWA communicates with the WS connector using SOAP requests. The WS connector listens for request at a specified port and the MWA sends request to this post.

The MWA is based on ASP.NET and is hosted on an IIS.

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

Last edited on June 20th, 2017