Technical Guide

This guide provides technical documentation for setting up, understanding, and extending the Digital Employee Payroll Officer.

How to Setup

Prerequisites

Before starting, ensure you have:

• Python 3.11 or 3.12

• Poetry 2.1.3 or higher

• Google Cloud SDK (for accessing internal package repositories)

• Access to CATAPA API with valid credentials

Installation Steps

1. Clone the repository:

   git clone https://github.com/GDP-ADMIN/CATAPA-API.git
   cd claudia/applications/digital-employee-payroll-officer

2. Install dependencies:

   make install

   This command configures Poetry authentication for internal repositories and installs all project dependencies.

3. Configure environment variables:

   Copy the example environment file and update with your credentials. See Environment Variables for detailed descriptions.

   cp .env.example .env

4. Run the application locally (optional, for testing):

   # Run locally with default message
   make run
   
   # Run with custom message
   make run MESSAGE="List employees with missing attendance in January 2026"

Deployment

1. Agent deployment: Agent deployment is handled by the Digital Employee team through Continuous Delivery (CD). This process registers the Digital Employee—along with its identity, tools, and configurations—on the AIP platform.

2. Enable the agent in CATAPA Chat admin dashboard:

   • Log in to the CATAPA Chat admin dashboard

   • Navigate to the Application settings

   • Create or edit an application

   • Add DE Payroll Officer as a supported agent in the application

   • Click Next to save the configuration

   • Manage user access to this application

   
3. Start using the agent:

   You can now interact with the DE Payroll Officer via CATAPA Chat.

---

Agent Architecture Diagram

The Digital Employee Payroll Officer uses a single-agent architecture with specialized tools for different tasks.

The architecture follows a hierarchical delegation model where the Coordinator Agent handles high-level orchestration and decision-making, while specialized sub-agents focus on specific operational tasks. The Reminder Agent handles all communication channels (WhatsApp and Email), while the Request Agent performs automated cleanup operations with Human-In-The-Loop (HITL) safeguards for destructive actions.

Agent Description

Payroll Officer Agent (Coordinator)

• Type: Main Coordinator Agent

• Purpose: Orchestrates pre-payroll validation workflows by delegating tasks to specialized sub-agents

• Model: Default model (from digital_employee_core)

• Key Capabilities:

  • Coordinates data retrieval for pending approvals and attendance

  • Identifies missing payroll components

  • Delegates specific operations to Reminder Agent and Request Agent

• Tools:

  • GetPendingApprovalsAndAttendanceTool - Gets pending roster approvals and attendance data

  • GetMissingPayrollComponentsTool - Retrieves missing payroll components

  • date_range_tool - Built-in tool for date range operations

  • time_tool - Built-in tool for time operations

• MCPs: None

• Sub-agents: Reminder Agent, Request Agent

• Configurations: CATAPA credentials (tenant, username, password, base_url)

Reminder Agent

• Type: Specialized Sub-Agent

• Purpose: Identifies and reports comprehensive payroll processing issues to HR managers, employees, or supervisors via WhatsApp and Email reminders

• Model: GPT-5 Mini

• Key Capabilities:

  • Proactive notification and issue reporting

  • Multi-channel communication (WhatsApp and Email)

  • Comprehensive payroll issue identification

• Tools:

  • GetMissingPayrollComponentsTool - Retrieves missing payroll components from CATAPA

  • GetPendingApprovalsAndAttendanceTool - Gets pending roster approvals and attendance data

  • glchat_qiscus_whatsapp_tool - Sends WhatsApp messages via GLChat/Qiscus integration

  • date_range_tool - Built-in tool for date range operations

  • time_tool - Built-in tool for time operations

• MCPs:

  • google_mail_mcp - Google Mail integration for sending email reminders

• Tool Configurations: CATAPA API credentials, GLChat/Qiscus credentials (base_url, api_key, channel_id)

Request Agent

• Type: Specialized Sub-Agent

• Purpose: Retrieves and processes pending roster approvals and missing attendance data. Capable of automated cleanup by filling missing attendance with unpaid leave and rejecting pending approval entries to resolve payroll-blocking issues

• Model: GPT-5 Mini

• Key Capabilities:

  • Automated cleanup operations for payroll-blocking issues

  • Filling missing attendance records

  • Rejecting pending approval entries

• HITL (Human-In-The-Loop): Enabled for destructive operations

• Tools:

  • GetPendingApprovalsAndAttendanceTool - Gets pending roster approvals and attendance data

  • FillMissingAttendanceTool - Fills missing attendance records with unpaid leave status (HITL required)

  • RejectEntriesTool - Rejects pending approval entries (presence/absence corrections) (HITL required)

• MCPs: None

• Tool Configurations: CATAPA API credentials, HITL timeout settings, default attendance status code for filling missing attendance

Tools Reference

Tool	Purpose
get_pending_roster_approval_for_employee_tool	Gets pending roster approvals and attendance data
get_missing_payroll_components_tool	Retrieves missing payroll components
date_range_tool	Built-in tool for date range operations
time_tool	Built-in tool for time operations
glchat_qiscus_whatsapp_tool	Sends WhatsApp messages via GLChat/Qiscus integration
fill_missing_attendance_tool	Fills missing attendance records with unpaid leave status (HITL required)
reject_entries_tool	Rejects pending approval entries (presence/absence corrections) (HITL required)

---

Code Snippet

Below is a code snippet showing how the Payroll Officer Digital Employee is created and configured. See the full source code on GitHub.

def create_payroll_officer_agent() -> DigitalEmployee:
    instruction = _load_instruction()
    reminder_agent = ReminderAgent()
    request_agent = RequestAgent()
    job = DigitalEmployeeJob(title="Payroll Officer Coordinator", description=DESCRIPTION, instruction=instruction)
    identity = DigitalEmployeeIdentity(name=NAME, email="[e-mail]", job=job)
    configurations = [
        DigitalEmployeeConfiguration(key="CATAPA_TENANT", value=CATAPA_TENANT),
        DigitalEmployeeConfiguration(key="CATAPA_USERNAME", value=CATAPA_USERNAME),
        DigitalEmployeeConfiguration(key="CATAPA_PASSWORD", value=CATAPA_PASSWORD),
        DigitalEmployeeConfiguration(key="CATAPA_BASE_URL", value=CATAPA_BASE_URL),
    ]
    digital_employee = PayrollOfficerDigitalEmployee(
        identity=identity,
        tools=[
            get_pending_roster_approval_for_employee_tool,
            get_missing_payroll_components_tool,
            time_tool,
            date_range_tool,
        ],
        sub_agents=[reminder_agent, request_agent],
        mcps=[],
        configurations=configurations,
    )
    digital_employee.deploy()
    return digital_employee

This function:

1. Loads agent instructions from a markdown file (payroll_officer_agent.md).

2. Creates two sub-agents: ReminderAgent (reminders) and RequestAgent (automated requests).

3. Defines the job with title "Payroll Officer Coordinator", description, and instructions.

4. Creates the identity with name, email, and job.

5. Sets CATAPA API configurations (tenant, username, password, base URL).

6. Instantiates PayrollOfficerDigitalEmployee with:

   • Identity

   • Tools: pending roster approval, missing payroll components, time, date range

   • Sub-agents: reminder and request agents

   • Configurations: CATAPA credentials

7. Deploys the digital employee.

8. Returns the deployed digital employee instance.

Usage Example

payroll_officer_agent = create_payroll_officer_agent()
result = payroll_officer_agent.run(message="List employees missing attendance for January 2026")
print(result)

---

Environment Variables

This section describes all environment variables required to configure the Digital Employee Payroll Officer.

AIP Configuration

GDP Labs AI Agents Package (AIP) is the platform where the Digital Employee is deployed.

Variable	Description
AIP_API_URL	Base URL of the AIP platform API
AIP_API_KEY	API key for authenticating with the AIP platform

BOSA Configuration

BOSA is a proxy service that simplifies integration with Connector-compatible APIs. In this case, it is used as a gateway to connect to Gmail API for sending email reports.

Variable	Description
BOSA_BASE_URL	Base URL of the BOSA service
BOSA_API_KEY	API key for BOSA authentication
BOSA_IDENTIFIER	User identifier for BOSA
BOSA_SECRET	User secret for BOSA authentication

CATAPA Configuration

CATAPA is the HRIS system where payroll data is retrieved.

Variable	Description
CATAPA_BASE_URL	Base URL of the CATAPA API
CATAPA_USERNAME	Username for CATAPA authentication
CATAPA_PASSWORD	Password for CATAPA authentication
CATAPA_TENANT	Tenant ID to identify the company in CATAPA
CATAPA_CLIENT_ID	OAuth 2.0 client ID for CATAPA API access
CATAPA_CLIENT_SECRET	OAuth 2.0 client secret for CATAPA API access

Note: The CATAPA user and OAuth client must have full privileges for the following modules:

• Payroll / Compensation & Benefits

• Employee / Organization

• Time Management

• Master Data

Google MCP Configuration

Google MCP (Model Context Protocol) is used for email integration.

Variable	Description
GOOGLE_MCP_X_API_KEY	API key for Google MCP authentication
GOOGLE_MAIL_MCP_URL	Base URL of the Google Mail MCP service

Payroll Officer Agent Configuration

Agent-specific settings for prompt constants and default values.

Variable	Description	Default
PROMPT_CONSTANT_PAYROLL_OFFICER_AGENT_HR_APPROVER_EMAIL	Email address of the HR approver used in reminder messages	-
PROMPT_CONSTANT_PAYROLL_OFFICER_AGENT_HYPERLINK_SALARY_DECREE_APPROVAL	Hyperlink URL for salary decree approval page	-
PROMPT_CONSTANT_PAYROLL_OFFICER_AGENT_HR_USER_NAME	Name of the HR user used in reminder messages	-
DEFAULT_ATTENDANCE_STATUS_CODE	Default attendance status code for missing attendance records	CUTPOT

GLChat/WhatsApp Configuration

Configuration for WhatsApp messaging via GLChat/Qiscus integration.

Variable	Description
GLCHAT_WA_BASE_URL	Base URL of the GLChat WhatsApp service
APP_API_KEY	API key for GLChat authentication
QISCUS_CHANNEL_ID	Qiscus channel ID for WhatsApp messaging

---

CATAPA Setup

1. Add a new employee to represent the Digital Employee.

   • Employee name: preferably “Claudia DE”

   • Note the username for the final step

   • Complete the verification instructions sent to the user’s email to set the password. Alternatively, if no email is provided, manually reset the user password from the User List page.

   • Note the password for the final step.

   
2. In Roles & Permissions, assign the Administrator role, or a role with full privileges for the following modules:

   • Master Data

   • Compensation & Benefits

   • Time Management

   • Organization

   
3. Create an approver group with Claudia DE approvers.

   • Add this approver group to all approval templates at the manager approval step.

   

   
4. Create an OAuth 2.0 Client.

   • Client ID: preferably de_payroll_officer

   • Authorized Grant Type: client_credentials

   • Client Access: grant full access to Payroll, Employee, and Time Management

   • Web Server Redirect URI: https://catapa.com

   • Click Save, then copy the generated Client Secret

   
5. Select an attendance status code for missing attendance records

   • By default, we use CDT (Cuti di luar tanggungan).

   • Open Attendance Status to view the list of available attendance statuses.

   • Note the selected attendance status code for the final step.

6. Provide the username, password, Client ID, Client Secret, and attendance status code to the CATAPA infra team.

---

References

• DE Payroll Officer User Guide

• GitHub Repository