This is the shared form job with three additions: the visitor proves their email before anything is saved, a second application from the same email is refused, and the customer account is made by an automation when the application lands. The page never creates accounts and never asks for a password.
Ask first
- What does an application hold? The questions, by step if it is long. At least the person's full name, their email, a phone number and their organization.
- Which email is the account's? The one question whose answer becomes the customer's login (e.g. "Work email").
- Who should be told of each application? A staff address for the form's notify email.
- What should the new customer be sent? The sign-in email's words, the site's login address, and a phone number for help.
- Which customer groups do new registrants join? E.g.
Customerplus one group staff can filter on.
Steps
1. Collection builder: the applications, one per email
Create a collection for the applications (e.g. phazzer_registration). One field per question, as in the shared form. On the email field the account will use, set unique: true in its schema.
unique in the schema does not stop duplicates on its own. The database index is built by the collection fix: call_appengine POST /repository/collections/fix with [{ "action": "", "datatype": "<collection name>" }]. It answers [{ "<collection name>": "fixed" }].
After that, a second record with the same email is refused with HTTP 409:
{ "reason": "duplicate", "field": "email", "statusCode": 409,
"error": "A phazzer_registration with email \"[email protected]\" already exists." }The index compares the stored text exactly, so [email protected] and [email protected] are two different emails. Have the page lowercase the email before it submits.
Leave out any password field. Passwords never go into a form record; the customer sets one later through the sign-in screen.
Keep Guest out of the collection's permission. The CRM form needs nothing on the collection to save into it. A collection with Guest in create is also a public form under its own name, at /form?collection=<name> and POST /client/forms/<collection name>/submit, and that path skips the emailed code and saves records with no owner, so the automation in step 3 never sees them. See Put a form on a website page.
Hands on: the collection's name.
Check: open the collection; the email field shows unique. Then make two test records with the same @test.local email (create_record): the second must fail with duplicate. Delete the test record.
2. CRM Forms: the form, gated by an emailed code
Create a CRM form (crm_form) on that collection:
| Field | Value |
|---|---|
name / title | e.g. registration / "Registration" |
collection | the collection name from step 1 |
authenticationType | code, with no accessCode and no participants. The server then emails the visitor a 6-digit code and refuses a submit without it. |
status | open |
email | the staff address to notify of each application |
submitMessage | the thank-you text |
How the gate works, for the page in step 4:
| Call | What it does |
|---|---|
POST /client/forms/<form name>/access with { "email": "<visitor's email>" } | Emails the code. Answers { "sent": true, "email": "…", "via": "code", "session": "<sk>" }. The code lasts 72 hours. |
POST /crm/form/submit/<form name>?token=<code>&email=<visitor's email> with the answers as the body | Saves the application into the collection. |
Refusals the page must show:
| Status | reason | When |
|---|---|---|
| 401 | link-required | no code sent with the submit |
| 401 | code-wrong | the code doesn't match |
| 401 | link-expired | the code is older than 72 hours |
| 403 | email-not-verified | the application's email is not the one the code was sent to |
| 409 | duplicate | this email already has an application (step 1) |
authenticationType: "email" (the model's default) does not check anything: any address typed in is accepted. Use code (or magic-link) when the email has to be proven.
Hands on: the form's name.
Check: with a @test.local address, submit without a code (expect 401 link-required), request a code, then submit with a wrong one (expect 401 code-wrong). Read the right code from the pending form_submission (data.authentication.token), submit, and the application appears in the collection. Submit again: expect 409 duplicate. Delete the test records.
3. Automation: the customer account
Call list_automation_capabilities and list_automations first. Then create_automation with status: "draft":
- trigger:
database_changeon the collection, not the form:{ datatype: "<collection name>", operation: "created", whereField: "owner.id", whereValue: "<form name>" }. Every application the form saves is stampedowner = { datatype: "crm_form", id: "<form name>" }, so the filter keeps out records made any other way. - steps (give each its
id, because the condition jumps to them):
| id | type / name | config |
|---|---|---|
already_customer | condition record_exists | datatype: "customer", match: { "data.email": "{{data.email}}" }, thenStepId: "mark_existing", elseStepId: "create_customer" |
create_customer | action create_data | datatype: "customer", data: { accountType: "contact", email: "{{data.email}}", username: "{{data.email}}", name: "{{data.full_name}}", phone: "{{data.direct_phone}}", company: "{{data.org_name}}", groups: ["Customer", "<group>"], status: "active", source: "form:<form name>" } |
mark_created | action update_data | collection: "<collection name>", filter: { sk: { $in: ["{{dataId}}"] } }, update: { "data.accountCreated": true, "data.accountStatus": "created" } |
welcome | action send_email | to: "{{data.email}}", subject, body: the sign-in email (the login address; "Send magic link" or "Forgot password?" to set a password) |
mark_existing | action update_data | the same filter, update: { "data.accountCreated": false, "data.accountStatus": "existing-customer" } |
The submitted answers are {{data.<field>}}; the application's own id is {{dataId}}. Use the field names the collection really has (get_schema on it).
How it behaves:
- A new email runs
create_customer,mark_createdandwelcome, then ends. The run does not fall through intomark_existing: a step that is a condition's jump target is only reached through that jump. - An email that is already a customer only runs
mark_existing. No second customer is made, and no email is sent. - The customer has no password. They sign in with Send magic link, or set a password with Forgot password?, both on the site's
/login.
- Don't use the
form_submittedtrigger. It only fires for forms with no collection behind them. A form bound to a collection saves a record in that collection, so the trigger isdatabase_changeon the collection. create_dataoncustomeris refused unlessaccountType: "contact". That makes a customer with no password, without the sign-up service's own steps (its welcome email, its duplicate check), which is why therecord_existscheck comes first. The engine also has acreate_customerstep (appengineautomation/actions/create-customer.action.ts, registered inautomation.module.ts412). It runs the real sign-up service: the email is normalised, one account per email (an existing email succeeds withexists: trueand sends nothing), theCustomergroup, and the org'scustomer-welcomeemail. Its config takesemail(required),firstName,lastNameorname,phone,company,title,groups(CRM customer groups to join),siteHost(where the welcome email links) andfields. It can replacecreate_data+ therecord_existscheck in the table above; the table is the tested path.- A step can't read an earlier step's result. The new customer's sk can't be written onto the application;
accountCreated/accountStatusare what link them. - A
{{field}}with no answer is saved as the text{{field}}. Only map fields the form requires. update_datatakescollection,filterandupdatewith dot keys ("data.accountStatus"), not$set. The Studio builder's Update Record step saves a different shape the engine refuses when the automation is turned on, so build this step withcreate_automation, and don't re-save it from the builder.
Stop: turning this on creates a customer, and emails them, for every application from then on. Show the person the trigger, the customer fields and groups, and the sign-in email, and wait for yes. Then call_appengine POST /automation/start/<sk>. set_automation_status → active alone saves the status without connecting the trigger, so it wouldn't run.
Hands on: the automation's sk.
Check: submit one test application (step 2's check). Within a few seconds the application shows accountStatus: "created" and a customer with that email exists (find_records on customer). Submit a second test from an email that already has a customer: it shows existing-customer and no new customer appears. The runs are listed at GET /automation/<sk>/runs (each status: "completed") and on the builder's monitor. Delete the test customers and applications.
4. Site pages: request the code, then submit
On the business's own page, the submit button runs the gate from step 2. Both calls go through the site's /api (same-origin fetch('/api/…')). The site adds the org and its app token on the server side, so no admin token is ever in the page.
- On Submit,
POST /api/client/forms/<form name>/accesswith{ email }, then show a code box: "We sent a 6-digit code to …". Offer Send a new code (the same call again) and Change email. - With the code,
POST /api/crm/form/submit/<form name>?token=<code>&email=<email>with the answers. Put the code in the query string: the site's/apidoes not pass custom headers such asx-form-tokenon. - Show the outcome: success; a wrong or expired code next to the code box; for 409
duplicate, "An application from this email already exists" with a link to/login.
Through the site's /api, an error body comes back wrapped: { "error": { "reason": "duplicate", "error": "…", "statusCode": 409 } }. Read reason from inside error.
Put the page's script in its Page settings → Style → JavaScript (style.javascript), not in a <script> in the body; body scripts don't run on a hosted page. See Run JavaScript on a hosted page.
Check: open the page and go through it once with a @test.local address: the code arrives, the right code submits, and the same email a second time shows the "already exists" message.
When it's done
Tell the person:
- the collection (where applications land) and that email is unique;
- the form, and that it emails a code before it accepts an application;
- the automation: what customer it creates, its groups, the sign-in email, and whether it is on or still a draft;
- the page, and that it never asks for a password.
Open the automation in the builder and the form on its own screen.
What it can't do yet
- One code can be used more than once on a form with a collection behind it, for 72 hours: the pending
form_submissionstayspending. The submit only accepts the email the code was sent to (403email-not-verifiedfor any other), and the unique email stops a second application under that address. - No "already applied" check before the code. The visitor learns about the duplicate only when they submit with the code.
- With the steps above, the account is a contact-type customer made by
create_data, not by the customer sign-up service. It has no password and gets no platform welcome email; the automation'ssend_emailis its welcome. Thecreate_customerstep (see the warning in step 3) makes a full customer through the sign-up service instead; it was read from the code, not tested here.
Don'ts
- Don't create the customer from the page (
/profile/customer/signupfrom the browser). The automation does it, after the email is proven. - Don't put a password field in the form or its collection.
- Don't create the automation
active. Passstatus: "draft"and turn it on after a yes. - Don't trigger on
form_submittedfor a form with a collection behind it; it never fires.