Skip to main content

How to Configure Multi-Instance Portals

Summary​

This procedure guides you through configuring multi-instance Purpose-built App portals, enabling organizations to deploy multiple configurations of the same portal for different teams, departments, or use cases. Multi-instance configuration is essential for enterprise deployments where different user groups need customized portal experiences while maintaining centralized management.

Time Required: 20-30 minutes
Skill Level: Intermediate
Prerequisites: Completed Purpose-built App Quickstart

Steps​

Step 1: Enable Multi-Instance Configuration​

Configure your Purpose-built App Plugin to support multiple instances by adding the multi-instance configuration object.

Edit Plugin Configuration​

Open your Plugin's config.json file and locate the configurationSettings section. Add the multiInstanceConfiguration object:

{
  "metadata": {
    "configurationSettings": {
      "configurable": true,
      "allowTabNameCustomization": true,
      "defaultEnabledState": false,
      "multiInstanceConfiguration": {
        "authType": "cxRoles"
      }
    }
  }
}

Set Authentication Type​

The authType property controls which backing auth integration powers the Users/Roles panes for each instance. It only accepts two values:

  • "cxRoles": Use the CX Roles–backed UI (recommended)
  • "roleService": Use the legacy Role Service UI

multiInstanceConfiguration does not accept any other properties — authType is the only field it supports.

Step 2: Deploy Multi-Instance Extension​

Submit your updated extension to enable multi-instance functionality.

Validate Configuration​

Before deployment, verify your configuration:

# Test configuration syntax
xmt validate extension

# Expected output: Configuration valid ✓

Submit Extension Changes​

Deploy your updated extension:

# Submit extension with multi-instance support
xmt submit extension

Share with Target Brands​

Share your extension with brands that need multi-instance capability:

  1. Navigate to Extension Registry
  2. Find your extension
  3. Click Share tab
  4. Add target brands with multi-instance requirements
⚠️ Important: Role Configuration Required

Regardless of which authType you choose, brand administrators must configure roles before users can access portal instances. This is a security feature that prevents unauthorized access.

Step 3: Configure Brand-Level Roles​

Brand administrators must set up roles to control instance access.

Access Role Management​

In the target brand:

  1. Navigate to Admin → User Management → Roles
  2. Click Create New Role or modify existing roles
  3. Look for your Purpose-built App permissions

Create Instance-Specific Roles​

Create roles for different portal instances:

Role Examples:
- "Support Portal - Tier 1 Agents"
- "Support Portal - Supervisors" 
- "Support Portal - Management"
- "Analytics Portal - Analysts"
- "Analytics Portal - Directors"

Assign Portal Permissions​

For each role, assign appropriate portal access:

  1. Select the role
  2. Navigate to Extensions permissions
  3. Find your Purpose-built App
  4. Assign Use and/or Configure permissions as needed

Step 4: Create Portal Instances​

Brand administrators can now create multiple portal instances with different configurations.

Access App Configuration​

Navigate to the App Configuration interface:

  1. Go to Admin → Extensions → My Apps
  2. Find your Purpose-built App
  3. Click Configure or Create Instance

Create New Instance​

For multi-instance portals, you'll see a Create Instance option:

  1. Click Create Instance
  2. Provide instance details:
    • Instance Name: Descriptive name for this configuration
    • Description: Purpose and target audience
    • Default State: Enabled or disabled for new users

Configure Instance Settings​

Customize the instance for its specific use case:

Instance Configuration Options:
├── Tab Selection
│   ├── Enable/disable specific tabs
│   ├── Customize tab names
│   └── Set tab-specific requirements
├── Branding
│   ├── Portal title and description
│   ├── Theme selection
│   └── Custom announcements
└── Access Control
    ├── Role-based restrictions
    ├── Feature flag requirements
    └── User assignment rules

Step 5: Assign Users to Instances​

Configure which users can access each portal instance.

Use Role-Based Assignment​

The recommended approach uses the role system:

  1. Navigate to User Management → Users
  2. Select users who need access
  3. Assign appropriate roles that include portal permissions
  4. Users will automatically see instances they have access to

Validate User Access​

Test that users see the correct portal instances:

  1. Log in as a test user with assigned roles
  2. Check the portal switcher (waffle menu)
  3. Verify only appropriate instances appear
  4. Test navigation between instances

Step 6: Monitor and Manage Instances​

Establish ongoing management processes for your multi-instance deployment.

Regular Access Reviews​

Periodically review instance access:

Monthly Review Checklist:
□ Verify active users still need access
□ Check for new users requiring access
□ Review role assignments for accuracy
□ Audit instance-specific configurations
□ Monitor usage analytics per instance

Instance Lifecycle Management​

Plan for instance evolution:

  • Creation: Document business justification for new instances
  • Modification: Track configuration changes with approval process
  • Retirement: Safely decommission unused instances
  • Migration: Move users between instances when needed

Performance Monitoring​

Track instance performance separately:

// Example: Instance-specific analytics
const trackInstanceUsage = (instanceId: string, action: string) => {
  analytics.track({
    event: 'portal_instance_usage',
    properties: {
      instanceId,
      action,
      timestamp: new Date().toISOString()
    }
  });
};

Recap​

You have successfully configured multi-instance Purpose-built App portals. This setup enables:

✅ Enterprise Flexibility​

  • Multiple portal configurations from a single extension
  • Department-specific customizations while maintaining consistency
  • Centralized management with distributed access control

🔒 Security and Governance​

  • Role-based access control for granular permissions
  • Instance-level isolation for sensitive use cases
  • Audit trail for configuration changes and user access

📊 Operational Benefits​

  • Reduced extension management overhead
  • Consistent user experience across instances
  • Scalable deployment model for growing organizations

Common Use Cases Enabled:​

  • Department-Specific Portals: Sales, support, marketing teams with tailored interfaces
  • Regional Variations: Localized portals for different geographic regions
  • Hierarchy-Based Access: Executive, manager, and employee portal variations
  • Project-Based Instances: Temporary portals for specific initiatives

Next Steps:​

  • Configure additional instances as needed
  • Set up automated user provisioning
  • Implement instance usage monitoring
  • Train portal administrators on management procedures
Security Reminder

Always follow the principle of least privilege when assigning portal access. Users should only have access to instances and features necessary for their role.

For advanced multi-instance patterns and enterprise deployment strategies, review the Purpose-built App Deep Dive guide.