Base Dispatcher

nautobot_chatops.dispatchers

Dispatchers module for the nautobot_chatops Nautobot App.

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 = '' class-attribute instance-attribute

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

platform_color = None class-attribute instance-attribute

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

platform_name = None class-attribute instance-attribute

Descriptive string - must be set by all subclasses.

platform_slug = None class-attribute instance-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.