PayloadCMS Greenhouse Plugin

A comprehensive PayloadCMS plugin that integrates with Greenhouse ATS (Applicant Tracking System) to manage job listings directly within your Payload admin dashboard.

🚀 Features

Core Functionality

• Job Management: View and manage Greenhouse job listings directly in Payload admin
• Real-time Sync: Fetch job data from Greenhouse API with automatic validation
• Dashboard Widget: Beautiful dashboard interface showing job statistics and quick actions
• Debug Tools: Built-in debugging endpoints for troubleshooting API connections

Job Board Integration

• Multiple Display Types: Support for accordion and cycle view layouts
• Customizable Forms: Support for both iframe and inline application forms
• Department Organization: Jobs organized by offices and departments
• Location Filtering: Filter jobs by location and office

Developer Features

• TypeScript Support: Full TypeScript definitions included
• Caching System: Configurable cache expiration for optimal performance
• Error Handling: Comprehensive error handling and logging
• Flexible Configuration: Multiple configuration options for different use cases

📦 Installation

npm install payload-greenhouse
# or
yarn add payload-greenhouse
# or
pnpm add payload-greenhouse

⚙️ Configuration

1. Environment Variables

Set up your environment variables in .env:

GREENHOUSE_URL_TOKEN=your_greenhouse_url_token
GREENHOUSE_API_KEY=your_greenhouse_api_key  # Optional, required for inline forms

2. Basic Plugin Setup

Add the plugin to your Payload configuration:

// payload.config.ts
import { buildConfig } from 'payload'
import { payloadGreenhouse } from 'payload-greenhouse'

export default buildConfig({
  // ... your other config
  plugins: [
    payloadGreenhouse({
      urlToken: process.env.GREENHOUSE_URL_TOKEN,
      apiKey: process.env.GREENHOUSE_API_KEY, // Optional
    }),
  ],
})

3. Advanced Configuration

payloadGreenhouse({
  // Required: Your Greenhouse URL token
  urlToken: process.env.GREENHOUSE_URL_TOKEN,

  // Optional: API key for inline application forms
  apiKey: process.env.GREENHOUSE_API_KEY,

  // Board display type: 'accordion' or 'cycle'
  boardType: 'accordion',

  // Form integration type: 'iframe' or 'inline'
  formType: 'iframe',

  // Cache expiration time in seconds (default: 3600 = 1 hour)
  cacheExpiryTime: 3600,

  // Transition effect for cycle view
  cycleFx: 'fade', // 'fade' | 'fadeout' | 'none' | 'scrollHorz'

  // Enable debug mode for additional logging
  debug: true,

  // Disable the plugin entirely
  disabled: false,

  // Disable the dashboard widget
  disableDashboard: false,

  // Add Greenhouse job board to specific collections
  collections: {
    posts: true,
    pages: true,
  },
})

🛠️ Usage

Managing Jobs

1. Navigate to Admin Dashboard: Open your Payload admin panel
2. Greenhouse Jobs Section: Find the "Greenhouse Jobs" collection under "Integrations"
3. Add New Job: Click "Create New" and enter a valid Greenhouse Job ID
4. Auto-sync: Job details will be automatically fetched and populated from Greenhouse

Job Collection Fields

When you add a job, the following fields are automatically populated:

| Field | Description | Source | | --------------- | ----------------------- | ---------------------- | | jobId | Greenhouse Job ID | User input (validated) | | title | Job title | Greenhouse API | | location | Job location | Greenhouse API | | department | Department name | Greenhouse API | | office | Office location | Greenhouse API | | publishedDate | Publication date | Greenhouse API | | updatedAt | Last update timestamp | Auto-generated | | absoluteUrl | Direct application link | Greenhouse API | | content | Job description | Greenhouse API | | companyName | Company name | Greenhouse API | | requisitionId | Internal requisition ID | Greenhouse API | | internalJobId | Internal job identifier | Greenhouse API |

Dashboard Widget

The plugin adds a dashboard widget that displays:

• Total number of available jobs
• Quick statistics by department and office
• Recent job updates
• Quick access to add new jobs
• Debug information (when enabled)

API Endpoints

The plugin exposes several API endpoints:

GET /api/greenhouse/jobs

Fetch all available jobs from Greenhouse

// Example response
;[
  {
    id: 12345,
    title: 'Senior Software Engineer',
    department: 'Engineering',
    office: 'San Francisco',
    location: 'San Francisco, CA',
    absoluteUrl: 'https://boards.greenhouse.io/company/jobs/12345',
    updatedAt: '2024-01-15T10:30:00Z',
  },
]

POST /api/greenhouse/apply

Submit job applications (requires API key)

POST /api/greenhouse/clear-cache

Clear the job cache

GET /api/greenhouse/debug

Debug endpoint for troubleshooting API connections

// Example response
{
  "success": true,
  "totalJobs": 25,
  "availableJobIds": [12345, 12346, 12347],
  "jobDetails": [
    {
      "id": 12345,
      "title": "Senior Software Engineer",
      "department": "Engineering",
      "office": "San Francisco"
    }
  ]
}

🏗️ Adding to Collections

You can add Greenhouse job board functionality to existing collections:

payloadGreenhouse({
  collections: {
    posts: true, // Add to posts collection
    pages: true, // Add to pages collection
    projects: true, // Add to projects collection
  },
})

This adds a greenhouseJobBoard field group to the specified collections with options to:

• Enable/disable job board for individual documents
• Override the default board type per document

🔧 Development

Project Structure

src/
├── index.ts                 # Main plugin configuration
├── components/              # React components
│   ├── BeforeDashboardServer.tsx   # Server-side dashboard component
│   ├── BeforeDashboardClient.tsx   # Client-side dashboard component
│   └── BeforeDashboardClient.module.css  # Styles
├── utils/                   # Utility functions
│   └── greenhouseApi.ts     # Greenhouse API integration
└── exports/                 # Export definitions
    ├── client.ts           # Client-side exports
    └── rsc.ts              # React Server Components exports

Building the Plugin

# Install dependencies
pnpm install

# Build the plugin
pnpm build

# Development mode
pnpm dev

# Run tests
pnpm test

# Lint code
pnpm lint

Testing

The plugin includes comprehensive tests:

# Run all tests
pnpm test

# Run with coverage
pnpm test --coverage

# Run specific test file
pnpm test integration.test.ts

🐛 Troubleshooting

Common Issues

"URL token not configured"

• Ensure GREENHOUSE_URL_TOKEN environment variable is set
• Verify the token is valid in the Greenhouse dashboard

"Job ID not found"

• Use the /api/greenhouse/debug endpoint to see available job IDs
• Ensure the job is published and active in Greenhouse

"Unauthorized access to Greenhouse API"

• Check that your URL token has proper permissions
• For inline forms, ensure GREENHOUSE_API_KEY is set correctly

Debug Mode

Enable debug mode for additional logging:

payloadGreenhouse({
  debug: true,
  // ... other options
})

API Connection Testing

Test your Greenhouse connection:

curl http://localhost:3000/api/greenhouse/debug

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

1. Fork the repository
2. Clone your fork: git clone https://github.com/your-username/payload-greenhouse.git
3. Install dependencies: pnpm install
4. Create a feature branch: git checkout -b feature/your-feature-name
5. Make your changes and add tests
6. Run tests: pnpm test
7. Submit a pull request

📞 Support

• GitHub Issues: Create an issue
• Documentation: Check this README and inline code comments
• Community: Join the PayloadCMS Discord community

🔗 Related Links

• PayloadCMS Documentation
• Greenhouse API Documentation
• Plugin Development Guide