Skip to content

# Base Dispatcher

## `nautobot_chatops.dispatchers`

Dispatchers module for the nautobot_chatops Nautobot plugin.

The classes implemented in this module implement a common API for "dispatching" content (plaintext messages, formatted text, UI elements, etc.) to the user of a given chat platform.

### `Dispatcher`

Abstract base class for all chat-app dispatchers.

#### `command_prefix = ''` `instance-attribute` `class-attribute`

Prefix prepended to all commands, such as "/" or "!" in some clients.

#### `platform_color = None` `instance-attribute` `class-attribute`

RGB hex code associated with this platform - must be set by all subclasses.

#### `platform_name = None` `instance-attribute` `class-attribute`

Descriptive string - must be set by all subclasses.

#### `platform_slug = None` `instance-attribute` `class-attribute`

String which is used to set the "chat_type" extra variable when sending jobs to Ansible tower.

Ansible uses this to derive the filename of the module to call when running the chat_message Role.

#### `user` `property`

Dispatcher property containing the Nautobot User that is linked to the Chat User.

#### `__init__(context=None)`

Init this Dispatcher with the provided dict of contextual information (which will vary by app).

#### `actions_block(block_id, actions)`

Construct a block consisting of a set of action elements.

#### `ask_permission_to_send_image(filename, action_id)`

Send a prompt to the user to grant permission to post an image.

#### `bold(text)`

Mark text as bold.

#### `command_response_header(command, subcommand, args, description='information', image_element=None)`

Construct a consistently forwarded header including the command that was issued.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`command` | `str` | Primary command string | required
`subcommand` | `str` | Secondary command string | required
`args` | `list` | of tuples, either (arg_name, human_readable_value, literal_value) or (arg_name, literal_value) | required
`description` | `str` | Short description of what information is contained in the response | `'information'`
`image_element` | `dict` | As constructed by self.image_element() | `None`

#### `get_session()`

Return the whole session data.

#### `get_session_entry(key)`

Return the session data for a key.

#### `hyperlink(text, url)`

Create Hyperlinks.

#### `image_element(url, alt_text='')`

Construct an image element that can be embedded in a block.

#### `lookup_user_id_by_email(email)` `classmethod`

Call out to the chat platform to look up a specific user ID by email.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`email` | `str` | Uniquely identifying email address of the user. | required

Returns:

Type | Description
--- | ---
`Optional[str]` | (str, None)

#### `markdown_block(text)`

Construct a simple Markdown-formatted text block.

#### `markdown_element(text)`

Construct a simple Markdown-formatted text element.

#### `monospace(text)`

Mark text as monospace.

#### `multi_input_dialog(command, sub_command, dialog_title, dialog_list)`

Provide several input fields on a single dialog.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`command` | `str` | The top level command in use. (ex. net) | required
`sub_command` | `str` | The command being invoked (ex. add-vlan) | required
`dialog_title` | `str` | Title of the dialog box | required
`dialog_list` | `list` | List of dictionaries containing the dialog parameters. See Example below. | required

Example

For a selection menu::

    {
        type: "select",
        label: "label",
        choices: [("display 1", "value1"), ("display 2", "value 2")],
        default: ("display 1", "value1"),
        confirm: False
    }

For a text dialog::

    {
        type: "text",
        label: "text displayed next to field"
        default: "default-value",
        optional: True
    }

Dictionary Fields

- type: The type of object to create. Currently supported values: select, text
- label: A text descriptor that will be placed next to the field
- choices: A list of tuples which populates the choices in a dropdown selector
- default: (optional) Default choice of a select menu or initial value to put in a text field.
- confirm: (optional) If set to True, it will display a "Are you sure?" dialog upon submit.
- optional: (optional) If set to True, the field will return NoneType is not specified.

#### `needs_permission_to_send_image()`

Return True if this bot needs to ask the user for permission to post an image.

#### `platform_lookup(item_type, item_name)` `classmethod`

Call out to the chat platform to look up, e.g., a specific user ID by name.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`item_type` | `str` | One of "organization", "channel", "user" | required
`item_name` | `str` | Uniquely identifying name of the given item. | required

Returns:

Type | Description
--- | ---
`Optional[str]` | (str, None)

#### `prompt_for_text(action_id, help_text, label, title='Your attention please!')`

Prompt the user to enter freeform text into a field.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`action_id` | `str` | Identifier string to attach to the "submit" action. | required
`help_text` | `str` | Markdown string to display as help text. | required
`label` | `str` | Label text to display adjacent to the text field. | required
`title` | `str` | Title to include on the modal dialog. | `'Your attention please!'`

#### `prompt_from_menu(action_id, help_text, choices, default=(None, None), confirm=False, offset=0)`

Prompt the user to make a selection from a menu of choices.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`action_id` | `str` | Identifier string to attach to the "submit" action. | required
`help_text` | `str` | Markdown string to display as help text. | required
`choices` | `list` | List of (display, value) tuples. | required
`default` | `tuple` | Default (display, value) to pre-select. | `(None, None)`
`confirm` | `bool` | If True, prompt the user to confirm their selection (if the platform supports this). | `False`
`offset` | `int` | Used for apps that have a menu selection display limit. | `0`

#### `select_element(action_id, choices, default=(None, None), confirm=False)`

Construct a basic selection menu with the given choices.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`action_id` | `str` | Identifying string to associate with this element | required
`choices` | `list` | List of (display, value) tuples | required
`default` | `tuple` | Default (display, value) to preselect | `(None, None)`
`confirm` | `bool` | If true (and the platform supports it), prompt the user to confirm their selection | `False`

#### `send_blocks(blocks, callback_id=None, modal=False, ephemeral=None, title=None)`

Send a series of formatting blocks to the user/channel specified by the context.

#### `send_busy_indicator()`

Send a "typing" indicator to show that work is in progress.

#### `send_error(message)`

Send an error message to the user/channel specified by the context.

#### `send_image(image_path)`

Send an image as a file upload.

#### `send_large_table(header, rows, title=None)`

Send a large table of data to the user/channel.

The below default implementation works for both Slack and Webex.

#### `send_markdown(message, ephemeral=None)`

Send a Markdown-formatted text message to the user/channel specified by the context.

#### `send_snippet(text, title=None, ephemeral=None)`

Send a longer chunk of text as a snippet or file attachment.

#### `send_warning(message)`

Send a warning message to the user/channel specified by the context.

#### `set_session(value)`

Set the whole session data.

#### `set_session_entry(key, value)`

Set the session data for a key.

#### `split_message(text_string, max_message_size)` `staticmethod`

Method to split a message into smaller messages.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`text_string` | `str` | Text string that should be split | required
`max_message_size` | `int` | Maximum size for a message | required

#### `static_url(path)`

Construct an absolute URL for the given static file path, such as "nautobot/NautobotLogoSquare.png".

#### `subclasses()` `classmethod`

Get a list of all subclasses of Dispatcher that are known to Nautobot.

#### `text_element(text)`

Construct a simple plaintext element.

#### `unset_session()`

Unset whole session data.

#### `unset_session_entry(key)`

Unset a session data for a key.

#### `user_mention()`

Markup for a mention of the username/userid specified in our context.