Skip to content

About Verastream Web Services

Providing a Web service to your host applications enables rapid reuse of the business logic that exists on these hosts. Web services provide reusable APIs for creating portals, Web applications, and other business solutions. And, because they are technology independent, they can run on any platform. Developers can use utilities to generate specific files to locate and consume the Web service.

Web Service Standards

Host Integrator, at model deployment, generates both a SOAP (Simple Object Access Protocol) Web service and a REST (REpresentational State Transfer) service that uses JSON (Java Script Object Notation) to call VHI procedures from a Web application.

  • VHI SOAP-based Web services adhere to WS-Standards, which includes WS-Resource, WS-Security, and WS-Addressing. These standards follow a third-party specification. In most cases proper SOAP headers are generated to use these standards and it is unnecessary for you to write separate code, however some applications may not be able to consume these features for various reasons. The Web service standards are turned off by default. This setting can be changed on the Session Server Web Service Property panel in the Administrative Console.

    See a List of Web Service Specifications for a description of WS-Security, WS-Addressing, and WS-Resource.

  • VHI REST services use JSON as the data carrier, and, like the SOAP-based services, runs over HTTP.

Deploying the Web Service

In VHI, after a model is deployed using the Design Tool, Web services are automatically provided by the session server as both an embedded SOAP stack and as a REST service. The embedded Web service supports all model procedures and features, including executeSQLStatement and ProcessString event handlers.

Metadata request format

  • SOAP request - http://host-name:port/vhi-ws/model-or-session/model-or-pool-name?wsdl

  • REST request - http://host-name:port/vhi-rs/model-or-session/model-or-pool-name?json

About Model and Environment Variables

Model variables and environment variables are an optional part of every SOAP or REST document that a client submits to a VHI Web service to invoke a Web method. Although these elements are optional, meaning that the WSDL and schema, or REST metadata, do not require them in the syntax, a given application may require them to be specified to run successfully.

After you deploy your model to the session server, you can view and test the model to see if the Web service that is created works as expected, by clicking Test on the Deployment Successful message box to open the Web Services Explorer. In the Web Services Explorer you can add, remove and view model and environment variables.

Model variables

By default, VHI creates three model variables whenever a model is created. Any user-defined model variables that you create also are listed. How these user-defined variables are used and their semantics are application-dependent.

Model variable Description
userID Created by default. Specify a userID if needed when executing a VHI procedure
Password Created by default. Specify a password if needed when executing a VHI procedure
Cursor position Created by default. Specify the cursor position if needed when executing a VHI procedure
Additional user-defined model variables You can specify other application-specific data when executing a VHI procedure

Note

Within Web services there is a method, getModelVariables, that you can use to query the current settings.

Environment variables

VHI uses environment variables to communicate to the service how to run. For example, what server or domain to use.

Environment variable Description
DomainName Use this variable to have the client use the connect via domain feature when you execute a VHI procedure. If this option is not specified, VHI will invoke the procedure with using connect via server.
ServerName Use this variable to have the client specify the management server for connect via domain, or to specify an alternate session server when not using the connect via domain option. The default is localhost.
SessionID Use this variable to have the client specify a suspended session when using stateful Web services. SessionId is obtained from wsResourceCreate, and is valid until wsResourceDestroy is used to release the session.
Password This variable has the client specify a password when executing a VHI procedure as required with session server security enabled.
Username This variable has the client specify a user name when executing a VHI procedure as required with session server security enabled.
VmrPrefix Specifies a model debug file name prefix for this web method invocation. This variable is ignored unless model debug recording is enabled.

Note

When using SOAP Web services, if WS-Addressing, WS-Resource, or WS-Security are enabled in the Administrative Console, then, using the WS-Addressing, WS-Resource, and WS-Security specifications, the SessionID, Password, and Username information can be placed in the SOAP header instead.

Web Services Ports

Web Services deployed to the session server are set by default to run on HTTP port 9680 or HTTPS port 9681.

Using the WSDL Document

The Web Service Description Language (WSDL) document describes the interface to the Web service, the data types it uses, and the location of the service. Developers use this document to identify inputs, outputs, and methods needed to consume the Web service. Web services generation utilities use the WSDL document to create proxy objects and sample code for the services.

You can access your Web services WSDL documents here:

http://<session server>:9680/vhi-ws for a list of available WSDLs

For example:

http://<session server>:9680/vhi-ws/model/<model name>?wsdl for a non-pooled model

http://<session server>:9680/vhi-ws/session/<pool name>?wsdl for a pooled session

-or here-

https://<session server>:9681/vhi-ws for a list of available WSDLs

For example:

https://<session server>:9681/vhi-ws/model/<model name>?wsdl for a non-pooled model

https://<session server>:9681/vhi-ws/session/<pool name>?wsdl for a pooled session

Using the REST Document

Just like XML, JSON (using JavaScript syntax) is text only and thus can be read and used as data input by any programming language. However, unlike XML, JSON is very light-weight and easy to read. It is also very widely used for interchanging data on the Web.

JSON documents are an easier to use alternative to XML and follow this simple format:

{"employees":[
    {"firstName":"John", "lastName":"Doe"},
    {"firstName":"Betty", "lastName":"Brown"},
    {"firstName":"Michael", "lastName":"Jones"}
]}

You can access all available REST services for models or sessions deployed to the Host Integrator session server here:

http://<session server>:9680/vhi-rs

For example:

http://<session server>:9680/vhi-rs/model/<model name>?json for a non-pooled model

http://<session server>:9680/vhi-rs/session/<pool name>?json for a pooled session

-or here-

https://<session server>:9681/vhi-rs

For example:

https://<session server>:9681/vhi-rs/model/<model name>?json for a non-pooled model

https://<session server>:9681/vhi-rs/session/<pool name>?json for a pooled session

Example

Take a look at a REST Web application that uses the CICSAcctsDemo model to demonstrate Host Integrator's REST service. It provides an example of both a stateful and stateless procedure call.

Prerequisites

  • Using the Design Tool, deploy CICSAcctsDemo to localhost. The model is located here: .../Micro Focus/Verastream/HostIntegrator/examples/ModelSamples/CICSAcctsDemo.
  • Verify that the security option is disabled in the Administrative Console. This option is disabled by default and can be found under Session Server Properties > General Properties > Security.

Managing Web Service Settings

You use the Administrative Console to enable and disable all VHI Web services. In the Properties panels of the session server, model and session pool configurations you can set server-level policies as well as options for specific models and session pools.

  • Server level properties set Web service configurations, including enabling HTTP or HTTPS connections and other Web service elements. You can also decide whether to make Web services available for models and pools and link to the list of all available Web services.
  • Model level properties display information and options for the Web service associated with the selected model that is deployed to the session server. This is where you can override the session server values for a particular model.
  • Session pool level properties contain settings to configure the Web service for a particular session pool. This is where you can override the session server properties set for the Web service and view the Web service documentation.