CM/Track V3 as new portal application (#657428)

CM/Track V3 is the new web application which acts as a portal for ConSol CM. It allows the customers to view the status of their cases and interact with the Web Client users by adding comments and attachments or executing activities. The web application is responsive, so that it can be used on mobile phones.

The previous portal application, CM/Track V2, is still supported. It will be removed in a future version.

New applications

You need to run two new applications:

• CM/Track V3: track-v3-application-package-war.war for deployment in the same application server as ConSol CM and track-v3-application-package-app.jar for standalone deployment.
• Authentication application: auth-application-package-war-portal-user.war for deployment in the same application server as ConSol CM and auth-application-package-app-portal-user.jar for standalone deployment.

If the applications are deployed in the same application server as ConSol CM, the URLs are <CM_URL>/cm-track and <CM_URL>/cmas-auth-portal-user.

Features

CM/Track V3 has the same functional scope as CM/Track V2. In addition, the following features are supported:

• Global date format: The date format can now be defined in the localization.json files. Two attributes have been added:
  • globalDateViewFormat: Date format in view mode; default value "dd.MMM yyyy"
  • globalDateEditFormat: Date format in edit mode; default values "dd.MMM yyyy" for German and "M/d/yy" for English
• Easy definition of styles: The styles from can be overwritten on the Portal configurations page in the Web Admin Suite. Some colors can be selected on the GUI and are written to the new theme.css file. Additional styles can be changed by manually editing the new custom.css file.
• Easy switching of images: The images (logo, background image of the login page, image on the welcome page and image on the FAQ page) can now be managed on the Portal configurations page in the Web Admin Suite, where it is possible to upload other images.
• New set of queue icons: The icons and colors set for the queues on the Queues page of the Web Admin Suite are now used on the welcome page. You can choose from a large number of default icons or upload your own icon (PNG or SVG format). In addition, you can freely determine the background color for the icon, see Queue icons (#658830, #658890).

Usability improvements

The following usability improvements have been made in CM/Track V3:

• Intuitive button for case creation: The button to create a new case is located in a prominent position in the upper right corner so that it is easy to find. The case is created in a modal window.

  

• Intuitive queue selection for case creation: When creating a new case, the queue is now selected in a user-friendly way in a modal window. The queue selector on the case creation page has been removed.

  

• New position of workflow activities: The workflow activities are now shown on the right side of the case in a similar way as in the Web Client. Therefore, all activities are shown directly and the user has a good overview of the options.

  

• Filtering of the case list: The options to filter and sort the case list are now bundled in the Filter button to save space. The number of applied filters is displayed in a small badge on the button.

  

• Improved display of empty case list: If the case list is empty, a user-friendly message with a nice image is now shown instead of a blank space.

• Improved display of the case history: The case history now has colored icons and descriptive tags to make it easy to distinguish the different types of content.

  

• Better wording: The wording in CM/Track V3 has been improved for better clarity.

• Attachment validation on upload: The size and file type of attachments is now checked directly after uploading the file. The related error messages are displayed inside the upload component for each attachment. This allows the user to react directly.

  

• New MLA selector: The MLA selector now allows selecting a value by clicking the value itself and opening the next level by clicking the arrow icon in front of the value.

  

• Dark mode: The user can now choose to display the whole application in dark mode. By default, the light mode is active.

Configuration enhancements

Two new pages have been added to facilitate the configuration of CM/Track V3. In addition, the error handling has been improved. If CM/Track V3 is opened and there is no connection to the ConSol CM server or the portal configuration could not be loaded because it is broken, an error message is shown directly on the login page.

New Portal configurations page

The configuration of CM/Track V3 can now be done on a graphical user interface in the Web Admin Suite. Hints and validation messages are shown to help the user with the configuration. The page Portal configurations has been added to the new menu group Portals for this purpose. It shows a table with all configurations for CM/Track V3. The details panel of a configuration has two tabs:

• Basic configuration: Allows to configure CM/Track V3 on a graphical user interface. The settings are saved to the config.json file and the theme.css file. They are grouped in the following sections:

  • Visual appearance: Styles and images

  • Case fields: Field layout when creating a case and / or viewing a case, defined for each field group

    info

    The field groups can now be ordered as desired using the arrow buttons.

  • Activity forms: Field layout of activity forms, prefilled with the layout defined on the Activity forms page

  • General settings: Miscellaneous settings

  • Rich text editor: Features and display of the rich text editor for different screen sizes

  • Welcome page: Order and content of the boxes to create cases in specific queues on the welcome page

  • News widget: Configuration of the news widget on the welcome page

• Authentication: Allows to configure the properties which are required for the OIDC configuration. The OIDC provider can be the authentication application provided by ConSol CM or a third-party OIDC provider.

• Files: Allows to edit GUI texts in the localization.json and components_localization.json files and the public.json file. The default styles of CM/Track V3 can be overwritten in the custom.css file. In addition, it is possible to add custom files. The buttons at the top of the page allow to jump to the files directly. The file content is wrapped to avoid horizontal scrolling.

Configurations for CM/Track V3 are displayed on the Client configurations page alongside the configurations for CM/Track V2. The TrackV3 template is now available when creating a new client configuration on this page. When creating a new configuration on the Portal configurations page, the TrackV3 template is applied automatically if no existing CM/Track V2 configuration is selected for migration.

info

The TrackV3 template does not contain any examples which are based on the Test and Demo scene because the configuration can be done using the graphical user interface.

New Global portal settings page

The settings which are shared between all portal configurations and CM/Track versions are displayed on the new Global portal settings page. The page has six tabs:

• Authentication: Default OIDC configuration (CM/Track V3 only) and authentication method
• Credentials: Permissions, credentials and login to CM/Track
• Case fields: Case fields available in CM/Track
• Case history: Case history entries available in CM/Track
• Workflow: Workflow activities available in CM/Track
• General: Miscellaneous settings

The user can view the settings and switch to the pages where they are configured to modify them as needed. Settings which are saved in system properties can be edited directly.

Authentication changes

Internally, CM/Track V3 uses the new ConSol CM authentication application. This application serves as an internal OIDC provider. It can retrieve the credentials from database or LDAP as in previous versions of CM/Track. In addition, it can be used with an external ID provider as Azure AD/Entra ID or ADFS.

The following steps are required to enable authentication in CM/Track V3:

1. Run the authentication application for CM/Track V3. It can be either deployed in the application server or executed as a standalone Java application.

2. Create a portal configuration in the Web Admin Suite.

3. Review the OIDC properties. The default properties are added automatically during setup and update of ConSol CM.

   info

   If your portal configuration is called "trackV3", the default properties (<property_name>.default) will be used. If your portal configuration has a different name, the named properties (<property_name>.<configuration_name>) will be used. They are created automatically together with the portal configuration:

   • cmas-core-security, oidc.track3.authority.default: URL of the authenticating authority. The default value is the ConSol CM URL + /cmas-auth-portal-user.
   • cmas-core-security, oidc.track3.clientId.default: Client ID (application ID) of the application, as registered in the OIDC provider.
   • cmas-core-security, oidc.track3.clientSecret.default: Secret of the client, generated by the OIDC provider.
   • cmas-core-security, oidc.track3.globalLogout.default: Determines if the user is also logged out from the OIDC provider when logging out of CM/Track. The default value is "true", which is correct for an internal provider. 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.
   • cmas-core-security, oidc.track3.providerType.default: The type of OIDC provider. The default value is "internal", which means that the ConSol CM authentication application is used as an OIDC provider. Select "external" if a third-party application, such as Azure AD or ADFS should be used.
   • cmas-core-security, oidc.track3.redirectUri.default: 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 default value is the ConSol CM URL + /cm-track/oidc/.
   • cmas-core-security, oidc.track3.usernameClaim.default: Name of the claim in the ID token which is used to map the user to a contact in ConSol CM. The default value is "sub".
   • cmas-core-security, oidc.track3.usernameRegexp.default: Regular expression used for mapping the user name claim values to ConSol CM user names. The default value is "(.*)".

4. Enter the URL of the authentication application in the property cmas-core-server, url.track.auth. If it is deployed in the application server, this is the /cmas-auth-portal-user endpoint.

5. Review the new password reset template track-auth-password-reset-template, which is added automatically during setup and update of ConSol CM.

6. Review the new authentication protection templates mail-auth-contact-many-account-auth-failures and mail-auth-admin-contact-unblock-code, which are added automatically during setup and update of ConSol CM.

info

The authentication application can be used for CM/Track V3 only. The example proxy configuration has been updated with the required information about running the application behind a proxy.

REST changes

The ConSol CM REST API has been extended by the endpoint /configuration/{configName}/entries/{entryName}/variants/{variant}. It allows to fetch the localization.json files in the different language variants, and the custom.css, theme.css and public.json files.

Migration

When selecting an existing CM/Track V2 configuration in the New configuration window, this configuration is migrated to CM/Track V3. This means that a new CM/Track V3 configuration with the settings of the existing configuration is created.

info

The existing CM/Track V2 configuration remains as is, i.e. it is not modified.

This facilitates switching to CM/Track V3 as no manual efforts are required to take over the configuration.

Added configurations

The following elements are added to the configuration files during the migration:

• theme.css file with the default values for the new design
• Empty custom.css file as a placeholder for further styling changes
• Attributes globalDateViewFormat and globalDateEditFormat with default values for the date display in localization.json
• Localizations which are new in the TrackV3 template are added with their default values to the localization.json and public.json files. If the configuration includes languages other than English or German, the English translations are used for these languages.

Removed configurations

The following attributes are removed from the config.json file during the migration because they are not needed anymore:

• layout and layoutOptions for case field groups: Replaced by editLayout, viewLayout, editLayoutOptions and viewLayoutOptions.

• width attribute for rich text fields: The width of rich text fields is determined by the number of columns they span. This is configured in the Case fields section for the respective field group.

• icon attribute for queues on the welcome page: The icon defined for the queue on the Queues page is now used.

  warning

  Font Awesome icons are not supported anymore.

• description attribute for queues on the welcome page: Only localized descriptions are used now. They are created in the localization.json files when a description is provided in the Welcome page section. By default, i.e. if no localized descriptions are provided, the descriptions for the queue from the Queues page are used.

• title attribute for news: Only localized titles are used now. They are created in the localization.json files automatically.

• autoscroll attribute for news: Automatic scrolling for news entries is not supported anymore.

In addition, translation keys, which were present in the TrackV2 template and are not present in the TrackV3 template, are removed from the localization.json and public.json files during the migration because they are not needed anymore.