README

by billy in Blog

Ada ATS – A Retro, Gamified ATS (Applicant Tracking System) for WordPress

For support, visit: wilcosky.com/contact

A comprehensive Applicant Tracking System built as a WordPress theme, featuring resume parsing, candidate management, requisition workflows, gamification, and embeddable job listings.

To test Ada out, tap the login button above. Then, see that light blue bar at the top? It lists usernames and a password you may use. Each username lets you demo a different type of user with different permissions.

  • Log in as the Hiring Manager to submit a new requisition
  • Log in as the Req Approver to approve a new requisition
  • Log in as the Recruiter for everything else

This is a demo which is periodically reset. Still, please be professional and do not publish anything nasty.

Key Features:

  • ✅ Fully dynamic candidate status system (no hardcoded status names required)
  • ✅ Custom requisition and application form fields
  • ✅ Intelligent resume parsing with automatic field population
  • ✅ Per-requisition candidate status tracking
  • ✅ Gamification system with points and achievements
  • ✅ Game Mode for engaging candidate interactions
  • ✅ Embeddable job listings for external websites

Table of Contents

  1. Installation
  2. Initial Setup
  3. User Roles & Permissions
  4. Resume Parsing
  5. Requisition Management
  6. Candidate Management
  7. Public Job Listings
  8. Embed System
  9. Gamification System
  10. Settings & Configuration
  11. Testing the System
  12. Troubleshooting

Installation

Prerequisites

  • WordPress 5.0 or higher
  • PHP 7.4 or higher
  • MySQL 5.6 or higher
  • Required PHP extensions:
    • gd or imagick (for image processing)
    • mbstring (for text processing)
    • zip (for file handling)
    • xml (for PDF parsing)

Step 1: Install WordPress

If you don’t have WordPress installed:

  1. Download WordPress from wordpress.org
  2. Extract and upload to your web server
  3. Create a MySQL database for WordPress
  4. Run the WordPress installation wizard
  5. Complete the initial WordPress setup

Step 2: Install the Ada Theme

  1. Upload the Ada theme folder to /wp-content/themes/
  2. Log in to your WordPress admin dashboard
  3. Navigate to Appearance > Themes
  4. Find “Ada” in the theme list
  5. Click Activate

Step 3: Flush Permalinks

After activation:

  1. Go to Settings > Permalinks
  2. Click Save Changes (even if you don’t change anything)
  3. This registers the custom ATS routes (/ats/*)

Step 4: Verify Installation

  1. Visit http://yoursite.com/wp-admin/themes.php?page=ada-theme-settings
  2. You should see the Ada Settings page
  3. If you see a 404, go to Settings > Permalinks and save again

Initial Setup

1. Configure Basic Settings

Navigate to Appearance > Ada Settings (or directly to wp-admin/themes.php?page=ada-theme-settings).

General Tab

  • Logo: Upload your company logo (recommended: 45px height)
  • Favicon: Upload a favicon for browser tabs
  • Timezone: Set your timezone for accurate timestamps
  • Cloudflare Turnstile (optional):
    • Site Key: Your Turnstile site key
    • Secret Key: Your Turnstile secret key
    • Leave blank if not using Turnstile (for development/testing)

Application Form Tab

Configure the fields that appear on public job application forms:

  • Default Fields: Name, Email, Phone, Cover Letter, Resume
  • Add Custom Fields: Click “Add Field” to add text, textarea, select, checkbox, or file upload fields
  • Field Options:
    • Type: text, email, textarea, select, checkbox, file
    • Label: Display name for the field
    • Name: Internal field name (lowercase, no spaces)
    • Required: Check if field is mandatory

Requisition Form Tab

Configure the fields that appear when submitting new requisitions:

  • Default Fields: Job Title, Location, Department, Salary Range, Job Description (used if no custom fields configured)
  • Add Custom Fields: Click “Add Field” to add text, email, textarea, select, checkbox, file, number, tel, url, or date fields
  • Field Options:
    • Type: text, email, textarea, select, checkbox, file, number, tel, url, date
    • Label: Display name for the field
    • Name: Internal field name (lowercase, no spaces)
    • Required: Check if field is mandatory
    • Options: For select fields, enter options one per line
  • Dynamic Rendering: All configured fields automatically appear on the requisition submission form
  • Note: Job Title and Job Description fields are always required (if they exist in your configuration)

Candidate Statuses Tab

Configure the status workflow for candidates:

  • Default Statuses: Review, Screened, Interview, Offer, Hired, Rejected (used if none configured)
  • Add Status: Click “Add Status” to create new statuses
  • Add Steps: Each status can have sub-steps (e.g., Interview can have Interview 1, Interview 2, Interview 3)
  • Reorder: Drag statuses to reorder them
  • Status Options:
    • Name: Display name (e.g., “Phone Screen”)
    • Slug: Internal identifier (e.g., “phone_screen”)

Status Requirements:

  • Minimum: At least one status is required (becomes the default starting status)
  • Recommended: Include a status with “rejected” in the name/slug for proper rejection handling
  • Recommended: Include a status with “hire” or “hired” in the name/slug for hiring functionality
  • Note: The system intelligently detects these statuses by searching for keywords in names/slugs (case-insensitive)
  • Fallback: If no “rejected” status is found, the system uses the last status in your list
  • Fallback: If no “hired” status is found, hiring features will be unavailable

See STATUS_REQUIREMENTS.md for detailed information about status configuration.

Gamification Tab

Configure the points system for recruiters:

  • Points Map: Set points awarded for each action:
    • hourly: Points per hour logged in (default: 1)
    • candidate_reviewed: Points for reviewing a candidate (default: 0.5)
    • status_progression: Points for moving a candidate forward (default: 0.5)
    • Custom status points: Points for moving to specific statuses
  • Spend Points Email: Email address to receive notifications when recruiters spend points

Embed Settings Tab

Configure the embed system for external job listings:

  • API Key: Generate a unique API key for embed authentication
  • Whitelist Domains: Add domains allowed to embed your jobs (one per line)
    • Example: example.com, jobs.example.com
    • Leave blank to allow all domains (not recommended for production)

Retro Theme Tab

Customize the retro terminal aesthetic:

  • Colors: Adjust color scheme
  • Font: Choose font family
  • Scanlines: Toggle scanline effect

2. Create User Accounts

Navigate to Users > Add New to create user accounts for your team.

Adding a User

  1. Username: Choose a unique username
  2. Email: Enter a valid email address
  3. Password: Set a strong password (or let WordPress generate one)
  4. Role: Select one of the following:
    • Administrator: Full access to WordPress and ATS
    • Editor: Full ATS access (can manage all candidates and requisitions)
    • Recruiter: Can manage candidates, update statuses, view requisitions
    • Hiring Manager: Can view candidates, create and edit requisitions
    • ATS Approver: Can approve requisitions and assign recruiters
  5. Click Add New User

Setting User Roles

After creating a user, you can change their role:

  1. Go to Users > All Users
  2. Find the user
  3. Click Edit
  4. Change the Role dropdown
  5. Click Update User

User Roles & Permissions

Administrator

WordPress Role: administrator

Capabilities:

  • ✅ Full WordPress access
  • ✅ Manage all ATS settings
  • ✅ Create, edit, delete candidates
  • ✅ Create, edit, delete requisitions
  • ✅ Approve requisitions
  • ✅ Assign recruiters
  • ✅ Update candidate statuses
  • ✅ Manage gamification settings
  • ✅ View all data

Use Case: Site owners, IT administrators, system managers

Editor

WordPress Role: editor

Capabilities:

  • ✅ Manage all ATS settings
  • ✅ Create, edit, delete candidates
  • ✅ Create, edit, delete requisitions
  • ✅ Approve requisitions
  • ✅ Assign recruiters
  • ✅ Update candidate statuses
  • ✅ Manage gamification settings
  • ✅ View all data
  • ❌ Limited WordPress access (no plugin/theme management)

Use Case: HR managers, ATS administrators who need full ATS control without WordPress admin access

Recruiter

WordPress Role: ada_recruiter

Capabilities:

  • ✅ View all candidates
  • ✅ Edit all candidates (including others’ candidates)
  • ✅ View all requisitions
  • ✅ Edit requisitions
  • ✅ Submit new requisitions
  • ✅ Update candidate statuses
  • ✅ Screen candidates
  • ✅ Move candidates to interview
  • ✅ Move candidates to offer
  • ✅ Hire candidates
  • ✅ Rate candidates (star ratings)
  • ✅ Add notes and timeline events
  • ✅ Assign tags to candidates
  • ✅ View and earn points
  • ❌ Cannot delete candidates
  • ✅ Can approve requisitions
  • ✅ Can assign recruiters
  • ❌ Cannot manage settings

Use Case: Recruiters who actively manage candidates through the hiring process

Access Points:

  • Dashboard: /ats/dashboard
  • Candidates: /ats/candidates
  • Candidate Details: /ats/candidate/{id}
  • Requisitions: /ats/requisitions
  • Requisition Details: /ats/requisition/{id}
  • Submit Requisition: /ats/submit-requisition
  • Points: /ats/points

Hiring Manager

WordPress Role: ada_hiring_manager

Capabilities:

  • ✅ View all candidates
  • ✅ View all requisitions
  • ✅ Create new requisitions
  • ✅ Edit requisitions
  • ❌ Cannot edit candidates
  • ❌ Cannot update candidate statuses
  • ❌ Cannot approve requisitions
  • ❌ Cannot assign recruiters
  • ❌ Cannot manage settings

Use Case: Department managers who need to create job postings and view applicants

Access Points:

  • Dashboard: /ats/dashboard
  • Candidates: /ats/candidates (view only)
  • Candidate Details: /ats/candidate/{id} (view only)
  • Requisitions: /ats/requisitions
  • Requisition Details: /ats/requisition/{id}
  • Submit Requisition: /ats/submit-requisition

ATS Approver

WordPress Role: ada_approver

Capabilities:

  • ✅ View all requisitions
  • ✅ Edit requisitions
  • ✅ Submit new requisitions
  • ✅ Approve requisitions
  • ✅ Assign recruiters to requisitions
  • ✅ Can view candidates
  • ❌ Cannot manage settings

Use Case: HR directors or executives who approve job postings and assign recruiters

Access Points:

  • Dashboard: /ats/dashboard
  • Requisitions: /ats/requisitions
  • Requisition Details: /ats/requisition/{id}
  • Submit Requisition: /ats/submit-requisition

Resume Parsing

How It Works

The Ada ATS automatically parses uploaded resumes to extract:

  1. Contact Information:
    • Name (from header section)
    • Email address
    • Phone number
  2. Skills:
    • Programming languages (JavaScript, Python, Java, etc.)
    • Frameworks (React, Angular, Django, etc.)
    • Design tools (Photoshop, Figma, etc.)
    • Business tools (Excel, Salesforce, etc.)
    • Soft skills (Leadership, Communication, etc.)
    • Industry-specific skills (Accounting, Healthcare, etc.)
  3. Extracted Text:
    • Full text content of the resume
    • Preserved formatting and structure
    • Available for search and review

Supported File Formats

  • PDF (.pdf): Text-based and image-based PDFs
    • Uses Smalot/PdfParser library for extraction
  • Word Documents:
    • .docx (Word 2007+): Full support via ZIP/XML extraction
    • .doc (Word 97-2003): Basic support via text extraction (may have limitations with complex formatting)

Parsing Process

When a candidate uploads a resume:

  1. Upload: File is uploaded to WordPress media library
  2. Parse: System extracts text using appropriate parser (PDF or Word)
  3. Extract Contact Info: Name, email, and phone are identified
  4. Extract Skills: Comprehensive skill patterns are matched against resume text
  5. Store: All data is saved to the candidate profile
  6. Auto-fill: Application form fields are automatically populated

Step-by-Step Feedback

During resume upload, candidates see real-time progress:

  • “Uploading resume…”
  • “Resume uploaded.”
  • “Parsing resume…”
  • “Saving extracted text…”
  • “Pulling out skills…”
  • “Looking at the application fields…”
  • “These fields were detected: [list]”
  • “I see a name in the extracted resume text…”
  • “Populating the name field…”
  • “I see an email…”
  • “Populating the email field…”
  • “I see a phone number…”
  • “Populating the phone field…”
  • “Success!”

Viewing Parsed Data

On the candidate detail page (/ats/candidate/{id}):

  1. Extracted Text: Scrollable box showing the full parsed resume text
  2. Tags: Automatically extracted skills displayed as tags
  3. Contact Info: Name, email, and phone (if extracted)

Troubleshooting Parsing

If parsing fails:

  1. Check File Format: Ensure file is PDF or Word document
  2. Check File Size: Large files (>10MB) may timeout
  3. Check File Type: Image-only PDFs may not parse correctly
  4. Check Server Logs: Review PHP error logs for parsing errors
  5. Check PHP Extensions: Ensure required extensions are installed

Requisition Management

Requisition Workflow

  1. Submit: Hiring Manager, Recruiter, ATS Approver, Administrator, or Editor creates a requisition
  2. Pending: Requisition awaits approval
  3. Approved: ATS Approver approves the requisition
  4. Assign Recruiter: ATS Approver assigns a recruiter (optional)
  5. Post: Requisition becomes visible on public job listings
  6. Close: Requisition is closed (no longer accepting applications)

Creating a Requisition

Who Can Create: Hiring Managers, Recruiters, ATS Approvers, Administrators, Editors

Steps:

  1. Navigate to /ats/submit-requisition (or click “New Requisition” in sidebar)
  2. Fill in the form fields. The form dynamically displays all fields configured in Settings > Requisition Form:
    • Default Fields: Job Title, Location, Department, Salary Range, Job Description
    • Custom Fields: Any additional fields you’ve configured (automatically rendered)
    • Field types supported: text, email, textarea, select, checkbox, file, number, tel, url, date
    • Job Description: Uses rich text editor (Quill) for formatted content
  3. All configured fields are automatically included and validated
  4. Click Submit Requisition

Status After Submission: pending

Note: The requisition form supports dynamic custom fields. Add custom fields in Appearance > Ada Settings > Requisition Form, and they will automatically appear on the submission form.

Approving a Requisition

Who Can Approve: ATS Approvers, Administrators, Editors

Steps:

  1. Navigate to /ats/requisitions
  2. Find the requisition with status “Pending”
  3. Click on the requisition to view details
  4. Click Approve Requisition
  5. (Optional) Assign a recruiter from the dropdown
  6. Click Save

Status After Approval: approved (visible on public listings) or approved_unposted (not visible)

Assigning a Recruiter

Who Can Assign: ATS Approvers, Administrators, Editors

Steps:

  1. Open the requisition detail page
  2. Find the “Assigned Recruiter” field
  3. Select a recruiter from the dropdown
  4. Click Save

Note: Recruiters can view all requisitions regardless of assignment. Assignment is for organizational purposes.

Adding Knockout Questions

Who Can Add: Anyone who can edit requisitions

Steps:

  1. Open the requisition detail page
  2. Scroll to “Knockout Questions” section
  3. Click Add Question
  4. Enter:
    • Question: The question text
    • Options: Multiple choice options (one per line)
    • Correct Answer: The correct answer option
  5. Click Save

How It Works:

  • Knockout questions appear on the public application form
  • If a candidate answers incorrectly, they are automatically rejected for that requisition
  • The application is still submitted, but status is set to “rejected”
  • A timeline note is added: “Rejected due to answering ‘[answer]’ to the knockout question ‘[question]'”
  • Candidates are not shown an error message (application appears successful)

Requisition Statuses

  • Pending: Awaiting approval
  • Approved: Approved and visible on public listings
  • Approved – Unposted: Approved but not visible on public listings
  • Closed: No longer accepting applications

Viewing Requisitions

Navigate to /ats/requisitions to see:

  • Requisition number
  • Job title
  • Location
  • Department
  • Status
  • Number of candidates
  • Assigned recruiter

Filters:

  • Requisition ID
  • Status
  • Location
  • Department

Requisition Detail Page

Click on a requisition to view:

  • Details:
    • Job Title
    • Hiring Manager
    • Assigned Recruiter
    • Location
    • Department
    • Salary Range
    • Status
  • Job Description: Full formatted description
  • Knockout Questions: List of questions and correct answers
  • Candidates Table: All candidates who applied to this requisition
    • Name
    • Email
    • Phone
    • Status (per-requisition)
    • Resume (View link)
    • Applied Date

Candidate Management

Candidate Status System

The candidate status system is fully dynamic – you can configure any status names you want. The system intelligently detects special statuses by searching for keywords in status names/slugs (case-insensitive).

Key Features:

  • ✅ Fully customizable status names (no hardcoded requirements)
  • ✅ Supports status sub-steps for granular tracking
  • ✅ Intelligent detection of “rejected” and “hire”/”hired” statuses
  • ✅ Per-requisition status tracking (candidates can have different statuses per job)

Candidates have per-requisition statuses, meaning the same candidate can have different statuses for different jobs they applied to.

Example:

  • Candidate applies to Job A → Status: “New”
  • Candidate applies to Job B → Status: “Interview”
  • On Job A detail page: Status shows “New”
  • On Job B detail page: Status shows “Interview”

Default Statuses (Fallback)

If no custom statuses are configured, the system uses these defaults:

  1. Review: Initial status when candidate applies
  2. Screened: Candidate has been screened
  3. Interview: Candidate is in interview process
  4. Offer: Offer has been extended
  5. Hired: Candidate has been hired
  6. Rejected: Candidate has been rejected

Note: You can completely customize these statuses. The system intelligently detects statuses with “rejected” or “hire”/”hired” in their names for special functionality. See STATUS_REQUIREMENTS.md for details.

Customizing Statuses

  1. Go to Appearance > Ada Settings > Candidate Statuses
  2. Add Status: Click “Add Status”
  3. Add Steps: Click “Add Step” within a status (sub-steps for granular tracking)
  4. Reorder: Drag statuses to change order
  5. Edit: Click on status name or slug to edit
  6. Click Save Changes

Dynamic Status System: The system is fully dynamic and doesn’t require specific status names. However, for optimal functionality:

  • Include a status with “rejected” in the name for proper rejection handling
  • Include a status with “hire” or “hired” in the name for hiring features
  • The system automatically detects these by searching keywords in names/slugs (case-insensitive)
  • See STATUS_REQUIREMENTS.md for complete details on status configuration

Viewing Candidates

Navigate to /ats/candidates to see:

  • Candidate name
  • Email
  • Phone
  • Tags (skills)
  • Rating (star rating average)
  • “Incomplete Application” badge (if applicable)
  • Applied date

Filters:

  • Search: Search by name, email, phone, tags, or parsed resume text
    • Supports boolean operators: AND, OR, NOT, +term, -term, (term)
    • Example: JavaScript AND React OR Vue
  • Requisition: Filter by requisition
  • Tags: Filter by tags

Candidate Detail Page

Navigate to /ats/candidate/{id} to view full candidate information.

Candidate Information

  • Basic Info: Name, email, phone
  • Resume: View/download resume
  • Parsed Resume Text: Scrollable box with extracted text
  • Tags: Skills extracted from resume (click to remove)
  • Rating: Star rating (average of all recruiter ratings)
  • Assigned Recruiter: Currently assigned recruiter

Requisitions Section

  • Requisition Dropdown: Select a requisition to view candidate’s status for that requisition
  • Status: Current status for selected requisition
  • Timeline: Activity history for selected requisition

Updating Candidate Status

  1. Select a requisition from the dropdown
  2. Use the Status dropdown to change status
  3. Click Update Status
  4. A timeline event is automatically added

Adding Notes

  1. Scroll to “Notes” section
  2. Enter note in rich text editor
  3. Click Add Note
  4. Note appears in timeline

Rating Candidates

  1. Click stars (1-5) to rate candidate
  2. Rating is saved immediately
  3. Displayed rating is the average of all recruiter ratings

Adding Tags

  1. Scroll to “Tags” section
  2. Enter tags in the input field (comma-separated)
  3. Click Save Tags
  4. Tags are added to candidate profile

Note: Tags input is for adding new tags only. Existing tags are displayed above the input.

Assigning Recruiter

  1. Scroll to “Assigned Recruiter” section
  2. Select recruiter from dropdown
  3. Click Save

Uploading Resume

  1. Scroll to “Resume” section
  2. Click Choose File
  3. Select PDF or Word document
  4. Click Upload Resume
  5. Resume is parsed automatically
  6. Tags are updated with extracted skills
  7. Parsed text is updated

Note: Uploading a new resume does not change the candidate’s status.

Bulk Actions

On the candidates list page (/ats/candidates):

  1. Select candidates using checkboxes
  2. Choose action from “Bulk Actions” dropdown:
    • Update Status: Change status for multiple candidates
    • Assign Recruiter: Assign recruiter to multiple candidates
    • Assign Requisition: Link candidates to a requisition
    • Delete: Delete candidates (Administrators only)
  3. Click Apply

Incomplete Applications

If a candidate uploads a resume but doesn’t complete the application form, they are marked as “Incomplete Application”.

Identifying Incomplete Applications:

  • Badge appears on candidate list: “⚠ Incomplete Application”
  • Notice appears on candidate detail page

Alerting Candidates:

  1. On candidate detail page, find “Incomplete Application” notice
  2. Click Alert Candidate
  3. Confirm in dialog
  4. Email is sent to candidate with:
    • Subject: “Incomplete Application”
    • Body: Link to public job posting and application form

Completing Incomplete Applications:

  • Candidate can return and complete the application
  • If they submit with the same name/email for the same requisition, their existing candidate profile is updated (not duplicated)

Public Job Listings

Public Job Board

Navigate to /ats/jobs to see the public job listings page.

Features:

  • List of all approved requisitions
  • Search by keyword
  • Filter by location, department, salary range
  • Click on job to view details and apply

Individual Job Page

Navigate to /ats/job/{id} to view a specific job posting.

Features:

  • Full job description
  • Location, department, salary range
  • Application form
  • Resume upload with parsing
  • Auto-filled fields after resume upload

Application Process

  1. View Job: Candidate views job posting
  2. Upload Resume (optional):
    • Click “Upload Resume”
    • Select PDF or Word document
    • Watch step-by-step parsing progress
    • Fields auto-populate with extracted contact info
  3. Complete Form: Fill in any remaining fields
  4. Answer Knockout Questions: If applicable
  5. Submit: Click “Submit Application”

After Submission:

  • Candidate sees success message
  • Application is saved (even if knockout questions failed)
  • If knockout questions failed, candidate status is set to “rejected” for that requisition
  • Timeline note is added with rejection reason

Duplicate Application Detection

The system checks for duplicate applications based on:

  • Email address
  • Name (exact match)
  • Requisition ID

If Duplicate Found:

  • If existing application is incomplete, it is updated (not duplicated)
  • If existing application is complete, candidate sees error: “You have already applied for this position”

Embed System

Overview

The embed system allows you to display job listings and application forms on external websites using a simple JavaScript snippet.

Setup

  1. Go to Appearance > Ada Settings > Embed Settings
  2. Generate API Key: Click “Generate” to create a unique API key
  3. Whitelist Domains: Add domains allowed to embed your jobs (one per line)
    • Example: example.com
    • Leave blank to allow all domains (not recommended)

Getting the Embed Code

  1. Go to Appearance > Ada Settings > Embed Settings
  2. Copy the embed snippet displayed on the page
  3. Paste into your external website’s HTML

Embed Code Format

<script type="text/javascript">
(function() {
    var adaEmbed = document.createElement('script');
    adaEmbed.type = 'text/javascript';
    adaEmbed.async = true;
    adaEmbed.src = 'https://yoursite.com/wp-content/themes/Ada/public/js/embed.js';
    adaEmbed.setAttribute('data-api-url', 'https://yoursite.com/wp-json/ada/v1/');
    adaEmbed.setAttribute('data-api-key', 'YOUR_API_KEY');
    var s = document.getElementsByTagName('script')[0];
    s.parentNode.insertBefore(adaEmbed, s);
})();
</script>

Embed Features

  • Job Listings: Display all approved jobs
  • Search: Search jobs by keyword
  • Filters: Filter by location, department, salary range
  • Job Details: View full job description
  • Application Form: Complete application inline (not in modal)
  • Resume Parsing: Same step-by-step parsing as main site
  • Auto-fill: Fields auto-populate after resume upload

Embed Container

The embed will automatically create a container element. You can style it with CSS:

.ada-embed-container {
    /* Your custom styles */
}

Security

  • Embed requests are validated against whitelisted domains
  • API key is required for authentication
  • Nonce validation is optional for embeds (handled by whitelist)

Gamification System

Overview

The gamification system awards points to recruiters for various actions, encouraging engagement and productivity.

Earning Points

Points are awarded for:

  • Hourly Login: 1 point per hour logged in (default)
  • Candidate Reviewed: 0.5 points per candidate reviewed (default)
  • Status Progression: 0.5 points per status change (default)
  • Custom Status Points: Configurable points for moving to specific statuses

Viewing Points

  1. Navigate to /ats/points
  2. View:
    • Current points balance
    • Points history (transactions)
    • Points earned per action

Spending Points

Recruiters can “spend” points to request rewards:

  1. Navigate to /ats/points
  2. Enter points to spend
  3. Enter message/request
  4. Click Spend Points
  5. Email is sent to admin (configured in Gamification settings)

Configuring Points

  1. Go to Appearance > Ada Settings > Gamification
  2. Set points for each action:
    • hourly: Points per hour
    • candidate_reviewed: Points per review
    • status_progression: Points per status change
    • Custom status slugs: Points for specific statuses
  3. Set Spend Points Email: Email to receive spending requests
  4. Click Save Changes

Settings & Configuration

Settings Tabs

Navigate to Appearance > Ada Settings to access all configuration options.

1. Gamification

  • Points map (points per action)
  • Spend points email

2. Requisition Form

  • Custom fields for requisition submission (dynamically rendered on form)
  • Field types: text, email, textarea, select, checkbox, file, number, tel, url, date
  • Fields automatically appear on the /ats/submit-requisition page
  • Supports required/optional field configuration

3. Application Form

  • Custom fields for public application forms
  • Field types: text, email, textarea, select, checkbox, file

4. Candidate Statuses

  • Configure status workflow (fully dynamic – no hardcoded status names)
  • Add/edit statuses and sub-steps
  • Reorder statuses
  • System intelligently detects “rejected” and “hire”/”hired” statuses
  • Supports any custom status names you configure

5. Embed Settings

  • API key generation
  • Domain whitelist

6. Retro Theme

  • Color customization
  • Font selection
  • Scanline effect toggle

7. General

  • Logo upload
  • Favicon upload
  • Timezone setting
  • Cloudflare Turnstile keys

8. Email Templates

  • Configure email templates for system notifications
  • Available templates:
    • Requisition assigned (to recruiters)
    • Requisition submitted (to approvers)
    • Points spending (to admin)
    • Incomplete application (to candidates)

Testing the System

Test Workflow

Follow this complete workflow to test all features:

1. Create Test Users

  1. Create a Hiring Manager user
  2. Create a Recruiter user
  3. Create an ATS Approver user

2. Create a Requisition

Option A – Hiring Manager:

  1. Log in as Hiring Manager
  2. Navigate to /ats/submit-requisition
  3. Fill in job details (all configured fields will appear dynamically)
  4. Submit requisition
  5. Verify status is “Pending”

Option B – Recruiter:

  1. Log in as Recruiter
  2. Navigate to /ats/submit-requisition
  3. Fill in job details
  4. Submit requisition
  5. Verify status is “Pending”

Option C – ATS Approver:

  1. Log in as ATS Approver
  2. Navigate to /ats/submit-requisition
  3. Fill in job details
  4. Submit requisition
  5. Verify status is “Pending”

3. Approve Requisition

  1. Log in as ATS Approver
  2. Navigate to /ats/requisitions
  3. Open the pending requisition
  4. Click Approve Requisition
  5. Assign a recruiter
  6. Verify status is “Approved”

4. Add Knockout Questions

  1. Still on requisition detail page
  2. Add a knockout question:
    • Question: “Do you have 5+ years of experience?”
    • Options: “Yes”, “No”
    • Correct Answer: “Yes”
  3. Save

5. Apply as Candidate (Public)

  1. Log out
  2. Navigate to /ats/jobs
  3. Click on the job
  4. Upload a resume (PDF or Word)
  5. Watch parsing progress
  6. Verify fields auto-populate
  7. Complete application form
  8. Answer knockout question incorrectly
  9. Submit application
  10. Verify success message

6. Review Candidate (Recruiter)

  1. Log in as Recruiter
  2. Navigate to /ats/candidates
  3. Find the candidate
  4. Verify “Incomplete Application” badge (if applicable)
  5. Click on candidate
  6. Verify:
    • Parsed resume text is visible
    • Tags are extracted
    • Status is “rejected” (due to knockout question)
    • Timeline shows rejection reason
  7. Select requisition from dropdown
  8. Change status to “Screen”
  9. Add a note
  10. Rate candidate (3 stars)
  11. Add a tag

7. Test Search

  1. On candidates page, use search:
    • Search by name
    • Search by email
    • Search by tag (e.g., “JavaScript”)
    • Search by parsed resume text
    • Test boolean operators: JavaScript AND React

8. Test Bulk Actions

  1. Select multiple candidates
  2. Update status for all
  3. Assign recruiter to all

9. Test Points System

  1. As recruiter, navigate to /ats/points
  2. Verify points are awarded for actions
  3. View points history
  4. Test spending points

10. Test Embed

  1. Go to Appearance > Ada Settings > Embed Settings
  2. Generate API key
  3. Add test domain to whitelist
  4. Copy embed code
  5. Create test HTML page with embed code
  6. Verify jobs load
  7. Test search and filters
  8. Test application submission

Troubleshooting

Common Issues

1. “You must be logged in to access this page”

Cause: Trying to access ATS pages without logging in

Solution: Log in to WordPress, then access ATS pages

2. “404 Not Found” on ATS pages

Cause: Permalinks not flushed after theme activation

Solution: Go to Settings > Permalinks and click Save Changes

3. Resume parsing fails

Causes:

  • Unsupported file format
  • File is image-based PDF (no text layer)
  • PHP extensions missing
  • File too large

Solutions:

  • Ensure file is PDF or Word document
  • Check PHP error logs
  • Verify PHP extensions are installed
  • Try smaller file (<10MB)

4. “Invalid security token” error

Causes:

  • Nonce expired
  • Cloudflare Turnstile misconfigured
  • Caching issues

Solutions:

  • Refresh page and try again
  • Clear browser cache
  • Check Turnstile keys in settings
  • Disable Turnstile for testing (leave keys blank)

5. Tags showing as serialized data

Cause: Data corruption or migration issue

Solution: This should be automatically fixed. If not, contact support.

6. Candidates not appearing in search

Causes:

  • Search term too specific
  • Boolean operator syntax error
  • Data not indexed

Solutions:

  • Try simpler search terms
  • Check boolean syntax: term1 AND term2, not term1&term2
  • Verify candidate has tags or parsed resume text

7. Embed not loading

Causes:

  • Domain not whitelisted
  • API key incorrect
  • CORS issues

Solutions:

  • Verify domain is in whitelist (no http:// or https://)
  • Check API key matches settings
  • Check browser console for CORS errors

8. Points not awarding

Causes:

  • Points map not configured
  • WP-Cron not running
  • User role incorrect

Solutions:

  • Check Gamification settings
  • Verify WP-Cron is enabled
  • Ensure user has ada_recruiter role

Getting Help

  1. Check Error Logs: Review PHP error logs and WordPress debug log
  2. Check Browser Console: Open browser developer tools (F12) and check for JavaScript errors
  3. Verify Permissions: Ensure user has correct role and capabilities
  4. Test in Incognito: Rule out browser cache/cookie issues
  5. Check WordPress Version: Ensure WordPress is up to date
  6. Check PHP Version: Ensure PHP 7.4+ is installed

Additional Notes

Security

  • All ATS pages require login (except public job listings)
  • Public application endpoints validate nonces and Turnstile (if configured)
  • Embed system uses domain whitelisting and API keys
  • All user input is sanitized and escaped
  • File uploads are validated and stored securely

Performance

  • Resume parsing is performed server-side
  • Large files may take time to parse
  • Search uses WordPress meta queries (optimized)
  • Points system uses WP-Cron for hourly awards

Data Storage

  • Candidates: Custom post type ada_candidate
  • Requisitions: Custom post type ada_requisition
  • Resume files: WordPress media library
  • Parsed text: Post meta ada_parsed_resume_text
  • Tags: Post meta ada_tags
  • Status: Post meta ada_status_requisition_{id} (per-requisition)
  • Timeline: Post meta ada_timeline_requisition_{id} (per-requisition)
  • Points: User meta ada_points

Cleanup

  • Resumes are automatically deleted when candidate is deleted
  • Orphaned resumes (not linked to any candidate) are cleaned up daily via WP-Cron
  • Timeline events are stored indefinitely (no automatic cleanup)

Support

For issues, questions, or feature requests, please contact the theme developer or submit an issue through the appropriate channel.

Version: 1.0.0
Last Updated: December 5, 2025
Author: Billy Wilcosky
License: Proprietary

Live Demo