Configuring Business Automation Workflow endpoints to match your topology

If the user's browser requests pass through a web server or load-balancing server before the request reaches the Business Automation Workflow server, you must configure the virtual host information that is used by Business Automation Workflow to generate URLs. Depending on the complexity of your topology and security setup, you might have to configure several different types of URLs.

Before you begin

This task uses the setBPMVirtualHost, setBPMDefaultVirtualHost, and setBPMEndpoint commands, which are run using the AdminTask object of the wsadmin scripting client. To run the commands, the following prerequisites must be met:

The commands must be run on the deployment manager node.
If the deployment manager is stopped, use the wsadmin -conntype none option to run the commands in disconnected mode.
If the deployment manager is running, you must connect with a user ID that has WebSphere Application Server configurator privileges. Do not use the wsadmin -conntype none option.

Start the wsadmin scripting client from the deployment_manager_profile/bin directory. The setBPMVirtualHost, setBPMDefaultVirtualHost, and setBPMEndpoint commands do not write to a log file, but the wsadmin scripting client always writes a profile_root/logs/wsadmin.traceout log file where you will find exception stack traces and other information.

About this task

Business Automation Workflow generates many different types of URLs for action links in the external browser client, internal communications, and connections to internal services. If your topology or security setup requires that Business Automation Workflow must generate certain types of URLs differently, there are various ways to configure them.

It is important to identify the different entry points in your network, such as load balancers and web servers, for external and internal clients. For example, generally, the protocol, host name, and port number of the entry point server must be used in any generated links that are served to clients. Sometimes the endpoints can be defined as a static URL, but in more complex topologies it might be necessary to use a dynamic strategy, such as extracting the information from the header of the request.

In simple topologies, the defaults should work without any changes. Generally, a production environment requires some changes to the defaults. For example, if you have a web server for external clients, see Customizing IBM BPM to work with a web server.

More complex topologies and ones that include multiple deployment environments require more targeted configuration of specific objects.

For each scenario, if the url attribute is specified, that URL is returned before any of the strategies are attempted.

For each scenario, the strategies are attempted in the order that they are listed until one returns the required information. Each strategy uses a different approach to determine the transport protocol, host, and port that are used to generate URLs, for example, by extracting them from a particular header in the request.

When an endpoint lookup is required by a particular product feature, there is an optional and a default scenario associated with each specific lookup. When the lookup is performed, the following actions are taken in order until an endpoint URL value is returned.

The optional scenario is checked.
The default scenario is checked.
The default virtual host for the deployment environment is checked.
The CurrentJVMDefaultTransportStrategy is used.

By default, most lookups will use the CurrentJVMDefaultTransportStrategy if no changes have been made to the endpoint settings, which results in a URL pointing at the HTTPS port of the current JVM. For most cases, you can modify only the default scenarios or rely on the default behavior.

Procedure

To configure the endpoints, complete the following actions:

Identify the components and structure of your topology. Components to consider include such things as load balancers, external web servers, reverse proxies, firewalls, internal web servers, process servers, and process centers.
Identify which default scenarios you must modify, and decide whether to use a virtual host object, a URL, or a list of dynamic strategies to determine the correct endpoint. See Default IBM BPM endpoint scenario keys and Strategies for identifying endpoint information.

Connect to the wsadmin client by entering the following command:

wsadmin.bat -conntype NONE -lang jython

wsadmin.sh -conntype NONE -lang jython

Change the default scenarios as required for each deployment environment. See Changing default scenarios.
If you have a complex topology, you might need to configure optional scenarios for specific types of generated URLs. See Setting up optional scenarios for complex topologies.
Activate the new settings by performing a ripple start of your clusters.
Optional: Verify that the endpoints that you configured are working as expected.
Workflow Center environments provide a servlet to verify the configuration of the endpoint service. It can be accessed at the following URL:
```
/ProcessCenterInternal/endpointUrl?specificScenario=EXPOSED_ITEMS&defaultScenario=EXTERNAL_CLIENT&webAppName=teamworks.war
```
Depending on which endpoints you configured, check that the clients that are affected by the endpoint changes are working correctly. For example, any changes to a scenario with a key that starts with the string PROCESS_PORTAL can be tested by using Process Portal from a browser. If there are any problems, check and correct the endpoint settings for URLs that are not working.
If you are using Business Space and the federated REST API, you need to ensure that you update the URLs in the REST Services Gateway as in earlier versions of the product. See the topic REST service providers configuration.

Results

All URLs that are generated by Business Automation Workflow work correctly in your topology.