Development Topics

PLUG-IN PARAMETERS

Parameters are used by several plug-in types to provide easily-selectable deployment-time configuration. A number of default template parameters are provided, and you can define your own as necessary. Refer to the documentation for each plug-in type for information about how to use parameters for that type. This section documents the parameter XML file structure, so you can define your own custom parameters.

Parameter Structure

Plug-ins that accept parameters will have a parameters subdirectory in them. This directory will contain several files, including:

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/<plug-in type>/parameters as individual files; review those files to see what parameters you can use from the template.
release.pml: This file lists the parameters that are locally defined for this particular release of the Collector. These parameters are also implemented as individual files, each of which is included in the same parameters directory where release.pml is located.
sample.xml: This file contains a sample parameter definition which you can clone and use for your own purposes, or delete if you will not be using it.

Each parameter is defined in a small XML file that describes the parameter name and what values are possible. There is a sample.xml file provided in the plug-in development directory, plus you can look in the template for many more examples of what is possible.

Plug-in Parameter Process

Follow this process when constructing the parameter lists for your plug-in:

Review the list of parameters in the template.pml file and remove any that are not appropriate
Review the list of template parameters provided in /proj/content/dev/sdk/2011.1/<plugtype>/static/parameters and add any that are needed by this plug-in
If you need additional parameters:
1. Construct a local <parameter name>.xml file in the plug-in's /parameters directory. Use the sample.xml file already in that directory as an example/template.
2. Edit the new <paramname>.xml file to describe the parameter.
3. For Report plug-ins, if you want the user to be prompted for the new parameter be sure to set <IsForPrompting>1</IsForPrompting>.
4. Edit the release.pml file and add your new <parameter name> to it.
If you want to use a template parameter but need to change it slightly (provide different default values, for example), copy it from the template into the release directory and reference it in release.pml

XML Parameter Definition File Structure

A typical parameter XML file might look like this:

 <PluginParameterDefinition>   
 <Type>String</Type>   
 <DisplayName>Test Option String</DisplayName>   
 <InternalName>TestOptionString</InternalName>   
 <Description>Select an option.</Description>   
 <DefaultValue>B</DefaultValue>   
 <Options>     
  <Property>       
   <Value>A</Value>       
   <Name>Option A</Name>     
  </Property>     
  <Property>       
   <Value>B</Value>       
   <Name>Option B</Name>     
  </Property>     
  <Property>       
   <Value>C</Value>       
   <Name>Option C</Name>     
  </Property>   
 </Options>   
 <OptionQuery>SELECT EVT_SRC_MGR_NAME as NAME, EVT_SRC_MGR_ID as VALUE FROM EVT_SRC_MGR</OptionQuery> 
</PluginParameterDefinition>

Here's what each element means:

PluginParameterDefinition: Declares that this block of XML defines a parameter (NOTE: For Collectors ONLY, this element is called <CollectorParameterDefinition>).
Type: Declares the data type of the parameter value; this can be "String" (freeform string), "Integer", or "Severity" (integer 0-5).
DisplayName: The string that will be displayed in the UI when the parameter is presented to the user for configuration.
InternalName: The internal name used to refer to the parameter; use this in your code when you wish to reference the parameter.
Description: Where the UI allows for it, this string is presented as a description of what this parameter does.
DefaultValue: The initial default value for this parameter, which the configuring user can override.
Options: Defines a set of enumerated options for this parameter; the possible settings are restricted to this set, and the UI will present a drop-down selection box. This element (and its children) are optional.
Property (Name/Value): Specifies one of the selectable optional values for this parameter. The Name specifies the string presented in the UI to the configuring user; the Value is what will actually be passed to the backend.

Note that individual plug-in types might have additional extensions and variations, which are documented in the type's respective documentation.

Collector Parameters

Back up to Develop to Sentinel