Technical overview

How ProofSync works

ProofSync takes a completed job in a contractor's job-management system and applies it to the matching job in the client's CAFM, then proves it landed. This page is the detail behind that sentence, for the person who has to sign it off.

The sync engine

Every sync is an explicit, ordered pipeline. Each stage writes an audit event before the next begins, so a run is always reconstructable after the fact, including the ones that failed.

  1. 1

    Validate

    Is the job actually complete? Is there a client job reference, and is it well-formed?

  2. 2

    Match

    Look the job up in the client system by its unique reference. Zero matches or several matches both stop the run.

  3. 3

    Transform

    Apply the field mapping and the client’s policy rules to build the target payload.

  4. 4

    Update

    Write only the permitted, actually-changed fields.

  5. 5

    Upload

    Transfer permitted document categories and attach them to the job.

  6. 6

    Verify

    Re-read the record from the client system and compare it against what was sent.

The matching rule is absolute. A unique, valid client job reference is mandatory. No reference, no target, or an ambiguous match each raise a distinct exception. ProofSync will never fuzzy-match its way into updating the wrong job on your client's system, that is the one failure mode that would cost you the account.

Field mapping

Every client wants their data in a different shape. Mapping is explicit and inspectable, not a black box, and not a no-code maze nobody can audit.

SourceTransformResult
timeOnSite = 127minutes → hours2h 7m
totalCost = 160.5currency£160.50
followOn = falseboolean → textNo

Per-client policy sits on top: whether costs transfer at all, which document categories are permitted, and whether ProofSync may move the job status or must leave closure to a human. Operators preview the exact result of a mapping before anything is written.

The exception model

Every run ends in a definite state: synced, partially synced, awaiting review, failed, retrying, or ignored by rule. Nothing is dropped quietly. The distinction that matters is whether a machine can fix it or a human must.

ExceptionMeaningResolver
Missing client referenceNo reference stored against the job. We refuse to guess.Human
Target job not foundThe reference exists but matches nothing in the client system.Human
Duplicate matchMore than one job matched. Ambiguity is never resolved automatically.Human
Required field missingThe client system requires a value the source never captured.Human
Document upload failedCore data landed; a file did not. Job marked partial.Retry
Rate limited / unavailableClient system pushed back or was down.Auto-retry
Authentication failedCredentials or permissions changed on the client side.Human

Transient failures (rate limits, timeouts, outages) retry automatically on a capped backoff. Structural problems never retry, retrying a missing reference just produces the same failure more often. They go to a person, once.

Connecting to a client system

The sync engine has no knowledge of any specific vendor. It speaks a normalised shape; every system-specific detail lives in a connector behind a common interface. Adding a client system is a connector, not a rewrite, and we take the highest rung on this ladder the client system supports.

The order is about what a client system exposes, not about how much work each route is worth. Rung one is the best engineering; it is not the most common situation. Every rung below it is held to the same evidence standard, and the last one is the reason a client system with no interface at all can still be kept in step. That is the gap ProofSync exists to close.

1

Documented API

Preferred

Direct, fast, resilient. Where the client system exposes a usable interface, this is always the route.

2

Scheduled file import (SFTP/CSV/XML)

Good

Many CAFM platforms accept batch job-update imports. Supported, contractual, robust, and more common than people assume.

3

Contractor portal upload

Workable

A supported human path, driven reliably. Slower, but sanctioned.

4

Controlled automation

By written authorisation

Where a system exposes no interface at all, ProofSync works it the way your coordinator would: on an account the client issues and controls, authorised in writing, scoped to the job update, on a dedicated worker, and verified by reading the record back. The same evidence standard as rung one. Where a client’s terms or security model rule it out, the rung stays closed and we say so.

Security & governance

  • Audit trail on every sync

    What triggered it, which fields were read, changed and excluded, what the client system returned, whether it verified, and who intervened.

  • Secrets never in the database

    Credentials come from a managed secret store, server-side only. Nothing sensitive reaches a browser.

  • Client-authorised access

    A client system is only connected on that client’s written approval, with an account they control.

  • Least privilege

    The integration account gets only the permissions the write-back flow requires.

  • Signed, idempotent ingestion

    Inbound events are signature-verified and de-duplicated, so a replayed event can never double-update a job.

  • Deployment options

    Hosted by ProofWorks, or deployed inside your own environment where contracts demand it.

What ProofSync is not

  • Not a replacement for your job-management system

    Your system stays exactly as it is. ProofSync reads from it; it does not compete with it.

  • Not a replacement for your client’s CAFM

    We update their system on their terms. We never ask them to change it.

  • Not an AI product

    Nothing here guesses. The behaviour is deterministic and inspectable, because you cannot audit a guess.

  • Not a way to close jobs behind your client’s back

    Status changes and job closure are policy-gated, and can require human approval every time.

See it against your own data

Name one client system you're re-keying into. We'll prove the sync before you commit to anything.