Slack Work Arrangement Integration Setup Guide

This guide will help you set up the Slack integration for tracking work-from-home arrangements via emoji reactions.

Overview

The work arrangement tracking system allows team members to indicate where they're working from (home, main office, or alternate office) by reacting to a daily Slack message with specific emojis. The system tracks quota usage (e.g., once per week for working from home) and provides an admin dashboard to view arrangements.

Features

• 📱 Track work locations via Slack emoji reactions
• 📊 Quota management (configurable limit per week)
• 📈 Admin dashboard to view arrangements and quota status
• 🔔 Real-time tracking via Slack webhooks
• 👥 Team-wide visibility

Setup Steps

1. Create a Slack App

1. Go to Slack API
2. Click Create New App → From scratch
3. Name your app (e.g., "Work Arrangement Tracker")
4. Select your workspace

2. Configure Bot Permissions

Navigate to OAuth & Permissions and add the following Bot Token Scopes:

• channels:history - Read messages in public channels
• reactions:read - View emoji reactions and their associated content
• users:read - View people in the workspace
• chat:write - Post messages

3. Enable Event Subscriptions

1. Go to Event Subscriptions

2. Enable Events: ON

3. Set Request URL to: https://your-domain.com/api/slack/events

   • Replace your-domain.com with your actual domain
   • Slack will verify the URL is working

4. Subscribe to the following bot events:

   • reaction_added - A member added an emoji reaction
   • reaction_removed (optional) - A member removed an emoji reaction

5. Click Save Changes

4. Install App to Workspace

1. Go to Install App
2. Click Install to Workspace
3. Review permissions and authorize
4. Copy the Bot User OAuth Token (starts with xoxb-)

5. Get Signing Secret

1. Go to Basic Information
2. Find App Credentials section
3. Copy the Signing Secret

6. Get Channel ID

1. Open Slack and navigate to the channel where daily messages will be posted
2. Right-click the channel name → View channel details
3. Scroll down to find the Channel ID
4. Or use the Slack API: https://api.slack.com/methods/conversations.list

7. Configure Environment Variables

Add the following to your .env.local file:

# Slack Work Arrangement Integration
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_SIGNING_SECRET=your-signing-secret-here
SLACK_CHANNEL_ID=C01234ABCDE

8. Initialize Slack Configuration

Use the API to configure the Slack integration:

curl -X POST https://your-domain.com/api/slack/config \
  -H "Content-Type: application/json" \
  -d '{
    "botToken": "xoxb-your-bot-token",
    "signingSecret": "your-signing-secret",
    "channelId": "C01234ABCDE",
    "dailyMessageTime": "09:00",
    "enabled": true,
    "emojiMapping": {
      "home": "🏠",
      "main_office": "🏢",
      "alternate_office": "🏛️"
    },
    "quotaSettings": {
      "homeQuotaPerWeek": 1,
      "weekStartsOn": 1
    },
    "updatedBy": "admin"
  }'

9. Map People to Slack Users

Update your people (staff) records in Firestore to include their Slack user IDs:

// Get Slack user ID from their profile or API
// Update person document (people collection)
await db.collection('people').doc(personId).update({
  slackUserId: 'U01234ABCDE'
});

You can find Slack user IDs:

• From their profile: Click profile → More → Copy member ID
• Via API: https://api.slack.com/methods/users.list

Usage

Daily Workflow

1. Post Daily Message: Every morning, post a message in your configured channel asking team members where they'll be working

   Example message:

   Good morning team! 🌅
   
   Where are you working from today?
   React with:
   🏠 - Working from home
   🏢 - Main office
   🏛️ - Alternate office

2. Team Members React: Team members react to the message with the appropriate emoji

3. Automatic Tracking: The system automatically records their work arrangement and updates quota information

4. View Dashboard: Admins can view arrangements at /work-arrangements

Emoji Configuration

Default emojis (configurable):

• 🏠 (:house:) - Home
• 🏢 (:office:) - Main Office
• 🏛️ (:classical_building:) - Alternate Office

You can customize these emojis in the Slack configuration.

Quota Settings

• homeQuotaPerWeek: Number of times an engineer can work from home per week (default: 1)
• weekStartsOn: Day of week that starts the week (0 = Sunday, 1 = Monday, etc.)

When an engineer exceeds their quota, the system logs a warning (you can extend this to send Slack DMs).

Admin Dashboard

Access the dashboard at: /work-arrangements

Features:

• View Arrangements: See who's working where, filtered by today/week/month
• Quota Tracking: View quota usage and remaining quota for each engineer
• Statistics: Quick stats on total arrangements, home/office counts
• Real-time Updates: Click refresh to get latest data

Views:

1. Arrangements View:

   • Grouped by date
   • Shows engineer name, location, and timestamp
   • Filterable by period (today, week, month)

2. Quotas View:

   • Weekly quota status for all engineers
   • Color-coded status (over quota, at limit, remaining)
   • Breakdown by location type

API Endpoints

Webhook Endpoint

• POST /api/slack/events - Receives Slack events (reactions)

Configuration

• GET /api/slack/config - Get Slack configuration
• POST /api/slack/config - Set/update Slack configuration

Work Arrangements

• GET /api/work-arrangements - Get arrangements
  • Query params: period (today/week/month), engineerId

Quotas

• GET /api/work-arrangements/quotas - Get quota information
  • Query params: engineerId, week, year

Firestore Collections

The integration uses the following Firestore collections:

1. work-arrangements: Individual arrangement records

   • Stores location, date, engineer info, emoji used

2. work-arrangement-quotas: Weekly quota summaries

   • Aggregates arrangements by engineer and week
   • Tracks quota usage and remaining quota

3. system/slack-config: Slack configuration (singleton)

   • Stores tokens, channel ID, emoji mappings, quota settings

Security Considerations

1. Webhook Verification: All Slack requests are verified using the signing secret
2. Token Storage: Store sensitive tokens as environment variables
3. Request Timestamps: Requests older than 5 minutes are rejected
4. Access Control: Admin dashboard should be protected with authentication

Troubleshooting

Webhook Not Receiving Events

1. Verify the webhook URL is publicly accessible
2. Check Slack Event Subscriptions page for errors
3. Verify signing secret matches your environment variable
4. Check server logs for verification failures

Reactions Not Being Tracked

1. Ensure bot is added to the channel
2. Verify emoji mappings match configured emojis
3. Check if engineer has slackUserId mapped
4. Review server logs for processing errors

Quota Not Updating

1. Verify week calculation (ISO week vs calendar week)
2. Check quota settings (weekStartsOn)
3. Review Firestore quotas collection for data

Automated Daily Messages (Optional)

You can set up a scheduled function to post daily messages automatically:

Using Cloud Scheduler + Cloud Functions:

1. Create a Cloud Function that posts the daily message
2. Use Cloud Scheduler to trigger it daily at your configured time
3. Example function:

import { WebClient } from '@slack/web-api';

export async function postDailyMessage() {
  const client = new WebClient(process.env.SLACK_BOT_TOKEN);
  
  await client.chat.postMessage({
    channel: process.env.SLACK_CHANNEL_ID,
    text: 'Where are you working from today?',
    blocks: [
      {
        type: 'section',
        text: {
          type: 'mrkdwn',
          text: '*Good morning team!* 🌅\n\nWhere are you working from today?\nReact with:\n🏠 - Working from home\n🏢 - Main office\n🏛️ - Alternate office'
        }
      }
    ]
  });
}

Support

For issues or questions:

1. Check server logs for error messages
2. Verify all configuration steps are completed
3. Test webhook endpoint manually
4. Review Slack app configuration in API dashboard