IBM Watson Salesforce SDK

The IBM Watson Salesforce SDK uses the Watson Developer Cloud services to help you solve complex problems using Apex in your Salesforce environment. Currently, this SDK supports two Watson services: Conversation and Discovery. More are planned to be added in the future.

Installation using Salesforce DX

Automatic deployment

You can automatically deploy the SDK to a new scratch environment using the Deploy to SFDX button.

Manual deployment

1. Clone this repository from GitHub using the following command:

   git clone https://github.com/watson-developer-cloud/salesforce-sdk

2. Create a new scratch environment (optional if you don't want to re-use an existing one):

   sfdx force:org:create -a watson-sdk -s -f config/project-scratch-def.json

3. Push the source to the scratch environment:

   sfdx force:source:push

If you want to use the Watson SDK within a non-scratch environment you can deploy it using the Salesforce DX CLI.

1. Authenticate the Salesforce DX CLI to the target environment:

   sfdx force:auth:web:login

   In the browser window that opens, sign in to your org with your credentials. More information here

2. Create an output directory:

   mkdir mdapioutput

3. Convert the source code:

   sfdx force:source:convert -d mdapioutput/

4. Deploy the source code:

   sfdx force:mdapi:deploy -d mdapioutput/ -u TargetOrg -w 100

Installation using the Ant Build Tool

You can install or update the SDK using the Ant Build Tool by following these steps:

1. Clone this repository from GitHub using the following command:

   git clone https://github.com/watson-developer-cloud/salesforce-sdk

2. Edit install/build.properties to insert your Salesforce username and password. Since you will be using the API to access Salesforce, remember to append your Security Token to your password.

3. Open your command line to the install folder, then deploy using Ant:

   ant deployWatson

Getting Started

Using the Watson services require service credentials in Bluemix, meaning you will need to create a Bluemix account if you do not have one already.

To get your service-specific credentials, follow these steps:

1. Log in to Bluemix

2. Create an instance of the desired service:

   1. In the Bluemix Catalog, select the service you want to use.
   2. Click Create.

3. Copy your credentials:

   1. On the left side of the page, click Service Credentials, and then View credentials to view your service credentials.
   2. Copy url, username and password.

There are two ways of specifying credentials, Using Named Credentials or Specifiying credentials in the Apex code

Using Named Credentials

When creating a service instance like with new Discovery(). Each service loads the credentials from Named Credentials. The SDK will use the service name and API version to build the Named Credentials name.

For example

IBMDiscoveryV1 discovery = new IBMDiscoveryV1('2017-09-01');

Will look for the watson_discovery_v1 named credentials while:

IBMConversationV1 discovery = new IBMConversationV1('2017-05-26');

Will look for watson_conversation_v1.

In order to create Named credentials:

1. Go to Setup
2. Enter Named Credentials in the quick find box and select the highlighted entry
3. Click on New Named Credential
4. Enter the following values:
   • Label: A unique label that identifies your named credentials
   • Name: watson_<service_name_snake_case>_<api_version>, e.g: watson_conversation_v1
   • URL: <SERVICE_URL>, e.g: https://gateway.watsonplatform.net/conversation/api
   • Identity Type: Named Principial
   • Authentication Protocol: Password Authentication
   • Username: <USERNAME>
   • Password: <PASSWORD>
5. Click on Save.

Specifiying credentials in the Apex code

Storing credentials in the Apex code is not recommended. If possible, use Named Credentials.

For example:

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

Examples

Getting started using a service is very simple! All services follow the same pattern of service instantiation, option building, and requesting. To get an idea, below is an example of using the Discovery service to get a list of your current environments:

// Will load credentials from the `watson_discovery_v1` named credential
IBMDiscoveryV1 discovery = new IBMDiscoveryV1(IBMDiscoveryV1.VERSION_DATE_2017_09_01);

// configuring options for listing environments
IBMDiscoveryV1Models.ListEnvironmentsOptions options = new
  IBMDiscoveryV1Models.ListEnvironmentsOptionsBuilder()
  .build();

// making request
IBMDiscoveryV1Models.ListEnvironmentsResponse environmentList = discovery.listEnvironments(options);
System.debug(environmentList);

Similarly, here is an example of creating an intent in the Conversation service:

// Will load credentials from the `watson_conversation_v1` named credential
IBMConversationV1 conversation = new IBMConversationV1(IBMConversationV1.VERSION_DATE_2017_05_26);

// configuring options for creating intent
IBMConversationV1Models.CreateIntentOptions options = new
  IBMConversationV1Models.CreateIntentOptionsBuilder()
  .workspaceId('<workspace_id>')
  .intent('MyIntent')
  .description('This is an example of creating an intent!')
  .build();

// making request
IBMConversationV1Models.Intent intent = conversation.createIntent(options);
System.debug(intent);

The manner of instantiating and using services should be consistent no matter which you decide to use, which should make it easy to explore the many capabilities Watson services have to offer.

Functional Tests

The force-app/main/test folder contains the example calls for each service. These examples are used for functional testing of services. Developers can use them for reference and testing the installed SDK.

Contributing

If you're interested in helping to make this project better, see Contributing.md.

License

This library is licensed under the MIT license. Full license text is available in LICENSE.