Contribute in GitHub:

Connecting through a service orchestration engine

For self-service agents, you can incorporate a service orchestration engine (SOE) into your IBM® Voice Gateway environment, which you can use to add your own layer of customization to your agent's behavior.

The service orchestration engine acts as a proxy that sits between Voice Gateway and the IBM Watson™ Assistant service, intercepting and modifying message requests and responses using third-party APIs. For example, you can intercept messages and use the data to personalize responses, such as by using customer location information to provide a personal weather forecast. For more information, see Conversation flow through a service orchestration engine.

To add a service orchestration engine to your Voice Gateway environment, complete these steps as described in the following sections:

Create a service orchestration engine application and deploy it to an application server.
Configure Voice Gateway to connect to the service orchestration engine instead of Watson Assistant.

Creating and setting up a service orchestration engine

A service orchestration engine is a separate application that you can deploy to an on-premises server or to a cloud-based environment such as IBM Cloud. The application connects to Watson Assistant and hooks in the APIs and other tools that you use to collect and analyze the conversation.

To quickly familiarize yourself with service orchestration engines, try deploying the samples in the sample.voice.gateway GitHub repository. The soe folder contains sample service orchestration engine applications in several languages, such as Java™, Node-RED, and Python. Each sample has detailed instructions to guide you through the setup process steps, including:

Setting up prerequisites, such as the required Watson services and server
Configuring the server environment to run the sample application with your Watson services
Deploying the sample application to your chosen environment

As you develop your own service orchestration engine application, keep in mind the following considerations:

REST APIs are stateless: The Watson Assistant service REST API maintains statelessness, which means Watson Assistant does not store any state information. In each Watson Assistant turn during a call, all data is passed verbatim between Voice Gateway, the service orchestration engine, and Watson Assistant on a context object within a MessageRequest object. You can store JSON data from the service orchestration within this context object and pass it back and forth as long as necessary. For example, on a Watson Assistant turn the service orchestration engine might collect an account number, which it can then pass as JSON back to Voice Gateway. Voice Gateway passes it back to the service orchestration engine for further use, and the data is maintained throughout the call as long as it continues to be passed.
You choose APIs: How your service orchestration engine functions depends on the APIs that you integrate with it. For a service orchestration engine, you might incorporate APIs for Systems of Record (SOR) or REST APIs exposed by a third-party tool or service.
Complexity equals latency: The more complex the analysis that your service orchestration engine does, the longer the whole transaction takes, which can result in noticeable latency to the caller.

Configuring the service orchestration engine in Voice Gateway

Because the service orchestration engine sits between Voice Gateway and Watson Assistant, you configure Voice Gateway to connect directly to the service orchestration engine instead of these services. The service orchestration engine is configured on the same variables as Watson Assistant, but you don't configure the workspace ID. If the service orchestration engine is configured to require authentication, specify the user name and password for HTTP basic authentication.

Table 1. Configuration for connecting to a service orchestration engine
Environment variable (single tenant)	JSON property (multi-tenant)	Description
`WATSON_CONVERSATION_URL`	`conversation.url`	The exact URL to the service orchestration engine.
`WATSON_CONVERSATION_USERNAME`	`conversation.username`	The plain-text user name for the service orchestration engine. Required only if authentication is enabled in the SOE.
`WATSON_CONVERSATION_PASSWORD`	`conversation.password`	The plain-text password for the service orchestration engine. Required only if authentication is enabled in the SOE.

Single-tenant environment: In the SIP Orchestrator configuration, configure the service orchestration engine on the environment variables.

For Docker Engine deployments, define the environment variables in the docker-compose.yml file.

WATSON_CONVERSATION_URL=https://soe-example.net
WATSON_CONVERSATION_USERNAME=adminuser
WATSON_CONVERSATION_PASSWORD=XgUCZZItgZD0

For deployments to Kubernetes in IBM Cloud Kubernetes Service, in the deploy.json file, define the environment variable name-value pairs in the env object of the vgw-sip-orchestrator container.

"env": [
  ...
  {
    "name": "WATSON_CONVERSATION_URL",
    "value": "https://soe-example.net"
  }, {
    "name": "WATSON_CONVERSATION_USERNAME",
    "value": "adminuser"
  }, {
    "name": "WATSON_CONVERSATION_PASSWORD",
    "value": "XgUCZZItgZD0"
  }]

Multi-tenant JSON configuration: In the multi-tenant JSON configuration file, for each tenant where you want to connect to a service orchestration engine, configure a conversation object:
```
...
"conversation": {
"url": "https://soe-example.net",
"username": "adminuser",
"password": "XgUCZZItgZD0"
}
...
```
Dynamic configuration: You can dynamically configure whether you connect to a service orchestration engine or Watson Assistant during a call by using thevgwActSetConversationConfig action tag from the Voice Gateway API. For more information, see Dynamically configuring Watson services.