Create a custom action plugin

When defining Actions, the defaults are email notifications and alerts. You can extend the actions capabilities by using one of the Unomaly plugins or writing your own custom action plugin. This topic discusses how to write and configure a custom plugin to work with Unomaly Actions. For the list of Unomaly action plugins, see "Integrations and plugins".

Requirements

General:

• Write your custom plugin using Javascript supported by Node.js version 8.9.4 or greater.

For creating a working plugin:

• Write a package.json file with a valid "id" UUID.
• Write an index.js that implements the handle: function (event, context, callback)
• Any dependencies must be bundled using bundleDependencies in package.json

For installing in Unomaly:

• Tarball (.tgz) created using npm pack

Configuration

Configuring your custom plugin involves creating a package.json file, creating an index.js file, installing the dependencies, and creating the tarball to install in Unomaly.

Name your project

Create a new directory and give it a descriptive name starting with unomaly-plugin-. For example, if you are writing a plugin for a chat server, called ChatService, you may name the directory: unomaly-plugin-chatservice.

This plugin name will also be used in the name property inside package.json.

Create a package.json file

1. In the plugin directory you created, copy the sample below into a file named package.json. This file will store the configuration for your plugin.

 {
     "id": "<NOT-A-VALID-ID>",
     "name": "unomaly-plugin-myname",
     "description": "My Company's ChatService Plugin",
     "version": "1.0.0",
     "main": "index.js",
     "license": "ISC",
     "parameters": {
       "type": "object",
       "properties": {
         "channel": {
           "title": "Channel",
           "description": "Messages will be sent to this channel",
           "type": "string"
         }
       },
       "required": [
         "channel"
       ]
     },
     "configuration": {
       "type": "object",
       "properties": {
         "webhookUrl": {
           "title": "WebHook URL",
           "description": "ChatService generated WebHook to use for this pluginZ",
           "type": "string",
           "format": "uri"
         }
       },
       "required": [
         "webhookUrl"
       ]
     },
     "icon": "",
     "bundleDependencies": []
 }

2. In a terminal window, generate a UUID:

uuidgen

3. Copy and paste the UUID into the "id" value field of package.json.

Create index.js

In the project directory, copy the following into a file called index.js:

module.exports = {
    handle: function (event, context, callback) {
        // Do something with event
    }
};

Install and bundle dependencies

In the project directory, run the following command to install dependencies and save them to bundleDependencies:

npm install [module_name] --save-bundle

Install the plugin in Unomaly

1. In the project directory, run the following command to generate a .tgz file that can be installed in Unomaly:

npm pack

2. To install the plugin in Unomaly, move the .tgz file to /DATA/plugins/js/load on the Unomaly instance.

Unomaly will detect and automatically load the new plugin. You can verify that the plugin was successfully installed by looking in the file: /DATA/unomaly_logs/pluginjs.log.

Development reference

Configuration property

Your plugin configuration will be accessible in the Unomaly user interface in Settings > Plugins. Configuration is defined in the configuration property in package.json. Each entry in properties must follow the specification:

"configuration": {
    "type": "object",
    "properties": {
        "webhookUrl": {
            "title": "WebHook URL",
            "description": "ChatService generated WebHook to use for this plugin",
            "type": "uri"
        }
    },
    "required": ["webhookUrl"]
}

Parameters property

Parameters will be accessible in the Unomaly user interface for every Action that is created. This means that you can configure different actions by varying the parameters you send to the plugin. For example, you may want to send a notification to a different chat channel depending on the severity of the situation score.

Parameters are defined in the parameters property in package.json. The format is the same as for the configuration properties. Below is an example:

"parameters": {
     "type": "object",
     "properties": {
         "channel": {
             "title": "Channel",
             "description": "Messages will be sent to this channel",
             "type": "string"
         }
     },
     "required": ["channel"]
}

Arguments to handle

The handle function takes 3 arguments: event, context, and callback:

The following are callback examples:

callback(); // Plugin was executed without error
callback(null); // Same as above - Plugin was executed without error
callback(null, "Informative message"); // Plugin was executed without error and 
an informative message was passed on
callback(new Error("Something went wrong")); // Plugin was executed with error

Event types - situation

When event == "situation", the context argument in handle contains the following information:

The following is an example of a situation event type:

{
  env: {
      unomalyHostname: 'unomaly.mycompany.com'
  },
  parameters: {
      channel: '#thechannel'
  },
  configuration: {
      webhookUrl: "https://chatservice.mycompany.com/webhooks/123"
  },
  data: {
      count: 1,
      knowns: {
          "5a68887810c95710f0b88a08": {
              name: "Database maintenance",
              classification: "NOTICE",
              tags: ["database", "maintenance"],
              meaning: "Someone is executing maintenance commands for a DB",
              solution: "Ignore",
              reason: "Maintenance",
              id: "5a68887810c95710f0b88a08",
          }
      },
      situationId: "123",
      url: "https://10.44.251.26/situations/123",
      score: 3,
      systems: {
          456: {
              url: "https://10.44.251.26/situations?condition[]=has:host:db-system",
              id: "456",
              name: "db-system",
          },
      },
      topEvent: {
          knowns: ["5a68887810c95710f0b88a08"],
          timestamp: "1519649306",
          system: "456",
          frequency: "weekly",
          data: "Database tables successfully compacted\nNo reindex needed",
          firstSeen: "1518768860",
      },
      createdAt: "1519649306",
  },
}

Event types - away

When event == "away", the context argument in handle contains the following information:

The following is an example of a away event type:

{
  env: {
      unomalyHostname: 'unomaly.mycompany.com'
  },
  parameters: {
      channel: '#thechannel'
  },
  configuration: {
      webhookUrl: "https://chatservice.mycompany.com/webhooks/123"
  },
  data: {
      situationId: '1580911',
      url: 'https://unomaly.mycompany.com/situations/123',
      score: 10,
      system: {
          url: 'https://unomaly.mycompany.com/situations?condition[]=has:host:my-system',
          id: '95',
          name: 'my-system'
      },
      awaySince: '1520263800',
      createdAt: '1520263800'
  }
}