Modular Service Portal Architecture…

intermediateTested on Xanadu

The Modular Service Portal Architecture Pattern establishes a structured approach to building Service Portals using reusable widget components organized into distinct functional categories. This pattern separates layout widgets (containers, navigation, styling) from data widgets (forms, lists, displays) and creates a clone-safe widget library that can be versioned and deployed across multiple portals.

This pattern solves the common problem of widget sprawl and tight coupling that occurs when organizations build Service Portals organically without architectural planning. Without proper modularization, widgets become tightly coupled to specific portals, contain mixed layout and business logic, and become difficult to maintain or reuse. The pattern works by establishing widget naming conventions, creating base widget classes for inheritance, and implementing a widget registry system that manages dependencies and configurations across portal instances.

The architecture promotes consistency across portals while enabling customization through configuration rather than duplication. Widget libraries become assets that can be shared across business units, tested independently, and evolved without breaking existing portal implementations.

Chrome Extension

Sourdough: ServiceNow Monitoring and Analytics

A Chrome extension for ServiceNow Admins and Developers with essential tools, analytics, graphs and monitoring features.

Instance HealthGraphs & ChartsAPI HealthDeveloper ToolsQuick SearchInstance Switcher

Add to Chrome

Free to install. Pro $5/month after a 14-day no-card trial.
Pro requires the ServiceNow admin role. Upgrade inside the extension.

Overview

Tasks

CMDB

API

Metrics

Monitor

Internals

Instance:sourdoughdev·Version:Yokohama

Instance StateONLINE

System StatusFully Operational

Session Timeout90 minutes

Logged-In Sessions2 (20 active)

Build Nameyokohama-12-18-2024_p1

IP Address10.159.128.43

Instance HealthHealth Score: 90%

🔥 5dSourdough (Chrome Plugin)Dark Mode

Use This When

Use this pattern when building multiple Service Portals across an organization, when you need to maintain consistent branding and functionality across portals, or when you anticipate significant portal customization requirements. This pattern is essential for organizations with complex portal requirements, multiple business units sharing common functionality, or environments where portal widgets need frequent updates without impacting stability.

Avoid When

Avoid this pattern for single-portal implementations with simple requirements or proof-of-concept portals where rapid prototyping is more important than maintainability. The overhead of establishing modular architecture may be excessive for small organizations with limited ServiceNow development resources or when portal requirements are unlikely to expand beyond basic functionality.

Implementation

Server-side

// Widget Library Manager Script Include
var WidgetLibraryManager = Class.create();
WidgetLibraryManager.prototype = {
    initialize: function() {
        this.WIDGET_CATEGORIES = {
            LAYOUT: 'layout',
            DATA: 'data', 
            NAVIGATION: 'navigation',
            UTILITY: 'utility'
        };
        this.WIDGET_PREFIX = 'lib_';
    },

    // Create widget registry entry for tracking dependencies
    registerWidget: function(widgetId, category, dependencies, config) {
        var registry = new GlideRecord('u_widget_registry');
        registry.initialize();
        registry.widget_id = widgetId;
        registry.category = category;
        registry.dependencies = JSON.stringify(dependencies || []);
        registry.default_config = JSON.stringify(config || {});
        registry.version = '1.0.0';
        registry.is_library_widget = true;
        var sysId = registry.insert();
        gs.info('Registered widget: ' + widgetId + ' in category: ' + category);
        return sysId;
    },

    // Get widget configuration for specific portal
    getWidgetConfig: function(widgetId, portalId) {
        var config = {};
        
        // Get base configuration from registry
        var registry = new GlideRecord('u_widget_registry');
        if (registry.get('widget_id', widgetId)) {
            config = JSON.parse(registry.default_config.toString() || '{}');
        }
        
        // Override with portal-specific configuration
        var portalConfig = new GlideRecord('u_portal_widget_config');
        portalConfig.addQuery('widget_id', widgetId);
        portalConfig.addQuery('portal_id', portalId);
        if (portalConfig.next()) {
            var overrides = JSON.parse(portalConfig.configuration.toString() || '{}');
            config = this._mergeConfigs(config, overrides);
        }
        
        return config;
    },

    // Validate widget dependencies before deployment
    validateDependencies: function(widgetId, targetPortal) {
        var registry = new GlideRecord('u_widget_registry');
        if (!registry.get('widget_id', widgetId)) {
            return { valid: false, message: 'Widget not found in registry' };
        }
        
        var dependencies = JSON.parse(registry.dependencies.toString() || '[]');
        var missingDeps = [];
        
        for (var i = 0; i < dependencies.length; i++) {
            var depWidget = new GlideRecord('sp_widget');
            if (!depWidget.get('id', dependencies[i])) {
                missingDeps.push(dependencies[i]);
            }
        }
        
        if (missingDeps.length > 0) {
            return { valid: false, message: 'Missing dependencies: ' + missingDeps.join(', ') };
        }
        
        return { valid: true, message: 'All dependencies satisfied' };
    },

    // Clone widget with proper library conventions
    cloneLibraryWidget: function(sourceWidgetId, targetWidgetId, customizations) {
        var sourceWidget = new GlideRecord('sp_widget');
        if (!sourceWidget.get('id', sourceWidgetId)) {
            throw new Error('Source widget not found: ' + sourceWidgetId);
        }
        
        var newWidget = new GlideRecord('sp_widget');
        newWidget.initialize();
        newWidget.id = this.WIDGET_PREFIX + targetWidgetId;
        newWidget.name = customizations.name || sourceWidget.name + ' (Custom)';
        newWidget.template = customizations.template || sourceWidget.template;
        newWidget.client_script = customizations.client_script || sourceWidget.client_script;
        newWidget.server_script = customizations.server_script || sourceWidget.server_script;
        newWidget.css = customizations.css || sourceWidget.css;
        newWidget.option_schema = customizations.option_schema || sourceWidget.option_schema;
        newWidget.demo_data = customizations.demo_data || sourceWidget.demo_data;
        newWidget.description = 'Cloned from library widget: ' + sourceWidgetId;
        
        var newSysId = newWidget.insert();
        gs.info('Cloned widget ' + sourceWidgetId + ' to ' + newWidget.id);
        return newWidget.id.toString();
    },

    _mergeConfigs: function(base, overrides) {
        var merged = JSON.parse(JSON.stringify(base)); // Deep copy
        for (var key in overrides) {
            merged[key] = overrides[key];
        }
        return merged;
    },

    type: 'WidgetLibraryManager'
};

Client-side

// Base Widget Client Script Pattern for Library Widgets
function($scope, $http, spUtil, $window) {
    var c = this;
    
    // Initialize widget with library configuration
    c.initialize = function() {
        // Get widget configuration from server
        c.server.get({
            action: 'getLibraryConfig',
            widget_id: c.options.widget_id || 'default',
            portal_id: $window.location.pathname.split('/')[1]
        }).then(function(response) {
            c.config = response.data.config || {};
            c.initializeWidget();
        });
    };
    
    // Widget-specific initialization after config loaded
    c.initializeWidget = function() {
        // Override in specific widget implementations
        console.log('Base widget initialized with config:', c.config);
    };
    
    // Standard error handling for library widgets
    c.handleError = function(error, context) {
        console.error('Widget error in ' + (context || 'unknown context') + ':', error);
        c.errorMessage = c.config.show_errors ? error.message : 'An error occurred';
        spUtil.addErrorMessage(c.errorMessage);
    };
    
    // Standard loading state management
    c.setLoading = function(isLoading) {
        c.isLoading = isLoading;
        if (c.config.show_loading_spinner !== false) {
            c.showSpinner = isLoading;
        }
    };
    
    // Event bus for widget communication
    c.emitEvent = function(eventName, data) {
        $scope.$emit('widget.' + eventName, {
            widget_id: c.options.widget_id,
            data: data
        });
    };
    
    c.onEvent = function(eventName, callback) {
        $scope.$on('widget.' + eventName, callback);
    };
    
    // Initialize when widget loads
    c.initialize();
}

The server code implements a Widget Library Manager that maintains a registry of reusable widgets with dependency tracking and configuration management. The client code provides a base widget pattern with standardized initialization, error handling, and inter-widget communication. Key aspects include the widget registry system for tracking dependencies, portal-specific configuration overrides, and the event bus pattern for loose coupling between widgets.

Alternatives

Monolithic Widget Approach

Build large, feature-complete widgets that handle multiple responsibilities within a single component. Faster initial development but becomes difficult to maintain and customize as requirements grow.

Page-Level Customization Pattern

Customize portals at the page and theme level rather than widget level, using CSS overrides and page-specific JavaScript. Simpler architecture but limited reusability and harder to maintain consistent functionality across pages.

External Framework Integration

Use external frameworks like Angular or React components embedded within ServiceNow widgets for complex UI requirements. Provides powerful UI capabilities but increases complexity and requires additional skillsets to maintain.

Test Your Knowledge

Quick 3-question quiz — see how your ServiceNow skills stack up.

Question 1 of 3Performance

A list view on a table with millions of records is slow. Best fix?

Select an answer to continue