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:

RELEASE-12

2025-04-03 retry wrapper: properly handle "ignore dependency"

2025-01-28 add on-error wrapper

RELEASE-11

RELEASE-10

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

2024-11-18 remove deprecations

2024-10-29 update status message for notify and rollback

2024-10-28.2 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

Key	Type	Description	Default
child_execution_location	enum	Any of Location of wrapper execution Key Type Description Default mode_name string The child runs where the wrapper execution runs. Constant value: wrapper_execution Location of wrapped resource Key Type Description Default mode_name string The child runs where the child resource is located. Constant value: wrapped_resource Location of wrapper resource Key Type Description Default mode_name string The child runs where the wrapper resource is located. Constant value: wrapper_resource Specific project Key Type Description Default mode_name string Where the child execution should run. Constant value: specific_project project_name string The project where the child should run. Default project Specific bundle Key Type Description Default bundle_name string The bundle where the child should run. mode_name string Where the child execution should run. Constant value: specific_bundle
max_age_minutes	integer	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

Key	Type	Description	Default
checker_flow	string	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_script	string	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_location	enum	Any of Location of wrapper execution Key Type Description Default mode_name string The child runs where the wrapper execution runs. Constant value: wrapper_execution Location of wrapped resource Key Type Description Default mode_name string The child runs where the child resource is located. Constant value: wrapped_resource Location of wrapper resource Key Type Description Default mode_name string The child runs where the wrapper resource is located. Constant value: wrapper_resource Specific project Key Type Description Default mode_name string Where the child execution should run. Constant value: specific_project project_name string The project where the child should run. Default project Specific bundle Key Type Description Default bundle_name string The bundle where the child should run. mode_name string Where the child execution should run. Constant value: specific_bundle
inputs	object	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

Key	Type	Description	Default
body	string	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_location	enum	Any of Location of wrapper execution Key Type Description Default mode_name string The child runs where the wrapper execution runs. Constant value: wrapper_execution Location of wrapped resource Key Type Description Default mode_name string The child runs where the child resource is located. Constant value: wrapped_resource Location of wrapper resource Key Type Description Default mode_name string The child runs where the wrapper resource is located. Constant value: wrapper_resource Specific project Key Type Description Default mode_name string Where the child execution should run. Constant value: specific_project project_name string The project where the child should run. Default project Specific bundle Key Type Description Default bundle_name string The bundle where the child should run. mode_name string Where the child execution should run. Constant value: specific_bundle
child_message_is_markdown	boolean	If set, the status message of ended child executions is interpreted as markdown.	True
context	object	Any contextual JSON data which is attached to notifications.
delete_retries	boolean	If set, previous child executions are deleted when a new child execution is started.	True
fail_on_missing_reference	boolean	Whether the wrapper execution should fail if a resource referenced in the inputs is missing.
interactive_limit_minutes	integer	Cloudomation Engine users which have not been active within that time are considered inactive.	30
notify_users	enum	Any of Active users Key Type Description Default mode string Notify all users which were active within interactive_limit_minutes. Constant value: active_users A list of email addresses Key Type Description Default email_addresses array A list of email addresses and the SMTP connector to be used. {'cloudomation_users': [], 'mode': 'email_addresses'} mode string A list of email addresses and the SMTP connector to be used. Constant value: email_addresses {'cloudomation_users': [], 'mode': 'email_addresses'} smtp_connector string A list of email addresses and the SMTP connector to be used. {'cloudomation_users': [], 'mode': 'email_addresses'} A list of Cloudomation users Key Type Description Default cloudomation_users array Notify a list of Cloudomation users. {'cloudomation_users': [], 'mode': 'cloudomation_users'} mode string 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.
subject	string	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

Key	Type	Description	Default
child_execution_location	enum	Any of Location of wrapper execution Key Type Description Default mode_name string The child runs where the wrapper execution runs. Constant value: wrapper_execution Location of wrapped resource Key Type Description Default mode_name string The child runs where the child resource is located. Constant value: wrapped_resource Location of wrapper resource Key Type Description Default mode_name string The child runs where the wrapper resource is located. Constant value: wrapper_resource Specific project Key Type Description Default mode_name string Where the child execution should run. Constant value: specific_project project_name string The project where the child should run. Default project Specific bundle Key Type Description Default bundle_name string The bundle where the child should run. mode_name string Where the child execution should run. Constant value: specific_bundle
ignore_in_productive_mode	object	When set and run in productive mode, the child will not be mocked but started normally.
mock_in_productive_mode	object	When set and run in productive mode mock will be created
mode	enum	Any of ENDED_SUCCESS Key Type Description Default mode_name string Looks for the last successful execution of the child and returns its output_value. Constant value: ENDED_SUCCESS ENDED_ERROR Key Type Description Default mode_name string Looks for the last failed execution of the child and returns its output_value. Constant value: ENDED_ERROR LAST Key Type Description Default mode_name string Looks for the last execution of the child and returns its output_value. Constant value: LAST STATIC Key Type Description Default mode_name string Returns the output_value which is configured. Constant value: STATIC output_value object JSON FIXED Key Type Description Default execution_id string Returns the output_value of the execution which is configured. mode_name string 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

Key	Type	Description	Default
body	string	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}} ______________________________ **Last state change timestamp:** {{last_state_change_timestamp}} **Time past since last state change:** {{time_past_since_last_state_change}} ______________________________ {{/notify_on_state_change}}
child_execution_location	enum	Any of Location of wrapper execution Key Type Description Default mode_name string The child runs where the wrapper execution runs. Constant value: wrapper_execution Location of wrapped resource Key Type Description Default mode_name string The child runs where the child resource is located. Constant value: wrapped_resource Location of wrapper resource Key Type Description Default mode_name string The child runs where the wrapper resource is located. Constant value: wrapper_resource Specific project Key Type Description Default mode_name string Where the child execution should run. Constant value: specific_project project_name string The project where the child should run. Default project Specific bundle Key Type Description Default bundle_name string The bundle where the child should run. mode_name string Where the child execution should run. Constant value: specific_bundle
child_message_is_markdown	boolean	If set, the status message of ended child executions is interpreted as markdown.	True
fail_on_missing_reference	boolean	Whether the wrapper execution should fail if a resource referenced in the inputs is missing.
notify_on_error	boolean	If a notification should be generated when the child ends with ENDED_ERROR or ENDED_CANCELLED.	True
notify_on_state_change	boolean	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_success	boolean	If a notification should be generated when the child ends with ENDED_SUCCESS.
renotify_state_change_to_error_minutes	integer	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_inputs	object	Key Type Description Default
run_on_state_change_flow_name	string	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_message	boolean	If a change in the child message indicates a state change.
state_change_consider_output_value	boolean	If a change in the child output value indicates a state change.
state_change_consider_output_value_key	string	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_status	boolean	If a change in the child status indicates a state change.	True
status_setting_name	string	The name of the setting where the current and last status is stored. Defaults to "child_name-wrapper-notify-status-setting".
subject	string	A template for the subject line of notifications sent to users.	{{child_name}} {{child_status}} - last state change: {{last_state_change_timestamp}}
to	enum	Any of A list of Cloudomation users Key Type Description Default cloudomation_users array Notify a list of Cloudomation users. {'cloudomation_users': [], 'mode': 'cloudomation_users'} mode string Notify a list of Cloudomation users. Constant value: cloudomation_users {'cloudomation_users': [], 'mode': 'cloudomation_users'} A list of email addresses Key Type Description Default email_addresses array A list of email addresses and the SMTP connector to be used. {'cloudomation_users': [], 'mode': 'email_addresses'} mode string A list of email addresses and the SMTP connector to be used. Constant value: email_addresses {'cloudomation_users': [], 'mode': 'email_addresses'} smtp_connector string 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

on-error

Execution wrapper for rollbacks

starts a rollback flow in case of exceptions

usage:

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

Input schema

Key	Type	Description	Default
child_execution_location	enum	Any of Location of wrapper execution Key Type Description Default mode_name string The child runs where the wrapper execution runs. Constant value: wrapper_execution Location of wrapped resource Key Type Description Default mode_name string The child runs where the child resource is located. Constant value: wrapped_resource Location of wrapper resource Key Type Description Default mode_name string The child runs where the wrapper resource is located. Constant value: wrapper_resource Specific project Key Type Description Default mode_name string Where the child execution should run. Constant value: specific_project project_name string The project where the child should run. Default project Specific bundle Key Type Description Default bundle_name string The bundle where the child should run. mode_name string Where the child execution should run. Constant value: specific_bundle
rollback_flow_name	string	The name of the flow that should be executed in case of a DependencyFailedError.

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

Key	Type	Description	Default
child_execution_location	enum	Any of Location of wrapper execution Key Type Description Default mode_name string The child runs where the wrapper execution runs. Constant value: wrapper_execution Location of wrapped resource Key Type Description Default mode_name string The child runs where the child resource is located. Constant value: wrapped_resource Location of wrapper resource Key Type Description Default mode_name string The child runs where the wrapper resource is located. Constant value: wrapper_resource Specific project Key Type Description Default mode_name string Where the child execution should run. Constant value: specific_project project_name string The project where the child should run. Default project Specific bundle Key Type Description Default bundle_name string The bundle where the child should run. mode_name string Where the child execution should run. Constant value: specific_bundle
delay_sec	integer	The number of seconds to wait in between retries.	10
delete_retries	boolean	If set, previous child executions are deleted when a new child execution is started.	True
max_tries	integer	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

Key	Type	Description	Default
child_execution_location	enum	Any of Location of wrapper execution Key Type Description Default mode_name string The child runs where the wrapper execution runs. Constant value: wrapper_execution Location of wrapped resource Key Type Description Default mode_name string The child runs where the child resource is located. Constant value: wrapped_resource Location of wrapper resource Key Type Description Default mode_name string The child runs where the wrapper resource is located. Constant value: wrapper_resource Specific project Key Type Description Default mode_name string Where the child execution should run. Constant value: specific_project project_name string The project where the child should run. Default project Specific bundle Key Type Description Default bundle_name string The bundle where the child should run. mode_name string Where the child execution should run. Constant value: specific_bundle
rollback_flow_name	string	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

Key	Type	Description	Default
child_execution_location	enum	Any of Location of wrapper execution Key Type Description Default mode_name string The child runs where the wrapper execution runs. Constant value: wrapper_execution Location of wrapped resource Key Type Description Default mode_name string The child runs where the child resource is located. Constant value: wrapped_resource Location of wrapper resource Key Type Description Default mode_name string The child runs where the wrapper resource is located. Constant value: wrapper_resource Specific project Key Type Description Default mode_name string Where the child execution should run. Constant value: specific_project project_name string The project where the child should run. Default project Specific bundle Key Type Description Default bundle_name string The bundle where the child should run. mode_name string Where the child execution should run. Constant value: specific_bundle
seconds	integer	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

Key	Type	Description	Default
child_execution_location	enum	Any of Location of wrapper execution Key Type Description Default mode_name string The child runs where the wrapper execution runs. Constant value: wrapper_execution Location of wrapped resource Key Type Description Default mode_name string The child runs where the child resource is located. Constant value: wrapped_resource Location of wrapper resource Key Type Description Default mode_name string The child runs where the wrapper resource is located. Constant value: wrapper_resource Specific project Key Type Description Default mode_name string Where the child execution should run. Constant value: specific_project project_name string The project where the child should run. Default project Specific bundle Key Type Description Default bundle_name string The bundle where the child should run. mode_name string Where the child execution should run. Constant value: specific_bundle
mode	enum	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_validation	enum	Any of Input value Constant value: input Output value Constant value: output
schema_name	string	The name of the schema resource that should be used for the wrapper.

wrapper-validate-input-schema