Messages and Forms

Messages are accessible in the side menu under Messages.

Cloudomation offers the generation of messages and HTML-forms through flow scripts. This makes it easy to add interactivity to an automation.

Simple messages

A message is generated every time system.message() is called in a flow-script. Messages can be used to request information from a user or to simply provide information. 

A simple message can be created like this:

system.message(subject='your subject', message='your message text.')

To access this message, a user will have to navigate to the messages section in the side menu. All logged in users in the same client can access all messages.

To create a simple string input request, you can use the “request” parameter:

system.message(subject='your subject', request='foobar?')

This will create a simple message with a string input field. Any input provided by the user will be returned as output of the message. Use msg.wait() to wait until the user has provided a response and access the response with msg.get('response').

Complex messages and forms

System.message() can also be used to generate elaborate messages with styled bodies and forms. 

The function system.message() has 3 parameters:

Message Type

There are 4 different types of messages available: 

INFO is the default message type and will be used when you don’t specify the type. WARN and ERROR are highlighted and displayed more prominently than an INFO message. The POPUP message type is displayed in a modal.

Message Body

The body of the message can contain various HTML elements. The type of the HTML element is defined with 'element':'element-type'

There are 8 different types of elements for every kind of message:

string-field: an HTML input field for any string

number-field: an HTML input field for any number

date-field: an HTML input field for dates

time-field: an HTML input field for time

date-time-field: an HTML input field for date and time

markdown-field: markdown displays structured text as HTML

toggle-button: an HTML checkbox input displayed as a toggle button

submit-button: an HTML button, which can be clicked

Example

Let’s create messages!

In the following flow script, two messages will be created. The first is a POPUP message, which asks for the user’s first and last name, whereby the first name is required. 

After clicking the Submit button, the second message of message type INFO will be generated and can be accessed in the sidebar under Messages.

To see this in action, create a new flow script, copy the code into it and hit Try.

def handler(system, this):
    # create a popup message with 2 string input fields and 1 submit button
    msg = system.message(
        subject='Name Input', 
        message_type='POPUP',
        body={
        'type': 'object',        
        'properties': {
            'first-name': {
                'element': 'string',
                'type': 'string',
                'example': 'Enter your first name',
                'order': 1,
                'label': 'What is your first name?',
            },
            'last-name': {
                'element': 'string',
                'type': 'string',
                'example': 'Enter your last name',
                'order': 2,
                'label': 'What is your last name?',
            },
            'submit-button': {
                'element': 'submit',
                'type': 'boolean',
                'order': 3,
                'label': 'Submit',
            },
        },
        'required': [
            'first-name',
            'submit-button',
        ]
    })

    # wait until the user clicked the submit button
    msg.wait()


    response=msg.get('response')
    # read out the values of the input field
    first_name = response.get('first-name')
    last_name = response.get('last-name','')


    # create a second message, which will be visible in the sidemenu under Messages
    hello = system.message(
        subject=f'Hello {first_name}',
        message_type='INFO',  # INFO is the default message type 
        body={
        'type': 'object',
        'properties': {
            'markdown': {
                'element': 'markdown',
                'description': f'### Hello *{first_name} {last_name}*!',
                'order': 1,
            },
        },
    })
    return this.success('all done')

The first message will be displayed as a pop-up:

The second message will be displayed in the messages section directly, with markdown styling applied to the text:

Let’s recap: we used the message types POPUP and INFO, we generated text input fields, a submit-button and a markdown-field in the message body above.

Additionally we waited for the user to click the submit button with msg.wait(), then we got the response with msg.get('response') and read out the values the user just typed in.

Messages like this are used i.e. for inviting a user to your workspace, creating alerts and notifications on the end of of a flow script or on successful or erroneous steps in a process.

Shortcuts

Remembering the handy shortcuts for creating messages mentioned at the very beginning, we can create messages a little faster as well. Instead of providing the body dictionary, either a message or a request keyword argument can be given. Both get passed a string, while the message string can be markdown formatted text.

The request argument generates a string-field, with both the label and the example  set to the text provided by this argument.

The second message from the example above could thus be rewritten like this:

hello = system.message(
    subject=f'Hello {first_name}',
    message_type='INFO', # since INFO is the default we could even omit this line
    message=f'### Hello *{first_name} {last_name}*!'
)