IBM Watson Workspace Javascript SDK

An unofficial IBM Watson Workspace Javascript SDK.

Usage

Include the SDK using a Node.js require statement, authenticate, and begin running API commands. API functions return data through bluebird promises.

const SDK = require('watsonworkspace-sdk')
const ww = new SDK(
  process.env.APP_ID,
  process.env.APP_SECRET
)

ww.authenticate()
.then(token => {
  ww.sendMessage(spaceId, 'Hello from Watson Workspace SDK')
})
.catch(error => logger.error(error))

If you already have a token (through OAuth for example), you can skip the authenticate call.

const SDK = require('watsonworkspace-sdk')
const ww = new SDK('', '', 'eyJhbGciOiJSUzI1NiIsInR ... I5ZWQtNDJ'
)

ww.sendMessage(spaceId, 'Hello from Watson Workspace SDK')

API

Authentication

Authentication is completed using an appId and appSecret. The resulting JWT token is returned through a promise, but stored as a private property. You do not need to store the JWT token; it will be automatically used and refreshed by the SDK.

ww.authenticate()
.then(token => ...)
.catch(error => logger.error(error))

Working with messages

Individual messages can be obtained using getMessage(id, fields). Fields correspond to the allowed GraphQL fields per documentation.

ww.getMessage(message.messageId, ['id', 'content', 'annotations'])
.then(message => ...)

To handle GraphQL objects you can create a Javascript object as a field value with the format

{
  name: 'theObjectName', fields:['field1', 'field2']
}

The following example shows the Person object with the id and displayName fields being retrieved in a message.

[
  'id',
  'content',
  'annotations',
  {
    name: 'createdBy',
    fields: ['id', 'displayName']
  }
]

To send a message into a conversation, use sendMessage(spaceId, content). If content is a string, the message is sent as-is to the space. (Workspace supports markdown, and markdown will be rendered using this function.)

ww.sendMessage(spaceId, 'Hello from *Watson Workspace* SDK')
.then(message => ...)

For more expressive messages, construct the content as an object per the Workspace documentation.

ww.sendMessage(spaceId, {
  "type": "generic",
  "version": "1",

  "color": "#36a64f",
  "title": "Hello world",
  "text": "Hello from a Watson Work Services app",

  "actor": {
    "name": "Frank Adams"
  }
})
.then(message => ...)

Working with action fulfillment

To support action fulfillment, a message must be annotated with the message-focus annotation. This can be done using Watson Conversation; see Make your app cognitive in documentation. Additionally, you can add a message-focus annotation programmatically using addMessageFocus(message, phrase, lens, category, actions, payload).

ww.addMessageFocus(message, 'text to be underlined', 'My Lens', 'Category A', 'my-focus-action', '{foo:bar}'))

The message argument should be obtained from a message-created or message-annotation-added event. If you are retrieving a message using getMessage ensure that the id and content fields are returned. The content property is necessary to determine the start and end positions of the phrase in the overall content's text.

To handle the newly added lens, use sendTargetedMessage(userId, annotation, items). The annotation is the annotationPayload returned by a actionSelected message-annotation-added event. To make it easier, use the Watson Workspace Bot Framework to handle and parse such events.

To create the standard title-subtitle-buttons user interface, do the following.

const UI = require('watsonworkspace-sdk').UI

const buttons = [
  UI.button('button-submit', 'Submit')
  UI.button('button-cancel', 'Cancel')
]
const dialog = UI.generic('Your awesome title', 'and slightly smaller but equally good subtitle', buttons)

ww.sendTargetedMessage(userId, annotation, dialog)

You can similarly send a card-based user interface.

const cards = [
  UI.card(keyword.text, `${keyword.relevance.toString()} relevance`, '', [
    UI.cardButton('More')
  ], date)
  UI.card(entity.type, `${entity.relevance.toString()} relevance`, entity.text, [], date)
]
ww.sendTargetedMessage(userId, annotation, cards)

The card(title, subtitle, text, buttons, date) builder takes a bit more information that the generic(title, text, buttons) builder, but they're very similar. Depending on which you choose, sendTargetedMessage will construct the appropriate action fulfillment dialog.

Working with Information Extraction

As messages are posted to Watson Work Services; information extraction occurs behind the scene. For each message, the entire text gets processed using Alchemy Language services: entities, keywords, doc-sentiment, relations, concepts, taxonomy, and dates. Annotations are created if the results are not empty. For convenience, the informationExtraction function will parse the annotations to provide an object with such information.

{
  "keywords": [
    {
      "relevance": 0.972529,
      "text": "Watson Workspace SDK"
    },
    {
      "relevance": 0.604772,
      "text": "Hello"
    }
  ],
  "entities": [],
  "concepts": [
    {
      "dbpedia": "http://dbpedia.org/resource/AS_Watson",
      "relevance": 0.9044,
      "text": "AS Watson"
    }
  ],
  ...
  "docSentiment": {
    "score": 0.729815,
    "type": "positive"
  }
}

Working with files

Files can be sent into a space. Two functions are provided, sendFile and sendFileStream.

Use sendFile when you have a file on the file system. The mime-type will be interpreted automatically based on the file extension. Use the full path when constructing the file name.

ww.sendFile(spaceId, `/vanstaub/sdkSpec.js`)

If your file is an image, you can include width and height dimensions. (If width and height are omitted, the full image dimensions will be used.)

ww.sendFile(spaceId, `/vanstaub/keyboard_cat.gif`, 640, 480)

Use sendFileStream when you have the file in a stream format (for example, when your app has downloaded it from another server). You must provide the file name and mime-type.

sendFileStream (spaceId, stream, 'awesome.jpg', 'image/jpeg')

Files can be retrieved from a space. Use the following format to return a Promise containing the file as a stream:

www.getFile(fileId)

Working with photos

Similar to files, photos can be added to an application or user (assuming the application has the user's OAuth token). The format must be a jpg file.

ww.uploadPhoto(`/vanstaub/van.jpg`)

Working with templates

Functionality is provided to access the properties and status provided with a space created from a template.

Get all the properties of a space:

ww.getProperties(spaceId) // returns a promise resolving to an array containing the properties and their values

ww.setProperty(spaceId, propertyName, propertyValue) // sets the value of a property

ww.getStatus(spaceId) // returns a promise resolving to the status

ww.setStatus(spaceId, newStatus) // sets the status

NOTE: Templates are an EXPERIMENTAL feature of Watson Workspace; as it evolves, this SDK may evolve with it.

Working with raw requests

Obviously not all functionality is presently covered with the SDK.

You can use sendGraphql(query) to send GraphQL to Work Services and receive JSON. The query can either be raw GraphQL as seen in the documentation.

query getMessage {
  message(id: "message-id") {
    id
    content
    contentType
    annotations
  }
}

You can also send GraphQL JSON objects. Examples can be found in graphql.js. This is the default implementation in the SDK. See the getMessage function as an example.

Special note: sendGraphql(query) will respond to the promise with the value of the data property. Said differently, GraphQL normally appears as:

{
  "data": {
    "message": {
      "id": "59e54851e4b017bb0ba2973c",
      ...
    }
  }
}

The promise will receive the message object in the above example.

For the lowest level of communication, use sendRequest(route, method, headers, body). The route is relative to the base server URL, for example v1/spaces/${spaceId}/messages. The authentication header will be automatically added to the headers argument; you do not need to add it.

Testing

A Jasmine test suite is located in the spec folder. Run npm test to start the test suite.