Empdate Documentation

Introduction: How It Functions

Empdate is a lightweight, open-source background daemon written in Python. Its primary function is to eliminate the friction of ticket tracking by bringing Jira directly to where developers communicate: Slack and Webex.

The Workflow:

1. The apscheduler daemon wakes up based on a configured CRON schedule.
2. It connects to your local SQLite database to retrieve the active roster of engineers (Peers).
3. It fetches all In Progress Jira tickets assigned to those engineers using the Atlassian API.
4. It dispatches a direct message via the Slack or Webex API to the engineer summarizing their tickets and asking for a status update.
5. When the engineer replies with a casual, informal message (e.g., "I just fixed the caching bug, deploying to staging now"), Empdate captures the webhook.
6. The casual reply is sent to an AI Provider (OpenAI or a custom local LLM) which transforms it into a professional, structured Jira comment.
7. Empdate posts the AI-formatted comment directly to the Jira ticket.

Architecture Overview

The codebase is split into highly modular files inside the core/ directory:

• config.py: Parses the config.yaml file safely.
• db.py: Manages the local SQLite database using SQLAlchemy.
• jira_client.py: Handles all Atlassian API interactions.
• slack_bot.py / webex_bot.py: Abstracted messaging clients.
• ai_client.py: The prompt-engineering wrapper for the LLM.
• empdate.py: The main entry point containing the BackgroundScheduler.

Prerequisites

Before installing, ensure you have the following ready:

• Python 3.10+ installed on your server or local machine.
• Admin Access to your Jira instance to generate an API token.
• Workspace Admin permissions in Slack or Webex to create a bot app.
• An OpenAI API Key (or a URL to your local LLM like Ollama or vLLM).

Step 1: Clone & Setup

First, grab the source code from the repository and install the required Python dependencies.

git clone https://github.com/abhinav-193/empdate.git cd empdate/core # It is highly recommended to use a virtual environment python -m venv venv # Activate the virtual environment # On Mac/Linux: source venv/bin/activate # On Windows: venv\Scripts\activate # Install dependencies pip install -r requirements.txt

Step 2: The config.yaml File

Empdate uses a single YAML file for configuration to ensure no secrets are hardcoded. Copy the example template to create your actual config file:

cp config.yaml.example config.yaml

Open config.yaml in your text editor. Every field is critical for the daemon to start correctly.

Jira Integration

To connect Empdate to Jira, you need three pieces of information:

1. Domain: Your company's Atlassian URL (e.g., yourcompany.atlassian.net).
2. Email: The email address associated with the service account that will post comments.
3. API Token: Generated from your Atlassian Account Settings > Security > Create API Token.

If your company hosts Jira on-premise and requires custom SSL verification, provide the absolute path to your PEM file in the cert_path property. Leave it empty otherwise.

# config.yaml jira: domain: "yourcompany.atlassian.net" email: "bot-service@company.com" api_token: "YOUR_JIRA_API_TOKEN" cert_path: "/etc/ssl/certs/company-ca.pem" # Optional

Slack Bot Setup

Empdate relies on a Slack App to send Direct Messages to users.

1. Go to api.slack.com/apps and click Create New App.
2. Navigate to OAuth & Permissions in the sidebar.
3. Under Bot Token Scopes, add the following scopes:
   • chat:write (To send messages)
   • users:read (To lookup users by their email address)
   • users:read.email (To match Jira emails to Slack IDs)
4. Click Install to Workspace at the top of the page.
5. Copy the Bot User OAuth Token (starts with xoxb-) into your config.yaml.

# config.yaml slack: bot_token: "xoxb-1234567890-YOUR-BOT-TOKEN"

Webex Bot Setup

If your organization uses Webex Teams instead of Slack, you can configure the Webex module.

1. Go to the Webex Developer Portal.
2. Click Create a New App and select Bot.
3. Fill in the bot name and icon.
4. Upon creation, you will be given a Bot Access Token. Paste this into your config.yaml.

AI Models & Prompts

Empdate's secret sauce is its AI formatting layer. By default, it uses OpenAI's GPT-4. However, you can easily switch to a local privacy-preserving model.

To use Ollama or a local vLLM instance, simply change the endpoint to your local server and provide the custom model name.

# config.yaml ai: provider: "custom" endpoint: "http://localhost:11434/v1" # Your local endpoint api_key: "sk-dummy-key" # Ignored by local instances custom_model_name: "llama3-8b-instruct"

To modify the system prompt that instructs the AI on how to format tickets, edit the ai_client.py file directly:

# core/ai_client.py messages=[ {"role": "system", "content": "You are a strict, highly professional project manager. Summarize the user's input into a 3-bullet-point Jira comment."}, {"role": "user", "content": prompt} ]

IAM Hierarchy (SQLite)

Empdate uses an SQLite database named empdate.db. It creates a table called user_iam with three roles: admin, manager, and peer.

The cron job only pings users with the peer role. To add a user, open your terminal and interact with the database:

sqlite3 empdate.db # Add an engineer sqlite> INSERT INTO user_iam (email, role, manager_email) VALUES ('dev1@company.com', 'peer', 'boss@company.com'); # Add a manager sqlite> INSERT INTO user_iam (email, role) VALUES ('boss@company.com', 'manager');

3. Running the Daemon

With configuration complete and your database populated, start the service.

python empdate.py

You will see the apscheduler boot up. Depending on your cron schedule in config.yaml (e.g., "0 9 * * *"), it will idle until 9:00 AM, at which point it will query Jira and dispatch messages!

Production Deployment

For production use, do not run python empdate.py in a standard tmux session. It is highly recommended to wrap the service in a Systemd unit or a Docker container so it automatically restarts on failure.