Pipelines Extension Step Model

Files

Extension step definitions must be stored in a subdirectory path of the form: steps/<namespace>/<stepTypeName>. 

• namespace  is the namespace for the set of extension sets. This parent subdirectory may contain multiple step definition subdirectories.
• stepTypeName is the named type of the step. Must be alphabetic characters only, and is case-sensitive. 

The subdirectory can hold the following files to define the step.

Extension step definitions are loaded from the source repository when it is configured in the Pipelines UI as an extension source.

Syntax Model

description: <string>		    # User can provide an optional description

configuration:                  # array of properties
  <property name string>:
    type: <data type>           # required
    validate:                   # optional
      <validation specifiction>

   # more property definitions


userDefinedDataType:             # array of data type definitions
  - type: <string>               # Defines a new data type
    configuration:
      - <string>:                # Specifies a property of the data type
        type: <data type>           # required
        validate:                   # optional
          <validation specifiction>

   # more data type property definitions

description

Optional

Value: String

A user-friendly description of the resource's function that will be available for display in the Pipelines UI.

configuration

A step extension inherits all of the same tags as the generic Bash step to specify scoped environment variables, runtimes, node pools, and other standard properties. It also inherits the tags for integrations , inputsteps, inputresources and outputresources. In addition, a step extension can define other properties that will be unique to the step.

The configuration tag begins a block of property definitions. Each property definition begins with the name of the property (letters only, case-sensitive), followed by these subordinate tags:

configuration:
  healthCheckUrl:
    type: Url
  notifyOnSuccess:
    type: Boolean
  notifyOnFailure:
    type: Boolean
  stuff:
    type: String[]
    validate:
      isRegex:  ["^[a-z]+$",'i']    # Each element in array is validated with this

userDefinedDataType

Begins a set of user-defined data type specifications. User-defined data types specify property types with validation rules, and can be used as type values in the step's property definitions.

The tag syntax is the same as used for the Resource Model.

Shell Scripts

An extension step definition may include optional shell scripts to be executed for the appropriate tags in step's the execution  blog. These scripts define the operation of the step.

onExecute.sh

When present in the step definition's repository directory, the onExecute.sh shell script will be executed as the step's onExecute block. This should perform the primary function of the step.

The script must return a true value if the step succeeded, or false if it fails.

For example:

checkHealth() {
  local success=true
  local url=$(find_step_configuration_value "healthCheckUrl")
  {
    local statusCode=$(curl --silent --output /dev/stderr --write-out "%{http_code}" "$url")
  } || exitCode=$?
  if test $statusCode -ne 200; then
    export success=false
  fi

  $success
}

execute_command checkHealth

onSuccess.sh

When present in the step definition's repository directory, the onSuccess.sh shell script will be executed as part of the step's onSuccess block, in advance of user commands.

This script will be executed when the onExecute script returns true.

For example:

sendSuccessNotification() {
  local notifyOnSuccess=$(find_step_configuration_value "notifyOnSuccess")
  if [ -z "$notifyOnSuccess" ]; then
    notifyOnSuccess=false
  fi
  if [ "$notifyOnSuccess" == "true" ]; then
    echo "Health check succeeded"
  fi
}

execute_command sendSuccessNotification

onFailure.sh

When present in the step definition's repository directory, the onSuccess.sh shell script will be executed as part of the step's onFailure block, in advance of user commands.

This script will be executed when the onExecute script returns false.

For example:

sendFailNotification() {
  local notifyOnFailure=$(find_step_configuration_value "notifyOnFailure")
  if [ -z "$notifyOnFailure" ]; then
    notifyOnFailure=false
  fi
  if [ "$notifyOnFailure" == "true" ]; then
    echo "Health check failed"
  fi
}

execute_command sendFailNotification

onComplete.sh

When present in the step definition's repository directory, the onComplete.sh shell script will be executed as part of the step's onComplete block, in advance of user commands.

For example:

echo "All done!"