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/
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.
Template Name | Extension Name | Extension Version |
---|---|---|
Slack Bot | ue-slack-bot | 1.0.2 |
Refer to Changelog for version history information.
This integration requires a Universal Agent and a Python runtime to execute the Universal Task.
Requires Python 3.7.0 or higher. Tested with the Universal Agent bundled Python distribution.
Both Windows and Linux agents are supported.
Universal Controller Version 7.1.0.0 and later.
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.
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:
Area of Interest | Available Commands |
---|---|
Tasks and Instances | Rerun a Task Instance. |
Tasks and Instances | Hold a Task Instance. |
Tasks and Instances | Force Finish/Cancel a Task Instance. |
Tasks and Instances | Show Task Instances for specific filter parameters. |
Tasks and Instances | Show Late Task Instance with certain parameters. |
Tasks and Instances | Retrieve the output of a Task Instance. |
Tasks and Instances | Retrieve detailed information about a task instance. |
Tasks and Instances | Schedule an ad-hoc run of a task instance by enabling a trigger. |
Agents | Show the status of all available Universal agents |
Reports | Show a Report. |
Additionally, this extension provides the following features:
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.
To use the Universal Template, the following steps need to be followed:
This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.
To import the Universal Template into your Controller, follow the instructions here.
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.
In order to use the Slack Bot extension, it is required to:
Those steps are described in detail in the following sections.
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:
The first configuration needed in this new application is to create an App-Level token, from the "Basic Information" page:
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.
Navigate to "App Manifest" section (navigation bar on the left) and follow the steps:
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:
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:
After creating the new Slack Application, using again a Slack admin account, follow the steps:
For a new Universal Task, create a new task, and enter the required input fields.
The input fields for this Universal Extension are described below.
Field | Input type | Default value | Type | Description |
---|---|---|---|---|
Slack Bot token | Required | - | Credentials | The Slack bot token as obtained from Slack App. It is used to connect Slack Application with a Workspace. The Credentials definition should be as follows:
|
Slack App token | Required | - | Credentials | The Slack app token obtained from Slack App. It is used to connect the Slack Bot with the corresponding Slack App. The Credentials definition should be as follows:
|
Slack Channel ID | Required | - | Text | The Slack channel ID that the bot will connect. to. |
ACL | Required | - | Script | The JSON script that contains the ACL rules for your Slack. users. |
Universal Controller URL | Required | - | Text | The URL of the target UC (e.g. http://ue.stonebranch.org:8080/uc). |
Universal Controller Credentials | Required | - | Credentials | This extension uses RESTful Web Services API as a client, and in this field the corresponding username & password should be provided. This user should have Web Service Access enabled (directly or through System Default). It is strongly advised not to reuse admin or any existing user but create a new one used only for this specific integration. The Universal Controller Credentials definition should be as follows:
|
UC REST API Timeout | Required | 20 | Text | The timeout (in seconds) that the Slack Bot will wait for UC to respond. If the UC won't respond in the specified time limit Slack will display a corresponding error to the user. |
Auditing | Optional | True | Checkbox | A variable that if selected the bot will provide auditing logs. |
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.
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.
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.
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:
Key | Description |
---|---|
resource | Whether a command is related to instances, agents or reports. Can be equal to "*" to refer to all available resources. |
action | Available actions that can be performed in a resource. Can be equal to "*" to refer to all available resources. |
permission | Whether the permission of the combination of specified action and resource is allowed or forbidden. |
ACL Rules to Slack Command Mapping
Command | Resource | Action |
---|---|---|
rerun task instance | instance | instance.rerun |
hold task instance | instance | instance.hold |
force finish task instance | instance | instance.finish |
schedule ad hoc run | instance | instance.schedule |
get task instances | instance | instance.query |
get late tasks | instance | instance.query |
get task instance output | instance | instance.query |
get task instance info | instance | instance.query |
get agents | agent | agent.query |
run report | report | report.run |
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.
{
"john.doe": [
{
"resource": "instance",
"action": "instance.rerun",
"permission": "ALLOW"
}
]
}
{
"alice.smith": [
{
"resource": "instance",
"action": "instance.rerun",
"permission": "ALLOW"
},
{
"resource": "agent",
"action": "agent.query",
"permission": "ALLOW"
}
]
}
{
"john.doe": [
{
"resource": "instance",
"action": "*",
"permission": "ALLOW"
}
],
"alice.smith": [
{
"resource": "report",
"action": "report.run",
"permission": "ALLOW"
},
{
"resource": "instance",
"action": "instance.hold",
"permission": "ALLOW"
}
]
}
{
"*": [
{
"resource": "*",
"action": "*",
"permission": "ALLOW"
}
]
}
{
"john.doe": [
{
"resource": "report",
"action": "report.run",
"permission": "DENY"
}
],
"*": [
{
"resource": "*",
"action": "*",
"permission": "ALLOW"
}
]
}
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:
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.
Example of UE Slack Bot Universal Task for starting the execution of the Slack Bot.
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.
{
"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
}
}
}
The output only fields for this Universal Extension provide operational information of the Slack Bot and are described below.
Field | Type | Description |
---|---|---|
Total Requests Handled | Text | The total request slack bot has handled since starting |
Total Requests Succeeded | Text | The total request slack bot has returned a successful response |
Total Requests Failed | Text | The total request slack bot has returned a failed response |
Total Validation Errors | Text | The sum of validation errors that slack bot raised |
Total Permission Errors | Text | The sum of permission errors that slack bot raised |
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
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 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 Name: rerun task instance
Parameters | Description | Values and Constraints | Required | Default |
---|---|---|---|---|
id | sys_id used within the Universal Controller to identify this task instance | Same with Universal Controller | True | - |
/uacbot rerun task instance id:'<some_valid_id>'
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 Name: hold task instance
Parameters | Description | Values and Constraints | Required | Default |
---|---|---|---|---|
id | sys_id used within the Universal Controller to identify this task instance | Same with Universal Controller | True | - |
/uacbot hold task instance id:'<some_valid_id>'
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 Name: force finish task instance
Parameters | Description | Values and Constraints | Required | Default |
---|---|---|---|---|
id | The identifier of the task instance to be force finished or canceled. | Same with Universal Controller | True | - |
halt | If set to True it prevents successor task instances of the specified task instance id in a Workflow from being run. | True / False | False | False |
cancel | If set to True cancels the task instances. | True / False | False | False |
/uacbot force finish task instance id:'<some_valid_id>' halt: 'true'
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 Name: get task instances
Parameters | Description | Values and Constraints | Required | Default |
---|---|---|---|---|
name | The name of the task instances. This field also accepts wildcards "?" or "*". | Max 255 length string (case insensitive). | False | - |
type | Filter the tasks being queried, by task type attribute. | Valid Universal Controller task types (case insensitive). | False | - |
status | Filter the tasks being queried, by task status attribute. | Valid Universal Controller statuses (case insensitive). | False | - |
lastupdated | Filter instances that have been updated in the last X hours/minutes. | Timestamps in hours or minutes format, e.g 1h, 20m. | False | - |
show | Filter to fetch all instances or only the last updated instances that match the rest of the input fields. | Latest / All | False | All |
/uacbot get task instances name:'slack*' type:'linux/unix' status:'Success, Finished' lastupdate:'2d' show:'latest'
Get Late Tasks command enables the user to list task instances that have been configured with the "late" parameter in the Universal Controller.
This command comes in handy for monitoring tasks that are to be run with a trigger if they are part of a Workflow.
Command Name: get late tasks
Parameters | Description | Values and Constraints | Required | Default |
---|---|---|---|---|
name | The name of the task instances. This field also accepts wildcards "?" or "*". | Max 255 length string (case insensitive). | True | - |
lastupdated | Filter instances that have been updated in the last X hours/minutes. | Timestamps in day, month or minutes format, e.g. 1h, 20m. | False | 24h |
type | Filter tasks based on available late time options. | Late start / Late finish / Early finish / All | False | Late Start |
/uacbot get late tasks name:'slack*' ' lastupdate:'2d' type:'all'
Get Task Instance Output command is used to retrieve the output of a specific task instance.
Command Name: get task instance output
Parameters | Description | Values and Constraints | Required | Default |
---|---|---|---|---|
instance | The id of the task instance to be retrieved. | Max 255 length string (case insensitive) or valid Universal Controller sys_id format. | True | - |
outputtype | Retrieve instance output by type. | Long list of values, including: STDOUT, STDERR, EXTENSION. Full list of values is available in popup drop-down list. | False | STDOUT |
length | Number of lines to fetch from the outputtype. | Positive integer | False | 20 |
fetchfrom | Fetch the output logs from the start or from the end. | Start / End | False | Start |
/uacbot get task instance output instance:'<slack-bot>' criteria:'Newest Active Instance' length:'20' fetchfrom:"end"
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 Name: get task instance info
Parameters | Description | Values and Constraints | Required | Default |
---|---|---|---|---|
instance | The name or the id of the task instance to be retrieved. | Max 255 length string (case insensitive) or valid Universal Controller sys_id format. | True | - |
criteria | The last updated criteria of the task instance. Mandatory when the query is made with task name. | Newest Instance, Oldest Instance, Newest Active Instance, Oldest Active Instance. | False | Newest Instance |
/uacbot get task instance info instance:'<slack-bot>' criteria:'Oldest Instance'
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 Name: schedule ad hoc run
Parameters | Description | Values and Constraints | Required | Default |
---|---|---|---|---|
triggername | The name of the triggered to be created. | Max 255 length string (case insensitive) | True | - |
taskname | The task name to be binded with the created trigger triggername. | Max 255 length string (case insensitive) | True | - |
date | The date which the taskname will be run. | YYYY-mm-dd format | True | Current date |
time | The date which the taskname will be run. In combination with date filed it must be after current time. | HH:MM format | True | Current time + 1 minutes |
timezone | the timezone of the specified time. | UTC-12 to UTC+14 | True | UTC |
/uacbot schedule ad hoc run triggername:'<valid_trigger_name>' taskname:'<valid_task_name>' date:'YYY-mm-dd' time:'HH:MM' timezone: 'UTC'
Get Agents commands can be used to list all the available agents of the Universal Controller and gain visual information about their state.
Command Name: get agents
Parameters | Description | Values and Constraints | Required | Default |
---|---|---|---|---|
name | The name of the agent to be retrieved. This field also accepts wildcards | Max 255 length string (case insensitive) | False | - |
os | Filter based on the operating system the agent is based on. | Windows, Linux, z/OS (case insensitive) | False | - |
version | Filter based on agent version. | Valid Universal Controller version format | False | - |
status | Filter based on agent status. | Active / Offline (case insensitive) | False | - |
suspended | Filter agents that are temporarily suspended. | True/False | False | - |
groupby | Filter to control the grouping of the output message. | A value of all previous available fields. | False | Operating System |
/uacbot get agents name:'<valid_agent_name>' os:'Linux' version:'7.2.0.0' status:'active' suspended:'false' groupby:'os'
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 Name: get agents
Parameters | Description | Values and Constraints | Required | Default |
---|---|---|---|---|
name | The name of the report to be retrieved. | Max 255 length string (case insensitive) | True | - |
/uacbot get agents name:'<valid_report_name>'
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.
Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.
This document references the following documents.
Document Link | Description |
---|---|
Universal Templates | User documentation for creating, working with and understanding Universal Templates and Integrations. |
Universal Tasks | User documentation for creating Universal Tasks in the Universal Controller user interface. |
Slack Bot API | User guide for Slack Bot API. |
Bugfix
: Extension is available for 7.1 and 7.2 UC versions'
Bugfix
: Ignore trailing slash character in field 'Universal Controller URL'Added
: Initial Version