Watson-Work-Express

Watson Work Module for use with NodeJS Express. See Developer Guide for details on developing Watson Work Applications. This package provides a number of objects, event sources, caching, and support functions to make it easier to develop Watson Work applications.

• Event
  • Message
  • Annotation
    • Action
      • Button
  • Focus
  • Reaction
• Space
• Person
• graphQL

Install

npm install watson-work-express

Use

var WWExpress = require('watson-work-express');
var Express = new WWExpress();
...
app.use('/webhook', Express.express()); // add Watson Work Express Middleware
app.post('/webhook',(req,resp) => {
  // don't really need to do anything here, but you can inspect the req.body for raw events
})
...

Express method takes optional settings. See settings for all default values.

However if you just want to get the raw events (not using any classes), the express class is also a type of EventEmitter with the event type as the topic:

Express as EventEmitter

EventEmitte for CRUD operations (create, update, delete)

Express.on("message-annotation-added", annotation => {
  console.log("Annotation Added:")
  console.log(JSON.stringify(annotation,null,2));
});

Event class

The event class is a base class for all the inbound events coming from the Watson Work outbound webhook mechanism. The class also creates a normalized operation property representing the standard CRUD operations for the event as appropriate.

Message class

Messages are a type of Event and are cached per settings.

static events()

EventEmitter for CRUD operations (create, update, delete)

Express.message.events().on("create", message => {
  console.log("Message Created:")
  console.log(JSON.stringify(message,null,2));
});

There is also a special event completed which waits a specific period of time from when the message created event is recieved in order to allow all annotation events to be received and associated with the message. This is the best way to get the complete message (with annotations), but does require a delay in emitting the event.

static get(spaceId, messageId})

find a specific message in a specific spaces

Express.message.get("somevalidspaceid", "somevalidmessageid").then(message => {
  console.log("Got Message:");
  console.log(JSON.stringify(message,null,2));
})

addFocus(phrase, lens, category, actions, payload, hidden = false)

Adds a focus annotation to a specific message. A Payload can be added to the focus containing and useful information for processing the focus later. Returns the the message with all annotations.

message.addFocus("Express","MyLens","MyCategory","OneAction",{key: "value"}).then(message => {
  console.log("Focus created");
  console.log(JSON.stringify(message,null,2));
})

Annotation class

The annotation class simplifies the structure of the raw Watson Work Annotation by JSON parsing the payload, and merging the payload properties with the annotation properties (so there is no longer a annotationPayload property).

static events()

EventEmitter for CRUD operations (create, update, delete)

Express.annotation.events().on("create", annotation => {
  console.log("Annotation Created:")
  console.log(JSON.stringify(annotation,null,2));
});

Focus class

Focus is a type of Annotation.

static events()

EventEmitter for CRUD operations (create, update, delete)

Express.focus.events().on("create", focus => {
  console.log("Focus Created:")
  console.log(JSON.stringify(focus,null,2));
});

Reaction class

Reaction is a type of Event.

static events()

EventEmitter for CRUD operations (create, update, delete)

Express.reaction.events().on("create", reaction => {
  console.log("Reaction Created:")
  console.log(JSON.stringify(reaction,null,2));
});

Space class

Space is a type of Event and are cached per settings.

static events()

EventEmitter for CRUD operations (create, update, delete, members-added, members-removed)

Express.space.events().on("update", space => {
  console.log("Space Updated:")
  console.log(JSON.stringify(space,null,2));
});

static get(spaceId})

find a specific spaces

Express.space.get("somevalidspaceid").then(space => {
  console.log("Got Space:");
  console.log(JSON.stringify(space,null,2));
})

sendMessage(message)

Sends a message to the space. Message structure is (default values):

{
    type: <string>, // currently 'generic' is only valid option
    version: <float>, // currently 1.0 is only valid option
    color: <hex color>,
    title: <string>,
    text: <string,
    actor: {
      name: <string>
    }
  }

sendFile(filename, width, height)

Sends a file to the space, width & height can be ignore if file is an image.

  space.sendFile("picture.png").then(response => {
    console.log("Added file, response:")
    console.dir(response);
  })
})

Action class

Actions are a type of Annotation, and are part of the Action Fulfillment flow.

static events()

EventEmitter operations ('selected');

Express.action.events().on("selected", action => {
  console.log("Action Selected:")
  console.log(JSON.stringify(action,null,2));
});

sendTargettedMessage(cards)

Responds to an action with an array of cards. Cards take the structure of:

{
    type: 'INFORMATION',
    title: <string>,
    subtitle: <string>,
    text: <string>,
    date: <string>,
    buttons: [
      {
        text: <string>,
        payload: <string>,
        style: 'PRIMARY' || 'SECONDARY'
      }
    ]
  }

payload can be any kind of javascript type including an object. The payload will be available in the Button action when it is pressed.

isButton()

Returns true if the action is a button, false otherwise.

Button class

Buttons are a kind of Action. They happen when a button on an action fulfillment card is pressed.

buttonPayload

Property that contains the payload specified when the button on the card was created as part of the targetted message.

static events()

EventEmitter for operations ('selected')

Express.button.events().on("selected", button => {
  console.log("Button Selected:")
  console.log(JSON.stringify(button,null,2));
});

closeAction(cards)

used to complete the Action Fulfillment flow, you can provide any set of cards you want. The default is a single card with no buttons:

{
  type: 'INFORMATION',
  title: 'Action Completed',
  text: "You can close this action.",
  buttons: []
};

Example

See Example.