Administration Guide

Portal Home Page

On this page

The Self Service Portal home page is a dashboard of widgets arranged in columns. Each portal instance has its own JSON home page template and its own New Experience setting. For an instance that uses the New Experience, you choose what the home page shows on the instance's Homepage Template tab in the Admin Center; otherwise the portal takes it from an HTML template file on the web server. For the instance's other settings, see Self Service Portal Settings.

How the home page is built

The instance's New Experience setting decides where the portal takes the home page from:

  • With the New Experience on, the portal builds the home page from the instance's JSON template, which you edit on the Homepage Template tab. The portal checks the template against its schema. If the template is valid JSON but does not pass the check, the portal uses a built-in default layout instead.
  • With the New Experience off, the portal builds the home page from the HTML template file on the portal's web server. See The HTML template on the web server.

On the home page of an instance that uses the New Experience, the bar at the top of the page is drawn partly transparent.

In the Admin Center

Edit the home page template

IMPORTANT: Template text that is not valid JSON is not replaced by the default layout. The portal's home page then fails to load, whether or not the instance uses the New Experience.

  1. In the Admin Center, go to Apps and Portals > Self Service Portal and select the instance.
  2. Open Homepage Template. Use Export to keep a copy before editing.
  3. Edit the JSON template, or use Import to load it from a file.
  4. Save your changes. The notice on the tab explains when they take effect.

The Homepage Template tab of a portal instance edits "a JSON file that controls the layout, placement, and configuration of homepage widgets". The tab has the same toolbar as the View Configuration and Lookup Configuration tabs:

  • Export downloads the current template as dashboard-template.json.
  • Import replaces the template with the text of a file you upload.
  • Restore Default writes back the template of the default settings. It is disabled while the template already equals it or when no default exists.

The editor is shown while the instance uses the New Experience. On an upgraded instance, the New Experience check box appears beneath the description, with the text "If you choose not to use the New Experience, the classic HTML template with all widgets in three columns will be used." Clearing the check box hides the editor again without discarding the template. An instance that is not upgraded and uses the New Experience shows the editor and no check box.

The Admin Center saves the template exactly as you type it. It does not check that the text is valid JSON. If you clear the template and save, the template of the default settings is copied in.

The tab also shows the notice "Changes will take effect in a few minutes after saving." with "Users can perform a hard refresh in their browser (e.g., Ctrl+F5) to see the changes immediately."

The JSON template

The template is a JSON object with one search item and a list of columns, each holding a list of widgets.

  • search carries visible and title. When visible is false, the home page keeps the header background but shows neither the search heading nor the search box.
  • In the supplied template, each widget carries a type and a title, and some widgets also carry a description, an itemCount, an orderBy, or an anonymousAccess key; see The supplied template.
  • itemCount is the number of items a list widget asks the server for. When a list widget has no itemCount, or has an itemCount of 0, the server returns its own number of items: 3 for Announcements and 5 for the other list widgets.
  • A list widget also sends its orderBy, filter, and categoryName values to the server with its request for items, each only when it is set.

The texts in title and description are message names. For the search banner, the banners, and the list widgets, the portal shows the message named HOME. followed by the text: for FRAME_TITLE.TICKET_SUBMIT, it shows the message HOME.FRAME_TITLE.TICKET_SUBMIT. A text for which no such message exists is shown as typed.

The supplied template

This section describes what a new 2026.1 database created with the Default Workflow contains; see Default Workflow Configuration. In that database, the default settings hold the template below, and their New Experience setting is turned on. An upgraded database need not have this template, and an administrator may have changed it.

The template's search item carries "visible": true and "title": "FRAME_TITLE.SEARCH", and its three columns hold these widgets:

Column type title / description Other keys
1 TicketSubmit FRAME_TITLE.TICKET_SUBMIT / FRAME_TITLE.TICKET_SUBMIT.DESC -
1 LatestUpdates FRAME_TITLE.LATEST_UPDATES itemCount 5
1 ServiceCatalog FRAME_TITLE.POPULAR_SERVICE_CATALOG itemCount 5, orderBy Request_Count DESC, Name ASC
2 ServiceRequest FRAME_TITLE.SERVICE_REQUEST / FRAME_TITLE.SERVICE_REQUEST.DESC -
2 MyTickets FRAME_TITLE.MY_TICKETS itemCount 3
2 MyApproval FRAME_TITLE.MY_APPROVAL itemCount 3
3 AskQuestion FRAME_TITLE.ASK_QUESTION / FRAME_TITLE.ASK_QUESTION.DESC -
3 Announcements FRAME_TITLE.ANNOUNCEMENTS anonymousAccess true
3 KBArticles FRAME_TITLE.POPULAR_ARTICLES anonymousAccess true, itemCount 5, orderBy Views DESC, Created_Date DESC

Home page widgets

The portal has eleven widget types:

Kind Types
Search banner Search
Banners TicketSubmit, ServiceRequest, AskQuestion
Lists LatestUpdates, MyTickets, MyApproval, ServiceCatalog, Announcements, KBArticles
Custom Custom

For how customers use the home page, see Navigate the Portal.

Search banner

The search banner shows a heading and a search box over the header background image. When a customer presses Enter or clicks the search icon, the portal opens the search results for the text in the box. An empty search box does nothing.

Banners

When a visitor who is not signed in clicks the TicketSubmit banner, the portal opens the sign-in page. When a signed-in customer clicks it, with the Tickets or Incidents module enabled, the portal opens the form for a new ticket. If exactly one ticket action is available, the form uses that action. If more than one is available, the form itself resolves which action to use.

Lists

Each list widget shows its items as follows:

  • MyTickets: each ticket shows its summary, ID, and creation date, with an icon that tells incidents from service requests.
  • MyApproval: each approval request shows the type of the item to approve and its stage, its ID, the requester, and the due date when one is set.
  • KBArticles: each article shows its view count and last-modified date.
  • ServiceCatalog: clicking an item opens it with its details shown.
  • Announcements: a high-priority announcement has a colored left border.
  • LatestUpdates: clicking an item opens the updated item's page. A service catalog item opens with its details shown.

While a list widget loads its items, it shows a placeholder. It then shows one of these instead of the list:

  • A message that sign-in is required, when the visitor is not signed in and the widget is not open to such visitors (see Widgets for visitors who are not signed in), or when the server refuses the request because the visitor is not signed in.
  • A message that the widget type is not supported, when the server does not find the widget's data.
  • A message that no items exist, when the list is empty.
  • An error message, when the request fails for another reason.

Widgets for visitors who are not signed in

Only the Announcements and KBArticles list widgets can be shown to a visitor who is not signed in. Such a visitor sees one of them only when all of the following hold:

  • The widget itself allows anonymous access. In the supplied template, both widgets carry anonymousAccess true.
  • The instance grants anonymous access to announcements, for the Announcements widget, or to Knowledge Base articles, for the KBArticles widget. See Anonymous Access.
  • The module is enabled.

The KBArticles widget shows its link to more articles to such a visitor only when the instance also grants anonymous access to the whole Knowledge Base. For a signed-in customer, the link is shown whenever the Knowledge Base module is enabled.

Every other list widget, and an Announcements or KBArticles widget that these conditions do not open, shows a visitor who is not signed in the message that sign-in is required.

The HTML template on the web server

When the New Experience is off, the portal serves its home page from the template.html file in the [PhysicalPathToSSP]\remix\client\ folder on the portal's web server. The file holds <portlet> elements, and the portal places a widget for each of them:

  • A portlet whose type is not one of the eleven widget types gets no widget.
  • A portlet whose module is not enabled is left out. A Search or Custom portlet is shown while at least one module is enabled. See Modules.
  • The url of a Custom portlet must end in .html.

As in the JSON template, a list widget of the HTML template that has no item count, or an item count of 0, gets the server's own number of items. The HTML template passes no category name to a list widget.

The portal reads a changed file the next time its server process starts. Files on the portal's web server are edited by the administrator of an on-premises installation. For the other files in this folder and for restarting the portal, see Advanced Portal Customization.