ATS — install & operate

This page is written for the person who owns the portal. It is ordered as the work actually happens: decide the tier, install, provision the pages, fill the data, tune, verify. The section that most often gets skipped is § What matching needs, and skipping it is the single most common reason a working install produces useless rankings.

Before you start#

The tier decision — make it before installing#

The schema installs in tiers because 19 objects does not fit on a normal portal. Choose the smallest one that covers the process you actually run; upgrading later is additive and never deletes.

Upgrades only ever add. Going from lean to standard creates the two new objects and leaves everything else untouched; there is no downgrade, because a downgrade would mean deleting records.

What install provisions#

The dynamic job-detail page is bound to the portal's own ats_job_posting object. That binding is per-portal, which is why object type ids are resolved at runtime everywhere and never hardcoded.

The settings page#

Five tabs, in the app's listing in HubSpot:

Matching settings are staged and saved as a group — nothing takes effect until Save, and Discard restores what is stored.

What matching needs#

Read this section even if you are not tuning anything. The engine scores properties, and only properties. It does not read CVs, it does not infer, and a field nobody filled is not a low score — it is a dimension that either scores a neutral 50 or drops out of the calculation entirely.

The failure this produces is quiet and specific: every candidate scores roughly the same, in a band around 50, and the ranking looks arbitrary. That is not a broken engine. That is an engine with nothing to compare.

On the job posting#

A posting that states no requirement for a dimension excludes it. That is deliberate and usually right, but it means a thinly filled posting scores everyone on very little. If rankings need to be comparable across postings, make these fields required in your own process — the app does not enforce it.

On the candidate — the Contact#

Every field lives in the ATS – Candidate Matching property group: seniority level, remote preference, willing to relocate, total years of experience, primary skills, languages, education level, industry, match keywords, salary expectation minimum and maximum, and open to work.

Three ways they get filled, in descending order of how much you should rely on them:

1. A workflow or an import. The reliable answer. Map whatever you already hold onto these properties.
2. A recruiter, on the Contact record. Fine at low volume.
3. The application form. It captures the applicant, not their full profile. It does not populate the matching fields.

There is no fourth way, and in particular there is no CV extraction. An uploaded CV attaches to the candidate and nothing reads it.

Migrating an already-installed portal#

Properties added after a portal was installed do not appear on it by themselves. Run the schema migration:

POST https://api.worksby.design/apps/ats/admin/migrate-schema

It is idempotent and additive — it creates what is missing and touches nothing that exists. Two properties are worth checking for specifically, because their absence is silent:

• ats_open_to_work — without it the candidate pool is unfiltered, as above.
• stage_entered_at — without it, time-in-stage reports nothing. There is no error; the number is simply always empty.

Run this after any upgrade. A portal that has been installed for a while and has never been migrated is the usual explanation for "that feature is documented but I do not have it".

Sample data does not update itself. The seeder reuses records that already exist rather than overwriting them, which is what stops a re-seed duplicating your demo. The consequence: if the shipped sample set gains fields, an already-seeded portal will not pick them up from a re-seed. Remove the sample data and add it again, or ask us to backfill.

Verification#

In order. Each step proves the one before it actually worked, and the last one is observable by a person rather than by a log.

1. Licence — GET /apps/ats/license-status for the portal answers active.
2. Objects — the Settings page's Status tab lists the tier and shows every expected object present.
3. Pages — /careers/jobs loads on the portal's own domain and renders the module rather than an empty page.
4. A posting appears — create a posting, publish it, and confirm it is on /careers/jobs. If the list is empty, the posting is not both live and active; nothing else filters it.
5. The job page resolves — open the posting from the list. The detail page is the dynamic page; if it 404s, the dynamic page was skipped at install because the custom object did not exist yet.
6. An application lands — apply through the form, then find the ats_application record associated to both the Contact and the posting. Submitting the same form twice must produce one record, not two.
7. The status link works — request a status link for that email, follow it, and see the application with a simplified status.
8. Matching produces a real ranking — on the Settings page's Matching tab, run the dry-run calibrator against that posting's record id. This is the step that proves the data, not just the plumbing. A spread of scores means the candidate properties are populated; every candidate clustered near 50 means they are not, and § What matching needs is where to go.
9. The job-board feed resolves — open https://api.worksby.design/apps/ats/jobs.xml?portalId=<portalId> in a browser. A 409 means the careers base URL is not set. Otherwise check the X-Jobs-Included header against the number of live postings, and click one <url> from the document — that link is what a candidate will follow from a job board, and it is the only part no test can prove for you.

When something is wrong#

Security posture#

The shareable summary. A deeper analysis exists and is not published — ask, and we will walk through it.

• Candidate data stays on your portal. The app stores postings, applications, candidates and documents as CRM records on your own HubSpot. No external database holds them.
• The public careers routes authenticate the portal, not the caller. That is appropriate for a public careers page: anyone may read live postings and anyone may apply. What is protected is the data — public routes return only the public field set, never another candidate's application.
• The candidate status link is a signed, expiring token bound to one contact. Requesting one always returns the same acknowledgement, so it cannot be used to discover whether somebody applied.
• The candidate never sees your internal pipeline. The status portal returns a reduced shape by design — no internal stage name, no rejection reason.
• The recruiter surface is bound to a licensed portal install rather than to an individual user, because HubSpot does not sign card-initiated calls. Stated in full in ats-integration.md.
• Workflow actions are genuine signed HubSpot webhooks, verified per request.

What an uninstall destroys#

Two things survive, and both matter:

• Contacts survive. Candidates are Contacts, and Contacts are yours. The ATS property group's values remain on them, so a reinstall finds the candidate data intact.
• Schema deletion can fail without the uninstall failing. HubSpot refuses to drop a schema while soft-deleted records or workflow references remain. That is reported in the result rather than treated as fatal, so check the result rather than assuming a clean removal. Retrying later usually clears it.

Reinstalling is not a repair tool. For a portal that is behaving oddly, the migration above fixes missing properties, and the tier upgrade fixes missing objects — both without touching data.