This technical note describes web services functionality provided by Verastream Host Integrator (VHI) and how it differs from earlier product versions.
Note: This technical note applies to older product versions. Information has not been updated to address changes in configuration and features introduced in versions 7.5 and higher.
About Web Services
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.
What's New in Version 7.x Web Services
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.)
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
|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
||See KB 7021323
|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)
||See KB 7021534
|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.
Version 7.x Naming Tip
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).
Testing Web Services in Version 7.1
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:
- Click the "Test" button displayed by Design Tool after successfully deploying a model
- Click the "Test" link displayed in the list of WSDLs for deployed models at http://<session server>:9680/vhi-ws
- In a web browser, open the following URL:
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.
Configuring Version 7.1.1142
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 information on manually restarting the service, see KB 7021352.
Configuring Version 7.0 through 7.1.221
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 information on manually restarting the service, see KB 7021352.
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.
Encryption in Version 7.x
Regarding SSL encryption security in version 7.x:
- To add a CA-signed certificate for SSL, place it in the server keystore using the Java JSSE keytool. If no certificate exists in the HostIntegrator\sesssrvr\etc directory, a self-signed certificate is generated for non-production purposes.
- To disable the non-secure HTTP port:
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.
Authentication and Authorization in Version 7.x
Regarding client authentication security in version 7.x, see Connection C in KB 7021314.
Stateful Web Services in Version 7.x
Regarding stateful web services in version 7.x:
- Sessions are suspended with a default timeout of 60 minutes; sessions not resumed within this period are automatically terminated by the session server. Beginning in version 7.1.1142, the suspend timeout can be modified in Administrative Console. In version 7.1.221, the suspendTimeout value can be modified in an XML file (see Configuring Version 7.0 through 7.1.221).
- Stateful web services are implemented in accordance with Web Services Resource 1.2 (WS-Resource) Framework, Web Services Resource Lifetime 1.2 (WS-ResourceLifetime), Web Services Resource Properties 1.2 (WS-ResourceProperties), and Web Services Base Faults 1.2 (WS-BaseFaults).
- With WS-Resource, wsResourceCreate returns a SessionID, which is used in subsequent web method requests (with wsa:isReferenceParameter="true") and wsResourceDestroy releases the session.
Disabling WS-Resource in Version 7.1
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 KB 7021336.
Upgrading to Version 7.x
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 https://support.microfocus.com/contact/.
If your web service project is based on a user-defined project type (rather than an installed standard project type), see also KB 7021580.
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:
- In Web Builder version 7.0.961, right-click the project and click Explore. This will open the project folder, such as C:\Program Files\Verastream\HostIntegrator\projects\<project name>.
- In a text editor, open the project.properties file.
- Add the following line:
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).
- Close and re-open the Web Builder application.