AI Time Sheet Remainder BOT Workflow

1. Purpose

This workflow automates timesheet compliance monitoring and reminder notifications for Fleet Studio employees. It checks the previous week's timesheet submissions, identifies employees who haven't submitted their timesheets, and sends personalized Slack direct messages to remind them. The workflow runs automatically on Mondays to ensure timely timesheet submissions for the previous week.

2. Trigger

Type: Cron (Scheduled)

Details:

The workflow runs automatically on a weekly schedule.

Schedule Time:

• Every Monday at 12:00 (12:00 PM) - Asia/Kolkata timezone
• Every Monday at 15:00 (3:00 PM) - Asia/Kolkata timezone

Timezone: Asia/Kolkata

The workflow is triggered by a Schedule Trigger node that runs twice on Mondays to ensure employees receive reminders for submitting their previous week's timesheets.

3. Step-by-Step Process

Step 1: Schedule Trigger

What happens here: The workflow starts automatically every Monday at 12:00 PM and 3:00 PM (Asia/Kolkata timezone).

What input it uses: No input required - this is the entry point of the workflow.

Why this step is needed: Ensures the workflow runs consistently on Mondays to check and remind employees about the previous week's timesheet submissions, helping maintain compliance and timely data collection.

Step 2: Get many users (Parallel Path 1)

What happens here: Retrieves all users from the Slack workspace using Slack OAuth2 API to get user information including user IDs and names.

What input it uses: No input - fetches all Slack users directly from Slack API.

What output it produces: List of all Slack users with their user IDs, names, real names, and team information.

Why this step is needed: Provides the complete list of Slack users that will be matched with timesheet defaulters to enable direct messaging.

Slack API: OAuth2 authentication

Operation: GetAll users

Credentials: Fleetstudio Slack OAuth2 API (stored in n8n credentials)

How to Get OAuth Credentials:

Option 1: Direct Slack OAuth Setup (Standard Method)

1. Go to Slack API Apps
2. Click "Create New App" → "From scratch"
3. Enter app details:
   • App Name: Fleetstudio Slack Integration
   • Workspace: Select your Fleet Studio workspace
4. Navigate to OAuth & Permissions in the sidebar
5. Add the following User Token Scopes (Scopes → User Token Scopes):
   • chat:write - Send reminder messages
   • im:write - Open a direct message channel with a user
   • im:read - Verify DM channel IDs when sending messages
   • users:read - Identify users in Slack by their name
   • users:read.email - Identify users in Slack by their email
6. Scroll to OAuth Tokens for Your Workspace section
7. Click "Install to Workspace"
8. Review permissions and click "Allow"
9. Copy the OAuth Access Token (starts with xoxp-)
10. In n8n, create new Slack OAuth2 credentials:
    • Enter the OAuth Access Token
    • Save credentials as "Fleetstudio Slack OAuth2 API"

Option 2: Get OAuth Credentials from GCP Secret Manager

If the Slack OAuth credentials are stored in Google Cloud Platform (GCP) Secret Manager, follow these steps:

1. Access GCP Console:

   • Go to Google Cloud Platform Console
   • Select the appropriate project (e.g., fleetstudio-production)

2. Navigate to Secret Manager:

   • In the left sidebar, go to Security → Secret Manager
   • Or use the search bar to find "Secret Manager"

3. Locate the Slack OAuth Secret:

   • Look for a secret named something like:
     • slack-oauth-token
     • slack-oauth-credentials
     • fleetstudio-slack-oauth
   • Click on the secret name to open it

4. Retrieve the Secret Value:

   • Click on the latest version of the secret
   • Click "View Secret Value" button
   • Copy the secret value (this will be either:
     • An OAuth Access Token (starts with xoxp-)
     • Or JSON containing client_id and client_secret)

5. If you have Client ID and Client Secret:

   • Create a Slack app at Slack API Apps if not already created
   • Use the Client ID and Client Secret to generate an OAuth token
   • Follow the OAuth flow to get the access token

6. Configure in n8n:

   • In n8n, go to Credentials → Add Credential
   • Select Slack OAuth2 API
   • Enter the OAuth Access Token (from step 4 or 5)
   • Test the connection
   • Save credentials as "Fleetstudio Slack OAuth2 API"

Note: Ensure you have the necessary GCP permissions (secretmanager.secrets.get or Secret Manager Secret Accessor role) to access the secret.

Step 3: Time Sheet Login (Parallel Path 2)

What happens here: Authenticates with the timesheet backend system using service account credentials to obtain an authentication token.

What input it uses: Service account credentials stored securely in the workflow.

What output it produces: Authentication token that will be used for subsequent timesheet API calls.

Why this step is needed: Provides authenticated access to the timesheet system APIs, enabling retrieval of user data and timesheet submission status.

API Endpoint: https://timesheet-be.fleetstudio.com/api/user/login

Method: POST

Credentials:

• Email: fshackathon@fleetstudio.com
• Password: (stored securely in workflow configuration, not exposed in documentation)

Step 4: TimeSheet Defaulters List (Parallel Path 3)

What happens here: Retrieves the list of employees who haven't submitted their timesheets for the previous week from the timesheet monitoring system.

What input it uses: No input - calls API directly.

What output it produces: List of defaulters with user IDs, names, employment status, total days missed, and specific days without submission.

Why this step is needed: Identifies which employees need to be reminded about their missing timesheet submissions, enabling targeted notifications.

API Endpoint: https://timesheet-be.fleetstudio.com/api/timesheet-monitor/missing-by-day

Method: POST

Request Body: {"previousWeek": true}

Step 5: Get Time Sheet Users

What happens here: Retrieves all registered users from the timesheet system using the authentication token obtained from login.

What input it uses: Authentication token from Time Sheet Login.

What output it produces: Complete list of timesheet system users with their details including email, employee ID, employment status, and active status.

Why this step is needed: Provides user data from the timesheet system that will be matched with defaulters to get complete user information for notifications.

API Endpoint: https://timesheet-be.fleetstudio.com/api/user/getUsers

Method: GET

Authentication: Bearer token (from login response)

Step 6: Format Data

What happens here: Cleans and formats the timesheet user data, combining first and last names, normalizing email addresses, and extracting key fields.

What input it uses: Raw user data from timesheet system.

What output it produces: Formatted user data with:

• Full name (first name + last name)
• Normalized email (lowercase)
• Employee ID
• Employment status
• Timesheet user ID
• Active status

Why this step is needed: Standardizes the data format and ensures consistency for matching operations in subsequent steps.

Step 7: Flatten Data

What happens here: Extracts and flattens the defaulters list from the API response structure, creating individual items for each defaulter.

What input it uses: API response containing defaulters summary and week information.

What output it produces: Individual items for each defaulter containing:

• Timesheet user ID
• Name
• Employment status
• Total days missed
• Days with no submission (array with day names)
• Week information (start date, end date)

Why this step is needed: Transforms the nested API response into a flat structure that can be easily processed and matched with user data.

Step 8: GET Users DM ID

What happens here: Retrieves direct message (DM) channel IDs for all Slack users by calling Slack's conversations.list API. Creates a mapping of Slack user IDs to their DM channel IDs.

What input it uses: Slack users list from "Get many users" step.

What output it produces: Enriched user data with:

• Slack user ID
• DM channel ID (for sending direct messages)
• Email (constructed as name@fleetstudio.com)
• Real name
• Team ID

Why this step is needed: Enables sending direct messages to users by providing the necessary DM channel IDs. Only users with valid DM channels are included in the output.

Slack API: https://slack.com/api/conversations.list

Method: GET

Parameters: types: 'im' (direct message channels)

Authentication: Slack Bot Token

Bot Configuration:

• Bot Name: FS Timesheet Bot
• Required Permissions (Bot Token Scopes):
  • channels:read - View basic information about public channels
  • chat:write - Send messages as the bot
  • im:read - View basic information about direct messages
  • im:write - Start direct messages
  • users:read - View people in a workspace
  • users:read.email - View user email addresses

Note: Step 2 uses User Token Scopes (OAuth2) for retrieving user information, while Step 8 uses Bot Token Scopes for accessing DM channels and sending messages. Both require similar permissions but use different authentication methods.

How to Create the Slack Bot:

1. Go to Slack API Apps
2. Click "Create New App" → "From scratch"
3. Enter app details:
   • App Name: FS Timesheet Bot
   • Workspace: Select your Fleet Studio workspace
4. Navigate to OAuth & Permissions in the sidebar
5. Scroll to Scopes section and click "Add an OAuth Scope" under Bot Token Scopes
6. Add the following Bot Token Scopes one by one:
   • channels:read - View basic information about public channels
   • chat:write - Send messages as the bot
   • im:read - View basic information about direct messages
   • im:write - Start direct messages
   • users:read - View people in a workspace
   • users:read.email - View user email addresses
7. Scroll down to OAuth Tokens for Your Workspace section
8. Click "Install to Workspace" button
9. Review the requested permissions and click "Allow" to authorize
10. After installation, you'll see the Bot User OAuth Token (starts with xoxb-)
11. Copy the Bot User OAuth Token
12. In n8n, go to Credentials → Add Credential
13. Select Slack API credential type
14. Choose Bot Token as the authentication method
15. Paste the Bot User OAuth Token you copied
16. Test the connection to verify it works
17. Save credentials as "FS Timesheet Bot"

Note: Make sure all 6 permissions listed above are added before installing to workspace. The bot needs these permissions to read user information, access DM channels, and send direct messages.

Step 9: Map Time Sheet Defaulters with User Data

What happens here: Merges timesheet defaulter data with complete user information from the timesheet system by matching on timesheet user ID.

What input it uses:

• Formatted timesheet users (from Format Data)
• Flattened defaulters list (from Flatten Data)

What output it produces: Combined data with defaulter information enriched with user details (email, employee ID, etc.).

Why this step is needed: Combines defaulter status with complete user profile information, ensuring all necessary data is available for creating personalized reminder messages.

Merge Mode: Combine

Match Field: timeUserId

Step 10: Map Time Sheet Defaulters with Slack

What happens here: Merges the enriched defaulter data with Slack user information (including DM channel IDs) by matching on email addresses.

What input it uses:

• Enriched defaulter data (from previous merge)
• Slack users with DM channel IDs (from GET Users DM ID)

What output it produces: Complete data combining timesheet defaulter status, user profile, and Slack contact information ready for messaging.

Why this step is needed: Links timesheet defaulters with their Slack accounts, enabling direct message delivery with all necessary context.

Merge Mode: Combine

Match Field: email

Step 11: Message To Users

What happens here: Sends personalized Slack direct messages to each defaulter with customized messages based on how many days they missed. Messages are sent to their personal DM channels.

What input it uses: Complete user data with defaulter status, week information, and Slack DM channel ID.

What output it produces: Slack message delivery confirmation for each user.

Why this step is needed: Delivers timely reminders directly to employees who haven't submitted their timesheets, improving compliance and ensuring timesheet data is collected promptly.

Slack Channel: Direct message (using DM channel ID)

Message Logic:

• If all 5 days missed: "Hi [name]. Our system noticed you haven't submitted your timesheet for the week [startDate] - [endDate]. Please update it at the earliest."
• If some days missed: "Hi [name]. Our system noticed you haven't submitted your timesheet for [specific days] of the week [startDate] - [endDate]. Please update it at the earliest."
• Important Note: The workflow only processes employees who appear in the timesheet defaulters list. Employees who have submitted their timesheet for all days will not be in the defaulters list and therefore will not reach this step and will not receive any message (including any "thank you" message). Only employees with missing timesheet submissions receive reminder messages.

Message Format: Markdown enabled

Credentials: FS Timesheet Bot (Slack API stored in n8n credentials)

4. Workflow Logic Summary

The workflow executes the following sequence from start to finish:

1. Triggers automatically every Monday at 12:00 PM and 3:00 PM (Asia/Kolkata timezone)
2. Runs three parallel operations:
   • Path 1: Retrieves all Slack users from workspace
   • Path 2: Logs into timesheet system and gets all registered users
   • Path 3: Gets list of employees who haven't submitted timesheets for previous week
3. Formats timesheet user data (combines names, normalizes emails)
4. Flattens defaulter data (extracts individual defaulter records)
5. Retrieves Slack DM channel IDs for all users (enables direct messaging)
6. Merges defaulters with user data (matches on timesheet user ID)
7. Merges with Slack user data (matches on email to get DM channels)
8. Sends personalized Slack DMs to each defaulter with:
   • Customized message based on days missed
   • Week date range
   • Friendly reminder to submit timesheet

This automated process ensures employees receive timely reminders about missing timesheet submissions, helping maintain compliance and accurate time tracking for the organization.

5. Diagram / Screenshot

The workflow diagram shows the complete automation flow from schedule trigger through parallel data retrieval, data merging, and personalized Slack direct message delivery to timesheet defaulters.

6. Dependencies

This workflow depends on several backend services and third-party platforms to function properly.

Backend Server APIs

Timesheet Backend API

• Base URL: https://timesheet-be.fleetstudio.com
• Endpoints Used:
  • /api/user/login - User authentication
  • /api/user/getUsers - Get all registered users
  • /api/timesheet-monitor/missing-by-day - Get timesheet defaulters list
• Method: POST (login, missing-by-day), GET (getUsers)
• Purpose: Manages timesheet data, user information, and compliance monitoring
• Requires Auth: Yes (Bearer token for protected endpoints)
• Credentials: Service account (fshackathon@fleetstudio.com) stored in workflow
• Usage:
  • Authenticates to access timesheet system
  • Retrieves user data for matching
  • Gets list of employees with missing timesheet submissions

Third-Party Services

Slack API

• Purpose: Team communication platform for sending reminder messages
• Usage:
  • Retrieves all workspace users
  • Gets direct message channel IDs for users
  • Sends personalized reminder messages via direct messages
• Configuration:
  • OAuth2 authentication for user retrieval
  • Bot token for DM channel lookup and messaging
• Credentials:
  • Fleetstudio Slack OAuth2 API (for user retrieval)
  • FS Timesheet Bot (for messaging)
• API Endpoints Used:
  • conversations.list - Get DM channels
  • Direct message sending via Slack node

7. Source Links

n8n Instance

Workflow URL: https://agent.fsgarage.in/workflow/ubqxYjwEyTjZlCdn

Workflow Name: AI Time Sheet Remainder BOT

Workflow ID: ubqxYjwEyTjZlCdn

Email: technology@fleetstudio.com

Password:

n8n Instance URL: https://agent.fsgarage.in

GitHub Repository

Repository: https://github.com/TeamFleetStudio/fs-labs-timesheet-be

Description: Source code repository for the Timesheet Backend API, including user management, timesheet monitoring, and compliance tracking features.

Related Workflows

• Workflows Index - View all workflows
• Workflows Directory - Workflow documentation guidelines