Exact Synergy Enterprise

How-to: Configuring login configurations for portals

Introduction

To enhance the login experience for the system login, Exact Synergy Enterprise supports the login page with video background for the reseller, partner, and customer portals. The login page can be customized with a user-defined header text, background image, and/or background video. It is also possible to have a separate customization of the login page based on the domain, virtual directory name, and/or division.

Customization

Creating the Exact.Login.config file

The customization of the login page is specified by the text file “Exact.Login.config”. This file can be created using any text editor, such as Notepad, and this file must be stored in the XMD subfolder in the Exact Synergy Enterprise installation folder. As an example, see the following:

Once the file is created, use the text editor to edit the contents in the file, and customize the file based on the following sections.

Formatting Exact.Login.config file contents

The contents in the Exact.Login.config file contain a group of rules. Each rule is defined with a condition or group of conditions so that when the conditions are met, the customizations for the rules are applied. The structure of the file is as follows:

In the Exact.Login.config file, the structure is in the XML format, such as the following:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
   <rules>
     <rule>
       <conditions>
        <condition type="Domain" value="www.domain.com"></condition>
        <condition type="UrlParam" value="Division=001"></condition>
       </conditions>
       <customization>
        <header termid="0">Welcome to Domain dot com</header>
        <image>MyCustomImage.png</image>
        <video mp4="MyCustomVideo.mp4" ogg="MyCustomVideo.ogg" webm="MyCustomVideo.webm"></video>
        <credentials domain="exact-software" forgotPasswordLink="forgetpassword.html" requestPortalAccessLink="PortalAccess.html"</credentials>
       </customization>
     </rule>
    </rules>
</configuration>

Each <rule> node represents one rule, and can be repeated for the customization of different domains, virtual directories, and/or divisions.

Exact.Login.config XML template

The following blank template can be used to create or edit the Exact.Login.config file.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
   <rules>
     <rule>
       <conditions>
        <condition type="" value=""></condition>
        <condition type="" value=""></condition>
       </conditions>
       <customization>
        <header termid="0"></header>
        <image></image>
        <video mp4="" ogg="" webm=""></video>
        <credentials domain="" forgotPasswordLink="" requestPortalAccessLink=""></credentials>
       </customization>
     </rule>
   </rules>
</configuration>

Each section is explained in the following:

Section	Description
<?xml version="1.0" encoding="utf-8"?> <configuration> <rules> [rules here] </rules> </configuration>	The Exact.Login.config file should always contain this structure: The <?xml> element specifying that the contents are in XML. The <configuration> root element and a child <rules> element. All the configuration details (for example, rules) should be defined inside the <rules> element.
<rule> [rule definition here] </rule>	The <rule> element represents one rule definition, and can be repeated for many rules. The rule definition specifies the customizations that are applied when the conditions are fulfilled. Therefore, each rule should be defined with a set of conditions, and customizations using <conditions> and <customization> elements.
<conditions> <condition type="[condition type here]" value="[condition value here]"> </condition> </conditions>	The <conditions> element must be a child of the <rule> element, and it is the parent of one or more <conditions> elements. If more than one <conditions> is defined, all the conditions must be met for the rule to apply. Each <conditions> must be defined by a type and value attribute. The possible values for the type are: Domain VirtualDirectory URLParam
<condition type="Domain" value="[domain name]"> </condition>	To apply a rule when the login screen is located on a specific domain, use the <condition> element with the type="Domain". The value should be the name of the domain. For example, <condition type="Domain" value="www.joanne.com"></condition>
<condition type="VirtualDirectory" value="[virtual directory]"> </condition>	To apply a rule when the login screen is located on a specific virtual directory, use the <condition> element with the type="VirtualDirectory". The value should be the name of the virtual directory. For example, <condition type="VirtualDirectory" value="SynergyDev"></condition>
<condition type="UrlParam" value="Division=001"> </condition>	To apply a rule when the login screen is loaded for a specific division, use the <condition> element with the type="URLParam". The value should be in the format of Division=<division name>. For example, <condition type="UrlParam" value="Division=001"></condition>
<customization> <header termid="0"></header> <image></image> <video mp4="" ogg="" webm=""></video> <credentials domain="" forgotPasswordLink=""> </credentials> </customization>	The <customization> element must be a child of the <rule> element, and it is the parent of one or more customization element(s). This section specifies what will be customized on the login page when the condition(s) of the rule is(are) met. The possible customization elements are: <header> <image> <video> <credentials> Only one child element of each type is allowed in the <customization> element.
<header termid="0"> [custom header text here] </header>	To customize the header of the login screen, use the <header> element, and specify the header text within the element. For example, <header termid="0">Welcome to Domain (dot) com</header>
<image> [image filename here] </image>	To customize the background image of the login screen, use the <image> element, and specify the filename of the image. For example, <image>MyCustomImage.png</image>
<video mp4="[mp4 filename here]" ogg="[ogg filename here]" webm="[webm filename here]"> </video>	To customize the background video of the login page, use the <video> element, and specify the filename(s) of one (or more) of the supported video formats in the respective attributes, for example, mp4, ogg, webm. If more than one file type is specified, the system will select the file in this order, MP4 > OGG > WEBM. For example, <video mp4="MyCustomVideo.mp4" ogg="MyCustomVideo.ogg" webm="MyCustomVideo.webm"></video> OR <video mp4="MyCustomVideo.mp4"></video>
<credentials domain="[domain here]" forgotPasswordLink= "[forget password link here]" requestPortalAccessLink="[link to request for portal access here]"> </credentials>	To customize the domain name that will be prefixed to the username on the login page, use the <credentials> element and the domain attribute. To display a “Forgot your password?" hyperlink on the login page that will redirect to a specified forgot password page, use the <credentials> element and the forgotPasswordLink attribute. The value should specify the URL / link to the forgot password page. To display a “No access yet? Request here!” hyperlink on the login page that will redirect to a specified request for portal access page, use the <credentials> element and the requestPortalAccessLink attribute. The value should specify the URL / link to the request for portal access page. For example, <credentials domain="exact-software" forgotPasswordLink="forgotpassword.html" requestPortalAccessLink="PortalAccess.html"></credentials>

Behavior and limitations

Order and precedence of the rules

The rule conditions are evaluated based on the order they are listed in the Exact.Login.config file, and only the first rule whereby the conditions are met, will be applied to the login page. Thus, once a condition is met, the customizations of the rule will be applied, and all the other rules will be ignored. Therefore, the rules should be listed from specific to generic.

Based on the following example, Rule 1 is evaluated first. If the condition is met, Rule 1 will be applied. Otherwise, if the condition is not met, Rule 2 will be evaluated, and so on.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
   <rules>
     <!—Rule #1: Applied when domain = www.domain.com and URL is login.aspx?Division=001-->
   <rule>
     <conditions>
      <condition type="Domain" value="www.domain.com"></condition>
      <condition type="UrlParam" value="Division=001"></condition>
     </conditions>
     <customization> [...customizations here...] </customization>
   </rule>
<!—Rule #2: Applied when domain = www.domain.com -->
   <rule>
    <conditions>
      <condition type="Domain" value="www.domain.com"></condition>
    </conditions>
    <customization> [...customizations here...] </customization>
   </rule>
  </rules>
</configuration>

Based on the following example, the order of these rules is wrong as Rule 2 will never be applied because Rule 1 will be evaluated first, and it is more generic.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
   <rules>
     <!—Rule #1: Applied when domain = www.domain.com -->
     <rule>
      <conditions>
        <condition type="Domain" value="www.domain.com"></condition>
      </conditions>
      <customization> [...customizations here...] </customization>
     </rule>
   <!—Rule #2: Applied when domain = www.domain.com and URL is login.aspx?Division=001 -->
   <rule>
     <conditions>
      <condition type="Domain" value="www.domain.com"></condition>
      <condition type="UrlParam" value="Division=001"></condition>
     </conditions>
     <customization> [...customizations here...] </customization>
   </rule>
   </rules>
</configuration>

Public user access rights

The public user rights are needed for the login page. Ensure that ExactWebGuest is in the Exact Synergy Enterprise database. For more information, see How-to: Configuring Information Internet Services (IIS) for portals.

Custom background image and video files

The background images and video files should be placed in the “<SynergyInstallationFolder>\docs\login” location.

Note: If the customization is defined in the configuration file but the image, or video file cannot be located in the login folder, the login page will be displayed as a blank white page.

Forget password link

By default, the link to the forget password page is relative to the “<SynergyInstallationFolder>\docs\login” location. This means that the physical file for the password page can be placed in this folder and only the filename needs to be specified in the customization file.

For example, if forgotpassword.html was created and used, the following configuration will display a link that redirects to http://<Synergy domain>/docs/login/forgotpassword.html

<credentials forgotPasswordLink="forgotpassword.html"></credentials>

Alternatively, it is possible to specify a full URL path to the created file. For example,

<credentials forgotPasswordLink="http://domain/path/forgotpassword.html"></credentials>

The link to the forget password page can point to a landing page or directly to a recovery page.

For example, to link the forget password page to a landing page, the URL will be:

<credentials forgotPasswordLink="forgotpassword.html"></credentials>

For example, to link the forget password page directly to a recovery page (including the relative path), the URL will be:

<credentials forgotPasswordLink="../SysPasswordRecovery.aspx"></credentials>

For example, to link the forget password page to a recovery page using the full path, the URL will be:

<credentials forgotPasswordLink="http://domain/docs/SysPasswordRecovery.aspx"></credentials>

Request for access link

A link where users can request access to the portal can be specified. This will redirect users to a page where they can provide details for their request to access the portal.

The landing page should be placed in the “<SynergyInstallationFolder>\docs\login” folder. To enable this feature, the requestPortalAccessLink attribute is used as part of the credentials element.For example, the following configuration will display a link that redirects to http://<Synergy domain>/docs/login/PortalAccess.html

<credentials requestPortalAccessLink="PortalAccess.html"></credentials>

Note: If the attribute is not specified, the request for access link will not be displayed in the login page.

Supported file formats

The supported file format for the background images is .PNG. The supported file formats for the background videos are .MP4, .OGG, and .WebM.

Default background and videos

If the Exact.Login.config file is removed or not created, the default background image and video of Exact Synergy Enterprise will be used on the login page.

Note:

If you only want to use the background image, the rule should contain an empty <video></video> tag. This will overwrite the defaults.
If you want to use both the background image and video, use the first scene from the video as the background image because if the image is available, it will be loaded behind the video.

Logging out

The customizations described in this document are only applicable to the login page. Logging out from the portal will always redirect the user to the standard portal login page on the same domain or virtual directory.