developer_docs.md

Mattermost ServiceNow Virtual Agent Plugin

Table of Contents

• License
• Overview
• Features
• Basic Knowledge
• Installation
• Setup
• Connecting to ServiceNow
• Development

License

See the LICENSE file for license rights and limitations.

Overview

This plugin integrates the ServiceNow Virtual Agent in Mattermost. It is created using the official Virtual Agent Bot API documentation which can be found here. For a stable production release, please download the latest version from the Plugin Marketplace and follow the instructions to install and configure the plugin.

Features

• This plugin supports sending the below fields to the Virtual Agent through Mattermost:

  1. Text messages

     

  2. File attachments

     

  3. Date/Time

     

     

• Handling/Displaying the following types of responses from the Virtual Agent:

  1. OutputText

     

  2. OutputImage

     

  3. OutputLink

     

  4. Picker/Dropdown

     

  5. OutputCard

     

Note- For sending file attachments to the Live Agent other than an image, you need to have ServiceNow version greater than or equal to "San Diego Patch 4". Also, the link of the file attachment sent to the Virtual Agent/Live Agent will be expired in 15 minutes.

Basic Knowledge

• What is ServiceNow?

• What is ServiceNow Virtual Agent?

  • Virtual Agent
  • Activating Virtual Agent

• Virtual Agent Bot Integration API

• Virtual Agent Designer

  To start a conversation with a Virtual agent we need to select a conversation topic. Virtual Agent provides various predefined conversation flows/topics for some common conversations and we can design our own conversation flows as well as mentioned here.

  • Virtual Agent Designer
  • Designing a Virtual Agent Topic

• Pre-defined Conversation Flows/Topics

  • Pre-defined Conversation Flows/Topics
  • Additional Plugins
  • Sometimes a conversation flow might not work because the user does not have access to some tables or APIs which are being used in that flow (You can see the errors in "All > System Log > Errors"). In such cases, you have to manually provide the access in "All > Application Cross-Scope Access".
    • Create cross-scope access privileges for topic blocks and custom controls

• File Upload

  For sending file attachments to the Virtual Agent or the Live Agent we need to send a public link of the file in the request from where the Virtual Agent can download it. Virtual Agent does not support sending file attachments from any source, we have to specify the trusted domains ourselves so that the Virtual Agent knows that the specified domains can be trusted.

  • Set up trusted media domains
    • Configuring the form layout

• Invalid response We get an "undefined" response from Virtual Agent API in a specific case. Please refer to this community question for more information about the issue. To bypass this issue, you should increase the value of va.bot.to.bot.take.control_times variable. You can read more about it here.

Installation

1. Go to the releases page of this GitHub repository and download the latest release for your Mattermost server.
2. Upload this file on the Mattermost System Console > Plugins > Management page to install the plugin. To learn more about how to upload a plugin, see the documentation.
3. Enable the plugin from System Console > Plugins > ServiceNow Virtual Agent.

Setup

• ServiceNow Setup
• Plugin Setup

Connecting to ServiceNow

• Send any direct message to servicenow-virtual-agent. Note- If servicenow-virtual-agent is not visible in your DMs, click on the plus(+) icon on the right side of "Direct Messages" and search for servicenow-virtual-agent.

  

• You will get a response with a link to connect your ServiceNow account.

  

• Click on that link. If it asks for login, enter your instance credentials and click Allow to connect your account.

Development

Setup

Make sure you have the following components installed:

• Go - v1.16 - Getting Started

  Note: If you have installed Go to a custom location, make sure the $GOROOT variable is set properly. Refer Installing to a custom location.

• Make

Building the plugin

Run the following command in the plugin repo to prepare a compiled, distributable plugin zip:

make dist

After a successful build, a .tar.gz file in /dist folder will be created which can be uploaded to Mattermost. To avoid having to manually install your plugin, deploy your plugin using one of the following options.

Deploying with Local Mode

If your Mattermost server is running locally, you can enable local mode to streamline deploying your plugin. Edit your server configuration as follows:

{
    "ServiceSettings": {
        ...
        "EnableLocalMode": true,
        "LocalModeSocketLocation": "/var/tmp/mattermost_local.socket"
    }
}

and then deploy your plugin:

make deploy

You may also customize the Unix socket path:

export MM_LOCALSOCKETPATH=/var/tmp/alternate_local.socket
make deploy

If developing a plugin with a web app, watch for changes and deploy those automatically:

export MM_SERVICESETTINGS_SITEURL=http://localhost:8065
export MM_ADMIN_TOKEN=j44acwd8obn78cdcx7koid4jkr
make watch

Deploying with credentials

Alternatively, you can authenticate with the server's API with credentials:

export MM_SERVICESETTINGS_SITEURL=http://localhost:8065
export MM_ADMIN_USERNAME=admin
export MM_ADMIN_PASSWORD=password
make deploy

or with a personal access token:

export MM_SERVICESETTINGS_SITEURL=http://localhost:8065
export MM_ADMIN_TOKEN=j44acwd8obn78cdcx7koid4jkr
make deploy