Configuring Slack applications for integration

IBM Cloud Pak® for AIOps supports a direct integration to your enterprise Slack installation.

Prerequisites

The following requirements are necessary to setting up a Slack integration:

  • Slack

  • API authentication to your Slack instance

  • A valid certificate (not self-signed) for your publicly exposed Red Hat OpenShift Container Platform route

  • If you have an offline (air-gapped) deployment of IBM Cloud Pak for AIOps , then you must have the details of a proxy server that you have set up for IBM Cloud Pak for AIOps to connect to Slack.

  • If you have an online deployment of IBM Cloud Pak for AIOps, network connectivity between the IBM Cloud Pak for AIOps instance and the Slack Enterprise edition instance.

    Note: If a direct endpoint cannot be established, you can use Secure Tunnel to securely tunnel between the two. For more information about Secure Tunnel, see Using Secure Tunnel for ChatOps.

Creating your Slack app

Complete the following steps to configure your Slack integration.

Note: Be careful which workspace that you use. You must either be a workspace administrator – or wait for approval from the workspace administrator – when you interact with some of Slack's administrative settings.

Important: IBM Cloud Pak for AIOps requires two Slack channels, one for proactive notifications and one for reactive notifications. You must configure two channels, one for each purpose.

Configuring your Slack app

  1. After you create your Slack app from the Slack API page, click the name of the app that you created, then click Features > App Manifest.

  2. Replace the contents of the manifest file (YAML) with the following (make sure you update the <app name> to your own app name) and save the changes.

             _metadata:
                major_version: 1
                minor_version: 1
             display_information:
                name: <app name>
             features:
                bot_user:
                      display_name: <app name>
                      always_online: false
             oauth_config:
                scopes:
                   user:
                      - channels:history
                      - chat:write
                      - groups:history
                   bot:
                      - app_mentions:read
                      - channels:manage
                      - channels:read
                      - chat:write
                      - files:write
                      - groups:read
                      - groups:write
                      - users:read
                      - users:read.email
                      - commands
                      - mpim:read
             settings:
                org_deploy_enabled: false
    
    

    This manifest adds the following bot token to your application:

    • app_mentions:read
    • channels:manage
    • channels:read
    • chat:write
    • files:write
    • groups:read
    • groups:write
    • users:read
    • users:read.email
    • commands

    To validate your changes were saved, you can navigate to Features > OAuth, & Permissions and review the Bot Scopes section.

  3. Go to the Settings > Install App page and go to the OAuth Tokens for Your Workspace section.

    1. Click Install to Workspace.
    2. Review the information and click Allow. Note that you must reinstall your application every time you change the scope.
    3. Record the Bot User OAuth Token found in the OAuth Tokens for Your Workspace section.
  4. On the Settings > Basic information page, go to select App Credentials section and record the Signing Secret value.

  5. Using your Slack desktop application, create and name two Slack channels under your Slack workspace:

    • Proactive channel (for example, aiops-proactive)
    • Reactive channel (for example, aiops-reactive)

    Retrieve the channel ID for both channels. Right-click the channel name, then click Copy link to get the web URL link. The last part of the link is the channel ID (Such as C020EA7QWLS). You need these values in following steps.

  6. Log in to the IBM Cloud Pak for AIOps console.

  7. From the main navigation menu (four horizontal bars in the upper-left), expand Define, and click Integrations. On the Integrations page, click Add integration.

  8. Select ChatOps in the Category list (on the left), and click the Slack tile. On the side-panel, review the instructions and when ready to continue, click Next.

  9. Enter the following information on the Slack integration definition page:

    • Name: The display name of your integration (Such as Slack Chat Ops)
    • Description: An optional description for the integration.
    • Signing secret: The signing secret generated for the client. You can copy this value from the App Credentials section inside the Basic Information page of the Slack application.
    • Bot token: This is the token value for the bot that you recorded earlier. You can copy this value from the Settings > Install App page section in the Slack application.
    • Language ID: A dropdown list offering various different languages options for the integration.
    • Proactive channel: The channel ID for the channel that you want to use for notifications. You recorded this value in step 5.
    • Reactive channel: The channel ID for the channel that you want to use for incidents and alerts. You recorded this value in step 5.

    On the optional Configure Proxy page, toggle the Enable Proxy selection to on if you require a proxy server to connect to Slack, and enter the following information:

    • Proxy URL: The hostname of your proxy server
    • Proxy Port: The port number
    • Proxy username: The proxy server username
    • Proxy password: The proxy server password
  10. Test your Slack integration integration by clicking Test connection. This test verifies that IBM Cloud Pak for AIOps can communicate with Slack (though it does_not_verify if Slack can communicate with IBM Cloud Pak for AIOps). If the test fails, review all preceding steps described previously.

  11. Click Done.

  12. From the Slack application page, go to Features > App Manifest. Complete the following updates to the contents of the manifest YAML.

    • Under the settings element, add the following child items. Ensure that you update the placeholders. The <request URL> value is the URL that you get from the console on the Integrations. For example, https://myibm.com/aiops/aimanager/instances/1647499820476511/api/slack/events. You can also get the value from the secure tunnel section Using Secure Tunnel for ChatOps.

            event_subscriptions:
               request_url: <request url>
               bot_events:
                  - app_mention
                  - member_joined_channel
            interactivity:
                  is_enabled: true
                  request_url: <request url>
      

      event_subscriptions and interactivity are at the same level in the configuration as the org_deploy_enabled and socket_mode_enabled elements.

    • Under the features element, add the following child item. Ensure that you update the placeholders.

            slash_commands:
               - command: /welcome
                  url: <request url>
                  description: Welcome to IBM Cloud Pak for AIOps
                  should_escape: false
      

      slash_commands is at the same level in the configuration as the bot_user element.

  13. Verify the Request URL. Click Click here to verify link. If this URL verification is not successful, review all preceding steps and ensure that the Request URL is correct.

  14. Using the Red Hat OpenShift command line, run the following commands for the changes to take effect:

    oc project <namespace>
    

    Where <namespace> is the namespace where IBM Cloud Pak for AIOps is installed.

    oc set env deployment/$(oc get deploy -l app.kubernetes.io/component=chatops-slack-integrator -o jsonpath='{.items[*].metadata.name }') SLACK_WELCOME_COMMAND_NAME=/welcome
    
  15. After the Slack application is configured, it must be reinstalled, as several permissions changed. Go to Settings > Install App page and click Reinstall to Workspace. On the subsequent page, click Allow.

  16. Add the Slack application to both channels that you created earlier, such as your proactive and reactive channels.

    • Using your Slack desktop application, open the Details view of the channel, click Integration > Add apps, and add the Slack application to the channel. (The channel's Details view is found by clicking the small down-arrow next to the channel's name in the Slack UI.)
    • After you add the application to the channel, send the message /welcome to the channel. As a response, you can get a welcome message posted to the channel, which confirms the integration was made successfully.

You can now use Slack as your ChatOps interface. For more information about using the ChatOps interface, see ChatOps insight management.