Creating a web service

You can create a web service in IBM® Business Automation Workflow that you expose to exterior systems so that they can access functionality in an Business Automation Workflow application.

Before you begin

By default, the enable-advanced-parameter-properties-for-wsdl configuration property is set to the value false for backward compatibility reasons. Unless you have strong backward compatibility requirements for already existing web services, you should change the value of this property to true. If you change the configuration property to true, you can still retain compatibility by adjusting the advanced parameter properties of business objects used by these web services.

Important: Setting the value to true will affect all inbound web services.

For more information, see the following topics:

About this task

To provide a way for an external system or application to call into Business Automation Workflow, create and publish a web service endpoint. The web service endpoint invokes an operation that calls a particular Business Automation Workflow service or set of services.

All operations that you expose in a web service are request-response operations. Even an operation that is bound to a service that has no outputs is still a request-response operation that has no output. One-way operations are not supported.

Tip: The endpoint address for a web service is in the following format: http://host_name:port/[custom_prefix/]teamworks/webservices/process_app_name/[snapshot_name/]web_service_name.tws.

If you do not specify the snapshot_name in the endpoint URL, it points to the tip snapshot for Workflow Center or to the default snapshot for Workflow Server.

Procedure

Open a process application in Process Designer.
Select the plus sign next to the Services and then select Web Service from the list.
Name the new web service.
The web service editor opens.

In the Behavior section:

If you want to add user name and password security to the operations, enable Protected.
The user name and password must be registered at the server and the user name must have at least read access to the process application. Note that the protection is not authentication in the context of an HTTP transaction, so selecting Protected does not display a default user ID and password.
Notice the WSDL URI in the Behavior section. You can use this URI to test the exposed web service.

Set the scheme used to create the target namespace for the web service in Target namespace scheme. The target namespace depends on the scheme that you pick, the namespace setting in the process app or toolkit settings, and the snapshot. See the table below the scheme options for more information..

Use process app or toolkit settings (default): Use the namespace from the XML Settings section of the Process App Settings page and do not include the snapshot name. This is the recommended setting because the target namespace remains consistent across multiple snapshots.
Important: If the process application namespace is not set, the scheme instead uses the host and port of the local machine and, if it exists, the snapshot name.
Use snapshot name: Use the snapshot name as well as the namespace from the XML Settings section of the Process App Settings page. This means that the target namespace value in the web service client targets a specific snapshot.
Important: In the following situations, the namespace of the Web Services Description Language (WSDL) file changes and you must obtain a new file to maintain consistency between the namespace used by the client and the namespace on the server:
- When the application namespace is not consistent with the namespace on the server.
- When the host name and port changes and the exposed web service uses a business object defined in the System Data toolkit, which uses a host name and port specification.
- When you create a snapshot and switch a service to the exposed web service in the new snapshot.
- When you switch from a specific snapshot to the default snapshot or from the default snapshot to a specific snapshot.
Remember: Versions of Business Automation Workflow before 8.0.1 use, in effect, the snapshot name scheme.
Custom: Use only the value specified in the Target namespace field.

The following table shows the resulting target namespace depending on the value you choose for the scheme, the namespace setting for the process application, and where the web service is running.

Combination	Resulting URI
Process App namespace set to `http://xyz` value Use process app or toolkit scheme	`http://xyz/web_service_name.tws`
Process App namespace set to `http://xyz` value Run on a snapshot that is not tip or default Use snapshot scheme	`http://xyz/snapshot/web_service_name.tws`
Process App namespace set to no value Run on a tip or default snapshot Use process app or toolkit scheme or Use snapshot scheme	`http://host:port/teamworks/webservices/ proc_app/web_service_name.tws`
Process App namespace set to no value Run on a snapshot that is not tip or default Use process app or toolkit scheme or Use snapshot scheme	`http://host:port/teamworks/webservices/ proc_app/snapshot/web_service_name.tws`
Use Custom scheme	`http://custom_namespace`

Select the SOAP version you want to use.

Note: SOAP header information is available in system variables. The tw.system.soap.header.request variable is automatically initialized to contain the list of SOAP header entries found in the incoming request message. You can include JavaScript code with your inbound web service which accesses these SOAP header entries. You can also write JavaScript code which adds SOAP header entries to the tw.system.soap.header.response system variable. The SOAP header entries contained in this variable are added to the outbound response message.

For each function that you want your web service to support, add an operation. In the operation details, name the operation and attach the service flow that provides the functionality to the operation.
For information about service flows and how to create them, see Creating a service flow.
Tip: By default, the list of services that you can attach contains only service flows. If you want to attach a service created in Business Automation Workflow V8.5.7.0 or earlier and it has not been converted into a service flow, select the Show heritage services checkbox at the bottom of the list service. The list of attachable services now includes these services. They are categorized according to their type. These services are not editable in the web Process Designer. If you want to edit them, you must open them in the desktop Process Designer.
In the Policy section, specify the application policy set and then specify the policy binding for the web service.
- Policy set: Select the application policy set from the list available on the server. Selecting no policy set removes any existing policy binding.
  The policy set contains configuration and security settings. For additional information about policy sets, see the IBM Redbook WebSphere Application Server Web Services Guide. Some default application policy sets include WSHTTPS default, WSAddressing default, and Username WSSecurity default. You can also create custom application policy sets in the WebSphere Application Server Administrative Console.
- Policy binding: After you have selected the policy set, select the policy binding from the list of general provider policy set bindings available on the server. The policy binding is not available until you select the policy set that the binding applies to.
  The policy binding contains the system-specific configuration parameters like username and password information. Default policy set bindings include Provider sample and Provider sample V2. You can also create custom policy set bindings in the WebSphere Application Server Administrative Console.
Click Save or Finish Editing.