Web Service

LinkServer supports a Web Services technology for integration with third-party ERP, CRM and other software systems. It supports the SOAP protocol,  used for sending XML-encoded data over secure HTTP connections.

LinkServer’s Web Service allows total control of the server. It is possible to stop/restart the server, manage users, register and configure Device Servers and Data Terminals, view  Data Terminal events and their status etc.

Technically, the Web Service provides methods for getting and setting values of context variables and calling context functions. Listening to context events is not supported.

Web Service Address

LinkServer Web Service is available at the following addresses:

https://server_host_name:server_ssl_port/ws/services/LinkServerWeb (for secure SHTTP-based connections)

http://server_host_name:server_non_ssl_port/ws/services/LinkServerWeb (for non-secure HTTP connections)

server_host_name is the IP address or host name of the server. It may match one of the aliases defined in the host name aliases list Global Configuration Setting.

server_ssl_port is the port number on which LinkServer accepts incoming secure HTTP (HTTPS) connections. Default value is 8443. This port is defined by Port number to listen for HTTPS (secure) connections Global Configuration Setting.

server_non_ssl_port is the port number on that LinkServer accepts incoming HTTP connections. Default value is 8080. This port is defined by Port number to listen for HTTP (non-secure) connections Global Configuration Setting.

Available Functions

Functions that use XML encoding of Data Tables

1. getXML

The getXML Web Service function is used to retrieve values of LinkServer context variables.

Function parameters:

Return value: this function returns a String that is a Data Table containing the value of requested variable. This value is encoded in XML format. See Data Table XML Encoding for more information. The resulting XML string is encoded once again according to the URL encoding standard specified by RFC 1738 (Uniform Resource Locators). This is to ensure that the resulting string doesn't contain characters unsafe for SOAP protocol.

2. setXML

The setXML function allows to change the value for a LinkServer context variable.

Function parameters:

Return value: none.

In most cases, the value argument passed to this function is a Data Table that was previously retrieved by the getXML function.

3. callXML

The callXML function is used to execute LinkServer context functions, by passing function arguments in an XML-encoded Data Table.

Function parameters:

Return value: this Web Service function returns a String that is a Data Table returned by the function executed. This value is encoded just like the value input parameter above.

Functions that REPRESENT DATA TABLES AS STRING ARRAYS

1. setByStringArray

The setByStringArray function is used to change values of LinkServer context variables. Cells of the Data Table containing the new value are passed to it as an array of String arguments.

Function parameters:

Return value: none.

2. callByStringArray

callByStringArray function allows to execute LinkServer context function by passing its arguments as a String array.

Function parameters:

Return value: this Web Service function returns a String that is a Data Table returned by the function executed. This value is encoded just like the value input parameter above.

Functions that use NATIVE encoding of Data Tables

There are three Web Service functions that use the same Data Table encoding used in AggreGate Communications Protocol:

These functions are used to get/set values of LinkServer context variables and call context functions respectively. They are used by LinkServer .NET API and should not be used by other Web Service clients.

Examples

Example 1: Accessing LinkServer Web Service From a PHP Script

This example shows how to get the value of a LinkServer context variable from a PHP script using the Web Service.

<?php

// Creating SOAP client for the LinkServer running on localhost

$client = new SoapClient("https://localhost:8443/ws/?wsdl");

$username = "admin";

$password = "admin";

$context = "users.admin";

$variable = "userInfo";

try

{

       // Calling getXML Web Service function and decoding its output by URL decoder

       $userInfoXML = urldecode($client->getXML($username, $password, $context, $variable));

}

catch (SoapFault $fault)

{

       echo "Error occurred while calling remote function: ".$fault->faultcode." (".$fault->faultstring.")";

       exit();

}

if (is_soap_fault($userInfoXML))

{

       echo "Error occurred while calling remote function: ".$fault->faultcode." (".$fault->faultstring.")";

       exit();

}

// Creating DOM document from XML

$xml = new DomDocument;

$xml->loadXML( $userInfoXML );

// Loading XSLT transformation

$xsl = new DomDocument;

$xsl->load( 'resources/xslt/dataTable.xslt' );

// Creating XSLT processor

$proc = new xsltprocessor;

$proc->importStyleSheet( $xsl );

// Processing out XML document and and showing the output

echo $proc->transformToXML( $xml );

?>

Example 2: Calling a Context Function

This example shows how to create a new LinkServer user account by calling the register function of the root context. Creation of SOAP client and error checking are omitted in this example.

$params[0]="phpuser"; // Username (value for record 0, field 0 of function input Data Table)

$params[1]="test"; // Password (value for record 0, field 1)

$params[2]="test"; // Repeat Password (value for record 0, field 2)

urldecode($client->callByStringArray("admin", "admin", "", "register", $params)); // Calling function via Web Service