Please note that all future sample code, including updates to these samples, will be maintained in the IBM Watson repos on GitHub. This includes the following repositories of interest from this project:
- WEX Application Builder Samples
- WEX with Personality Insights Example
- Application Builder Sample Proxy
- And many other interesting Watson Explorer samples, examples, and applications
IBM Watson Explorer combines search and content analytics with unique cognitive computing capabilities offered by the Watson Developer Cloud to help users find and understand the information they need to work more efficiently and make better, more confident decisions. Watson Explorer Application Builder is the delivery tool that allows developers to quickly construct a 360-degree view combining data and analytics from many sources into a single view. These applications can be enhanced using content from external sources, external visualization libraries (such as D3.js), and external APIs. Integrating with the Watson Developer Cloud provides opportunities for further enhancing Watson Explorer applications to include cognitive-based features. Watson Developer Cloud applications can be integrated with Watson Explorer in a number of ways depending on the use cases and desired functionality.
In this set of examples, we introduce the basics for integrating a Watson Explorer application with applications deployed to the Watson Developer Cloud emphasizing some of the Watson Cognitive services. The examples provided are basic technical proofs of concept; we give you the technical foundation you need to build truly awesome cognitive applications. In each example we walk you through the process of deploying an application to the Watson Developer Cloud. We show you how to integrate that application with Watson Explorer. We then provide you with some food for thought — What should you think about when deploying this kind of integration into a production environment? What are some additional ideas for integration?
By the end of each example you should understand what each service does, how it could benefit your organization, and how to integrate it with an Application Builder application.
Before beginning the tutorials you should review the prerequisites provided below. For more information on the available Watson Developer Cloud cognitive services, please visit the services catalog.
The integration between Watson Developer Cloud (WDC) and Watson Explorer follows relatively straightforward web services patterns. All of the WDC services use a basic REST API. This makes it relatively easy to use WDC services from WDC applications. The example WDC applications here also use a simple REST API to facilitate communication between the WDC application and Watson Explorer. Communication between a Watson Explorer application and a deployed WDC application is accomplished in two ways.
- Watson Explorer Engine can communicate with WDC applications via a parser node (parser nodes in Engine allow for advanced and basic web requests to be made).
- Watson Explorer Application Builder widgets communicate with WDC applications by going through a proxy deployed to the same web server as Application Builder.
The sample proxy enables two important properties. First, browsers enforce a same-origin policy for web requests made from JavaScript, thus to allow for effective asynchronous user interactions from a client browser (via Ajax) a URL from the same domain must be available. Rather than modify Application Builder core, the Proxy allows you to effectively create your own API for Ajax calls. This same proxy can also be used directly by Application Builder widgets to improve maintainability. In this capacity, the proxy creates an abstraction on top of WDC applications to buffer Application Builder widgets from WDC endpoint changes and better promote testing.
There are five basic integration patterns for combining Watson Explorer and Watson Developer Cloud. The specific integration pattern used will depend on the use cases and desired functionality.
- Application Builder Widget. The most common place to use a cognitive service is from within an Application Builder widget. Most examples here demonstrate this.
- In the client browser. Once a page is rendered in a user's browser there may be use cases in which you would want to allow a user to interact with a WDC application without refreshing the page. For example, a user might dialog with a Watson service from an entity page. At this time the included proxy must be used to satisfy the end-user's browser same-origin policy.
- At crawl time. The Relationship Extraction Integration provides an example of an Engine converter that indexes the data returned from the Relationship Extraction service.
- At query time. It is also possible to access WDC applications at query time from Engine.
- Pre- or post-process. In some cases it is useful to use a WDC application as a pre- or post-processing step and the output of this is used by the Watson Explorer application in some way.
The integrations were developed using two runtimes on Bluemix; Java Web Services running on Websphere Liberty Profile and Ruby Sinatra. The following sections detail the setup for each of these approaches.
Bluemix provides multiple different runtimes for your cloud-based application. In order to gain access to the Bluemix environment you will need to register for an account. After registration and configuration of the Cloud Foundry tools, you can setup your Java or Ruby development environment by following the instructions provided below.
Steps for Bluemix setup:
- Register for an account on Bluemix
- Install the Cloud Foundry command line tool, installation instructions
Some examples like the Machine Translation Service are a Java-based Bluemix applications. The following steps get you setup and running for development of these applications.
- A JDK is required to compile the Java code. Download and install IBM JDK 1.7
- We use Maven to build the package. Download and install Apache Maven
The following tools and plug-ins can make testing and deployments easier.
- Eclipse Luna Java EE Edition
- IBM Eclipse tools for Bluemix
- IBM WebSphere Application Server Liberty Profile developer tools for Luna
- All required Jars for Java examples will be included via Maven.
Some examples like the Concept Expansion Service are a Ruby Sinatra-based Bluemix application. The following steps get you setup and running for development of these applications.
- Ruby is required to compile the code. Download and install Ruby 1.9.3
- Ruby DevKit is useful for development on Windows. Download and install Ruby DevKit 4.5.2
- JRuby is used in the Proxy development. Download and install JRuby 1.7.13
- Bundler is required to build the bundle install. Download and install using "gem install bundler" after setting up JRuby.
In Watson Explorer, you should:
- Build an Example Metadata collection in Watson Content Explorer, see the Using Metadata for Searching, Sorting, and Filtering tutorial for instructions.
- Learn how to create Application Builder search widgets, see the Creating An Application tutorial for more information.
All sample code contained within this project repository or any subdirectories is licensed according to the terms of the MIT license, which can be viewed in the file license.txt.