Drupal

Contents

Migrating from v2 to v3

Differences between v2 and v3

v2 v3
Screens Files .ZIP upload not supportedRequires upload of individual files or manual creation of folder and file copy procedure New Format!Single .ZIP file to upload, supports multiple .ZIP files
Example Example configuration installed without uninstall option Example configuration is optional to install and enable
Data Mapping Custom UI Uses Drupal Rules
Information tab None Includes an Information tab on the Janrain Configuration Page that provides the site installer and builder access to Janrain configuration information to assist with troubleshooting
Janrain Social Share version 2 (as of October 2014) version 3
Upgrades No v1 upgrade to v2 available Upgrade from v2.13 to v3 requires:

  • Configuration changes (Rules for mapping, screens file)
  • A SQL script

Should I Upgrade or Do a New Install?

For sites that have user profiles connected with comments and other user-generated content we recommend taking a few steps to make sure the data is all properly tied together upon upgrade from v2 to v3. To help you do this, we have provided a SQL script below that you can ask your DBA to run on your Drupal database.

If log-in is used purely as a gateway to additional content and is not tied to user-created posts, comments, pages, or other content, it is possible to simply uninstall v2 and install v3. All user data resides safely on Janrain’s servers and will update on the Drupal site as soon as the user logs in again.

Note: The connection between the user and the user’s content is stored in the Drupal database and not in Registration. Content can be anything in Drupal that may be associated with a user (depending on how the Drupal site is set up).

For sites that configure data mapping, the logic must be recreated using our new integration with Drupal Rules.

Upgrading from v2 to v3

With version 3 of the Janrain module we combined the Social Login (Engage) and Registration (Capture) modules into a single, more efficient module (with submodules that can be enabled to add functionality as desired). The processes of upgrading from either v2 module are similar as a result of our continued use of the authmap table in the database to map the authentication.

To upgrade from v2 to v3:

1. Run the SQL migration script that matches your module (either Engage or Capture):

SQL script for upgrading from Janrain Registration (Capture):

SQL script for upgrading from Janrain Social Login (Engage):

2. Disable, uninstall, and delete the v2 module(s).

3. Download, enable, and configure the v3 module to use the same app.

  1. Rewrite any data mappings as Drupal Rules.
  2. Obtain a new screens package from your Janrain representative.

Prerequisites

Installation

The Janrain module is the main (core) module, and consists of a number of submodules. A module (including the main module) must be enabled to implement its functionality.

Each module you enable adds another layer of Janrain functionality (Social Login, Registration, and so on) to the Drupal site.

The following table describes all of the v3 modules and submodules:

Name Module or Submodule Required or Optional Description
Janrain module Required The main (core) Janrain services module that must be enabled to implement the integration.
Enabling Janrain core makes certain hooks available to expert programmers who want to write their own implementation of Janrain services.
Janrain Admin UI submodule Optional Turns on the Janrain administrative UI tabs. This could be disabled in the case where a customer does not want Drupal administrators to change the configuration.
Enabling Admin UI creates a page where you can configure your Janrain Social Login and/or Registration implementations.
Janrain Data submodule Optional Enabling Janrain Data creates mapping between Janrain customer profile data and Drupal fields.
Janrain Example submodule Optional Includes a reference implementation of Janrain services on a Drupal site (that is, it implements all the other modules on the Drupal site).

Janrain Example implements fully-functional versions of Janrain core, Janrain User Interface, and Janrain Data on a Drupal site. We encourage you to copy and customize this submodule to meet your needs.

The Example submodule activates Drupal users who are already linked to Registration accounts, so that a user logged in to a Registration account will also be logged in to Drupal. (Specifically, users logged in via Janrain are marked in Drupal as “active”.) The user’s status is permanently switched as soon as the blocked user logs in. This functionality is included to ensure a smoother demo and user experience.

When the Example submodule is disabled or not in use, Janrain honors Drupal bans (but does not record them in Registration).

Janrain Social Sharing submodule Optional Integrates Janrain Social Sharing on a Drupal site.

Enabling Janrain Social Sharing creates a field that can be placed anywhere that a Drupal field is allowed. The field displays the Janrain Social Sharing widget and allows users to share the page on which the field is located.

Janrain User Interface submodule Optional Enables the management of Janrain user interfaces (widgets) for placement on the Drupal site.

Enabling Janrain User Interface creates blocks that can be placed in Drupal structures that display the various components of Social Login and Registration.

Install the Janrain Module

For more information, see Installing modules (Drupal 7) in Drupal’s online help.

1. Install and enable the Janrain v3 module from https://www.drupal.org/project/janrain. Answer yes to enable dependent modules.

module-list

Figure 1: Enable Janrain v3 Dependent Modules

2. Configuration > People > Account Settings. If this is a new site, configure the user registration parameters.

account-settings

Figure 2: Configuration > People > Account Settings

Janrain core doesn’t have configuration methods, so after enabling it, we recommend enabling Janrain Admin UI, which allows you to configure Janrain core.

To prevent users with more limited permissions from changing the configuration, disable the Janrain Admin UI. The configuration will remain but the forms to change the configuration will be removed until Janrain Admin UI is enabled again.

When the Janrain module is in Social Login-only mode, the module doesn’t change the Configuration > People > Account settings; it honors them (admins beware!). However, when the Janrain module is in Registration mode, it forces the Who can register accounts? setting to Administrators Only since Registration should own registrations.

The Drupal Require email verification when a visitor creates an account setting is just something we honor. Drupal accounts won’t be created if this setting is active, and we don’t have verified emails on Social Login or Registration profiles.

This is also why it is best practice to make emails required, unique, and verified. But you are allowed to operate in the completely unsecured mode of unverified emails.

The Log-in Escape Hatch

If you set up an admin account that is not connected to a Janrain user account, you may not be able to log in through the account provided by Janrain. If there is a problem with your configuration that affects Janrain registration and/or sign-in, you can use this URL to gain access to Drupal: http://sitedomain/user/login.

If you are using localhost and you cannot log in to the admin account via this URL, make sure your base URL is set correctly in your /sites/default/settings.php file.

Switching between Social Login and Social Login + Registration Configurations

When switching between Social Login and Social Login + Registration modes, remember to flush the caches (in Configuration > Development > Performance, click Clear all caches).

Steps for Social Login

Configure the Janrain Module

1. Configuration > People > Janrain

config-janrain

Figure 3: Configuration > People > Janrain

2. Select Social Login as the product type.

janrain product

Figure 4: Select Social Login as the Product Type

3. Enter your API key from the Janrain Engage dashboard for the app you wish to use.

api key

Figure 5: Enter your API Key

4. The settings information will appear on the Information tab after configuration has been saved:

drupal information

Figure 6: Settings Information

Configure Profile Data Mapping from Janrain to Drupal

Enable the Janrain Data submodule.

Engage paths take the form of $.profile.identifier or $.merged_poco.identifier

For Facebook IDs, use $.profiles[?(@.name=="facebook")].identifier

Use the Provider Guide to determine which attributes are returned by which provider.

Steps for Social Login + Registration

Configure the Janrain Module

1. Configuration > People > Janrain

account settings-2

Figure 7: Configuration > People > Janrain

2. Select Social Login + Registration as the product type.

janrain product 2

Figure 8: Select Social Login + Registration as the Product Type

3. Enter your Registration app URL, Client ID, and Client secret.

login + registration settings

Figure 9: Enter your Registration App URL, Client ID, and Client Secret

4. Upload the .ZIP file.

upload zip file

Figure 10: Upload the .ZIP file

After you upload the .ZIP file, the Manage section expands.

upload zip file 2

Figure 11: The Manage Section Expands

5. The settings information will appear on the Information tab after the configuration has been saved:

drupal information 2

Figure 12: Settings Information Appears on the Information Tab

Configure Profile Data Mapping from Janrain to Drupal

Capture paths take the form of $.uuid.

1. Enable the Janrain Data submodule.

2. In Modules, enable Rules UI Module.

3. Configuration > Workflow > Rules > Add new rule

add new rule

Figure 13: Configuration > Workflow > Rules > Add New Rule

4. Enter a Name for the Rule.

5. For React on event, select Janrain customer information updated.

add new rule-2

Figure 14: Select Janrain Customer Information Updated

5. Click Save.

6. Select Add Action.

add action

Figure 15: Select Add Action

7. Select Store Janrain customer information.

store customer information

Figure 16: Select Store Janrain Customer Information

8. In the Value field, add a variable such as $.uuid.

9. Expand the Data selector and find a selector such as site:current-user:name.

destination of data

Figure 17: Find a Selector

10. Click Save.

Add Janrain Sharing to the Site

1. Enable the Sharing submodule.

2. Structure > Content Types

content types 1

Figure 18: Structure > Content Types

3. Edit the Basic Page content type.

content types 2

Figure 19: Edit the Basic Page Content Type

4. Click Manage Fields.

manage fields

Figure 20: Click Manage Fields

5. Add a new field and widget: Janrain Share.

6. Social sharing can only be added to pages. Add a new basic page to the site (Content > Add Content > Basic Page) and sharing will be displayed on that page.

Add the Janrain Social Login Block to the Site

1. Enable the Janrain Admin UI submodule.

2. Select Administration > Structure > Blocks.

blocks

Figure 21: Select Administration > Structure > Blocks

3. Identify the location for the new block.

block location

Figure 22: Identify the Location for the New Block

Adding the Social Login block to the Help section creates this layout:

social login block layout

Figure 23: Adding the Social Login Block to the Help Section Creates this Layout

TEST CASE–Display Message based on Janrain/Drupal Value

1. Ensure Rules UI module is enabled.

2. Configuration > Workflow > Rules > Active Rules.

3. Select your Rule.

select your rule

Figure 24: Select your Rule

4. Select Add Action.

add action 2

Figure 25: Select Add Action

5. Select Add a variable and click Continue.

add a variable

Figure 26: Select Add a Variable and Click Continue

6. For Value, select Text.

value - text

Figure 27: For Value, Select Text

7. Select Continue.

8. Modify the default variable name.

provided variables

Figure 28: Modify the Default Variable Name

9. Select Save.

10. Select Add Action.

add action 3

Figure 29: Select Add Action

11. Select Show Message on Site.

12. Place the variable in the Message.

message

Figure 30: Place the Variable in the Message

13. Save.

14. Configuration > Performance > Clear all caches.

Implementations

One Site (Mom and Pop)

Follow the Installation instructions to implement Janrain services on one site.

Multiple Sites (Consistent, Reliable, Repeatable Service)

To implement Janrain services across multiple sites, you can create a Drupal submodule based on the Janrain Example submodule and install this customized module on all your Drupal sites.

The Example submodule:

The Example submodule contains the following files:

Example Submodule File Description
janrain_example.info In addition to describing the submodule and setting dependencies, this file contains the initial field_base calls for the fields that the Rules will populate.

( features[field_base] [ ] = field_birthday )

janrain_example.install Handles user/login issues using menu_link_maintain. Uses janrain_example_node_create() to create pages for password recovery and email verification. Note that text for those pages is created here as well as the path, which in the example includes the word “janrain” to prevent duplication.
janrain_example.module Overrides Drupal login/registration/logout. Checks to see if the settings for password recovery and email verification on the Janrain dashboard match the ones created in the example.
janrain_example.rules_defaults.inc Creates some example Rules using Drupal and Janrain SDK tools.
janrain_example.features.field_base.incjanrain_example.features.field_instance.inc Defines the fields that Rules map into.
login.php Adds Social Login to sign-in/sign-up pages. Maps incoming pictures onto user data.
registration.php Creates the tab for edit Janrain profile on user pages. Handles log-in. Places or hides blocks according to signed-in state. More password recovery and email verification node setup.

Before creating your own submodule based on the Janrain Example, read through all the code as many tasks are accomplished through actions in multiple files.

To create your own submodule, copy the Example into a different folder of the Janrain module folder and give it a unique name. For example, instead of “Example” it could be “Bluesites” and the .info file might have the name “Janrain Bluesites”.

This is a task best suited for someone who has written modules before. The commenting is clear and it should be possible to make a solid submodule based on the given examples. Adding Rules involving numbers may mean adding dependencies on Drupal modules that support certain number types.

Always work in a development environment first, and happy coding!

Advanced Module Builds (for Drupal Programmers)

If you have Drupal programming expertise on your staff, you can use the Janrain core module in standalone mode (that is, use the core module itself, without enabling any of the submodules) with the Janrain-provided hooks and function calls.

To use the Janrain core module in standalone mode, you need to configure your Registration widget to have an event handler that posts the response code to the Drupal service endpoint and “primes” the log-in. When you’re ready to actually log in, submit a login form to the regular Drupal login endpoint and the module will take care of Drupal account creation, linking, or log-in.

If you want to hook into data events without the Rule module, your module should implement a hook_janrain_profile_received() handler which will receive a reference to a Janrain::Profile object. This object has some convenience methods for working with the Profile: