Registration Flow

One of the more frequent flows that an application must achieve is that of registering a user. Cloud CMS already provides registration support. The application service convenience method shown below make it a little easier to register users for your web application by letting you predefine:

• The Custom Domain Name where new users will be created.
• The Email Provider to be used to send emails to new users.
• The Registrar where new tenants will be created (optional).
• The Domain User to run as (or run as system user).

Configure your Application Instance

To utilize the convenience flow for user registrations, you first need to have an Create new Application Keys data store instantiated that will be used to store data for your mobile/web application. You can instantiate this through the Cloud CMS console or you can do so programmatically. Once you've done so, you will need to configure the application instance to have the following properties:

• public.userDomainId - The ID of one of your platform's domains that should be used to store the new, registered users.
• public.emailProviderId - The ID of one of your platform's email providers that should be used to send emails.
• public.tenantRegistrarId - (optional) The ID of one of your platform's registrars that should be used to store new tenants.
• public.runAsPrincipalId - (optional) The ID (or domain qualified ID) of the principal on one of your platform's domains that should be used to execute the registration process.
• public.allowRegistrationAutoConfirm - (optional) Boolean that indicates whether the registration flow for this application allows for one-hop auto confirmations (see below).

Sample configuration

The following JSON can be appended into your Application JSON (which you can edit within the Cloud CMS console). Or you can edit your application and enter these values via a form.

{
    "public": {
        "userDomainId": "primary", // either "primary" or a domain ID
        "emailProviderId": "{Email Provider GUID}",
        "tenantRegistrarId": "{Registrar GUID}",
        "tenantRunAsPrincipalId": "{Principal GUID}", // usually in the format "{domainId}/{principalId}"
        "allowRegistrationAutoConfirm": true|false // to allow for registration auto confirms
    }
}

Registration Flow

The registration flow works like this:

1. A web site user fills out a form on your web site. They click submit.
2. Your application code calls Cloud CMS to create a registration object.
3. Your application code calls Cloud CMS to send the confirmation email.
4. Your web site informs the user that an email was sent and that they should click the link contained in the email to verify their email address and continue the registration process.
5. The user checks their email and clicks the link. The user's browser is taken to a registration page on your web site. This page receives a "hash" request parameter which is used to complete the registration process (below).
6. The web site user fills in any additional information they need to supply. They click submit.
7. Your application code calls Cloud CMS to update the registration object (if needed).
8. Your application code calls Cloud CMS to confirm the registration and passes along the any password and payment information.
9. Cloud CMS creates a new user and optionally creates a new tenant complete and billing confirmation for the new user.

API Methods

Below we cover step-by-step how to use the API methods to complete a registration flow. For technical details on using the API, please see:
Public Application Services API

Create and Update a Registration

The method calls to create and update a registration are perhaps the most intensive in that they allow you to specify quite a lot of fields. The two methods you want to use are:

POST /pub/applications/{applicationId}/registrations/create
POST /pub/applications/{applicationId}/registrations/{registrationId}/update

In both cases, you need to specify the ID of your Application instance in the path to the method. For the case of an existing registration, you also need to provide the ID of your existing registration instance.

The body of your POST should contain the JSON of the properties to be applied. For a simple user registration, you can do something like this:

{
    "userEmail": "joe@joe.com",
    "userName": "joe",
    "userProperties": { // optional
        "firstName": "Joe",
        "lastName": "Smith"
    },
    "emails": {
        "confirmation": {
            "body": "<a href='http://website.com/registration.html?hash=${hash}'>Click me</a>",
            "from": "webmaster@website.com"
        },
        "welcome": {
            "body": "Welcome to the web site!  You have successfully registered.",
            "from": "webmaster@website.com"
        }
    }
}

Here is an example of using some straightforward jQuery to create a registration:

// the application
var applicationId = "GUID1";

// create the registration
$.ajax({
    "type": "POST",
    "dataType": "json",
    "processData": false,
    "url": "/pub/applications/" + applicationId + "/registrations/create",
    "data": {
        "userEmail": "joe@joe.com",
        "userName": "joe",
        "userProperties": {
            "firstName": "Joe",
            "lastName": "Smith"
        },
        "emails": {
            "confirmation": {
                "body": "<a href='http://website.com/registration.html?hash=${hash}'>Click me</a>",
                "from": "webmaster@website.com"
            },
            "welcome": {
                "body": "Welcome to the web site!  You have successfully registered.",
                "from": "webmaster@website.com"
            }
        }
    }
});

And here's how you might do an update:

// the application
var applicationId = "GUID1";

// the registration
var registrationId = "GUID2";

// update the registration
$.ajax({
    "type": "POST",
    "dataType": "json",
    "processData": false,
    "url": "/pub/applications/" + applicationId + "/registrations/" + registrationId + "/update",
    "data": {
        "userProperties": {
            "middleName": "Roosevelt"
        }
    }
});

And here is a list of everything that can be passed in when defining a registration:

{
    ///////////////////////////////////////////////////
    //
    // auto-creation of user
    //

    // required - the user email address
    "userEmail": "",

    // required - the user name
    "userName": "",

    // required - the domain where the user should be created
    "userDomainId": "", // optional

    // optional - additional properties to apply to user
    "userProperties": {},

    // optional - set to "merge" to merge with existing user if found, leave undefined to detect collision and not create
    "primaryUserCreationStrategy": null,



    ///////////////////////////////////////////////////
    //
    // auto-creation of a tenant
    //

    // optional - tenant title
    "tenantTitle": "",

    // optional - tenant description
    "tenantDescription": "",

    // optional -tenant plan
    "tenantPlanKey": "",

    // optional - tenant registrar
    "tenantRegistrarId": "",

    // optional - custom properties for tenant
    "tenantProperties": {},



    ///////////////////////////////////////////////////
    //
    // emails
    //

    // email definitions
    "emails": {
        "confirmation": {
            // required confirmation email definition
        },
        "welcome": {
            // required welcome email definition
        }
    },

    // required - email provider ID
    "emailProviderId": "",



    ///////////////////////////////////////////////////
    //
    // additional settings

    // optional - any discounts to be applied to payment plan
    "discounts": {},

    // optional - any addons to be applied to payment plan
    "addons": {},

    // optional - user properties assigned during signup phase
    "signupProperties": {},

    // optional -  project to automatically add the user to
    "projectId": "",

    // optional - specific team keys for project teams the user should be added to
    "projectTeamKeys": []

}

When you create a registration, you'll get back a JSON object containing the newly created registration. Within it, you will find the _doc field which is the Registration ID you'll need to pass in to do any updates.

For more details on how the registration objects work, see Registration Objects.

Send the Confirmation Email

To send the confirmation email, you can simply do an empty POST to:

POST /pub/applications/{applicationId}/registrations/{registrationId}/send/confirmation

The confirmation email will be sent and it will contain the body and properties as defined in the emails templates block within your registration object. For more details on how to use these registration variables, see Registration Email Templates.

Once the email is sent, the end user will receive an email with a link that they can follow to continue the registration process. This link must connect to your web site and the link should also pass along a request parameter (or a hash link) that contains the ${hash} for the registration. This hash is generated by the registration flow and will only be made available to the email recipient. When the end user clicks on the link, the hash is passed over to your web site.

Your web site can then either confirm them straight away or present a form for the collection of additional information. Specifically, you should at this point collect their password (or auto-assign a password, depending on the flow that you intend to have).

Here is an example of using some straightforward jQuery to send the confirmation email:

// the application
var applicationId = "GUID1";

// the registration id
var registrationId = "GUID2";

// send the registration confirmation email
$.ajax({
    "type": "POST",
    "dataType": "json",
    "processData": false,
    "url": "/pub/applications/" + applicationId + "/registrations/" + registrationId + "/send/confirmation"
});

Retrieving and Testing the Registration Validity

When the end user receives the email, they should have a link in it that takes them back into your web site. Coming back in, you should pick off the hash from either the URL hash (client-side) or a request parameter (server-side). Either way, the hash is a unique, unguessable key that provides a one-time registration confirmation to your web app. It validates that the end user received the email, that they're real and that they have the intention of registering.

The first thing you should do is use the hash to verify that the registration is real, that it hasn't expired and that it hasn't already been completed.

You can do this by making a simple AJAX call like this:

// the application
var applicationId = "GUID1";

// the registration hash
var hash = "HASH";

// confirm the registration (and send welcome email)
$.ajax({
    "type": "POST",
    "dataType": "json",
    "processData": false,
    "url": "/pub/applications/" + applicationId + "/registrations/" + hash + "/testvalidity",
    "done": function(data) {

        if (data.ok) {
            // looks good
        }
        else if (data.error) {
            alert(data.message);
        }

    }
});

Complete the Registration

To complete the registration, you simply need to call over to Cloud CMS and confirm along with the following details:

• The account password that the user has selected
• An optional payment method object (defining their credit card number, holder name and expiration date)

The POST payload should contain these properties. Here is the full set of properties that can be passed in:

{
    "password": "", // required password
    "paymentMethodObject": { // optional
        "holderName": "",
        "number": "",
        "expirationYear": "",
        "expirationMonth": ""
    }
}

Here is an example of using some straightforward jQuery to confirm the registration:

// the application
var applicationId = "GUID1";

// the registration hash
var hash = "HASH";

// confirm the registration (and send welcome email)
$.ajax({
    "type": "POST",
    "dataType": "json",
    "processData": false,
    "url": "/pub/applications/" + applicationId + "/registrations/" + hash + "/confirm",
    "data": {
        "password": "password1"
    }
});

When this method completes, the user will be created in the domain specified on the Application instance configuration.

If the registration definition includes a tenant, a tenant will be created within the target Registrar. If the tenant plan requires billing and the confirmation step does not pass billing information (or passes invalid billing information), the registration will fail. Be sure to check the error code of the response to ensure that your tenant was set up.

Send the welcome email

Once the registration has been completed, you can have the registration send off the welcome email to inform the end user that they've been registered for an account. The welcome email is optional. It's not something that you have to include, but if you'd like, it's there for you to use.

You can fire off a POST call to trigger the email send. All you need to do is pass in the hash code for the registration (which was received by the by incoming link from the email):

POST /pub/applications/{applicationId}/registrations/send/confirmation?hash={hash}

Here is an example of using some straightforward jQuery to send the welcome email:

// the application
var applicationId = "GUID1";

// the registration hash
var hash = "HASH";

// confirm the registration (and send welcome email)
$.ajax({
    "type": "POST",
    "dataType": "json",
    "processData": false,
    "url": "/pub/applications/" + applicationId + "/registrations/" + hash + "/send/welcome",
    "data": {
        "password": "password1"
    }
});

Specifying the password and/or payment method ahead of time

You can also specify the user's password and/or their payment method ahead of time, before the first verification email is sent.. In some registration flows, you may wish to collect this information up front and have it be utilized later, once the end user clicks on the email link and is brought back to the web site.

To specify this ahead of time, you can plug in values for the password and/or the paymentMethod fields on the signupProperties object.

Here's an example of creating the registration with the password and paymentMethod supplied before the email is sent.

// the application
var applicationId = "GUID1";

// create the registration
$.ajax({
    "type": "POST",
    "dataType": "json",
    "processData": false,
    "url": "/pub/applications/" + applicationId + "/registrations/create",
    "data": {
        "userEmail": "joe@joe.com",
        "userName": "joe",
        "userProperties": {
            "firstName": "Joe",
            "lastName": "Smith"
        },
        "signupProperties": {
            "password": "mypassword",
            "paymentMethod": {
                "holderName": "Joe Smith",
                "cardNumber": "1111222233334444",
                "expirationMonth": "06",
                "expirationYear": "2015"
            }
        },
        "emails": {
            "confirmation": {
                "body": "<a href='http://website.com/registration.html?hash=${hash}'>Click me</a>",
                "from": "webmaster@website.com"
            },
            "welcome": {
                "body": "Welcome to the web site!  You have successfully registered.",
                "from": "webmaster@website.com"
            }
        }
    }
});

To confirm, you can simply call the confirm method without any data payload. If you do supply either the password or the paymentMethod in the payload, it will override the values provided during registration creation.

// the application
var applicationId = "GUID1";

// the registration hash
var hash = "HASH";

// confirm the registration (and send welcome email)
$.ajax({
    "type": "POST",
    "dataType": "json",
    "processData": false,
    "url": "/pub/applications/" + applicationId + "/registrations/" + hash + "/confirm"
});

Auto Confirmation

In some applications, you may wish to take advantage of some of the features of a registration flow without requiring the end user to confirm their email or account information.

For example, you might have a mobile application that seeks to offer a user registration page with one-click account creation. When the user clicks "Create", the application should complete the registration, thereby creating the user's account and sending a welcome email.

In effect, this is a shortcut version of the greater registration flow where the confirmation step is skipped. To use this flow, you create your registration and possibly update it as detailed above. However, instead of sending the confirmation email, you can "auto-confirm" the registration.

The method looks like this:

POST /pub/applications/{applicationId}/registrations/{registrationId}/autoconfirm

In order to use this, you must add a boolean JSON property to your application, like this:

{
    "public": {
        "allowRegistrationAutoConfirm": true
    }
}

If your application has this public property in place, then auto confirmation will be enabled and your application will be able to one-hop the registration process.