Providers

Overview

The Providers feature manages external service providers, their contracts, location associations, and integration credentials. It supports provider types, activation tracking, API integration, and comprehensive notes for provider relationships.

Key Features

Provider Management

• Provider Profiles: Complete provider information including contact details and address
• Provider Types: Categorize providers (Agency, Vendor, Partner, etc.)
• API Integration: Store API credentials (username, password, API keys, tokens)
• Active Status: Track active/inactive providers
• API Support Flag: Indicate if provider supports API integration

Location Associations

• LocationProvider Junction: Link providers to specific locations
• Activation Tracking: Record who activated provider at each location and when
• Deactivation Tracking: Record who deactivated provider and when
• Multiple Locations: One provider can serve multiple locations
• Multiple Providers: One location can have multiple providers

Contract Management

• ProviderContract: Track contracts between tenant and providers
• Contract Details: Terms, dates, and agreement information
• Provider Relationship: Link contracts to specific providers

Notes and Documentation

• ProviderNote: Store notes about providers
• User Attribution: Track who created each note
• Timestamps: Automatic note timestamping

Database Models

Provider Model

model Provider {
  id                   String             @id @default(cuid())
  createdAt            DateTime           @default(now())
  tenantId             String
  tenant               Tenant             @relation(fields: [tenantId], references: [id])
  createdByUserId      String?
  createdByUser        User?              @relation("createdByUser", fields: [createdByUserId], references: [id])
  lastModifiedByUserId String?
  lastModifiedByUser   User?              @relation("modifiedByUser", fields: [lastModifiedByUserId], references: [id])
  name                 String
  accountNumber        String
  email                String
  phone                String
  contactName          String
  addressLine1         String
  addressLine2         String
  city                 String
  state                String
  postalCode           String
  country              String
  username             String
  password             String
  apiKey               String
  token                String
  type                 String             @default("Agency")
  notes                String
  allowsApi            Boolean            @default(false)
  active               Boolean            @default(true)
  LocationProvider     LocationProvider[]
  ProviderContract     ProviderContract[]
  ProviderNote         ProviderNote[]
}

LocationProvider Model

Association between providers and locations:

model LocationProvider {
  id              String    @id @default(cuid())
  createdAt       DateTime  @default(now())
  tenantId        String
  tenant          Tenant    @relation(fields: [tenantId], references: [id])
  locationId      String
  location        Location  @relation(fields: [locationId], references: [id])
  providerId      String
  provider        Provider  @relation(fields: [providerId], references: [id])
  activatedOn     DateTime  @default(now())
  activatedById   String?
  activatedBy     User?     @relation("providerActivatedBy", fields: [activatedById], references: [id])
  deactivatedOn   DateTime?
  deactivatedById String?
  deactivatedBy   User?     @relation("providerDeactivatedBy", fields: [deactivatedById], references: [id])
}

ProviderContract Model

model ProviderContract {
  id         String   @id @default(cuid())
  createdAt  DateTime @default(now())
  updatedAt  DateTime @updatedAt
  tenantId   String
  tenant     Tenant   @relation(fields: [tenantId], references: [id])
  providerId String
  provider   Provider @relation(fields: [providerId], references: [id])
  title      String
  details    String   @db.NVarChar(max)
  startDate  DateTime
  endDate    DateTime?
  value      Decimal?
  status     String   @default("active")
}

ProviderType Model

model ProviderType {
  id        String   @id @default(cuid())
  createdAt DateTime @default(now())
  name      String
  order     Int      @default(0)
}

ProviderNote Model

model ProviderNote {
  id              String   @id @default(cuid())
  createdAt       DateTime @default(now())
  providerId      String
  provider        Provider @relation(fields: [providerId], references: [id])
  content         String   @db.NVarChar(max)
  createdByUserId String?
  createdByUser   User?    @relation(fields: [createdByUserId], references: [id])
}

Provider Types

Common provider types (configurable):

• Agency: Third-party agencies providing services
• Vendor: Product or service vendors
• Partner: Strategic business partners
• Consultant: Professional consultants
• Contractor: Independent contractors

Provider types can be managed via ProviderType model with custom ordering.

Location-Provider Associations

Activation Flow

1. Create LocationProvider record
2. Set activatedOn to current date
3. Record activatedById for audit trail
4. Provider becomes active at that location

Deactivation Flow

1. Update LocationProvider record
2. Set deactivatedOn to current date
3. Record deactivatedById for audit trail
4. Provider no longer active at that location

Tracking Benefits

• Audit Trail: Complete history of provider activations/deactivations
• User Attribution: Know who made each change
• Temporal Queries: Query active providers as of any date
• Reporting: Provider utilization reports by location and time period

API Integration

Credentials Storage

Providers can store API integration credentials:

{
  username: string;      // API username
  password: string;      // API password
  apiKey: string;        // API key
  token: string;         // Auth token
  allowsApi: boolean;    // Flag if API is supported
}

Security Considerations

1. Encryption: Credentials should be encrypted at rest
2. Access Control: Limit who can view/edit credentials
3. Rotation: Implement credential rotation policies
4. Audit Logging: Log all credential access

Contract Management

Contract Lifecycle

1. Create Contract: Define terms, dates, and value
2. Active Status: Track contract status (active, expired, terminated)
3. End Date: Optional end date for term-limited contracts
4. Value Tracking: Store contract value in decimal format
5. Details: Rich text field for contract specifics

Contract Queries

Common queries:

• Active contracts for a provider
• Contracts expiring soon
• Total contract value by provider
• Contracts by status

Notes and Documentation

Provider Notes

Store contextual information about providers:

• Communication logs
• Service quality notes
• Issue tracking
• Performance observations
• Contact preferences

Note Features

• User Attribution: Track note creators
• Timestamps: Automatic creation timestamps
• Rich Content: Support for detailed text content
• Provider Association: Notes linked to specific providers

Best Practices

1. Complete Profiles: Fill all provider contact information
2. Credential Security: Treat API credentials as sensitive data
3. Active Status: Keep provider active status current
4. Location Associations: Document provider-location relationships
5. Contract Tracking: Maintain accurate contract records
6. Note Taking: Document important provider interactions
7. Type Classification: Use consistent provider types
8. Audit Trail: Review activation/deactivation history regularly

Common Operations

Create Provider

1. Enter provider details (name, contact, address)
2. Set provider type
3. Add account number and contact name
4. Configure API credentials if applicable
5. Set active status
6. Save provider profile

Associate Provider with Location

1. Select provider and location
2. Create LocationProvider record
3. Set activation date (defaults to now)
4. Record activating user
5. Provider now active at location

Deactivate Provider at Location

1. Find LocationProvider record
2. Set deactivation date
3. Record deactivating user
4. Provider no longer active at that location

Create Provider Contract

1. Select provider
2. Enter contract title and details
3. Set start date and optional end date
4. Enter contract value
5. Set status (active by default)
6. Save contract

Add Provider Note

1. Navigate to provider profile
2. Create new note
3. Enter note content
4. Save (user and timestamp auto-recorded)

Integration Points

• Locations: Provider-location associations via LocationProvider
• Contracts: Contract management via ProviderContract
• Users: Track creators, modifiers, activators, deactivators
• Tenants: Multi-tenant isolation for provider data
• Notes: Detailed provider documentation
• Types: Categorize providers by type

Reporting and Analytics

Potential reports:

• Active providers by location
• Provider activation history
• Contract value by provider
• Contract expiration schedule
• Provider utilization metrics
• API-enabled vs manual providers
• Provider notes and issue trends