This technical note describes web services functionality provided by Verastream Host Integrator (VHI) and how it differs from earlier product versions.
Web services provide a standard means of communication that enable data to be exchanged between applications over a network. The web services protocol (SOAP) consists of XML data transmitted over HTTP. Verastream Host Integrator provides web service support, which enables other applications (web service clients) to interact with host applications.
Each web service provides a Web Services Description Language (WSDL) document, which defines the operations offered and can be used by third-party tools to automatically generate client-side code.
The following table summarizes how web services functionality in version 7.1 and 7.0 compare with earlier versions.
|Web Services Functionality
||Version 7.1.1142 (7.1+SP1)
||Versions 7.0 through 7.1.221
|Component(s) providing web services
||Session server (embedded SOAP stack; does not require or use Tomcat or IIS)
||Projects created in Web Builder are deployed to Tomcat/Axis “VHI Web Server” (for Java) or Microsoft IIS (for .NET)
||Automatic when model package is deployed
||Manual build and deployment, which must be repeated when model is changed
||Administrative Console (See Configuring Version 7.1.1142 below)
||Project properties in Web Builder
|Stateful web services (multiple client calls using the same host session)
||Automatically provided with WS-Addressing and WS-Resource if your SOAP client also supports these standards. (See Stateful Web Services in Version 7.x below.)
||Requires manual modification of Web Builder-generated .asmx.cs file to use suspendSession and resumeSession methods, return a session key value on connect, and use this token as an input value for each model procedure method.
|SSL (HTTPS) encryption security
||Supported (See Encryption in Version 7.x below)
|Access control security
||Credentials can be transmitted in SOAP headers or HTTP basic authentication. (See Authentication and Authorization in Version 7.x below.)
||Credentials must be passed in the data payload as input values for the Connect method.
|Procedures and model features
||All procedures are automatically available. To enable Execute SQL Statement or the ProcessString event handler, enable options in Administrative Console > Server, Model, or Pool Properties > Web Services.
||All procedures are automatically available. To enable Execute SQL Statement or the ProcessString event handler, uncomment appropriate lines in the
||In version 6.5 or 6.6: Options are individually configured in Web Builder.
In versions 5.0 through 6.0: Procedures can be hidden by naming with
|Default port numbers
||9680 (standard non-secure)
|WSDL document location URL
||In addition to the URLs supported in version 7.0+:
List of WSDL documents available at
Links to WSDL list in Administrative Console > Server Properties > Web Services.
Links to model (non-pooled) and pool WSDLs are available in Administrative Console > Model or Pool Properties > Web Services > Show WSDL.
|List of WSDL documents for deployed models:
Connect to model (non-pooled):
Connect to session pool:
See also Version 7.x Naming Tip below.
|Java web service:
.NET web service:
The session server, model, and connection method is specified in Project Properties.
|WSDL target namespace
||Unique value to avoid conflicts when the WSDL is imported into other tools.
|.NET web service in version 6.6.188 and earlier:
Java web service in version 6.6.188 and earlier:
Default for web service projects in Web Builder version 6.6.189 and higher:
|WSDL schema organization
||Single embedded schema that uses the WSDL namespace, for compatibility with Verastream Process Designer and other BPEL technologies based on Apache ODE 1.3.x.
||Java web services in version 6.6.189 and earlier have two embedded schemas in the WSDL with two different namespaces.
|Web service client for testing
||See Testing Web Services in Version 7.1
||Version 7.1: See Testing Web Services in Version 7.1
Version 7.0: Use third-party tools, such as SoapUI, to import the WSDL and submit requests.
|Test client automatically generated by Web Builder (runClient.bat for Java; web application for .NET)
|Method timeout (how long the connector waits for response from session server)
||Configurable in Administrative Console on a global, pool-specific, or model-specifc (non-pooled sessions) basis. Default 60000 msec (60 seconds).
||Version 7.0.982 through 7.1.221: Edit the
Versions 7.0.961 through 7.0.980: Not configurable, 30 seconds.
|Configurable in the Web Builder project properties. The default is 30 seconds.
|Domains (multiple session servers in a VHI load distribution domain)
||In Web Builder project properties, select the connect method “Connect to model via domain” or “Connect to session pool via domain.”
||Yes (version 6.6); can also support older non-compliant Microsoft Data Set return type.
The following notes expand on references in the table above.
Beginning in version 7.0, model names are automatically used in the WSDL URI and target namespace. For the widest compatibility with third-party web service clients, avoid spaces in model names and session pool names (use hyphens, underscores, or mixed case instead).
Beginning in version 7.1, Web Services Explorer is a web service client you can use to test the automatic web services, thereby eliminating the need to use a third-party client such as SoapUI. Web Services Explorer web application functionality is provided by the Management Server component. To access Web Services Explorer, use any of the following methods:
http://<management server>:8095/wsexplorer/wsexplorer.jsp?com.attachmate.eclipse.wst.ws.explorer=0&mode=standalone&wsdl=http://<session server>:9680/vhi-ws/model/<model name>?wsdl
For more information on using Web Services Explorer, see http://docs2.attachmate.com/verastream/vhi/7.1/en/topic/com.attachmate.vhi.help/html/reference/web_service_test.xhtml.
Note: Web Services Explorer does not support testing web services that are protected by WS-Security, Basic Authentication, or HTTPS encryption features. If you have these options enabled in the web services SOAP stack configuration, use a third-party client for testing.
Beginning in version 7.1.1142 (7.1 Service Pack 1), web services configuration can be accomplished in Administrative Console. (The service-ctx.xml file is no longer used for web services configuration as it was in versions 7.0 through 7.1.221.)
Some options not available in Administrative Console are configurable in other XML files located in the Attachmate\Verastream\HostIntegrator\sesssrvr\services\ws\META-INF directory. Note: These XML files are created after web services are initially configured.
The following values are configurable in the service-cfg.xml file:
|HTTP web service port
|HTTPS web service port
|HTTP basic authentication for client user authorization without WS-Security
The following values are configurable in the plugin-cfg.xml file:
|Session server load distribution domain
|Non-local management server for load distribution domain
Note: After saving changes to these files, you must restart the session server service to for changes to take effect. For more information on manually restarting the service, see Technical Note 10004.
To configure version 7.x web services, edit the service-ctx.xml file located in the following directory:
Windows: C:\Program Files\Attachmate\Verastream\HostIntegrator\sesssrvr\services\ws\META-INF
For example: To configure different port numbers, change value for the hostPort or secureHostPort properties.
After saving changes to this file, you must restart the session server service to for changes to take effect. For more information on manually restarting the service, see Technical Note 10004.
Note: When you upgrade to a later version (hotfix or major release) in the future, the service-ctx.xml file may revert to new defaults. It is recommended that you make a backup copy of your edited service-ctx.xml file. After upgrading in the future, use the backup copy as a guide for editing the installed service-ctx.xml file.
Regarding SSL encryption security in version 7.x:
Version 7.1.1142: Uncheck "Enable HTTP Web Services" in Administrative Console > Perspective > Host Integrator > Session Servers > Installation > Servers > your server name > Properties > Web Services.
Versions 7.0 through 7.1.221: Edit the service-ctx.xml file to change the httpEnabled property to false.
Note: Verastream Process Designer R3 does not support connections to encrypted web services.
Regarding client authentication security in version 7.x:
Regarding stateful web services in version 7.x:
For compatibility with some technologies, WS-Resource (Web Services Resource 1.2 Framework) can be disabled in the embedded web service configuration. To disable this feature, see Technical Note 10130.
If you have an existing Java or .NET web service project in Web Builder, you can continue to re-build and re-deploy it after upgrading to version 7.x.
By default, Web Builder no longer supports creating new web service projects. If you need to enable the deprecated web service project types for new Web Builder projects, please contact Support at http://support.attachmate.com/contact/.
If your web service project is based on a user-defined project type (rather than an installed standard project type), see also Technical Note 10120.
If your existing web service project (created in version 6.6.188 or earlier) does not display in Web Builder version 7.0.961, complete the following steps:
where myvalue is any non-blank string, such as the project name or urn:xmlns:attachmate:vhi-wb-ws:<project name> (the default value for new web service projects in version 6.6.189 or higher).