Categories

System Admin
Activity Tracking
DXM
Data
Approval Groups

Links

How to set up a Document Portal

Document Portal is a client-side JavaScript application that is available as a Studio Application within Kurtosys.

All Document Portals share the same codebase but individual apps can be configured and styled to match client branding.

Follow the steps below to set up a Document Portal. To see what the portal looks like and where specific elements are located, take a look at the Document Portal Visual Guide.

 

Pre-requisites

  1. The Document Portal Template Application must be deployed to the environment where you will be setting up. It is available in Release and Production, so only mentioned for completeness.
  2. A Client Admin user for the client you are setting up.
  3. An API user with a permanent token for the client you are setting up.
 
 

Creating a Document Portal instance

Log in to Kurtosys as a Client Admin and navigate to Studio.

Under the Apps tab click + to create a new Application Instance.

Skip the setup Wizard to access Application Details. 

 

App Config

Choose Template Application (default selection) from the large split-button at the top of the page.

Complete the form as follows.

 

Application Template

Select document-portal-vx.x.x.

 

Name

Name your application. Be careful since the name cannot be changed via the UI once the app has been created.

 

Description

A description for your application.

 

Cookie Domain

The cookie domain should be the domain where your application will be served from. This enables the application to set a cookie on successful login.

If you intend to use the application with its app manager url (for example: https://api.kurtosys.app/applicationManager/apps/xxxxxxxx-xxxx-xxxxxxxx) then the cookie domain should be set to ***kurtosys.app***.

If the application app manager url has been mapped to an internal development/staging domain or the clients’ production domain, then use that domain (for example, clientportal-dev.kurtosysweb.com, clientportal.someclient.com).

No http(s):// prefix is required for the cookie domain.

 

Application Domain

The application domain should be the URL where your application will be served from. This is primarily used in email templates where we link back to the Document Portal for reset password, register etc.

If you intend to use the application with its app manager URL, then use the full URL (for example, https://api.kurtosys.app/applicationManager/apps/xxxxxxxx-xxxx-xxxxxxxx).

Note: You must partially complete this field at first, since the application GUID will not be created until the new application is saved.

If the application app manager URL has been mapped to an internal development/staging domain or the client’s production domain, then use that domain (for example, https://clientportal-dev.kurtosysweb.com, https://clientportal.someclient.com).

Domain URLs should NOT include a trailing slash.

 

Sender email address

The From email address used by the application manager service when sending out emails, for example when registering users.

Click Save.

Template Styles

Template Styles displays groupings of style options for Document Portal. Styles fall into 3 types:

 

Global

Styles that make up the base ‘theme’ used throughout the application.

Breakpoints, Space, Line Height, Font Size, Icon Size, Font Weight, Font Family, Radii, Color, Z Index, Shadow

 

Components

Styles for specific components in the application.

 

Other

Styles without any group set.

 

Usage

Styles can be text or numbers, multi-value text or numbers, or color pickers depending on how they have been setup in the application template.

Style options generally correspond to CSS properties, so a knowledge of CSS is recommended in order to set values correctly.

For example:

  • fontFamily settings would be a comma separated list of font names.
  • padding would be a number and unit such as 10px or 1em.
 

Responsive Styles

Multi-value component styles (arrays) are handled by the Document Portal application as responsive styles. Values are used in conjunction with breakpoints (see Global styles). Each value is applied at the breakpoints in order from smallest to biggest in a “mobile first” manor.

Example:

Given padding = [“10px”, “20px”, “30px”], and breakpoints “40em”, “52em”, “64em”:

  • 10px applies to viewport widths 0 to 40em
  • 20px applies to viewport widths 40em to 52em
  • 30px applies to viewport widths 52em to 64em (and over since it is the largest breakpoint)

We may not know ahead of time which component styles values should be responsive. So instead of having to redefine an application template style as an array we can use a pipe character “|” as a delimiter on text values which are then converted to an array by the application.

Example: padding = “10px|20px|30px”

 

Template Configuration

Template configuration is used to control various features and components of the Document Portal.

 

Portal Name

The name to be displayed on the login page and in the browser tab (page title).

If the name is not required on the login page it can be hidden by setting the style config for ***HeroHeading display*** to “none”.

 

API Token

An API user permanent token. This is used to request content from Commentaries and Disclaimers.

 

Router Base URL

If you intend to use the application with its app manager URL, then the router base URL should be set to the applicationManager path including the GUID of the app (for example: /applicationManager/apps/xxxxxxxx-xxxx-xxxxxxxx).

The router base URL should have a leading slash, but no trailing slash.

If the application app manager URL has been mapped to the root of a domain, then the router base url should be set to “/”.

 

Disclaimer Links

Disclaimer types of disclaimer content to be displayed as modal links in the footer area of the Document Portal.

It is recommended that disclaimer types used here are setup with friendly names, for example, “Privacy Policy” rather than “privacy_policy”. This is because the disclaimer type is used as link text to the content, and so will be visible in the Document Portal.

It is expected that there will only be one disclaimer per type. If there are multiple disclaimers only the first returned will be used. Disclaimers can have content in multiple cultures, but currently the application defaults to use ‘en-GB’.

 

Login Hero Content

A commentary type for content to display on the login screen “hero” area.

It is expected that there will only be one commentary for this type. If there are multiple commentaries only the first returned will be used. Commentaries can have content in multiple cultures, but currently the application defaults to use ‘en-GB’.

 

Assets

Document Portal has several assets described below which can be overridden to customise the application.

Assets can be overridden by an asset of any other name or type. For example, you may use MyBoldFont.woff to override HeaderFont.ttf, or MyBackground.jpg to override LoginBackground.svg.

 

Fonts

  • BodyFont.ttf
  • HeaderFont.ttf
  • The application includes @font-face rules for these fonts using the following names:
  • BodyFont
  • HeaderFont

You can use these font names in any style configuration for fontFamily.

 

Images

  • favicon.ico (icon displayed in browser tab)
  • HeaderLogo.svg (logo displayed in the header area)
  • LoginBackground.svg (full-screen background image displayed on the login page
  • LoginLogo.svg (logo displayed on the login page)
 
 

Email templates

Document Portal allows you to customise HTML email templates for an application instance.

You may use dynamic placeholders within the templates and subject line, such as {{userName}} and {{clientName}}, which are populated by the system when emails are sent.

The available templates are:

  • Account Locked
  • New Account
  • Password Reset
  • Password Reset Success
  • Saved Search Alert
  • Username Request
 
 

Roles & Permissions

In a template instance application Roles and Permissions are inherited from the Document Portal application template.

At the moment Document Portal does not make use of this feature.

 

Commentary and Disclaimer Setup

Before using Commentary and Disclaimer content in the Document Portal there are some setup steps to go through.

  1. In Data > Approval Groups, create Approval Group(s) containing users allowed to publish content for the Document Portal.
  2. In Settings > Data Dictionary, create a Commentary type for content to be used on the login page, and add the Approval group created in step 1.
  3. In Settings > Data Dictionary, create Disclaimer types for disclaimers to be used in the Document Portal, and add the Approval group created in step 1.

You will now be able to create and publish Commentaries and Disclaimers in Kurtosys.

Commentaries and Disclaimers do not need to be linked to an entity or segmentation list for use in the Document Portal.