App and Solution
...
Solutions
Register Your Solution

Landing Pages for Solutions

16min

Overview

Developers can enhance the user experience by configuring landing pages for their solutions. Landing pages direct users to specific pages within the solution based on their user group or a default setting. This guide will walk you through the process of setting up and managing landing pages for your solutions.

Landing Page Behavior

When a user accesses your solution, the landing page they are directed to is determined by the following rules, in order of precedence:

  1. If the user belongs to a single user group and that group has a landing page configured in the solution-level manifest file, the user will be directed to that landing page.
  2. If the user belongs to multiple user groups with configured landing pages, the user will be directed to the landing page of the user group with the highest priority (lowest rank value).
  3. If no user group-specific landing page matches the user's groups, if set, the default landing page configured will be used.
  4. If no landing pages are configured (user group-specific or solution default), the user will be directed to the first accessible app in their console sidebar.

Configuring Landing Pages

There are two types of landing pages you can configure for your solution:

  1. Default Landing Page: A single, default landing page for all users accessing your solution.
  2. User Group Landing Pages: Specific landing pages for different user groups within your solution.

Default Landing Page

To set a default landing page for your solution:

  1. In the request body, include the solnUrls object with the URL of your desired default landing page.

Example:

JSON


In this example, the solnUrls object contains an object with two properties:

If you configure a default landing page, it will direct users to this page when they access your solution, unless a user group-specific landing page is defined and takes precedence.

User Group Landing Pages

To configure landing pages for specific user groups:

  1. For each user group you want to configure a landing page for, add a landingPage attribute under the userGroupsRequired definition. This attribute should contain two properties:
    • url: The relative path to the landing page for this user group
    • rank: A positive integer indicating the priority of this user group in case the user belongs to more than one user group. Lower values have higher priority. For example, rank 1 is a higher priority than rank 3.

Here's an example manifest file with user group landing page configurations:

YAML

  1. Save your updated manifest file and upload it using the UploadArtifact API.
  2. Onboard your solution. The solution service will automatically configure the landing pages based on your manifest.

Retrieving Landing Page Configurations

To retrieve the landing page configurations:

  • For the default solution landing page: Use the GetSolution API to view the details in the solnUrls object defined when registering or updating your solution.
  • For user group landing pages: Use the GetArtifacts API to retrieve the manifest file contents, including the landing page URLs and ranks for each user group.

Updating Landing Pages

Follow the steps below to update the default landing page for your solution and the landing pages for specific user groups.

Updating the Default Landing Page

To update the default landing page, call the UpdateSolution endpoint and include the updated solnUrls array with the new default landing page URL in the request body:

JSON


Updating User Group Landing Pages

To update the landing pages for specific user groups: Edit the solution manifest YAML file and modify the landingPage attribute for the desired user groups.

  1. Call the UploadArtifacts API to upload the updated manifest file:
Curl


2. Update the solution version using the AddSolutionVersion API:

Curl


3. Onboard the updated solution version to the tenant using the Onboarding API with the forceCreateUserGroup=true query parameter:

Curl


After updating the landing page configurations, the changes will be reflected in your solution. Users will be directed to the updated landing pages based on their user groups and the new default landing page setting.

Note: Remember to replace {solutionVersionId} in the API endpoints with the actual version ID of your solution.

Removing User Group Landing Pages

If you need to remove previously configured landing pages from your solution, follow these steps:

Removing the Default Landing Page

To remove the default landing page for your solution:

  1. Call the UpdateSolution API.
  2. In the request body, pass null against the solnUrls object name and url parameters.

Example:

JSON


This will remove the default landing page configuration, and users will no longer be directed to the previously set default landing page when accessing your solution.

To remove landing pages for specific user groups:

  1. Locate the user groups for which you want to remove the landing page configuration.
  2. Remove the entire landingPage attribute and its sub-properties (url and rank) from each relevant user group definition.
  3. Save your updated manifest file and upload it using the UploadArtifact API.
  4. Onboard your solution. The solution service will automatically update the landing page configurations based on your manifest.

Example:

YAML


After removing the landing page configurations, the landing page precedence rules will be re-evaluated based on the remaining configurations. If no landing pages are configured at all (neither user group-specific nor solution default), users will be directed to the first accessible app in their console sidebar when accessing your solution.