Introduction

ServiceOptimizer has a number of SOAP Application Programming Interfaces (APIs) that allow data to be passed into the system and data to be read from the system.

This document details each of the SOAP APIs, giving an explanation of their use and explaining the data that each uses.

The SOAP APIs have previously been available in the form of a C API Class library and/or as a WSDL Web Service.

Starting with ServiceOptimizer 9.1.0, only the WSDL SOAP APIs are supported.

Conventions

Each SOAP API will be described in a table. Each table for the description will consist of the following columns:

Web Service Name - The name of the element in the web service.
Type - The data type of the field, either the primitive type or one of the defined Data Types.
Description - Description of the field.
Req? - Is this a required field?
Val? - Is the data in this field validated directly against data set up in ServiceOptimizer?

Using the Web Services

The SOAP APIs are defined in a WSDL file which is included with ServiceOptimizer, installed in the SOAP directory. This WSDL contains the definition for all fields and as such its definitions supersede anything that is written in this document.

In addition to being included in the ServiceOptimizer SOAP directory, the WSDL definition of the ServiceOptimzier SOAP APIs can be obtained dynamically by performing an HTTP GET request to the following URL:

http(s)://<serverHost>:<soapPort>/?wsdl

where:

Either http:// or https:// should be used, depending on how ServiceOptimizer has been configured;
The <serverHost> text should be replaced with the hostname of the ServiceOptimizer service; and
The <soapPort> text should be replaced with the port name that ServiceOptimizer has been configured to use for the SOAP API service.

The ServiceOptimizer server connection is indicated in the “service” part of the WSDL file so it does not need to be included with any function.

Each Web Service allows you to supply the login information as part of the function call. The standard structure is:

Web Service		Type	Description	Req?	Val?
`<login>`
	`<databaseUser>?</databaseUser>`	`string(30)`	For an Oracle database, use the Schema name. For a SQL Server database, use the database name.
	`<password>?</password>`	`string(50)`	Password for the ServiceOptimizer user.
	`<spUser>?</spUser>`	`string(50)`	Valid ServiceOptimizer user.
`</login>`

SOAP API responses are specified for all interfaces where they are specific to that interface. Where no response is specified the ‘standard’ structure will be returned:

Web Service			Type	Description	Req?	Val?
`<sp:StandardResponse>`
	`<result>`
		`<type>?</type>`	`ReturnCodeType`	Shows whether code should be taken as a success, success but with a warning, or failure.
		`<code>?</code>`	`int`	The Return Code.
		`<errNote>?</errNote>`	`string`	Optional note about any error(s).
	`</result>`
`</sp:StandardResponse>`

The majority of names and descriptions used/displayed within the ServiceScheduling system can be given translations into a number of different languages, as required to support the business. The system relies on these translations being set up in the database. The various APIs will then use the locale of the server environment to determine the correct language being provided or returned.

Localization

In the case of break names that are entered as overrides into the shift for any given operative/day, it is not possible to specify any translations and the only language available will be the one used when the break was created. As such, the Integration ServiceOptimizer Dispatch SOAP APIs will return this data in only the given language irrespective of the locale of the calling system.

Usernames and Passwords

It should be noted that, due to the way the API input is parsed, it is not possible to have usernames or passwords that include ‘special’ characters, specifically commas.

Latitude and Longitude

A number of interfaces accept input of latitude and longitude. These values are assumed to be entered using the World Geodetic coordinate System WGS84 and have a precision of up to 9 decimal places.

Browser not supported