interaction.worker automations are conversational processes that can pause between steps to collect additional input, such as web-based forms or other external events.

An interaction continues to the next step once additional input is received.

The most common source of additional input is a web-based form with multiple fields.

• Inputs
• Outputs
  • await:form:
  • await:draft:
  • await:duration:
  • await:interaction:
  • await:record:
  • return:
• Callers
  • Toolbars
  • Built-in
    • Interactions
    • Project boards
    • Sheets
    • Internal

These interactions are started by a caller in response to a worker action within Cerb. The caller is usually a customizable toolbar, but it could be any interface component or feature (e.g. buttons, links, images).

At its conclusion, an interaction returns a dictionary and exit state to the caller, which is then responsible for acting on the results.

Each caller provides its own inputs, as well as the possible responses it accepts.

This separation of duties makes interactions simpler to build and reuse. An interaction doesn’t have to be concerned with the capabilities of a specific caller.

For instance, an interaction may be started from a toolbar in the email reply editor to fetch information based on the recipients (e.g. order history). The interaction generates and returns a text snippet, which the caller pastes into the editor at the cursor. The interaction only needs to generate some text, without any consideration for how it will be pasted into the editor.

Inputs

An interaction automation dictionary starts with the following input values:

Outputs

await:form:

When suspending in the await:form: state, the interaction displays a web form with the desired elements. The form may prompt for user input, validate it, and set dictionary keys (placeholders) with the responses.

await:
  form:
    title: Your form title
    elements:
      # ...

title:

The title of this form to be displayed in the interaction popup. This is usually a summary of the current step.

elements:

Form elements are defined with a key in the format type/name:.

The name must be unique within the form. When an element prompts for user input, a placeholder with the same name will be created with their response. For instance, text/prompt_name: will create a placeholder of {{prompt_name}} with the value of that text element.

A form can be created with any combination of the following element types:

When the interaction suspends in the await state, a submit: element is automatically appended to the form if one doesn’t already exist.

start:
  await/who:
    form:
      title: Introduction
      elements:
        text/prompt_name:
          label: What is your name?
          required@bool: yes
  
  await/hello:
    form:
      title: Hello!
      elements:
        say/hello:
          content: Hello, {{prompt_name}}!
  
  return:
    user:
      name@key: prompt_name

await:draft:

When suspending in the await:draft: state, the interaction opens the email editor popup and waits for completion.

uri:

The uri: parameter specifies a compose or reply draft to resume (by ID or token). An automation can create a draft record prior to this step.

output:

An optional output: parameter has the following keys:

This allows the interaction to make decisions based on those outcomes.

start:
  record.create:
    output: draft_record
    inputs:
      record_type: draft
      # See: https://cerb.ai/docs/records/types/draft/
      fields:
        name: Draft for customer@cerb.example
        type: mail.compose
        worker_id@key,int: worker_id
        params:
          to: customer@cerb.example
          content@text:
            Hi,
            
            #signature

  await/resume:
    draft:
      uri: cerb:draft:{{draft_record.id}}
      output: results_draft

  outcome/sent:
    if@bool: {{results_draft.status ends with '.sent'}}
    then:
      await:
        form:
          say: Message sent!

await:duration:

When suspending in the await:duration: state, the interaction displays a message: and waits until: a given date/time or interval (e.g. 5 seconds).

This can be used to display a status update while waiting for a long-running asynchronous task to finish. For instance, an AWS Step Function for new account provisioning.

message:

The message: to be displayed in the interaction while waiting.

until:

The until: parameter is an absolute (2021-12-31 08:00 America/New_York) or relative (10 seconds) duration to wait for before resuming.

output:

(none)

start:
  set:
    isPlaying@bool: yes
  
  while:
    if@bool: {{isPlaying}}
    do:
      # A suspenseful wait
      await/rolling:
        duration:
          message: Rolling...
          until: 3 seconds
      
      await/rolled:
        form:
          title: Results
          elements:
            say:
              content@text:
                You rolled a {{random(1,6)}}
                ====
            submit/prompt_continue:
              buttons:
                continue/yes:
                  label: Roll again
                  icon: playing-dices
                  icon_at: start
                  value: roll
                continue/no:
                  label: Quit
                  style: secondary
                  value: quit
      
      # If quitting, break the loop
      outcome/quit:
        if@bool: {{prompt_continue == 'quit'}}
        then:
          set:
            isPlaying@bool: no

await:interaction:

When suspending in the await:interaction: state, the interaction temporarily hands control to another delegate interaction. The interaction resumes at the current point when the delegate exits.

Delegates can be nested to any depth. For instance, a reusable delegate could handle email or SMS validation, and be shared by many other interactions.

This makes interactions much more modular and reusable.

uri:

The uri: parameter specifies the delegate automation. This must use the interaction.worker trigger.

output:

An output: key specifies the placeholder that should receive the results from the delegate.

start:
  while:
    if@bool: yes
    do:
      await/menu:
        form:
          title: Menu
          elements:
            say:
              message: How can we help?
            sheet/prompt_menu:
              required@bool: yes
              data:
                0:
                  key: map
                  label: Map
                1:
                  key: echo
                  label: Echo
              schema:
                layout:
                  style: buttons
                  headings@bool: no
                  paging@bool: no
                  title_column: label
                columns:
                  selection/key:
                    params:
                      mode: single
                  text/label:
            submit:
              continue@bool: no
              reset@bool: no
      await/do:
        interaction:
          output: results
          uri@text:
            cerb:automation:{{{
                'map': 'wgm.interaction.locationByIP',
                'echo': 'wgm.interaction.echo',
              }[prompt_menu]}}

await:record:

When suspending in the await:record: state, the interaction opens a record editor popup and waits for completion.

uri:

This takes a uri: parameter which specifies a record type (and optionally record ID) to open in an editor popup.

If the ID is omitted then the editor is opened in ‘create’ mode.

output:

An optional output: parameter specifies a placeholder to store the status of the record after creation/modification (e.g. saved, deleted, aborted).

This allows the interaction to make decisions based on those outcomes.

inputs:
  text/record_type:
    type: record_type
    required@bool: yes
  record/column:
    record_type: project_board_column
    required@bool: yes

start:
  await:
    record:
      uri: cerb:{{inputs.record_type}}
      output: result
  outcome:
    if@bool: {{result.record._context and result.record.id}}
    then:
      record.update:
        output: new_record
        inputs:
          record_type: {{result.record._context}}
          record_id: {{result.record.id}}
          fields:
            links@list:
              project_board_column:{{inputs.column.id}}

return:

When the interaction concludes in the return state, it returns any number of key/value pairs to the caller. Keys may be nested to return dictionaries.

Each caller has a set of expected return keys to control its behavior.

return:
  key1: value1
  key2: value2
  ...

The following keys are available on all worker interactions:

Callers

An interaction receives different inputs and expects different outputs depending on its caller.

Toolbars

Built-in

Interactions

Project boards

Sheets

Internal