Plugin.xml file

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

For an overview of the plugin.xml file, see Create plugins.

In this topic:

Plugin.xml structure

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:

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:

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.

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

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:

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 contains 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:

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:

• Upgrade.xml file