# 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**:

   <pre class="language-bash" data-line-numbers><code class="lang-bash">git clone https://github.com/GDP-ADMIN/CATAPA-API.git
   cd claudia/applications/digital-employee-payroll-officer
   </code></pre>
2. **Install dependencies**:

   <pre class="language-bash" data-line-numbers><code class="lang-bash">make install
   </code></pre>

   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](#environment-variables) for detailed descriptions.

   <pre class="language-bash" data-line-numbers><code class="lang-bash">cp .env.example .env
   </code></pre>
4. **Run the application locally** (optional, for testing):

   <pre class="language-bash" data-line-numbers><code class="lang-bash"># Run locally with default message
   make run

   # Run with custom message
   make run MESSAGE="List employees with missing attendance in January 2026"
   </code></pre>

#### 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](http://claudia.catapa.com/) admin dashboard
   * Navigate to the [Application settings](https://claudia.catapa.com/admin/chatbot)
   * 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

   <figure><img src="https://2914931754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXbRDlxflF58D1QG2tLmP%2Fuploads%2FRxhCi6IagE9bhcZ5Zj0h%2Fimage.png?alt=media&#x26;token=ae2f91e4-59dc-4ccd-92d5-73cc93279fc6" alt=""><figcaption></figcaption></figure>
3. **Start using the agent**:

   You can now interact with the DE Payroll Officer via [CATAPA Chat](http://claudia.catapa.com/).<br>

<figure><img src="https://2914931754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXbRDlxflF58D1QG2tLmP%2Fuploads%2F3EspBl7uAIXaQ5U7nV49%2Fimage.png?alt=media&#x26;token=167c5249-314b-470c-a423-be1d8961c55a" alt=""><figcaption></figcaption></figure>

***

### Agent Architecture Diagram

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

{% @mermaid/diagram content="flowchart TD
Coordinator\[Payroll Officer Agent<br/>Coordinator]

```
Coordinator --> ReminderAgent[Reminder Agent]
Coordinator --> RequestAgent[Request Agent]

subgraph CoordinatorTools["Coordinator Tools"]
    CT1[GetPendingApprovalsAndAttendanceTool]
    CT2[GetMissingPayrollComponentsTool]
    CT3[date_range_tool<br/>built-in]
    CT4[time_tool<br/>built-in]
end

subgraph ReminderTools["Reminder Agent Tools"]
    RT1[GetMissingPayrollComponentsTool]
    RT2[GetPendingApprovalsAndAttendanceTool]
    RT3[glchat_qiscus_whatsapp_tool]
    RT4[date_range_tool<br/>built-in]
    RT5[time_tool<br/>built-in]
end

subgraph ReminderMCPs["Reminder Agent MCPs"]
    RMCP1[google_mail_mcp]
end

subgraph RequestTools["Request Agent Tools"]
    ReqT1[GetPendingApprovalsAndAttendanceTool]
    ReqT2[FillMissingAttendanceTool<br/>HITL Required]
    ReqT3[RejectEntriesTool<br/>HITL Required]
end

Coordinator --> CoordinatorTools
ReminderAgent --> ReminderTools
ReminderAgent --> ReminderMCPs
RequestAgent --> RequestTools" %}
```

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

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

***

### 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](https://github.com/GDP-ADMIN/CATAPA-API/blob/master/claudia/applications/digital-employee-payroll-officer/digital_employee_payroll_officer/payroll_officer/main.py).

{% code lineNumbers="true" %}

```python
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="payroll.officer@example.com", 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

```

{% endcode %}

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

{% code lineNumbers="true" %}

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

{% endcode %}

***

### Environment Variables

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

**AIP Configuration**

GDP Labs [AI Agents Package (AIP)](https://gdplabs.gitbook.io/gl-aip/getting-started/quick-start-guide/local-vs-remote#remote-mode) 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](https://gdplabs.gitbook.io/sdk/tutorials/connectors/agentic-tools-and-model-context-protocol-mcp#pre-requisites)-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](https://apps.catapa.com/dashboard/security/role-permission/privilege) and [OAuth](https://apps.catapa.com/dashboard/setup/settings/oauth-client) 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](https://apps.catapa.com/dashboard/personnel-admin/employee-directory/active-employee/add) 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](https://development.catapa.com/dashboard/security/user/user-list/existing) page.
   * Note the password for the final step.

   <figure><img src="https://2914931754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXbRDlxflF58D1QG2tLmP%2Fuploads%2Fyspj6OVWRLC3dlGKzQeG%2Fimage.png?alt=media&#x26;token=5edfadff-c69b-43c6-86ed-7b6f00291e25" alt=""><figcaption></figcaption></figure>
2. In [Roles & Permissions](https://apps.catapa.com/dashboard/security/role-permission/privilege), assign the **Administrator** role, or a role with full privileges for the following modules:

   * Master Data
   * Compensation & Benefits
   * Time Management
   * Organization

   <figure><img src="https://2914931754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXbRDlxflF58D1QG2tLmP%2Fuploads%2FmLRNRzeYIEZerBW2n7Jc%2Fimage.png?alt=media&#x26;token=443dd18d-2b3c-4bf9-8a2e-934393b74e23" alt=""><figcaption></figcaption></figure>
3. Create an [approver group](https://apps.catapa.com/dashboard/template/group) with **Claudia DE** approvers.

   * Add this approver group to all [approval templates](https://apps.catapa.com/dashboard/template) at the **manager approval** step.

   <figure><img src="https://2914931754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXbRDlxflF58D1QG2tLmP%2Fuploads%2FkPNUymvaQ39IV416TwlD%2Fimage.png?alt=media&#x26;token=402ada05-fea1-4e3c-9cc5-fd0cb37c7084" alt=""><figcaption></figcaption></figure>

   <figure><img src="https://2914931754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXbRDlxflF58D1QG2tLmP%2Fuploads%2FLVntyhNNkaDIQli2aI3N%2Fimage.png?alt=media&#x26;token=c478c0b2-6167-44d4-a82b-678fe73f328b" alt=""><figcaption></figcaption></figure>
4. Create an [OAuth 2.0 Client](https://apps.catapa.com/dashboard/setup/admin-panel/oauth-client/add).

   * 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**

   <div align="left"><figure><img src="https://2914931754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXbRDlxflF58D1QG2tLmP%2Fuploads%2Fb2T67Wevrz8vtmUVwNh1%2FScreenshot%20from%202026-02-10%2007-57-43.png?alt=media&#x26;token=d258bd57-b341-441c-9c15-48a8e7ac5229" alt=""><figcaption></figcaption></figure></div>
5. Select an attendance status code for missing attendance records
   * By default, we use **CDT (Cuti di luar tanggungan)**.
   * Open [Attendance Status](https://apps.catapa.com/time-management/dashboard/setup/attendance/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](https://gdplabs.gitbook.io/catapa/digital-employee-de/list-of-de/claudia-de-hr/claudia-de-payroll-officer/user-guide)
* [GitHub Repository](https://github.com/GDP-ADMIN/CATAPA-API/tree/master/claudia/applications/digital-employee-payroll-officer)