Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use, which are available at https://www.stonebranch.com/integration-hub/Terms-and-Privacy/Terms-of-Use/

Overview

Slack is a messaging app for business that connects people to the information they need. By bringing people together to work as one unified team, Slack transforms the way organizations communicate.

This Universal Extension creates a Slack Bot that provides the capability to directly interact with Universal Controller, by executing Slack Commands.

Version Information

Refer to Changelog for version history information.

Software Requirements

This integration requires a Universal Agent and a Python runtime to execute the Universal Task.

Software Requirements for Universal Template and Universal Task

Requires Python 3.7.0 or higher. Tested with the Universal Agent bundled Python distribution.

Software Requirements for Universal Agent

Both Windows and Linux agents are supported.

• Universal Agent for Windows x64 Version 7.1.0.0 and later with python options installed.
• Universal Agent for Linux Version 7.1.0.0 and later with python options installed.

Software Requirements for Universal Controller

Universal Controller Version 7.1.0.0 and later.

Network and Connectivity Requirements

UE Slack Bot needs outbound connectivity with Slack , which is achieved by using WebSockets, connected in port 443. Additionally, it needs HTTPS outbound connectivity to the Universal Controller for the bot to answer Slack Commands.

Key Features

This Universal Extension provides Slack Commands that let a user gain information about reports, agents and task instances, or even alter the latter. These commands are the following:

Additionally, this extension provides the following features:

• Help Menu: Quick access to all available commands.
• Graphical & CLI interface: Trigger automation commands both through popup dialogs and "command-line" style interface.
• Audit: Keep a detailed audit log on Slack users' interaction to the UAC Bot and the UAC.
• Security & fine-grained access control (ACL): Limit the access to the UAC Bot using a private Slack channel (only members of this channel will be able to use the UAC Bot) & manage the level of access of your Slack users, on a resource level (making sure that the right users have access to available resources & actions).

How to Start 

This extension is shipped with in-Slack dialogs available to your users, in order for them to be introduced to the basic Slack Bot functionality and provide on-going access to help menu. Here is a list of example screenshots that provide a step-by-step approach to a user for getting familiar to Slack Bot and successfully executing one Slack Bot command.

Step 1: Introduction of the Slack Bot to the users is done at the setup phase, where the Slack Bot greets the channel users with a small and informative message, guiding them on the next actions they could take.

Step 2: The help menu is available to the users whenever they need a list of available commands, from which they can even trigger the corresponding popup dialog (help menu is available though command /uacbot help).

Step 3: Triggering a Slack command from a popup dialog is helpful, as the dialog provides guidance on the available parameters and their values.

Step 4: Slack Bot command results are provided in-channel, with simple and informative messages.

Import Universal Template

To use the Universal Template, the following steps need to be followed:

1. This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.

2. To import the Universal Template into your Controller, follow the instructions here.

3. When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.

Modifications of this integration, applied by users or customers, before or after import, might affect the supportability of this integration. For more information refer to Integration Modifications.

Slack Application Installation & UC Extension Configuration

In order to use the Slack Bot extension, it is required to:

1. Create a Slack Application in your workspace.
2. Configure a slack channel for the UAC Slack bot to operate in.
3. Configure the extension to connect to the Slack Application.
4. Initialize channel participants and verify user access.

Those steps are described in detail in the following sections.

Slack Application Creation

Create Application

In order to create a new Slack Application in your workspace, the following steps using an admin account in your Slack workspace needs to be executed:

1. Navigate to the page which displays the applications created in your workspace: https://api.slack.com/apps
2. Select option: "Create an app".
3. Chose option: "From scratch".
4. Set App Name: "Stonebranch UAC Bot".
5. Set the workspace that the application will be installed in.
6. Press button "Create App", which should result to web browser redirection to the application settings page.

Create Application Token

The first configuration needed in this new application is to create an App-Level token, from the "Basic Information" page:

1. Scroll down to "App-Level Tokens" section .
2. Press "Generate Token and Scopes".
3. In the popup provided:
   • Add some token name (e.g. "app_token").
   • Add scope: "connections:write".
   • Press "Generate" button and copy the Token that was just created, it will later be used as input to the "Slack App Token" field of the Slack Bot task.
4. Close the popup and verify the new token is listed in "Tokens" list.

Apply application configuration

Most of the application configuration needed will be applied through a Manifest file, but on top of this, it is needed to do some additional configuration by hand.

Apply application Manifest file

Navigate to "App Manifest" section (navigation bar on the left) and follow the steps:

1. Select "YAML" preview.
2. Override the App Manifest with the following configuration:

display_information:
  name: Stonebranch UAC Bot
  description: Integrate Slack Workspace with UAC platform
  background_color: "#000000"
settings:
  org_deploy_enabled: false
  token_rotation_enabled: false
  socket_mode_enabled: true
  interactivity:
    is_enabled: true
  event_subscriptions:
    bot_events:
      - app_mention
features:
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: false
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: UACBot
    always_online: true
  slash_commands:
    - command: /uacbot
      description: Send commands to UAC Bot
      usage_hint: " [command] [parameters]"
      should_escape: false
oauth_config:
  scopes:
    bot:
    - app_mentions:read
    - channels:read
    - chat:write
    - commands
    - files:write
    - links:write
    - users:read
    - groups:read

3. Press "Save Changes".

4. After this step make sure the following settings are set correctly:

• Basic Information > Add Features and functionality > Slash Commands: Only one command was created with name '/uacbot'.
• Basic Information > Add Features and functionality > Event Subscriptions: Should be enabled, and socket mode identified as enabled.
  • "Subscribe to bot events" list includes only event "app_mention".
  • "Subscribe to events on behalf of users" list should be empty.
  • "App unfurl domain" list should be empty.
• Basic Information > Add Features and functionality > Bots:
  • Verify that Display Name (Bot Name) equals "UACBot".
  • Verify that Default Name equals "uacbot".
  • Verify that "Always Show My Bot as Online" is checked.
  • Verify that Show Tabs > Home Tab is disabled.
  • Verify that Show Tabs > Messages Tab is disabled.
• Basic Information > Add Features and functionality > Permissions:
  • Verify that in Scopes > Bot Token Scopes list only these scopes are included:
    • app_mentions:read
    • channels:read
    • chat:write
    • commands
    • files:write
    • links:write
    • users:read
  • Verify that Scopes > User Token Scopes list is empty.

Application installation in workspace

1. Navigate to "OAuth & Permissions" (navigation bar on the left).
2. In section "OAuth Tokens for Your Workspace", select "Install to Workspace", review the requested permissions (they should match the Bot Token Scopes mentioned in previous section), and approve installation.
3. After successful installation, the web browser will be redirected back to "OAuth & Permissions" page, and a "Bot User OAuth Token" should now be available. Copy the Bot Token that was just created, it will later be used as input to the "Slack Bot Token" field of the Slack Bot task.

Application Icon

The final step in application configuration is setting the application icon that will be visible in all responses the Slack Bot will be posting. To set this up the following steps are required:

1. Navigate to "Basic Information" (navigation bar on the left).
2. Scroll down to the "Display Information" section.
3. Upload the icon provided here:

Configure a slack channel

After creating the new Slack Application, using again a Slack admin account, follow the steps:

1. Create a new private Slack channel in your workspace (naming is not important).
2. Copy the channel ID from the channel info (right click on channel -> get channel details), it will later be used as input to the "Slack Channel ID" field of the Slack Bot task.
3. Do not invite any Slack users to this channel yet.

Configure Universal Task

For a new Universal Task, create a new task, and enter the required input fields.

Input Fields

The input fields for this Universal Extension are described below.

ACL

ACL (Access Control List) is responsible for granting or denying permissions to your Slack users, on accessing specific functionality & resources on UC, through Slack commands. The access rights granted can be fine-grained, using rules that describe the explicit access right for a specific user, providing his e-mail local part(what everything is included before @ symbol) on a specific resource type and the corresponding action on that resource.

Permissions

The default permission (that is used even if it is not explicitly provided in configuration) is DENY for all users on all resources, meaning that by default no Slack user can run any Slack command. Users will be able to use the available Slack commands when rules that permit such actions are added to the ACL. More than one rules can be created for each user, so it is possible for your users to have different access rights per resource. Also this integration supports rules that can be used to specify access rights for multiple users and/or multiple resources, using the wildcard character '*'. This makes it easier to provide access rights to multiple users with a single access rule, but it should be used with caution.

Permissions Evaluation

The ACL rules are evaluated sequentially from the first to the last one, and access to a resource is provided either when an explicit rule is found that grants permission or if no rule denying permission is found in the list.

Permissions Configuration

The ACL configuration is based on UC Scripts (of type Data Script), and more specifically expressed with JSON format. It is expected to be consisted of rules for each user, where each rule has the following fields:

ACL Rules to Slack Command Mapping

Usage Examples

The order in which the rules are provided is essential. The first rule has the most priority whereas the last rule is the lowest priority.

• Granting access to user with email "john.doe@company.com" to execute rerun task instance command.

{
  "john.doe": [
    {
        "resource": "instance",
        "action": "instance.rerun",
        "permission": "ALLOW"
    }
  ]
}

• Granting access to user with email "alice.smith@company.com" to execute rerun task instance and show agents status commands.

{
  "alice.smith": [
    {
        "resource": "instance",
        "action": "instance.rerun",
        "permission": "ALLOW"
    },
    {
        "resource": "agent",
        "action": "agent.query",
        "permission": "ALLOW"
    }
  ]
}

• Granting access to user with email "john.doe@company.com" to execute all commands related to instances and allow user with email "alice.smith@example" to only run reports and hold task instances.

{
  "john.doe": [
    {
        "resource": "instance",
        "action": "*",
        "permission": "ALLOW"
    }
  ],
  "alice.smith": [
    {
        "resource": "report",
        "action": "report.run",
        "permission": "ALLOW"
    },
    {
        "resource": "instance",
        "action": "instance.hold",
        "permission": "ALLOW"
    }
  ]
}

• Granting access to all users to execute all the commands.

{
  "*": [
    {
        "resource": "*",
        "action": "*",
        "permission": "ALLOW"
    }
  ]
}

• Granting access to all users to execute all the commands but forbid a user with user with email "john.doe" to run reports.

{
  "john.doe": [
    {
        "resource": "report",
        "action": "report.run",
        "permission": "DENY"
    }
  ],
  "*": [
    {
        "resource": "*",
        "action": "*",
        "permission": "ALLOW"
    }
  ]
}

Initialize Channel Participants

At this point a new Slack Application should have been configured, an empty private Slack channel, and a Slack Bot task up and running (if this is not the case, please look for the root cause in the extension logs, after enabling Debug log level for the task). In Slack Bot task, an ACL list with the desired user permissions should have been set up also.

What is left for the UAC Slack Bot to be accessible to the users is to:

1. Invite the corresponding Slack users to the private channel.
2. Invite the UAC Slack Bot to the channel by just mentioning it (just type @uacbot and press enter).

UAC Slack Bot after being successfully invited to the channel will provide a greeting message for all the users to see. From this point on, users will have access to UAC Slack Bot based on the ACL configuration completed in previous step.

Task Examples

Example of UE Slack Bot Universal Task for starting the execution of the Slack Bot.

Task Output

Since this universal task is designed to operate endlessly, task output is provided only in case of an error in initialization phase or during task instance cancel.

• In case of an initialization error the extension produces the following output with error code equals to 20 and invocation fields equal to the extension input.

{
    "exit_code": 20,
    "status_description": "Rule report.query found in ACL is invalid. Please provide a valid rule",
    "invocation": {
        "extension": "ue-slack-bot",
        "version": "1.0.0",
        "fields": {
            "slack_bot_token": "****",
            "slack_app_token": "****",
            "slack_channel_id": "C01DL0HDZV0",
            "acl_configuration": "/home/ue-dev/lindev71p377/data/tmp/a32c170f-fd15-4380-b675-e7dde8d6a10a",
            "uc_url": "http://ue-uac-dev.stonebranch.org/uc",
            "uc_creds_username": "****",
            "uc_creds_password": "****",
            "uc_timeout": 20,
            "auditing": true
        }
    }
}

Output Only Fields

The output only fields for this Universal Extension provide operational information of the Slack Bot and are described below.

STDOUT and STDERR

STDOUT and STDERR provide additional information to the user. The populated content can be changed in future versions of this extension without notice. Backward compatibility is not guaranteed.

In STDOUT the application also prints auditing logs, if the respective input field checkbox is selected. One example audit log entry for the user "john.doe@company.com" running the command :

<datetime> AUDIT - user:john.doe, channel:C049CHU74P9, command:Get Agents Status, parameters:['groupby:"operating system"'], result: SUCCESS

Available Commands

All the available commands can be executed in two different ways, through Slack's popup interface or directly as a command with parameters. Moreover, all commands require the /uacbot prefix followed by the command name to be recognized as commands by Slack.

In case a user wants to run a command directly the accepted input format is the following:

/uacbot <command_name> parameter_1:'value' parameter_2:'value'

If a command is to be executed through popup interface, then the accepted format is the following

/uacbot  <command_name>

Rerun Task Instance

Rerun Task Instance command lets a user to re-run a task instance in Universal Controller. This is possible only if the task instance is not deleted. In case it belongs to a workflow, the workflow should not be deleted, too.

To qualify for re-run, a task instance status must be in one of the following: Success, Start Failure, Failed, Cancelled, Finished.

Command Usage

Command Name: rerun task instance

Command Examples

/uacbot rerun task instance id:'<some_valid_id>' 

Hold Task Instance

Hold Task Instance command lets a user to hold a task instance in the Universal Controller. If a Workflow is put on Hold and has not yet started, the Workflow and all the task instances in it are put on Hold state.

If the command is triggered for a Workflow when it is in Running status, all the task instances within the Workflow that have not yet started are put on Hold; however, the Workflow itself does not go to Hold status because it already has started.

Command Usage

Command Name: hold task instance

Command Examples

/uacbot hold task instance id:'<some_valid_id>' 

Force Finish/Cancel Task Instance

The Force Finish/Cancel command cancels a task instance and puts it into Finished status, regardless of what the task instance is doing. The command can Force Finish/Cancel a task instance while it is in any of the following statuses: Queued, Action Required, Started, Running. If the task instance is part of a Workflow, it also can Force Finish/Cancel the task instance if the task instance is re-run after the Workflow completes.

Command Usage

Command Name: force finish task instance

Command Examples

/uacbot force finish task instance id:'<some_valid_id>' halt: 'true'   

Get Task Instances

The Get Task Instance command lets a user to list all task instances that match certain parameters and retrieve information about their state, including their status, or when they were last updated.

Command Usage

Command Name: get task instances

Command Examples

• Fetch the latest task instances that contain "slack" in their name of type Linux with statuses Finish and Success that have been last updated in the past two days.

/uacbot get task instances name:'slack*' type:'linux/unix' status:'Success, Finished' lastupdate:'2d' show:'latest'  

Get Late Tasks

Get Late Tasks command enables the user to list task instances that have been configured with the "late" parameter in the Universal Controller.

• Early Finish filters all the task instances that have been finished earlier than expected.
• Late Finish filters all the task instances that have been finished later than expected.
• Late Start filters all the task instances that have been started later than expected.

This command comes in handy for monitoring tasks that are to be run with a trigger if they are part of a Workflow.

Command Usage

Command Name: get late tasks

Command Examples

• Fetch task instances that contain "slack" in their name that have been last updated in the past two days and have late type of either late start, late finish or early finish.

/uacbot get late tasks name:'slack*' ' lastupdate:'2d' type:'all'

Get Task Instance Output

Get Task Instance Output command is used to retrieve the output of a specific task instance.

Command Usage

Command Name: get task instance output

Command Examples

• Fetch last twenty lines of the newest active instance that matches the name slack-bot.

/uacbot get task instance output instance:'<slack-bot>' criteria:'Newest Active Instance' length:'20' fetchfrom:"end"  

Get Task Instance Info

Get Task Instance Info command is used to retrieve general information about a task instance including its id, name, agents acquired, triggered by, start time, end time, status, status description and exit code.

Command Usage

Command Name: get task instance info

Command Examples

/uacbot get task instance info instance:'<slack-bot>' criteria:'Oldest Instance'

Schedule Ad hoc Run

Schedule Ad hoc run command lets user to schedule the execution of a task instance or a Workflow, by creating a trigger and binding it to a specific task name.

Command Usage

Command Name: schedule ad hoc run

Command Examples

/uacbot schedule ad hoc run triggername:'<valid_trigger_name>' taskname:'<valid_task_name>' date:'YYY-mm-dd' time:'HH:MM' timezone: 'UTC'

Get Agents

Get Agents commands can be used to list all the available agents of the Universal Controller and gain visual information about their state.

Command Usage

Command Name: get agents

Command Examples

• List and groupby os all active, non-suspended agents which run linux operating system and 7.2 UC version with a specified name.

/uacbot get agents name:'<valid_agent_name>' os:'Linux' version:'7.2.0.0' status:'active' suspended:'false' groupby:'os' 

Run Report

Run Report command provides the capability to run an already existing report in Universal Controller and retrieve the output file in your Slack workspace.

Command Usage

Command Name: get agents

Command Examples

/uacbot get agents name:'<valid_report_name>' 

Integration Modifications

Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.

• Python code modifications should not be done.
• Template Modifications
  • General Section
    • "Name", "Extension", "Variable Prefix", "Icon" should not be changed.
  • Universal Template Details Section
    • "Template Type", "Agent Type", "Send Extension Variables", "Always Cancel on Force Finish" should not be changed.
  • Result Processing Defaults Section
    • Success and Failure Exit codes should not be changed.
    • Success and Failure Output processing should not be changed.
  • Fields Restriction Section
    • Default configured values should not be changed.

Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.

Document References

This document references the following documents.

Changelog

ue-slack-bot-1.0.2 (2022-12-15)

• Bugfix: Extension is available for 7.1 and 7.2 UC versions'

ue-slack-bot-1.0.1 (2022-11-22)

• Bugfix: Ignore trailing slash character in field 'Universal Controller URL'

ue-slack-bot-1.0.0 (2022-11-21)

• Added: Initial Version