The plugin.xml file

This topic provides instructions on defining the elements of the plugin.xml file and their appropriate attributes.

The structure of plugin.xml

The structure of the plugin.xml file includes:

  • Elements used by all plugins such as the document type declaration and the <plugin> root element that identifies the XML schema type, PluginXMLSchema_v1.xsd.
  • The <header> element that provides the identity, version, and description of the plugin. See Plugin header: the header element.
  • The step definitions. Each step is defined with a <step-type> element that describes the step's functionality and properties. See Plugin steps: the step-type element.

Back to top

Plugin header: the header element

The required <header> element identifies the plugin and contains the following child elements:

Child elements Description
<identifier>

This element's attributes identify the plugin:

  • version. API version (the version number used for upgrading plugins is defined in the info.xml file).

  • id. Identifies the plugin.

  • name. The plugin name that appears on the Automation Plugins pane in Deployment Automation.

Enclose all values in single or double quotation marks.

<description> This element describes the plugin. It appears on the Deployment Automation page in the Deployment Automation user interface.
<tag> This element defines where the plugin is positioned in the process designer's hierarchy of plugins.

The location is defined by a string separated by slashes. For example, the Tomcat definition is Application Server/Java/Tomcat. In this case, the Tomcat steps are listed under the Tomcat item, which, in turn, is nested under the other two.

Here's an example of the <header> definition:

<header>
  <identifier version="3" id="com.&company;.air.plugin.Tomcat"name="Tomcat"/>
  <description>
  The Tomcat plugin is used during deployments to execute Tomcat run-book 
  automations and deploy or undeploy Tomcat applications.
    </description>
  <tag>Application Server/Java/Tomcat</tag>
</header>

Back to top

Plugin steps: the step-type element

Plugin steps are defined with the <step-type> element that represents a single step in the Deployment Automation process designer. A <step-type> element consists of a name attribute and the following child elements:

  • description
  • properties
  • command
  • post-processing

The required name attribute identifies the step. The description and name that you specify in the element are displayed in the process designer.

Here's an example of the <step-type> definition:

<step-type name="Start">
  <description>Start Apache HTTP server</description>

Back to top

Step properties: the properties element

The <properties> element is a container for properties, which are defined with the property tag. Each step has a single <properties> element that can contain any number of property child elements.

A property tag has a required name attribute, optional required attribute, and child elements, property-ui and value.

The following table describes property tag child elements:

Child elements Description
<property-ui>

This element defines how the property is presented in the Deployment Automation process designer. It contains the following attributes:

  • label. Identifies the name of the property shown in the process designer Properties.

  • description. Help shown for the property in Properties.

  • default-value. The default value of the property. This is displayed in Properties and is used by the step if left unchanged.

  • type. Identifies the type of widget displayed to users. Possible values are:

    • textBox. Enables users to enter an arbitrary amount of text, limited to 4064 characters.

    • textAreaBox. Enables users to enter an arbitrary amount of text in a multi-line text box. The length of the text is limited to 4064 characters.

    • secureBox. Used for passwords. Similar to textBox except values are redacted.

    • checkBox. Displays a check box. If selected, a value of true will be used; otherwise the property is not set.

    • selectBox. Requires a list of one or more values that will be displayed in a drop-down list box. Configuring a value is described below.

<value> This element specifies values for the selectBox type. Each value has a required label attribute, which is displayed to users, and a value used by the property when selected. Values are displayed in the order they are defined.

Here's an example of the <property> definition:

<property name="onerror" required="true">
 <property-ui type="selectBox"
    default-value="abort"
    description="Action to perform when statement fails: continue, stop, abort."
    label="Error Handling"/>
 <value label="Abort">abort</value>
 <value label="Continue">continue</value>
 <value label="Stop">stop</value>
</property>

Back to top

Step commands: the command element

Steps are performed by running the command-line command specified by the <command> element. The <command> element's program attribute defines the location of the tool that performs the command.

Make sure that the tool is located on the host and the agent invoking the tool has access to it.

Example: In this example, the location of the scripting tool groovy (the tool that performs the command) is invoked:

<command program='${GROOVY_HOME}/bin/groovy'>

You can run any command as long as it is in the path and is available.

The actual command and any parameters it requires are passed to the tool by the <command> element's <arg> child element. You can use any number of <arg> elements.

The following table describes the attributes of the <arg> element:

Attribute Description
<value> Specifies a parameter passed to the tool. The format is tool-specific. Must be enclosed in single quotation marks.
<path> Specifies the path to the files or classes required by the tool. Must be enclosed in single quotation marks.
<file> Specifies the path to any files required by the tool. The format is tool-specific. Must be enclosed in single quotation marks.

Because <arg> elements are processed in the order they are defined, ensure that the order conforms to that expected by the tool.

Here's an example of the <command> definition:

<command program='${GROOVY_HOME}/bin/groovy'>
  <arg value='-cp' />
  <arg path='classes:${sdkJar}:lib/commons-codec.jar:
                  lib/activation-1.1.1.jar:
                  lib/commons-logging.jar:lib/httpclient-cache.jar:
                  lib/httpclient.jar:lib/httpcore.jar:
                  lib/httpmime.jar:lib/javamail-1.4.1.jar' />
  <arg file='registerInstancesWithLB.groovy' />
  <arg file='${PLUGIN_INPUT_PROPS}' />
  <arg file='${PLUGIN_OUTPUT_PROPS}' />
</command>

The <arg file='${PLUGIN_INPUT_PROPS}' /> specifies the location of the tool-supplied properties file.

The <arg file='${PLUGIN_OUTPUT_PROPS}' /> specifies the location of the file that will contain the step-generated properties.

New lines are not supported by the <arg> element. In this example, they are shown only for presentation.

Back to top

Step post-processing: the post-processing element

When a plugin step's <command> element finishes processing, the step's required <post-processing> element runs. The <post-processing> element optionally sets the step's output properties and error handling.

The <post-processing> element can contain any valid JavaScript script (unlike the <command> element, <post-processing> scripts must be written in JavaScript). You can use your own scripts when configuring the step in the Deployment Automation process designer. Although not required, it is best practice for the scripts to be wrapped in a CDATA element.

You have access to a java.util.Properties variable called properties. The properties variable has several special properties:

  • exitCode. Contains the process exit code.
  • Status. Contains the step's status. A Status value of Success means that the step completed successfully.

Another available variable, scanner, can scan the step's output log on the agent and take actions depending on the result. The scanner variable may use the following public methods:

Method Description
register(String regex, function call) Registers a function to be called when the regular expression is matched.
addLOI(Integer lineNumber) Adds a line to the lines of interest list, which are highlighted in the Log Viewer. Implicitly called whenever scanner matches a line.
getLinesOfInterest() Returns a java.util.List of lines of interest. This can also be used to remove lines.
scan() Scans the log. Used after all regular expressions are registered.

The post-processing script can examine the step's output log and take actions based on the result. In the following code fragment, scanner.register() registers a string with a regular expression engine, then takes an action if the string is found. Once all strings are registered, it calls scanner.scan() on the step's output log line by line.

Here's an example of the code fragment where scanner.register() registers a string with a regular expression engine and then takes an action if the string is found. After all strings are registered, it calls scanner.scan() on the step's output log line by line:

![CDATA[
    properties.put("Status", "Success");
    if (properties.get("exitCode") != 0) {
        properties.put("Status", "Failure");
    }
    else {
      scanner.register("(?i)ERROR at line",  function(lineNumber, line) {
          var errors = properties.get("Error");
          if (errors == null) {
              errors = new java.util.ArrayList();
          }
          errors.add(line);
          properties.put("Error", errors);
          properties.put("Status", "Failure");
      });
      .
      .
      .
      scanner.scan();
      var errors = properties.get("Error");
      if (errors == null) {
          errors = new java.util.ArrayList();
      }
      properties.put("Error", errors.toString());
    }
   ]]

Post-processing scripts enable you to set output properties that you can then use in other steps in the same process. This enables you to design complex workflows.

Reference prior step output properties with this syntax: ${p:stepName/propName}

Back to top

Example of a typical plugin.xml file

The following example demonstrates a typical plugin.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="PluginXMLSchema_v1" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <header>
    <identifier id="plugin_id" version="version_number" name="Plugin Name"/>
    <description/>
    <tag>Plugin_type/Plugin_subtype/Plugin_name</tag>
  </header>
  <step-type name="Step_Name">
    <description/>
    <properties>
      <property name="property_name" required="true">
        <property-ui type="textBox" label="Driver Jar" 
            description="The full path to the jdbc driver jar to use." 
            default-value="${p:resource/sqlJdbc/jdbcJar}"/>
      </property>
    </properties>
    <post-processing>
      <![CDATA[
        if (properties.get("exitCode") != 0) {
            properties.put("Status", "Failure");
        }
        else {
            properties.put("Status", "Success");
        }
    ]]>
  </post-processing>
  <command program="${path_to_tool">
      <arg value="parameters_passed_to_tool"/>
      <arg path="${p:jdbcJar}"/>
      <arg file="command_to_run"/>
      <arg file="${PLUGIN_INPUT_PROPS}"/>
      <arg file="${PLUGIN_OUTPUT_PROPS}"/>
  </command>
 </step-type>
</plugin>

Back to top

Next steps: