Wrapper bundle

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-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
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.
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_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
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 Notify all users which were active within interactive_limit_minutes. Single user Notify a single user. Multiple users 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
ignore_in_productive_mode	boolean	When set and run in productive mode, the child will not be mocked but started normally.	True
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}} ______________________________ {{/notify_on_state_change}}
child_message_is_markdown	boolean	If set, the status message of ended child executions is interpreted as markdown.	True
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}}
to	enum	Any of Single user Notify a single user. Multiple users 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,
    timeout_sec: int = 0,
    delete_retries: bool = True,
).flow(
    'child-execution'
)

DEPRECATED: the timeout_sec option is deprecated, in favour of it please combine the retry wrapper with the timeout wrapper like this:

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

todo:

• back-off
• hard timeout: cancel child when exceeded

Input schema

Key	Type	Description	Default
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
timeout_sec	integer	DEPRECATED Fail, if the child did not succeed within the timeout. Set to 0 to disable.

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
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
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
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