Self Service Portal Settings
On this page
Each Self Service Portal instance has its own settings. They include these groups:
| Group | What it covers |
|---|---|
| Identity | The instance's name, title, subtitle, and address |
| Branding | Logo, header image, color theme, home page template, and the New Experience setting |
| Modules | Which portal modules the instance offers |
| Access | Password sign-in, SSO providers, and anonymous access |
| Language | The languages the instance offers and its default language |
| Data views | The data views and lookup lists customers see |
| Proxy | The host header, for an instance deployed behind a proxy or load balancer |
| AI Assistant | The portal's AI Assistant |
You administer these settings in the Admin Center. The Settings App carries a few further portal pages: self-registration, portal workflow, and the portal's e-mail templates. For what the portal offers its customers, see About the Self Service Portal. For how the two administrative applications divide the work, see Admin Center and Settings App.
In the Admin Center
The portal's instance settings are under Apps and Portals > Self Service Portal, with one set of pages per instance. The Self Service Portal entry requires the permission to configure the Self Service Portal. It lists the configured instances; when only one instance exists, the menu goes straight to that instance's tabs. When no instance exists yet, the page shows a notice that links to the installation instructions; see Install the Self Service Portal.
An instance's tabs include General and Application Gateway, described below, and the tabs that the following sections name. The AI Assistant tab needs a permission of its own. The Anonymous Access tab is not shown for an instance that uses Windows authentication.
The Homepage Template tab is described in Portal Home Page. For the Self-Registration tab, see Self-Registration. The instance's New Experience setting decides how the portal draws its home page: from the tab's JSON template when the setting is on, and from the classic HTML template otherwise.
The Title, Logo, Header, Color Theme, Authentication, Anonymous Access, Application Gateway, View Configuration, and Lookup Configuration tabs show 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." On the Title, Logo, Header, and Color Theme tabs, the notice appears once you change a field.
The portal's e-mail templates are edited on the SSP E-mail Templates page among the Admin Center's notification pages; see Notifications Overview.
A settings change reaches the running portal without a restart. This includes the AI Assistant settings. The portal checks for changed settings every few minutes.
Instances
You do not create portal instances in the Admin Center. An instance registers itself the first time it is used, and then appears in the list. A new instance is named after the address it was first opened with, and starts with a copy of the default settings' view configuration.
The Admin Center marks an instance as old when it has not been used for more than seven days. The General tab of an old instance, and only of an old one, shows Delete, beside a warning that begins "This instance has been inactive for over 7 days and appears to no longer exist." To delete the instance, click Delete and confirm Delete instance?; the Admin Center then leaves the instance's pages.
Deleting an instance marks it as deleted and keeps its settings. The default instance is not offered for deletion. If a deleted instance is still in use, it restores itself the next time it reads its settings.
General
The General tab holds the instance's name and address:
- Name is for your reference only and is not visible to users.
- URL is the instance's address. Review the auto-generated URL, and enter the correct address manually if needed. A button beside the field opens the address in a new browser tab; it is disabled while the field is empty. Saving does not check that the address is reachable.
The system macro that is used to generate direct links in workflow notifications holds the portal's address too. When the URL and the macro differ, not counting trailing slashes, the tab also shows the read-only System macro with the alert "System macro differs from URL" and two buttons:
- Update system macro with instance URL sets both fields to the stored URL.
- Update instance URL with system macro sets both fields to the stored macro value.
Saving the instance's settings also saves the system macro, which is kept in the system-wide settings rather than with the instance.
Application Gateway
The Application Gateway tab has one field, Host Header. Its description begins "If this application is deployed behind a proxy or load balancer, please provide the host header."
Default settings
The default settings are the template every instance falls back to. They are not listed as an instance.
- The Restore button of an image field and the Restore Default button of a document editor return the value of the default settings.
- A data view, lookup, or home page template document that you save empty is filled in again from the default settings.
- When a new instance is added, an empty title, subtitle, or module list is filled in from the default settings.
- For an instance that has no view configuration or lookup configuration of its own, the portal uses the document of the default settings.
A new database created with the Default Workflow contains the default settings; see Default Workflow Configuration. The values of the default settings that this page gives, in the Title, Data views, and Lookups sections, are those of the supplied configuration. An upgraded database need not have these values, and an administrator may have changed them.
Title
The Title tab has two fields:
- Title is shown at the top of each page next to the logo.
- Subtitle is shown just below the title in a smaller font.
The tab recommends keeping the title under 50 characters and the subtitle under 80 characters. Longer text is accepted. In the supplied configuration, the title of the default settings is set to "Self Service Portal" and the subtitle to "Your business motto".
In the portal, the logo, title, and subtitle appear in the bar at the top of every page except the sign-in pages, and the logo links to the home page.
Logo and header image
The Logo tab and the Header tab each hold one image field. The Logo tab reads "Specify the logo image that will appear at the top of Web pages. You can use the default Alloy Software logo image or load a custom image." The Header tab describes the header image as the image "at the top of the homepage, behind the Find a Solution search box".
Both fields accept PNG, JPG, BMP, and SVG images. A file of another type is refused.
- The logo area is 50 pixels high. Larger images are scaled down, keeping the aspect ratio.
- The header image area is 1600 pixels wide and 330 pixels high. Larger or smaller images are resized to fill the area and centered, keeping the aspect ratio.
To set an image, do one of the following:
- Drop an image onto the box that reads "Drop an image here, or click to select a file".
- Click the box, or click Upload, and select a file.
To return to the image of the default settings, click Restore. The button is disabled while the field already holds that image.
The portal's sign-in page has no bar at the top; it shows the logo at the top of the sign-in card.
Color Theme
The Color Theme tab offers eight named colors: Ocean Depth - Default, which is the default, Alien Eyes, Bordeaux, Dark Side, Fresh Iris, Jungle, Lotus, and Soho Lights.
When you choose a color, the tab recolors a live preview: a header strip in the theme's color with the instance's logo, the instance's header image beneath it, and a sketch of the portal's page body over both.
In the portal, the theme colors two things:
- The bar at the top of every page except the sign-in pages. On the home page of an instance that uses the New Experience, the bar is drawn slightly transparent.
- The strip behind the logo at the top of the sign-in card. The theme does not change the sign-in page's own background.
An instance without a stored theme is shown in Ocean Depth - Default. Whether the portal is shown in light or dark mode depends on each visitor's own color mode, not on the theme.
Modules
The Modules tab lists seven check boxes, one per portal module: Service Catalog, Incidents, Equipment Lending Library, Approvals, Knowledge Base, Announcements, and Assets.
The instance offers a module only when it is checked here and your license allows it. The portal checks whether your license covers ITSM and whether it covers ITAM:
| License covers | Modules it allows |
|---|---|
| ITSM and ITAM | Every checked module |
| ITSM only | Service Catalog, Incidents, Knowledge Base, Approvals, and Announcements |
| ITAM only | Approvals, Announcements, Equipment Lending Library, and Assets |
When your license covers neither ITSM nor ITAM, the instance offers no modules.
In the portal, the navigation menu and the home page widgets show only the areas of the modules the instance offers. The search box in the bar at the top of the pages other than the home page is shown only while the instance offers at least one module.
Enabling a module and granting anonymous access to it are two separate settings. A visitor who is not signed in reaches an area only when both allow it; see Anonymous Access.
Authentication
The Authentication tab sets how customers sign in to the instance. For SSO providers and domains in general, see Authentication Methods.
Unless the instance uses Windows authentication, the tab shows:
- Under Password Authentication, the Allow password authentication check box.
- Under SSO/LDAP Authentication, the SSO Providers grid. It lists every SSO provider, sorted by name. Each row has a check box and a switch in the column headed Allow sign-in without SSP accounts. The switch is disabled until the row is checked. When no provider exists, the grid reads "No services configured." and offers Add SSO providers.
The Domains grid lists every domain with a switch. The switches are disabled unless the instance uses Windows authentication or allows password authentication. When no domain exists, the grid offers Add domains. Switching a domain on lets users of that domain sign in to the portal without a portal account; see Sign-in without a portal account.
For new domain users: Create Persons using this Action selects an Active Directory create action of the Person class. The field is required. The selected action is stored in the system-wide settings, not with the instance's own settings. For service actions, see Service Actions and Field Mappings.
For an instance that does not use Windows authentication, Save is disabled until Allow password authentication or at least one SSO provider is checked. Save keeps only the checked SSO providers and the domains whose switch is on. Saving this tab does not restart anything. Saving the instance's settings never changes whether the instance uses Windows authentication. Whether the portal uses Windows or standard authentication is chosen on the Authentication Method page of the Web Configuration tool, which offers Windows Authentication and Standard Authentication; see Install the Self Service Portal.
In the portal, the sign-in page of an instance that does not use Windows authentication shows:
- The password fields, when Allow password authentication is checked, with a link for a forgotten password.
- Each of the instance's SSO providers as its own sign-in button, below a divider when the password fields are shown. Microsoft, Okta, and ADFS providers have their own icons and a custom provider a generic icon; a provider of an unrecognized type has no icon.
- A link to self-registration, when self-registration is enabled; see Self-Registration.
For an instance that uses Windows authentication, the portal shows neither the password form nor the SSO providers. A visitor who is not signed in is sent to Windows sign-in, so the customer types nothing into the portal, and the portal shows no sign-out button. The portal's Windows sign-in answers only when Windows authentication is also enabled in IIS for the portal; see Authentication Methods.
Sign-in without a portal account
When Allow sign-in without SSP accounts is on for a provider, a user whose identity that provider asserts is not refused for lacking an account. The portal looks for a Person with the e-mail address the provider asserts, creates a Person from the asserted full name and e-mail address when none matches, and signs the user in as that Person. The same applies to directory sign-in: a directory listed as a provider of this kind lets a domain user in and imports the user as a Person on first use. A domain is listed this way when its switch is on in the Domains grid.
For domain sign-in, an existing account must be active. A domain user without a portal account can sign in only when the domain's switch is on. The portal uses the Person already imported for that directory user or creates one with the action selected in Create Persons using this Action. For sign-in behavior, see Authentication Methods. For portal accounts, see Accounts.
Anonymous Access
The Anonymous Access tab sets what a visitor who has not signed in may open. It has four check boxes:
| Check box | What it opens to a visitor who has not signed in |
|---|---|
| Homepage | The homepage. If you clear this check box, anonymous users are prompted to sign in when they try to open the homepage. |
| Announcements | Viewing announcements. |
| Knowledge Base Articles | Opening knowledge base articles by their URLs. |
| Knowledge Base | Browsing the knowledge base. |
Knowledge Base is available only while Knowledge Base Articles is checked. Clearing Knowledge Base Articles also clears Knowledge Base.
When Knowledge Base Articles is checked and Knowledge Base is not, a visitor who has not signed in can open an article from its link, but the portal does not show the knowledge base's category tree or article list.
Anonymous access to announcements or the knowledge base also requires the Announcements or Knowledge Base module to be enabled on the Modules tab. No anonymous-access setting opens tickets, approvals, the service catalog, the equipment library, or assets.
The portal's search results are open to a visitor who has not signed in only while Announcements or Knowledge Base Articles is checked.
For an instance that does not use Windows authentication, a visitor who has not signed in and opens a portal page that requires signing in is sent to the sign-in page rather than shown an error.
Languages
The Languages tab sets which languages the instance offers:
- Additional languages lists every language, sorted by display name, each with a check box. The default language is shown in a heavier font.
- Default language offers only the languages checked under Additional languages. The default language cannot be cleared under Additional languages.
The check boxes and the default language are saved only when you click Save. The tab's notice says that changes take effect in a few minutes after saving; it has no hard-refresh sentence.
The following commands act at once, without Save:
- Export in a language's row menu downloads the language as a
<language code>.jsonfile. - Delete in a language's row menu deletes the language after the confirmation "Are you sure you
want to delete the selected item?". Delete is not offered for the default language or for
en-US. - Import language takes one
.jsonfile and adds it as a language, under the name the file gives it. If the file carries a language that is already on the list, "Replace language?" asks before the existing translation is replaced; the language keeps its existing name. A file that is not valid JSON shows "The file content is invalid." and nothing is imported.
For each visitor, the portal picks the language in this order: the language saved in the visitor's browser cookie, when the instance has it enabled, then the first of the browser's preferred languages that the instance has enabled, then the default language.
The installation's display language is set in the Admin Center under General > Language & Region, in Display language; see Branding and Appearance. Once a display language is stored, the portal uses it as its default language instead of the one chosen on this tab. Saving Language & Region also sets the default language of every instance that is not deleted, and of the default settings, to the display language, and adds the display language to their languages.
View Configuration and Lookup Configuration
Two tabs edit XML documents:
- View Configuration: "This XML configuration defines all data views available to Self Service Portal customers and allows customization, such as adding or removing columns."
- Lookup Configuration: "This XML configuration determines how lookup lists appear on forms."
Each tab has the same toolbar:
- Export downloads the current document, as
view-configuration.xmlorlookup-configuration.xml. - Import replaces the document with the text of a file you upload.
- Restore Default writes back the document of the default settings. It is disabled while the document already equals it or when no default exists.
Before editing either document, click Export and keep the downloaded file as a backup. Make your changes and click Save. To restore your copy, click Import, select the saved file, and click Save.
Saving does not validate the document: a document with errors is saved as typed. A document you save empty is filled in again from the default settings. Restore Default returns the current default settings document, not your previous custom configuration.
Data views
The view elements identify the records each view displays:
| View element | Records |
|---|---|
TicketView, TicketManagerView, TicketCollaboratorView |
Tickets; manager and collaborator views use the access rules described below |
ServiceView, ServiceCollaboratorView |
Service Requests |
ReservationsView |
Equipment Reservations |
ApprovalsView |
Approval Requests |
LibraryView |
Library Items |
AssetsView |
Assets |
ArticlesView |
Knowledge Base articles |
ServiceCatalogView |
Service Catalog items |
Each view has a <Fields> list and can have a <Filter>, an SQL condition over the class's fields.
For grid views, a column is named by its field name
with underscores, such as Created_Date or Service_Catalog_Item. To add or remove a column,
add or remove its <Field Name="…" /> line.
For example, the supplied "Open Tickets" view is a TicketView with the columns Ticket,
Summary, Status, and Created_Date, in that order, and the filter not [Status] = 'Closed'.
Use the filters in ArticlesView and ServiceCatalogView to limit the Knowledge Base articles
and Service Catalog items shown across the portal instance, including popular articles and items.
These filters apply in addition to the existing visibility rules. The supplied Live Articles
and Active Items views have no filter; add a <Filter> to restrict their content. The portal
shows articles in a list with fixed fields and catalog items as cards, so the fields listed in
these two views do not change the fields shown in the list or on the cards.
When you upgrade the database, the default settings' view configuration is replaced with the supplied configuration. For each portal instance, the upgrade adds supplied view kinds that are missing from that instance's configuration. Back up any changes to the default settings before upgrading.
For customer record lists, a customer is offered every view of a class, with one exception: a manager view (TicketManagerView)
is listed only when the customer's access level is manager, group, organization, or organization
with subunits. Collaborator views are listed to everyone.
- A collaborator view shows the records the customer collaborates on.
- A manager view, and every service request view, also shows the records of the requesters that the customer's access level covers: people whose manager is the customer, members of a group the customer manages, or people in the customer's organization, with or without its subunits.
If a view names a field that the portal cannot resolve, for example a field that a customization or an upgrade removed, the whole view fails, not just that column.
Lookups
The lookup configuration uses <Lookup Name="…"> elements, one per named lookup. Each lists, as
<Field Name="…" /> lines, the fields a lookup row shows, with ID first.
A lookup's name is matched against the product's named lookups, not against the class list. Most names are class names, such as "Person", "Service Catalog Item", and "Knowledge Base Article", but "Technician", "Technician Group", "Ticket Service", and "Library" name lookups, not classes.
In the supplied document, Person lists ID and Full_Name; Organization lists ID, Name,
Parent_ID, and Internal; Location lists ID, Location, and Parent_ID; and the five
ticket-shaped classes list ID and Ticket.
For example, to show a person's primary e-mail address in the rows of the Person lookup as well,
add <Field Name="Primary_Email" /> to its field list.
AI Assistant
The AI Assistant tab has an Enable AI Assistant check box, a readiness banner, and four sub-tabs: General, Skills, Commands, and Placeholders. Each sub-tab has its own address, so a link to a sub-tab opens it directly.
The banner reads "AI Assistant is currently unavailable" when AI features are not enabled or no API key is set, and "AI Assistant is ready to use" otherwise. Both add "AI Assistant requires globally enabled AI features and relies on a properly configured AI integration, including the API key." and a Configure AI integration link.
In the portal, the AI Assistant answers only while AI features are enabled globally and Enable AI Assistant is checked for the instance.
General
- Enable system prompt editing is disabled until Enable AI Assistant is checked. The prompt box is disabled until both are checked. Enable system prompt editing opens checked only when a custom prompt is stored.
- Without a custom prompt, the box shows the default prompt, which begins "You are a helpful AI assistant for the 'Self Service Portal'." and carries placeholders for the current user's name and locale.
- Clearing Enable system prompt editing, or checking it while the box is empty, puts the default prompt back in the box. Checking it over existing custom text leaves the text alone.
- Restore Default under the box puts the default prompt back. It is disabled while the box already holds the default prompt or the box is disabled.
- The prompt is stored as a custom prompt only when prompt editing is on, the text is not empty, and it differs from the default prompt.
Incident Create Action reads "Select a workflow action for the assistant to use as the ticket constructor. This avoids asking the user when multiple actions exist." Its Action box lists the enabled portal create actions of the Incident class, actions without a group first, then by rank. The section is hidden when there are none. The Action box stays available while Enable AI Assistant is cleared.
When an action is selected, the portal's AI Assistant uses only that action to create a ticket and does not ask the customer to choose one. When no action is selected, the assistant can use any of the portal's ticket create actions, and it picks the action without asking when only one exists.
Skills
The skills table shows Display name, Description, System, and Enabled. Click Add to create a skill. Each row offers a delete action.
The skill form has:
- Display name (required).
- Skill ID (required). For a new skill, the ID is filled in from the display name as lowercase words joined by hyphens, until you edit it yourself. The ID accepts lowercase letters, digits, and hyphens, must be unique, and cannot be changed once the skill exists. The form reports "Name must be in kebab-case format (e.g. your-custom-name)" or "Another skill already uses this ID".
- Description, Instructions, and Required modules.
- For an existing skill, a read-only System box and an Enabled box.
The text fields and the module list of a system skill are disabled. An enabled skill whose required module or embedding is missing shows a warning tooltip naming what is missing.
Commands
The commands table shows a check mark in its Enabled column for an enabled command. The table offers Add and Delete.
The command form has Display name (required), Display name localization key, AI prompt (required), Prompt localization key, and Required skills, plus the System and Enabled boxes for an existing command. The fields of a system command are disabled. An enabled command whose required skill is unavailable shows a warning tooltip that lists the unavailable skills and adds "See Skills tab".
What applies to this instance and what applies to all
- The Enabled box of a skill or command applies to this instance only and is saved only when you save the page.
- The text you enter in a skill or command form is saved as soon as you click Ok in the form, and it changes that skill or command for every portal instance.
Placeholders
The Placeholders sub-tab is a reference table, not a form. It lists placeholder tokens and their descriptions in three sections:
- User Context:
{{$currentUser.name}}and{{$currentUser.locale}}. - Skills: five tokens, one per built-in skill.
- Tools: ten tokens, one per built-in tool.
Portal logs
Among the Admin Center's Logs pages are two portal logs. For logs in general, see Logs.
- The portal search log lists the logged portal searches, newest first, each with its date, which links to the record, the person, the search scope, the search text, and the number of results. Opening a record shows the same five values in a side panel.
- The portal AI Assistant log lists AI Assistant runs, newest first.
Both logs offer a delete action.
In the Settings App
The Settings App's Self Service Portal node holds the Self-Registration, Workflow, and E-mail Templates pages, and the Settings App also reads the portal search log. See Self-Registration, Portal Actions and Forms, Notifications Overview, and Logs.