Allowing Existing Users to Opt Into a New Role in Ultimate Member

Overview

This guide explains how to allow existing users to opt into an additional Ultimate Member role while keeping their current roles intact. By default, Ultimate Member assigns a single role per user, but with minor customizations, users can retain multiple roles when opting for a new one.

Example Use Case

Our site has approximately 14,000 existing users, many of whom are customers or subscribers. We want to introduce a new user role, Narrative Connections Members, for a therapist directory. Many users interested in becoming Narrative Connections Members are already registered on the site. Therefore, we need a process that allows existing users to opt into this new role without losing their current roles.

Requirements

  • Ultimate Member plugin installed and activated
  • Ultimate Member Forms
  • A method to modify user roles dynamically (e.g., a custom function or automatic URL-based opt-in)

Step 1: Create a Custom Registration or Opt-In Form

  1. Navigate to Ultimate Member > Forms.
  2. Click Add New and select Registration Form.
  3. Add necessary fields, including an opt-in field (e.g., a checkbox for selecting the new role).
  4. Save the form.

Step 2: Add a Custom Code Snippet to Retain Existing Roles

To ensure users retain their existing roles when opting into a new one, add the following PHP snippet to your theme’s functions.php file or a custom plugin:

function um_add_role_without_removal( $user_id ) {
    // Get the user object
    $user = get_user_by( 'ID', $user_id );
    
    // Check if the opt-in field is set in form submission
    if ( isset( $_POST['um_optin_role'] ) && $_POST['um_optin_role'] == 'yes' ) {
        
        // Define the new role
        $new_role = 'narrative-connections'; // Replace with the actual role slug
        
        // Get current roles
        $current_roles = $user->roles;
        
        // Add the new role if not already assigned
        if ( !in_array( $new_role, $current_roles ) ) {
            $user->add_role( $new_role );
        }
    }
}
add_action( 'um_after_user_is_approved', 'um_add_role_without_removal', 10, 1 );

Alternative Method: URL-Based Opt-In for Existing Users

For a quick opt-in process, existing users can be assigned the new role via a URL-based trigger. Add the following snippet to your site’s functions.php file or run it using the WPCode plugin:

add_action( 'template_redirect', 'um_09132024_add_new_role', 10 );
function um_09132024_add_new_role() {
    if ( isset( $_REQUEST['umm_update_user'] ) && ! current_user_can( 'manage_options' ) ) { 
        $user_id = get_current_user_id();
        $user = get_user_by( 'ID', $user_id );
        $user->add_role( 'um_narrative-connections' );
        UM()->common()->users()->set_as_pending( $user_id );
    }
}

How to Use the URL-Based Opt-In

  1. Ensure the above snippet is active.
  2. Direct users to visit the following URL while logged in: 
    yoursite.com?umm_update_user=true
  3. Upon visiting this URL, their account will be updated with the Narrative Connections Member role.
  4. You can verify the role assignment by checking Users > All Users in WordPress admin.

Step 3: Assign the Custom Field to Your Opt-In Form

  1. Edit your previously created opt-in form.
  2. Add a Checkbox field and set its meta key to um_optin_role.
  3. Configure the field label (e.g., Opt into Narrative Connections Membership).
  4. Save the form.

Step 4: Test the Functionality

  1. Log in as a test user and access the opt-in form or visit the URL-based opt-in link.
  2. Submit the form with the opt-in option selected (if using a form-based method).
  3. Navigate to Users > All Users in the WordPress admin panel.
  4. Verify that the user retains their original role(s) and now has the additional Narrative Connections Member role.

Conclusion

With this setup, existing users can opt into new roles while maintaining their previous ones. This is particularly useful for communities with multiple role-based access levels, ensuring seamless role upgrades without overwriting previous permissions.

For further customization, developers can modify the PHP snippet to accommodate specific role conditions or integrate additional features based on user choices.

Warning: We have created this code example to provide guidance and to make it easier for you to implement this code into your website. However, we are not able to provide any support when it comes to customizing the plugin. If you need help implementing this code, please hire a developer.