Watson Engagement Advisor Accelerator App enables users to interact with a Watson Engagement Advisor (WEA) instance using the conversation API. Its appearance can be customized and it can be configured to use a client-specific Watson Experience Manager endpoint.
- a web server
- access to a Watson Experience Manager instance
The application has been tested on the following browser platforms:
| Chrome | Firefox | Internet Explorer | Opera | Safari |
|---|---|---|---|---|
| 41 | 36 | 11 | 28 | 8 |
| Android | Safari Mobile |
|---|---|
| 4.4 | 7.1 |
The following steps are required to deploy the application.
- Configure server-specific settings
- Customize the appearance and texts (optional)
- Build the distributable
- Upload the app to a web server
First, install node.js. Then run the following commands to install the dependencies and build tools:
$ npm install -g gulp
$ npm install
For SCSS linting, scss-lint Ruby gem is also required:
$ gem install scss-lint
Edit wea-config.json to configure server-specific settings.
Make sure to edit the settings for the correct environment; for example, if building a production distributable, edit the settings for production environment.
| Setting | Description | Example value |
|---|---|---|
WEA_API_URL |
(required) The URL of a WEA API server. |
http://server...com/instance/watson/wea/v2 |
WEA_API_TOKEN |
(required with WEA_API_URL) The value to set as the user_token header in API requests. |
wea-example |
Any static texts in the application (such as the input field placeholders) can be configured by editing po/en_US.po file using either a text editor or a .po file editor such as poedit.
Application styles and colors can be changed by editing app/styles/_overrides.scss using a text editor. See the code comments in the file for more details.
$ gulp [--target local|develop|demo|production]
The target argument optionally specifies the deployment environment (defaults to local). The distributable gets built to the dist/ folder.
After having built the distributable, upload the contents of dist/ folder to a web server.
WEA Accelerator App connects to the WEA API to send questions and receive responses from Watson.
+-----------+ +-----------------------+
| WEA API | <-------> | WEA Accelerator App |
+-----------+ +-----------------------+
wea/
app/
images/
modules/ # application modules
dialog/
examples/
guidance/
intro/
quit/
styleguide/
util/
styles/ # SCSS style sheets
vendor/ # any third-party components
app.js # application root JS
index.html # application root HTML
gulpfile.js # build task descriptions
wea-config.json # configuration settings
The application code is divided into several modules which consist of one or more components. For example, the guidance module contains a component for showing the Guidance ("Helpful Links") drawer. The following modules are built-in into the application:
The Dialog module is responsible for managing and displaying the conversation between the user and Watson (WEA API). It sends user's messages to the API and parses & displays the responses it receives.
The Dialog module also has built-in support for several response template styles and components that can be used within the responses. See styleguide for live illustrations of the templates and components. The styleguide also contains examples of supported text styles that can be used to format the responses.
A response template gets triggered if a matching style class is found in the response. Currently supported templates are summary, confirmation, transition and default. To use a specific template in a response, include the template's name in the class attribute of the response root element. Also include the class full-screen to declare that the template should occupy the entire screen:
<div class="transition full-screen">
...
</div>Displays a clickable element that submits it's value as the next message to WEA API.
Displays a list of clickable elements that submit their value as the next message to WEA API.
Displays a dropdown selector that submits the selected value as the next message to WEA API.
Displays a date & time picker that submits the selected date as the next message to WEA API.
Displays the default avatar image.
The content of this tag is displayed as-is and also used as the question text shown to the user in the input screen.
The content of this tag is not shown to the user. Instead, it is sent as a message to the API immediately before the user's next message.
Displays a "Did this answer your question?" feedback question with Yes/No options and sends the response to WEA /feedback API. Automatically added to real pipeline responses, but can be added manually to fake pipeline responses as well.
In addition to using the built-in ones, it is possible to create custom components. Generally speaking, creating a custom component consists of three steps:
- creating the response markup
- transforming it to renderable HTML + logic
- presenting the component to the user.
The component markup to be used inside a Dialog response node can be basically arbitrary. WEA Accelerator App currently namespaces all custom component tags with mct, which is also the default namespace of custom elements used inside Dialog itself.
For example, <mct:input> is a component that submits it's contents back to the API as a response:
<ul class="bubbles">
<li>
<mct:input>Yes</mct:input>
</li>
<li>
<mct:input>No</mct:input>
</li>
</ul>When a response is received from Dialog, it is parsed and transformed to produce the HTML to be rendered along with any JavaScript logic required for the desired functionality. For instance, the above <mct:input> example could be transformed into the following HTML:
<ul class="bubbles">
<li>
<span class="autoinput" onclick="myFunction()">Yes</span>
</li>
<li>
<span class="autoinput" onclick="myFunction()">No</span>
</li>
</ul>where myFunction is a function submitting the contents of the element to the API. In practice, component markup and logic is encapsulated using AngularJS directives:
The WEA Accelerator App uses AngularJS directives to encapsulate markup and logic of a component. For example, the mct:input markup is first transformed to a directive called autoinput, which is implemented as
angular.module('dialog.component.autoinput', ['dialog.service'])
.directive('autoinput', function (dialogService) {
return {
'restrict': 'E',
'transclude': true,
'replace': true,
'template': '<span class="autoinput" ng-transclude></span>',
'link': function (scope, element) {
var text = element.text();
element.bind('click', function (e) {
dialogService.query(text);
});
}
};
});See app/modules/dialog/dialog-parser-service.js for examples on parsing response components.
The custom components can be styled using arbitrary CSS rules. In the WEA demo app, for example, an <autoinput> component inside a <ul class="bubbles"> list is rendered as a circle-shaped button.
This module contains a <guidance> component for displaying the "Helpful Links" drawer. See app/modules/dialog/dialog.html for a usage example.
This module contains a <quit> component for displaying the quit icon and, when user clicks on the icon, an overlay containing Quit / Cancel buttons. See app/modules/dialog/dialog.html for a usage example.
The intro module contains the introductory animation sequence displayed when user first loads the application.
This module contains generic helper components.
The styleguide module contains a page showcasing the various templates and styles used throughout the application. It also allows live editing of the templates to preview changes in responses. Browse to /#/styleguide in the deployed application to view the styleguide page.
The examples module contains an example in-app landing page for the imaginary Flexrate insurance company mainly for demoing purposes. In a real-life scenario the landing page would likely reside outside of the application. Browse to /#/examples/flexrate in the deployed application to view the page.
$ gulp serve
$ gulp test
for running tests once, or
$ gulp autotest
for running the tests whenever a source file changes.
$ gulp lint
for linting once, or
$ gulp autolint
for linting whenever a source file changes.