Creating source plug-ins

Source-type plug-ins are defined with upgrade.xml, info.xml, and plugin.xml files.

Like automation plug-ins, source plug-ins are defined with three files: upgrade.xml, info.xml, and plugin.xml. The structure of the first two files is identical for both plug-in types. The structure of the plugin.xml file for the two plug-in types is different. Source-type plug-ins contain five SCM-type steps and the server:plugin-type property is Source.

The following code fragment contains a typical example of a source plug-in header element:

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://www.urbancode.com/PluginXMLSchema_v1"
   xmlns:server="http://www.urbancode.com/PluginServerXMLSchema_v1"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <header>
    <identifier id="com.urbancode.air.plugin.git" name="Git" version="4"/>
    <description>
       The Git Plugin automates cloning a Git repo, tagging source, and publishing source changes to the Changes tab of the Build Life.
    </description>
    <tag>SCM/Git</tag>
    <server:plugin-type>Source</server:plugin-type>
  </header>

    <!-- ==================================== -->
    <!--   SCM STEPS                          -->
    <!-- ==================================== -->

    <step-type name="Git Cleanup">
      <description>Perform a cleanup of the Git working directory</description>
      <properties>
        <property name="source">
          <server:property-ui type="sourcePropSheetRef"
                              label="Source Config"
                              hidden="true"/>
        </property>
      </properties>
      <post-processing><![CDATA[
        if (properties.get("exitCode") != 0) {
            properties.put(new java.lang.String("Status"), new java.lang.String("Failure"));
        }
        else {
            properties.put("Status", "Success");
        }
     ]]></post-processing>

      <command program="${GROOVY_HOME}/bin/groovy">
        <arg value="-cp"/>
        <arg path="classes"/>
        <arg file="cleanup.groovy"/>
        <arg file="${PLUGIN_INPUT_PROPS}"/>
        <arg file="${PLUGIN_OUTPUT_PROPS}"/>
      </command>

      <server:type>SCM_Cleanup</server:type>
      <server:validation language="javascript">
      </server:validation>
    </step-type>

Cleanup step

The Cleanup step requires the sourcePropSheetRef property. The step type must be SCM_Cleanup.

The following code fragment contains an example of a source plug-in SCM_Cleanup step:

<step-type name="Git Cleanup">
  <description>Perform a cleanup of the Git working directory</description>
  <properties>
    <property name="source">
      <server:property-ui type="sourcePropSheetRef"
                          label="Source Config"
                          hidden="true"/>
    </property>
  </properties>
  <post-processing><![CDATA[
    if (properties.get("exitCode") != 0) {
        properties.put(new java.lang.String("Status"), new java.lang.String("Failure"));
    }
    else {
        properties.put("Status", "Success");
    }
 ]]></post-processing>

  <command program="${GROOVY_HOME}/bin/groovy">
    <arg value="-cp"/>
    <arg path="classes"/>
    <arg file="cleanup.groovy"/>
    <arg file="${PLUGIN_INPUT_PROPS}"/>
    <arg file="${PLUGIN_OUTPUT_PROPS}"/>
  </command>

  <server:type>SCM_Cleanup</server:type>
  <server:validation language="javascript">
  </server:validation>
</step-type>

Checkout/Populate step

The Checkout/Populate step type must be SCM_Populate. The Checkout/Populate step has the following properties:

sourcePropSheetRef
date
cleanWorkspace

The following code fragment contains an example of a source plug-in SCM_Populate step:

<step-type name="Git Checkout">
  <description>Perform a Git checkout of the workflow's source</description>
  <properties>
    <property name="cleanWorkspace">
      <server:property-ui type="checkBox"
                          label="Clean Workspace"
                          description="Erase all files from the workspace before performing checkout" />
    </property>
    <property name="date">
      <server:property-ui type="textBox"
                          label="Date"
                          description="Date of sourcecode to checkout ('yyyy-MM-dd HH:mm:ss z' OR
                          'E MMM dd HH:mm:ss zzz yyyy' OR milliseconds since Unix Epoch). Defaults to the current time." />
    </property>
    <property name="source">
      <server:property-ui type="sourcePropSheetRef"
                          label="Source Config"
                          hidden="true"/>
    </property>
  </properties>
  <post-processing><![CDATA[
    if (properties.get("exitCode") != 0) {
        properties.put(new java.lang.String("Status"), new java.lang.String("Failure"));
    }
    else {
        properties.put("Status", "Success");
    }
 ]]></post-processing>

  <command program="${GROOVY_HOME}/bin/groovy">
    <arg value="-cp"/>
    <arg path="classes"/>
    <arg file="checkout.groovy" />
    <arg file="${PLUGIN_INPUT_PROPS}"/>
    <arg file="${PLUGIN_OUTPUT_PROPS}"/>
  </command>

  <server:type>SCM_Populate</server:type>
  <server:validation language="javascript">
  </server:validation>
</step-type>

Label step

The Tag/Label step type must be SCM_Label. The Tag /Label step has the following properties:

sourcePropSheetRef
message
label

The following code fragment contains an example of a source plug-in SCM_Label step:

<step-type name="Git Create Tag">
  <description>Create a tag in Git of the specified working copy.</description>
  <properties>
    <property name="message" required="true">
      <server:property-ui type="textBox"
                          label="Message"
                          description="A message for the commit" />
    </property>
    <property name="label" required="true">
      <server:property-ui type="textBox"
                          label="Tag"
                          description="The tag name to create" />
    </property>
    <property name="source">
      <server:property-ui type="sourcePropSheetRef"
                          label="Source Config"
                          hidden="true"/>
    </property>
  </properties>
  <post-processing><![CDATA[
    if (properties.get("exitCode") != 0) {
        properties.put(new java.lang.String("Status"), new java.lang.String("Failure"));
    }
    else {
        properties.put("Status", "Success");
    }
 ]]></post-processing>

  <command program="${GROOVY_HOME}/bin/groovy">
    <arg value="-cp"/>
    <arg path="classes"/>
    <arg file="tag.groovy"/>
    <arg file="${PLUGIN_INPUT_PROPS}"/>
    <arg file="${PLUGIN_OUTPUT_PROPS}"/>
  </command>

  <server:type>SCM_Label</server:type>
  <server:validation language="javascript">
  </server:validation>
</step-type>

Changelog step

The Changelog step type must be SCM_Changelog. The Changelog step has the following properties:

sourcePropSheetRef
changesURL
startBuildLifeId
endDate
startDate

Use these properties to define the date range used when searching for changes.

The following code fragment contains an example of a source plug-in SCM_Changelog step:

<step-type name="Git Changelog">
  <description>Perform a Git changelog and publish the results.</description>
  <properties>
    <property name="startBuildlifeId">
      <server:property-ui type="textBox"
                          label="Start BuildLife Id"
                          description="The ID of the start buildlife. Captures changes since that build life." />
    </property>
    <property name="startDate">
      <server:property-ui type="textBox"
                          label="Start Date"
                          description="Start changelog at this date ('yyyy-MM-dd HH:mm:ss z' OR
                          'E MMM dd HH:mm:ss zzz yyyy' OR milliseconds since Unix Epoch)" />
    </property>
    <property name="endDate">
      <server:property-ui type="textBox"
                          label="End Date"
                          description="End changelog at this date ('yyyy-MM-dd HH:mm:ss z' OR
                          'E MMM dd HH:mm:ss zzz yyyy' OR milliseconds since Unix Epoch)" />
    </property>
    <property name="changesUrl">
      <server:property-ui type="textBox"
                          label="Changes URL"
                          hidden="true" />
    </property>
    <property name="source">
      <server:property-ui type="sourcePropSheetRef"
                          label="Source Config"
                          hidden="true"/>
    </property>
  </properties>
  <post-processing><![CDATA[
    if (properties.get("exitCode") != 0) {
        properties.put(new java.lang.String("Status"), new java.lang.String("Failure"));
    }
    else {
        properties.put("Status", "Success");
    }
 ]]></post-processing>

  <command program="${GROOVY_HOME}/bin/groovy">
    <arg value="-cp"/>
    <arg path="classes"/>
    <arg file="changelog.groovy"/>
    <arg file="${PLUGIN_INPUT_PROPS}"/>
    <arg file="${PLUGIN_OUTPUT_PROPS}"/>
  </command>

  <server:type>SCM_Changelog</server:type>
  <server:validation language="javascript">
  </server:validation>
</step-type>

QuietPeriod step

The QuietPeriod step type must be SCM_QuietPeriod. The QuietPeriod step has the following properties:

sourcePropSheetRef
endDate
startDate

The QuietPeriod step typically runs the same command as the Changelog step. It always looks for the date of the latest change in the source repository.

The following code fragment contains an example of a source plug-in SCM_QuietPeriod step:

<step-type name="Git Quiet Period">
  <description>Perform a Git changelog for quiet period detection and publish most recent change date within the period.</description>
  <properties>
    <property name="startDate">
      <server:property-ui type="textBox"
                          label="Start Date"
                          description="Start changelog at this date ('yyyy-MM-dd HH:mm:ss z' OR
                          'E MMM dd HH:mm:ss zzz yyyy' OR milliseconds since Unix Epoch)" />
    </property>
    <property name="endDate">
      <server:property-ui type="textBox"
                          label="End Date"
                          description="End changelog at this date ('yyyy-MM-dd HH:mm:ss z' OR
                          'E MMM dd HH:mm:ss zzz yyyy' OR milliseconds since Unix Epoch)" />
    </property>
    <property name="source">
      <server:property-ui type="sourcePropSheetRef"
                          label="Source Config"
                          hidden="true"/>
    </property>
  </properties>
  <post-processing><![CDATA[
    if (properties.get("exitCode") != 0) {
        properties.put(new java.lang.String("Status"), new java.lang.String("Failure"));
    }
    else {
        properties.put("Status", "Success");
    }
 ]]></post-processing>

  <command program="${GROOVY_HOME}/bin/groovy">
    <arg value="-cp"/>
    <arg path="classes"/>
    <arg file="quietperiod.groovy"/>
    <arg file="${PLUGIN_INPUT_PROPS}"/>
    <arg file="${PLUGIN_OUTPUT_PROPS}"/>
  </command>

  <server:type>SCM_QuietPeriod</server:type>
  <server:validation language="javascript">
  </server:validation>
</step-type>