You can onboard invited users by emailing a link that identifies an object with an external ID and, after the user registers or signs in, linking that object to the logged-in user.
What onboarding does
Onboarding is the process of bringing a user into your application and connecting that user to the information that was prepared for them. A common case is an invitation: you create an object for a prospective user, send a link to that object, and let the recipient register before assigning the object to their account.
This pattern is useful when the recipient must act on a specific object, such as an invitation, request, or other record created before the recipient has an account.
Invitation flow
Use the following sequence to implement the onboarding flow.
- Create the object that the recipient should access. For example, create an invitation object for a person you want to add to the application.
- Ensure that the object can be referenced by an external ID. The external ID is the value used by the link to identify the object.
- Create an email that contains a link to a page that uses the external-ID reference.
- Send the email to the intended recipient.
- When the recipient follows the link, let the page resolve the external-ID reference and identify the relevant object.
- If the page is password protected, the recipient is redirected to the login/registration page.
- After registration completes, use the logged-in user represented by CurrentUser to link the referenced object to that user.
- Continue the user journey from the linked object. For example, show the invitation or the next page that the invitation enables.
Example: invite a new user
Assume that you have created an invitation object before the person has an account.
- The invitation receives an external ID.
- Your application sends an email containing a link to the invitation page using that external ID.
- The recipient opens the link. Because the invitation page is password protected, the application presents login or registration.
- The recipient registers.
- Registration establishes CurrentUser.
- The application links the invitation object identified by the external ID to CurrentUser.
The important distinction is that the external ID identifies the object before authentication, while CurrentUser identifies the person after authentication. Keep both parts of the flow available until the link between the object and the user has been made.
Password-protected pages
A password-protected page ensures that the recipient has authenticated before the application performs the user-specific linking step.
| Stage | Available information | Purpose |
|---|---|---|
| Before login or registration | External-ID reference | Identify the object that the email link refers to. |
| After registration or login | CurrentUser and the referenced object | Link the object to the authenticated user. |
Do not treat the email link alone as the completed onboarding action. The link identifies the target object; registration or login establishes CurrentUser; the application must then perform the object-to-user link.
Start with BaseApp when you need supporting functionality
If your application needs more than the basic invitation pattern, start from or merge BaseApp. BaseApp includes onboarding-related building blocks, including email confirmation, collecting more information during registration, welcome email, password-reset email and screens, and login management through SysUsers.
BaseApp also contains email-related support for outgoing-email logging, email templates, editable HTML templates, and notification handling. Its email handling includes tracking states such as waiting, queued, failed/requeue, and sent, which helps you investigate delivery problems. Some BaseApp features are intended to be extended by subclassing and further implementation.
For an example of beginning with an empty model and merging BaseApp to obtain onboarding, user management, notifications, email queueing, templates, and reset-password logic, watch the walkthrough.
Design checklist
Before implementing an invitation flow, confirm that you have:
- An object to represent what the recipient is being invited to access.
- An external ID that the email link can use to identify that object.
- A page that receives and uses the external-ID reference.
- Password protection on the page when authentication is required.
- Login and registration behavior that establishes CurrentUser.
- Logic that links the referenced object to CurrentUser after registration or login.
- Email creation and delivery handling, including a way to inspect failed or queued messages when email is part of the flow.
Related guidance
Use Documentation:GettingStarted for the wider MDriven learning path. Use Documentation:Turnkey for Turnkey setup and architecture guidance. If you are new to MDriven Designer, Documentation:Start Introduction provides a guided introduction.