Skip to main content
Version: 11 - TBD

Wrapper bundle

Take a look at the wrappers documentation to learn how to write your own wrappers.

Wrappers encapsulate executable resources. Executing a wrapped resource will instead run the wrapper, which can coordinate the execution of the wrapped resource.

Release Notes:

2024-12-12 fix notify a list of Cloudomation users per name

2024-11-18 remove deprecations

2024-10-22 update input schemas

2024-08-21 BREAKING CHANGE remove deprecated timeout_sec from retry wrapper

2024-08-13 adust input schemas

2024-06-11 add configuration for handling missing resources

2024-04-19 allow configuring the project of child executions

2024-04-18 allow the notify and interactive wrappers to send emails to non Cloudomation users

2024-03-18 add run_on_state_change_flow_additional_inputs parameter for notify wrapper

2024-03-11 make status_setting_name configurable for notify wrapper

2024-02-09 remove deprecated is_archived flag

2024-02-06 extend notify wrapper with state change functionality

2023-12-04 change naming to Cloudomation Engine

2023-11-13 fix validate wrapper error when used without inputs

2023-08-29 fix linter errors

2023-08-03 consider only activity of notify_users in interactive wrapper

2023-07-04 fix "NoneType" is not a mapping

2023-06-15 add label to check wrapper inputs

2023-05-11.2 initial release

Download​

Download the bundle using the Bundle Manager.

Included resources​

cache​

Execution wrapper for caching an output_value

Returns the output_value of a previous execution.

usage:

this.using(
    'cache',
    max_age_minutes=60,
).connect(
    'my-connector'
)
# returns the output_value of the last successful execution of
# "my-connector". if there is no successful execution of
# within the last 60 minutes, it will create a new connection
# and return its output_value

Input schema​

KeyTypeDescriptionDefault
child_execution_locationenum

Any of

  • Location of wrapper execution
KeyTypeDescriptionDefault
mode_namestring

The child runs where the wrapper execution runs.

Constant value:

wrapper_execution
  • Location of wrapped resource
KeyTypeDescriptionDefault
mode_namestring

The child runs where the child resource is located.

Constant value:

wrapped_resource
  • Location of wrapper resource
KeyTypeDescriptionDefault
mode_namestring

The child runs where the wrapper resource is located.

Constant value:

wrapper_resource
  • Specific project
KeyTypeDescriptionDefault
mode_namestring

Where the child execution should run.

Constant value:

specific_project
project_namestring

The project where the child should run.

Default project
max_age_minutesinteger

How old a child execution can be before considered stale.

1440

check​

Execution wrapper for output_value checks

waits for a child execution and passes the outputs to a script to check for correctness

usage with a checker flow:

this.using(
    'check',
    checker_flow='my-checker-flow',
    inputs={
        'additional': 'inputs',
        'to': 'checker',
    },
).flow(
    'child-execution'
)

usage with a checker script:

this.using(
    'check',
    checker_script=(
        '''
        import flow_api

        def handler(system: flow_api.System, this: flow_api.Execution):
            # TODO add your logic to check this.get('input_value')['data']
            # additional inputs are available in this.get('input_value')
            return this.success('check succeeded')
        '''
    ),
    inputs={
        'additional': 'inputs',
        'to': 'checker',
    },
).flow(
    'child-execution'
)

Input schema​

KeyTypeDescriptionDefault
checker_flowstring

A flow which is called with the output_value of the child to determine if the child was successful. Either checker_flow or checker_script must be given.

checker_scriptstring

A script which is called with the output_value of the child to determine if the child was successful. Either checker_flow or checker_script must be given.

child_execution_locationenum

Any of

  • Location of wrapper execution
KeyTypeDescriptionDefault
mode_namestring

The child runs where the wrapper execution runs.

Constant value:

wrapper_execution
  • Location of wrapped resource
KeyTypeDescriptionDefault
mode_namestring

The child runs where the child resource is located.

Constant value:

wrapped_resource
  • Location of wrapper resource
KeyTypeDescriptionDefault
mode_namestring

The child runs where the wrapper resource is located.

Constant value:

wrapper_resource
  • Specific project
KeyTypeDescriptionDefault
mode_namestring

Where the child execution should run.

Constant value:

specific_project
project_namestring

The project where the child should run.

Default project
inputsobject

Any additional inputs being passed to the child

interactive​

Execution wrapper for interactive error handling

observes a child execution and pauses when an error occurs

usage:

this.using(
    'interactive',
    interactive_limit_minutes: int = 30,
    delete_retries: bool = True,
    notify_users: list[str] = None,
    context: object = None,
    child_message_is_markdown: bool = True,
    subject: str = '{{child_name}} failed{{#is_retry}} {{fail_count}} times{{/is_retry}}',
    body: str = '''Execution [{{child_name}}]({{self_url}}/execution/{{child_id}}) ended with **{{child_status}}**

{{#parent_name}}
The parent process **{{parent_name}}** is blocked and waiting for confirmation on how to continue.
{{/parent_name}}

{{#is_email}}
Please choose how to proceed by following this link: [{{subject}}]({{self_url}}/execution/{{this_id}})
{{/is_email}}

{{#context}}
### Context

{{context}}
{{/context}}

{{#child_message}}
### Status message

{{child_message}}
{{/child_message}}
    ''',
).flow(
    'child-execution'
)

Input schema​

KeyTypeDescriptionDefault
bodystring

A template for the body of notifications sent to users.

Execution [{{child_name}}]({{self_url}}/execution/{{child_id}})
ended with **{{child_status}}**

{{#parent_name}}

The parent process **{{parent_name}}** is blocked and waiting for confirmation
on how to continue.

{{/parent_name}}

{{#is_email}}

Please choose how to proceed by following this link: [{{subject}}]({{self_url}}/execution/{{this_id}})

{{/is_email}}

{{#context}}

### Context

{{context}}

{{/context}}

{{#child_message}}

### Status message

{{child_message}}

{{/child_message}}

child_execution_locationenum

Any of

  • Location of wrapper execution
KeyTypeDescriptionDefault
mode_namestring

The child runs where the wrapper execution runs.

Constant value:

wrapper_execution
  • Location of wrapped resource
KeyTypeDescriptionDefault
mode_namestring

The child runs where the child resource is located.

Constant value:

wrapped_resource
  • Location of wrapper resource
KeyTypeDescriptionDefault
mode_namestring

The child runs where the wrapper resource is located.

Constant value:

wrapper_resource
  • Specific project
KeyTypeDescriptionDefault
mode_namestring

Where the child execution should run.

Constant value:

specific_project
project_namestring

The project where the child should run.

Default project
child_message_is_markdownboolean

If set, the status message of ended child executions is interpreted as markdown.

True
contextobject

Any contextual JSON data which is attached to notifications.

delete_retriesboolean

If set, previous child executions are deleted when a new child execution is started.

True
fail_on_missing_referenceboolean

Whether the wrapper execution should fail if a resource referenced in the inputs is missing.

interactive_limit_minutesinteger

Cloudomation Engine users which have not been active within that time are considered inactive.

30
notify_usersenum

Any of

  • Active users
KeyTypeDescriptionDefault
modestring

Notify all users which were active within interactive_limit_minutes.

Constant value:

active_users
  • A list of email addresses
KeyTypeDescriptionDefault
email_addressesarray

A list of email addresses and the SMTP connector to be used.

{'cloudomation_users': [], 'mode': 'email_addresses'}
modestring

A list of email addresses and the SMTP connector to be used.

Constant value:

email_addresses
{'cloudomation_users': [], 'mode': 'email_addresses'}
smtp_connectorstring

A list of email addresses and the SMTP connector to be used.

{'cloudomation_users': [], 'mode': 'email_addresses'}
  • A list of Cloudomation users
KeyTypeDescriptionDefault
cloudomation_usersarray

Notify a list of Cloudomation users.

{'cloudomation_users': [], 'mode': 'cloudomation_users'}
modestring

Notify a list of Cloudomation users.

Constant value:

cloudomation_users
{'cloudomation_users': [], 'mode': 'cloudomation_users'}
  • Single user

DEPRECATED - use "A list of Cloudomation users" instead Notify a single user.

  • Multiple users

DEPRECATED - use "A list of Cloudomation users" instead Notify a list of users.

subjectstring

A template for the subject line of notifications sent to users.

{{child_name}} failed{{#is_retry}} {{fail_count}} times{{/is_retry}}

mock​

Execution wrapper for mocking output_value

Returns the output_value of a previous execution.

modes

  • ENDED_SUCCESS (default)

    looks for the last successful execution of the child and returns its output_value

  • ENDED_ERROR

    looks for the last failed execution of the child and returns its output_value

  • LAST

    looks for the last execution of the child and returns its output_value

  • STATIC

    returns the output_value which is configured in the output_value parameter of the wrapper

  • FIXED

    returns the output_value of the execution which is specified using the execution_id parameter of the wrapper

usage:

this.using(
    'mock',
).connect(
    'my-connector'
)
# returns the output_value of the last successful execution of "my-connector"

Input schema​

KeyTypeDescriptionDefault
child_execution_locationenum

Any of

  • Location of wrapper execution
KeyTypeDescriptionDefault
mode_namestring

The child runs where the wrapper execution runs.

Constant value:

wrapper_execution
  • Location of wrapped resource
KeyTypeDescriptionDefault
mode_namestring

The child runs where the child resource is located.

Constant value:

wrapped_resource
  • Location of wrapper resource
KeyTypeDescriptionDefault
mode_namestring

The child runs where the wrapper resource is located.

Constant value:

wrapper_resource
  • Specific project
KeyTypeDescriptionDefault
mode_namestring

Where the child execution should run.

Constant value:

specific_project
project_namestring

The project where the child should run.

Default project
ignore_in_productive_modeboolean

When set and run in productive mode, the child will not be mocked but started normally.

True
modeenum

Any of

  • ENDED_SUCCESS
KeyTypeDescriptionDefault
mode_namestring

Looks for the last successful execution of the child and returns its output_value.

Constant value:

ENDED_SUCCESS
  • ENDED_ERROR
KeyTypeDescriptionDefault
mode_namestring

Looks for the last failed execution of the child and returns its output_value.

Constant value:

ENDED_ERROR
  • LAST
KeyTypeDescriptionDefault
mode_namestring

Looks for the last execution of the child and returns its output_value.

Constant value:

LAST
  • STATIC
KeyTypeDescriptionDefault
mode_namestring

Returns the output_value which is configured.

Constant value:

STATIC
output_valueobject

JSON

  • FIXED
KeyTypeDescriptionDefault
execution_idstring

Returns the output_value of the execution which is configured.

mode_namestring

Returns the output_value of the execution which is configured.

Constant value:

FIXED

notify​

Execution wrapper for notifications

observes a child execution and generates notification on end

usage:

this.using(
    'notify',
    notify_on_success: bool = False,
    notify_on_error: bool = True,
    notify_on_state_change: bool = False,
    child_message_is_markdown: bool = True,
    to: list[str] = None,
    context: object = None,
    subject: str = '{{child_name}} {{child_status}}',
    body: str = '''Execution [{{child_name}}]({{self_url}}/execution/{{child_id}}) ended with **{{child_status}}**

{{#context}}
### Context

{{context}}
{{/context}}

{{#child_message}}
### Status message

{{child_message}}
{{/child_message}}
    ''',
).flow(
    'child-execution'
)

Input schema​

KeyTypeDescriptionDefault
bodystring

A template for the body of notifications sent to users.

Execution [{{child_name}}]({{self_url}}/execution/{{child_id}})
ended with **{{child_status}}**
{{#context}}

### Context

{{context}}

{{/context}}

{{#child_message}}

### Status message

{{child_message}}

{{/child_message}}



{{#notify_on_state_change}}

### State changes:

{{#state_change_consider_status}}
Status change: **{{status_changed}}**
{{/state_change_consider_status}}

{{#state_change_consider_message}}
Message change: **{{message_changed}}**
{{/state_change_consider_message}}

{{#state_change_consider_output_value}}

{{^state_change_consider_output_value_key}}
Output value change: **{{output_value_changed}}**
{{/state_change_consider_output_value_key}}

{{#state_change_consider_output_value_key}}

{{^output_value_key_missing}}
Output value key '**{{state_change_consider_output_value_key}}**' change: **{{output_value_key_changed}}**
{{/output_value_key_missing}}

{{#output_value_key_missing}}
Output value key '**{{state_change_consider_output_value_key}}**' change: Output value key '**{{state_change_consider_output_value_key}}**' not found.
{{/output_value_key_missing}}

{{/state_change_consider_output_value_key}}
{{/state_change_consider_output_value}}

______________________________

{{#state_change_consider_status}}
**Current status:**
{{child_status}}

**Last status:**
{{last_status}}
______________________________
{{/state_change_consider_status}}

{{#state_change_consider_message}}
**Current message:**
      
{{child_message}}

**Last message:**

{{last_message}}
______________________________
{{/state_change_consider_message}}

{{#state_change_consider_output_value}}
**Current output value:**
      
{{child_output_value}}

**Last output value:**

{{last_output_value}}
______________________________
{{/state_change_consider_output_value}}

*Last successful execution*

**Timestamp:**
{{last_success_timestamp}}

**Id:**
{{last_success_execution_id}}
______________________________
*Last failed execution*

**Timestamp:**
{{last_failure_timestamp}}

**Id:**
{{last_failure_execution_id}}
______________________________
**Successful executions:**
{{succeded_execution_count}}

**Failed executions:**
{{failed_execution_count}}
______________________________
{{/notify_on_state_change}}

child_execution_locationenum

Any of

  • Location of wrapper execution
KeyTypeDescriptionDefault
mode_namestring

The child runs where the wrapper execution runs.

Constant value:

wrapper_execution
  • Location of wrapped resource
KeyTypeDescriptionDefault
mode_namestring

The child runs where the child resource is located.

Constant value:

wrapped_resource
  • Location of wrapper resource
KeyTypeDescriptionDefault
mode_namestring

The child runs where the wrapper resource is located.

Constant value:

wrapper_resource
  • Specific project
KeyTypeDescriptionDefault
mode_namestring

Where the child execution should run.

Constant value:

specific_project
project_namestring

The project where the child should run.

Default project
child_message_is_markdownboolean

If set, the status message of ended child executions is interpreted as markdown.

True
fail_on_missing_referenceboolean

Whether the wrapper execution should fail if a resource referenced in the inputs is missing.

notify_on_errorboolean

If a notification should be generated when the child ends with ENDED_ERROR or ENDED_CANCELLED.

True
notify_on_state_changeboolean

If a notification should be generated when a specified attribute (e.g. status) of the current child execution is different to the previous execution of the child.

notify_on_successboolean

If a notification should be generated when the child ends with ENDED_SUCCESS.

renotify_state_change_to_error_minutesinteger

How long the wrapper should wait, before sending another state change notification if an error persists. Set to 0 to disable.

run_on_state_change_flow_additional_inputsobject
KeyTypeDescriptionDefault
run_on_state_change_flow_namestring

The name of a flow that is started in case of a state change. The output value of the child is passed to the flow as input value

state_change_consider_messageboolean

If a change in the child message indicates a state change.

state_change_consider_output_valueboolean

If a change in the child output value indicates a state change.

state_change_consider_output_value_keystring

If a change in a specific key in the child output value indicates a state change. Leave it as an empty string, to consider the whole output value.

state_change_consider_statusboolean

If a change in the child status indicates a state change.

True
status_setting_namestring

The name of the setting where the current and last status is stored. Defaults to "child_name-wrapper-notify-status-setting".

subjectstring

A template for the subject line of notifications sent to users.

{{child_name}} {{child_status}}
toenum

Any of

  • A list of Cloudomation users
KeyTypeDescriptionDefault
cloudomation_usersarray

Notify a list of Cloudomation users.

{'cloudomation_users': [], 'mode': 'cloudomation_users'}
modestring

Notify a list of Cloudomation users.

Constant value:

cloudomation_users
{'cloudomation_users': [], 'mode': 'cloudomation_users'}
  • A list of email addresses
KeyTypeDescriptionDefault
email_addressesarray

A list of email addresses and the SMTP connector to be used.

{'cloudomation_users': [], 'mode': 'email_addresses'}
modestring

A list of email addresses and the SMTP connector to be used.

Constant value:

email_addresses
{'cloudomation_users': [], 'mode': 'email_addresses'}
smtp_connectorstring

A list of email addresses and the SMTP connector to be used.

{'cloudomation_users': [], 'mode': 'email_addresses'}
  • Single user

DEPRECATED - use "A list of Cloudomation users" instead Notify a single user.

  • Multiple users

DEPRECATED - use "A list of Cloudomation users" instead Notify a list of users

retry​

Execution wrapper for retries

observes a child execution and restarts it if an error occurs

usage:

this.using(
    'retry',
    max_tries: int = 0,
    delay_sec: int = 10,
    delete_retries: bool = True,
).flow(
    'child-execution'
)

todo:

  • back-off

Input schema​

KeyTypeDescriptionDefault
child_execution_locationenum

Any of

  • Location of wrapper execution
KeyTypeDescriptionDefault
mode_namestring

The child runs where the wrapper execution runs.

Constant value:

wrapper_execution
  • Location of wrapped resource
KeyTypeDescriptionDefault
mode_namestring

The child runs where the child resource is located.

Constant value:

wrapped_resource
  • Location of wrapper resource
KeyTypeDescriptionDefault
mode_namestring

The child runs where the wrapper resource is located.

Constant value:

wrapper_resource
  • Specific project
KeyTypeDescriptionDefault
mode_namestring

Where the child execution should run.

Constant value:

specific_project
project_namestring

The project where the child should run.

Default project
delay_secinteger

The number of seconds to wait in between retries.

10
delete_retriesboolean

If set, previous child executions are deleted when a new child execution is started.

True
max_triesinteger

The number of times to try starting the child before failing.

3

rollback​

Execution wrapper for rollbacks

starts a rollback flow in case of exceptions

usage:

this.using(
    'rollback',
    rollback_flow_name: str = 'my_rollback_flow',
).flow(
    'child-execution'
)

Input schema​

KeyTypeDescriptionDefault
child_execution_locationenum

Any of

  • Location of wrapper execution
KeyTypeDescriptionDefault
mode_namestring

The child runs where the wrapper execution runs.

Constant value:

wrapper_execution
  • Location of wrapped resource
KeyTypeDescriptionDefault
mode_namestring

The child runs where the child resource is located.

Constant value:

wrapped_resource
  • Location of wrapper resource
KeyTypeDescriptionDefault
mode_namestring

The child runs where the wrapper resource is located.

Constant value:

wrapper_resource
  • Specific project
KeyTypeDescriptionDefault
mode_namestring

Where the child execution should run.

Constant value:

specific_project
project_namestring

The project where the child should run.

Default project
rollback_flow_namestring

The name of the flow that should be executed in case of a DependencyFailedError.

timeout​

Execution wrapper for timeouts

Starts a child execution and waits for it to end within a timeout. If the timeout is exceeded, the child execution and all descendants are cancelled.

usage:

this.using(
    'timeout',
    seconds=30,
).flow(
    'child-execution'
)

Input schema​

KeyTypeDescriptionDefault
child_execution_locationenum

Any of

  • Location of wrapper execution
KeyTypeDescriptionDefault
mode_namestring

The child runs where the wrapper execution runs.

Constant value:

wrapper_execution
  • Location of wrapped resource
KeyTypeDescriptionDefault
mode_namestring

The child runs where the child resource is located.

Constant value:

wrapped_resource
  • Location of wrapper resource
KeyTypeDescriptionDefault
mode_namestring

The child runs where the wrapper resource is located.

Constant value:

wrapper_resource
  • Specific project
KeyTypeDescriptionDefault
mode_namestring

Where the child execution should run.

Constant value:

specific_project
project_namestring

The project where the child should run.

Default project
secondsinteger

The number of seconds before a timeout occurs.

60

validate​

Execution wrapper for validating input/output schema.

usage:

this.using(
    'validate',
    schema_name: str = 'my_schema_name',
    mode: str = 'complain',
    point_of_validation: str = 'input',
).flow(
    'child-execution'
)

Input schema​

KeyTypeDescriptionDefault
child_execution_locationenum

Any of

  • Location of wrapper execution
KeyTypeDescriptionDefault
mode_namestring

The child runs where the wrapper execution runs.

Constant value:

wrapper_execution
  • Location of wrapped resource
KeyTypeDescriptionDefault
mode_namestring

The child runs where the child resource is located.

Constant value:

wrapped_resource
  • Location of wrapper resource
KeyTypeDescriptionDefault
mode_namestring

The child runs where the wrapper resource is located.

Constant value:

wrapper_resource
  • Specific project
KeyTypeDescriptionDefault
mode_namestring

Where the child execution should run.

Constant value:

specific_project
project_namestring

The project where the child should run.

Default project
modeenum

Any of

  • Complain

Validates the input_value or output_value of the child against a json schema and raises a SchemaValidationError on failed validation.

Constant value:

complain
  • Learn

Creates a json schema from the input_value or output_value of the child. If the schema exists it gets updated so that it accommodates its old schema and the newly learned schema. Otherwise the schema is created with the newly learned schema.

Constant value:

learn
point_of_validationenum

Any of

  • Input value

Constant value:

input
  • Output value

Constant value:

output
schema_namestring

The name of the schema resource that should be used for the wrapper.

wrapper-validate-input-schema​