SOAP Web Services
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.
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
- The expected value by the parameter is specified in the file SmoBridge.php.
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:
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.
|
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.
List of the Service Manager SOAP web services
Equipment
- Create an item of equipment: EZV_CreateEquipment
- Update an item of equipment: EZV_ModifyEquipment
- Create an item of equipment using an XML structure: EZV_CreateEquipmentXML
- Update an item of equipment using an XML structure: EZV_ModifyEquipmentXML
Employees
- Create an employee: EZV_CreateUser
- Update an employee: EZV_ModifyUser
- Create an employee using an XML structure: EZV_CreateUserXML
- Update an employee using an XML structure: EZV_ModifyUserXML
Tickets
Note: The Tickets term includes incidents, service requests, change requests, investment requests, problems, events.
- Create a ticket: EZV_CreateRequest
- Update a ticket: EZV_UpdateRequest
- Close a ticket: EZV_CloseRequest
- Suspend a ticket: EZV_SuspendRequest
- Reopen a ticket: EZV_RestartRequest
- Create a task for a ticket: EZV_CreateTask
- Attach a document to a ticket: EZV_AttachDocToRequest
- Count the number of documents attached to a ticket: EZV_GetDocumentCount
- Search for the URL address of documents attached to a ticket: EZV_GetDocumentURL
Actions
- Create an action for a ticket: EZV_CreateRelatedAction
- End an action attached to a ticket: EZV_EndAction
Others
- Execute an internal query: EZV_SYS_ExecuteInternalQuery