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. Open url.png 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

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

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.

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.
             Open url.png  See Example.

List of the Service Manager SOAP web services

Equipment

Employees

Tickets

Note: The Tickets term includes incidents, service requests, change requests, investment requests, problems, events.

Actions

Others

Tags :
Powered by XWiki © EasyVista 2022