How to implement my own register form

Teach on Mars application may allow users to create their own account. But they also allow clients to customize the register form that learners use to create their account and update their profile information.

Technically, the register form is a web application hosted anywhere that is loaded in a web view of the application. So, it is easy to configure a custom register form as long as it follows some requirements, which we will go through in this article.

Depending on how the learner accounts are managed, there might also be additional developments required. This article will cover that as well.

Requirements for your custom register form

Online responsive web application

The register form must be a web application that is accessible online. It will be displayed in either a mobile web view or in the webapp. Therefore, the design must be responsive so that it can be displayed in multiple screen sizes and ratios.

Learner account creation

The register form is responsible for creating the learner account in the Mission Center using a web service.

Learner account update

The register form is also responsible for updating the learner information in the Mission Center using a web service. The form will receive the learner ID as a query parameter.

Learner authentication in the app

The register form must also log the learner in the application when the account creation is complete.

Use the web services

How to call the Mission Center web services

The Mission Center web services require a specific authentication technique that is described in the article How to use the Mission Center Web services. Please refer to it when you need to implement your WS authentication methods.

How to create a new learner in the Mission Center

To create a learner in the Mission Center, the following request should be sent (see documentation):

POST /api/identities/v1/learners
{
 "login" : "john.doe",
 "firstname" : "John",
 "lastname" : "Doe",
 "email" : "john.doe@company.com",
 "password" : "ACu$tomPassword!",
 "segment": {
   "country": ["FRANCE"]
 },
 "options": {
   "notifyLearner": true
 }
 "lang": "en-GB"
}

Response:
{
 "identifier": "46e11440-ea40-11e7-a88a-3d64957b0864",
 "email": "john.doe@company.com",
 "login": "john.doe,
 "metadata": {
   "country": ["FRANCE"]
 },
 "status": "Active",
 ...
}

Some details about this payload:

• The login is always mandatory and must be unique. Either you define an email address and the password field is optional, or you define a password and the email field can be omitted. 
• The segment relates to the custom fields in the Mission Center.
• If the option notifyLearner is set to true, an email will be sent to the learner when the account is created. This email can be customized and translated by the Teach on Mars production team.
• The email will be sent in the language set to the learner through the lang property.

How to update the learner in the Mission Center

To update a learner in the Mission Center, the following request should be sent (see documentation)

PUT /api/identities/v1/learners/{learnerId}
{
 "login" : "john.doe",
 "firstname" : "John",
 "lastname" : "Doe",
 "email" : "john.doe@company.com",
 "segment": {
   "country": ["FRANCE"]
 },
 "lang": "en-GB"
}

Response:
{
 "identifier": "46e11440-ea40-11e7-a88a-3d64957b0864",
 "email": "john.doe@company.com",
 "login": "john.doe,
 "metadata": {
   "country": ["FRANCE"]
 },
 "status": "Active",
 ...
}

Some details about this payload:

• Fields not included into the payload will not be updated
• The segment relates to the custom fields in the Mission Center.

Obtain the information of a learner to pre-fill the edition form

Request (see documentation)

GET /api/identities/v1/learners/{learnerId}
Response:
{
 "response": {
   "learnerId": "46e11440-ea40-11e7-a88a-3d64957b0864",
   "email": "john.doe@company.com",
   "login": "john.doe,
   "metadata": {
     "country": "FRANCE"
   },
   ...
 }
}

Log the learner in the application

Once the learner is created in the Mission Center, you need to obtain an authentication token from the Mission Center and pass it to the application. This will lead to the learner being authenticated in the app. Here's how it works : Obtain an authentication token

Implications of the register form

Password and authentication management

The register form must deal with the account creation in the Mission Center, but it doesn't tell us which system should be responsible for the authentication of the users.

There are a few operations relative to the password maintenance and they need to be consistent. These operations are:

• User authentication
• Password update by the user
• Password reset, when the user has lost the password

The important question is: which system does maintain the passwords of the users?

Option 1: the distant system

Operations like authentication, password update and password reset must be dealt with in the distant system.

See later how you can deal with these operations.

Option 2: the Mission Center always knows the right passwords

You just need to make sure that, if there is an update form that allows password update, the new password is updated in the Mission Center.

Apart from that, the Mission Center will take care of authentication and password reset.

Password maintenance operations

Read more about how to customize the learner authentication service

Read more about how to customize the password recovery process

Project sheet

Things to consider when planing this kind of integration: