Webex Teams Notification Bot for AppDynamics Using BotKit

Inspired by BotKit samples for Webex Teams by Stève Sfartz mailto:stsfartz@cisco.com

Instructions for deployment

Either if you deploy locally or to Heroku, you'll need to perform these two tasks first:

Create a Bot Account from the 'Webex for developers' bot creation page, and copy your bot's access token.
Create an AppDynamics account if you don't already have one and copy your AppD account name (TIP: for SaaS deployments, the account name is what comes before "saas.appdynamics.com" in the URL).

Note: If you just need to demostrate the functionality of the bot, you don't need an AppDynamics account. You can just checkout the demo branch of this repository and launch a completely stand alone bot with dummy data.

Heroku deployment

Click below to quickly deploy the bot to Heroku. You will need the following information:

Your Bot token
Your AppDynamics account name
Your public URL (for a Heroku deployment this would be https://{app-name}.herokuapp.com, where {app-name} is the name you chose for your Heroku app).

Note: Again, if you just need to demostrate the functionality of the bot, you don't need an AppDynamics account. You can just deploy the demo branch of this repository to Heroku navigating first to the demo branch.

Local deployment

Choose your storage type. You have two options: local storage using JSON File Store (JFS) or Redis, a NO-SQL, in-memory data structure store. If you choose to use JFS, you don't have to install anything yourself. If you choose to use Redis you'll need to download and install it on your local machine, with the default settings (port 6379).
[Optional] Webex Teams uses a webhook to send incoming messages to your bot, but webhooks require a public IP address. If you don't have one, you can use ngrok to create a tunnel to your machine. Launch ngrok to expose port 3000 of your local machine to the internet:
```
ngrok http 3000
```
Pick the HTTPS address that ngrok is now exposing. Note that ngrok exposes HTTP and HTTPS protocols, make sure to pick the HTTPS address.
[Optional] Open the .env file and modify the settings to accomodate your bot.

Note that you can also specify any of these settings via env variables. In practice, the values on the command line or in your machine env will prevail over .env file settings. In the example below, we do not modify any value in settings and specify all configuration values on the command line.
You're ready to run your bot

From a bash shell, type:

> git clone https://github.com/AltusConsulting/sparkbot-appd-botkit.git
> cd sparkbot-appd-botkit
> npm install
> BOT_TOKEN=0123456789abcdef PUBLIC_URL=https://abcdef.ngrok.io SECRET="not that secret" APPD_ACCOUNT=myappdaccount1234567890 node bot.js

If you're using Redis, this last command would be:

> BOT_TOKEN=0123456789abcdef PUBLIC_URL=https://abcdef.ngrok.io SECRET="not that secret" APPD_ACCOUNT=myappdaccount1234567890 REDIS_URL=redis://localhost:6379/1 node bot.js

From a windows shell, type:

> git clone https://github.com/AltusConsulting/sparkbot-appd-botkit.git
> cd sparkbot-appd-botkit
> npm install
> set BOT_TOKEN=0123456789abcdef
> set PUBLIC_URL=https://abcdef.ngrok.io
> set SECRET=not that secret
> set APPD_ACCOUNT=myappdaccount1234567890
> node bot.js

If you're using Redis, you'll need to add an additional environment variable before launching the bot:

> set REDIS_URL=redis://localhost:6379/1

where:

BOT_TOKEN is the API access token of your Webex Teams bot.
PUBLIC_URL is the root URL at which Webex Teams can reach your bot. If you're using ngrok, this should be the URL ngrok exposes when you run it.
SECRET is the secret that Webex Teams uses to sign the JSON webhooks events posted to your bot.
APPD_ACCOUNT is your AppDynamics account name.
REDIS_URL is the URL of the Redis instance you installed.

Testing your bot

To test that your bot is online, add it to your Webex Teams account as you will add any other contact and ask the bot for help with the help command.

Notifications Module

The notifications module allows you to subscribe to specific types of notifications (Errors, Warnings and Informational), so that when your AppDynamics instance detects an event in one of your monitored applications the AppD Bot will send you a message directly via Webex Teams.

Subscribing to a notification

You can subscribe to a notification by telling the AppD Bot:

subscribe

or, for short:

sub

The bot will then ask you what type of notification you want to subscribe to. You can subscribe to INFO, WARN or ERROR notifications.

Unsubscribing from a notification

You can subscribe to a notification by telling the AppD Bot:

unsubscribe

or, for short:

unsub

The bot will then ask you what type of notification you want to unsubscribe from.

Showing your current subscriptions

You can ask the bot for a list of your current subscriptions:

show subscriptions

or, for short:

show sub

Interactive Mode

You can interactively query your AppDynamics instance to get information about applications, events and application metrics.

Show configured applications

You can show the existing configured applications with the following command:

show applications

or, for short:

show apps

The bot will then show a list of the existing applications.

Show recent events

You can request the recent events for a specific application with the following command:

show events

or, for short:

show ev

The bot will then ask for the application for which you want to retrieve the events. Once you answer with one of the available applications the bot will then show a list of the most recent events for that specific application. For the time being this command retrieves events for the last week only. In the future this will be configurable.

Show metrics for an application

You can request the metrics for a specific application with the following command:

show metrics for <app name>

for example, if there's an application called MyNodeApp, the command should be:

show metrics for MyNodeApp

The bot will then answer with all the Overall Application Performance metrics for the last 60 minutes. In the future, other metrics will be available as well and the time period will be configurable.

Configuring your AppD server

In order for notifications to be sent to your bot, you need to configure your AppD server accordingly. Here are the steps:

1. Create an HTTP Request Template.

Navigate to Alert & Respond -> HTTP Request Templates.
Select New to create a new template.

Fill the information as follows:

Name: Something like "Webex Bot" or "Webex Teams"
Method: POST
Raw URL: http://<PUBLIC_URL>/appd where PUBLIC_URL is the Internet facing URL where the bot can be reached, as defined in your environment variables
URL Encoding: UTF-8
Authentication: NONE
MIME Type: application/json
Payload encoding: UTF-8
Payload:

[
#foreach(${event} in ${fullEventList})
    #set( $msg = $event.summaryMessage.replace("
", "\\n") )
    {"app": "${event.application.name}",
    "appid": "${event.application.id}",
    "tier": "${event.tier.name}",
    "node": "${event.node.name}",
    "time": "${event.eventTime}",
    "deeplink": "${event.deepLink}",
    "name": "${event.displayName}",
    "severity": "${event.severity}",
    "message": "${msg}"}
    #if($velocityCount != $fullEventList.size()) , #end
#end
]

2. Create an Action.

Navigate to Alert & Respond -> Actions.
Select Create to create a new action.
Select HTTP Request -> Make an HTTP Request and the press OK.
Assign a name to the request. It can be something like "Webex Teams Bot"
From the HTTP Request Template dropdown list select the template created in the previous step.

3. Create a Policy.

Navigate to Alert & Respond -> Policies.
Select Create to create a new policy.
Assign a name to your policy.
Select the Health Rule Violation Events and/or Other Events you want to be notified about, depending on your needs.
Press Next
In Actions to Execute press the plus (+) sign and then select the action you created in the previous step. Press Select.

Now you should begin receiving notifications from the AppD Bot on Webex Teams, once you subscribe to them.