Watson Assistant just got connected!
Building and scaling a virtual assistant these days requires integrating with several third-party APIs. Together, IBM App Connect and Watson Assistant make that integration easier than ever.
In the world of virtual assistants, integrations are critical if you’re building anything more than a basic FAQ BOT. In fact, if you talk to anyone who has ever created an assistant that relies on a wide range of cloud services to deliver a complex conversation flow, you’ll find that one of the biggest challenges they faced was integrating with various APIs to deliver the solution.
Watson Assistant just recently released a new feature called extensions that makes the assistant developer’s job way easier when it comes to integrations. This new feature allows developers to register an external RESTful API with their assistant using a widely supported API specification standard called OpenAPI (formally known as Swagger). You can read more about this new extensions feature in Watson Assistant here.
By adding support for OpenAPI, Watson Assistant has taken a major step forward in its ability to integrate with external enterprise APIs. One of the really cool things this enables is a simple way to integrate with a category of applications known as Integration Platform as a Service (or iPaaS). An iPaaS is a platform that standardizes how applications are integrated into an organization, making it easier to automate business processes and share data across applications. There are several iPaaS products in the market including MuleSoft, Zapier and others, but one of the best is IBM App Connect. IBM App Connect comes pre-built with hundreds of connectors that can be wired together into all kinds of powerful business flows using their low-code, web-based tooling.
The remainder of this article will demonstrate how to do a quick integration with a simple API exposed from App Connect. The focus is on the integration between Watson Assistant and App Connect, not to show off all the things you can do with App Connect. This resources page is a good place to go if you want more details on what App Connect can do for your business. Note also that the pattern described in this blog can be applied to the other IPaaS platforms listed above.
Let’s build a simple API in App Connect
For the purposes of this demo, my App Connect API will only write a ticket to a Cloudant database and return the ticket number which will be the document ID returned from Cloudant. After you create your App Connect service instance in IBM Cloud you can create an API flow from the App Connect home page by clicking on “Create flows for an API”. You’ll see a page like this:
After you add the API name and the name of your model, click the “Create model” button. You will then be asked to enter your API properties. You can see the three I added here:
Next create the API operation needed to insert the ticket into the database.
Now that we have our “Create Ticket” operation we need to implement the flow for this API operation. This is where you can start pulling connectors from the catalog. Get started by clicking the “Implementation flow” button shown in the diagram above.
From here you can click the + button between Request and Response and add as many connectors as you would like. In this case I am going to add a single connector labeled “IBM Cloudant”. You should setup a Cloudant service instance in your IBM cloud account and create a database within that service instance for use in this demo before doing this step.
Now add your account details, select which Cloudant operation you want to perform and select the database you want to perform the operation on. I skipped a few steps but you can see the end result here. I setup a create document operation using the ticket_id passed into the request as the document ID and I mapped two additional document properties to store the user_name and issue_details:
Now you have to map the resulting ticket_id from the ticket created in Cloudant into the API response. Click on the response icon to do this. In this example I am only returning the ticket_id and I’m mapping it to the document ID returned from Cloudant:
You now have a basic flow setup in App Connect to store a newly created ticket into a database called “tickets”. It’s now time to startup your new flow. You can do this by clicking “Done” and then clicking the three dots in the upper right corner of the screen where you’ll find the “Start API” menu item:
Now all that’s left to make your API visible to the world is to configure security. You do this by clicking on the Manage icon and then scroll down to the section titled “Sharing outside of Cloud Foundry organization” and then click on the “Create API key and documentation link” button. Take note that this API key will be used when you create the extension for this API flow inside of Watson Assistant to configure authentication. After you create your API key the page should look something like this:
You’re now almost ready to integrate this new App Connect enabled API flow with your assistant. The next step is to extract the OpenAPI (Swagger) specification of the API you just created. This can be done by going to the “API Documentation Link” shown in the above screen shot. This link points to a page that looks like this:
From here you can download the OpenAPI document associated with your API by clicking the download arrow. This will download an OpenAPI v2 yaml file to your local browser’s download folder. This files contains all the details about your API including:
- Properties
- Methods
- Endpoint URL
- API security type (no API keys are included in the OpenAPI spec)
Convert the OpenAPI spec for Watson Assistant consumption
For Watson Assistant to use this file, it must be converted to an OpenAPI v3 JSON version of the spec. Fortunately, you can use a free swagger.io account to convert the file into the format required by Watson Assistant. First, upload your OpenAPI v2 yaml file to your swagger hub account:
Next convert the API from OpenAPI v2 to OpenAPI v3. This menu entry is available under the Save button:
Now all that’s left is to export the OpenAPI file in JSON format (instead of yaml):
You should use the JSON Unresolved format so that API references will be maintained.
Create your extension in Watson Assistant
Now for the easy part. You’ve built your API flow in App Connect and you’ve converted the OpenAPI file into a format that can can be consumed by Watson Assistant. Next step is to build the extension in Watson Assistant for this new API.
First thing to note is that extensions are only available in the new Watson Assistant experience and can only be used with Actions. In the new experience you first go to the Integrations page by clicking the icon at the bottom left. From here click the blue button titled ‘Build custom extension’.
This will next take you to a page where you will have to provide some details about your extension including the extension name and a description of your extension:
Next you will import the OpenAPI spec you created above.
When you hit next you will see a summary of the API you just imported. At this point the extension has been created and is shown within your assistant’s catalog.
Just because its in your catalog doesn’t mean your assistant is ready to use it. For your actions to start working with the new extension you now have to add it to your assistant’s draft environment (note that you will have to do this again for your live environment which can be configured differently if needed). Click the add button at the bottom right of the extension to start the add process:
Remember above when I mentioned that you would need the API key to configure authentication for the extension? This is when you copy the API key associated with your App Connect flow into the configuration for your extension. Note that you can have an extension for both your draft and production environments that contain two different API keys and two different endpoint URLs.
Click next and you have a chance to review all the settings related to the extension for the current environment which should be ‘draft’ as this point.
It’s time to use your new extension!
At this point everything is in place for your actions to use your newly added App Connect extension. This section will walk you through exactly how to setup a simple action that uses the extension.
Let’s start by adding an action that will trigger off of the phrase “I want to open a ticket”. In this action, the first two steps are used to collect the user name and then the issue details:
With this information we now have all we need to call out to the extension hosted in App Connect. Next create a new step that maps variables to the extension method for creating a new ticket. You can see below I simply generated a random number for the ticket_id:
In the last action step we read back the ticket number to the user. This is pulled from the message body associated with the extension response:
You can now test out your extension! Note that currently extensions do not work with the Preview panel found within actions. This should be resolved in the very near future but in the meantime you can test this by going to the Preview Assistant:
You can see from the preview that after all the information was collected, a ticket number was returned. Below is a view of the ticket in Cloudant:
Conclusion
Combining Watson Assistant with App Connect using the new extensions feature makes it possible to easily integrate your assistant with the full spectrum of connectors that App Connect supports out of the box. Within App Connect, you can create complex business process flows that include multiple connectors and then rapidly pull those capabilities directly into your assistant with little to no coding impact on your assistant development team. This same integration pattern works for other iPaaS platforms as well. So if you have a need to quickly build an assistant that connects to other cloud services, consider using the new Watson Assistant extensions capabilities to complete your next project.
One last thing. Both the actions skill and the OpenAPI spec that I used to create this demo can be found in this git repo. Enjoy!
