@sassoftware/conversation-designer-components

SAS Conversation Designer SDK

Overview

The SAS Conversation Designer SDK is a set of JavaScript APIs and web components that enable SAS Conversation Designer chatbots to be easily embedded in a third-party application or web page. This functionality is delivered as the conversation-designer-components JavaScript library. This project provides examples of how to use the SDK components in various scenarios.

Prerequisites

Access to a deployment of SAS Conversation Designer and a bot are required in order to use the SDK. For more information about server set up, see the SAS Viya setup section. Note that the other sections on the Getting Started page are specific to SAS Visual Analytics and not this SDK.

Installation

NPM

The @sassoftware/conversation-designer-components library is published to NPM and can be installed by running the npm install command as shown below. conversation-designer-components does not support ES6 imports. Therefore, the contents of the conversation-designer-components/dist folder must be deployed with your page, and then loaded using a script tag.

# From the root directory of your project
npm install @sassoftware/conversation-designer-components

# Copy the contents of the package to an asset folder for deployment
cp -r ./node_modules/@sassoftware/conversation-designer-components ./sdk-assets

The library can then be loaded out of the deployed assets folder using a script tag.

<script async src="./sdk-assets/dist/umd/conversation-designer-components.js"></script>

CDN (Content Delivery Network)

Accessing the conversation-designer-components library from a CDN is easy. It does not require installation or hosting of the library code and assets. There are several public options for accessing NPM content through a CDN, such as UNPKG and jsDelivr. Here is an example of loading the 0.1.0 version of conversation-designer-components from UNPKG using an HTML script tag. When used in production, the version should be pinned to the full major.minor.patch semantic version.

<script async src="https://unpkg.com/@sassoftware/conversation-designer-components@0.1.0/dist/umd/conversation-designer-components.js"></script>

Getting Started

When using the SDK there is some information that must be provided to configure the components. Where/how these values are used is covered in the API section. Following is a description of each attribute:

• url - this value points to the base url of your SAS environment (ex: if SAS Conversation Designer was deployed to http://yourcompany.com/SASConversationDesigner, then set this value to http://yourcompany.com)
• botUri - this is the unique identifier for the bot you want the component to communicate with (ex: /naturalLanguageConversations/bots/e3b1f772-1562-4c8c-a60e-1ee20684ce4b)
• revisionId - this is the unique identifier for the bot revision within your bot that the component will communicate with; this could be a delegate value (ex: @published, @latest) or the UUID (ex: aa1e4567-e89b-12d3-a456-426614158700)

Examples

Full examples are located in the examples folder of this repository.

API

SASChatElement

SASChatElement is a custom HTML element that renders a chat window. This element extends HTMLElement.

To find the correct values for the url, botUri, and revisionId attributes, see the Getting Started section.

Custom Element Tag

<sas-chat url="https://my-viya-server.com"
          botUri="/naturalLanguageConversations/bots/ca433b17-157b-46e9-9d60-d91d81991639"
          connectorName="connectorName"
></sas-chat>

Attributes

authenticationType: string

Choose the method to authenticate requests to the SAS Viya server:

• 'guest' automatically signs in to the SAS Viya server as the guest user.
• 'credentials' uses SAS Logon to establish an authenticated session.

default value: 'credentials'

url: string

Specify the URL of the SAS Viya server that hosts the report. This is the full context root, including the protocol, optional port, and host.

botUri: string

Specify the bot URI.

revisionId: string

Specify the revision Id.

default value: '@published'

userId: string

Specify the user id. This value is only used when authenticationType is 'guest'. This is only used for tracking/display and is not related to authorization or security.

default value: user id of authenication Viya user

userName: string

Specify the user name. This value is only used when authenticationType is 'guest'. This is only used for tracking/display and is not related to authorization or security.

default value: user name of authenication Viya user

connectorName: string

Specify the name of the connector displayed in the bot history view

sessionProperties: Object

Specify a JSON object containing data to add to the chat session at creation.

Properties

chatEventListener: Function

A JavaScript function that will be called for all chat events.

Contributing

We welcome your contributions! Please read CONTRIBUTING.md for details on how to submit contributions to this project.

License

This project is licensed under the Apache 2.0 License.

Additional Resources

SAS Conversation Designer Documentation

FAQ

How do I find the botId for my bot?

The most common way to find the botId for a bot is using the Natural Language Conversations API (ex: if SAS Conversation Designer was deployed to http://yourcompany.com/SASConversationDesigner, then the base URL for the API would typically be http://yourcompany.com/naturalLanguageConversations). Once you have found the base URL, you can then call GET on the bots endpoint (ex: http://yourcompany.com/naturalLanguageConversations/bots). This will return a list of all bots that currently exist and you search the list for your bot. Once you find it the botId value is shown as 'id'.

Here is an example:

{
...
"items": [
  {
  "id": "7d3137bf-c306-4127-b513-3e3ab816d125",
  "createdBy": "sas",
  "creationTimeStamp": "2020-08-31T14:19:36.136Z",
  "modifiedBy": "sas",
  "modifiedTimeStamp": "2020-08-31T14:19:36.276Z",
  "name": "My bot",
  ...

The 'id' value (ex: 7d3137bf-c306-4127-b513-3e3ab816d125) should be used as the botId mentioned above.

How do I find the revisionId for my bot?

There are three options for revisionId:

• @published - (recommended) this value points to the published version of your bot, then each time a new bot version is published, the connector automatically updates to use the most recently published bot version
• @latest - this value points to the latest/draft version of your bot, then each time a new bot latest/draft is created, the connector automatically updates to use the new latest/draft bot version
• specific revision id - this value points to a specific version the bot and will not change as versions are published or created

To find a specific revision id, follow the above instructions on how to get the botId. Then you can use the API to get access to all of the revisions available for a bot. This can be done by calling GET on the revisions endpoint (ex: http://yourcompany.com/naturalLanguageConversations/bots/{botId}/revisions). This will return a list of all revisions that currently exist for your bot. Then find the revision you are interested in and the revision value is shown as 'id'.

Here is an example:

{
...
"items": [
  {
  "id": "e09881bb-3206-4d73-a9c0-a6280202c188",
  "createdBy": "sas",
  "creationTimeStamp": "2020-08-31T14:19:36.136Z",
  "modifiedBy": "sas",
  "modifiedTimeStamp": "2020-08-31T14:19:36.276Z",
  "name": "My best revision",
  ...

The 'id' value (ex: e09881bb-3206-4d73-a9c0-a6280202c188) should be used as the revisionId mentioned above.

I'm getting a CORS error. How do I fix it?

When the sdk is deployed in a different domain than SAS Viya, you will need to update the SAS Viya CORS configuration to allow access. Instructions can be found on developers.sas.com.