Portal configurations

Introduction to portal configurations in ConSol CM

Portal configurations are used to configure the user interface of CM/Track. You can create several portal configurations for different CM/Track instances.

Concepts, terms and definitions

Concept	Other terms	Definition
CM/Track		ConSol CM add-on, portal which allows customers to create and view their cases
JSON	JavaScript Object Notation	Format of files holding portal configurations
activity form	ACF, Activity Control Form	Form which is displayed when the user executes an activity. The required fields of the form need to be filled out before proceeding.
default values script	prefill script	Script used to prefill fields with certain values for case creation

Purpose and usage

The portal configuration allows to define the following aspects for CM/Track:

• images and colors
• displayed components
• layout of the case page
• localization for various languages

A portal configuration consists of several JSON and CSS files where the settings are made. In addition, some images are saved in the ConSol CM database, and the authentication settings are saved in system properties. The portal configuration is based on a template with the default configuration.

Portal configuration are managed in three tabs:

• Basic configuration: Graphical user interface which allows to configure everything besides authentication, translations and advanced styling

• Authentication: System properties which are used to configure authentication

• Files: JSON and CSS files which hold the basic configuration and allow advanced customizations

The settings made on the Portal configurations page apply to one or several specific instances of CM/Track. In addition to this configuration, some global settings, which apply to all CM/Track instances, are required. They are done on the Global portal settings page.

Files for portal configurations

The portal configuration for CM/Track includes the following files:

• components_localization.json
  Contains the localizations of GUI texts from PrimeReact components. By default, the file is available for English (components_localization_en.json) and German (components_localization_de.json). Other language variants can be added to localize the components into these languages.

• config.json
  Contains the configuration of CM/Track after logging in. This includes the welcome page, the case page and the password change functionality.

• custom.css
  Allows to override the default styles of CM/Track. Please use it only for styles which are not included in the theme.css.

• localization.json
  Contains the localization of the GUI texts which are displayed after logging in to CM/Track. By default, the file is available for English (localization_en.json) and German (localization_de.json). Other language variants can be added to localize CM/Track for these languages.

• public.json
  Contains the configuration of CM/Track before logging in. This includes the password reset functionality and localizations.

• theme.css
  Contains the settings from the Visual appearance section. Should not be edited manually.

• welcome.json
  Contains the configuration for the case creation tiles on the welcome page.

Settings for portal configurations

The portal configuration has the following attributes:

• Name: Internal name of the configuration.

• URL of the CM/Track instance: URL, including protocol, target port and path to of the CM/Track instance which should use the configuration. If your configuration is called trackV3, it is picked up by all your CM/Track instances automatically.

  If you want to map several CM/Track instances to the same portal configuration, you need to edit the system properties related to the URL mapping and OIDC configuration manually, see Using a portal configuration for several URLs.

Visual appearance

CM/Track comes with a light and a dark mode. You can choose your own images and colors for each mode. The following colors can be defined:

• Primary color: The primary color of the theme. The color selected here will be used in buttons, borders, visual selection highlighters and the most important application links.

• Top bar: The color of the upper border of the top navigation bar. Typically the same or a complementary color to the primary color.

• Text of selected element: The text color used in actively selected elements, for example in a hierarchical list, date, autocomplete, select or dropdown. This color setting is used as background color when a button is in focus.

• Shadow of focused element: When an element like a button or input field is in focus (via tabbing or mouse click), this is communicated visually with a focus ring. The color selected here defines the color of this ring, typically you will use a variant of the primary color.

• Header background: The color selected here is used as a background color of header elements, for example in tables.

• Background of selected element: The color used to visually communicate an actively selected element, for example in a hierarchical list, date, autocomplete, select or dropdown.

• Background of hovered element: The color used to visually communicate a hovered element, for example when selecting a value in a hierarchical list, date, autocomplete, select or dropdown.

• Borders: The color of borders throughout the application, for example the form field or table borders. In most cases these will be gray.

• Text: The primary text color. Most of the visible text will appear in the selected color.

• Headline text: Color used for headline texts, for example the case subject, navigation menu, table and page headers.

• Label text: Text color used for secondary or grayed out texts, mostly in labels.

• Text on primary color background: Color which is used when the text is written on the primary color, like on buttons. It should be white when using a dark primary color and black otherwise.

The settings are saved to the theme.css file and the images which you upload are saved to the database.

Case fields

Configure the layout of cases for the two modes:

View: The customer displays an existing case. The layout is saved to the editLayout and editLayoutOptions attributes of config.json file.

Create: The customer creates a new case. The layout is saved to the createLayout and viewLayoutOptions attributes of config.json file.

The following settings are available for each mode:

• Default number of columns: Defines how many columns are used to display the fields which do not have an explicit layout.

• Displayed fields: Defines which fields are shown. Possible values:

  • All fields available via REST: All case fields which have the setting to make them available via REST with full access or read-only access are shown.

  • Only fields added explicitly: Only case fields which are configured explicitly are shown. This means that you need to select the respective field group and add the fields to the group layout.

  See Global portal settings for a detailed description of which fields are available via REST.

• Field groups: Select the field groups which should be shown in CM/Track and sort them with the arrow buttons. For each group, you need to click the Add field layout button to select the fields which should be shown and position them as desired. Fields can span several columns, which is useful for large tables.

  Empty positions can only be added at the end of a row. Empty positions at the beginning or in the middle are removed automatically when saving the configuration.

Activity forms

Configure the layout of the activity forms which are used in activities which are available for customers. This is only required if you want to override the layout defined on the Activity forms page.

Select the activity form which you want to layout. You can choose the number of columns and position the fields as desired. Fields can span several columns, which is useful for large tables.

Fields which are not configured explicitly are displayed below the configured fields, i.e. you cannot remove a form field by removing it from the layout. Instead, you need to make the field unavailable via REST.

Empty positions can only be added at the end of a row. They are removed automatically when saving the configuration of they are placed at the beginning or in the middle.

General settings

The following settings are available. They are saved in the config.json and public.json files:

• Comment required for case creation: Determines if the user must enter a comment when creating a new case (true) or not (false).

• Display order of case history entries: Determines the order of the case history entries; can be Newest entries first (default value) or Oldest entries first.

• Users cannot reset their passwords on the sign-in page
  Determines whether the users can reset their passwords on the sign-in page of CM/Track (false, default value) or not (true). If this attribute is set to true, the link Forgot your password? is not displayed.

• Users cannot change their passwords: Determines whether the users can change their passwords when they are logged in to CM/Track (false, default value) or not (true). If this attribute is set to true, the menu item Change password is not shown.

• Apply default values script
  Determines whether the default values script of the queue is executed when a user creates a new case (true) or not (false), see Scripts of the type Default values.

Rich text editor

Rich text editors are used in the comment field and in rich text fields. They have one common setting:

• Maximum file size (MB): Determines the maximum size of one image in the editor in megabytes. This applies to both rich text fields and the comment field.

The following settings can be configured independently for each editor. First, you select the scope of the configuration: Comment or Rich text field. For rich text fields, you can define the behavior for all fields, or select a specific field to define editor properties for this field only.

• Minimum editor height (px): Only for the comment editor. Determines the height of the editor in pixels.

• Editor height (px): Only for rich text fields. Determines the height of the editor in pixels.

• Editor toolbar: Defines the available toolbar buttons in a JSON structure. See https://froala.com/wysiwyg-editor/docs/options for the available options.

The settings are saved to the config.json file.

In the localization.json files you can modify the text which is shown for rich text fields which are configured for link view with the Rich text display in view mode setting:

• preview_show_link: Text for the link to open the dialog with the field content

• preview_dialog_title: Title of the dialog with the field content

Case creation tiles

The welcome page includes tiles which serve as a quick access to case creation. By default, all queues to which the user has access are displayed on the welcome page with their default settings, i.e. with the queue name, description and icon from the Queues page.

Alternatively, you can define the tiles individually. The settings are saved in the welcome.json file. If the user has access to a queue for which there is no tile, this queue is shown in the More button.

You can freely combine tabs and lists to group your tiles and create a hierarchical structure. There are several configuration possibilities:

• Tiles only: Directly add your tiles to the welcome page. Such a configuration looks similar to the default display, with the difference, that all defined tiles are shown directly, i.e. there can be several rows of tiles.

• List: Create list items and add the desired tiles to each list item. You can choose between a display as panels or as a list, depending on whether all tiles should be visible at once or not.

• Tabs: Create tabs and decide for each tab if it should contain a list or tiles only.

The following settings apply to the structure:

• Enable item search: Decide if a search field to filter the tiles should be shown above the tiles. This can be useful if you have many tiles. This is a global setting.

• Items per row: Select how many tiles should be displayed in each row on large screens. This setting is global if no tabs are used. If there are tabs, it can be defined for each tab.

• List item visualization: Only relevant if lists are used. Select how to display list items and tiles. This setting is global if no tabs are used. If there are tabs, it can be defined for each tab.

  • Underneath each other on the left side: A list is shown on the left. The tiles belonging to a list item are displayed on the right when selecting the respective list item.

  • One panel for each list item: The tiles are grouped in panels with each panel representing a list item. All tiles are visible at once.

Adding tiles

To add a tile, click the plus icon in the main panel. The following settings can be made for each tile:

• Name for links: Mandatory. Enter a name for the tile. The name will be used in the URL of the case creation window for this tile to allow setting a bookmark for direct access.

• Target queue: Mandatory. Select the queue in which the case will be created.

• Localized name: Optional. Enter the localized name for the tile.

• Localized URL: Optional. Enter a valid URL to show a link icon pointing to this URL inside the tile. Optionally, you can add a description for the URL after a space.

• Localized description: Optional. Enter the localized description to be displayed below the tile name.

• Default values: Optional. Select default values for prefilling data fields of the types Enumerated list or Hierarchical list in the case creation window.

• Icon: Mandatory. Select an icon for the tile or upload a new one. By default, the queue’s icon is used.

• Color: Mandatory. Select a color for the icon. By default, the queue’s color is used.

Using lists

To add the first list item, click the New list item button. Subsequent list items can be added by clicking the plus icon below the first list item. The following settings can be made for each list item:

• Name: Mandatory. Enter an internal name for the list item.

• Localized name: Optional. Enter the localized name for the list item.

Using tabs

To add the first tab, click the New tab button. Subsequent tabs can be added by clicking the plus icon next to the first tab. The following settings can be made for each tab:

• Name: Mandatory. Enter an internal name for the tab.

• Localized name: Optional. Enter the localized name for the tab.

• Icon: Optional. Select an icon to be displayed before the tab name.

• Color: Optional. Select a color for the icon.

Widgets on the welcome page

Three types of widgets can be shown on the welcome page of CM/Track:

• Case list: Shows the newest cases of the user.

• Generic: Shows script-based content.

• News: Shows news.

By default, there is a case list widget only. You can add additional widgets by clicking the Add widget button. You need to enter an internal name and select the widget type. The available settings depend on the widget type. Afterwards you can drag the widget to the desired place on the grid and modify its size by using the arrow icons.

Case list

No additional settings

Generic

You need to select a widget visualization script (see Scripts of the type Widget visualization) in the the Script (type ‘Widget visualization’) field. The script needs to return the content of the widget.

News

You need to provide the following settings:

• Script (type ‘News publisher’): Select a news script see Scripts of the type News publisher) which creates the news entries. They can be retrieved from several sources, for example, case comments or RSS feeds, or created directly in the script.

• Headline: Enter the title for the news widget in the configured languages. If no localized title is specified, the default title “News” is displayed.

• Height (px): Enter the height of the widget in pixels.

• Show creation date: Determines whether the date when a news entry was created should be displayed (true) or not (false).

• Show update date: Determines whether the date when a news entry was updated should be displayed (true) or not (false).

• Show author: Determines whether the author who created the news entry should be displayed (true), or not (false).

• Color selection: Select a color for the news symbol and headline.

Authentication

The Authentication tab contains the settings which are needed to configure user authentication via OIDC.

The following settings are available:

• Provider type: Select “Internal” to use the ConSol CM authentication application as OIDC provider. Select “External” if a third-party application, such as Azure AD or ADFS should be used. Saved to the system property cmas-core-security, oidc.track3.providerType.<configuration_name>.

• Global logout: Determines if the user is also logged out from the OIDC provider when logging out of CM/Track. For an internal provider, the value “True” should be selected. For an external provider, the value is usually “False”, so that sessions in other applications, which are provided by the same provider, are not closed. Saved to the system property cmas-core-security, oidc.track3.globalLogout.<configuration_name>.

• Authentication method: Read-only. The authentication method for CM/Track if the internal OIDC provider, i.e. ConSol CM itself, is used.

  This is a global setting which applies to all portal configurations. It can be changed only on the Global portal settings page.

• URL of the CM/Track instance for OIDC: Read-only. The URL of the CM/Track instance which the OIDC configuration belongs to.

  The value is derived from the URL of the CM/Track instance. If another value is needed, you can change it in the system property cmas-core-security, domain.map.for.oidc.config.<configuration_name> on the System properties page.

• Redirect URI: Read-only. Redirect URI where authentication responses can be received. This is either the OIDC endpoint on the ConSol CM server running CM/Track or on the load balancer.

  The value is derived from the URL of the CM/Track instance. If another value is needed, you can change it in the system property cmas-core-security, oidc.track3.redirectUri.<configuration_name> on the System properties page.

• URL of the authentication authority: Enter the URL of the authenticating authority. Saved to the system property cmas-core-security, oidc.track3.authority.<configuration_name>.

  The default value is derived from the URL where the Web Admin Suite runs.

• Client ID: Enter the client ID (application ID) of the application, as registered in the OIDC provider. Saved to the system property cmas-core-security, oidc.track3.clientId.<configuration_name>.

• Client secret: Enter the secret of the client, generated by the OIDC provider. Saved to the system property cmas-core-security, oidc.track3.clientSecret.<configuration_name>.

• Name of claim: Enter the name of the claim in the ID token which is used to map the user to a contact in ConSol CM. The value depends on the settings of the OIDC provider; the default values are “upn” and “unique_name”. Saved to the system property cmas-core-security, oidc.track3.usernameClaim.<configuration_name>.

• Regex for mapping user names: Define the regular expression used for mapping the user name claim values to ConSol CM user names. Saved to the system property cmas-core-security, oidc.track3.usernameRegexp.<configuration_name>

  • “upn” as claim: (.*)@.* will transform the claim value “user1@sso.yourdomain.com” to “user1” and look up “user1” in the ConSol CM database.

  • “unique_name” as claim: .*\\(.*) will transform the claim value “SSO\user1” to “user1” and look up “user1” in the ConSol CM database.

Basic tasks

Working with portal configurations

You can perform the following actions on client configurations:

• Create a new portal configuration
  Click the New configuration button and enter a name for the configuration. You can either select an existing CM/Track V2 configuration to migrate it to CM/Track V3 or leave this field empty to create a new configuration based on the default template TrackV3.
• Edit a portal configuration
  Open the details of a configuration and go to the Basic configuration tab. Make the desired changes, see Settings for portal configurations and click Update configuration.
• Edit the files of a portal configuration
  Open the details of a configuration and go to the Files tab. You can edit the name of a file by clicking the Edit icon next to the file name. Click the Add file button to add a new file to the configuration. This can either by a file from the TrackV3 template from the template file selector or an empty file. Click the Delete file button below the editor of the file to remove this file from the configuration. You can edit the content of the file in the editor displayed below the file name. Click the Save changes button below the editor to save your changes. If you modify several files you can also use the Save all files button at the bottom of the page. Click the Discard changes button below the editor to revert your changes to the respective file.
  
• Delete a portal configuration
  Click the Delete icon. The configuration is deleted upon confirming the warning message.

Advanced tasks

Editing GUI texts

The GUI texts can be changed in the components_localization.json, localization.json and public.json files:

1. Go to the Files tab.

   If you have unsaved changes in the Basic configuration tab, you need to save these changes first.

2. Click the button of the desired file to scroll the page to the beginning of the file.

   • components_localization.json: Contains the texts from components visible to users after logging in to CM/Track.

   • localization.json: Contains the texts visible to users after logging in to CM/Track.

   • public.json: Contains the texts on the login page of CM/Track.

3. Edit the texts in quotes after the colon.

4. Save your changes by clicking the Save changes button below the file or the global Save all files button.

Changing number and date formats

The localization.json file contains attributes which allow to change number and date formats:

• globalDateViewFormat: date format in view mode, default is dd.MMM yyyy

• globalDateEditFormat: date format in edit mode, default is dd.MMM yyyy for German and M/d/yy for English

• number_decimal_separator: decimal separator for numbers, default is . for English

• number_group_separator: thousands separator for numbers, default is , for English

Adding headlines to the case or activity form layout

You can use headlines to structure the fields of cases or activity forms:

1. Create a field and assign the setting Text display with the value Title on the Case fields page.

2. Add the field to the layout:

   • Case fields: Click the Add field layout button for the respective field group, select the field and position it as desired.

   • Activity form: Add the field to the activity form on the Activity forms page and position it as desired.

Make sure that the group which the field belongs to includes at least one field which has a value. Otherwise, the whole group is omitted when viewing the case.

Using a portal configuration for several URLs

The default OIDC configuration covers the situation that the default portal configuration called “trackV3” is used by one instance of CM/Track, which is accessible via one URL. If the portal configuration has another name, an OIDC configuration with this name is created automatically when providing the URL of the CM/Track instance.

Manual OIDC configurations are needed if several URLs are used, for example in the following situations:

• Two different instances of CM/Track use the same portal configuration.

• One instance of CM/Track is accessed via two different URLs, e.g. an internal one and an external one.

For each URL used to access CM/Track, one OIDC configuration is needed. It must be created manually on the System properties page. The following changes are needed:

1. Add all the URLs which should use the portal configuration as a comma-separated list to the system property cmas-restapi-core, domain.map.for.client.config.<portal_configuration>, e.g. domain.map.for.client.config.MYPORTAL=http://cm.consol.pl:8999/cm-track, http://cm.consol.pl/cm-track.

2. Create an OIDC configuration for each URL. It needs to contain at least the following properties:

   • Create cmas-core-security, domain.map.for.oidc.config.<oidc_configuration> and set the URL through which CM/Track is reached as a value, e.g. domain.map.for.oidc.config.MYTRACK1=http://cm.consol.pl:8999/cm-track.

   • Create cmas-core-security, oidc.track3.redirectUri.<oidc_configuration> and set the /oidc endpoint of the CM/Track instance as a value, e.g. oidc.track3.redirectUri.MYTRACK1=http://cm.consol.pl:8999/cm-track/oidc/.

   • Create cmas-core-security, oidc.track3.authority.<oidc_configuration> and set the /cmas-auth-portal-user endpoint of the authentication application as a value, e.g. oidc.track3.authority.MYTRACK1=http://cm.consol.pl:8999/cmas-auth-portal-user.

3. Review the default OIDC configuration, see Authentication. If different values are needed, create configuration-specific properties to overwrite the defaults, e.g. oidc.track3.authority.MYTRACK1.