📘

The content on this page was written for a legacy feature of the ​Akamai​ Identity Cloud (in this case, the JavaScript SDK). The basic content is still valid; however, the procedures described here no longer have to be carried out by using the Identity Cloud REST APIs; instead, they can be completed (perhaps a little quicker and a little more efficiently) by using Console. See the individual notes for links to the Console equivalents.

By default, the standard registration experience includes the standard flow and the user entity type, and for most cases this suffices. However, when managing the complexity that comes hand-in-hand with multiple brands, sometimes it's necessary to implement additional flows and entity types.

When to create multiple flows

If one of the following scenarios applies to your brand or site you might consider creating another copy of your flow:

• Brand A requires pieces of information that should be optional for Brand B.
• Your sites or brands are very different aesthetically, and you use Akamai's transactional emails.

You can copy a flow by making a POST request to the /config/{app}/Flows/{Flow}/copy operation. You can then reference this new flow at your site by using the flowName and flowVersion settings:

janrain.settings.capture.flowName = "myNewFlow";
janrain.settings.capture.flowVersion = "01234567890123456789";

The following subsections describe the preceding use cases in more detail.

📘

See Copy a flow to learn how to copy a flow in Console.

Brand A requires pieces of information that should be optional for Brand B

Suppose you have site A and site B. Site A requires birthdate, but site B does not. Suppose that, in order to fulfill the requirements of site A, you have created a birthday field that has the required validation rule.

At first consideration, in order to fulfill the requirements of site B it might seem like a good idea to create another birthday field that doesn’t have the required validation rule (let’s call this field “birthdayOptional”), and then to exclude the required birthdate field on site B.

Unfortunately, this won't work. Although Site A uses the birthday field and site B uses the birthdayOptional field, both sites use the same registration form in the flow. Therefore, while site B might exclude the JTL tag markup on the registration screen for the required version of the birthday field, the registration form in the flow still expects this field to be submitted. Since the birthday field has the required validation rule, registration always fails with validation errors on site B.

One alternative is to make both fields optional, and implement your own client-side JavaScript validation on site A where birthday is required. However, this approach excludes server-side validation (not a recommended practice). Therefore, it's better in these cases to create a copy of your existing flow, add, remove, or modify fields on the new flow, and then direct each site to the respective flow.

Your sites or brands are very different aesthetically, and you use Akamai's transactional emails

A single flow assumes the same general look and feel for email templates across all sites–for instance, maybe the registration confirmation email has a 3-column horizontal layout with a title and body. The email template then may include JTL tags that allow variation in images, welcome messages, or values for style elements in order to give each site a different feel/appearance.

However, what if you want to have a registration confirmation email for Site A that has a 3-column layout, but for Site B you want to have a single-column layout?

Because a single flow only allows only one template across sites for each transactional email type, both sites need to share the same template. At first glance, putting HTML into API client settings and then referencing those in your emails might seem like a feasible solution. However, this approach is not recommended; API client settings values are escaped and printed as plain text.

Therefore, if you wish to achieve dramatically different email template layouts for each site the best approach is to create a copy of your flow and modify the email templates in the new flow.

Alternatively, consider utilizing Integrate third-party analytics if your transactional email solution requires a high degree of customization.

When to implement multiple entity types

If one of the below scenarios applies to your sites/brands, then you may want to consider creating a new entityType:

• Sites A and B are two drastically different brands; it would be too complex to incorporate all brand structures into one schema for user profile data.

• You wish to segment users from Site A and users from Site B and therefore cannot have data in common between the two sites.

• You do not want your users to view brands as associated with each other; for instance, sharing the same login experience between child and adult brands.

• Site A has special membership validations and users from site B shouldn’t be able to login with their profile from site B. A common example is meeting legal agreements for doctor-login portals between countries.

Generally speaking, To implement multiple entityTypes, you need to change both the Flow and the API client settings in the Console, in addition to creating your new entityType.

1. Create your new entityType by making a POST call to the /entityType.create operation. If you want to copy an existing entity and modify it, you can do this by copying the attr_defs object from a GET request on the desired entityType. You must not include the id or uuid attributes, as these are automatically created with the new entityType. Below is an example value for the attr_defs URL parameter, which creates an entityType with the “name” and “description” attributes.

[
     {     
       "name":"name",
       "type":"string",
       "case-sensitive":false   
     },   
     {
       "name":"description",
       "type":"string",
       "length": 1000,     
       "case-sensitive":false   
     }
    ]

2. In the Flow, add the list of entityTypes to the schemas object in the Flow. Below is an example PUT request adding the entityType user_2 to the Flow. Note, make sure to include in your request all entityTypes that this flow may be used with, not just the entityType you wish to add.

{
     "userData": [
       "email",
       "displayName"
     ],
     "schemas": [
       "user",
       "user\_2"
     ]
    }

3. In your API client settings add the user_entity_type setting to all clients to specify the entityType each uses.

   

📘

See Create a schema for information on creating schemas in Registration Builder.

📘

The content on this page was written for a legacy feature of the ​Akamai​ Identity Cloud (in this case, the JavaScript SDK). The basic content is still valid; however, the procedures described here no longer have to be carried out by using the Identity Cloud REST APIs; instead, they can be completed (perhaps a little quicker and a little more efficiently) by using Console. See the individual notes for links to the Console equivalents.

By default, the standard registration experience includes the standard Flow and user entityType, and for most cases this suffices. However, when managing the complexity that comes hand-in-hand with multiple brands, sometimes it is necessary to implement additional Flows and entityTypes.

When to create multiple flows

If one of the below scenarios applies to your brand/site, then you may want to consider creating another copy of your Flow:

• Brand A requires pieces of information that should be optional for Brand B
• Your sites/brands are very different aesthetically, and you use Akamai's transactional emails

You can copy a Flow by making a POST request to the /config/{app}/Flows/{Flow}/copy operation. Then, you can reference this new Flow at your site via the flowName and flowVersion settings:

janrain.settings.capture.flowName = "myNewFlow";
janrain.settings.capture.flowVersion = "01234567890123456789";

The following subsections describe the above use cases in more detail.

Brand A requires pieces of information that should be optional for Brand B

Suppose you have site A and site B. Site A requires birthdate, but site B does not. Suppose that, in order to fulfill the requirements of site A, you have created a birthday field that has the required validation rule.

At first consideration, in order to fulfill the requirements of site B it may seem like a good idea to create another birthday field that doesn’t have the required validation rule (let’s call this field “birthdayOptional”), and then to exclude the required birthdate field on site B.

Unfortunately, this would not work. Although Site A uses the “birthday” field and site B uses the “birthdayOptional” field, both sites use the same registration form in the Flow. Therefore, while site B may exclude the JTL tag markup on the registration screen for the required version of the birthday field, the registration form in the Flow still expects this field to be submitted to it. Since this “birthday” field has the required validation rule, then registration will always fail with validation errors on site B.

One alternative may be to make both fields optional, and then to implement your own client-side JavaScript validation on site A where birthday is required. However, this approach excludes server-side validation (not a recommended practice). Therefore, it is better in these cases to create a copy of your existing Flow, add/remove/modify fields on the new Flow, and then direct each site to the respective Flow.

Your sites or brands are very different aesthetically, and you use Akamai's transactional emails

A single Flow assumes the same general look and feel for email templates across all sites–for instance, maybe the registration confirmation email has a 3-column horizontal layout with a title and body. The email template then may include JTL tags that allow variation in images, welcome messages, or values for style elements in order to give each site a different feel/appearance.

However, what if you want to have a registration confirmation email for Site A that has a 3-column layout, but for Site B you want to have a single-column layout?

Since a single Flow only allows only one template across sites for each transactional email type, then both sites would need to share the same template. At first glance, putting HTML into API client settings and then referencing those in your emails may seem like a feasible solution. However, this approach is not recommended; API client settings values are escaped and printed as plain text.

Therefore, if you wish to achieve dramatically different email template layouts for each site the best approach is to create a copy of your Flow and modify the email templates in the new Flow.

Alternatively, also considering utilizing third-party email integrations if your transactional email solution requires a high degree of customization.

When to implement multiple entityTypes

If one of the below scenarios applies to your sites/brands, then you may want to consider creating a new entityType:

• Sites A and B are two drastically different brands; it would be too complex to incorporate all brand structures into one schema for user profile data.

• You wish to segment users from Site A and users from Site B and therefore cannot have data in common between the two sites.

• You do not want your users to view brands as associated with each other; for instance, sharing the same login experience between child and adult brands.

• Site A has special membership validations and users from site B shouldn’t be able to login with their profile from site B. A common example is meeting legal agreements for doctor-login portals between countries.

Generally speaking, To implement multiple entityTypes, you need to change both the Flow and the API client settings in the Console, in addition to creating your new entityType.

1. Create your new entityType by making a POST call to the /entityType.create Capture endpoint. If you want to copy an existing entity and modify it, you can do this by copying the attr_defs object from a GET request on the desired entityType. You must not include the id or uuid attributes, as these are automatically created with the new entityType. Below is an example value for the attr_defs URL parameter, which creates an entityType with the “name” and “description” attributes.

[
     {     
       "name":"name",
       "type":"string",
       "case-sensitive":false   
     },   
     {
       "name":"description",
       "type":"string",
       "length": 1000,     
       "case-sensitive":false   
     }
    ]

2. In the Flow, add the list of entityTypes to the schemas object in the Flow. Below is an example PUT request adding the entityType user_2 to the Flow. Note, make sure to include in your request all entityTypes that this flow may be used with, not just the entityType you wish to add.

{
     "userData": [
       "email",
       "displayName"
     ],
     "schemas": [
       "user",
       "user\_2"
     ]
    }

3. In your API client settings add the user_entity_type setting to all clients to specify the entityType each uses.