mirror of
https://github.com/kbenestad/reimburse.git
synced 2026-06-18 16:04:31 +00:00
123 lines
5.7 KiB
Markdown
123 lines
5.7 KiB
Markdown
# User Guide — Reimbursement Form
|
||
|
||
This guide is for staff submitting expense reimbursement claims.
|
||
|
||
---
|
||
|
||
> Copyright 2026 Kristian Benestad. Licensed under the Apache License, Version 2.0. See LICENSE for more information.
|
||
>
|
||
> This is a custom build of kbenestad/reimburse for Boat People SOS and People Serving People Foundation.
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
The reimbursement form runs in your browser. You fill in your expenses, attach receipts, and click one button to download a PDF. No account, login, or internet upload is needed — the PDF is generated entirely on your device.
|
||
|
||
---
|
||
|
||
## Step-by-step
|
||
|
||
### 1. Open the form
|
||
|
||
Navigate to the URL your administrator has given you (e.g. `https://app.example.org/reimbursement/`). The form loads in a few seconds. If you see an error, check your internet connection — the form needs to reach CDN servers to load its libraries.
|
||
|
||
### 2. Fill in the header fields
|
||
|
||
At the top of the form you will see four fields:
|
||
|
||
| Field | What to enter |
|
||
|---|---|
|
||
| **Staff** | Your full name. This is saved in your browser and pre-filled next time. |
|
||
| **Period from** | Start date of the expense period (defaults to the first day of last month). |
|
||
| **to** | End date of the expense period (defaults to the last day of last month). |
|
||
| **Base currency** | The currency your reimbursement will be paid in. Select from the dropdown. |
|
||
|
||
> **Period default logic:** On the last day of the current month, the period defaults to the current month instead of the previous one.
|
||
|
||
### 3. Add items
|
||
|
||
An "item" groups related expenses — for example, a trip, a project, or a category. Click **+ Add item / project / travel** to create one. Give the item a descriptive name (e.g. "Field visit to Chiang Rai, March 2026").
|
||
|
||
You can add as many items as you need and remove any item with the **✕ Remove** button.
|
||
|
||
### 4. Add expense lines
|
||
|
||
Each item contains one or more expense lines. A line represents a single purchase or payment. Click **+ Add line** inside an item to add a line.
|
||
|
||
Each line has the following fields:
|
||
|
||
#### Date
|
||
The date the expense was incurred. Use the date picker or type `YYYY-MM-DD`.
|
||
|
||
#### Vendor
|
||
The name of the shop, service provider, or payee. Example: "Bangkok Airways", "Office Depot".
|
||
|
||
#### Currency
|
||
The currency in which you paid. Select from the dropdown. Each option shows the currency code (e.g. `THB`) and the full name (e.g. "Thai baht").
|
||
|
||
#### FX rate
|
||
How many units of the line currency equal one unit of the base currency.
|
||
|
||
- Example: if base currency is USD and you paid in THB, enter the number of Thai baht per 1 US dollar (e.g. `34.25000`).
|
||
- If the line currency is the same as the base currency, this field is locked at `1.00000` and you cannot change it.
|
||
- The form remembers FX rates you have entered for each currency during the session.
|
||
|
||
> **FX rate direction:** `line_amount ÷ fx_rate = base_amount`. Always use the rate as "how many [line currency] per 1 [base currency]".
|
||
|
||
#### Description
|
||
A brief description of what was purchased or paid for. Example: "Taxi from airport to hotel".
|
||
|
||
#### Receipt
|
||
Select **Yes** if you have a receipt, **No** if you do not.
|
||
|
||
- **Yes:** Upload one or more receipt files (PDF, JPG, or PNG). Each file will be embedded at the end of the PDF output. You can remove an uploaded file and re-upload.
|
||
- **No:** A text box appears. You must explain why no receipt is available (e.g. "Toll fees — no receipt issued"). This explanation will appear on the PDF.
|
||
|
||
#### Amount
|
||
The amount paid, in the line currency (not converted). Enter a positive number. Example: `1850.00`.
|
||
|
||
#### Account
|
||
Select the accounting code that this expense belongs to. The options are configured by your administrator.
|
||
|
||
#### Program
|
||
Select the program or project this expense relates to. If you select **Other**, a text field appears where you must type the program name.
|
||
|
||
### 5. Review totals
|
||
|
||
Each item shows a **Subtotal** in the base currency. The bottom of the form shows the **Total reimbursement claim**. These update as you type.
|
||
|
||
### 6. Generate the PDF
|
||
|
||
Click **Generate Reimbursement Form**. The form validates all fields first. If anything is missing or incorrect, a red box at the top lists the problems — fix them and click again.
|
||
|
||
When validation passes, the PDF is generated in your browser and downloaded automatically. The filename is:
|
||
|
||
```
|
||
reimbursement_[Your_Name]_[from-date]_[to-date].pdf
|
||
```
|
||
|
||
### 7. Submit the PDF
|
||
|
||
Send the downloaded PDF to whoever handles reimbursements at your organisation. No further action is needed in the browser.
|
||
|
||
---
|
||
|
||
## Tips
|
||
|
||
- **Your name is remembered.** It is stored in your browser's local storage so you do not need to retype it next visit.
|
||
- **FX rates are remembered within a session.** If you enter a rate for THB and then switch to USD and back, the THB rate is restored.
|
||
- **Large receipt files slow PDF generation.** If the browser appears frozen after clicking "Generate", wait — it is processing the files.
|
||
- **Password-protected PDFs cannot be merged.** If a receipt PDF is password-protected, the output will contain an error page in its place. Use a non-protected version.
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
| Symptom | Likely cause | Fix |
|
||
|---|---|---|
|
||
| Form shows "Loading configuration…" indefinitely | Network issue or server misconfiguration | Check internet connection; contact your administrator |
|
||
| "Failed to load: Cannot load config.yml" | Server is not serving the config file | Contact your administrator |
|
||
| PDF download starts but contains error text | A receipt PDF is password-protected or corrupt | Replace the file with an unprotected version |
|
||
| Amounts show as "–" in the PDF | Amount field left blank or non-numeric | Enter a valid number in the amount field |
|
||
| FX rate field is greyed out | Line currency equals the base currency | No action needed; rate is 1.00000 by definition |
|