Skip to main content
Version: 9 - Germknödel

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

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

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

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

30
notify_usersenum

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.

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

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

True
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

  • 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

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

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

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