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.
- In the Admin Center, go to Apps and Portals > Self Service Portal and select the instance.
- Open Homepage Template. Use Export to keep a copy before editing.
- Edit the JSON template, or use Import to load it from a file.
- 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.
searchcarriesvisibleandtitle. Whenvisibleisfalse, 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
typeand atitle, and some widgets also carry adescription, anitemCount, anorderBy, or ananonymousAccesskey; see The supplied template. itemCountis the number of items a list widget asks the server for. When a list widget has noitemCount, or has anitemCountof 0, the server returns its own number of items: 3 forAnnouncementsand 5 for the other list widgets.- A list widget also sends its
orderBy,filter, andcategoryNamevalues 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
anonymousAccesstrue. - The instance grants anonymous access to announcements, for the
Announcementswidget, or to Knowledge Base articles, for theKBArticleswidget. 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
SearchorCustomportlet is shown while at least one module is enabled. See Modules. - The
urlof aCustomportlet 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.