The shortcut SOAP stands for Simple Object Access Protocol. Most current programming languages support SOAP. Furthermore LiveConfig provides a WSDL file (Web Service Description Language) for automatic detection of all available functions and data types for a seamless integration into own applications.

The communication for SOAP access is done using XML message and normal HTTP(s) connections. For example, the invocation of the SOAP method TestSayHello looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:ns1="urn:LiveConfig">
  <SOAP-ENV:Body>
    <ns1:TestSayHello>
      <ns1:auth>
        <ns1:login>admin</ns1:login>
        <ns1:timestamp>2009-12-22T19:20:59.000Z</ns1:timestamp>
        <ns1:token>7juGMfg7N/F1G4t+S7XW99nRidg=</ns1:token>
      </ns1:auth>
      <ns1:firstname>Manfred</ns1:firstname>
      <ns1:lastname>Mustermann</ns1:lastname>
    </ns1:TestSayHello>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

On a successful invocation the response looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Body>
    <TestSayHelloResponse xmlns="urn:LiveConfig">
      <greeting>Hello, Manfred Mustermann</greeting>
    </TestSayHelloResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

If an error occured while processing the request, a SOAP exception containing an appropriate error message is generated. For instance the exception because of an expired (invalid) timestamp looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
                   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault>
      <faultcode>SOAP-ENV:Server</faultcode>
      <faultstring>Authentication timestamp too far in past or future</faultstring>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

5.1.1.  Prerequisites

The LiveConfig SOAP API can be access at the URL /liveconfig/soap. All SOAP request have to be in document/literal style (not RPC/encoded).

Additionally, you need a Standard license or a Business license for LiveConfig. The SOAP API is not available with the Basic license.

To authenticate SOAP requests, a special token is required. This is a checksum on the time, method name and a separate SOAP password. Each user in LiveConfig may define a SOAP password beside his normal user password (see Section 2.7, “ Password Initialization ”.

All SOAP methods require the submission of an auth parameter, which contains the user name, a timestamp and the SOAP token. The token is a base64-encoded HMAC-SHA1 checksum on the string LiveConfig, the user name, the invoked method name and a time stamp; the SOAP password is used as key.

This example shows the creation of the auth parameter in PHP 5:

$user = 'admin';         # user name
$pass = 'PaSsWoRt';      # SOAP password
$func = 'TestSayHello';  # invoked SOAP method

# create timestamp; example: '2009-12-07T11:05:00.000Z'
$ts = gmdate("Y-m-d") . "T" . gmdate("H:i:s") . ".000Z";

# create token:
$token = base64_encode(hash_hmac('sha1',
                                 'LiveConfig' . $user . $func . $ts,
                                 $pass,
                                 true
                                )
                      );

# create auth parameter:
$auth = array('login'     => $user,
              'timestamp' => $ts,
              'token'     => $token
             );

The timestamp has to be in UTC/GMT time zone and must not differ by more than 15 minutes from the local time at the LiveConfig server.

Resellers: invoke methods with customer's permissions

Resellers can invoke all SOAP methods also with their customer's permissions. This is useful for example if you want to assign additional customers to one of your own customers.

In this case just add the (encoded) customer ID to the token and the parameter customer to the auth parameter.

The customer, with whose permissions a method is to be invoked, also requires the appropriate permissions for this, independent of the user used for SOAP authentication.

Example for method invocation with customer permissions in PHP 5:

$user = 'admin';         # user name
$pass = 'PaSsWoRt';      # SOAP password
$func = 'TestSayHello';  # invoked SOAP method
$cust = 'c9R4hQp.T-rF';  # encoded customer id

# create timestamp; example: '2009-12-07T11:05:00.000Z'
$ts = gmdate("Y-m-d") . "T" . gmdate("H:i:s") . ".000Z";

# create token:
$token = base64_encode(hash_hmac('sha1',
                                 'LiveConfig' . $user . $func . $ts . $cust,
                                 $pass,
                                 true
                                )
                      );

# create auth parameter:
$auth = array('login'     => $user,
              'timestamp' => $ts,
              'token'     => $token,
              'customer'  => $cust
             );

LiveConfig provides a WSDL description of all permitted methods and accompanying data types for a particular user. For this, append ?wsdl as well as the user name and the SOAP password to the SOAP URL.

The following example shows the creation of a SOAP client in PHP 5 based on a WSDL file:

$user = 'admin';         # user name
$pass = 'PaSsWoRd';      # SOAP password

# create WSDL URL:
$url = 'https://your.liveconfig.server:8443/liveconfig/soap'
      .'?wsdl'  # request WSDL
      .'&l=' . urlencode($user)
      .'&p=' . urlencode($pass);

# create SOAP client:
$client = new SoapClient($url,
                         array('style' => SOAP_DOCUMENT,
                               'use'   => SOAP_LITERAL,
                              )
                        );

Currently the SOAP password for the WSDL request is appended unencrypted to the WSDL URL. The transmission to the server though is encrypted using the HTTPS protocol and in the access_log from LiveConfig the password gets masked. In later versions of LiveConfig the use of a password hash is planned. But because some programming languages (e.g. the WebService Wizzard from C#) expect the input of a WSDL URL, a manual hash calculation isn't practical.

5.1.4.  Examples

In this section you find some examples for using the SOAP API with common program languages.

PHP5 has native SOAP support and requires (other than PHP4) no additional PEAR/PECL packages. The only prerequisite is that PHP was compiled with the option --enable-soap. If SOAP support is enabled can be seen in the output of phpinfo():

The following example program shows all necessary steps to send a SOAP request to LiveConfig:

<?php

  # Configuration parameters:
  $user = 'admin';
  $pass = 'PaSsWoRd';
  $url  = 'https://your.liveconfig.server:8443/liveconfig/soap';

  # Construct WSDL URL
  $wsdl_url = $url
             .'?wsdl'
             .'&l=' . urlencode($user)
             .'&p=' . urlencode($pass);

  # Create SOAP client
  $client = new SoapClient($wsdl_url,
                           array('style'    => SOAP_DOCUMENT,
                                 'use'      => SOAP_LITERAL,
                                )
                          );

  # Construct SOAP token:
  $ts = gmdate("Y-m-d") . "T" . gmdate("H:i:s") . ".000Z";
  $token = base64_encode(hash_hmac('sha1',
                                   'LiveConfig' . $user . 'TestSayHello' . $ts,
                                   $pass,
                                   true
                                  )
                        );

  $auth = array('login'     => $user,
                'timestamp' => $ts,
                'token'     => $token);
  
  $params = array('auth'      => $auth,
                  'firstname' => 'John',
                  'lastname'  => 'Doe');

  try {
    $response = $client->TestSayHello($params);
  } catch (SoapFault $soapFault) {
    die("Error while calling Web Service: " . $soapFault->faultstring . "\n");
  }

  echo "Response: " . $response->greeting . "\n";

?>

The commonly used Perl module SOAP::Lite does not support the document/literal format, which has been widely accepted as standard for web services.

Instead we recommend the module SOAP::WSDL, which can also be installed via CPAN.

The following example program shows all necessary steps to send a SOAP request to LiveConfig:

#!/usr/bin/perl -w -t

use strict;
use SOAP::WSDL;
use MIME::Base64;
use Digest::HMAC_SHA1;
use URI::Escape;

# Configuration parameters:
my $user = 'admin';
my $pass = 'PaSsWoRd';
my $url  = 'http://your.liveconfig.server/liveconfig/soap';

# Construct WSDL URL
my $wsdl_url = $url
              .'?wsdl'
              .'&l=' . uri_escape($user)
              .'&p=' . uri_escape($pass);

my $firstname = 'John';
my $lastname  = 'Doe';

# Create SOAP client
my $soap = SOAP::WSDL->new( wsdl => $wsdl_url);

# Construct SOAP token:
my ($sec,$min,$hour,$mday,$mon,$year)=gmtime(time);
my $ts = sprintf('%4d-%02d-%02dT%02d:%02d:%02d.000Z',
                 $year+1900, $mon+1, $mday, $hour, $min, $sec);
my $token = MIME::Base64::encode(
                Digest::HMAC_SHA1::hmac_sha1(
                    'LiveConfig' . $user . 'TestSayHello' . $ts,
                    $pass
                ),
                ''
            );

my %auth = ('login'     => $user,
            'timestamp' => $ts,
            'token'     => $token
           );

my %params = ('auth'      => \%auth,
              'firstname' => $firstname,
              'lastname'  => $lastname
             );

my $som = $soap->call('TestSayHello', TestSayHello => \%params);

if ($som->fault) {
  die "Error while calling Web Service: " . $som->faultstring . "\n";
}

print "Response: " . $som->result() . "\n";

In the following reference all SOAP methods are listed.

Method Description
TestSayHello Test method to check SOAP API
LiveConfigVersion Query version number of the LiveConfig server
UserEdit Edit user
SessionCreate Create session (for Single Sign On)
Prev   Next   Up   Home