Administration Guide

Customizing the SSP homepage layout

Introduced in 2021.1

Updated in 2024.2

The Self Service Portal (SSP) homepage layout is defined using a JSON-based template that allows full control over the placement, configuration, and appearance of widgets. This template is managed in the Admin Center. Read this page to see how you can customize the homepage's layout for the chosen template.

Accessing and managing the homepage template

To view or modify the homepage template:

  1. Navigate to Admin Center > Apps and Portals > SSP Homepage Template.

  2. Use the built-in JSON editor to customize widget properties, layout, and behavior. For example, you can adjust the itemCount for specific widgets or change the visibility of the search box by setting the visible parameter to true or false.

  3. Save your custom template as a JSON file using the Export option. This allows you to back up your settings or reuse them for other instances.

  4. To apply an existing configuration, use the Import option to upload the JSON file, making it easy to replicate layouts across multiple portals.

You can revert the homepage layout to the default settings at any time by clicking Restore Default. For additional information, see Help: Customizing the homepage template.

Homepage widgets

Widgets are modular components that provide various functionalities on the SSP homepage. You can configure the layout by organizing widgets into columns and setting their properties within the JSON file.

Key widget properties:

  • type: Defines the widget type, such as Search, TicketSubmit, or KBArticles.

  • title: Specifies the display title for the widget.

  • itemCount: Controls the number of items displayed in list-based widgets (e.g., Announcements, KBArticles).

  • anonymousAccess: Determines visibility for unauthenticated users (applicable to Announcements and KBArticles).

  • orderBy: Specifies sorting for list-based widgets.

Embedding custom JavaScript

Custom JavaScript files can be added to the Self Service Portal to enhance functionality. These scripts are stored in the following location: [PhysicalPathToSSP]\www\js\custom\.

To manage custom scripts:

  1. Place your JavaScript files in the specified directory [PhysicalPathToSSP]\www\js\custom\.

  2. Test and review scripts to ensure compatibility.

Versions from 2021.1 through 2024.1

On-prem only

The Self Service Portal comes with a set of colorful templates that controls the color theme of the whole portal and define the homepage layout. Read this page to see how you can customize the homepage's layout for the chosen template.

FOR CLOUD CUSTOMERS: Please note that homepage customization is only available for on-premises deployments. Contact our Support Team for assistance with this step.

Each template has its own folder containing styles and configuration settings, with each file controlling a specific aspect of the template. The homepage layout is controlled by the template.html file.

The template.htm file defines various widgets (tagged as portlets), that is, small application components that provide specific functionality. The available widgets are listed below;

  • Search: This widget renders a Search For Solution area at the top of the page.

  • TicketSubmit: This widget renders a Submit a Ticket button which opens a new ticket form.

  • AskQuestion: This widget renders an Ask a Question button which navigates to the Knowledge Base.

  • LatestUpdates: This widget renders a list of the latest updates from the Tickets, Equipment Requests, and Approvals which are available for the current user.

  • MyTickets: This widget renders a list of recent tickets from the Tickets, Equipment Requests, and Approvals which was submitted by the current user.

  • MyApproval: This widget renders a list of approval requests which are available for the current user.

  • Announcements: This widget renders a list of Announcements.

  • KBArticles: This widget renders a list of KB articles from the Knowledge Base.

  • Custom: This widget renders a custom widget which allows user to add custom HTML via iframe (url attribute).

Widget configuration

Each widget configuration is contained in a separate element. This string represents one such element, specifying the configuration for the Search widget:

<portlet type="Search" title="FRAME_TITLE.SEARCH" />

Customizing widgets

Each widget's behavior and appearance are controlled by a set of parameters that you can customize as necessary.

IMPORTANT: Before making any changes to a homepage template, create a copy of the template folder with its contents and use only that copy for customization. We recommend basing your customizations on the "Ocean Depth (3 columns) - Default" template.

Here is a comprehensive list of all potential parameters. Note that not all parameters are applicable to every widget.

  • type:The type of widget. For example, "Search", "TicketSubmit", "LatestUpdates", etc. The comprehensive list of widgets is provided above.

  • title: The title or label of the widget, which is displayed to users.

  • cssClass: Optional property that allows you to specify a custom CSS class for the widget container. If a class is not provided, the widget will inherit a default CSS class based on its type (WidgetCssClassByType).

  • anonymousAccess: When set to true, the widget will be displayed for anonymous users; otherwise, it will only appear for authenticated users. This property is used only for the "Announcements" and "KBArticles" widgets.

  • itemCount: For list-based widgets such as "Announcements," "KBArticles," "MyTickets," "MyApproval," and "LatestUpdates," this property determines the number of items shown in the list. By default, it's set to 3 for the "Announcements" widget and 5 for others. If the value is left blank or less than 1, the default value will be used.

  • orderBy, filter, categoryName: These parameters are related to the sorting, filtering, and categorization of items in the "KBArticles" widget. Specifically, orderBy determines the column used for sorting, filter enables additional SQL filtering for the result set, and categoryName filters items based on category name.

  • url: For the "Custom" widget, this parameter specifies the URL used to load custom HTML content via an iframe.

Removing widgets

To remove a widget from the homepage, simply delete the entire element representing that widget from the template.htm file.

Version 8.7 and earlier

Deprecated in 2021

NOTE: This section describes deprecated functionality that only works with Alloy Navigator Express 8.7 and earlier.

When SSP customers sign in to the Self Service Portal, they land on the Home page. The Home page consists of portlets. Portlets are rectangular display components of the portal, that are used to organize important information and provide access to various objects and actions on the Home page.

The following portlets are on the Home page by default:

  • Tools: Provides access to all Self Service Portal objects and actions

  • Latest Updates: Displays most recently updated Tickets and Equipment Reservations.

  • Announcements: Displays active Announcements created for SSP users

  • Popular Articles: Displays most often viewed articles from the Knowledge Base

You can hide or add portlets or configure what information they display. For example, you can create a portlet to display top 5 most recent articles from a particular Knowledge Base category. The number of articles and the order in which they are displayed can be customized.

In addition to the default portlets, you can create a custom portlet displaying content from a web page or from a local HTML file.

By default, portlets are arranged in two columns. You can add more columns or reorder portlets within a column.

To make any customizations, you need to edit the WelcomePage.config file and configure its parameters as explained further. This file is located in the config folder under the folder where your Alloy Navigator Express Self Service Portal files are located: [PhysicalPathToSSP]\config\WelcomePage.config.

The [PhysicalPathToSSP] is the placeholder for the physical path to the installation folder of your Self Service Portal.

NOTE: For instruction on viewing the physical path of Self Service Portal installation folder, see Physical Path to Self Service Portal Files.