Carerix sync

A WordPress plugin to sync vacancies from Carerix ATS to WordPress posts.

Description

Carerix Sync is a lightweight WordPress plugin that connects to the Carerix GraphQL API to fetch job vacancies and automatically create WordPress posts. The plugin provides an easy-to-use interface for syncing vacancies with preview and confirmation before creating posts.

✨ Features

• 🔐 OAuth 2.0 Authentication: Secure connection to Carerix API using client credentials flow
• 🔍 GraphQL Integration: Fetches vacancies using Carerix GraphQL API with server-side filtering
• ✅ Active Vacancies Only: Automatically filters to only sync active vacancies (publicationEnd in the future)
• 🌐 REST API Endpoints: Uses WordPress REST API for better debugging and network visibility
• 👀 Preview Before Sync: Review fetched vacancies before creating WordPress posts
• ⚡ Batch Processing: Creates posts in batches to prevent CPU overload
• 🚫 Duplicate Prevention: Automatically skips vacancies that have already been synced
• 📝 Custom Post Type: Creates a dedicated "Vacancy" post type for synced jobs
• 📊 Rich Metadata: Stores all Carerix data as custom fields for easy access
• 🐛 Debug Panel: View raw API responses to troubleshoot and discover available fields

📦 Installation

1. 📤 Upload the plugin files to /wp-content/plugins/carerix-sync/
2. ✅ Activate the plugin through the 'Plugins' menu in WordPress
3. ⚙️ Go to Carerix > Settings to configure your API credentials

Note: The plugin includes all dependencies (vendor directory), so no Composer installation is required.

⚙️ Configuration

🔑 Setting up Carerix API Access

1. 🔐 Log in to your Carerix application as an administrator
2. 📍 Navigate to Maintenance > Identity Access > Clients
3. ➕ Click New and create a Confidential Client
4. ⚙️ Configure the client:
   • Name: Give it a descriptive name (e.g., "WordPress Sync")
   • Code: Use format urn:{vendor}/{unique name}
   • Default Scopes: Set to urn:cx/cx5Wrapper:data:manage
   • Active: Set to YES
5. 🔗 Click OpenID Configuration to get the token endpoint URL
6. 📝 Note your Client ID and Client Secret

🔧 Plugin Settings

1. 🎯 Go to Carerix > Settings in WordPress admin
2. ✏️ Enter your Carerix API credentials:
   • Token URL: The token endpoint from OpenID Configuration
   • Client ID: Your client ID
   • Client Secret: Your client secret
   • Scope: urn:cx/cx5Wrapper:data:manage (default)
3. 🧪 Click Test Connection to verify your credentials
4. 💾 Click Save Changes

Usage

Syncing Vacancies

1. Go to Carerix in the WordPress admin menu
2. Click Sync Vacancies
3. Review the preview table showing fetched vacancies
4. Check the debug panel (if needed) to see the raw API response
5. Click Confirm & Create Posts to create WordPress posts
6. Posts are created as drafts - you can review and publish them manually

Managing Synced Vacancies

• View all synced vacancies: Carerix > Vacancies
• Edit individual vacancies to review and publish
• All Carerix metadata is stored as custom fields and visible in the post editor

How Active Vacancies Are Filtered

The plugin automatically filters vacancies to only sync active ones:

• Publication Start: Must be in the past or today
• Publication End: Must be in the future (or null/empty)

This ensures you only sync vacancies that are currently active, even if your Carerix system has thousands of historical vacancies.

Batch Processing

When creating posts, the plugin processes them in batches of 50 to prevent CPU overload. This is especially important when syncing large numbers of vacancies (e.g., 900+). The plugin will show progress and batch information in the success message.

📋 Requirements

• ✅ WordPress 5.0 or higher
• ✅ PHP 7.4 or higher
• ✅ Valid Carerix API credentials

📦 Dependencies

• Guzzle HTTP Client (^7.10): For making HTTP requests to Carerix API
  • ✅ Included in the plugin (vendor directory)
  • ✅ No separate installation required

💻 Development

📁 Project Structure

carerix-sync/
├── assets/
│   ├── js/
│   │   └── admin.js          # Admin JavaScript
│   └── img/
│       └── carerix.svg       # Plugin icon
├── src/
│   ├── Admin/
│   │   ├── Admin.php         # Main admin class (REST API routes)
│   │   ├── PostType.php      # Custom post type registration
│   │   └── Settings.php      # Settings page
│   ├── Api/
│   │   └── Client.php        # GraphQL API client
│   └── Sync/
│       └── SyncService.php   # Vacancy sync logic with filtering
├── templates/
│   ├── admin-page.php        # Main admin page template
│   ├── settings-page.php     # Settings page template
│   └── fields/
│       └── text-field.php    # Text field template
├── vendor/                    # Composer dependencies
├── carerix-sync.php          # Main plugin file
├── composer.json             # Composer configuration
└── README.md                 # This file

🔨 Building

The plugin includes all dependencies in the vendor/ directory. If you need to update dependencies:

# Update dependencies (optional, only if you modify composer.json)
composer update

# Install dependencies (optional, only if vendor/ is missing)
composer install

Note: For end users, no Composer installation is needed as all dependencies are included.

💬 Support

• 👤 Developer: Bas van de Kamer
• 📧 Email: bas@alterio.nl
• 🐙 GitHub: https://github.com/basduchambre/carerix-sync

📄 License

This plugin is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

This plugin is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

📝 Changelog

🎉 1.0.0

• 🎊 Initial release
• 🔐 OAuth 2.0 authentication with fallback support
• 🔍 GraphQL API integration with server-side filtering
• ✅ Active vacancies filtering (publicationEnd in the future)
• 🌐 REST API endpoints for better debugging
• 🔄 Vacancy syncing with preview and confirmation
• ⚡ Batch processing for post creation (prevents CPU overload)
• 📝 Custom post type for vacancies
• 📊 Rich metadata storage with custom fields
• 🐛 Debug panel for API response inspection
• 📄 Pagination support with maximum page size (100 items)
• 🚫 Duplicate prevention using publication ID
• 📦 All dependencies included (no Composer required for installation)