ZoomAsk

Sends a message (question) to either user (in a direct message) or to a channel. The message includes predefined reply options. The response can also close a task (might be conditional) in a playbook.

python · Zoom

Source

import dateparser
import demistomock as demisto
from CommonServerPython import *

from CommonServerUserPython import *

STYLES_DICT = {
    "white": "Default",
    "blue": "Primary",
    "red": "Danger",
    "gray": "Disabled",
}

DATE_FORMAT = "%Y-%m-%d %H:%M:%S"


def parse_option_text(option_text):
    # Function to parse the option text with color information and extract the text and style
    # Format of the option text: "<text>#<color>"
    parts = option_text.split("#", 1)
    if len(parts) == 2:
        text, color = parts
        style = STYLES_DICT.get(color.lower(), "Default")
    else:
        text = option_text
        style = "Default"
    return text, style


def generate_json(text, options, response_type):
    if response_type == "button":
        # Generate JSON for button type response
        button_items = []
        for _i, option in enumerate(options):
            option_text, option_style = parse_option_text(option)
            button_item = {"value": option_text, "style": option_style, "text": option_text}
            button_items.append(button_item)

        json_data = {"head": {"type": "message", "text": text}, "body": [{"type": "actions", "items": button_items}]}

    elif response_type == "dropdown":
        # Generate JSON for dropdown type response
        select_items = []
        for _i, option in enumerate(options):
            option_text, _ = parse_option_text(option)
            select_item = {"value": option_text, "text": option_text}
            select_items.append(select_item)

        json_data = {
            "body": [
                {
                    "select_items": select_items,
                    "text": text,
                    "selected_item": {"value": select_items[0].get("value")},
                    "type": "select",
                }
            ]
        }

    else:
        raise ValueError("Invalid responseType. should be 'button' or 'dropdown'.")
    return json_data


def main():
    demisto_args = demisto.args()
    res = demisto.executeCommand("addEntitlement", {"persistent": demisto_args.get("persistent")})
    if isError(res[0]):
        return_results(res)
    entitlement = demisto.get(res[0], "Contents")
    option1 = demisto_args.get("option1")
    option2 = demisto_args.get("option2")
    extra_options = argToList(demisto_args.get("additionalOptions", ""))
    reply = demisto_args.get("reply")
    response_type = demisto_args.get("responseType", "buttons")
    lifetime = demisto_args.get("lifetime", "1 day")
    try:
        parsed_date = dateparser.parse("in " + lifetime, settings={"TIMEZONE": "UTC"})
        assert parsed_date is not None, f"Could not parse in {lifetime}"
        expiry = datetime.strftime(parsed_date, DATE_FORMAT)
    except Exception:
        parsed_date = dateparser.parse("in 1 day", settings={"TIMEZONE": "UTC"})
        assert parsed_date is not None
        expiry = datetime.strftime(parsed_date, DATE_FORMAT)
    default_response = demisto_args.get("defaultResponse")

    entitlement_string = entitlement + "@" + demisto.investigation()["id"]
    if demisto_args.get("task"):
        entitlement_string += "|" + demisto_args.get("task")

    args = {"ignoreAddURL": "true", "using-brand": "Zoom"}

    user_options = [option1, option2]
    if extra_options:
        user_options += extra_options
    blocks = json.dumps(generate_json(demisto.args()["message"], user_options, response_type))
    args["message"] = json.dumps(
        {
            "blocks": blocks,
            "entitlement": entitlement_string,
            "reply": reply,
            "expiry": expiry,
            "default_response": default_response,
        }
    )
    to = demisto_args.get("user")
    channel_name = demisto_args.get("channel_name")
    channel = demisto_args.get("channel_id")

    if to:
        args["to"] = to
    elif channel:
        args["channel_id"] = channel
    elif channel_name:
        args["channel"] = channel_name
    else:
        return_error("Either a user or a channel_id or channel_name must be specified")

    args["zoom_ask"] = "true"
    try:
        return_results(demisto.executeCommand("send-notification", args))
    except ValueError as e:
        if "Unsupported Command" in str(e):
            return_error(f"The command is unsupported by this script. {e}")
        else:
            return_error("An error has occurred while executing the send-notification command", error=e)


if __name__ in ("__builtin__", "builtins", "__main__"):
    main()

README

Sends a message (question) to either a user (in a direct message) or to a channel. The message includes predefined reply options. The response can also close a task (might be conditional) in a playbook.

Script Data


Name Description
Script Type python3
Tags Zoom
Version 5.5.0

Use Case


This automation allows you to ask users in Zoom (including users who are external to Cortex XSOAR) questions, have them respond and
reflect the answer back to Cortex XSOAR.

Dependencies


Requires an instance of the Zoom integration with Long Running instance checked.

This script uses the following commands and scripts.
send-notification

Inputs


Argument Name Description
user The Zoom user to whom to send the message. Can be either an email address or a Zoom user_id.
channel_id The Zoom channel_id to which to send the message.
message The message to send to the user or channel.
option1 The first reply option. The default is “Yes” with a blue button. To change the color of the button, add the pound sign (#) followed by the name of the new color (blue, red, or black). The default color is “Blue”. For example, “Yes#blue”. Options cannot contain whitespaces.
option2 The second reply option. The default is “No” with a red button. To change the button color, add the pound sign (#) followed by the name of the new color (green, red, or black). The default color is “red”. For example, “No#red”. Options cannot contain whitespaces.
task The task to close with the reply. If empty, then no playbook tasks will be closed.
persistent Indicates whether to use one-time entitlement or persistent entitlement.
responseType How the user should respond to the question.
additionalOptions A comma-separated list of additional options in the format of “option#color”, for example, “maybe#red”. The default color is “black”. Options cannot contain whitespaces.
reply The reply to send to the user. Use the templates {user} and {response} to incorporate these in the reply. (i.e., “Thank you {user}. You have answered {response}.”)
lifetime Time until the question expires. For example - 1 day. When it expires, a default response is sent.
defaultResponse Default response in case the question expires.

Outputs


There are no outputs for this script.

Guide


The automation is most useful in a playbook to determine the outcome of a conditional task - which will be one of the provided options.
It uses a mechanism that allows external users to respond in Cortex XSOAR (per investigation) with entitlement strings embedded within the message contents.
ZoomAsk

The automation can utilize the interactive capabilities of Zoom to send a form with buttons.
This requires the external endpoint for interactive responses to be available for connection. (See the Zoom integration documentation).
You can also utilize a dropdown list instead, by specifying the responseType argument.

To use ZoomAsk via playbook:

  1. Add the ZoomAsk script to a playbook as a task.
  2. In the message argument, specify the message to be sent.
  3. Configure the response options by filling out the option1 and option2 arguments (default values are ‘Yes’ and ‘No’).
  4. Either a user or a channel_id or channel_name must be specified.
  5. In the ZoomAsk task, pass a tag value to the task argument.

All other inputs are optional.
At some point at the playbook, after running ZoomAsk, add a manual conditional task, which holds up the playbook execution until the response is received from Zoom.
The condition names must match the response options you passed in to ZoomAsk.
In order to tie the conditional task back to ZoomAsk, add the same tag from the fifth step to the conditional task (under the “Details” tab of the task). The conditional task will be marked as completed when a user responds to the ZoomAsk form.

Notes


  • ZoomAsk will not work when run in the playbook debugger. This is because the debugger does not generate entitlements, since they must be tied to an investigation. Entitlements are needed to track the response.
  • Whitespaces are not supported in custom options and will not work. (i.e. setting a button to I Agree)