> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# FM Vendor Management - Administrator Guide

> Module: FM-03 Vendor Management Audience: Facilities Managers, Org Admins, FM Administrators Last Updated: 2025-12-07

**Module:** FM-03 Vendor Management\
**Audience:** Facilities Managers, Org Admins, FM Administrators\
**Last Updated:** 2025-12-07

***

## Overview

This guide covers administrative tasks for the Vendor Management module, including vendor setup, certification tracking, performance monitoring, and integration with work orders and accounts payable.

***

## Initial Setup

### 1. Configure Module Settings

Before adding vendors, configure module-level settings:

1. Navigate to **Facilities → Settings → Vendors**
2. Configure:
   * **Require Vendor Certification**: Whether certifications are required for work order assignment
   * **Default Certification Alert Days**: When to alert before expiration (default: 90, 60, 30)
   * **Vendor Approval Required**: Whether new vendors need approval
   * **Preferred Vendor Limit Per Category**: Maximum preferred vendors per service category

### 2. Create Vendors

To add a new vendor:

1. Navigate to **Facilities → Vendors**
2. Click **Add Vendor**
3. Enter required fields:
   * **Company Name**: Vendor's legal business name
   * **Vendor Category**: Primary service type
4. Enter contact information:
   * **Primary Contact Name**
   * **Phone Number**
   * **Email Address**
   * **Business Address**
5. Enter optional fields:
   * **Hourly Rate**: Standard billing rate
   * **Tax ID** (EIN/SSN): For 1099 reporting
   * **Notes**: Additional information
6. Click **Add Vendor**

**Note:** New vendors start with "Pending Approval" status if approval workflow is enabled.

### 3. Assign Service Sites

Link vendors to specific sites they can service:

1. Open the vendor detail page
2. Go to the **Sites** tab
3. Click **Add Site**
4. Select the site(s) the vendor services
5. Optionally mark as **Preferred Vendor** for that site
6. Click **Save**

### 4. Add Certifications

Track vendor compliance documents:

1. Open the vendor detail page
2. Go to the **Certifications** tab
3. Click **Add Certification**
4. Enter:
   * **Certification Type**: COI, License, Bonding, or Other
   * **Certification Name**: Specific name (e.g., "General Liability Insurance")
   * **Certificate Number** (optional)
   * **Issuing Authority** (optional)
   * **Effective Date**
   * **Expiration Date**
   * **Coverage Amount** (for insurance)
5. Upload the certificate document (optional)
6. Click **Save**

***

## Vendor Categories

The system supports these service categories:

| Category               | Common Services                                   |
| ---------------------- | ------------------------------------------------- |
| **Plumbing**           | Pipe repair, drain cleaning, fixture installation |
| **Electrical**         | Wiring, panel upgrades, lighting                  |
| **HVAC**               | Heating, cooling, ventilation, refrigeration      |
| **Janitorial**         | Cleaning, floor care, waste management            |
| **Landscaping**        | Lawn care, tree service, irrigation               |
| **Security**           | Alarm systems, access control, guards             |
| **General Contractor** | Construction, renovation, multi-trade             |
| **Other**              | Specialty services not listed above               |

***

## Certification Management

### Certification Types

| Type        | Description                | Common Documents                       |
| ----------- | -------------------------- | -------------------------------------- |
| **COI**     | Certificate of Insurance   | General liability, workers comp, auto  |
| **License** | Professional/trade license | Contractor license, electrical license |
| **Bonding** | Surety bond                | Payment bond, performance bond         |
| **Other**   | Additional requirements    | W-9, service agreements                |

### Expiration Alerts

The system monitors certification expiration dates:

| Alert Level | Days Before Expiration | Action                               |
| ----------- | ---------------------- | ------------------------------------ |
| 90-day      | 90 days                | Informational alert                  |
| 60-day      | 60 days                | Warning alert                        |
| 30-day      | 30 days                | Urgent alert                         |
| Expired     | Past due               | Critical alert, may block assignment |

### Edge Function: Automated Checks

The `check-vendor-certifications` edge function runs daily to:

* Update certification alert flags
* Mark expired certifications
* Generate notifications for upcoming expirations

***

## Performance Tracking

### Performance Metrics

The system automatically tracks:

| Metric                  | Calculation                                |
| ----------------------- | ------------------------------------------ |
| **Total Work Orders**   | Count of assigned work orders              |
| **Completion Rate**     | Completed / Total assigned                 |
| **Avg Completion Time** | Average days from assignment to completion |
| **On-Time Rate**        | Completed by due date / Total completed    |
| **Satisfaction Rating** | Average of work order ratings (1-5)        |

### Viewing Performance

1. Open the vendor detail page
2. Go to the **Performance** tab
3. View:
   * Current metrics summary
   * Trend charts over time
   * Work order history

### Using Performance Data

* **Preferred Vendor Selection**: Use metrics to identify top performers
* **Vendor Reviews**: Schedule reviews with low-performing vendors
* **Rate Negotiations**: Use data to justify rate discussions

***

## Work Order Integration

### Assigning Vendors

When assigning vendors to work orders:

1. The system validates:
   * Vendor is active
   * Vendor is approved (if required)
   * Vendor has valid certifications (if required)
   * Vendor serves the work order site

2. If validation fails, the assignment is blocked with a clear message

### Assignment Workflow

```
Pending → Accepted → In Progress → Completed → Invoiced → Paid
                 ↓
              Declined
```

### Tracking Vendor Assignments

The `fm_vendor_work_orders` table tracks:

* Assignment status and dates
* Quote information
* Scheduled work date
* Actual start/end times
* Invoice and payment status

***

## Tax & Payment Information

### Tax ID Management

For 1099 reporting, vendors can store:

* **EIN** (Employer Identification Number): XX-XXXXXXX
* **SSN** (Social Security Number): XXX-XX-XXXX

**Security:**

* Tax IDs are masked in the UI (showing only last 4 digits)
* Full access requires appropriate permissions
* Data is encrypted at rest

### Payment Tracking

Each vendor assignment tracks:

* **Quote Amount**: Initial estimate
* **Invoice Number**: Vendor's invoice reference
* **Invoice Amount**: Actual billed amount
* **Invoice Date**: Date invoice received
* **Payment Status**: Pending, Approved, Paid
* **Payment Date**: When payment was processed

***

## Security & Access Control

### Role-Based Permissions

| Role               | View Vendors | Assign to WO | Create/Edit | Manage Settings |
| ------------------ | ------------ | ------------ | ----------- | --------------- |
| Platform Admin     | ✅            | ✅            | ✅           | ✅               |
| Org Admin          | ✅            | ✅            | ✅           | ✅               |
| FM Admin           | ✅            | ✅            | ✅           | ✅               |
| Facilities Manager | ✅            | ✅            | ✅           | ❌               |
| Staff              | ✅            | ✅            | ❌           | ❌               |
| View Only          | ✅            | ❌            | ❌           | ❌               |

### Multi-Tenant Isolation

* Vendors are organization-specific
* RLS policies enforce organization boundaries
* No cross-organization vendor access

### Audit Trail

All changes are tracked:

* Created by / created at
* Updated by / updated at
* Certification changes logged
* Assignment status changes logged

***

## Integration with Other Modules

### Work Orders (FM-01)

* Vendors assigned to work orders via `fm_vendor_work_orders`
* Work order costs include vendor costs
* Vendor performance updated on work order completion

### Inventory (FM-02) - Future

* Link vendors as preferred suppliers for inventory items
* Vendor catalogs with item pricing
* Automatic vendor selection for reorders

### Accounts Payable (FA-03) - Future

* Vendor invoices flow to AP for processing
* 3-way match: Work order ↔ Invoice ↔ Payment
* Vendor payment terms and discounts

### Purchase Orders (FA-04) - Future

* Create POs for vendor work
* Track vendor quotes vs actuals
* Vendor contract pricing

***

## Module Settings Reference

| Setting                        | Description                                | Default       |
| ------------------------------ | ------------------------------------------ | ------------- |
| `require_vendor_certification` | Block assignment if certifications expired | true          |
| `certification_alert_days`     | Days before expiration to alert            | \[90, 60, 30] |
| `vendor_approval_required`     | New vendors need approval                  | true          |
| `max_preferred_per_category`   | Limit preferred vendors                    | 3             |
| `auto_update_performance`      | Update metrics on WO completion            | true          |

***

## Troubleshooting

### Common Issues

**Cannot assign vendor to work order**

1. Check vendor status is Active
2. Check vendor is Approved
3. Check certifications are valid
4. Verify vendor serves the work order's site

**Certification alerts not sending**

1. Verify notification settings
2. Check edge function is running
3. Confirm expiration dates are set correctly

**Performance metrics not updating**

1. Ensure work orders are marked as completed
2. Check trigger function is enabled
3. Manually trigger recalculation if needed

**Tax ID validation errors**

1. EIN format: XX-XXXXXXX or XXXXXXXXX
2. SSN format: XXX-XX-XXXX or XXXXXXXXX
3. Remove extra spaces or special characters

***

## Best Practices

1. **Regular Reviews**: Review vendor certifications monthly
2. **Performance Monitoring**: Check low performers quarterly
3. **Documentation**: Keep digital copies of all certifications
4. **Site Assignment**: Keep vendor-site mappings current
5. **Preferred Vendors**: Limit to top 2-3 per category
6. **Tax Documentation**: Collect W-9 before first payment
7. **Contact Updates**: Verify contact info annually

***

## Need Help?

* **Technical Issues**: Contact system administrator
* **Process Questions**: Contact Facilities Manager
* **Feature Requests**: Submit through feedback system