Endjin.FreeAgent.Journal 1.0.0-preview.2

Endjin.FreeAgent.Journal.App

A command-line tool for automating payroll journal entries in FreeAgent accounting software. This tool processes payroll data from CSV or HTML files and generates balanced double-entry bookkeeping journal entries ready for submission to FreeAgent.

Overview

The FreeAgent Journal App streamlines the monthly payroll accounting process by:

• Automatically parsing payroll summaries from various formats
• Validating employee configurations and payroll data
• Generating balanced journal entries with proper categorization
• Supporting both company directors and regular employees
• Handling various deductions including PAYE, NIC, student loans, and benefits

Features

• Multi-format Support: Process payroll data from CSV or HTML files
• Validation: Comprehensive validation of employee configurations and journal balance
• Smart Categorization: Automatic categorization using FreeAgent's standard categories
• Director Support: Distinguishes between directors and employees for proper NIC handling
• Interactive Confirmation: Review journal entries before submission
• Formatted Output: Color-coded console output for easy review

Prerequisites

• .NET 10.0 or later
• FreeAgent account with API access enabled
• FreeAgent API credentials (Client ID, Client Secret, Refresh Token)

Installation

As a .NET Global Tool

dotnet tool install -g endjin-freeagent-journal

Build from Source

./build.ps1

Configuration

FreeAgent API Setup

1. Create a FreeAgent app at https://dev.freeagent.com/apps
2. Configure your appsettings.json:

{
    "FreeAgent": {
        "ClientId": "your-client-id",
        "ClientSecret": "your-client-secret",
        "RefreshToken": "your-refresh-token"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information"
        }
    }
}

Alternatively, set environment variables:

• FreeAgent__ClientId
• FreeAgent__ClientSecret
• FreeAgent__RefreshToken

Usage

Basic Command Structure

freeagent-journal validate <employees-file> <payroll-file> [date]

Parameters

• <employees-file>: Path to YAML file containing employee configurations
• <payroll-file>: Path to CSV or HTML file containing payroll data
• [date]: Optional journal entry date (YYYY-MM-DD format). Defaults to last day of current month

Examples

# Process payroll with CSV file
freeagent-journal validate employees.yaml payroll.csv

# Process payroll with specific date
freeagent-journal validate employees.yaml payroll.csv 2024-12-31

# Process payroll with HTML file
freeagent-journal validate employees.yaml payroll.html

Input File Formats

Employee Configuration (YAML)

Create an employees.yaml file with the following structure:

- FirstName: John
  LastName: Smith
  Id: "user-001"
  PayRef: "EMP001"
  IsDirector: false
  Roles: []

- FirstName: Jane
  LastName: Doe
  Id: "user-002"
  PayRef: "DIR001"
  IsDirector: true
  Roles: []

Field Descriptions:

• FirstName: Employee's first name
• LastName: Employee's last name
• Id: Unique employee identifier (must be unique across all employees)
• PayRef: Payroll reference (must be unique and match payroll file)
• IsDirector: Set to true for company directors, false for regular employees
• Roles: Array of roles (typically empty array [])

Payroll Data Formats

CSV Format

The CSV file should contain columns for:

• PayRef
• EmployeeName
• Earnings
• Deductions
• PAYE
• EmployeeNIC
• EmployerNIC
• NetPay
• Additional deduction columns (StudentLoan, Benefits, etc.)

HTML Format

HTML payroll summaries are automatically parsed from supported payroll provider formats.

Project Structure

Endjin.FreeAgent.Journal.App/
├── .github/workflows/                      # CI/CD pipelines
├── .zf                                     # ZeroFailed Build configuration
├── Solutions/
│   ├── Endjin.FreeAgent.Journal.App/       # Main application
│   │   ├── App/
│   │   │   ├── Commands/                   # CLI commands
│   │   │   ├── Domain/                     # Domain models
│   │   │   ├── Payroll/                    # Payroll processing logic
│   │   │   └── Infrastructure/             # DI and configuration
│   │   └── appsettings.json                # Configuration file
│   └── Endjin.FreeAgent.Journal.App.Tests/ # Unit tests
└── build.ps1                               # Build script

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

© 2024 Endjin Limited. All rights reserved.