Mastering ServiceNow Service Portal Scripting: A Deep Dive

The ServiceNow Service Portal has revolutionized how organizations deliver IT and other enterprise services. It provides a modern, user-friendly interface for employees to access services, report issues, and find information. While the out-of-the-box capabilities are robust, the true power of the Service Portal lies in its extensibility through scripting. This chapter is your guide to unlocking that potential, transforming a standard portal into a dynamic, personalized, and highly functional hub.

We’ll embark on a journey through the core aspects of Service Portal scripting, from the fundamental building blocks like understanding URLs to the more advanced concepts of widget development and troubleshooting. Whether you’re looking to streamline user workflows, enhance the visual appeal, or build complex integrations, this comprehensive exploration will equip you with the knowledge and practical skills to excel.

1. Setting Up Appointments: Streamlining User Interactions

One of the most common and impactful use cases for Service Portal scripting is facilitating appointment scheduling. Imagine a scenario where users need to book time with IT support, HR professionals, or even book resources like meeting rooms. Manually managing these requests can be time-consuming and error-prone. Scripting allows us to build intuitive appointment booking interfaces directly within the Service Portal.

The User Experience: A Seamless Booking Process

The goal is to provide a frictionless experience for the end-user. This typically involves:

• Clear Availability Display: Showing available time slots based on the scheduler’s calendar or pre-defined availability.
• User Input: Capturing necessary details like the user’s name, contact information, reason for the appointment, and preferred time.
• Confirmation: Providing immediate feedback to the user that their request has been received and outlining the next steps.
• Calendar Integration (Advanced): Automatically creating calendar events for both the user and the service provider.

Under the Hood: How it Works

To implement appointment scheduling, you’ll typically use a combination of:

• Service Portal Widgets: To display the booking form and available slots.
• Client-Side Scripting (AngularJS): To handle user input, perform real-time validation, and interact with the server.
• Server-Side Scripting (Script Includes/Business Rules): To query availability, create records (e.g., `u_appointment` table), and potentially interact with the GlideDateTime API for complex scheduling logic.

Practical Example: A Basic Appointment Request Widget

Let’s conceptualize a simple widget. The client script might:

1. Fetch available dates and times from the server (e.g., from a custom table `u_available_slots`).
2. Display these slots in a user-friendly format (e.g., a calendar view or a list of time slots).
3. When a user selects a slot and submits the form, send the selected details to the server.

The server script (likely within a `spUtil.get` or `spUtil.save` in the widget’s server script, or a dedicated Script Include) would then:

1. Validate the selected slot is still available.
2. Create a new record in a custom appointment table, linking it to the user and the selected time.
3. Potentially trigger notifications to the user and the designated staff member.

This might involve JavaScript code that looks something like this in the client controller:

function($scope, $http, spUtil) {
    var c = this;
    c.data.appointment = {};
    c.data.availableSlots = [];

    // Fetch available slots on page load
    $http.get('/api/now/table/u_available_slots?sysparm_query=active=true&sysparm_limit=10')
        .then(function(response) {
            c.data.availableSlots = response.data.result;
        });

    c.submitAppointment = function() {
        spUtil.save(c.data).then(function(response) {
            // Handle success or error
            spUtil.getControlMessage(response.data.messages);
        });
    };
}
    

And on the server script:

(function() {
    /* populate the 'data' object */
    data.message = 'Appointment requested!';

    if (input && input.appointment) {
        var app = new GlideRecord('u_appointment');
        app.initialize();
        app.user = gs.getUserID();
        app.appointment_time = new GlideDateTime(input.appointment.selectedTime); // Assuming input.appointment.selectedTime is a string
        app.reason = input.appointment.reason;
        var sysId = app.insert();

        if (sysId) {
            gs.info('New appointment created: ' + sysId);
            // Potentially send notifications here
        } else {
            gs.error('Failed to create appointment.');
            data.message = 'Error submitting appointment. Please try again.';
        }
    }
})();
    

2. Understanding URLs in the Service Portal

URLs are the backbone of web navigation, and in the ServiceNow Service Portal, they play a crucial role in how users access pages, widgets, and specific data. Understanding how URLs are constructed and how to manipulate them is fundamental for effective development and troubleshooting.

The Anatomy of a Service Portal URL

A typical Service Portal URL looks like this:

https://yourinstance.service-now.com/sp?id=your_page_id&sys_id=your_record_sys_id&optional_parameter=value

• /sp?: This is the standard entry point for the Service Portal.
• id=your_page_id: This parameter is critical. It tells the Service Portal which page record to load. Pages are the containers for widgets.
• sys_id=your_record_sys_id: Often, you’ll want to display details about a specific record (e.g., a specific incident, catalog item, or knowledge article). This parameter passes the unique identifier of that record.
• &optional_parameter=value: These are custom parameters you can define and pass to your widgets or pages. They can be used to control widget behavior, filter data, or pass context.

Dynamic Navigation and Deep Linking

You can leverage URLs to create dynamic navigation. For instance:

• Linking to a Catalog Item: You might link directly to a catalog item’s page with its `sys_id`: /sp?id=sc_cat_item&sys_id=abcdef1234567890
• Linking to a Form: To display a form for a specific record: /sp?id=form&table=incident&sys_id=1234567890abcdef
• Passing Custom Parameters: If you have a widget that displays a list of tasks assigned to a user, you could link to it with the user’s `sys_id`: /sp?id=my_tasks&user_id=00000000000000000000000000000000

Client-Side Manipulation of URLs

In your widget’s client controller (AngularJS), you can access and manipulate URL parameters using the $location service:

function($scope, $location) {
    var c = this;
    var searchParams = $location.search();
    c.pageId = $location.search().id;
    c.recordSysId = $location.search().sys_id;

    if (c.recordSysId) {
        // Fetch data based on sys_id
    }

    // Programmatically navigate
    c.goToPage = function(pageId, params) {
        var url = '/sp?id=' + pageId;
        if (params) {
            for (var key in params) {
                url += '&' + key + '=' + params[key];
            }
        }
        $location.url(url);
    };
}
    

Server-Side URL Generation

On the server side, you can construct URLs using the GlideURI API, which is particularly useful when generating links in notifications or within server scripts that need to create a navigable link.

var uri = new GlideURI('/sp');
uri.addQueryParameter('id', 'ticket');
uri.addQueryParameter('table', 'incident');
uri.addQueryParameter('sys_id', current.sys_id);
gs.info('Link to ticket: ' + uri.toString());
    

3. Creating the Meeting Widget: A Practical Application

Building on the concepts of appointment setting and URL understanding, let’s delve into creating a specific widget. A “Meeting Widget” could serve various purposes, from displaying upcoming meetings to allowing users to schedule new ones. We’ll focus on a widget that displays a user’s upcoming meetings from their calendar or a custom “meetings” table.

Widget Structure: HTML, CSS, Client Script, Server Script

Every Service Portal widget consists of these core components:

• HTML Template: Defines the structure and layout of the widget’s content.
• CSS: Styles the HTML elements, controlling the widget’s appearance.
• Client Script: Handles user interactions, fetches data from the server, and manipulates the DOM.
• Server Script: Retrieves data from ServiceNow tables, performs server-side logic, and prepares data to be passed to the client.

Developing the “My Upcoming Meetings” Widget

Server Script (server.js)

This script will query for meetings scheduled for the currently logged-in user.

(function() {
    /* populate the 'data' object */
    data.user = gs.getUserDisplayName();
    data.upcomingMeetings = [];

    var meetingGR = new GlideRecord('u_meeting'); // Assuming a custom 'u_meeting' table
    meetingGR.addQuery('attendee', gs.getUserID());
    meetingGR.addQuery('start_time', '>=', gs.nowDateTime()); // Filter for meetings in the future
    meetingGR.orderBy('start_time');
    meetingGR.setLimit(5); // Limit to the next 5 meetings
    meetingGR.query();

    while (meetingGR.next()) {
        data.upcomingMeetings.push({
            sys_id: meetingGR.getUniqueValue(),
            subject: meetingGR.getValue('subject'),
            start_time: meetingGR.getDisplayValue('start_time'),
            duration: meetingGR.getValue('duration')
        });
    }
})();
    

Client Script (controller.js)

This script will use the data passed from the server to display the meetings. It might also include logic to click on a meeting and navigate to a details page.

function($scope, $location, spUtil) {
    var c = this;
    c.meetings = c.data.upcomingMeetings;
    c.userName = c.data.user;

    c.viewMeetingDetails = function(meetingSysId) {
        // Navigate to a dedicated meeting details page, passing the sys_id
        $location.url('/sp?id=meeting_details&sys_id=' + meetingSysId);
    };

    // Example: Add a message if no meetings are found
    if (c.meetings.length === 0) {
        spUtil.addInfoMessage("You have no upcoming meetings.");
    }
}
    

HTML Template (widget.html)

This displays the list of meetings.

    

        
Upcoming Meetings for {{::c.userName}}
    
    

        

            

                

                    

                        
Subject
                        
Start Time
                        
Duration
                    
                
                

                    

                        
{{::meeting.subject}}
                        
{{::meeting.start_time}}
                        
{{::meeting.duration}} minutes
                    
                
            
        
        

            
No upcoming meetings found.
        
    

    

CSS (style.css)

Basic styling for the panel and table.

.panel { margin-bottom: 20px; }
.panel-heading { background-color: #f7f7f7; border-bottom: 1px solid #ddd; padding: 10px 15px; }
.panel-title { margin: 0; font-size: 1.1em; }
.panel-body { padding: 15px; }
.table th { background-color: #e9e9e9; }
    

4. Aesthetic Changes: Elevating the User Interface

A beautiful and intuitive Service Portal isn’t just about functionality; it’s also about presentation. Aesthetic changes can significantly improve user adoption and satisfaction. Scripting, combined with CSS, allows for extensive customization of the portal’s look and feel.

Leveraging CSS for Visual Enhancements

You can add custom CSS to:

• Widget Styling: As demonstrated in the meeting widget, you can style individual widgets to match your brand guidelines.
• Global Styles: Inject CSS into the portal’s global stylesheet to affect multiple elements across different pages.
• Branding: Implement company logos, color schemes, and typography.
• Layout Adjustments: Modify column widths, spacing, and responsiveness.

Adding Custom CSS

There are several ways to apply custom CSS:

1. Widget-Specific CSS: Each widget has its own CSS file (style.css). This is ideal for styling elements only within that widget to avoid unintended side effects.
2. Theme CSS: You can modify or extend the CSS files associated with your chosen Service Portal theme.
3. Custom CSS Include: Create a separate widget (often not visible to users) whose sole purpose is to include custom CSS or JavaScript. You can then embed this widget on pages where you want its styles to apply.

Client-Side Scripting for Dynamic Styling

Sometimes, styling needs to be dynamic based on user actions or data. Client-side JavaScript can achieve this:

• Toggling Classes: Add or remove CSS classes from elements based on certain conditions. For example, highlighting an active navigation item.
• Inline Styles: Directly manipulate the `style` attribute of HTML elements, though this is generally less maintainable than using CSS classes.

// In your client controller
c.highlightSection = function(sectionId) {
    // Remove highlight from previously selected
    angular.element('.highlighted-section').removeClass('highlighted-section');
    // Add highlight to the current section
    angular.element('#' + sectionId).addClass('highlighted-section');
};
    

And in your CSS:

.highlighted-section {
    background-color: #e0f7fa; /* Light cyan */
    border-left: 4px solid #00bcd4;
    padding-left: 10px;
}
    

Using Font Awesome or Custom Fonts

Enhance icons and typography by integrating libraries like Font Awesome or by linking to custom font files through your theme’s CSS.

5. Option Schema: Configuring Your Widgets

The Option Schema is a powerful feature that allows you to make your widgets configurable from the Service Portal Designer. Instead of hardcoding values or requiring developers to edit the widget code for simple changes, you can expose options that end-users or administrators can set through a user-friendly interface.

What is the Option Schema?

The Option Schema is defined in the “Widget Options Schema” related list of a widget record. It’s essentially a JSON structure that defines the available configuration fields and their types (text, integer, boolean, choice, etc.).

Benefits of Using Option Schema

• Flexibility: Allows non-developers to configure widget behavior.
• Reusability: A single widget can be adapted for multiple use cases simply by changing its options.
• Maintainability: Reduces the need to modify widget code for simple adjustments.
• Consistency: Ensures that configurations are applied in a standardized way.

Common Option Types

• Text: For general string inputs.
• Integer: For numerical inputs.
• Boolean: For true/false toggles.
• URL: For entering web addresses.
• Choice: A dropdown list of predefined options.
• Reference: Allows selection of records from a specific ServiceNow table.
• Color Picker: For selecting colors.

Example: Configuring a “Welcome Message” Widget

Let’s say you have a widget that displays a welcome message. You’d want to make the message text, and perhaps its color, configurable.

Widget Options Schema (JSON)

[
    {
        "name": "welcome_message",
        "label": "Welcome Message Text",
        "type": "string",
        "default": "Welcome to our Service Portal!"
    },
    {
        "name": "message_color",
        "label": "Message Text Color",
        "type": "colorpicker",
        "default": "#333333"
    },
    {
        "name": "show_user_name",
        "label": "Show User's Name",
        "type": "boolean",
        "default": true
    }
]
    

Server Script (Accessing Options)

In your widget’s server script, you access these options via options.option_name.

(function() {
    data.welcomeMessage = options.welcome_message || "Welcome!"; // Use option or default
    data.messageColor = options.message_color || "#333333";
    data.showUserName = options.show_user_name !== undefined ? options.show_user_name : true;

    if (data.showUserName) {
        data.dynamicGreeting = "Hello, " + gs.getUserDisplayName() + "! ";
    } else {
        data.dynamicGreeting = "";
    }
})();
    

HTML Template (Using Options)

    
{{::c.dynamicGreeting}}{{::c.welcomeMessage}}

    

Using Options in the Client Script

You can also access options in the client script, though it’s more common to pass derived data from the server.

function($scope) {
    var c = this;
    // Accessing an option directly (less common for dynamic logic)
    // c.showUserName = c.options.show_user_name;
}
    

6. Troubleshooting Widgets: Solving Common Issues

Even the best-written scripts can encounter problems. Effective troubleshooting is a critical skill for any Service Portal developer. Here’s a breakdown of common issues and how to approach them.

Common Widget Issues and Solutions

Issue 1: Widget Not Loading or Displaying Errors

• Check Browser Console: This is your first stop. Press F12 (or right-click -> Inspect -> Console) in your browser. Look for JavaScript errors (red messages).
• Check Widget Server Script: Errors in the server script can prevent data from being sent to the client. Use gs.info() or gs.error() to log values and trace execution. View these logs in the System Logs table (syslog) filtering by source “Service Portal”.
• Check Widget Client Script: Similar to the server script, JavaScript errors here will appear in the browser console.
• Check Widget HTML Template: Syntax errors in HTML or incorrect AngularJS bindings can cause rendering issues.
• Check Page Configuration: Ensure the widget is correctly added to the page in Service Portal Designer.
• Check Widget Instance Options: If your widget relies on options, verify they are set correctly in the widget instance’s “Edit Options” modal.

Issue 2: Data Not Displaying Correctly

• Verify Server-Side Data Retrieval: On the server script, log the results of your GlideRecord queries. Are you fetching the expected records and fields?
• Check Data Structure: Ensure the data being pushed to the client (`data` object) has the structure your client script expects.
• Inspect AngularJS Bindings: In your HTML, ensure you’re using the correct variable names from the `c` (controller) object (e.g., `{{::c.data.myVariable}}`).
• Use ng-repeat Correctly: If displaying lists, ensure your data is an array and your `ng-repeat` syntax is correct.
• Check Data Types: Mismatched data types (e.g., trying to display a GlideDateTime object directly without formatting) can cause unexpected results.

Issue 3: Performance Problems (Slow Loading)

• Optimize Server-Side Queries: Ensure your GlideRecord queries are efficient. Use `addQuery` and `addEncodedQuery` effectively. Avoid querying all fields if you only need a few.
• Reduce Data Sent to Client: Only pass the necessary data to the client. Large datasets can significantly slow down page load times.
• Client-Side Performance: Complex AngularJS loops or DOM manipulations on the client can also impact performance. Profile your client-side code.
• Caching: ServiceNow and browsers cache data. Sometimes, a hard refresh (Ctrl+Shift+R or Cmd+Shift+R) can resolve perceived caching issues.

Issue 4: Widget Instance Options Not Appearing or Working

• Validate Option Schema JSON: Ensure the JSON in your “Widget Options Schema” is perfectly formatted. Even a misplaced comma can break it. Use an online JSON validator.
• Correct Option Names: Double-check that the `name` attribute in your schema matches how you’re accessing the option in your server script (e.g., `options.my_option_name`).
• Widget Instance vs. Widget Definition: Ensure you are editing the options for a specific widget *instance* on a page, not the widget *definition* itself.

Debugging Techniques

• Browser Developer Tools: The most powerful tool. Use the Console for errors, the Network tab to see HTTP requests and responses, and the Elements tab to inspect HTML.
• `gs.info()` and `gs.log()`: Essential for server-side debugging. Log variable values at different stages of your script.
• `console.log()`: The equivalent for client-side debugging in the browser console.
• Service Portal Designer: Visually inspect the widgets on a page and their configurations.
• Widget Tree: In Service Portal Designer, you can see the hierarchy of widgets on a page, which helps understand how they interact.

Interview Relevance

For those looking to break into or advance their careers in ServiceNow development, understanding Service Portal scripting is a major advantage. Interviewers will often probe your knowledge in these areas:

Summary

Service Portal scripting is a cornerstone of modern ServiceNow customization. By mastering the art of creating widgets, understanding URL parameters, leveraging the option schema for configurability, and adeptly troubleshooting issues, you can transform the Service Portal into a powerful, user-centric platform. This chapter has provided a foundational understanding and practical examples to empower your development journey. As you continue to build and innovate, remember that clear, efficient code, coupled with a user-first approach, will always lead to successful Service Portal implementations.