Messages and Forms

Use Cases

Use messages to

• provide status updates about active executions
• log processing steps
• store reports or results

Use forms to

• query parameters from Cloudomation users
• wait for confirmation by Cloudomation users

Concept

Usage

Messages and forms are created by an execution of a flow.

Simple informational message

To create a simple informational message use the message argument of the system.message() call. The message will be rendered as markdown and include an "OK" button.

import flow_api
def handler(system: flow_api.System, this: flow_api.Execution):
    system.message(
        subject='Information message',
        message=(
            '''
            # Message body
            with **Markdown** formatting!
            '''
        ),
    )
    return this.success('all done')

Simple request form

To create a simple request form use the request argument of the system.message() call. The message will include one string input field and an "OK" button. The value entered by the user is accessible in the string key of the response dictionary.

import flow_api
def handler(system: flow_api.System, this: flow_api.Execution):
    message = system.message(
        subject='Input request',
        request='Please enter some value',
    )
    # wait until the message was responded
    message.wait()
    # retreive the value which was entered
    # the value of a "request" message is always of type string
    # and stored in the key `string`
    value = message.get('response')['string']
    this.log(value=value)
    return this.success('all done')

Advanced message form

To create advanced message forms use the body argument of the system.message() call. The message can contain multiple informational fields, input fields, and submit buttons. The structure of the response dictionary is configured by the names of the fields.

The value of the body argument is validated with SCHEMA_MESSAGE_BODY which is outlined below:

SCHEMA_MESSAGE_FIELD = {
    'type': 'object',
    'properties': {
        # the form element to use
        'element': {
            'type': 'string',
            'enum': [
                'string',       # string input field
                'number',       # number input field
                'password',     # password input field
                'date',         # date picker
                                # returned as string in the format YYYY-mm-dd
                'time',         # time input field or picker (browser dependent)
                                # returned as string in the format HH:MM
                'date-time',    # date-time picker
                                # returned as string in the format YYYY-mm-ddTHH:MM
                'markdown',     # markdown output
                'toggle',       # toggle button
                                # returned as boolean
                'submit',       # submit button
                                # the button which was pressed
                                # will return boolean `True`
            ]
        },
        # datatype of the value in the response dictionary
        'type': {
            'type': 'string',
            'enum': ['string', 'number', 'boolean']
        },
        # label for the element. if unset, the name of the field is used.
        'label': {
            'type': 'string'
        },
        # the "placeholder" value, displayed when the input field is empty
        'example': {
            'type': ['string', 'number', 'null']
        },
        # the order in which the element will appear in the form
        'order': {
            'type': 'integer'
        },
        # a default value which is pre-filled
        'default': {
            'type': ['string', 'number', 'boolean', 'null']
        },
        # an additional format validator.
        # see https://json-schema.org/understanding-json-schema/reference/string.html#format
        'format': {
            'type': 'string'
        },
        # the markdown content
        'description': {
            'type': 'string'
        },
    },
    'required': [
        'element',
        'type',
        'order',
    ],
    'additionalProperties': False,
    "if": {
        "properties": { "element": { "const": "submit" } }
    },
    "then": {
        "properties": { "type": { "const": "boolean", } }
    },
    "else": {
    }
}
SCHEMA_MESSAGE_PROPERTIES = {
    'type': 'object',
    'patternProperties': {
        # field names must match this pattern
        '^[a-zA-Z0-9_]+$': SCHEMA_MESSAGE_FIELD,
    },
}
SCHEMA_MESSAGE_BODY = {
    'type': 'object',
    'properties': {
        # always "object"
        'type': {'type': 'string', 'enum': ['object']},
        'properties': SCHEMA_MESSAGE_PROPERTIES,
        # a list of field names which must be entered by the user
        'required': {'type': 'array', 'items': {'type': 'string'}},
    },
    'required': ['type', 'properties'],
}

import flow_api
def handler(system: flow_api.System, this: flow_api.Execution):
    message = system.message(
        subject='Message form',
        body={
            'type': 'object',
            'properties': {
                # the key in the response dictinary where the value will be stored
                'string-field': {
                    'element': 'string',
                    'type': 'string',
                    'example': 'enter a string',
                    'order': 1,
                    'label': 'string-field-label',
                },
                'number-field': {
                    'element': 'number',
                    'type': 'number',
                    'example': 'enter a number',
                    'order': 2,
                },
                'date-field': {
                    'element': 'date',
                    'type': 'string',
                    'format': 'date',
                    'order': 3,
                },
                'time-field': {
                    'element': 'time',
                    'type': 'string',
                    'format': 'time',
                    'order': 4,
                },
                'date-time-field': {
                    'element': 'date-time',
                    'type': 'string',
                    'format': 'date-time',
                    'order': 5,
                },
                # the markdown field is only informational and does
                # not produce a key in the response dictionary
                'markdown-field': {
                    'element': 'markdown',
                    'description': '### Markdown\n\n- item 1\n- item 2\n- item3',
                    'order': 6,
                },
                'toggle-button': {
                    'element': 'toggle',
                    'type': 'boolean',
                    'order': 7,
                },
                'submit-button': {
                    'element': 'submit',
                    'type': 'boolean',
                    'order': 8,
                },
                'alternative submit-button': {
                    'element': 'submit',
                    'type': 'boolean',
                    'order': 9,
                },
            },
            'required': [
                'string-field',
                'time-field',
            ],
        },
    )
    # wait until the message was responded
    message.wait()
    # retreive all values which were entered
    response = message.get('response')
    this.log(response=response)
    return this.success('all done')

Learn more