@microsoft/expense-entry

---
name: expense-entry
description: Processes expense receipts and creates expense report entries following company policies with approval thresholds and validation rules. Use when user says "log this expense", "process this receipt", "create expense entry", "submit expense", "add to expense report", uploads a receipt image, or provides purchase documentation to expense.
metadata:
  author: Dataverse
  version: 1.0.0
  category: finance
---

# Expense Entry Business Skill

This skill defines the business process for creating expense report entries from receipt information. It enforces company expense policies, proper categorization, and validation rules.

## Prerequisites

This skill requires an **Expense Report** table to be created in your Dataverse environment. Use the schema below to create the table, or adapt the skill to work with your existing expense management table.

### Required Table Schema: Expense Report

Create a custom table named `Expense Report` (logical name will be `cr###_expensereport` where ### is your publisher prefix) with these columns:

| Display Name | Logical Name | Type | Description |
|-------------|--------------|------|-------------|
| Report ID | cr###_reportid | Text (100) | Unique ID (e.g., ER-2025-1120-001) |
| Report Name | cr###_reportname | Text (200) | Descriptive name |
| Report Status | cr###_reportstatus | Choice | Draft, Submitted, Pending Approval, Approved, Rejected, Paid |
| Total Amount | cr###_totalamount | Currency | Pre-tax expense amount |
| Tax Amount | cr###_taxamount | Currency | Sum of tax amounts |
| Corporate Card Amount | cr###_corporatecardamount | Currency | Amount on corporate card |
| Personal Card Amount | cr###_personalcardamount | Currency | Amount requiring reimbursement |
| Approval Tier | cr###_approvaltier | Choice | None, Manager, Controller, CFO |
| Days Since Expense | cr###_dayssinceexpense | Whole Number | Days between expense and submission |
| Late Submission | cr###_latesubmission | Yes/No | True if > 90 days |
| Billable Amount | cr###_billableamount | Currency | Client-billable portion |
| Internal Amount | cr###_internalamount | Currency | Internal expense portion |
| Project Code | cr###_projectcode | Text (50) | Project code if billable |
| Expense Categories | cr###_expensecategories | Text (500) | Categories (Hotel, Meals, Travel, etc.) |
| Duplicate Status | cr###_duplicatestatus | Choice | No Duplicates, Duplicates Found, Not Checked |
| Policy Violations | cr###_policyviolations | Text (1000) | Any policy violations |
| Merchant Name | cr###_merchantname | Text (200) | Vendor/merchant name |
| Transaction Date | cr###_transactiondate | Date Only | Receipt/transaction date |
| Submission Date | cr###_submissiondate | Date Only | Date submitted |
| Employee | cr###_employee | Lookup (Contact) | Employee who submitted |
| Approved By | cr###_approvedby | Lookup (User) | Approving manager |
| Approved Date | cr###_approveddate | Date Only | Approval date |

> **Note:** Replace `cr###_` with your actual publisher prefix (e.g., `contoso_`, `new_`, etc.)

### Alternative: Dynamics 365 Finance Integration
If your organization uses Dynamics 365 Finance, this skill can be adapted to work with the `msdyn_expense` table from the Expense Management module.

## Instructions

### When to Use This Skill

Use this skill when:
- Processing expense receipts (images, PDFs, or text)
- Creating expense report entries from purchase documentation
- Categorizing and validating business expenses
- Ensuring compliance with company expense policies

**DO NOT** attempt to create expense entries without this skill - proper categorization and validation are required.

### Dataset Table Reference

All expense data is stored in your **Expense Report** table (see Prerequisites for schema). The skill references these fields using placeholder notation:
- `[reportid]`: Unique identifier (e.g., ER-2025-1120-001)
- `[reportstatus]`: Draft, Submitted, Pending Approval, Approved, Rejected, Paid
- `[totalamount]`: Total expense amount before tax
- `[taxamount]`: Sum of all tax amounts
- `[corporatecardamount]`: Amount paid with corporate card
- `[personalcardamount]`: Amount paid with personal card (requires reimbursement)
- `[approvaltier]`: None, Manager, Controller, CFO (based on amount)
- `[dayssinceexpense]`: Days between expense and submission
- `[latesubmission]`: Yes/No (if > 90 days)
- `[billableamount]`: Amount billable to clients
- `[internalamount]`: Amount for internal expenses
- `[projectcode]`: Project code if billable
- `[expensecategories]`: Categories included (e.g., "Hotel, Meals, Travel")
- `[duplicatestatus]`: No Duplicates, Duplicates Found, Not Checked
- `[policyviolations]`: Any policy violations detected

### Workflow Overview

### Step 1: Extract Receipt Information

From the receipt, extract:
- **Merchant name** and merchant category (airlines, hotels, restaurants, retailers, etc.)
- **Transaction date** (receipt date, not submission date)
- **Total amount** (pre-tax amount)
- **Tax amount** (separately itemized)
- **Currency** (default to USD if not specified)
- **Payment method** (Corporate Card vs Personal Card - critical for reimbursement)
- **Itemized details** (line items if available for multi-item receipts)
- **Receipt description/purpose** (business justification)

### Step 2: Categorize the Expense (CRITICAL)

Based on merchant category and itemized details, assign the correct **expense category** for the `expense_categories` field:

#### Hotel/Lodging
- Room rates, resort fees, hotel parking
- Hotel wifi charges (when part of hotel bill)
- **Merchant Categories**: Hotels, Lodges, Resorts
- **EXCLUDE**: AirBnB or short-term rentals (use "Travel")

#### Meals
- Business dinners with clients/partners
- Individual employee meals during travel
- **Merchant Categories**: Restaurants, Cafes, Catering
- **Validation**: If > $75 per person, require attendee list in description

#### Office Supplies
- Pens, paper, folders, toner, staplers
- USB drives, cables (under $50)
- Printer supplies, desk accessories
- **Merchant Categories**: Office Supply Stores, Stationery Stores

#### Travel
- Airline tickets, baggage fees, seat upgrades
- Taxi, Uber, Lyft, rental cars
- Parking fees, tolls, train tickets
- **Merchant Categories**: Airlines, Travel Agencies, Transportation Services

#### Software & Subscriptions
- SaaS subscriptions, software licenses
- Cloud services, API usage fees
- **Merchant Categories**: Software Vendors, Online Services

#### Equipment & Hardware
- Laptops, monitors, keyboards (over $100)
- Mobile devices, tablets
- **Merchant Categories**: Electronics Stores
- **Validation**: Items over $500 require asset tag assignment

#### Conference & Training
- Conference registrations, seminar fees
- Training course fees, certification exams
- **REQUIRES**: Event name and dates in description

### Step 3: Apply Business Rules & Validation

#### Approval Threshold Rules (Sets `approval_tier` field)
- **Under $500**: approval_tier = "None" (auto-approved)
- **$500 - $2,000**: [approvaltier] = "Manager"
- **$2,000 - $5,000**: [approvaltier] = "Controller"
- **Over $5,000**: [approvaltier] = "CFO" (requires business case documentation)

#### Payment Method Tracking (Sets `[corporatecardamount]` and `[personalcardamount]`)
- If **Corporate Card**: Set `[corporatecardamount]` = total amount, `[personalcardamount]` = 0
- If **Personal Card**: Set `[personalcardamount]` = total amount, `[corporatecardamount]` = 0
- Corporate Card = no reimbursement needed
- Personal Card = requires reimbursement workflow

#### Project & Billability Rules (Sets `[billableamount]`, `[internalamount]`, `[projectcode]`)
- If **client name** mentioned (not "Internal"):
  - Set `[billableamount]` = total amount, `[internalamount]` = 0
  - Extract and populate `[projectcode]` (search for active projects for that client)
  - If no project code found, flag for assignment

- If **internal expense**:
  - Set `[internalamount]` = total amount, `[billableamount]` = 0
  - Set `[projectcode]` = empty
  - Use department cost center code

#### Duplicate Detection (Sets `[duplicatestatus]` field)
- Search for existing expense entries with:
  - Same merchant name
  - Same transaction date
  - Same amount (within $1 tolerance)
  - Same employee
- If found: Set `[duplicatestatus]` = "Duplicates Found" and **DO NOT CREATE**
- If no duplicates: Set `[duplicatestatus]` = "No Duplicates"

#### 90-Day Policy Validation (Sets `[dayssinceexpense]` and `[latesubmission]`)
- Calculate `[dayssinceexpense]` = submission date - transaction date
- If `[dayssinceexpense]` > 90: Set `[latesubmission]` = "Yes"
- If `[dayssinceexpense]` <= 90: Set `[latesubmission]` = "No"

### Step 4: Create Expense Report Record

Create record in your **Expense Report** table with:

**Required Fields**:
- `[reportid]`: Generate unique ID (format: ER-YYYY-MMDD-XXX)
- `[reportname]`: "[Month Year] [Category] - [Employee Name]"
- `[submissiondate]`: Today's date (YYYY-MM-DD format)
- `[employee]`: Lookup to Contact record for employee
- `[reportstatus]`: "Submitted" (or "Draft" if saving for later)
- `[totalamount]`: Expense amount before tax (numeric)
- `[taxamount]`: Tax amount (numeric)

**Payment Method Fields**:
- `[corporatecardamount]`: Amount paid with corporate card
- `[personalcardamount]`: Amount paid with personal card

**Approval Fields**:
- `[approvaltier]`: Based on amount thresholds from Step 3
- `[approvedby]`: Empty (will be filled after approval)
- `[approveddate]`: Empty (will be filled after approval)

**Validation Fields**:
- `[dayssinceexpense]`: Calculated in Step 3
- `[latesubmission]`: "Yes" or "No" based on 90-day policy
- `[duplicatestatus]`: Result from duplicate detection
- `[policyviolations]`: Any violations detected (empty if none)

**Billability Fields**:
- `[billableamount]`: Amount billable to clients
- `[internalamount]`: Amount for internal expenses
- `[projectcode]`: Project code if billable

**Category Field**:
- `[expensecategories]`: Categories from Step 2 (e.g., "Hotel, Meals, Travel")

### Step 5: Create Supporting Records

#### If Approval Required (approval_tier not "None"):
- Create `task` record for approver
- Link to expense report
- Subject: "Approve Expense: [Category] - $[Amount] - [Merchant]"
- Assigned to: Based on `approval_tier` (Manager/Controller/CFO)
- Due date: 3 business days from submission

#### If Billable to Client:
- Create `note` linked to Project
- Content: "Expense incurred: [Category] - $[Amount] - [Date] - [Description]"
- Link to both Project and Expense Report for audit trail

### Step 6: Update Report Status

Set `[reportstatus]` based on approval requirements:
- If `[approvaltier]` = "None": Set `[reportstatus]` = "Approved"
- If `[approvaltier]` = "Manager", "Controller", or "CFO": Set `[reportstatus]` = "Pending Approval"

## Validation & Quality Checks

Before finalizing expense entry:

1. **Amount Reasonableness**:
   - Hotel: $100-$500/night typical (flag if outside range)
   - Meals: $15-$75 per person typical
   - Travel: $10-$150 typical for ground transport
   - Office supplies: Usually under $100

2. **Date Validation**:
   - Transaction date not in future
   - Calculate `[dayssinceexpense]` accurately
   - Set `[latesubmission]` = "Yes" if > 90 days

3. **Policy Compliance**:
   - Meals over $75/person: Verify attendee list in description
   - Hotel: Not from home city (unless business reason documented)
   - Expenses over $25: Receipt required

4. **Duplicate Detection**:
   - Always search before creating
   - Set `[duplicatestatus]` appropriately

## Error Handling

If validation fails:
- **DO NOT CREATE** incomplete/invalid expense entry
- Return specific error message:
  - "Missing required field: [field name]"
  - "Invalid category: [attempted category]"
  - "Duplicate expense detected: [details]"
  - "Policy violation: [specific rule]"
  - "Amount exceeds threshold: Requires [approval level]"

## Examples

### Example 1: Standard Office Supplies Expense

**User says:** "I bought office supplies for the team yesterday. Create an expense for this receipt: Office Depot, $247.50 total ($227.89 + $19.61 tax), paid Dec 2, 2025 with corporate card. Items: toner cartridge, copy paper, folders."

**Actions:**
1. Extract receipt data: Merchant = "Office Depot", Amount = $227.89, Tax = $19.61, Date = 2025-12-02, Payment = Corporate Card
2. Categorize: Merchant category = Office Supply Stores → expense_categories = "Office Supplies"
3. Apply rules: $247.50 < $500 → approval_tier = "None" (auto-approved)
4. Validate: No duplicates found, 1 day since expense → late_submission_flag = "No"
5. Create expense_reports record with all fields populated

**Result:**
```
Expense Report Created: ER-2025-1203-015
Status: Approved (auto-approved)
Amount: $247.50 (Corporate Card)
Category: Office Supplies
No reimbursement needed
No manager approval required
```

### Example 2: Client Dinner Requiring Approval

**User says:** "Log this dinner receipt: The Capital Grille, $425 total ($390 + $35 tax), personal card, client dinner with Contoso team on Dec 5. Attendees: John Smith, Sarah Chen, myself."

**Actions:**
1. Extract: Merchant = "The Capital Grille", Amount = $390, Tax = $35, Date = 2025-12-05, Payment = Personal Card
2. Categorize: Restaurant → [expensecategories] = "Meals"
3. Validate: $425/3 people = $141.67/person > $75 threshold → attendee list required (provided)
4. Apply rules: $425 ≥ $500 threshold → [approvaltier] = "Manager"
5. Set [billableamount] = $425 (client expense), find Contoso project code
6. Create record with [reportstatus] = "Pending Approval"
7. Create approval task for manager

**Result:**
```
Expense Report Created: ER-2025-1206-022
Status: Pending Approval (Manager)
Amount: $425.00 (Personal Card - Reimbursement Required)
Category: Meals
Billable to: Contoso (Project: PROJ-CONTOSO-2025)
Approval task created for: [Manager Name]
```

### Example 3: Late Travel Expense with Warning

**User says:** "Need to expense this flight from September: Delta Airlines $650, Sept 15, corporate card, NYC to Chicago for internal training."

**Actions:**
1. Extract: Merchant = "Delta Airlines", Amount = $650, Date = 2025-09-15, Payment = Corporate Card
2. Categorize: Airlines → expense_categories = "Travel"
3. Calculate: Days since expense = 82 days (approaching 90-day limit)
4. Apply rules: $650 ≥ $500 → approval_tier = "Manager"
5. Set internal_amount = $650, billable_amount = $0
6. Create record with late_submission_flag = "No" (still under 90 days)
7. Create approval task

**Result:**
```
Expense Report Created: ER-2025-1206-023
Status: Pending Approval (Manager)
Amount: $650.00 (Corporate Card)
Category: Travel
⚠️ Warning: 82 days since expense (90-day limit approaching)
Approval task created for: [Manager Name]
```

## Troubleshooting

### Error: Duplicate expense detected
**Cause:** Expense with same merchant, date, and amount already exists
**Solution:**
- Do NOT create duplicate record
- Return: "Duplicate expense detected: [ER-ID] created on [date] for $[amount] at [merchant]"
- Ask user to verify if this is a different expense

### Error: Missing required field
**Cause:** Receipt information incomplete (no amount, date, or merchant)
**Solution:**
- Do NOT create incomplete record
- Return: "Missing required field: [field name]"
- Request user provide missing information

### Error: Policy violation - Late submission
**Cause:** Expense older than 90 days
**Solution:**
- Set `[latesubmission]` = "Yes"
- Set `[policyviolations]` = "Late submission: [X] days past 90-day limit"
- Create record but flag for additional approval
- Note: Requires Controller approval regardless of amount

### Error: Meals expense over threshold without attendees
**Cause:** Meal expense > $75/person but no attendee list provided
**Solution:**
- Do NOT create record
- Return: "Meals over $75/person require attendee list. Please provide names of attendees."
- Wait for user to provide attendee information

An expense entry is complete and valid when:
- ✓ Category correctly assigned in `[expensecategories]`
- ✓ Approval tier determined based on amount thresholds
- ✓ Payment method properly tracked in `[corporatecardamount]` or `[personalcardamount]`
- ✓ Duplicate check performed and `[duplicatestatus]` set
- ✓ 90-day policy validated with `[dayssinceexpense]` and `[latesubmission]`
- ✓ Billability correctly determined in `[billableamount]` and `[internalamount]`
- ✓ Record created in **Expense Report** table with all required fields
- ✓ Approval task created if `[approvaltier]` requires it
- ✓ `[reportstatus]` set appropriately based on approval requirements