Integrating Watson Discovery into your Salesforce apps with the Watson Salesforce SDK
Integrating Watson Discovery into your Salesforce apps with the Watson Salesforce SDK


The newly released IBM Watson Salesforce SDK allows developers to more easily integrate Watson into their Salesforce applications (see SDK announcement blog here). “Apex” is the Salesforce proprietary programming language used by developers on the platform. Currently, the SDK supports the Watson Discovery and Conversation services. This blog will discuss some of the key features and applications of the Watson Discovery service, and show how to get started using the Salesforce SDK.

There are many ways that Discovery can be leveraged in applications today. I’ll provide a few examples to help you understand how some of Discovery’s capabilities can help organizations solve complex problems to enhance their business.

Augmentation to a Conversational Solution

One of the more powerful ways to leverage Discovery is as an extension or augmentation to any conversational system (see Watson Conversation Service). In short, when a Conversational bot cannot confidently identify or answer the question, its passes the question to the Discovery service. This is often called the “Long Tail” scenario. You would first ingest your vast amount of documentation, such as knowledge base articles or manuals, into Discovery. Discovery then enriches and indexes all your data to make it consumable. Finally, Discovery uses its integrated Natural Language Processing, Semantic Search and Machine Learning capabilities to identify the most relevant answers and passages within your documents, to address a user’s question. You have the option to custom train Discovery for your specific use case to help boost the relevance of your results. In this use case above, Discovery is a cognitive back end service that is providing additional intelligence to your conversational solution that is otherwise buried in documentation.

Unlocking Insights in Your Data

Another very powerful way to leverage the Discovery service is to use it to provide deep, hidden insights into your organization’s data to drive actionable change. For example, let’s say you’ve got thousands of pages of unstructured text based on customer surveys taken over a period of time. Discovery can quickly highlight trends, patterns and anomalies within your data. It will also provide you with customers’ sentiment and tone towards your brand, product or service. You could also train Discovery on a specific industry using machine learning models in Watson Knowledge Studio to identify specific entities or other specific terms (eg security violations or company guidelines) within your data. These powerful capabilities allow you to make informed decisions to improve your business.

For more detailed information on the Watson Discovery Service, check out the documentation here.

Get Hands-On!

Now that you’ve learned about Watson Discovery and some of the ways it can be used in your Salesforce applications, let’s get you setup with the service so that you can start using it.

IBM Cloud Setup

  1. Login or create a free IBM Cloud account to get access to Watson services.
  2. Navigate to the Catalog and create a free instance of the Discovery service.
  3. Click on “Service Credentials” on the left menu bar, then select “New credential” then select “Add” to create a set of credentials. Make note of the API username and password that show up on the resulting page as you will need these for connecting to the Discovery service in your Apex code.
  4. Go back to the “Manage” tab on the left menu bar and click on “Launch tool”. You will see a sample collection here named “Watson Discovery News” that you will leverage in part of this blog.

Instantiating the Discovery Service in Apex

Now that you’ve got your Discovery instance all set up, the next step is to deploy the Salesforce SDK into your Salesforce environment. You can find the guidance on how to do that here. Once you have the SDK deployed, you can start using the Discovery service with your Apex code.

With the SDK, invoking a Watson API with Apex code can be done with just a few lines of code. If you’re familiar with developing on Salesforce, you can use Named Credentials using the instructions here. Otherwise, you can copy and paste the code below, substituting your username and password that you received in IBM Cloud. For this example, you can use the Salesforce Developer Console.

IBMDiscoveryV1 discovery = new IBMDiscoveryV1(IBMDiscoveryV1.VERSION_DATE_2017_09_01);
discovery.setUsernameAndPassword('USERNAME', 'PASSWORD');

Now that you have an instance of Discovery, you can use its functionality. For this blog, I’m going to demonstrate using the service to query a collection of documents. I’ll use the sample Discovery News collection as our source of data, which contains million of recent news documents. This collection is provided out of the box by IBM and is constantly being updated to reflect the most current news. I’ll run a simple query against that collection and review the results.

Querying the Discovery News Collection

In this example, you are interested in reviewing some recent articles in the news about IBM Watson. You can build more sophisticated queries using features like filters and aggregations but for the purposes of this blog, I’ll run through a simple example to search the News collection for documents where “IBM Watson” was mentioned as an entity. I also want to specify to return only the top 10 results. In the Salesforce Developer Console, you can paste in the code below and execute it anonymously.

Note: You must replace the USERNAME and PASSWORD below with your Discovery service credentials. You also need to ensure your environmentId variable is set to ‘system’ and collectionId variable is set to ‘news’ which are the default values for the Discovery News collection.

IBMDiscoveryV1 discovery = new IBMDiscoveryV1(IBMDiscoveryV1.VERSION_DATE_2017_09_01);
    discovery.setUsernameAndPassword('USERNAME', 'PASSWORD');

    IBMDiscoveryV1Models.QueryOptions options = new
      .query('enriched_text.entities.text:"IBM Watson"')
    IBMDiscoveryV1Models.QueryResponse response = discovery.query(options);

To view the results, go to the logs tab, double-click on the row you just executed and then check off the “Debug Only” option. If successful, you will see something similar to the below (data in results will vary):

Great work! You’ve just successfully queried the Watson Discovery service using the Salesforce SDK.

Next Steps

Watson Discovery is a very powerful cognitive service that contains endless possibilities of ways to add value to enterprise applications. To learn more about Discovery’s features and capabilities, visit the IBM documentation. To take a closer look at the SDK and dive deeper, check out this lab here.

About the Author

Marc Nehme is a Chief Architect in the Watson Embed organization at IBM. His primary focus is working with strategic partners to help them achieve significant business value by creating Watson solutions that scale across their organizations. Marc has been in the IBM Watson family since 2014 and previously focused his efforts in the IBM Watson Delivery organization where he drove various customer projects from concept to production. You can follow Marc here.

4 comments on"Integrating Watson Discovery into your Salesforce apps with the Watson Salesforce SDK"

  1. Jaydip Bhattacharya January 23, 2018

    I followed all the steps above. Was able to use discovery service with no issue. But when I tried to use visual recognition service for face detection, I am getting blank response from service. I tried with browser, it works – only when I use salesforce code, it is not getting blank response. What could be the issue? Below is the code:

    String VERSION_2016_05_20 = ‘2016-05-20’;
    // Make sure the named credentials below is defined
    String NAMED_CREDENTIALS = ‘callout:watson_visual_recognition_v3’;
    IBMVisualRecognitionV3 visualRecognition = new IBMVisualRecognitionV3(VERSION_2016_05_20,API_KEY);

    string urlstr=’’;
    IBMVisualRecognitionV3Models.DetectFacesOptions options = new IBMVisualRecognitionV3Models.DetectFacesOptionsBuilder()
    options = options.newBuilder().build();
    IBMVisualRecognitionV3Models.DetectedFaces resp = visualRecognition.detectFaces(options);
    system.debug(‘Gender: ‘+resp.getImages()[0].getFaces()[0].getGender());

  2. Very nice blog indeed!

    I have one question which is unrelated to querying the collection. Do you know if through Apex code we can upload documents to IBM Watson collection?

    • Hi Nabs, from our Developer team!

      You can in fact upload documents with the SDK. The person asking can see examples of this in the testing code for Discovery.


Join The Discussion

Your email address will not be published. Required fields are marked *