SOAP Web Services

Last modified on 2022/11/08 13:22

UseRestInsteadOfSoap

Note: Service Manager SOAP web services are no longer maintened since the Oxygen version. You can still use them but we recommend that you use the Service Manager REST API to take advantage of the latest enhancements and features.

Definition

SOAP (Simple Object Access Protocol) is a protocol based on XML for exchanging structured information in the implementation of web services. It is used by web services to send messages between remote objects.

EndDefinitionServicePortfolio

Operating principle

A consumer carries out a request via a query near a supplier of web services.
The web service carries out the query then returns the answer to the consumer.
The consumer uses the answer in the framework of a third application which he has developed.

Service Manager supplier and consumer of SOAP web services

Service Manager as supplier of SOAP web services

Service Manager offers SOAP web services. These are well-defined business functions. See the list of web services.
example Component for the creation or the suspension of incidents in Service Manager

The third-party application calls a Service Manager SOAP web service sending the values expected by the parameters of this one. Processing is then carried out as if Service Manager was active.
example A Service Desk application calls the Suspend a ticket SOAP web service by sending the Service Manager incident number

Service Manager as consumer of SOAP web services

Service Manager can call SOAP web services provided by other products.
example Call of an external component that reinitializes the passwords

The access to the SOAP web service is performed using a WebService step automatic action in a process (workflow or business rule). The external SOAP web service must be previously declared and configured. See SOAP web services settings.

Open url.png See SOAP web services examples

Notes

The development of the consuming part needs to be done by the consumer and must respect the Service Manager WSDL that may be accessed at the following address: http://{easyvista_path}/WebService/SmoBridge.php.
- <easyvistapath> = your EasyVista folder on the Apache server
- Caution: The address is case sensitive.
Naming rules of Service Manager SOAP web services:
- EZV_(function name of the business rule).
- If it is a system function: EZV_SYS_(function name).
Properties of Service Manager SOAP web services:* The parameters are case sensitive: You need to respect upper and lower case characters.
- The expected value by the parameter is specified in the file SmoBridge.php.
  example Login: xsd:string
- When several parameters concern the same information, a search algorithm processes the parameters one by one and in a precise order until the corresponding record is found. If the record is not found, an error will be returned and the processing by Service Manager SOAP web service is stopped. In the description tables of Service Manager SOAP web services, the parameters related to this algorithm are regrouped and mentioned in the search order.
  example Group_ID - Group_Mail - Groupe_Name
- The error management is done via return codes.
  example -1 = Service Manager database not found

Best Practice

To avoid errors during the data entry of the parameters, use the Cut & Paste function from the descriptive file SmoBridge.php.
When you use a web service using an XML structure, refer to the database model Service Manager to codify the name of the fields and to avoid syntax errors.
Date type parameters: Respect the date format used in the country of the user connected to the application.
Label type parameters: Enter the defined labels in the language of the user connected to the application.

Licensing

Each time a call is made to a Service Manager SOAP web service, user access is recorded. See Service Manager license usage rules.

Access to the Service Manager SOAP web services

The access to the Service Manager SOAP web services is performed using a bridge produced in PHP.

It uses two files:
- WebService_Config.php
- SmoBridge.php

Operating principle of a bridge

A bridge permits exposing a WEB server (PHP page) externally and not an executable that needs to own an access to the databases.

The bridge receives a SOAP call of a consumer.
It converts it into a native SMOServer call (application server).
It retrieves the answer of the SMOServer, and then converts it into a SOAP message.
It returns the SOAP message to the consumer.

WebService_Config.php File

This file allows defining the parameters for the bridge and to indicate which SmoServer (application server) must be called.

Location: http://{easyvista_path}/WebService/SmoBridge.php.
- <easyvistapath> = your EasyVista folder on the Apache server
- Caution: The address is case sensitive.

Mandatory parameters

Parameter	Description
SMO_BROKER_PORT_ID	Port of SMOBroker.
SMO_BROKER_ADDRESS	IP Address of SMOBroker.

Optional parameters

Parameter	Description
SMO_SERVER_PORT_ID	Port of SMOServer.
SMO_SERVER_ADDRESS	IP Address of SMOServer. If the address is not completed, the broker returns a valid IP Address of the SmoServer, in accordance to the algorithm of load balancing.
SmoWebService	Partial namespace defined in the WSDL.
Namespace	Namespace identifying the service.

Example

<?
define( "SMO_BROKER_PORT_ID" , 49358 );
define( "SMO_BROKER_ADDRESS" , '127.0.0.1' );
define( "SMO_SERVER_PORT_ID" , 49359 );
define( "SMO_SERVER_ADDRESS" , "127.0.0.1" );
define( "SmoWebService" , "SmoWebService" );
define( "Namespace" , "http:~/~/localhost/" . SmoWebService );
define( "CONST_WSDL" , "http:~/~/localhost/WebService/SmoBridge.php?wsdl" );
define( "CONST_DEBUG_MODE" , false );
define( "CONST_LOG_FILENAME" , "C:\www\EVO_WS\WsLog.txt" );
define( "CONST_DELPHI_WSDL" , "http:~/~/localhost/WebService/wsdl/IDelphiSmoWebService" );
?>

SmoBridge.php File

This file contains the necessary code for the interfacing of SOAP / SmoServer and all the specifications relating to the use of SOAP web services.

Location: http://{easyvista_path}/WebService/SmoBridge.php

The detail of a web service allows to display all parameters that should be provided by the consuming application in order to use this service.
See Example.