Adding Step Plugins to Cycle

Plugging a step plugin into Cycle requires special setup. A plugin developer must install the plugin's artifacts into the Cycle directory, configure the runtime, and write a settings file. All the step endpoints and lifecycle endpoints must already be implemented and tested as well.

Setting the plugin version

A step plugin should set version numbers to better keep track of features and updates. Semantic Versioning is recommended. A plugin's version numbers should be set in the following places:

1. in the OpenAPI spec file
2. in the packaging for the plugin
3. anywhere else in the plugin's files (depending upon the language)

Follow typical programming language conventions for setting package versions. For instance:

Language	Convention
Go	Create a tag for the version (like v1.0.0) in the project's git repository.
Java	Set the version in the Maven pom.xml file.
JavaScript (Node.js)	Set the version in the packages.json file.
Python	Set the version in the package's setup.py file or in a pyproject.toml file.
.NET	Set the version in the .csproj file.

Installing the plugin

All step plugins should be installed into a subdirectory under the Cycle installation folder: .../CycleLabs/Cycle/steps/<step-plugin>, where <step-plugin> is a directory name for the step plugin.

Each step plugin must contain the following:

• the OpenAPI spec file named schema.openapi.yml
• a settings file named settings.yml
• the executable artifacts (like a JAR file, an EXE file, or a directory of scripts)
• any other files the executables need

The executable artifacts must be "built" artifacts, not source code or project files. The plugin does not need to include source code files. The executable artifacts should be applicable for the local machine's operating system.

Configuring the runtime

The runtime for the language in which the step plugin is written must be made available to Cycle. Go and Java do not need special configuration, while other languages do. Please refer to the Runtime configuration guide for more details.

Writing the settings file

The step plugin requires a settings file named settings.yml that provides information for running the step plugin. This settings file must include the command to start the step plugin, and it may include other settings.

Setting the start command

The start command should be set like this:

# The plugin's name.
name: My Step Plugin

# The plugin's commands.
commands:

  # The command that Cycle will call to start the step plugin as a local service.
  start:

    # The plugin's executable type.
    # Options: [exe|jar|script]
    type: jar

    # The name of the executable artifact in the plugin directory.
    file: my-step-plugin.jar

    # Cycle provides a port number to the step plugin when starting its service.
    # The step plugin must provide the mechanism for receiving the port number.
    # It can use either a command line argument flag or an environment variable.
    # The plugin author should specify exactly one, but not both.
    portEnvironmentVariableName: SERVER_PORT
    # portFlagName: --port

The command object and start property are required. The exact invocation command will depend upon the step plugin and the local machine's operating system. The example above shows how to launch a step plugin built as a Java JAR file. It uses the SERVER_PORT environment variable to pass the port number into the step plugin service.

Most web frameworks enable the port to be set via a command line option or an environment variable. For example:

• Go's Gin web framework uses the PORT environment variable
• Java's Spring Boot web framework uses the SERVER_PORT environment variable

Check the mechanism for your chosen web framework. If none is provided, then you will need to write extra logic in your step plugin code to accept a command line option or environment variable for the port number.

Restarting Cycle after installation

After installing a new step plugin, restart the editor (either the Cycle Desktop IDE or the Cycle Testing VS Code extension) for Cycle to start using the new steps. After restarting, make sure the editor does not issue any step plugin error notifications. Resolve any errors that appear before attempting to write and run Cycle tests.

Updating or uninstalling Cycle

When Cycle is updated to a new version (such as updating from 2.20 to 2.21), any step plugins that you have added to Cycle will be saved. They will not be deleted or removed. You can continue using them in the updated Cycle version.

When Cycle is uninstalled from the local machine, all Cycle files in the installation directory including any step plugins that you have added will be deleted. If you reinstall Cycle fresh, you will need to reinstall the desired step plugins with it.