New in Splunk Enterprise 6.3, custom alert actions (also called modular alerts) allow a developer to define an integration that can be reused multiple times and in different ways based on the data being presented to it. Custom alert actions interact specifically with the alerts that were already present in Splunk. There are a few new components that go into making a custom alert action (let's call this a CAA). We will discuss the various components of a CAA and build a very simple CAA that will output the results of the search into a file within the App.

The first step in the creation of a CAA is to determine what your alert is intending to do. While it is possible for your alert to do multiple actions, do not try and combine multiple technologies unless necessary. For example, you wouldn't want to combine a Facebook action with a Twitter action, since both actions require separate authentication and authorization methodologies and credentials. Once you have narrowed the scope of your CAA, we can proceed with the very basics of a CAA. We won't dive into the full implementation of a CAA, due to the fact that Splunk has a set of really nice documentation. The full documentation of CAAs can be found at http://docs.splunk.com/Documentation/Splunk/latest/AdvancedDev/ModAlertsCreate.

For a very simple CAA, the basics that are required are as follows:

There are many more options available; we would suggest you read the documentation to get the full effect. Let's start with the name of our CAA. Let's call it file_write. Once we have our name, we will update alert_actions.conf to have the following information:

[file_write]
is_custom = 1
label = File Writer
alert.execute.cmd = caa_file_write.py
payload_format = JSON
param.res_link = $results_link$

Break it down now! The first line, the stanza heading, is the name of the CAA. The first attribute (is_custom) allows Splunk to know that the CAA is a custom alert, not a typical alert. The second attribute is label, which will show in the Splunk UI, so make it pretty and clear to understand. The third attribute (alert.execute.cmd) is the $APP_HOME/bin relative filename for the alert script that you are implementing. The fourth attribute (payload_format) specifies how you want to pass in data (JSON is very nice, but there are instances where XML might be preferred). The final attribute (param.res_link) is a custom parameter that will get sent to the script each time it is called.

Once you have the configuration stanza in place, you can place the script into the bin folder of $APP_HOME. Let's place the following code in a file called caa_file_write.py:

import sys, json, urllib2
def write_file(settings):
    f = open('myfile','w')
    f.write("%s"%json.dumps(settings))
    f.close()
if __name__ == "__main__":
    caa_config = json.loads(sys.stdin.read())
    write_file(caa_config)

Let's break it down. The first line is import statements. Pretty typical of Python, am I right? Then, we define a write_file function that will take the settings passed to the alert and write out the settings to a file. Then, our main code block pretty much just reads the config from the standard in, and passes it to the write_file function. Then, save it. Once we finish creating the custom alert (we need to add an HTML file first), and then create an alert, you will see a file with the settings written to it.

The user interface portion of the CAA is required in order to provide an interface for the end user to place configuration settings. This file, which should be named the same as the CAA (in this case, file_write.html), should be placed in $APP_HOME/default/data/ui/alerts. For example, let's take a look at the expected code:

<form class="form-horizontal form-complex">
  <div class="control-group">
    <label class="control-label" for="file_name">file_name</label>

    <div class="controls">
      <input type="text" name="action.file_write.param.file_name" id="file_name" />
      <span class="help-block">File name to write to (located in the local folder)</span>
    </div>
  </div>
</form>

As you can see, the UI HTML for CAAs is pretty simple. The HTML doesn't have to be a full HTML-spec page, it can be partial HTML, as long as it validates. It can also contain Bootstrap CSS classes and formatting. There are a few special bits. Located in the input tag above, the name attribute of the input correlates to the parameter name of the CAA. This allows Splunk to tie the two together, allowing custom settings. For each parameter, you would, in the same way, put the HTML into that file. Once these are in place, restart Splunk to pick up the changes. Once you have logged back in, open a search and search for anything. Save that search as an alert, choose the File Write alert, and give it a filename (if you wish). After that, sit back and enjoy the file on the server. Of course, this is a super easy example, and you probably would want your CAA to do something useful. It's all in your hands now. For a more technical and in-depth read, consult the documentation, as it goes far deeper into requirements for App certification.