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. 

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

Each Web Service allows you to supply the log in 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.

Localisation

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 that used when the break was created. As such, the Dispatch APIs (see §10) 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.