​

Processing Application gate cutover

​

What enabling blocks

​

What the operator sees

• Send client agreement & application replaces “Send client agreement”. The application link is a custom value inside the agreement template, so one send delivers both.
• Once the agreement is out, that row nests a Waiting on client cluster with two rows — Awaiting signed agreement and Awaiting processing application — each carrying its own resend button. The rows are derived from CRM state and have no checkbox: the authoritative gate is the Convex check on the captured application, and a tickable row could claim a file was ready when a submit would still be rejected. Resend Application lives here rather than on the review step, so the cluster stays visible while either artifact is outstanding — even if the operator ticked the review early — and disappears only once both have landed and the review is cleared.
• Review agreement & processing application replaces “Review signed agreement” and covers both artifacts in one review call. Unlike the gate-off agreement review, it does not auto-complete when the paperwork lands — the operator clears it by hand once both artifacts are in.
• Its checkbox is disabled until both artifacts arrive, with a tooltip naming what is still missing. You cannot review paperwork that has not shown up, and ticking it early used to march the checklist onto a submit the server gate rejects. Un-ticking stays available, so a file whose review completed before the gate was switched on is never frozen. This is a UI guardrail only — the authoritative check is the Convex gate at submit time.
• While the review is outstanding, the pinned banner names the missing artifact and offers Message Client instead of prompting a review of paperwork that has not arrived.
• On term-loan files the offers step stays reachable during the wait, because pulling rates from Engine is not a hand-off. Only Generate Offers is offered early; Submit Term Loans to 7 Figures Funding is withheld until the review is genuinely current, since that is the hand-off the gate exists to hold back.

​

Preconditions

1. The location installation has Forms read access and has been re-authorized if the scope was added after installation.
2. The location has exactly one form named FM Processing Application.
3. The form-submission workflow sends the contact ID, location ID, and form ID to the Processing Application webhook. Send the exact submission ID when the workflow exposes it. When it does not, the webhook queries the Forms API for submissions by that exact contact on that form and excludes submissions already captured in Convex. Exactly one uncaptured submission within the preceding 10 minutes is recorded; any uncaptured submission older than that window, or multiple recent uncaptured matches, fail closed with an ambiguity error so a delayed event can never record a different submission. Zero matches are retried. When every candidate is already captured (a duplicate or delayed delivery), recording dedupes against the existing snapshot instead of writing a new one. A successfully submitted, non-empty snapshot is the completion evidence.
4. A contact-tag workflow listens for fm-resend-processing-application and sends the client the Processing Application message using the Processing Application Form Link custom value.
5. The funding-agreement template includes the same custom value where the application link should appear. The app creates or refreshes this value before sending the template.
6. GHL_PROCESSING_APPLICATION_WEBHOOK_SECRET is configured on the app. The workflow Authorization header uses the per-location HMAC token provisioned from that secret, not one bearer token shared by every location.
7. Every contact already at or beyond the processing handoff has been reviewed. Generate the candidate list with
   bun run scripts/processing-application-cutover-candidates.ts \
     --location LOCATION_ID --form FORM_ID
   
   which replays the gates in the order the submit path runs them. Do not export by pipeline stage: the agreement gate runs first, so a contact in the right stage without a completed, rated agreement needs no override, while one in an unexpected stage with a signed agreement does. The script reports contacts still in flight separately from those whose processing has already finished, because the latter only meet the gate on a new submit. Processing here spans every type: a contact whose cards are done but whose term-loan handoff is still ahead counts as in flight. A third bucket, needs manual review, holds contacts whose submission history exceeded the per-contact scan limit with nothing open observed: the review cannot tell whether processing is still open, so those contacts are left out of the recommended override list (and out of the --out file’s recommendedContactIds) and listed under needsManualReviewContactIds instead. Check each one in the CRM and grandfather it only if it is genuinely still in flight. Activation reconciles the reviewed list against active overrides.

​

Check configuration

await fetch(
  "/api/admin/processing-application-cutover?locationId=LOCATION_ID",
).then((response) => response.json());

​

Grandfather in-flight contacts

await fetch("/api/admin/processing-application-cutover", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    action: "grandfather",
    locationId: "LOCATION_ID",
    contactId: "CONTACT_ID",
    reason: "Already at the processing handoff before cutover",
  }),
}).then((response) => response.json());

​

Prove the capture workflow

​

Troubleshoot a failed capture

• 400 Invalid payload — the body must omit submissionId entirely when the workflow cannot supply one. An empty string is rejected.
• 401 Valid session required — the request never reached the route. The path must be exempt from the session middleware (lib/proxy/isExemptPath.ts).
• 409 ambiguous_submission — the contact has more than one uncaptured submission, or an uncaptured one older than the fallback window.
• 409 configuration_error — Forms read access is missing, or the location does not have exactly one FM Processing Application form.
• 422 invalid_submission — the submission could not be turned into a field snapshot. The logged message names the offending key.

​

Enable

await fetch("/api/admin/processing-application-cutover", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    action: "enable",
    locationId: "LOCATION_ID",
    workflowConfirmed: true,
    grandfatheringConfirmed: true,
    grandfatheredContactIds: [
      "CONTACT_ID",
    ],
  }),
}).then((response) => response.json());

​

Smoke checks

• A newly captured application can submit to Processing.
• A grandfathered in-flight contact can submit to Processing.
• An expired override or an override from a replaced form does not bypass the gate.
• A contact with neither a captured application nor an override is blocked with the Processing Application requirement.
• Resend Application, on the Awaiting processing application row, removes and re-adds the workflow tag and produces a new client message with a working form link.
• The review step stays open after both artifacts land and only clears when the operator checks it.
• Operators can read the captured snapshot and processors can edit only the audited working copy from the Application tab.

​

Roll back

await fetch("/api/admin/processing-application-cutover", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    action: "disable",
    locationId: "LOCATION_ID",
  }),
}).then((response) => response.json());