Last time (see Calling a Watson REST service on Bluemix that expects a file as input parameter), we were exploring the first part of the file support within the REST invocation capability that was added in the IBM Business Process Manager (BPM) V8.5.7 CF2016.12 cumulative fix. We were invoking the Speech to Text Watson service on IBM Bluemix. This service requires a file to be sent as one of the request parameters. Today we look at the other way: a service that returns a file. We will call the Text to Speech Watson service on IBM Bluemix.
Bluemix setup & Service Definition
The last post included a detailed step-by-step guide on how to create a service instance in the IBM Bluemix platform and on how to download the OpenAPI documentation file. You can adopt these steps to create your instance of the Text to Speech service and to download the documentation file. Once you are finished you will have:
- A service instance and credentials that contain the service URL and the user and password
- The OpenAPI documentation file
With these, you are ready to use the service in IBM BPM.
Discovering the REST service in IBM BPM
In IBM BPM, we need to discover the REST service as external service to later call it. The steps again match what was done in the last post to discover the Speech to Text service. Adopt those and you will have these artifacts in your process application:
- An external service for the Text to Speech REST service
- Some business object types related to the discovered service
- A REST server with the endpoint information. There you use the host name, user and password from your service credentials.
Using the REST service in IBM BPM
We are now ready to invoke the REST service. Let’s build a process with a user task that allows an end user to enter some text. This text is sent to the Text to Speech service in a system task. In a second user task, we play the response of the service. Here is how the diagram looks like:
The first user task is straight-forward. You implement it with a human service with one text input that is passed to the process.
More interesting is how to implement the Call Text to Speech activity. For this, we create a service flow with these variables:
The ECMDocumentInfo business object type is from the Content Management toolkit and represents the file reference to the result of the REST operation.
As the service flow diagram, we just need one script:
In the script, we invoke one operation offered by the Text to Speech service: postSynthesize. Here is an extract of the OpenAPI documentation of the required parameters only.
To invoke the operation we use the BPMRESTRequest and the tw.system.invokeREST function.
// Create BPMRESTRequest object with all information for the request
The response of the operation is the file type as specified in the OpenAPI documentation. IBM BPM in this case automatically stores the response as a local document and returns its reference information as the response content as ECMDocumentInfo object. The object contains the name of the ECM server (always the server name of the IBM BPM document store) and the document identifier. With them, you can run Content Integration steps to do whatever is needed with the document, for example to retrieve the content. You can also pass the object as input into another REST operation that requires a file as input parameter to build a service orchestration.
Or, you just show it to an end user, which is what we do in the second user task. As its implementation, we create a client-side human service with the speech variable as input. In a coach, we place the Document Viewer coach view and bind it to this variable. Note that this requires that the browser can play the audio file – this works in my Google Chrome 56 and Mozilla Firefox 45, but not in Internet Explorer 11.
And that’s it. You can find the complete process application here: BPM_ECM_blog_-_REST_service_invocation_with_file_response - V2.twxView Details
We have invoked a REST service that returned a file. In our example, we sent some text to the Text to Speech service on Bluemix to return us an audio file.
You can further extend this example if you want:
- You can use a toolkit to discover the external services and to define the service flows that calls the service. You can use this toolkit from multiple process applications.
- You can pass in the voice parameter into the REST operation to synthesize using a female voice or to use a language other than English.
- You can also use the voices operation to retrieve the available voices and build a user interface where the end user chooses the voice.
If you ask how you can use this in a real-life scenario, then think of people with a visual impairment. Instead of sending them letters they find hard to read, you could send them voice messages.