Slack connector

The Slack connector is used to integrate with the Slack web API and REST time messaging API to create Slack channels and send messages to channels or users.

The Slack connector is displayed on the process diagram with the Slack logo.

Important: The Slack connector requires a Slack account to use. This account is separate to the Alfresco hosted environment and should be created and managed by customers.

The actions that can be executed using the Slack connector are:

Send message

The SEND_MESSAGE action is used by the Slack connector to send a message to a user or channel.

The input parameters to send a message in Slack are:

ParameterTypeDescription
channelIdStringRequires one. The channel ID to send the message to.
channelNameStringRequires one. The name of the channel to send the message to.
userIdStringRequires one. The user ID of the message recipient.
userEmailStringRequires one. The email address of the message recipient.
textStringRequired. The contents of the message. The message supports Freemarker syntax, for example ${fullName.lastName} can be used from the metadata parameter to include variables.
metadataJSONOptional. Metadata to be used by the text parameter to include process variables in a message.
requestResponseStringOptional. Set to no and a response will be sent back to the process immediately after the message is sent. Set to any and a response will be sent back to the process only after a reply is received in the same channel. Set to thread and a response will be sent back to the process only after a reply is received in a thread.

The output parameters from sending a message in Slack are:

ParameterTypeDescription
messageStringOptional. The message received in the channel or thread if the input parameter requestResponse was set to any or thread.

Create channel

The CREATE_CHANNEL action is used by the Slack connector to create a new public or private channel in Slack.

The input parameters to create a channel in Slack are:

ParameterTypeDescription
channelNameStringRequired. The name of the channel to be created.
channelTypeStringRequired. Set whether the channel is public or private.
membersStringRequired. A list of members that will be invited to join the new channel using Slack IDs or email addresses.

The output parameters from creating a channel in Slack are:

ParameterTypeDescription
slackResultJSONOptional. An object containing the details of the newly created channel.

An example of a channel creation in the slackResult is:

{
  "ok":true,
  "channel":{
    "id":"CFWSKMFR6",
    "name":"my_channel",
    "is_channel":true,
    "created":1549985348,
    "is_archived":false,
    "is_general":false,
    "unlinked":0,
    "creator":"UFX13DBJM",
    "name_normalized":"my_channel",
    "is_shared":false,
    "is_org_shared":false,
    "is_member":true,
    "is_private":false,
    "is_mpim":false,
    "last_read":"0000000000.000000",
    "latest":null,
    "unread_count":0,
    "unread_count_display":0,
    "members":[
      "UFX13DBJM",
      "DFWSKM0HH"
    ],
    "topic":{
      "value":"",
      "creator":"",
      "last_set":0
    },
    "purpose":{
      "value":"",
      "creator":"",
      "last_set":0
    },
    "previous_names":[],
    "priority":0
  }
}

Configuration

The Slack connector requires a Slack application and a Slack bot in order to function. The application and bot need to be configured correctly.

  1. Use the Slack website to create an application.

    Note: You will need to be logged in as a workspace administrator to create an application.

  2. Use the following URL to create a bot in the application you created: https://api.slack.com/apps/<app_id>/bots.

  3. Use the following URL to configure the scope and permissions of the application and bot: https://api.slack.com/apps/<app_id>/oauth.

    The required scope and permissions are:

    • app_mentions:read
    • channels:read
    • channels:manage
    • groups:read
    • groups:write
    • mpim:read
    • mpim:write
    • users:read
    • users:read.email
    • chat:write
    • chat:write.public
    • im:read
    • im:write
  4. Use the following URL to obtain the Slack bot token and signing secret: https://api.slack.com/apps/<app_id>/oauth.

Configuration parameters

The configuration parameters for the Slack connector are:

ParameterDescription
SLACK_BOT_TOKENRequired. The Slack bot user token obtained from configuring Slack, beginning xoxb-.
SLACK_SIGNING_SECRETRequired. The Slack signing secret obtained from the Basic Information page in Slack.

Event subscription

To use Slack as a trigger the Slack bot needs to subscribe to events.

  1. Use the following URL to configure the events: https://api.slack.com/apps/<app_id>/event-subscriptions.

  2. Set the Request URL for Slack to post HTTP requests to as: https://<cluster-name>/<application-name>/connector/<connector-name>/slack/events. Where:

    • cluster-name is the name of the cluster running Process Automation.
    • application-name is the name of the application the trigger is configured for.
    • connector-name is the name of the Slack connector instance in the application.
  3. Subscribe the Slack bot user to the following events:

    • app_mention
    • message.channels
    • message.groups
    • message.im
    • message.npim

Errors

The possible errors that can be handled by the Slack connector are:

ErrorDescription
MISSING_INPUTA mandatory input variable was not provided.
INVALID_INPUTThe input variable has an invalid type.
INVALID_RESULT_FORMATThe REST service result payload cannot be parsed.
USER_NOT_FOUNDUser is not found.
CHANNEL_NOT_FOUNDChannel is not found.
INVALID_REQUESTA null response is received while sending message.
INVALID_CHANNELThere is a problem with the channel.
MSG_TOO_LONGMessage text is too long.
FATAL_ERRORThe server could not complete the operation without encountering a catastrophic error.
UNKNOWN_ERRORUnexpected runtime error.
UNAUTHORIZEDThe request has not been applied because it lacks valid authentication.
FORBIDDENThe server understood the request but refuses to authorize it.
REQUEST_TIMEOUTThe server would like to shut down this unused connection.

© 2023 Alfresco Software, Inc. All Rights Reserved.