Setting Up External Agreement Integrations
Lumieos can receive agreement completions from external signing tools (Jotform, Smartwaiver) via webhook, and can automatically mark agreements complete from FIRST’s Consent & Release status during Tableau import. This guide walks through configuring both paths.
Tip: Use the instance selector in the top navigation bar to personalize every admin URL on this page to your deployment. Until you pick one, URLs show a
<your instance>placeholder.
Overview
Three integration paths populate the electronic_external signature method on Agreements:
| Path | Who triggers | Match strategy |
|---|---|---|
| Jotform webhook | User submits a Jotform form | Token (hidden ref field) + fallback to form fields (team number, email) |
| Smartwaiver webhook | User signs a Smartwaiver waiver | Token (tag query param) + fallback to waiver template ID + participant fields |
| FIRST import | Partner admin uploads Tableau CSV | FIRST Consent Release Status == Accepted on the volunteer or student record |
All three paths share idempotent completion — re-delivering the same webhook or re-running the same import never double-marks an agreement or mutates chain-of-custody fields.
Admin URL:
Step 1 — Choose the AgreementType’s external tool
Admin URL:
Agreement types created through the admin can optionally point at an external signing tool. Open the Agreements page, click an agreement type in the Types table, and fill in:
| Field | Details |
|---|---|
| External tool | Jotform, Smartwaiver, or (none) |
| External URL | The Jotform form URL or the Smartwaiver waiver URL. Users click a “Sign with …” button on their agreement card which opens this URL in a new tab, with a single-use token appended automatically. |
| Field mapping (JSON) | Provider-specific. Jotform: {"team_number": "q5_teamNumber", "email": "q3_email", "name": "q7_fullName"}. Smartwaiver: {"template_id": "abc123-..."}. |
Note: Field mapping is only used when a webhook arrives without our token — for example, if a user fills out the Jotform form directly from a bookmark or shared link instead of clicking the “Sign with Jotform” button in Lumieos. The token path is preferred; the field-mapping fallback exists so direct-link submissions still match up.
Step 2 — Configure per-provider webhook secrets
Webhook signatures are verified with a per-partner, per-provider HMAC secret. Open the Webhook secrets panel on the Agreements page and click Set (or Rotate) next to Jotform or Smartwaiver. Paste the value from your provider’s webhook configuration and save.
Warning: Lumieos never returns the stored secret in any API response — it’s write-only. If you lose the value, rotate it in both Lumieos and the provider.
Jotform
- Go to your Jotform form → Settings → Integrations
- Search for Webhooks and add a new webhook
- Paste the webhook URL shown in the Agreement type detail drawer: it has the shape
https://<your-instance>/api/agreements/webhook/jotform/<partner-id>/ - In Jotform’s “Advanced” webhook settings, enable Include hash signature and use the shared secret you just set in Lumieos
- Back on the form editor, make sure the field names Lumieos expects (from your field-mapping JSON) actually match your form’s question names. Jotform question names look like
q5_teamNumber— you can see them in the form’s URL params or via the form’s Export submission data view.
Tip: For the token path, Jotform preserves URL query params (like
?ref=<token>) through the submission and echoes them back in therawRequestpayload — no special configuration needed.
Smartwaiver
- Go to your Smartwaiver template → Settings → Webhooks
- Paste the webhook URL:
https://<your-instance>/api/agreements/webhook/smartwaiver/<partner-id>/ - Set the signing key to match the Smartwaiver secret you set in Lumieos
- Tokens ride the
tagURL parameter on the signing URL and come back aswaiver.tagin the webhook payload — no extra setup needed
Step 3 — Test the webhook plumbing
Trigger a test submission from the provider. On the Agreements page in Lumieos, the Webhook history panel shows every recent delivery:
| Column | Meaning |
|---|---|
| Received | Local time the webhook arrived |
| Provider | jotform or smartwaiver |
| Verified | Green if the HMAC signature matched, red if not |
| Matched | Green if we resolved an Agreement, yellow if unmatched |
Click a row to expand the raw + processed payloads — helpful for diagnosing field-mapping mismatches.
Note: Unmatched submissions still return HTTP 200 to the provider (so they don’t retry forever). They sit in the history as “Matched: No” so an admin can investigate.
FIRST Consent & Release Integration
FIRST exposes a Consent Release Status field on volunteer and student records. When that value is Accepted during a Tableau import, Lumieos can automatically complete a matching agreement record.
Step A — Create the AgreementTypes
Before the mapping can do anything, create at least one published AgreementType for “FIRST Consent Release” (or whatever naming your partner uses). Typically you’d have two — one for volunteers, one for students/youth — but a single AgreementType can also serve both if you prefer.
Step B — Configure the FIRST mapping
Admin URL:
Scroll to the FIRST consent mapping panel. Pick:
- AgreementType for volunteer consent — matched against
NationalVolunteerRecord.consent_form_statusduring VMS imports - AgreementType for youth consent — matched against
StudentMemberRecord.consent_form_statusduring roster imports
Leave either dropdown on (none — opt out) to skip that half of the integration.
Step C — Run a Tableau import
Any normal Tableau import will now auto-complete the mapped AgreementType for every volunteer/youth record with Accepted status. The completion uses:
| Field | Value |
|---|---|
signature_method | electronic_external |
external_reference_id | first-nr-<national_record_id> |
signed_at | The provider’s reported date, parsed as UTC |
raw_source | first_import (tagged in logs for tracing) |
Note: Import is forward-only. Existing
Acceptedstatuses in historical records won’t be backfilled — only new imports after the mapping is configured trigger the integration.
Tip: Re-running the same import is safe — the idempotency check (
external_reference_idmatch on an already-complete agreement) short-circuits the update.
Troubleshooting
Webhook signature verification fails: Double-check the shared secret matches on both ends. Lumieos rotates the stored value on save, so if you recently rotated, re-paste into the provider too.
Webhook arrives as “Unmatched”: The token was missing/expired, and the field mapping couldn’t resolve a FormationTeamMember. Verify the field mapping JSON matches actual Jotform question names (or the Smartwaiver template ID is set).
FIRST import runs but no agreements complete: Confirm a FirstConsentAgreementMapping exists for your partner and the subject type (volunteer or youth). An unconfigured partner logs at DEBUG level and skips silently.
Concurrent webhook deliveries: Providers sometimes deliver the same event twice. The completion helper uses SELECT FOR UPDATE on the Agreement row inside a transaction, so the second caller sees the completed state and returns the idempotency no-op.
Manual Completion
Some agreements can’t be electronically signed and can’t be imported from FIRST — e.g., a paper form in a filing cabinet, or a completion verified through some offline channel. Partner admins can mark such agreements complete from the region-admin Agreements page.
Admin URL:
Global view
Switch to the Agreements tab on the region Agreements page. The table shows every agreement (defaulting to “Not finished”) across all teams in your partner. Filter by status, agreement type, signature method, or team number.
Select one or more rows via the checkboxes and click Mark complete (N) to open the completion dialog.
Per-team view
On the Teams page, click the file-signature icon in a team’s actions column to open the team-scoped agreements drawer. The drawer shows the same table filtered to that team — useful when processing a stack of paper forms one team at a time.
Completion methods
| Method | When to use |
|---|---|
| Paper on file | Notes describe where the physical form is stored. Supports bulk. |
| Paper upload | Admin uploads a scanned copy of the signed form. Single agreement only — one scan per person. |
Bulk completion only applies to paper_onfile. A single scanned file cannot represent multiple people, so the dialog disables “paper upload” when more than one row is selected.
Audit trail
Every manual completion records:
- The admin user who marked it (
paper_verified_by) - The moment they clicked save (
paper_verified_at) - The signed date the admin typed in (
paper_signed_date) - The notes or uploaded file (
paper_signature_notes/paper_signature_file) - A tamper-evident
signature_hashcomputed over the chain-of-custody fields
Manually-completed agreements auto-lock the same way electronically-signed ones do. Un-marking requires support intervention — same policy as any other completion method.
Tip: The “Not finished” filter is the default for a reason — focus on what still needs doing. Switch to “All” or “Complete” to audit the outcome afterwards.
User-Account Coaches
On US-based teams where coaches have Lumieos accounts, their agreements are now tracked through the same chain-of-custody system as formation members — but with one important difference: a user-account coach’s agreements are per-coach, not per-team. A coach who serves three teams signs each required form once, and completion flips the status on every team they coach.
The team documentation tab surfaces user-account coaches alongside formation members. Their rows are labeled “Applies to all teams” to make the cross-team scope explicit. Coaches sign at /account/agreements — admins don’t sign on a coach’s behalf from the doc tab.
Admin overrides (paper on file, paper upload) for user-account coaches live on the region admin Agreements page, same as for formation members. Filter by team number to see all agreements for that team’s coaches and members in one list.