Action Development Guide

ACTION PARAMETERS

Sentinel Action plug-ins can include configuration-time parameters that control the run-time operation of those Actions. The parameter system is designed to be modular and re-usable, but unlike Collectors Actions vary so much in operation that there are only a few common parameters.

You might use or create parameters, for example, to:

Allow implementors to select which Integrator instance to use with the Action instance.
Allow implementors to select different output formats produced by the Action.
Allow implementors to specify further detail of how the Integrator should function.
Allow implementors to specify which target objects to manipulate.
Allow implementors to control error reporting behavior of the Action itself.

Adding Parameters to an Action

Parameters are included with a given Action in a very simple way; by listing them in a file. There are two different types of parameters — those provided with the template, and those created custom for each Action — and hence there are two relevant files under the individual Action's parameters directory:

template.pml: This file allows the developer to list the parameters to be included from the template. Template parameters are stored in //current/sdk/2011.1/Action/static/parameters as individual files; review those files to see what parameters you can use from the template (at this time there's only one such parameter: integrator).
release.pml: This file lists the parameters that are locally defined for this particular release of the Action. These parameters are also implemented as individual files, each of which is included in the same parameters directory where release.pml is located.

The format of the PML files is very simple; each parameter to be included is listed on its own line. The parameter name is just the filename of the file that contains the parameter, with no extension. So for example to include the parameters defined in from_address.xml and display_fields.xml, you would add two lines to template.pml:

from_address
display_fields

Using Parameters In Your Code

Parameters are configured at deployment time of the Action by the person implementing that particular integration. The values set at that time for each parameter are then loaded into memory in JavaScript so that you can access them from your code. Parameters should be loaded into a global area of the instance object, which represents the running Action. The template will create a hash table called params under the global CONFIG area, and you will load the parameters there with the name of each hash element the name of the parameter and the value whatever value was configured for that parameter. Note however that the parameter name here is the InternalName defined in the parameter XML file, not the filename as specified in the PML file. For example, if an implementor sets the from_address parameter to Sentinel@netiq.com, then you will have:

instance.CONFIG.params.from == "Sentinel@netiq.com"

(review the contents of //current/sdk/2011.1/Action/static/parameters and see the InternalName element to find the name of the parameter).

Here's an example of how parameters are typically loaded:

instance.CONFIG.params.display_data = scriptEnv.getParameter("display_data");

Most parameters are simply strings, whether they are typed in by the implementor or they are part of an enumerated selectable list. Here's an example of how you might then use a parameter to control how your code functions:

if (instance.CONFIG.params.display_events == "all_events") {
    instance.CONFIG.multiEvent = true;
    // Fetch all events and display them    
}

Defining Custom Parameters

The process of defining custom parameters is as simple as creating a small XML file that describes the parameter and possible values. An example called sample.xml is provided for you in the default Action template, which is safe to delete if you are not planning to use it. You can copy that file and edit it to suit your needs, then all you have to do is add your new filename (without extension) to the release.pml file to include your custom parameter with the Action.

You may be able to figure out how to create your parameter simply by examining the samples, but the format of the parameter file is fully documented on a separate page — the format is used for several different plug-in types, including Collectors and Reports.

Forward to Additional Information
Back up to Develop to Sentinel