Skip to content

setup-guide.md

Latest commit

 

History

History
165 lines (112 loc) · 4.4 KB

setup-guide.md

File metadata and controls

165 lines (112 loc) · 4.4 KB
Raw

Enterprise Grid Setup Guide

Complete step-by-step guide for setting up Slack Channel Manager with Slack Enterprise Grid, including screenshots.

Prerequisites

  • Slack Enterprise Grid organization
  • Organization Admin permissions
  • Node.js 18+ installed

Automated Setup

Recommended: Use the guided setup wizard:

npm run setup

Choose "Create new app" and follow the interactive prompts.

Manual Setup with Screenshots

Step 1: Create Slack App

  1. Start the setup wizard:

    npm run setup

    Choose "Create new app" → "Yes" to open browser

  2. Create new app: Screenshot 1: Create App

    • Click "From scratch"

  3. App details: Screenshot 2: App Details

    • App Name: Slack Channel Manager Enterprise
    • Select any workspace in your Enterprise Grid
    • Click "Create App"

Step 2: Configure Bot Scopes

  1. App dashboard: Screenshot 3: App Dashboard

    • Note the sidebar options

  2. OAuth & Permissions: Screenshot 4: OAuth Page

    • Click "OAuth & Permissions" in sidebar

  3. Add bot scopes: Screenshot 5: Bot Scopes Add these to "Bot Token Scopes":

    • channels:read
    • channels:history
    • channels:manage
    • groups:read
    • groups:history
    • groups:write

Step 3: Configure OAuth Settings

  1. Add redirect URL: Screenshot 6: Redirect URLs
    • In "Redirect URLs" section
    • Add: https://slack.com/oauth/callback
    • Click "Save URLs"

Step 4: Enable Enterprise Grid Distribution

  1. Manage Distribution: Screenshot 8: Manage Distribution

    • Click "Manage Distribution" in sidebar

  2. Enable org-wide installation: Screenshot 9: Org-Wide Installation

    • Enable "Org-Wide App Installation"

  3. Complete distribution requirements: Screenshot 11: Distribution Requirements

    • Complete any required sections
    • You can skip "Activate Public Distribution" for internal use

Step 5: Install to Organization

  1. Return to OAuth & Permissions: Screenshot 12: Install Options

    • Should now see "Install to Organization" button

  2. Install to organization:

    • Click "Install to Organization" (NOT workspace)

  3. Authorize the app: Screenshot 14: Authorization

    • Review permissions
    • Click "Allow"

Step 6: Complete Setup

  1. Copy bot token: Screenshot 15: Bot Token

    • Copy the "Bot User OAuth Token" (starts with xoxb-)

  2. Paste in setup wizard:

    • Return to terminal and paste token
    • Complete workspace selection

  3. First test run:

    • Run npm start to test

Verification Checklist

✅ App created with correct name
✅ Bot scopes added (not user scopes)
✅ Redirect URL configured
✅ Org-wide installation enabled
✅ Installed to organization (not workspace)
✅ Bot token obtained and configured
✅ Multiple workspaces discovered
✅ Test run shows channel analysis

Troubleshooting

"Invalid client_id parameter"

  • Ensure redirect URL is set correctly
  • Try uninstalling and reinstalling the app

"no_bot_scopes_requested"

  • Make sure scopes are added to "Bot Token Scopes" (not "User Token Scopes")

"App not showing in other workspaces"

  • Verify organization-level installation (not workspace-level)
  • Check that org-wide installation is enabled

"not_in_channel" warnings

  • Normal behavior for private channels
  • Tool uses conservative rules for inaccessible channels

Screenshots

All setup screenshots are stored in docs/screenshots/ and referenced in this guide.

To add your own screenshots:

  1. Save screenshots with descriptive names
  2. Place in docs/screenshots/ folder
  3. Update this guide with references
  4. Use git add docs/screenshots/specific-file.png to include them

Next Steps

After successful setup:

  • Run channel analysis: npm start
  • Customize archiving rules: npm start -- --max-members-inactive 5
  • Add more workspaces: npm run setup → "Add/remove workspaces"