The Step Maven plugin serves as Command Line Interface (CLI) for all operations related to Automation Packages in Java. It provides an integration with the Step server and an easy way to integrate Step with a CI/CD pipeline. For non-Java projects, it is recommended to use the Step CLI.

The Step Maven plugin supports following operations:

• Upload Automation Packages to Step and execute them in isolation
• Deploy the content of Automation Packages to Step and enable the contained schedules

For compatibility reason it still supports following operation for the legacy Keyword packages

• Deploy Keyword Packages to Step (deprecated)

You can choose to integrate the plugin goals during the package phase or any later phase as you see fit in the Maven Lifecycle.

Integration

To include the Step plugin in your project you need to add the appropriate dependency to the <pluginManagement> section in your pom.xml.

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>ch.exense.step</groupId>
                <artifactId>step-maven-plugin</artifactId>
                <version>${step.plugin.version}</version>
            </plugin>
        </plugins>
    </pluginManagement>
</build>  

You can list the available plugin goals by calling the following command (in the folder of a maven project including the step-maven-plugin):

mvn step:help

To display the parameters of some plugin goal you can use the following command:

mvn step:help -Ddetail=true -Dgoal=goal-name

Once you have declared the plugin in the <pluginManagement> section, you can use it as any common Maven plugin: call a plugin goal directly from the command line, or bind a goal to a phase of the maven lifecycle (using the <plugins> section of the pom.xml file).

Integration with Step Enterprise Edition

The maven plugin supports the following optional features which are required to communicate with Step Enterprise, but should be left empty for Step Open Source:

• Authentication: the plugin allows to configure the API token which is used to authenticate to Step
• Project selection (multitenancy): because a user can have access to several projects in Step, the EE version allows to select the target project for deploying and running packages

Optional When triggering an execution on Step, an error summary is collected at the end of the execution in case of failure. To read error reports related to enterprise specific features an additional dependency reserved to Enterprise customer is required.

<pluginRepositories>
  <pluginRepository>
    <id>nexus-exense</id>
    <url>https://nexus-enterprise.exense.ch/repository/exense/</url>
  </pluginRepository>
</pluginRepositories>

<build>
  <pluginManagement>
    <plugins>
      <!-- Make the Step maven plugin available -->
      <plugin>
        <groupId>ch.exense.step</groupId>
        <artifactId>step-maven-plugin</artifactId>
        <version>${step.version}</version>
        <!-- adding dependencies to reports nodes for enterprise artefacts, only required to read errors that may occur during isolated executions -->
          <dependencies>
              <dependency>
                  <groupId>ch.exense.step-enterprise</groupId>
                  <artifactId>step-maven-plugin-ee-extensions</artifactId>
                  <version>${step.version}</version>
              </dependency>
          </dependencies>
      </plugin>
    </plugins>
  </pluginManagement>
</build>

Usage

Detailed descriptions of the goals are provided below.

Execute Automation Packages in Step

The maven goal execute-automation-package runs (executes) the plans contained in an Automation Package, on a one-off basis, and in an ephemeral context that is destroyed afterward. In other words, the Automation Package and its contents are not made permanently available on the server, but exist only temporarily during the execution.

The Automation Packages can either be:

• built as a part of current maven project
• an artefact deployed on an artefact repository

For this last case, the artifactGroupId, artifactId and artifactVersion must be specified. Remember that your Step instance needs to be configured to access this artefact repository.

Example:

<plugin>
  <groupId>ch.exense.step</groupId>
  <artifactId>step-maven-plugin</artifactId>
  <executions>
    <execution>
      <id>run-automation-package-in-step</id>
      <phase>package</phase>
      <configuration>
        <url>http://localhost:4201</url>
        <stepProjectName>Common</stepProjectName>
        <authToken>eyJhbGciO.....iJIUzI</authToken>
        <executionParameters>
          <env>PROD</env>
          <PARAM_EXEC>Value</PARAM_EXEC>
          <PARAM_EXEC2>Value</PARAM_EXEC2>
        </executionParameters>
      </configuration>
      <goals>
          <goal>execute-automation-package</goal>
      </goals>
    </execution>
  </executions>  
</plugin>

To call the plugin from the command line you can use the following command:

mvn package step:execute-automation-package "-Dstep.url=https://your.step.server/" "-Dstep.step-project-name=Common" "-Dstep.auth-token=yourtoken"

Please note the call to the package phase in this command line: it is required because the command step:execute-automation-package doesn’t build the project.

Deploy Automation Packages to Step

The maven goal deploy-automation-package deploys an Automation Package on a Step Server. The deployment makes available (and activates) all content contained in the Automation Package, such as keywords, plans, schedules, etc.

<plugin>
  <groupId>ch.exense.step</groupId>
  <artifactId>step-maven-plugin</artifactId>
  <executions>
    <execution>
      <id>deployed-automation-package-in-step</id>
      <phase>deploy</phase>
      <configuration>
        <url>http://localhost:4201</url>
        <stepProjectName>Common</stepProjectName>
        <authToken>eyJhbGciO.....iJIUzI</authToken>
      </configuration>
      <goals>
          <goal>deploy-automation-package</goal>
      </goals>
    </execution>
  </executions>  
</plugin>

To call the plugin from command line you can use the following command from the maven module where you have the deployed artifact with step Automation Package:

mvn deploy step:deploy-automation-package "-Dstep.url=https://your.step.server/" "-Dstep.step-project-name=Common" "-Dstep.auth-token=your_token_in_text_format"

Upload Keywords to Step (deprecated)

This Maven goal deploys a packaged jar containing Step keywords to the configured Step server as a Keyword Package. The plugin determines if the same Keyword Package has already been uploaded to Step earlier and updates it if found, otherwise it creates a new Keyword Package in Step.

You need to use the upload-keywords-package goal of the step-maven-plugin.

This goal has the following configuration

Example:

<plugin>
    <groupId>ch.exense.step</groupId>
    <artifactId>step-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>upload-package-to-step</id>
            <phase>package</phase>
            <configuration>
                <url>http://localhost:4201</url>
                <!-- For EE, configure the target project and authentication key -->
                <!--<stepProjectName>Common</stepProjectName>
                <authToken>eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJhMjUyYzhhNi1kO...</authToken>-->
              
                <!-- Example of library file configuration -->
                <!--
                  <libStepResourceSearchCriteria>
                    <id>64d933c88d944d61db7725e0</id>
                  </libStepResourceSearchCriteria> 
                -->
            </configuration>
            <goals>
                <goal>upload-keywords-package</goal>
            </goals>
        </execution>
    </executions>
</plugin>

You can use the following command to execute the plugin goal from the module containing package artifact with step keywords:

mvn package step:upload-keywords-package "-Dstep.url=https://your.step.server/"