Technical Notes

Web Services in Verastream Host Integrator
Technical Note 10092
Last Reviewed 13-Oct-2011
Applies To
Verastream Host Integrator version 6.0 through 7.1 SP1
Summary

This technical note describes web services functionality provided by Verastream Host Integrator (VHI) and how it differs from earlier product versions.

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	Unique value to avoid conflicts when the WSDL is imported into other tools. Model (non-pooled): urn:xmlns:attachmate:vhi-ws:model:<model name> Session pool: urn:xmlns:attachmate:vhi-ws:session:<pool name>		.NET web service in version 6.6.188 and earlier: http://tempuri.org/ Java web service in version 6.6.188 and earlier: http://<host name>:<port>/axis/services/<project name> Default for web service projects in Web Builder version 6.6.189 and higher: urn:xmlns:attachmate:vhi-wb-ws:<project name>
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 service-ctx.xml file (as described in Configuring Version 7.0 through 7.1.221 below) to uncomment and configure the global methodTimeout property (default 30000 msec). 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)	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 Technical Note 10103). 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 Technical Note 10103). 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 more information on manually restarting the service, see Technical Note 10004.

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 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.

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:

• You can require client authentication by enabling security on the session server (configured in Administrative Console). Authorized client users are configured in the User profile (Perspective > Management > Authorization). You can add users or groups from an LDAP directory server, or from a local OS group on the system running Verastream Management Server (after enabled in Perspective > Management > Directories).
• User credentials can be sent in a channel in the SOAP header, in accordance with Web Services Message Security 1.1 (WS-Security 2004) and Web Services Security UsernameToken Profile 1.1.
• HTTP basic authentication is also supported by the web service. Note the credentials are cached by the web service and not passed to the session server until a subsequent SOAP request is received. If the user is unauthorized, the initial HTTP authentication will appear to succeed but the SOAP request will fail. To enable basic authentication, edit the configuration file to change the authnMetadata and authnService properties.
• If your client does not support the above standards, inband equivalents are enabled by default, so information is passed in the data payload.
• To ensure confidentiality, use an HTTPS encrypted communications channel when sending User profile credentials (for client authentication) or host credentials (in model variables) because this data is transmitted as clear text.

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 Technical Note 10130.

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 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:

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.

Related Technical Notes

10004	Manually Starting and Stopping VHI Services
10091	Features Introduced in Verastream Host Integrator 7.0
10098	Errors in Microsoft Visual Studio When Using Verastream Host Integrator 7.x Web Service
10103	Configuring Verastream Management Server Failover
10113	Changing Verastream Host Integrator WSDL References
10115	Features Introduced in Verastream Host Integrator 7.1
10118	Web Services Explorer "Errors were encountered while validating XML schemas"
10119	Errors in Microsoft InfoPath 2010 with Verastream Host Integrator 7.x Web Service
10120	Web Builder User-Defined Project Type Issues After 7.1 Upgrade
10125	Verastream Host Integrator 7.1 Service Pack 1 - Features, Fixes, and Release Notes
10130	Disabling WS-Resource in Verastream Host Integrator
40024	Deploying a Java Web Service to a Linux/UNIX Server