RIDE SOAP Interface Service Provider User guide1.6 Document Conventions This document uses several conventions to facilitate recognition of instructions. See RIDE Web Interface Service

RIDE SOAP Interface

Service Provider

User guide

RIDE SOAP Interface Service Provider User guideIssue A09a 2 March 2007Copyright © 2004-2007 BT

Page 2 of 109

Copyright © 2003-2006 BT

All rights reserved. This publication and all supporting material is made available for the sole use of the original recipient. It may not be copied by any means or provided or otherwise made available in whole or in part to any other party without first obtaining written consent from BT.

Unauthorised copying, duplication, selling or otherwise distributing the document is a violation of copyright. Title to and ownership of this publication will at all times be with BT.

This publication is believed to be accurate. No responsibility is accepted for any inaccuracy of either this publication or the systems to which it relates, or of the consequences of the use of this publication, or such systems.

BT follows a policy of continuous improvement and reserves the right to revise this publication without notice.

Document History

Revision Number Date Summary of Change(s) Author

A1 10/06/2006 First draft of document MCWH

A2 19/06/2006 BT Review MCWH

A2a 03/08/2006 Issued for distribution MVD

A2b 09/08/2006 Error code and load control updates MVD

A2c 15/09/2006 Winner selection added MVD

A2d 13/11/2006 Inter command pause reduced to 10 seconds MVD

A7a 23/11/2006 To keep in step with new supplier documents MVD

A7b 19/12/06 To add url for updates MVD

A09a 02/03/2007 Simple synchronisation MVD


Page 3 of 109

1 INTRODUCTION .................................................................................................6

1.1 Purpose .............................................................................................................................6 1.2 Scope.................................................................................................................................6 1.3 Security .............................................................................................................................7 1.4 How to Read this Document ............................................................................................8 1.5 Related Documentation....................................................................................................8

1.5.1 System Specific Documents.........................................................................................8 1.6 Document Conventions....................................................................................................8 1.7 Where to find the latest version of this guide ................................................................8

2 INTRODUCTION TO RIDE SOAP.......................................................................9

2.1 What is SOAP....................................................................................................................9 2.2 Web Services & WSDL .....................................................................................................9 2.3 SOAP Tool Kits ...............................................................................................................10 2.4 Interoperability................................................................................................................10

3 SOAP INTERFACE FUNCTIONALITY .............................................................11

3.1 SOAP Request Messages ..............................................................................................11 3.1.1 Example of a SOAP Request .....................................................................................13 3.1.2 Example of a SOAP Response ..................................................................................14 3.1.3 Web Service Description Language ...........................................................................15 3.1.4 Generic parameters ...................................................................................................15

3.2 Functions - SOAP Methods and Parameters................................................................16 3.2.1 Change PIN................................................................................................................16

3.2.1.1 Change PIN Request...........................................................................................16 3.2.1.2 Change PIN Response ........................................................................................17

3.2.2 Change Password......................................................................................................18 3.2.2.1 Change Password Request .................................................................................18 3.2.2.2 Change Password Response ..............................................................................19

3.2.3 Execute Macro ...........................................................................................................20 3.2.3.1 Execute Macro Request ......................................................................................21 3.2.3.2 Execute Macro Response....................................................................................22

3.2.4 Execute Report ..........................................................................................................23 3.2.4.1 Specific Report Parameters.................................................................................25 3.2.4.2 Execute Report Request......................................................................................31 3.2.4.3 Execute Report Response...................................................................................33

3.2.5 Get RTS .....................................................................................................................36 3.2.5.1 Get RTS Request ................................................................................................37 3.2.5.2 Get RTS Response..............................................................................................37

3.2.6 Get SDR.....................................................................................................................40 3.2.6.1 Get SDR Request ................................................................................................42 3.2.6.2 Get SDR Response .............................................................................................42

3.2.7 Get SDW....................................................................................................................45


Page 4 of 109

3.2.7.1 Get SDW Request ...............................................................................................47 3.2.7.2 Get SDW Response ............................................................................................47

3.2.8 Get SDW Summary....................................................................................................50 3.2.8.1 Get SDW Summary Request...............................................................................51 3.2.8.2 Get SDW Summary Response ............................................................................52

3.2.9 Get VDC Sessions SIX...............................................................................................54 3.2.9.1 Get VDC Sessions SIX Request..........................................................................56 3.2.9.2 Get VDC Sessions SIX Response.......................................................................57

3.2.10 Get VDC Session Details SIX ..................................................................................61 3.2.10.1 Get VDC Session Details SIX Request..............................................................61 3.2.10.2 Get VDC Session Details SIX Response...........................................................61

3.2.11 Get VDC Sessions SDR...........................................................................................65 3.2.11.1 Get VDC Sessions SDR Request ......................................................................67 3.2.11.2 Get VDC Sessions SDR Response ...................................................................68

3.2.12 Get VDC Session Details SDR.................................................................................72 3.2.12.1 Get VDC Session Details SDR Request............................................................72 3.2.12.2 Get VDC Session Details SDR Response .........................................................72

3.2.13 Get SIV Mappings ....................................................................................................77 3.2.13.1 Get SIV Mappings Request ...............................................................................77 3.2.13.2 Get SIV Mappings Response ............................................................................78

3.2.14 Get SIX Watermark ..................................................................................................81 3.2.14.1 Get SIX Watermark Request .............................................................................81 3.2.14.2 Get SIX Watermark Response ..........................................................................82

3.2.15 Get SDR Watermark ................................................................................................83 3.2.15.1 Get SDR Watermark Request ...........................................................................84 3.2.15.2 Get SDR Watermark Response.........................................................................84

3.2.16 Get Service Var........................................................................................................86 3.2.16.1 Get Service Var Request ...................................................................................86 3.2.16.2 Get Service Var Response ................................................................................86

3.2.17 Set Service Var ........................................................................................................87 3.2.17.1 Set Service Var Request ...................................................................................89 3.2.17.2 Set Service Var Response.................................................................................90

3.2.18 Get Services.............................................................................................................91 3.2.18.1 Get Services Request........................................................................................91 3.2.18.2 Get Services Response .....................................................................................91

3.2.19 RTS Counters ..........................................................................................................94 3.2.19.1 RTS Counters Request......................................................................................95 3.2.19.2 RTS Counters Response...................................................................................96

3.3 Schemas & Regions .......................................................................................................97 3.3.1 Regional Schemas .....................................................................................................97 3.3.2 Schemas and their Associated Regions.....................................................................98

4 LOAD CONTROLS..........................................................................................100


Page 5 of 109

4.1 Load Control Limits......................................................................................................100 4.2 Report Restrictions ......................................................................................................101 4.3 Performance optimisation............................................................................................101

5 SERVICE VARIABLES ...................................................................................102

6 Application considerations...........................................................................102

6.1 Good practice................................................................................................................102 7 ERROR CODES ..............................................................................................103

7.1 Soap Fault .....................................................................................................................103 7.1.1 Fault Element Contents............................................................................................104

7.2 Status Codes.................................................................................................................105 7.3 Fault diagnostic best practice .....................................................................................108

8 SOAP related sources of information ..........................................................109

9 ABBREVIATIONS ...........................................................................................109


Page 6 of 109

1 INTRODUCTION

1.1 Purpose This document contains the high level specification required to design and build a SOAP interface for the BT Recorded Information Distribution Equipment (RIDE) platform and its purpose is to provide sufficient information for application developers to build their own client. This facility was originally delivered as the DARWIN interface: Direct Access RIDE Web Interaction Navigator. Improved to conform to SOAP standards, the interface offers the ability to provide machine level access to the following data without the need to establish a full web session:

• Real Time Statistics (RTS).

• Statistics Data Warehouse (SDW) for CDR and SDR.

• Service Management Unit (SMU) reports.

• Change and view service variables

• Execute Macros

1.2 Scope This document is limited to the specification of the external web interface requests, detailing both the structure of the parameters and the format of the returned data. The detailed design of the database procedures to deliver this functionality is outside the scope of this document.


Page 7 of 109

1.3 Security Any client software developed to communicate with the RIDE platform using the SOAP interface must support HTTP over SSL (HTTPS). Unencrypted HTTP connections are prevented from accessing the platform.

Whilst user names and passwords sent to the RIDE platform are encrypted using SSL Certificates, any developer or end user writing their own client software should ensure that such information is not stored within their client software, associated configuration files or sent in plain text across a Local or Public Network.

The following security is applied to protect your services and data from unauthorised access. Do not attempt to compromise these arrangements – they are applied for your benefit.

• Any service will be provided with one User ID and password combination.

• Every call via SOAP must include a valid User ID and password combination which has been pre-configured for this purpose.

• Attempts to hack into the interface will be presented with error code 100 and will not provide any further clue as to the details of the error.

• All passwords are automatically expired after 30 days, after which they must be changed to a new and different password combination.

• During software upgrades and other periodic maintenance, the SOAP interface may be made unavailable in a similar way to the regular web interface. This is to ensure the upgrade process is not delayed or corrupted by demands for service.

• All use of the SOAP interface is logged automatically.


Page 8 of 109

1.4 How to Read this Document The design of this guide is represented through the following chapters:

Introduction to SOAP. This section provides an introduction to SOAP.

SOAP Architecture. This section provides a high level overview of the SOAP architecture.

Soap Interface Functionality. This section describes Request messages and the methods used therein to return Response messages.

Load Controls. This section describes the load controls that have been implemented.

Error Codes. This section provides information on the error and status codes are returned.

Abbreviations. This section provides a description of the abbreviations used in this manual

1.5 Related Documentation 1.5.1 System Specific Documents The RIDE Web Interface Service Provider User Guide for general explanation of how to use and manage RIDE services.

A range of user guides describe the additional specific details required to use each product on the RIDE platform and also explains the content of all reports available for each product e.g.:

• Televote Service Provider User Guide

• FIVA Service Provider User Guide

• CAD Service Provider User Guide

1.6 Document Conventions This document uses several conventions to facilitate recognition of instructions.

See RIDE Web Interface Service Providers guide: 1.3 Document Conventions.

1.7 Where to find the latest version of this guide www.bt.com/uk/RIDESPUG

http://www.bt.com/uk/RIDESPUG


Page 9 of 109

2 INTRODUCTION TO RIDE SOAP This document explains the use of the SOAP functions. It does not explain the content or meaning of the reports obtained. These explanations are included in the RIDE and various product User Guides listed in Related Documentation.

2.1 What is SOAP A number of SOAP functions are available from the RIDE platform, which allows users to perform operations against the platform using their own client applications rather than through the normal web interface.

SOAP is a standard protocol that is managed by the WC3 standards organisation. To use the SOAP interface users will need to send XML formatted messages to the platform using an encrypted SSL link over HTTP (i.e. HTTPS). The platform will return a response message which will also be XML encoded.

2.2 Web Services & WSDL A Web Service Description Language (WSDL) file is available for the SOAP interface, this file contains schema information that describes all related SOAP methods available from the platform and the format of associated Request and Response messages.

Some tool kits allow you to generate code from a WSDL file. The WSDL file is available on-line from the web service at the following address:

https://[DARWIN URL address]/DarwinV1/Darwin.asmx?WSDL


Page 10 of 109

2.3 SOAP Tool Kits There are a number of libraries and tools available that have implementations of the SOAP standard, these may be used when writing a client to avoid implementing the SOAP protocol yourself. A short list of some of the main tool kits available are shown below:

• NET Framework

• Apache Axis for Java (Apache Project)

• SOAP:Lite for Perl

• Apache SOAP

• EasySOAP++

2.4 Interoperability Because of limitations in certain languages and also different interpretations of the SOAP standard, there are some Interoperability issues between the SOAP tool kits. This section lists some of the known issues:

• The Axis tool kit for Java does have some interoperability issues with .NET but these do not appear to present a problem for our test applications.

• When implementing Clients using SOAP:Lite for perl the following interoperability issues require additional work by the Perl developer:

• Must set a value for the action/SOAPAction item in the HTTP header

• Must define type, name and URI for all parameters

• Some SOAP tool kits may not support SSL (HTTPS)

• The RIDE platform SOAP interface has been built using the Microsoft .NET Framework, therefore .NET client applications will provide the best level of compatibility.

Other interoperability issues may be found when trying to implement clients using other SOAP Tool Kits.


Page 11 of 109

3 SOAP INTERFACE FUNCTIONALITY

3.1 SOAP Request Messages Because the RIDE platform uses HTTP as its transport for SOAP messages, any SOAP messages sent to/from the platform will also contain a HTTP header at the start of the message.

In addition to the standard HTTP header items, SOAP Request Messages shall also contain an action item (or SOAP Action for SOAP 1.1). This item is automatically included when developing clients using the .NET Framework but for other SOAP Implementations/tool kits you may need to add this when writing client applications using other tool kits as they may not automatically include the header.

action=“urn:darwin.disp/GetServices”

Action item Method name

Urn address

An example of the HTTP header is illustrated in Fig. 3.1.


Page 12 of 109

POST /DarwinV1/Darwin.asmx HTTP/1.1 User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; MS Web Services Client Protocol 2.0.50727.42) Content-Type: application/soap+xml; charset=utf-8; action=“urn:darwin.disp/GetServices” Host: [machine name]:8080 Content-Length: 419

Fig. 3.1 HTTP Header

Following the HTTP header the SOAP protocol requires the following elements to make up the SOAP message:

Fig. 3.2 SOAP method Elements


Page 13 of 109

3.1.1 Example of a SOAP Request This example shows the SOAP envelope and the SOAP body which is embedded in it. All later examples illustrated in this document will only show the contents within the SOAP body i.e. the SOAP method e.g.GetServiceVar

<?xml version=“1.0” encoding=“utf-8”?> <soap12:Envelope xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:soap12=“http://www.w3.org/2003/05/soap-envelope”> <soap12:Body> <GetSDW xmlns=“urn:darwin.disp”> <OutputType>X</OutputType> <UserID>SMAMArk</UserID> <Password>england06&</Password> <LangID>eng</LangID> <DateFormat>L</DateFormat> <ColumnList></ColumnList> <ServiceID>00028527</ServiceID> <BookMark>0</BookMark> <SchemaName></SchemaName> <BatchSize>100</BatchSize> </GetSDW> </soap12:Body> </soap12:Envelope>

Fig. 3.3 Example SOAP request

Output requested in this example is XML, as derived by the XML element <OutputType>X</OutputType>, and this is indicated in the Response message by the XML Element <xml_enc> </xml_enc>.

If TSV is selected, then the output has the <tsv_data> </tsv_data> element in the Response

http://www.w3.org/2001/XMLSchema-instance

http://www.w3.org/2001/XMLSchema


Page 14 of 109

3.1.2 Example of a SOAP Response

<?xml version=“1.0” encoding=“utf-8”?> <soap12:Envelope xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance“ xmlns:xsd=“http://www.w3.org/2001/XMLSchema” xmlns:soap12=“http://www.w3.org/2003/05/soap-envelope”> <soap12:Body> <GetSDWResponse xmlns=“urn:darwin.disp”> <GetSDWResult> <xml_enc> <Status>00000</Status> <ServiceID>00028527</ServiceID> <ServiceName>Treasure Hunt</ServiceName> <SampleDate>2006-06-05 15:19:33</SampleDate> <CDR> <Digits>08009194159</Digits> <Alias></Alias> <Answered>2006-06-05 10:57:40 930</Answered> <Released>2006-06-05 10:58:07 170</Released> <CallerID>1756879265</CallerID> <PostCode>ME18 5</PostCode> <Region>*</Region> <HoldTime>26.24</HoldTime> <KeyPad>24</KeyPad> </CDR> <CDR> <Digits>08009194159</Digits> <Alias></Alias> <Answered>2006-06-05 10:58:18 940</Answered> <Released>2006-06-05 10:59:04 150</Released> <CallerID>1756888265</CallerID> <PostCode>ME16 3</PostCode> <Region>*</Region> <HoldTime>45.21</HoldTime> <KeyPad>27</KeyPad> </CDR> <BookMark>0606051059041502922683211100541065218R</BookMark> <HiWaterMark>2006-06-05 15:15:00</HiWaterMark> </xml_enc> </GetSDWResult> </GetSDWResponse> </soap12:Body> </soap12:Envelope>

http://www.w3.org/2001/XMLSchema-instance


Page 15 of 109

Fig 3.4: SOAP response example

3.1.3 Web Service Description Language The interface is described by the WSDL file which gives exact details on how to format all message requests. Full details of the XML tag names are available via the WSDL page at the following address:

https://[DARWIN URL address]/DarwinV1/Darwin.asmx?WSDL

3.1.4 Generic parameters When executing SOAP Web Methods the body part of the XML message contains an xml element representing the method call and a number of sub elements representing parameters for the method. Table 3.1 below provides a list of parameters that apply to all web requests, additional parameters specific to the web method being called will be shown in later sections in this document.

Parameter Values

<OutputType> X (for XML output) T (for Tab Separated Value output)

<UserID> Platform User Name e.g. SMAMark

<Password> Platform Login Password e.g. england06&

<LangID> This is always ‘eng’ (English)

Table 3.1: Generic parameters


Page 16 of 109

3.2 Functions - SOAP Methods and Parameters 3.2.1 Change PIN The ChangePIN method is used to change a user’s PIN (referred to on the web interface as the password prompt).

ChangePIN Request Parameters

Parameter Value

All Generic parameters followed by:

<OldPIN> Current user PIN (password prompt)

<NewPIN> New user PIN (password prompt)

Table 3.2: ChangePIN Request Parameters

3.2.1.1 Change PIN Request The Request will replace the user’s prompt from blackbird to songthrush.

<ChangePIN xmlns=“urn:darwin.disp”> <OutputType>X</OutputType> <UserID>SMAMark</UserID> <Password>england26&</Password> <LangID>eng</LangID> <OldPIN>blackbird</OldPIN> <NewPIN>songthrush</NewPIN> </ChangePIN>

Fig. 3.5 Change PIN Request


Page 17 of 109

3.2.1.2 Change PIN Response XML Output

The Response simply provides an indication (by means of the ’Status Codes’). In this case the request was successful.

<ChangePINResponse xmlns=“urn:darwin.disp”> <ChangePINResult> <xml_enc> <Status>000000</Status> </xml_enc> </ChangePINResult> </ChangePINResponse>

Fig. 3.6 ChangePIN Response - XML Output example

TSV Output

In addition to the Status Code, the TSV Response also provides a brief description.

<ChangePINResponse xmlns=“urn:darwin.disp”> <ChangePINResult > <tsv_data> <string>PIN successfully changed</string> <string>00000</string> </tsv_data> </ChangePINResult> </ChangePINResponse>

Fig. 3.7 ChangePIN Response - TSV Output example

Note: The TSV output differs from the XML output in that a message string is included indicating if the operation was successful or not.


Page 18 of 109

3.2.2 Change Password The ChangePWD method is used to change a user’s password.

ChangePWD Request Parameters

Parameter Value


<PIN> Current user PIN (password prompt)

<NewPassword> New user password

Table 3.3 ChangePWD Request Parameters

3.2.2.1 Change Password Request This Request allows the user to change their password, but as a matter of security they must also provide their PIN (prompt).

<ChangePWD xmlns=“urn:darwin.disp”> <OutputType>X</OutputType> <UserID>SMAMark</UserID> <Password>england26&</Password> <LangID>eng</LangID> <PIN>songthrush</PIN> <NewPassword>marlins58$</NewPassword> </ChangePWD>

Fig. 3.8 ChangePWD Request


Page 19 of 109

3.2.2.2 Change Password Response XML Output


<ChangePasswordResponse xmlns=“urn:darwin.disp”> <ChangePasswordResult> <xml_enc> <Status>000000</Status> </xml_enc> </ChangePasswordResult> </ChangePasswordResponse>

Fig. 3.9 ChangePWD Response - XML output example

TSV Output


<ChangePasswordResponse xmlns=“urn:darwin.disp”> <ChangePasswordResult> <tsv_data> <string>Password successfully changed</string> <string>00000</string> </tsv_data> </ChangePasswordResult> </ChangePasswordResponse>

Fig. 3.10 ChangePWD Response - TSV output example

Note: The TSV output differs from the XML output in that a message string is included indicating if the operation was successful or not.


Page 20 of 109

3.2.3 Execute Macro The macros that are used in the ExecuteMacro method perform the same operations as the macros on the Shortcuts tab on the service administration tabbed display page of the RIDE Web Interface.

As with the macros in the RIDE Web Interface the Macros listed in Table 3.4 can only be used for specific services and executed by certain user types.

Televote and FIVA Macros

Televote and FIVA Macros

VOTESTART Start the vote

VOTESTOP Stop the vote

VOTEREOPEN Re-open the vote.

VOTEPRESTART Pre-start the vote.

FIVA simple synchronisation Macros

FSYNCHCONTROLCALLERS New caller control.

FSYNCHEVENTPROGRESS Event progress

FSYNCHJUMPTO Jump now

Table 3.4 Available Macros

These Macros are applicable to both Televote and FIVA services, but a FIVA service accessed via the web interface uses the term EVENT rather than VOTE.

Table 3.5 defines the parameters that are required to run each of the macros:


Page 21 of 109

Execute Macro Request Parameters

Parameter Description


<DateFormat> L (Local Time), G (GMT)

<MacroName> See Table 3.4 for a list of available macros.

<ServiceID> The Service ID e.g. 00028527

<Param1> Where required for the following Macros

FSYNCHCONTROLCALLERS 1 (Reject new callers) 0 (Allow new callers)

FSYNCHEVENTPROGRESS

0 (No hold) – Note: Only if no other options are available. 1 or Gate control caption (Hold at gate1) 2 or Gate control caption (Hold at gate 2) etc up to 32. 99 or Gate control caption (Hold at end node).

FSYNCHJUMPTO

1 or Gate control caption 2 or Gate control caption 3 or Gate control caption etc up to 32 99 or Gate control caption. Note: the event will jump to and run free from the specified gate onwards.

Table 3.5 Execute Macro Request Parameters

Note: FSYNCHJUMPTO is conditional and will only be available if the controlling variables have been enabled. Please consult your BT Administrator for further information.

3.2.3.1 Execute Macro Request The VOTESTART macro will start the event for the specified FIVA service.

<ExecuteMacro xmlns=“urn:darwin.disp”> <OutputType>X</OutputType> <UserID>SMAMark</UserID> <Password>england26&</Password>


Page 22 of 109

<LangID>eng</LangID> <DateFormat>L</DateFormat> <MacroName>VOTESTART</MacroName> <ServiceID>00028527</ServiceID> </ExecuteMacro>

Fig. 3.11 Execute Macro Request

3.2.3.2 Execute Macro Response XML Output

The status code of zero shown below, indicates a successful transaction.

<ExecuteMacroResponse xmlns=“urn:darwin.disp”> <ExecuteMacroResult> <xml_enc> <Status>000000</Status> </xml_enc> </ExecuteMacroResult> </ExecuteMacroResponse>

Fig. 3.12 Execute Macro Response (VOTESTOP) - XML output example

TSV Output


<ExecuteMacroResponse xmlns=“urn:darwin.disp”> <ExecuteMacroResult> <tsv_data> <string>Macro Execution successful</string> <string>00000</string> </tsv_data> </ExecuteMacroResult> </ExecuteMacroResponse>

Fig. 3.13 Execute Macro Response (VOTESTOP) - TSV output example


Page 23 of 109

3.2.4 Execute Report The ExecuteReport method is used to generate reports. The reports that are available on the system via SOAP interface are listed in Table 3.6.

Available Reports

Report Name Description

CLS Call Count to a Service

BPTR Traffic Analysis Busy Period Traffic

CLHLDT Call Hold Time for a Service

CLDTMF Televote DTMF Vote Count

SDRFLT FIVA Filtered SDR Data Dump

NACCLI Call Interrogation by Service ID

SRVRDD Service Type variable configuration report

CUSSUTL Session Capacity - Utilisation by Service

Table 3.6 Available Reports

The content of the output is explained in the appropriate Service Provider User Guide. See Related Documentation.

The main parameters required to run these reports are provided in Table 3.7:


Page 24 of 109

Execute Report Request - Main Parameters

Parameter Type Value


<DateFormat> String L (Local Time), G (GMT)

<ReportName> String Report Name. See Table 3.6.

<MaxResults> String Maximum number of data rows to return in report – MUST ALWAYS BE POPULATED WITH APPROPRIATE VALUES - NOT LEFT BLANK. (See “Specific Report Parameters” for details).

<PostNode> Integer 0 (No Regional Breakdown) 2 (Regions determined by CLI)

<RegSchema> String

<RegionID> String

See Table 3.32 and Table 3.33 for available Regional Schemas. MUST ALWAYS BE POPULATED WITH APPROPRIATE VALUES - NOT LEFT BLANK

<Parameter1> through to<Parameter12>

String See “Specific Report Parameters”.

Table 3.7 Execute Report Request - Main Parameters


Page 25 of 109

3.2.4.1 Specific Report Parameters Once the main parameters have been stipulated, the parameters which are specific to that report may then be specified. The number of parameters for each report varies from five to 9. These parameters and the values they should contain are provided in Table 3.8 through to Table 3.15.

CLS - Call Count to a Service

Param No Equates to Accepted Values and Format

<Parameter1> FromDate yyyy-mm-dd hh:mm:ss e.g. 2006-06-04 09:00:00 or dd mmm yyyy hh:mm:ss e.g. 04 Jun 2006 09:00:00

<Parameter2> ToDate yyyy-mm-dd hh:mm:ss e.g. 2006-06-05 17:30:00 or dd mmm yyyy hh:mm:ss e.g. 04 Jun 2006 09:00:00

<Parameter3> Granularity Can be one of the following: None, 1s, 5s, 15s, 1m, 5m, 30m, 1h, 12h, 24h, 7d

<Parameter4> ServiceID The Service ID e.g. 00028527

<Parameter5> CallType A (Answered)

Maximum Number of rows returned:

XML 1,000

TSV 5,000

See “Report Restrictions” for load weighting calculations on this report.

Table 3.8 CLS - Call Count to a Service


Page 26 of 109

CLHLDT - Call Hold Time for a Service




<Parameter3> Granularity Can be one of the following: None, 1s, 5s, 15s, 1m, 5m, 30m, 1h, 12h, 24h, 7d




XML 500

TSV 2,500


Table 3.9 CLS - Call Hold Time for a Service


Page 27 of 109

BPTR - Traffic Analysis Busy Period Traffic




<Parameter3> Service ID The Service ID e.g. 00028527


<Parameter5> CalcMethod S (Simple), C (Accumulation)


XML 500

TSV 2,500


Table 3.10 BPTR - Traffic Analysis Busy Period Traffic


Page 28 of 109

CLDTMF - Televote DTMF Vote Count





<Parameter4> SortFlag O (DDI) 1 (Call Count)

<Parameter5> CallType A (Answered),

Maximum Number of rows returned: No limitation

Table 3.11 CLDTMF - Televote DTMF Vote Count


Page 29 of 109

SDRFLT - SDR Filter Data Dump





<Parameter4> FilterBy Session Index Variable (SIV) value to use e.g. 1-8

<Parameter5> MinimumValue Any Integer. The value is dependent on the minimum value held in the SIV.

<Parameter6> MaximumValue Any Integer. The value is dependent on the maximum value held in the SIV.

<Parameter7> PrimarySortKey SIV value to use e.g. 1-8

<Parameter8> SecondarySortKey SIV value to use e.g. 1-8

<Parameter9> RowsReturned The number of rows to be returned.


XML 150

TSV 750


Table 3.12 SDRFLT - SDR Filter Data Dump


Page 30 of 109

NACCLI - Call Interrogation by CLI





<Parameter4> Calling Number Whole number or partial number.

<Parameter5> Report Type D (Detailed), S (Summary)


Table 3.13 NACCLI - Call Interrogation by CLI

SRVRDD - Service Type Variable Configuration



<Parameter2> ReportType May be either: 1 (All Variables) 2 (Enabled Nodes) 3 (Changed Variables)


Table 3.14 SRVRDD - Service Type Variable Configuration


Page 31 of 109

CUSSUTL - Current Utilisation By Service



<Parameter2> ServiceType ALLSTYPE (All Service Types) or ALLFIVA (FIVA services only) 00000031 (FIVA without Call Dist only) 00000033 (FIVA debug without Call Dist only)

<Parameter3> ReportType Sort order may be either: S (by Service), T (by Service Type) T

<Parameter4> System parameter 0 – in all cases.

Max number of rows returned: No limitation

Table 3.15 CUSSUTL - Current Utilisation by Service

3.2.4.2 Execute Report Request The example provided below is a request for the CLS report:

To include Regional Schemas in the report the <PostNode> element must be set to ‘2’.

The Schema, COUNTRIES, has been specified in the <RegSchema>.

This has been further broken down to return call data for a particular Region by specifying England in the <RegionID> element.

<Parameter1> and <Parameter2> define the date/time range.

<Parameter3> defines the granularity, in this case 12 hours.

<Parameter4> defines the Service ID.

<Parameter5> reports on All Calls made to the service.

<ExecuteReport xmlns=“urn:darwin.disp”> <OutputType>X</OutputType>


Page 32 of 109

<UserID>SMAMark</UserID> <Password>england26&</Password> <LangID>eng</LangID> <DateFormat>L</DateFormat> <ReportName>CLS</ReportName> <MaxResults>1000</MaxResults> <PostNode>2</PostNode> <RegSchema>COUNTRIES</RegSchema> <RegionID>England</RegionID> <Parameter1>04-Jun-2006 09:00:00</Parameter1> <Parameter2>05-Jun-2006 17:00:00</Parameter2> <Parameter3>12h</Parameter3> <Parameter4>00028527</Parameter4> <Parameter5>B</Parameter5> </ExecuteReport>

Fig. 3.14 Execute Report Request


Page 33 of 109

3.2.4.3 Execute Report Response XML Output

The Response provides the Service Name <ServiceName> and includes the Report Title <Title>. The <HEADINGS> element defines the heading that will be displayed in Columns 1 and 2.The Regional information appears within the <SECTION> element. The call information relating to the date of the call, the requested granularity and the number of calls made to the service within the requested time range is displayed in the <DATA> element.


Page 34 of 109

<ExecuteReportResponse xmlns=“urn:darwin.disp”> <ExecuteReportResult> <xml_enc> <ReportName>CLS</ReportName> <Status>00000</Status> <ServiceID>28527</ServiceID> <ServiceName>Treasure Hunt</ServiceName> <SampleDate>2006-06-06 09:23:15</SampleDate> <ReportData> <Title>Call - Count to the Treasure Hunt Service</Title> <HEADINGS> <col_1>Date/Time</col_1> <col_2>Number of Calls</col_2> </HEADINGS> <SECTION name=“England”> <DATA> <col_1>04 Jun 2006 09:00:00 BST </col_1> <col_2>32</col_2> </DATA> <DATA> <col_1>04 Jun 2006 21:00:00 BST </col_1> <col_2>0</col_2> </DATA> <DATA> <col_1>05 Jun 2006 09:00:00 BST </col_1> <col_2>43</col_2> </DATA> </SECTION> <FinalData>Total Calls</FinalData> </ReportData> </xml_enc> </ExecuteReportResult> </ExecuteReportResponse>

Fig. 3.15 Execute Report Response (CLS) - XML output example


Page 35 of 109

TSV Output

<ExecuteReportResponse xmlns=“urn:darwin.disp”> <ExecuteReportResult> <tsv_data> <string>Date/Time Number of Calls Region</string> <string>04 Jun 2006 09:00:00 BST 32 England</string> <string>04 Jun 2006 21:00:00 BST 0 England</string> <string>05 Jun 2006 09:00:00 BST 43 England</string> </tsv_data> </ExecuteReportResult> </ExecuteReportResponse>

Fig. 3.16 Execute Report Response (CLS) - TSV output example

Note: Column heading have been highlighted in black font for reasons of clarity.


Page 36 of 109

3.2.5 Get RTS The GetRTS method is used to retrieve Real Time Statistics for a specified service.

GetRTS Request Parameters

Parameter Value




<BreakdownIndicator> D (Separate Totals for all DDIs) T (Single Total for all DDIs on the service) T

<RegionalSchemaName>

<RegionName>

See Table 3.32 and Table 3.33 for available Regional Schemas or if not required leave blank.

<SortColumn> Defines which column to use when sorting output data: 0 (DDI) default 1 (Alias) 2 (Region) 3 (Calls since Last Reset) 4 (Calls Today) 5 (Total Calls) 6 (Calls Before Last Reset)

Table 3.16. GetRTS Request Parameters

Remember that the regional schemas Counties73 and Fixed vs.Mobile are not available for RTS. This is true for regular web access and the SOAP interface.


Page 37 of 109

3.2.5.1 Get RTS Request The Request below will return Real Time Statistics for the requested service and will provide the total number of calls made to the service DDI and sort them by calls received today.

<GetRTS xmlns=“urn:darwin.disp”> <OutputType>X</OutputType> <UserID>SMAMark</UserID> <Password>england26&</Password> <LangID>eng</LangID> <DateFormat>L</DateFormat> <ServiceID>00028527</ServiceID> <BreakdownIndicator>T</BreakdownIndicator> <RegionalSchemaName>NONE</RegionalSchemaName> <RegionName> </RegionName> <SortColumn>4</SortColumn> </GetRTS>

Fig. 3.17 GetRTS Request

3.2.5.2 Get RTS Response XML output

The Response returns the <ServiceName> along with the status of the service (FIVA or Televote) <VoteStatus>. Each DDI (this service has only one, hence the * in the <Digits> element and subsequently why there is also a * in the <Alias> element) provides the statistics for each of the Regions (not selected in this instance). Within each <Region> element the statistics are returned within the following sub elements:

<CBLR> Calls Before Last Reset.

<CSLR> Calls Since Last Reset.

<CToday> Calls Today.

<TotCalls> Total Calls.


Page 38 of 109

<GetRTSResponse xmlns=“urn:darwin.disp”> <GetRTSResult> <xml_enc> <Status>00000</Status> <ServiceID>00028527</ServiceID> <ServiceName>Treasure Hunt</ServiceName> <SampleDate>2006-06-06 15:48:00</SampleDate> <VoteStatus>Running</VoteStatus> <DDIS> <DDI> <Digits>*</Digits> <Alias>*</Alias> <Regions> <Region Description=“*”> <CBLR>0</CBLR> <CSLR>24</CSLR> <CToday>24</CToday> <TotCalls>24</TotCalls> </Region> </Regions> </DDI> </DDIS> </xml_enc> </GetRTSResult> </GetRTSResponse>

Fig. 3.18 GetRTS Response - XML Output example


Page 39 of 109

TSV output

<GetRTSResponse xmlns=“urn:darwin.disp”> <GetRTSResult> <tsv_data> <string>00000 Real Time Statistics</string> <string>Service ID: 00028527</string> <string>Service Name: Treasure Hunt</string> <string>2006-06-06 15:02:08</string> <string>Vote Status: Running</string> <string>DDI Alias Region Calls Before Last Reset Calls Since Last Reset <string> * * * 0 24 </tsv_data> </GetRTSResult> </GetRTSResponse>

Fig. 3.19 GetRTS Response - TSV Output example


Page 40 of 109

3.2.6 Get SDR The GetSDR method retrieves Session Data Records (SDRs) data from the Statistics Data Warehouse.

GetSDR Request Parameters

Parameter Value



<OutputColumns> If no output columns are stipulated, then all data for the column headings below will be returned. It is possible to randomly select any number of output columns listed in Table 3.18:


<Bookmark> -1 (All records) 0 (All records today, or use the bookmark value returned from the previous GetSDR call if you are receiving large amounts of data.)

<Batchsize> Maximum number of SDRs to be returned in the output.

The maximum Batchsize for XML output is 1,000 records.

The maximum Batchsize allowed for TSV output is 200,000 records.

Table 3.17: GetSDR Request Parameters


Page 41 of 109

GetSDR Parameter - OutputColumns

Sub Elements Information Returned

<CallStartTime/> The date/time the call started.

<FinalDTMFString/> Last DTMF string entered by the caller.

<SIV1/> -<SIV8/> The values configured to be held in the Session Index Variables.

<OnwardRoutedNumber/> The DDI the call was routed to.

<OnwardRouteResult/>

<CombinedTraceAudit/>

Indicates if onward route was Successful or Unsuccessful. Trace audit for actions taken in Function Nodes.

<ExitCondition/> 0 (Invalid), 1 (Caller Hangup), 2 (Normal), 3 (Data Call), 4 (Service inactive), 5 (CUG login denied), 6 (Service disabled), 7 (Outside event time), 8 (max DTMF attempts), 9 (timeout), 10 (error), 11 (Soft limit breach), 12 (Hard limit breach)

<FullDTMFString/> The total of all DTMF string entries.

<CUGDigitsReported/> Indicates if Closed User Group PIN was entered.

<AbortReason> Normal etc.

Table 3.18 GetSDR Parameter - OutputColumns


Page 42 of 109

3.2.6.1 Get SDR Request The example illustrated in Fig. 3.20, shows SDR data being retrieved for a FIVA Treasure Hunt service. For the sake of simplicity only three sessions have been requested (<BatchSize>). The caller will have a picture of the map in a magazine or newspaper, or more likely, will be viewing the map on a television screen. The service requests the caller to enter a two digit map coordinate where they think the treasure is located. The caller that enters the correct location is prompted to leave their name and address to be eligible for a cash prize. The DTMF input entered for the map coordinates is stored in SIV1; SIV2 stores the response time to enter the map coordinates; SIV4 stores an indicator if the caller left recorded audio (0 for no audio, 1 for audio).

<GetSDR xmlns=“urn:darwin.disp”> <OutputType>X</OutputType> <UserID>SMAMark</UserID> <Password>england26&</Password> <LangID>eng</LangID> <DateFormat>L</DateFormat> <OutputColumns><CallStartTime/><SIV1/><SIV2/><SIV4/><CLI/></OutputColumns> <ServiceID>00028257</ServiceID> <Bookmark>0</Bookmark> <BatchSize>3</BatchSize> </GetSDR>

Fig. 3.20 GetSDR Request

3.2.6.2 Get SDR Response XML output

The Response returns the <ServiceName> along with the time the request was initiated (<SampleDate>). The SDR information reflects the information specified in the Request parameters. The <Bookmark> element is used to hold the bookmark value returned from the previous GetSDR call if you are receiving large amounts of data. The indexing <HighWaterMark> is also displayed.


Page 43 of 109

<GetSDRResponse xmlns=“urn:darwin.disp”> <GetSDRResult> <xml_enc> <Status>00000</Status> <ServiceID>00028527</ServiceID> <ServiceName>Treasure Hunt</ServiceName> <SampleDate>2006-06-06 15:20:00</SampleDate> <SDRs> <SDR> <CallStartTime>06 Jun 2006 15:13:58:000 </CallStartTime> <SIV1>25</SIV1> <SIV2>3295</SIV2> <SIV4>0</SIV7> <CLI>1732879674</CLI> </SDR> <SDR> <CallStartTime>06 Jun 2006 15:14:21:000 </CallStartTime> <SIV1>22</SIV1> <SIV2>2333</SIV2> <SIV4>0</SIV7> <CLI>1634844896</CLI> </SDR> <SDR> <CallStartTime>06 Jun 2006 15:14:41:000 </CallStartTime> <SIV1>27</SIV1> <SIV2>2734</SIV2> <SIV4>1</SIV7> <CLI>1233566221</CLI> </SDR> </SDRs> <BookMark>123391627</BookMark> <HighWaterMark>2006-06-06 17:00:00</HighWaterMark> </xml_enc> </GetSDRResult> </GetSDRResponse>

Fig. 3.21 GetSDR Response - XML Output example


Page 44 of 109

TSV output

<GetSDRResponse xmlns=“urn:darwin.disp”> <GetSDRResult> <tsv_data> <string>Call Start SIV1 SIV2 SIV4 CLI</string> <string>06 Jun 2006 15:13:58:000 25 3295 0 1732879674</string> <string>06 Jun 2006 15:14:21:000 22 2333 0 1634844896</string> <string>06 Jun 2006 15:14:41:000 27 2734 1 1233566221</string> <string>Bookmark 123391627</string> <string>High Water Mark 2006-06-06 17:00:00</string> </tsv_data> </GetSDRResult> </GetSDRResponse>

Fig. 3.22 GetSDR Response - TSV Output example

Note: Column heading have been highlighted in black font for reasons of clarity.


Page 45 of 109

3.2.7 Get SDW This GetSDW method retrieves detailed statistical information from the Statistics Data Warehouse.

GetSDW Request Parameters

Parameter Value



<ColumnList> If no output columns are stipulated, then all data for the column headings below will be returned. It is possible to randomly select any number of output columns listed in Table 3.20:


<Bookmark> -1 = All records 0 = All records today, or use the bookmark value returned from the previous GetSDR call if you are receiving large amounts of data.

<SchemaName> See Table 3.26 and Table 3.27 for available Regional Schemas or if not required leave blank.

<Batchsize> Maximum number of SDRs to be returned.

Table 3.19 GetSDW Request Parameters


Page 46 of 109

GetSDW Parameter - ColumnLists

Sub Elements Information Returned

<Digits/> The DDI of the service

<Alias/> The DDI alias used in Televote competitions

<Answered/> The Date/Time stamp the call was answered e.g. dd mmm yyyy hh:mm:ss:mss or dd mmm yyyy hh:mm:ss

<Released/> The Date/Time stamp the call was released e.g dd mmm yyyy hh:mm:ss:mss or dd mmm yyyy hh:mm:ss

<CallerID/> The caller’s CLI

<PostCode/> The Post Code associated with the CLI.

<Region/> See Table 3.26 and Table 3.27 for available Regional Schemas or if not required leave blank.

<HoldTime/> The duration of the call.

<Keypad/> Any DTMF input entered by the caller.

Table 3.20 GetSDW Parameter - ColumnLists


Page 47 of 109

3.2.7.1 Get SDW Request In this example of the Request, the <ColumnLists> element has been left empty. This has the effect of requesting (and including in the response) all <ColumnList> entries described in Table 3.20. Only 2 sessions have been requested (<BatchSize>).

<GetSDW xmlns=“urn:darwin.disp”> <OutputType>X</OutputType> <UserID>SMAMark</UserID> <Password>england26&</Password> <LangID>eng</LangID> <DateFormat>L</DateFormat> <ColumnList> </ColumnList> <ServiceID>00028527</ServiceID> <Bookmark>0</Bookmark> <SchemaName> </SchemaName> <BatchSize>2</BatchSize> </GetSDW>

Fig. 3.23 GetSDW Request

3.2.7.2 Get SDW Response XML output

The Response returns the <ServiceName> along with the time the request was initiated (<SampleDate>). In this example, the <ColumnLists> element has been left empty. This has the effect of requesting (and including in the response) all <ColumnList> entries described in Table 3.20.


Page 48 of 109

<GetSDWResponse xmlns=“urn:darwin.disp”> <GetSDWResult> <xml_enc> <Status>00000</Status> <ServiceID>00028527</ServiceID> <ServiceName>Treasure Hunt</ServiceName> <SampleDate>2006-06-07 09:16:02</SampleDate> <CDR> <Digits>08009194159</Digits> <Alias> </Alias> <Answered>2006-06-06 14:14:01.110</Answered> <Released>2006-06-06 14:14:14.600</Released> <CallerID>1732879674</CallerID> <PostCode>ME19 6</PostCode> <Region>*</Region> <HoldTime>13.49</HoldTime> <Keypad>25<Keypad> </CDR> <CDR> <Digits>08009194159</Digits> <Alias> </Alias> <Answered>2006-06-06 14:14:23.870</Answered> <Released>2006-06-06 14:14:33.400</Released> <CallerID>1634589620</CallerID> <PostCode>ME1 5</PostCode> <Region>*</Region> <HoldTime>9.53</HoldTime> <Keypad>22<Keypad> </CDR> <BookMark>0606061414546502922683211100704643075R</BookMark> <HighWaterMark>2006-06-07 09:00:00</HighWaterMark> </xml_enc> </GetSDWResult> </GetSDWResponse>

Fig. 3.24 GetSDW Response - XML Output example


Page 49 of 109

TSV output

<GetSDWResponse xmlns=“urn:darwin.disp”> <GetSDWResult> <tsv_data> <string>Digits Alias Answered Released <string>08009194159 25 2006-06-06 14:14:01 1102006-06-06 14:14:01. <string>08009194159 22 2006-06-06 14:14:23 8702006-06-06 <string>Bookmark 0606061414546502922683211100704643075R</string> <string>High Water Mark 2006-06-07 09:00:00</string> </tsv_data> </GetSDWResult> </GetSDWResponse>

Fig. 3.25 GetSDW Response - TSV Output example

Note: For reasons of clarity not all column headings have been illustrated. Again, for reasons of clarity, column headings have been highlighted in black font.


Page 50 of 109

3.2.8 Get SDW Summary The GetSDWSummary method retrieves summarized statistical information from the Statistics Data Warehouse.

GetSDWSummary Request Parameters

Parameter Value




<SchemaName> See Table 3.26 and Table 3.27 for available Regional Schemas or if not required leave blank.

Table 3.21 GetSDWSummary Request Parameters


Page 51 of 109

3.2.8.1 Get SDW Summary Request In this example, the <ColumnLists> element has been left empty. This has the effect of requesting (and including in the response) all <ColumnList> entries listed in Table 3.20. Also included in the request is the option to include a breakdown by <SchemaName>, in this case COUNTRIES.

<GetSDW xmlns=“urn:darwin.disp”> <OutputType>X</OutputType> <UserID>SMAMark</UserID> <Password>england26&</Password> <LangID>eng</LangID> <DateFormat>L</DateFormat> <ColumnList> </ColumnList> <ServiceID>00028527</ServiceID> <SchemaName>COUNTRIES</SchemaName> </GetSDW>

Fig. 3.26 GetSDWSummary Request


Page 52 of 109

3.2.8.2 Get SDW Summary Response XML output

The Response returns the <ServiceName> along with the time the request was initiated (<SampleDate>). The <DailyCount> element contains the service DDI which is held in the <Digits>sub element and the regional breakdown (<Regions>) by country and the total number of calls received for the day (<TotCalls>) for the region.

<GetSDWSummaryResponse xmlns=“urn:darwin.disp”> <GetSDWSummaryResult> <xml_enc> <Status>00000</Status> <ServiceID>00028527</ServiceID> <ServiceName>Treasure Hunt</ServiceName> <SampleDate>2006-06-07 09:16:02</SampleDate> <DailyCount> <Day>2006-06-06</Day> <DDI> <Digits>08009194159</Digits> <Alias/> <Regions> <Region Description=“England”> <TotCalls>34</TotalCalls> </Region> <Region Description=“Wales”> <TotCalls>21</TotalCalls> </Region> </Regions> </DDI> </DailyCount> </xml_enc> </GetSDWSummaryResult> </GetSDWSummaryResponse

Fig. 3.27 GetSDWSummary Response - XML Output example


Page 53 of 109

TSV output

<GetSDWSummaryResponse xmlns=“urn:darwin.disp”> <GetSDWSummaryResult> <tsv_data> <string>00000 SDW Summary </string> <string>Service ID: 00028527 Service Name: Treasure Hunt</string> <string>2006-06-07 09:16:02 </string> <string>Date DDI Alias Region CallCount </string> <string>2006-06-06 08009194159 England 34</string> <string>2006-06-06 08009194159 Wales 21</string> <string>High Water Mark 2006-06-07 09:00:00</string> </tsv_data> </GetSDWSummaryResult> </GetSDWSummaryResponse>

Fig. 3.28 GetSDWSummary Response - TSV Output example

Note: For reasons of clarity not all column headings have been illustrated. Column heading have been highlighted in black font.


Page 54 of 109

3.2.9 Get VDC Sessions SIX The GetVDCSessions_SIX method retrieves ‘live’ SDR index (SIX) information.

GetVDCSessions_SIX Request Parameters

Parameter Value




<NumSessions> The number of sessions to return. Blank will return 100, 0 will return 100, maximum = 1000, a value of more than 1000 will return 1000

<DateFrom> yyyy-mm-dd hh:mm:ss e.g. 2006-06-04 09:00:00 or yyyy-mmm-dd hh:mm:ss e.g. 2006-Jun-04 09:00:00

<DateTo> As above

<RegSchema> See Table 4.32 for Regional Schemas else leave blank.

<Region> See Table 4.33 for Regions else leave blank.

<SessionID> If returning a Collected session, enter the session Reference e.g. 321140-5713933

<SessionState> The can be one of the following: a = Any State l = Locked u = Unlocked

<SortColumn> The default column names are: Session Time, Session Ref, Caller ID and Status. Additional column headings that can be used relate to the SIV captions.

<SortOrder> The Sort Order can be either: a = Ascending


Page 55 of 109

GetVDCSessions_SIX Request Parameters

Parameter Value

d = Descending

<SIV>x 8 <Comparitor>x 8

Integer from 1 to 8 that relates to the SIV reference on the web interface. This is the operand used for comparison relating to the value below: eq = equal to ge = greater than or equal to gt = greater than lt = less than le = less than or equal to ne = not equal to dc = any value (don’t care!)

<Value> x 8 The score contained in the function node at point of capture

Table 3.22 GetVDCSessions_SIX Request Parameters


Page 56 of 109

3.2.9.1 Get VDC Sessions SIX Request The example illustrated in Fig. 3.29 shows a request for one session where:

• the value for SIV 5 is greater than or equal to 10 and

• the call originated from England.

The column sorted on is the caption for SIV 5, ‘Final Score’ in ascending order.

<GetVDCSessions_SIX xmlns="urn:darwin.disp"> <OutputType>X</OutputType> <UserID>SMAMark</UserID> <Password>england26&</Password> <LangID>eng</LangID> <DateFormat>L</DateFormat> <ServiceID>69899</ServiceID> <NumSessions>1</NumSessions> <DateFrom>2006-Aug-21 11:00:00</DateFrom> <DateTo>2006-Aug-21 12:05:00</DateTo> <RegSchema>Countries</RegSchema> <Region>England</Region> <SessionID> </SessionID> <SessionState>a</SessionState> <SortColumn>Final Score</SortColumn> <SortOrder>a</SortOrder> <SIVFilters> <SIVFilterType> <SIV>5</SIV> <Comparator>ge</Comparator> <Value>10</Value> </SIVFilterType> Note: Up to eight SIVs can be used. </SIVFilters> </GetVDCSessions_SIX>

Fig. 3.29 GetVDCSessions_SIX Request


Page 57 of 109

3.2.9.2 Get VDC Sessions SIX Response The following information is included in the response:

• The response Status e.g. “00000” (successful)

• Session selection for Service (ID)

• Session Selection Results for (date-time)

• Service ID

• Service Name

• Data Source (Live)

• Watermark (date-time stamp)

• Current Session count (the number of sessions for the service

• Matching Sessions (the number of sessions that match the requested information)

• Sessions Requested (the number of sessions requested)

• Date From. (date-time stamp)

• Date To. (date-time stamp)

• Regional Schema (optional)

• Region (optional)

• Session Status

• Filter (optional)

• Sort column (optional)

• •Headings

• Session Time

• Session Ref

• Caller ID


Page 58 of 109

• Status

• Lock

• Other optional headings. In this case Final Score.

• Data

• Data for each of the headings listed above. The Data element is repeated for each SDR record returned.

The output may be to either XML or TSV


Page 59 of 109

XML Output

<GetVDCSessionsResponse xmlns="urn:darwin.disp"> <GetVDCSessionsResult> <xml_enc> <Status>00000</Status> <ServiceID>69899</ServiceID> <ServiceName>TV Quiz</ServiceName> <Summary> <DateTime>2006-08-21 12:15:19</DateTime> <DataSource>Live</DataSource> <FromDate>2006-08-21 11:00:00</FromDate> <ToDate>2006-08-21 12:05:00</ToDate> <RegSchema>UK Countries</RegSchema> <Region>England</Region> <SessionStatus>Any State</SessionStatus> <Filters> <Filter> <Variable>Answer to Q.1</Variable> <Compare>GE</Compare> <VarValue>10</VarValue> </Filter> </Filters> <SortColumn>FINAL SCORE (ascending)</SortColumn> <Watermark>2006-08-17 13:04:08</Watermark> <CurrentSessionCount>3</CurrentSessionCount> <MatchingSessions>3</MatchingSessions> <SessionsRequested>1</SessionsRequested> </Summary> <Columns> <Heading> ... Column Headings listed here ... </Heading> </Columns> <Sessions> <Data> <SessionTime>2006-08-21 11:09:51</SessionTime> <SessionRef>321140-5713933</SessionRef> <CallerID>1733879699</CallerID> <SIV1>10</SIV1> <Status>Session collected – more than 10 seconds of audio.</Status> <LockStatus>O</LockStatus> </Data> </Sessions> </xml_enc> </GetVDCSessionsResult> </GetVDCSessionsResponse>

Fig. 3.30 GetVDCSessions_SIX Response -XML Output example


Page 60 of 109

TSV Output

This is the same query run for the XML output with the exception that three sessions have been requested and found.

<GetVDCSessionsResponse xmlns="urn:darwin.disp"> <GetVDCSessionsResult> <tsv_data> <string>[TITLE]Status:00000Session Selection</string> <string>[TITLE]Status:00000Session Selection</string> <string>[SUBTITLE]Session Selection for Service: 69899</string> <string>[PARAM]Session Selection Results at2006-08-21 12:27:41</string> <string>[PARAM]Service ID 00069899</string> <string>[PARAM]Service Name TV Quiz</string> <string>[PARAM]Data Source Live</string> <string>[PARAM]Water Mark 2006-08-17 13:04:08</string> <string>[PARAM]Current Session Count 3</string> <string>[PARAM]Matching Sessions 3</string> <string>[PARAM]Sessions Requested 3</string> <string>[PARAM]Date From2006-08-21 11:00:00</string> <string>[PARAM]Date To2006-08-21 12:05:00</string> <string>[PARAM]Regional Schema UK Countries</string> <string>[PARAM]Region England</string> <string>[PARAM]Session Status Any State</string> <string>[PARAM]Filter 1 Answer to Q.1 GE 10</string> <string>[PARAM]Sort Column FINAL SCORE (ascending)</string> <string>[HEADINGS] Session Time Session Ref Caller ID .. <string>[DATA] 2006-08-21 11:09:51 321140-5713933 1733879699 <string>[DATA] 2006-08-21 12:03:09 321142-3760296 1634876259 <string>[DATA] 2006-08-21 12:03:51 321140-5713934 1265896248 </tsv_data> </GetVDCSessionsResult> </GetVDCSessionsResponse>

Fig. 3.31 GetVDCSessions_SIX Response - TSV Output example


Page 61 of 109

3.2.10 Get VDC Session Details SIX The GetVDCSessionDetails_SIX method retrieves ‘live’ detailed SDR information for one session. The Session Reference number must be known to be able to run this query.

GetVDCSessionDetails_SIX Request Parameters

Parameter Value




<SessionRef> The session reference number you wish to return the details on using the format nnnnnn-n(up to 10 digits) e.g. 321140-5713933

Table 3.23 GetVDCSessionDetails_SIX Request Parameters

3.2.10.1 Get VDC Session Details SIX Request The example illustrated in Fig. 4.32 shows how a request for one particular session is made.

<GetVDCSessionDetails_SIX xmlns="urn:darwin.disp"> <OutputType>X</OutputType> <UserID>SMAMark</UserID> <Password>england26&</Password> <LangID>eng</LangID> <DateFormat>L</DateFormat> <ServiceID>69899</ServiceID> <SessionRef>321140-5713933</SessionRef> </GetVDCSessionDetails_SIX>

Fig. 3.32 GetVDCSessionDetails_SIX Request

3.2.10.2 Get VDC Session Details SIX Response The response returns the following details for the requested SDR:


Page 62 of 109

The Response Status e.g. “00000” (Successful)

• Service ID

• Service Name

• Session Reference

• Session Data

• Session Index flag

• Call Start Time

• Call Stop Time

• CLI of the Caller

• SIV 1 Caption and value e.g. $IDXSIV1 = “Answer to Q.1” 2

• SIV 2 Caption and value e.g. $IDXSIV2 = “Score for Q.1” 5

• SIV 3 Caption and value e.g. $IDXSIV3 = “Answer to Q.2” 3

• SIV 4 Caption and value e.g. $IDXSIV4 = “Score for Q.1” 10

• SIV 5 Caption and value e.g. $IDXSIV5 = “Final Score” 10

• SIV 6 Caption and value e.g. $IDXSIV6 = “Details Recorded?” 1

• SIV 7 Caption and value e.g. $IDXSIV7 = “Random Selection” 1240560553

• SIV 8 Caption and value (Not configured in this example). This is followed by any DTMF or voice input left by the caller. In this example:

$CDSCLO5 refers to FN-05 of the service where the caller input ‘2’ as the “Answer to Question 1:”.

$CDSCRO5 refers to the time it took to respond to the question e.g. 3.395 seconds.

$CVXCA15 refers to the audio captured and the length of the recording e.g. 10.656 seconds.

Output may be to either XML or TSV format.

XML Output

<GetVDCSessionDetailsResponse xmlns="urn:darwin.disp"> <GetVDCSessionDetailsResult> <xml_enc>


Page 63 of 109

<Status>00000</Status> <ServiceID>00069899</ServiceID> <ServiceName>TV Quiz</ServiceName> <SessionRef>321140-5713933</SessionRef> <SessionData> <Variable ID="$IDXFLGS"> <Description /> <Value>13</Value> </Variable> <Variable ID="$SRTCALL"> <Description>VDC:Call Start Time</Description> <Value>2006-08-21 11:09:51</Value> </Variable> <Variable ID="$ENDCALL"> <Description>VDC:Call Stop Time</Description> <Value>2006-08-21 11:10:18</Value> </Variable> <Variable ID="$IDXCCLI"> <Description>VDC:CLI</Description> <Value>1733879699</Value> </Variable> <Variable ID="$IDXSIV1"> <Description>Answer to Q.1</Description> <Value>2</Value> </Variable> <Variable ID="$IDXSIV2"> <Description>Score for Q.1</Description> <Value>5</Value> </Variable> <Variable ID="$IDXSIV3"> <Description>Answer to Q.2</Description> <Value>3</Value>

Fig. 3.33 GetVDCSessionDetails_SIX Response - XML Output example

Note: To view all the data returned see the TSV output.

TSV Output

This is the same query run for the XML output.

<GetVDCSessionDetailsResponse xmlns="urn:darwin.disp"> <GetVDCSessionDetailsResult>

<tsv_data> <string>[TITLE]Status:00000 Session Details 00069899</string> <string>[SUBTITLE]Session Details for Service: 00069899 TVQuiz</string>


Page 64 of 109

<string>[SUBTITLE]Session Ref:321140-5713933</string> <string>[DATA]$IDXFLGS 13</string> <string>[DATA]$SRTCALLVDC:Call Start Time 2006-08-21 11:09:51</string> <string>[DATA]$ENDCALLVDC:Call Stop Time 2006-08-21 11:10:18</string> <string>[DATA]$IDXCCLIVDC:CLI 1733879699</string> <string>[DATA]$IDXSIV1 Answer to Q.1 2</string> <string>[DATA]$IDXSIV2 Score for Q.1 5</string> <string>[DATA]$IDXSIV3 Answer to Q.2 3</string> <string>[DATA]$IDXSIV4 Score for Q.2 10</string> <string>[DATA]$IDXSIV5 Final Score 10</string> <string>[DATA]$IDXSIV6 Details recorded? 1</string> <string>[DATA]$IDXSIV7 Random selection 1240560553</string> <string>[DATA]$CDSCL05 Answer for Question 1: 2</string> <string>[DATA]$CDSCR05 Response Time for Question 1: 3395</string> <string>[DATA]$CVXCA15 Caller's Details 10656</string>

</tsv_data> </GetVDCSessionDetailsResult> </GetVDCSessionDetailsResponse>

Fig. 3.34 GetVDCSessionDetails_SIX Response - TSV Output example


Page 65 of 109

3.2.11 Get VDC Sessions SDR The GetVDCSessions_SDR method retrieves SDR statistical information from the SDW.

GetVDCSessions_SDR Request Parameters

Parameter Value




<NumSessions> The number of sessions to return. Blank will return 100, 0 will return 100, maximum = 1000, a value of more than 1000 will return 1000

<DateFrom> yyyy-mm-dd hh:mm:ss e.g. 2006-06-04 09:00:00 or yyyy-mmm-dd hh:mm:ss e.g. 2006-Jun-04 09:00:00

<DateTo> As above

<RegSchema> See Table 3.32 for Regional Schemas else leave blank.

<Region> See Table 3.33 for Regions else leave blank.

<SessionID> If returning a Collected session, enter the session Reference e.g. 321140-5713933

<SessionState> The can be one of the following: a = Any State, d = Aborted Session, n = Normal Session o = Overwritten Session, x = Normal & Aborted y = Normal & Overwritten, z = Aborted & Overwritten

<SortColumn> The default column names are: Session Time, Session Ref, Caller ID and Status.


Page 66 of 109

GetVDCSessions_SDR Request Parameters

Parameter Value

Additional column headings that can be used relate to the SIV captions.

<SortOrder> The Sort Order can be either: a = Ascending d = Descending

<SIV> x 8 Integer from 1 to 8 that relates to the SIV reference on the web interface.

<Comparitor> x 8 This is the operand used for comparison relating to the value below: eq = equal to ge = greater than or equal to gt = greater than lt = less than le = less than or equal to ne = not equal to dc = any value (don’t care!)

<Value> x 8 The score contained in the function node at point of capture

Table 3.24: GetVDCSessions_SDR Request Parameters


Page 67 of 109

3.2.11.1 Get VDC Sessions SDR Request The example illustrated in Fig. 3.35 shows a request for one session, where the value for SIV 5 is greater than or equal to 10. No regional information has been requested. (See “Get VDC Sessions SIX Request” for details on filtering data to Regional Schemas). The column sorted on is the caption for SIV 5, ‘Final Score’.

<GetVDCSessions_SDR xmlns="urn:darwin.disp"> <OutputType>X</OutputType> <UserID>SMAMark</UserID> <Password>england26&</Password> <LangID>eng</LangID> <DateFormat>L</DateFormat> <ServiceID>69899</ServiceID> <NumSessions>1</NumSessions> <DateFrom>2006-Aug-21 11:00:00</DateFrom> <DateTo>2006-Aug-21 12:05:00</DateTo> <RegSchema> </RegSchema> <Region> </Region> <SessionID> </SessionID> <SessionState>a</SessionState> <SortColumn>Final Score</SortColumn> <SortOrder>a</SortOrder> <SIVFilters> <SIVFilterType> <SIV>5</SIV> <Comparator>ge</Comparator> <Value>10</Value> </SIVFilterType> </SIVFilters> </GetVDCSessions_SDR>

Fig. 3.35 GetVDCSessions_SDR Request


Page 68 of 109

3.2.11.2 Get VDC Sessions SDR Response The following information is included in the response:

• The response Status e.g. “00000” (successful)

• Session selection for Service (ID)

• Session Selection Results for (date-time)

• Service ID

• Service Name

• Data Source (Audit)

• Watermark (date-time stamp)

• Current Session count (the number of sessions for the service

• Matching Sessions (the number of sessions that match the requested information)

• Sessions Requested (the number of sessions requested)

• Date From. (date-time stamp)

• Date To. (date-time stamp)

• Region (optional)

• Session Status

• Filter (optional)

• Sort column (optional)

• Headings

• Session Time

• Session Ref

• Caller ID

• Status


Page 69 of 109

• Other optional headings. In this case Final Score.

• Data

• Data for each of the headings listed above. The Data element is repeated for SDR records returned.

The output may be to either XML or TSV

XML Output

<GetVDCSessionsResponse xmlns="urn:darwin.disp"> <GetVDCSessionsResult> <xml_enc> <Status>00000</Status> <ServiceID>69899</ServiceID> <ServiceName>TV Quiz</ServiceName> <Summary> <DateTime>2006-08-21 16:22:06</DateTime> <DataSource>Audit</DataSource> <FromDate>2006-08-21 00:00:00</FromDate> <ToDate>2006-08-21 00:00:00</ToDate> <Region>ALL</Region> <SessionStatus>Any State</SessionStatus> <Filters> <Filter> <Variable>Answer to Q.1</Variable> <Compare>GE</Compare> <VarValue>10</VarValue> </Filter> </Filters> <SortColumn>FINAL SCORE (ascending)</SortColumn> <Watermark>2006-08-21 16:00:00</Watermark> <CurrentSessionCount>3</CurrentSessionCount> <MatchingSessions>3</MatchingSessions> <SessionsRequested>1</SessionsRequested> </Summary> <Columns> <Heading>Session Time</Heading> <Heading>Session Ref</Heading> <Heading>Caller ID</Heading> <Heading>Final Score</Heading> <Heading>Status</Heading> </Columns> <Sessions /> <Data>


Page 70 of 109

<SessionTime>2006-08-21 11:09:51</SessionTime> <SessionRef>321140-5713933</SessionRef> <CallerID>1733879699</CallerID> <SIV1>10</SIV1> <Status>Normal</Status>

</Data> </Sessions> </xml_enc> </GetVDCSessionsResult> </GetVDCSessionsResponse>

Fig. 3.36 GetVDCSessions_SDR Response - XML Output example


Page 71 of 109

TSV Output

<GetVDCSessionsResponse xmlns="urn:darwin.disp"> <GetVDCSessionsResult> <tsv_data> <string>[TITLE]Status:00000 Session Selection</string> <string>[SUBTITLE]Session Selection for Service: 69899</string> <string>[PARAM]Session Selection Results at 2006-08-22 07:40:43</string <string>[PARAM]Service ID00069899</string> <string>[PARAM]Service Name TV Quiz</string> <string>[PARAM]Data Source Audit</string> <string>[PARAM]Water Mark 2006-08-22 07:00:00</string> <string>[PARAM]Current Session Count 3</string> <string>[PARAM]Matching Sessions 3</string> <string>[PARAM]Sessions Requested 3</string> <string>[PARAM]Date From 2006-08-21 00:00:00</string> <string>[PARAM]Date To 2006-08-21 00:00:00</string> <string>[PARAM]Region ALL</string> <string>[PARAM]Session Status Any State</string> <string>[PARAM]Filter 1 Answer to Q.1 GE 10</string> <string>[PARAM]Sort Column FINAL SCORE (ascending)</string> <string>[HEADINGS]Session Time Session Ref Caller ID Final Score Status <string>[DATA] 2006-08-21 11:09:51321140-5713933 1732879674 10 Normal</ <string>[DATA] 2006-08-21 12:03:09321142-3760296 1732879674 10 Normal</ <string>[DATA] 2006-08-21 12:03:51321140-57139341732879674 10 Normal</s </tsv_data> </GetVDCSessionsResult> </GetVDCSessionsResponse>

Fig. 3.37 GetVDCSessions_SDR Response - TSV Output example


Page 72 of 109

3.2.12 Get VDC Session Details SDR The GetVDCSessionDetails_SDR method retrieves ‘live’ detailed SDR information for one session from the SDW. The Session Reference number must be known to be able to run this query.

GetVDCSessionDetails_SDR Request Parameters

Parameter Value




<SessionRef> The session reference number you wish to return the details on using the format nnnnnn-n(upto 10 digits) e.g. 3211405713933

Table 3.25 GetVDCSessionDetails_SDR Request Parameters

3.2.12.1 Get VDC Session Details SDR Request The example illustrated in Fig. 4.38 shows how a request for one particular session is made.

<GetVDCSessionDetails_SDR xmlns="urn:darwin.disp"> <OutputType>X</OutputType> <UserID>SMAMark</UserID> <Password>england26&</Password> <LangID>eng</LangID> <DateFormat>L</DateFormat> <ServiceID>69899</ServiceID> <SessionRef>321140-5713933</SessionRef> </GetVDCSessionDetails_SDR>

Fig. 3.38 GetVDCSessionDetails_SDR Request

3.2.12.2 Get VDC Session Details SDR Response The response returns the following details for the requested SDR:

• The Response Status e.g. “00000” (Successful)


Page 73 of 109

• Service ID

• Service Name

• Session Reference

• Session Data

• Call Answer Time

• User Group Digits (If applicable)

• Audit String

• Trace String

• Onward Routing (if applicable)

• Final DTMF String (if applicable)

• Compressed String (if applicable) This is followed by any SIV captions with the appropriate DTMF or voice responses made by the caller. In this example, the caller is asked two questions. If the caller gets both questions right (as in this case) he is ‘awarded’ 5 points for each question:

• $IDXTXT1 refers to the caption for SIV 1, Answer to Q. 1: with a DTMF input of ‘2’.

• $IDXTXT2 refers to the caption for SIV 2. Score for Q. 1: in this case, ‘5’.

• $IDXTXT3 refers to the caption for SIV 3, Answer to Q. 2: with a DTMF input of ‘3’.

• $IDXTXT4 refers to the caption for SIV 4. Score for Q. 2: in this case, ‘5’ which is added to current score of ‘5’, therefore totalling ‘10’.

• $IDXTXT5 refers to the caption for SIV 5. Final Score. In this case ‘10’.

• $IDXTXT6 refers to the caption for SIV 6. Details Recorded?. In this case ‘1’ (Yes)

• $IDXTXT7 refers to the caption for SIV 7. Random Selection (1240560553).

• $IDXTXT7 refers to the caption for SIV 8. (not configured).

• $SRTCALL refers to the Call Start Time e.g. 2006-08-21 11:09:51

• $ENDCALL refers to the Call End Time e.g. 2006-08-21 11:10:18

• $SESRAND refers to the Random Session Tag e.g. 1240560553.

• $IDXCCLI refers to the caller’s CLI.

• $IDXCAFC refers to the number of recorded CAFs for this session e.g. ‘1’.


Page 74 of 109

• $IDXCAFD refers to the total duration for all CAFs for this session e.g. 10 (seconds)



Page 75 of 109

XML Output

<GetVDCSessionDetailsResponse xmlns="urn:darwin.disp"> <GetVDCSessionDetailsResult> <xml_enc> <Status>00000</Status> <ServiceID>00069899</ServiceID> <ServiceName>TV Quiz</ServiceName> <SessionRef>321140-5713933</SessionRef> <SessionData> <Variable ID="$ANSCALL"> <Description>Call Answer Time</Description> <Value>2006-08-21 11:09:52</Value> </Variable> <Variable ID="$SDRMAP1"> <Description>Closed User Group Digits</Description> <Value /> </Variable> <Variable ID="$SDRMAP2"> <Description>FIVA Audit String</Description> <Value>--------2_------3_--------------------</Value> </Variable> <Variable ID="$SDRMAP3"> <Description>FIVA Trace String</Description> <Value>222222322232122000000000000000002</Value> </Variable> <Variable ID="$SDRMAP4"> <Description>Onward Route</Description> <Value /> </Variable> <Variable ID="$SDRMAP5"> <Description>FIVA Final DTMF String</Description> <Value /> </Variable> <Variable ID="$SDRMAP6"> <Description>FIVA Compressed DTMF String</Description>

Fig. 3.39 GetVDCSessionDetails_SDR Response - XML Output example

Note: To view all data returned see the TSV Output.

TSV Output



Page 76 of 109

<GetVDCSessionDetailsResponse xmlns="urn:darwin.disp"> <GetVDCSessionDetailsResult>

<tsv_data> <string>[TITLE]Status:00000 Session Details 00069899</string> <string>[SUBTITLE]Session Details for Service: 00069899 TV Quiz</string <string>[SUBTITLE]Session Ref:321140-5713933</string> <string>[DATA]$ANSCALL Call Answer Time2006-08-21 11:09:52</string> <string>[DATA]$SDRMAP1 Closed User Group Digits</string> <string>[DATA]$SDRMAP2 FIVA Audit String--------2_------3_---------</s <string>[DATA]$SDRMAP3 FIVA Trace String2222223222321220000000000000000 <string>[DATA]$SDRMAP4 Onward Route</string> <string>[DATA]$SDRMAP5 FIVA Final DTMF String</string> <string>[DATA]$SDRMAP6 FIVA Compressed DTMF String</string> <string>[DATA]$IDXTXT1 Answer to Q.1 2</string> <string>[DATA]$IDXTXT2 Score for Q.1 5</string> <string>[DATA]$IDXTXT3 Answer to Q.2 3</string> <string>[DATA]$IDXTXT4 Score for Q.2 10</string> <string>[DATA]$IDXTXT5 Final Score 10</string> <string>[DATA]$IDXTXT6 Details recorded? 1</string> <string>[DATA]$IDXTXT7 Random selection 1240560553</string> <string>[DATA]$SRTCALL VDC:Call Start Time 2006-08-21 11:09:51</string> <string>[DATA]$ENDCALL VDC:Call Stop Time 2006-08-21 11:10:18</string> <string>[DATA]$SESRAND VDC:Random SessionTag 1240560553</string> <string>[DATA]$IDXCCLI VDC:CLI 1733879699</string> <string>[DATA]$IDXCAFC VDC:CAF Count 1</string> <string>[DATA]$IDXCAFD VDC:CAF Duration 10</string> </tsv_data> </GetVDCSessionDetailsResult> </GetVDCSessionDetailsResponse>

Fig. 3.40 GetVDCSessionDetails_SDR Response - TSV Output example


Page 77 of 109

3.2.13 Get SIV Mappings The GetSIVMappings method allows you to view and confirm the SIV Mappings for a particular service are as they should be.

GetSIVMappings Request Parameters

Parameter Value



Table 3.26 GetSIVMappings Request Parameters

3.2.13.1 Get SIV Mappings Request <GetSIVMappings xmlns="urn:darwin.disp"> <OutputType>X</OutputType> <UserID>SMAMark</UserID> <Password>england26&</Password> <LangID>eng</LangID> <DateFormat>L</DateFormat> <ServiceID>69899</ServiceID> </GetSIVMappings>

Fig. 3.41 GetSIVMappings Request


Page 78 of 109

3.2.13.2 Get SIV Mappings Response The response returns the following details:


• Service ID

• Service Name

• SIVs (Details for each SIV)

• SIV ID. The text description or caption e.g. Answer to Q. 1:

• Variable Reference e.g. DTMF Selection, Score, CAF Recorded, Random Number etc.

• Node. The Function Node where the Variable Reference is actioned. The SIV element is repeated for each SIV returned.



Page 79 of 109

XML Output

<GetSIVMappingsResponse xmlns="urn:darwin.disp"> <GetSIVMappingsResult> </xml_enc> <Status>00000</Status> <ServiceID>00069899</ServiceID> <ServiceName>TV Quiz</ServiceName> <SIVS> <SIV ID="1"> <Description>Answer to Q.1</Description> <VariableRef>DTMF Selection</VariableRef> <Node>Function Node 5</Node> </SIV> <SIV ID="2"> <Description>Score for Q.1</Description> <VariableRef>Score</VariableRef> <Node>Function Node 7</Node> </SIV> <SIV ID="3"> <Description>Answer to Q.2</Description> <VariableRef>DTMF Selection</VariableRef> <Node>Function Node 9</Node> </SIV> <SIV ID="4"> <Description>Score for Q.2</Description> <VariableRef>Score</VariableRef> <Node>Function Node 11</Node> </SIV> <SIV ID="5"> <Description>Final Score</Description> <VariableRef>Score</VariableRef> <Node>End of Call</Node> </SIV> </SIVS> </xml_enc> </GetSIVMappingsResult> </GetSIVMappingsResponse>

Fig. 3.42 GetSIVMappings - XML Output example

Note: SIVs 6 - 8 were not configured, hence there are no entries in the response.

TSV Output


Page 80 of 109


<GetSIVMappingsResponse xmlns="urn:darwin.disp"> <GetSIVMappingsResult> <tsv_data> <string>Status: 00000</string> <string>SIV Mappings for Service: 00069899</string> <string>Service Name: TV Quiz</string> <string>Variable ID Description Captured Variable Ref Node Number </st <string> 1 Answer to Q.1 DTMF Selection Function Node 5 </st <string> 2 Score for Q.1 Score Function Node 7 </st <string> 3 Answer to Q.2 DTMF Selection Function Node 9 </st <string> 4 Score for Q.2 Score Function Node 11</st <string> 5 Final Score Score End of Call </string <string> 6 Details recorded? CAF Recorded Function No <string> 7 Random selection Random Number End of Call </string> </tsv_data> </GetSIVMappingsResult> </GetSIVMappingsResponse>

Fig. 3.43 GetSIVMappings Response - TSV Output example

Note: the characters from the right hand side of each line have been omitted for clarity.


Page 81 of 109

3.2.14 Get SIX Watermark The GetSIXWaterMark method returns the current high watermark on the Collator and the number of sessions for a given service that are included in that watermark.

GetSIXWatermark Request Parameters

Parameter Value




Table 3.27 GetSIXWatermark Request Parameters

3.2.14.1 Get SIX Watermark Request <GetSIXWatermark xmlns="urn:darwin.disp"> <OutputType>X</OutputType> <UserID>SMAMark</UserID> <Password>england26&</Password> <LangID>eng</LangID> <DateFormat>L</DateFormat> <ServiceID>69899</ServiceID> </GetSIXWatermark>

Fig. 3.44 GetSIXWatermark Request


Page 82 of 109

3.2.14.2 Get SIX Watermark Response The response returns the following details:


• Session Index Watermark (date-time stamp)

• Record Count (number of indexed sessions on the platform for this service at the time of the watermark).


XML Output

<GetWatermarkResponse xmlns="urn:darwin.disp"> <GetWatermarkResult> </xml_enc> <Status>00000</Status> <CurrentWaterMark ID="SIX"> <DateTime>2006-08-17 13:04:08</DateTime> <RecordCount>3</RecordCount> </CurrentWaterMark> </xml_enc> </GetWatermarkResult> </GetWatermarkResponse>

Fig. 3.45 GetSIXWatermark - XML Output example


Page 83 of 109

TSV Output

<GetWatermarkResponse xmlns="urn:darwin.disp"> <GetWatermarkResult> <tsv_data> <string>Status:00000</string> <string>Details for Service: 00069899 TV Quiz</string> <string>Water Mark Record Count</string> <string>Session Index Watermark2006-08-17 13:04:08 3</string> </tsv_data> </GetWatermarkResult> </GetWatermarkResponse>

Fig. 3.46 GetSIXWatermark Response - TSV Output example

3.2.15 Get SDR Watermark The GetSDRWaterMark method returns the current high watermark on the SDW and the number of sessions for a given service that are included in that watermark.

GetSDRWatermark Request Parameters

Parameter Value




Table 3.28 GetSDRWatermark Request Parameters


Page 84 of 109

3.2.15.1 Get SDR Watermark Request <GetSDRWatermark xmlns="urn:darwin.disp"> <OutputType>X</OutputType> <UserID>SMAMark</UserID> <Password>england26&</Password> <LangID>eng</LangID> <DateFormat>L</DateFormat> <ServiceID>69899</ServiceID> </GetSDRWatermark>

Fig. 3.47 GetSDRWatermark Request

3.2.15.2 Get SDR Watermark Response The response returns the following details:


• Session Index Watermark (date-time stamp)

• Record Count (number of SDRs on the platform for this service at the time of the watermark).



Page 85 of 109

XML Output

<GetWatermarkResponse xmlns="urn:darwin.disp"> <GetWatermarkResult> </xml_enc> <Status>00000</Status> <CurrentWaterMark ID="SDR"> <DateTime>2006-08-22 12:00:00</DateTime> <RecordCount>5</RecordCount> </CurrentWaterMark> </xml_enc> </GetWatermarkResult> </GetWatermarkResponse>

Fig. 3.48 GetSDRWatermark - XML Output example

TSV Output

<GetWatermarkResponse xmlns="urn:darwin.disp"> <GetWatermarkResult> <tsv_data> <string>Status:00000</string> <string>Details for Service: 00069899 TV Quiz</string> <string>Water Mark Record Count </string> <string>Session Index Watermark 2006-08-22 12:00:00 5 </string> </tsv_data> </GetWatermarkResult> </GetWatermarkResponse>

Fig. 3.49 GetSDRWatermark Response - TSV Output example


Page 86 of 109

3.2.16 Get Service Var The GetServiceVar method allows you to view the value of a variable for a specific service. Viewing the value of a variable is subject to your level of access to the RIDE platform. Variables that are containers for announcements cannot be viewed. A full list of service variables that can be accessed is provided in “Service Variables”.

GetServiceVar Request Parameters

Parameter Value




<VarName> Any service variable other than announcement containers.

Table 3.28 GetServiceVar Request Parameters

3.2.16.1 Get Service Var Request This Request will return the value of the $SESIMPF variable (VDC:Pending Deletion Email:Enable) for a particular service.

<GetServiceVar xmlns=“urn:darwin.disp”> <OutputType>X</OutputType> <UserID>SMAMark</UserID> <Password>england26&</Password> <LangID>eng</LangID> <DateFormat>L</DateFormat> <ServiceID>00028527</ServiceID> <VarName>$SESIMPF</VarName> </GetServiceVar>

Fig. 3.50 GetServiceVar Request

3.2.16.2 Get Service Var Response XML output


Page 87 of 109

The Response provides confirmation of the variable requested with its current value. It also provides an element <ReadWrite> that indicates to the user that sent the request if they have permission to modify the variable value. W indicates that they may; R indicates that it is view only to them.

<GetServiceVarResponse xmlns=“urn:darwin.disp”> <GetServiceVarResult> <xml_enc> <Status>00000</Status> <ServiceID>00028527</ServiceID> <Variable> <Name>$SESIMPF</Name> <Alias /> <Value>No</Value> <ReadWrite>W</ReadWrite> </Variable> </xml_enc> </GetServiceVarResult> </GetServiceVarResponse>

Fig. 3.51 GetServiceVar Response - XML Output example

TSV output

<GetServiceVarResponse xmlns=“urn:darwin.disp”> <GetServiceVarResult> <tsv_data> <string>00000 Service Variable Service 00028527 </string> <string>Variable Name Variable Alias Variable Value ReadWrite </string> <string>$SESIMPF No W</string> </tsv_data> </GetServiceVarResult> </GetServiceVarResponse>

Fig. 3.52 GetServiceVar Response - TSV Output example

3.2.17 Set Service Var The SetServiceVar method allows you to modify the value of a variable for a specific service. Modifying the value of a variable is subject to your level of access to the RIDE platform. Variables that are containers for announcements cannot be modified. The XML Elements <VarAlias> and <VarValue> are optional; these only need to be included in the SOAP Request if the value is to be updated. Specifying these elements with no data will clear the value for the variable name or alias. A full list of service variables that can be accessed is provided in “Service Variables”.


Page 88 of 109

SetServiceVar Request Parameters

Parameter Value




<VarName> Any service variable other than announcement containers.

<VarAlias> The Alias associated with the Variable Name

<VarValue> The value of the Variable

<ChangeDate> The date/time you wish the change to take effect from using the format: yyyy-mm-dd hh:mm:ss (or dd mmm yyyy hh:mm:ss). Entering the word ‘Now’ will make the change with immediate effect.

Table 3.29 SetServiceVar Request Parameters


Page 89 of 109

3.2.17.1 Set Service Var Request This Request will update the value of the $SESIMPF variable (VDC:Pending Deletion Email:Enable) from No to Yes with immediate effect.

<SetServiceVar xmlns=“urn:darwin.disp”> <OutputType>X</OutputType> <UserID>SMAMark</UserID> <Password>england26&</Password> <LangID>eng</LangID> <DateFormat>string</DateFormat> <ServiceID>00028527</ServiceID> <VarName>$SESIMPF</VarName> <VarAlias></VarAlias> <VarValue>Yes</VarValue> <ChangeDate>Now</ChangeDate> </SetServiceVar>

Fig. 3.53 SetServiceVar Request


Page 90 of 109

3.2.17.2 Set Service Var Response XML output


<SetServiceVarResponse xmlns=“urn:darwin.disp”> <SetServiceVarResult> <xml_enc> <Status>00000</Status> </xml_enc> </SetServiceVarResult> </SetServiceVarResponse>

Fig. 3.54 SetServiceVar Response - XML Output example

TSV output


<SetServiceVarResponse xmlns=“urn:darwin.disp”> <SetServiceVarResult> <tsv_data> <string>Service variable update successful </string> <string>Status: 00000 </string> </tsv_data> </SetServiceVarResult> </SetServiceVarResponse>

Fig. 3.55 SetServiceVar Response - TSV Output example


Page 91 of 109

3.2.18 Get Services The GetServices method allows you to retrieve a list of services for a specific Service Provider.

GetServices Request Parameters

Parameter Value


<ServiceProviderName> The name of the Service Provider that you wish to retrieve a list of services from.

Table 3.30 GetServices Request Parameters

3.2.18.1 Get Services Request The Request simply supplies the <ServiceProviderName>.

<GetServices xmlns=“urn:darwin.disp”> <OutputType>X</OutputType> <UserID>SMAMark</UserID> <Password>england26&</Password> <LangID>eng</LangID> <ServiceProviderName>A Service Provider</ServiceProviderName> </GetServices>

Fig. 3.56 GetServices Request

3.2.18.2 Get Services Response XML output

The Response returns the name of the <ServiceProvider> and lists all the services supplying the service code (<ID>), the type the service is an instance of (<Type>) and the name of the service (<Name>).


Page 92 of 109

<GetServicesResponse xmlns=“urn:darwin.disp”> <GetServicesResult> <xml_enc> <Status>00000</Status> <ServiceProvider>A SERVICE PROVIDER</ServiceProvider> <Services> <Service> <ID>00069530</ID> <Type>Televote Small</Type> <Name>944394 Stars In Their Eyes 2</Name> </Service> <Service> <ID>00069543</ID> <Type>Message Link 2</Type> <Name>944393000200069543</Name> </Service> <Service> <ID>00069609</ID> <Type>Message Link 1</Type> <Name>944393000100069609</Name> </Service> <Service> <ID>00069886</ID> <Type>FIVA - Without Call Distribution</Type> <Name>Charity Event</Name> </Service> <Service> <ID>00070367</ID> <Type>Televote Small</Type> <Name>944394 - My Favourite Pop Star</Name> </Service> <Service> <ID>00070559</ID> <Type>Message Link 2</Type> <Name>944393000200070559</Name> </Service> </Services> </xml_enc> </GetServicesResult> </GetServicesResponse>

Fig. 3.57 GetServices Response - XML Output example


Page 93 of 109

TSV output

<GetServicesResponse xmlns=“urn:darwin.disp”> <GetServicesResult> <tsv_data> <string>00000 List of Services for A SERVICE PROVIDER</string> <string>Service ID Service Type Service Description </string> <string>00069530 Televote Small 944394 Stars in Their Eyes 2</string> <string>00069543 Message Link 2 944393000200069543 </string> <string>00069609 Message Link 1 944393000100069609 </string> <string>00069886 FIVA - Without Call Distribution Charity Event </str <string>00070367 Televote Small 944394 - My Favourite Soap </string> <string>00070559 Message Link 2 944393000200070559 </string> </tsv_data> </GetServicesResult> </GetServicesResponse>

Fig. 3.58 GetServices Response - TSV Output example


Page 94 of 109

3.2.19 RTS Counters The RTSCounters request allows you to Reset, Freeze or Unfreeze the Real Time Statistics Calls Since Last Reset counter.

Note: You are strongly recommended not to use this request but to make use of the Execute Macros request to start or stop the vote. Each Macro is only permitted under certain conditions – preventing you from making a mistake. The controls on there RTS counters are not protected and you can Reset when you mean to Freeze!

RTSCounters Request Parameters

Parameter Value




<Action> R (Reset) F (Freeze) U (Unfreeze)

<ChangeDate> The date/time you wish the Action to take effect from. Entering the word ‘Now’ will make the change with immediate effect.

Table 3.31 RTSCounters Request Parameters


Page 95 of 109

3.2.19.1 RTS Counters Request In the Request this Message Link 2 service will have the RTS counters frozen.

<RTSCounters xmlns=“urn:darwin.disp”> <OutputType>X</OutputType> <UserID>SMAMark</UserID> <Password>england26&</Password> <LangID>eng</LangID> <DateFormat>L</DateFormat> <ServiceID>00070559</ServiceID> <Action>F</Action> <ChangeDate>Now</ChangeDate> </RTSCounters>

Fig. 3.59 RTSCounters Request


Page 96 of 109

3.2.19.2 RTS Counters Response XML output

The Response indicates in the (<Status>) element that the request was successful and provides the action implemented to the Trip counter. As the change date in the Request message was stipulated as ‘Now’, the current date/time is displayed.

<RTSCountersResponse xmlns=“urn:darwin.disp”> <RTSCountersResult> <xml_enc> <Status>00000</Status> <ServiceID>00070559</ServiceID> <Action>Freeze</Action> <CounterType>Trip</CounterType> <Schedule>Jun 9 2006 9:01AM</Schedule> </xml_enc> </RTSCountersResult> </RTSCountersResponse>

Fig. 3.60 RTSCounters Response - XML Output example

TSV output

<RTSCountersResponse xmlns=“urn:darwin.disp”> <RTSCountersResult> <tsv_data> <string>00000 Realtime Counters Update 00070559</string> <string>ServiceID Action CounterType Scheduled</string> <string>00070559 Freeze Trip Jun 9 2006 9:05AM</string> </tsv_data> </RTSCountersResult> </RTSCountersResponse>

Fig. 3.61 RTSCounters Response - TSV Output example


Page 97 of 109

3.3 Schemas & Regions 3.3.1 Regional Schemas Available Schemas

Schema Parameter value Description

Fixed v. Mobiles

mobile Indicates whether the call originated from a Fixed Line or a Mobile phone.

ITV Broadcasting Regions

tv Used to break down the search selection to one or all ITV Broadcasting Regions.

UK Countries countries Used to break down the search selection to one or all countries within the UK.

UK Counties Counties73 Used to break down the search selection to one or all Counties within the UK.

Table 3.32 Schemas

In the above schema, the schema name displayed on the web view is different to the parameter used in the SOAP interface.

The Regions described below all use the same parameter for SOAP as deplayed on the web view.


Page 98 of 109

3.3.2 Schemas and their Associated Regions Schemas and their associated regions

Fixed v. Mobiles

All Fixed Line Mobile Phone

ITV Broadcasting Regions

All Anglia Television Border Television

Carlton Central Carlton and LWT Carlton - Westcountry

Channel TV Grampion Granada

HTV Meridian Broadcasting Mobile

Non-Geographic Scottish Television Tyne-Tees TV

Ulster TV Yorkshire Television

UK Countries

All Channel Islands England

Mobile Non-Geographic Northern Ireland

Scotland Wales

UK Counties

All Avon Bedfordshire

Berkshire Buckinghamshire Cambridgeshire

Central Scotland Cheshire Cleveland

Clwyd Cornwall County Antrim

County Armargh County Down County Durham

County Fermanagh County Londonderry County Tyrone


Page 99 of 109

Schemas and their associated regions

Cumbria Derbyshire Devon

Dorset Dumfries & Galloway Dyfed

East Sussex Essex Fife

Gloucestershire Grampian Greater London

Greater Manchester Guernsey Gwent

Gwynedd Hampshire Hereford & Worcester

Hertfordshire Highland Humberside

Isle of Man Isle of Wight Jersey

Kent Lancashire Leicestershire

Lincolnshire Lothian Merseyside

Mid Glamorgan Mobile Non-Geographic

Norfolk North Yorkshire Northamptonshire

Northumberland Nottinghamshire Orkney Islands

Oxfordshire Powys Scottish Borders

Shetland Islands Shropshire Somerset

South Glamorgan South Yorkshire Staffordshire

Strathclyde Suffolk Surrey

Tayside Tyne and Wear Warwickshire

West Glamorgan West Midlands West Sussex

West Yorkshire Wiltshire

Table 3.33 Schemas and their associated regions


Page 100 of 109

4 LOAD CONTROLS

4.1 Load Control Limits Usage of the SOAP interface will put extra demand on some components of the RIDE platform. To ensure that an acceptable level of performance is maintained for all users and processes on the platform, mechanisms have been implemented to prevent SOAP requests flooding the system.

• A SOAP account will be restricted to one ID and password combination.

• Multiple requests from the same IP address and/or user account are restricted to only one request at a time. Once the platform has completed a request, there is a timed interval of 10 seconds before another request is accepted. The time taken for the platform to complete the request does not include the time taken to download the response. Note that submitting subsequent requests too rapidly will result in the receipt of error code 00102.

• Attempting to connect using a locked user account or from an account from an unrecognised IP address will raise an alarm. This is consistent with standard web login procedures.

• The limit of new requests per minute is variable and depends upon the demand for service on the whole platform.

• A SOAP client interface will service a single shot connection and have no concept of user sessions or persistence; A request for data is made, it is authenticated and a result set is subsequently returned. Once this sequence is complete the connection is closed. Concurrency is defined by the number of currently active connections.

• When data is requested from the SDW the number of records returned is determined by a batch size parameter. This will prevent overloading of both the SDW and web servers with a single request. A bookmark protocol also enables the data returned by multiple requests to be reconstituted into a single data set.


Page 101 of 109

4.2 Report Restrictions Each report that is available via the ExecuteReport message will subject the platform to varying loads dependant on the report being run. Therefore the number of rows returned will differ for some reports. Reports that can return information on FromDate, ToDate, Granularity and Regional breakdown will be subject to the following weighting calculation:

Date Range / Granularity * Regions

Using the CLS report as an example:

The maximum number of rows the system will allow for XML output for this report is 1,000 rows. If the FromDate and ToDate spanned 10 days and the Granularity stipulated was 12 hours the number of rows returned would be 20. If the Regional Schema, Countries is selected and Regional ID is set to None (i.e. all regional IDs may be returned giving a total of 7 regions.), the number of rows is increased by a factor of 7 giving a total of 140 rows. A request that met this criteria would be returned successfully e.g. <Status>00000</Status>.

If, using the same example, a Granularity of 1 hour was selected, the number of rows to be returned would be 1,680 thereby exceeding the system maximum. In this case <Status>00130</Status> (Inappropriate Granularity for Report) will be returned in the Response message.

4.3 Performance optimisation To achieve the best performance, always consider the time and rate at which you submit coimmands.

• Do not submit more than one command at a time. Always wait for the response.

• Do not allow multiple use of a single ID/password combination.

• Do not jeopardise your urgent requests for RTS stats by demanding wharehouse stats at the same time. Bulk data for post event analysis can be obtained later when the platform is under less load. BT can help you determine these quieter periods.

• Make the most efficient use of the bookmark system by timing the calls so that the largest blocks of data are obtained. This will result in fewer calls to the platform and therefore less platform load.


Page 102 of 109

5 SERVICE VARIABLES The service variables that can be either viewed and/or modified are all defined in the relevant Service Provider User Guide (SPUG).

6 Application considerations These commands are intended to be generated by a computer with little or no human intervention. When you obtain the expected response, the complexity of the process is invisible. You are advised to consider how you develop and improve your use of these commands so that you can:

• Understand the implications of the individual changes.

• Easily revert to a known working command, if you encounter a problem.

• Quickly determine the cause of a failure and restore service.

6.1 Good practice • Test the application in advance of the need to use it and once satisfied, make no further

changes.

• Ensure users understand that regular web access can deliver the same data output and use this knowledge to confirm the application responses.

• Start with a simple example to ensure you can get the expected response e.g. GetServices. And then add complexity, periodically ensuring the response changes as you expect.

• As you develop your use of the application, keep records of versions which work, to allow you understand how each change has affected the response.

• Whenever the SOAP interface is changed, this User Guide will be re-issued to describe the new features. To take advantage of the changes, you must recompile your client software against the server.


Page 103 of 109

7 ERROR CODES Errors can be returned as either a SOAP Fault or a Status Error:

7.1 Soap Fault The basic structure of both the request and response message are the same, the main difference is the data contained within the <soap:body>.

A Response message may also contain a Fault Element (<soap:fault>) in the body if the operation was unsuccessful. An example of a response message containing the Fault Element is shown below in Fig. 7.1:

<?xml version=“1.0” encoding=“utf-8”?> <soap:Envelope xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/ xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance” xmlns:xsd=“http://www.w3.org/2001/XMLSchema”> <soap:Body> <soap:Fault> <faultcode>soap:Client</faultcode> <faultstring>The parameter ServiceID is invalid</faultstring> <detail /> </soap:Fault> </soap:Body> </soap:Envelope>

Fig. 7.1 Response message showing the Fault Element

http://schemas.xmlsoap.org/soap/envelope/


Page 104 of 109

7.1.1 Fault Element Contents A Fault Element <soap:Fault> may consist of the following sub elements:

Fault Element Contents

<faultcode> A text code use to indicate the class of the error:

soap:Client Indicates the client request contained an error

soap:Server Indicates that a server error prevented the soap request from being processed.

soap:VersionMismatch Indicates the SOAP Envelope contained an invalid namespace.

<faultstring> A human readable explanation of the error

<detail /> An element used to carry application-specific error methods. The detail element can contain child elements, called detail entries.

Table 7.1 Fault Element contents


Page 105 of 109

7.2 Status Codes The Table below provides a definitive list of all Status errors that can be returned in the Response message:

Status Errors

Code Description

00000 Successful

00100 Security Failure (caused by invalid user name, password or IP address)

00101 Security Failure (expired password)

00102 Server Busy (Caused by too many concurrent requests)

00103 Server Unavailable

00104 Real Time Statistics Unavailable

00105 Statistics Data Warehouse Unavailable

00106 Unrecognised Service ID

00107 Unrecognised Service Provider Name in GetServices

00108 Badly formed bookmark

00109 A supplied parameter was invalid (Incorrect parameter type, value or value out of range)

00110 The requested service variable does not exist or you do not have permission to access it or you have made subsequent requests too quickly (See Load Controls)

00111 Locked by RUD

00112 No DDI data available or no DDI's configured for the Service (Param1)

00113 The operation failed because it would have resulted in a rule violation

00114 Collator Unavailable


Page 106 of 109

Status Errors

Code Description

00115 Unable to set the new password because the same password has been used in the last year

00116 The new password does not meet the required security constraints

00117 The new password is identical to the current password

00118 The supplied DDI is already in use

00119 There is a problem with the service (Missing service variable etc.)

00120 System Error

00121 Invalid Service selected for Report

00122 Invalid Name selected for Report

00123 Service Download Report Name selected for Non VDC Service

00124 Invalid Schema selected for Node1

00125 Invalid Schema selected for Node2

00126 Invalid Region selected for schema

00127 Invalid Region selected

00128 Invalid Schema and/or Region selected for Post Node 0

00129 Invalid Node Flag for this user

00130 Inappropriate granularity entered for date range or max number of rows exceeded for report.

00131 Inappropriate granularity Report ID or max number of rows exceeded for report

00132 Invalid value for Report ID

00133 Invalid Call Type for Report


Page 107 of 109

Status Errors

Code Description

00134 Start Date after End Date for Reported ID

00135 Failure to execute macro.

00136 Server too busy to execute report, please try again later.

00500 The requested function does not exist

00999 Error code could not be translated (No mapping exists to convert the internal error code)

Table 7.2 Status Errors


Page 108 of 109

7.3 Fault diagnostic best practice If you encounter problems with the SOAP interface, we will always fix problems with the RIDE platform. We can not resolve problems with your application, but we will try and assist where possible.

You may need to resolve the following issues before you approach BT with a fault:

• When did it last work – what may have changed since then? Revert to a previous version and try again.

• Can your application gain access to the Inernet at all?

• Can you application execute a simple call such as “GetServices”. This may be a usefull test to be built into the application for just this situation.

• Can you use the SOAP UserID and password to log in manually to the regular web interface? If not, the password has expired or the details are incorrect. They need to be reset.

• Ensure that users can confirm that calls are actually being issued to the RIDE platform, before reporting a lack of response.

• Ensure that users know the level of detail required to report a fault.. I.e. they must know the precise service, user ID and password combination which has failed, including all the parameters, UserID and Password.

• Ensure that users know where to report a fault: 0800 110011 Option 1.

• Resist the temptation to run the application repetedly when you don’t get the expected response. If the application does not work first time, it will not work a second time, unless something changes. There is limited capacity to service these calls. A flood of test calls will degrade response times which may affect other services and users.

• Ensure that if the worst happens to your application, the regular web access will still be available for administration and capture of data. While this will be unsatisfactory compared to the working application, it will provide you with some output. Make sure you have processes in place to use the regular web access as a fallback.


Page 109 of 109

8 SOAP related sources of information Web Address Organisation

http://www.we.org/TR/SOAP/ SOAP 1.1 Specification

http://www.we.org/TR/SOAP12/ SOAP 1.2 Specification

http://msdn.microsoft.com/vstudio/ Microsoft Development Tools (Visual Studio)

http://www.mssoapinterop.org Microsoft SOAP Interoperability

http://xml.apache.org/soap Apache SOAP Project

http://ws.apache.org/axis/ Apache Axis (SOAP Project)

http://www.soapware.org Links to other Soap Information

9 ABBREVIATIONS See RIDE Web Interface Service Provider User Guide.

END