Docs »

Automations »

Triggers »

interaction.worker

interaction.worker automations are worker-based interactions that use continuations to pause and resume a multi-step workflow.

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:

Key Type Notes
caller_name string The caller which started the interaction.
caller_params dictionary Built-in parameters based on the caller type.
client_browser_name string The client browser name (e.g. Safari).
client_browser_platform string The client browser platform (e.g. Macintosh).
client_browser_version string The client browser version.
client_ip string The client IP address.
client_url string The client browser URL for the current page.
inputs dictionary Custom input values from the caller.
worker_* record The active worker record. Supports key expansion.

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:

Element  
editor: A code editor with syntax highlighting, autocompletion, and a custom toolbar.
fileDownload: File download prompt
fileUpload: File upload prompt
map: Interactive map
query: Search query prompt with autocompletion
say: Block of text or Markdown
sheet: Sheet with row selection
submit: Continue to next step
text: Text input with data types
textarea: Multiple lines of text

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:

status One of: compose.sent, compose.draft, compose.discard, reply.sent, reply.draft, reply.discard
record The dictionary of the record. For .sent this will be a message. For .draft it will be a draft.

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

event record.created, record.updated, record.deleted, record.aborted
record The dictionary of the created or modified record.

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:

Key Description
alert: Display a time-limited message at the top of a worker’s browser. This is particularly useful to confirm non-interactive actions (e.g. “Copied!”).
clipboard: Copy the given text to the worker’s keyboard. This is only available in response to a worker gesture (e.g. clicking an interaction toolbar).
open_link: Open a new tab in the worker’s browser to the given URL.
timer: Start a time tracking timer with the given time entry record ID.
snippet: If the interaction was started from an editor, paste the given text at the cursor.

Callers

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

Toolbars

Toolbar  
global.menu Global interactions from the floating icon in the lower right
mail.compose Composing new email messages
mail.read Reading email messages
mail.reply Replying to email messages
record.card Viewing a record card popup
record.profile Viewing a record profile page

Built-in

Interactions

Caller  
cerb.toolbar.cardWidget.interactions Interactions toolbar in card widgets
cerb.toolbar.profileWidget.interactions Interactions toolbar in profile widgets
cerb.toolbar.workspaceWidget.interactions Interactions toolbar in workspace widgets

Project boards

Caller  
cerb.toolbar.projectBoardColumn Project board column toolbar

Sheets

Caller  
cerb.toolbar.automation.interaction.worker.await.sheet Sheet prompt toolbar in an interaction
cerb.toolbar.cardWidget.sheet Sheet toolbar in card widgets
cerb.toolbar.profileWidget.sheet Sheet toolbar in profile widgets

Internal

Caller  
cerb.toolbar.editor.automation.script Automation script editor toolbar
cerb.toolbar.editor.automation.trigger Automation editor trigger chooser
cerb.toolbar.eventHandlers.editor Automation event handlers editor toolbar
cerb.toolbar.editor Toolbar editor
cerb.toolbar.editor.map Map editor toolbar