Comparing Web Services in Verastream Host Integrator 6.x vs. 7.x

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	Earlier Versions
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)
Enablement process	Automatic when model package is deployed		Manual build and deployment, which must be repeated when model is changed
Configuration	Administrative Console (See Configuring Version 7.1.1142 below)	Edit service-ctx.xml file (See Configuring Version 7.0 through 7.1.221 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)		Not supported
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 service-ctx.xml file.	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 _HIDE suffix.
Default port numbers	9680 (standard non-secure) 9681 (secure)		8081 (Java) 80 (.NET)
WSDL document location URL	In addition to the URLs supported in version 7.0+: List of WSDL documents available at http://<session server>:9680. 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: http://<session server>:9680/vhi-ws Connect to model (non-pooled): http://<session server>:9680/vhi-ws/model/<model name>?wsdl Connect to session pool: http://<session server>:9680/vhi-ws/session/<pool name>?wsdl See also Version 7.x Naming Tip below.	Java web service: http://<host name>:8081/axis/services/<project name>?wsdl .NET web service: http://<host name>/<project name>/<project name>.asmx?wsdl 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)	Edit the plugin-cfg.xml file (as described in Configuring Version 7.1.1142 below) to configure the domainName key (and serverName for a non-local management server, or management server cluster failover name as described in KB 7021563). Alternatively, you can specify DomainName and ServerName environment variables in your SOAP request, which takes precedence over the global configuration in the plugin-cfg.xml file.	Edit the service-ctx.xml file (as described in Configuring Version 7.0 through 7.1.221 below) to uncomment and configure the domainName property (and serverName for a non-local management server, or management server cluster failover name as described in KB 7021563). Alternatively, you can specify DomainName and ServerName environment variables in your SOAP request, which takes precedence over the global configuration in the service-ctx.xml file.	In Web Builder project properties, select the connect method “Connect to model via domain” or “Connect to session pool via domain.”
WS-I compliance	Yes		Yes (version 6.6); can also support older non-compliant Microsoft Data Set return type.

Additional Information

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:

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:

Description	Key	Original Default
HTTP web service port	hostPort	9680
HTTPS web service port	secureHostPort	9681
HTTP basic authentication for client user authorization without WS-Security	authnMetadata and authnService	false

The following values are configurable in the plugin-cfg.xml file:

Description	Key	Original Default
Session server load distribution domain	domainName	(null)
Non-local management server for load distribution domain	serverName	localhost

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:

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:

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:

1. 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>.
2. In a text editor, open the project.properties file.
3. Add the following line:

4. Close and re-open the Web Builder application.

Legacy KB ID

This article was originally published as Attachmate Technical Note 10092.