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.

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.