Slack-king-of-time NPM

slack-king-of-time

Usage | Installation | Development | Deployment | Configuration | Changelog | License

A bot to automates clocking in and out using KING OF TIME (www.kingtime.jp).

Features

Automates daily clock-ins and clock-outs using KING OF TIME.
Also supports freee 勤怠管理 Plus, which is a KING OF TIME's OEM.
Clock in and out directly from Slack with action buttons.
Bypasses the need for daily logins to the service.
Automates after work clock-outs, never forget to clock out again.
Easily deployable to Kubernetes using provided configurations.

How to Use

Configure

Set channel and users in config.json

{
  "channel": "slack-channel-id",
  "users": [
    {
      "slackUser": "slack-user-id",
      "clockInCronExpression": "0 9 * * *",
      "clockOutInterval": 999999,
      "kingOfTimeUserId": "king-of-time-user-id",
      "kingOfTimePassword": "king-of-time-password",
      "workingHours": 9,
      "skipWeekend": true,
      "skipJpHoliday": true
    }
  ]
}

channel <string> The Slack channel ID where the bot will post clock-in and clock-out messages (ex: "C05AGSJPVTQ").
users <Array<Object>>
- slackUser <string> The Slack user ID for the user to be managed (ex. "U04C4H79NMA").
- clockInCronExpression <string> A cron expression representing the user's regular clock-in time.
- clockOutInterval <number> Interval in milliseconds at which the bot checks if it's time to clock out. This serves as a randomization factor to prevent exact clock-out times each day.
- kingOfTimeUserId <string> The user ID for the user on the KING OF TIME.
- kingOfTimePassword <string> The password for the user on the KING OF TIME.
- workingHours <number> The length of the user's typical workday in hours. This is used to calculate the clock-out time.
- skipWeekend <boolean> If true, the bot will not clock in or out on weekends. Defaults to false.
- skipJpHoliday <boolean> If true, the bot will not clock in or out on Japanese holidays. Defaults to false.

Invite the bot to the configured channel.

To invite the bot, you can enter /invite @your-bot-name.

Start clock in

To start clocking in, you can enter /kot.

Or, you can wait until clock-in schedule configured in clockInCronExpression for receiving a message automatically

Start interaction

You can interact with action buttons for clock-ins and clock-outs.

Installation

To install the package, you can use npm:

npm install slack-king-of-time

Integration with Existing Bolt Apps

slack-king-of-time can be plugged into your existing Bolt apps. This allows you to add the functionality of slack-king-of-time to your existing Slack apps. Here's a simple example:

import { App } from "@slack/bolt";
import SlackKingOfTime from "slack-king-of-time";

// Assume that you have an existing Bolt app
const app = new App(...);
app.start();

// Initialize slack-king-of-time with the existing Bolt app
const slackKOT = new SlackKingOfTime({
  app,
  signingSecret: "signing-secret", // Optional, or read SLACK_SIGNING_SECRET from environment variables
  botToken: "bot-token", // Optional, or read SLACK_BOT_TOKEN from environment variables
  appToken: "app-token", // Optional, or read SLACK_APP_TOKEN from environment variables
  loginUrl: "https://kintaiplus.freee.co.jp/independent/recorder2/personal/", // Optional, or read LOGIN_URL from environment variables
})

// Start listening for Slack events
slackKOT.start()

Development

There are two ways to set up the development environment: manually or using Visual Studio Code and the Dev Containers.

Manual Setup

Clone the repository:

git clone https://github.com/yujiosaka/slack-king-of-time.git

Navigate to the project directory:

cd slack-king-of-time

Run the npm run config script to set up your development environment:
Set the required environment variables in a .env file.
Set Slack channel and users in a config.json file.
Run the chatbot:

npm run dev

Docker Dev Container Setup

Using Visual Studio Code and the Dev Containers extension, you can simplify the development environment setup process. The extension allows you to develop inside a Docker container and automatically sets up the development environment for you.

Install the Dev Containers extension in Visual Studio Code.
Clone the repository:

git clone https://github.com/yujiosaka/slack-king-of-time.git

Open the cloned repository in Visual Studio Code.
When prompted by Visual Studio Code, click "Reopen in Container" to open the project inside the Docker container.
The extension will build the Docker container and set up the development environment for you. This may take a few minutes.
Set the required environment variables in a .env file.
Set Slack channel and users in a config.json file.
Build and run the Docker container with Docker Compose:

docker-compose up --build

Local Deployment

To deploy the services locally, follow the steps below:

Set up the repository

Clone the repository:

git clone https://github.com/yujiosaka/slack-king-of-time.git

Navigate to the project directory:

cd slack-king-of-time

Secrets and ConfigMaps

Before deploying the services, you need to set up Kubernetes Secrets and ConfigMaps.

Create a .env file from the .env.example file and fill it with your actual values.
Use the following command to create Kubernetes Secrets:

make create-secrets

Create a config.json file from the config.json.example file and fill it with your actual values.
Use the following command to create Kubernetes ConfigMaps:

make create-configmap

Deploying to Kubernetes

To deploy the services to Kubernetes, use the following command:

make deploy

This command applies all Kubernetes configuration files located in the ./kubernetes/ directory.

Cleaning Up

To delete all the deployed resources, use the following command:

make delete

Note: Make sure you have kubectl configured to communicate with your Kubernetes cluster.

Docker Hub Repository

Docker images for this project are available in the Docker Hub repository. You can find suitable images for different versions or tags of the slack-king-of-time application.

Configuration

To configure and install slack-king-of-time in your Slack workspace, follow the steps below:

Create a new app from the manifest

Go to Slack's Your Apps page and click on "Create an App".
Select "From an app manifest" as the creation method.
Choose the workspace where you want to install the app and click the "Next" button.
Copy the contents of the manifest.yaml file and paste it into the text field. Then click the "Next" button.
Review the app details and click "Create" to create the app.

Updating App Credentials

Before starting the application, you need to update the .env file with the required credentials. Follow the steps below:

Create a .env file from the .env.example file.
Retrieve the "Signing Secret" from the "App Credentials" section in the "Basic Settings" menu of your Slack app.
Retrieve "App Token" from the "App Level Tokens" section in the "Basic Settings" menu of your Slack app.
Retrieve "Bot Token" from the "OAuth Tokens for Your Workspace" section in the "OAuth & Permissions" menu of your Slack app,
Replace the placeholders in the .env file with your actual credentials.
Save the .env file.
(Re)start the application.