docs
/
AI skills

Registration that creates the customer

A registration form on the business's own website page that proves the visitor owns their email with an emailed code, takes one application per email, and has an automation, not the page, create the customer account.

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. Customer plus 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:

FieldValue
name / titlee.g. registration / "Registration"
collectionthe collection name from step 1
authenticationTypecode, with no accessCode and no participants. The server then emails the visitor a 6-digit code and refuses a submit without it.
statusopen
emailthe staff address to notify of each application
submitMessagethe thank-you text

How the gate works, for the page in step 4:

CallWhat 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 bodySaves the application into the collection.

Refusals the page must show:

StatusreasonWhen
401link-requiredno code sent with the submit
401code-wrongthe code doesn't match
401link-expiredthe code is older than 72 hours
403email-not-verifiedthe application's email is not the one the code was sent to
409duplicatethis 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_change on the collection, not the form: { datatype: "<collection name>", operation: "created", whereField: "owner.id", whereValue: "<form name>" }. Every application the form saves is stamped owner = { 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):
idtype / nameconfig
already_customercondition record_existsdatatype: "customer", match: { "data.email": "{{data.email}}" }, thenStepId: "mark_existing", elseStepId: "create_customer"
create_customeraction create_datadatatype: "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_createdaction update_datacollection: "<collection name>", filter: { sk: { $in: ["{{dataId}}"] } }, update: { "data.accountCreated": true, "data.accountStatus": "created" }
welcomeaction send_emailto: "{{data.email}}", subject, body: the sign-in email (the login address; "Send magic link" or "Forgot password?" to set a password)
mark_existingaction update_datathe 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_created and welcome, then ends. The run does not fall through into mark_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_submitted trigger. 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 is database_change on the collection.
  • create_data on customer is refused unless accountType: "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 the record_exists check comes first. The engine also has a create_customer step (appengine automation/actions/create-customer.action.ts, registered in automation.module.ts 412). It runs the real sign-up service: the email is normalised, one account per email (an existing email succeeds with exists: true and sends nothing), the Customer group, and the org's customer-welcome email. Its config takes email (required), firstName, lastName or name, phone, company, title, groups (CRM customer groups to join), siteHost (where the welcome email links) and fields. It can replace create_data + the record_exists check 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 / accountStatus are what link them.
  • A {{field}} with no answer is saved as the text {{field}}. Only map fields the form requires.
  • update_data takes collection, filter and update with 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 with create_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.

  1. On Submit, POST /api/client/forms/<form name>/access with { 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.
  2. 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 /api does not pass custom headers such as x-form-token on.
  3. 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_submission stays pending. The submit only accepts the email the code was sent to (403 email-not-verified for 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's send_email is its welcome. The create_customer step (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/signup from 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. Pass status: "draft" and turn it on after a yes.
  • Don't trigger on form_submitted for a form with a collection behind it; it never fires.