Plugins

Plugins extend the functionality of Cloudomation Engine.

Use Cases

Use a plugin to

• extend the Cloudomaton User Interface with action buttons which create executions when clicked.

Concept

Plugin actions are restricted to a resource type. For each plugin action an action button will appear when viewing resources of the specified type. Clicking on a plugin action button will start an execution of the referenced flow and pass the ID of the resource in the input_value.

tip

We recomment to distribute plugins as part of a design self-contained project. The project should contain all resources (flows, settings, actions, etc.) which are needed for its purpose. If a plugin has dependencies, it should always check if they exist and provide meaningful errors when they are missing.

See Projects for more information about projects.

Configuration

Please see the table below for the different plugin fields and their meanings:

Field	Description
Enabled	If unset, Engine will not create action buttons of the plugin actions.

Please see the table below for the different plugin_action fields and their meanings:

Field	Description
Parent action	When set, this action will be placed in a dropdown menu below the parent action.
Resource type	an Engine resource type where the action should create a button.
Color	The color of the button. Currently not used.
Icon	An icon to display on the button.
Enabled	If unset, the action does not create a button.
Flow	The flow which should be started when the button is clicked.
Type	One of LIST or RECORD. See Action types.
Record filter	An additional filter to limit the rows for which the action button is created. See Record filter.
Execution location	If set to Triggering resource the execution will get the project_id of the resource where the plugin action is triggered. If set to Plugin it will get the project_id of the plugin that the plugin action is part of. If the respective resource is in a bundle, the execution will run in the Default project.
Navigate to execution	Controls what happens after the action creates its execution. When enabled (the default), clicking the action opens the created execution. When disabled, the Engine stays on the current screen and shows a success notification with a link to the created execution.

Action Types

• LIST

  The action button is also shown in list views. When clicked the flow is started once and the execution gets all record IDs passed in the input_value.

• RECORD

  The action button is shown in the record header. When clicked the flow is started once for each record and each execution gets one record ID passed in the input_value.

Record filter

A record filter limits the records for which an action button appears. It is evaluated against the record being viewed, and the button is shown only when the record matches.

Filters use the same grammar as list filters. A filter is either a group — {"and": [...]} or {"or": [...]}, which may be nested — or a leaf condition {"field": ..., "op": ..., "value": ...}.

Fields address the record being viewed:

• a top-level column, for example connector_type on a connector or object_template_id on a custom object;
• a dot path into a custom object's attributes, written value.<attribute> — for example value.status reads the status attribute of the custom object being viewed. This is what lets an action target custom objects in a specific state.

Operators (op):

Operator	Matches when the field…
eq	equals value (the default when a plain key: value pair is given)
neq	does not equal value
like / notlike	matches / does not match a case-insensitive SQL pattern (% matches any run of characters, _ matches a single character)
lt / lte / gt / gte	is less than / less-or-equal / greater than / greater-or-equal to value
set / unset	is present (non-null) / absent (null); no value is needed
in / notin	is / is not one of value, given as a list

Placeholders are substituted into a value per viewer when the button is rendered:

Placeholder	Resolves to
@me	the identity of the current user
@workspace	the current workspace id
@now	the current timestamp
@today	today's date

@me shows an action only when the record concerns whoever is looking at it — for example {"field": "value.assignee", "op": "eq", "value": "@me"}.

example (custom object in a specific state)

Show an "Approve" button only on custom objects of one object template that are in the proposed state:

{
  "and": [
    {"field": "object_template_id", "op": "eq", "value": "<object_template uuid>"},
    {"field": "value.status", "op": "eq", "value": "proposed"}
  ]
}

The flow behind the action receives the custom object's record id in inputs['id'].

example (connector type)

Show a "Test Connection" button only on SSH connectors:

{"and": [{"field": "connector_type", "op": "eq", "value": "SSH"}]}

A shorthand form — a flat set of key: value pairs matched for equality against the record's top-level columns, with multiple keys OR-combined — is also accepted for simple cases: {"connector_type": "SSH"}.

note

A record filter decides button visibility at render time, so related-record (exists) conditions are not applied: an action whose filter contains an exists node is hidden. Use plain field conditions for button visibility.

Action Handler Flow

The flow which is registered in a plugin action will be used to create an execution when the action button is pressed.

example

Flow to handle a "LIST" plugin action

import flow_api

def handler(system: flow_api.System, this: flow_api.Execution, inputs: dict):
    # Type "LIST" actions pass "ids"
    ids = inputs['ids']

    # we iterate over the list of IDs
    for id_ in ids:
        # read the type of the resource and the name
        this.log(system.resource(id, by='id').get('resource_type', 'name'))

    return this.success('all done')

example

Flow to handle a "RECORD" plugin action

import flow_api

def handler(system: flow_api.System, this: flow_api.Execution, inputs: dict):
    inputs = this.get('input_value')

    # Type "RECORD" actions pass "id"
    id_ = inputs['id']

    this.log(f'I was called with the ID {id_}')

    return this.success('all done')

Example

We provide an example plugin as part of the Connection Analysis & Test bundle.

Learn More

Connection Resource

Git Integration

Messages and Forms

Projects

Connection Analysis & Test bundle