Skip to content

Latest commit

 

History

History
225 lines (148 loc) · 11.8 KB

developer_docs.md

File metadata and controls

225 lines (148 loc) · 11.8 KB
Raw

Mattermost ServiceNow Plugin

Table of Contents

License

See the LICENSE file for license rights and limitations.

Overview

This plugin integrates ServiceNow with Mattermost by allowing users to subscribe to record changes in ServiceNow and manage them through Mattermost. 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 contains the following features:

  • Connecting/disconnecting to ServiceNow account using OAuth.

  • Creating/editing subscriptions to get notifications for ServiceNow record changes using wizards.

    image

  • Ability to open the create/edit subscription modal through UI or slash commands.

    image

  • Ability to create a record or bulk subscription.

    image

  • A record subscription is for subscribing to changes in a specific record and a Bulk subscription allows subscribing to all records of a particular type.

  • Supported record types for subscriptions - incident, problem, change_request.

    image

  • Supported events:

    • State changed

    • Priority changed

    • Assigned to changed

    • Assignment group changed

    • New comment added

    • New record created (only for bulk subscriptions)

      image

  • Notifications will be sent in the form of a post created by the ServiceNow bot in the channel specified while creating the subscription.

    image

  • Ability to see the existing subscriptions in the Right-Hand Sidebar or slash command.

    • In Right-hand sidebar

      image

    • Using slash command

      image

  • Ability to delete the subscriptions from the Right-Hand Sidebar or slash command.

  • Ability to filter subscriptions using the slash command to get a post containing filtered subscriptions.

  • Ability to filter subscriptions in the Right-Hand Sidebar using the filter icon.

    image

  • Search and share a ServiceNow record in a specific channel.

    image

  • Ability to open search and share record modal through UI or slash command.

  • View comments on a ServiceNow record and add new comments.

    image

  • Supported record types for adding new comments - incident, problem, change_request, task, change_task and cert_follow_on_task.

  • Update the state of a ServiceNow record.

    image

  • Ability to open the "Add and View comments" modal or "Update State" modal through buttons present in a notification post or a shared record post.

  • Supported record types for sharing a record - incident, problem, change_request, kb_knowledge, task, change_task and cert_follow_on_task.

  • Supported record types for updating a record state - incident, task, change_task and cert_follow_on_task.

Basic Knowledge

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 Plugin.

Setup

Connecting to ServiceNow

There are two methods by which you can connect your Mattermost account to your ServiceNow account.

  • Using slash command

    • Run the slash command /servicenow connect in any channel.
    • You will get an ephemeral message from the ServiceNow bot containing a link to connect your account.
    • Click on that link. If it asks for login, enter your ServiceNow credentials and click Allow to authorize and connect your account.

  • Using the button in the right-hand sidebar

    • Open the right-hand sidebar by clicking on the ServiceNow icon present in the channel header section of all channels.

    • You will see a button saying "Connect your account".

      image

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

After connecting successfully, you will get a direct message from the ServiceNow bot containing a Welcome message and some useful information along with some instructions for the system admins. Note: You will only get a direct message from the bot if your Mattermost server is configured to allow direct messages between any users on the server. If your server is configured to allow direct messages only between two users of the same team, then you will not get any direct message.

Development

Setup

Make sure you have the following components installed:

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 the /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

Creating/modifying the update set

The update set was created by creating a new application called ServiceNow for Mattermost Notifications using the "Studio" system application in ServiceNow. To open the app in Studio, navigate to All > System Applications > Studio and select the application "ServiceNow for Mattermost Notifications". Below is an image of how the application looks in the Studio.

image

As you can see, the application consists of 2 tables, 4 business rules, 4 event registrations, 4 script actions and 2 script includes sections. All of these contain some code. You can explore and modify the code according to your needs. Before doing any changes here, you should change the current application scope. Go to the ServiceNow home screen and hover on the globe icon present in the nav bar on the right side along with the search bar. Below is a screenshot of the icon:

image

As you can see in the screenshot, the application scope is "ServiceNow for Mattermost Notifications" but it is "Global" by default. So, change the application scope and you can also change the update set here if you want. You have to remember that whatever update set is selected here will contain the latest changes that you do in the application in Studio. If you don't change the update set, it will use the "Default" update set. After you have done all the required changes in the application in Studio, you can export the latest update set XML file from one of the two locations: All > System Update Sets > Retrieved Update Sets or All > System Update Sets > Local Update Sets. When you find the update set that you selected in the nav bar header before doing the changes, go to that update set and it will show all the changes you have done in the "Customer Updates" tab in the table at the bottom.

image

Then, you can merge this update set and the update set that you uploaded so that you can have all the changes in one update set. After both the update sets are merged, you can export the latest update as an XML file.

Made with ♥ by Brightscout