Skip to main content
System StatusContact Support
VersionOne Community

Continuum Flow Actions

Overview 

Instructions on how to define Actions that display appear in a number of places in the application, capture user input, and execute a number of different types of functions.

Actions are user-defined hooks or initiators of ad-hoc automation. For example, while Projects typically represent a source code repository, they are still by their definition a central access point for all sorts of activity related to their purpose. Defining actions on a Project provides a way for users to initiate automation on-demand, allowing much more flexibility to be built in to an otherwise rigid and formal delivery pipeline process.

Actions can be defined to appear on Products, Projects and Pipeline Instances.

Configuring Actions

Depending on where they are meant to live, Actions can be configured on appropriate Manage page.

For this example, we will discuss in the context of putting an Action on a Project. The process is the same when placing Actions on a Product, Pipeline Definition or Package Revisions.

Select Manage Projects from the right menu, and the Project Management page will appear. From the list on the left, select a specific Project.

From the tabs on the right, select the Actions tab.

Action Definition

At this time, the list of Project Actions is defined in a single JSON formatted document. The required and supported properties are:

  • name - (required) the name of the Action, will appear as the title in the UI

  • type - (required) five Action types are supported:

    • initiate_pipeline - kick off a pipeline

    • retry_instance - retry a failed instance (only available on a Pipeline Definition)

    • task - execute an automate Task

    • api - make a call to the Continuum REST API

    • plugin - invoke a function in a delivered or third-party plugin

  • icon - (optional) an icon selected from the icon library

  • args - (optional) any arguments to pass to the target of the Action. Will have a different meaning depending on the Action type.

  • parameters - (optional) definition of parameters to prompt the user to complete

Action Types

Depending on which Action type is selected, there are slight variations in behavior.

'task' type

The task type is the most common type of Action. By exposing a Task in the context of a Project, Product or completed Instance, complex and robust automation capabilities can be provided at the click of a button.

The task type allows additional properties:

  • task - (required) The Task Name to be executed

  • version - (optional) The Task Version

  • options - (optional, advanced) Additional 'options' for the Task

Here is a sample task type Action definition:

[{
    "icon": "12_48x48.png",
    "name": "Run the 'hello world' Task",
    "task": "hello world",
    "type": "task"
}]

'initiate_pipeline' type

The initiate_pipeline type is a very specific type of Action provided for convenience.

The initiate_pipeline type requires specific arguments:

  • project - (required) Project Name or ID in which to initiate

  • definition - (required) Pipeline Definition Name or ID to initiate

  • group - (required) The Pipeline Group

  • details - (optional) If provided, will be the initial Workspace for the Instance

Here is a sample initiate_pipeline type Action definition:

[{
    "icon": "12_48x48.png",
    "name": "Initiate the 'Package' Pipeline",
    "type": "initiate_pipeline",
    "definition": "Package",
    "project": "test",
    "group": "__GROUP",
    "details": {
        "name": "Buffy the Vampire Slayer"
    }
}]

Notice the __GROUP value in the definition? That's a constant and will be replaced with the relevant value from the Pipeline Instance. See here for a list of valid constants.

'retry_instance' type

The retry_instance type is a very specific type of Action to enable the ability to 'retry' an Instance that ended in failure status due to a glitch, or perhaps was canceled and needs to be tried again.

The retry_instance type requires a single argument:

  • instance - (required) Name or ID of the Instance to be retried.

Here is a sample retry_instance type Action definition:

[{
    "icon": "12_48x48.png",
    "name": "Retry",
    "type": "retry_instance",
    "instance": "[$ pi_id $]"
}]

Notice the 'instance' in this definition is a [$ variable $]? This Action is only useful when defined on a Pipeline and appears on an Instance Detail page. The variable is necessary so it will know how to restart itself. (Every Instance has it's identifier in the Workspace document.)

'api' type

Calling the Continuum API from an Action isn't a very common use case, however since the Continuum API has an advanced 'command and control' capability for the entire Continuum application, it's useful in many cases.

The api type requires additional properties:

  • method - (required) The API endpoint, or 'method', to access

  • verb - (optional, advanced) An advanced case for forcing the request to use GET or POST. Omit in almost all cases.

Here is a sample api type Action definition:

[{
    "icon": "30_48x48.png",
    "name": "Hit the API",
    "method": "list_tasks",
    "type": "api"
}]

Yes, that's a pretty useless example, but you get the idea. Keep reading...

'plugin' type

Calling a Plugin function from an Action allows access to any vendor-specific capabilities they may have been built into the Plugins. Plugins can contain functions for purposes other than inclusion in a Pipeline Stage, so specific plugin functions can be very useful for Actions, for display of data in a Canvas, etc.

The plugin type requires additional properties:

  • plugin - (required) The name of both the Plugin and the included module, dot separated

  • method - (required) The 'method' or 'function' in the Plugin to execute

See documentation for a specific plugin to determine specific details of which functions are available and/or useful for calling from an Action.

Here is a sample plugin type Action definition:

[{
    "icon": "42_48x48.png",
    "name": "Initate The Next Pipeline",
    "plugin": "flow.pipeline",
    "method": "manual_initiate",
    "type": "plugin",
    "args": {
        "@parameters": "details",
        "pipeline": "foo",
        "project": "test",
        "group": "manual"
    }
}]

Notice how this example has 'args'. These args are required by the 'manual_initiate' Flow Plugin function.

Action Parameters

Where args are a standard key : value type object which will be passed to the target, Parameters are more formal.

Parameters define:

  • the 'name' of a parameter to capture
  • default 'values' to prompt the user
  • presentation rules such as required flag, type (value, list, dropdown), and so forth.

Here is an example parameters section that defines all three parameter types: value, list and dropdown. This example can be pasted into the Parameters "text" box.

In a parameters definition, if presentation of default values is desired, the 'values' property is always a list, even if it's only one value.

[
    {
        "name": "i_am_required",
        "required": "true",
        "values": [
            "bar"
        ]
    },
    {
        "name": "pick_one",
        "present_as": "dropdown",
        "values": [
            "true",
            "false"
        ]
    },
    {
        "name": "a_list",
        "present_as": "list",
        "values": [
            "one",
            "two"
        ]
    }
]

Optional values include:

  • required - (true/false) If defined and ‘true’, user cannot submit unless this parameter is provided.

  • encrypt - (true/false) If defined and ‘true’, the value entered by the user will be encrypted while in any transmitted or stored forms.

  • present_as - The type of prompt to present. ‘list’, ‘dropdown’, ‘text’.  If omitted, or any other value is entered, it will default to ‘text’.

  • prompt - (true/false) is this visible to the user? Rarely used, effectively disables this parameter without deleting it from the definition..

  • description - A description of the Parameter that is displayed when the end user hovers the mouse over the (i) icon.

  • constraint - A regular expression limiting the users entry of a value to a set pattern.

  • constraint_msg - A message to display if the constraint is not met.

  • minvalue - A minimum value for the data entry.  Only applicable if the data is numeric, so should be used with an appropriate constraint.

  • maxvalue - A maximum value for the data entry.  Only applicable if the data is numeric, so should be used with an appropriate constraint.

  • minlength - A minimum length for the data entry.

  • maxlength - A maximum length for the data entry.

  • selected_value - Only relevant when present_as is ‘dropdown’.  Identifies the value to be selected by default.

Action Parameters

Regarding 'parameters' and 'args'...

When 'parameters' are provided, they act a little differently based on the Action type.

  • task - the parameters are sent directly to the Task. The task type does not support the args property.

  • plugin - parameters are merged with 'args' into a single document and provided to the plugin as it's 'args'

  • api - parameters are merged with 'args' into a single document and provided to the plugin as it's 'args'

In some advanced cases, it's required to actually send the 'parameters' as a subkey of the args. Case in point - sending 'details' to the 'manual_initiate' Flow Plugin call. When parameters are meant to be included as a subkey, the following special syntax is used:

"@parameter": "target_key"

When the @parameter key is encountered, the Action will take all the parameters and place them in the args document under the key name specified. For example, to pass parameters as 'details' to 'manual_initiate'.

"args": {
    "@parameters": "details",
    "pipeline": "foo",
    "project": "test",
    "group": "manual!"
}

would result in the following being sent to the plugin:

"args": {
    "details": {
        "param1": "value1",
        "param2": "value2"
    },
    "pipeline": "foo",
    "project": "test",
    "group": "manual!"
}

Pipeline Actions

When Actions are defined on a Pipeline Definition, a few additional properties apply. A Pipeline Definition applies to both a single Instance of that Pipeline, as well as summarized into a Group.

Actions are valid in both context, and often exclusive of one another. For example, some Actions may intuitively need to appear on the Instance Detail page, while others only should appear on the Group Detail page. However, all these actions are actually defined on the Pipeline Definition.

This segregation is accomplished via the on property of the Action. For example, here are two Actions - one will appear on any Instances of this Pipeline, while the other will only appear on the Group Detail page.

[
    {
        "icon": "31_48x48.png",
        "name": "Group Only",
        "on": "group",
        "task": "sample task",
        "type": "task"
    },
    {
        "icon": "18_48x48.png",
        "name": "Instance Only",
        "on": "instance",
        "task": "sample task",
        "type": "task"
    }
]

Instance Actions

Finally, Actions that appear on an Instance may have one additional property. By specifying the show property, the availability of the Action is determined by the Instance status. Here are three Actions, one will only appear on failed instances, the other will appear on successful instances, and the third is always available.

[
    {
        "icon": "01_48x48.png",
        "name": "Success Only",
        "show": "success",
        "task": "sample task",
        "type": "task"
    },
    {
        "icon": "02_48x48.png",
        "name": "Failure Only",
        "show": "failure",
        "task": "sample task",
        "type": "task"
    },
    {
        "icon": "03_48x48.png",
        "name": "Always Available",
        "show": "always",
        "task": "sample task",
        "type": "task"
    },
    {
        "icon": "04_48x48.png",
        "name": "ALSO Always Available",
        "task": "sample task",
        "type": "task"
    }
]
  • Was this article helpful?