LORENZ Foundation Administrator Guide

Administrator Guide
Foundation 20.2
October 2020
© LORENZ Life Sciences Group
© LORENZ Life Sciences Group
Administrator Guide Foundation 20.2
Table of Contents
Table of Contents .................................................................................................................. 2
Disclaimer ............................................................................................................................. 6
1. Introduction .................................................................................................................... 7
1.1 How this guide is organized..................................................................................... 7
1.2 General system architecture.................................................................................... 7
1.3 Utilities for Administrators ........................................................................................ 8
1.3.1 LORENZ adminPanel ....................................................................................... 8
1.3.2 LORENZ configPanel ....................................................................................... 9
2. Installation .....................................................................................................................11
2.1 General Installation Principles ................................................................................11
2.2 Installing the LORENZ Foundation .........................................................................11
2.2.1 Preparatory Work ............................................................................................11
2.2.2 Installing a Foundation server .........................................................................12
2.2.3 Upgrading a Foundation server .......................................................................13
2.2.4 Silent Installation possibilities ..........................................................................13
2.3 Database................................................................................................................14
2.3.1 Database conceptual overview........................................................................15
2.3.2 Database setup ...............................................................................................17
2.3.3 Manage application user security / Create application user .............................19
2.3.4 Upgrade an existing Database ........................................................................20
2.3.5 The LORENZ dbaPanel ..................................................................................20
2.4 Certificates .............................................................................................................23
2.4.1 Certificate creation ..........................................................................................23
2.4.2 Certificate deployment.....................................................................................24
2.4.3 Certificate ranges of use .................................................................................24
2.4.4 Certificate creation ..........................................................................................28
2.5 Service and client connectivity ...............................................................................30
2.5.1 user_login.xml .................................................................................................31
2.5.2 Using Windows Authentication for a Client ......................................................32
2.5.3 Disable 'Use Windows Authentication' on logon screen...................................33
3. License Management ....................................................................................................34
3.1 License overview....................................................................................................34

3.2 Installing licenses with the configPanel ..................................................................34
3.3 Viewing licenses with the adminPanel ....................................................................35
3.4 License expiration notification ................................................................................36
4. Settings .........................................................................................................................37
4.1 General Settings ....................................................................................................37
4.1.1 Logging ...........................................................................................................37
4.1.2 Login ...............................................................................................................37
4.1.3 Network Authentication ...................................................................................38
4.1.4 OpenID Connect .............................................................................................39
4.1.5 Password Policy ..............................................................................................39
4.1.6 SAML 2.0 ........................................................................................................40
4.1.7 System E-Mail Account ...................................................................................40
4.1.8 Web Hosting ...................................................................................................41
4.2 Product settings .....................................................................................................42
5. Configuration .................................................................................................................43
5.1 Export-/Import Packages ........................................................................................43
5.2 Files .......................................................................................................................44
5.3 Product configurations............................................................................................45
6. Monitoring & Controlling the System .............................................................................46
6.1 System Sessions overview .....................................................................................46
6.2 User Sessions overview .........................................................................................46
6.2.1 Log-off an active user ......................................................................................47
6.3 Session Log ...........................................................................................................47
6.4 Version check.........................................................................................................48
6.4.1 Version check using the configPanel ...............................................................48
6.5 Starting/Stopping services in configPanel...............................................................48
6.6 Starting/Stopping services in Windows MMC .........................................................50
6.7 Event Subscriptions................................................................................................50
6.7.1 Event Codes ...................................................................................................52
6.8 Sending Notifications to Users ...............................................................................52
6.9 Logging ..................................................................................................................53
6.9.1 LORENZ Log Files ..........................................................................................53
6.9.2 Client-Side Logging .........................................................................................54

6.9.3 Event Log (adminPanel) ..................................................................................54
6.9.4 SQL Tracing ....................................................................................................56
6.10 Creating a System Snapshot ..................................................................................56
7. User Management .........................................................................................................58
7.1 Managing User Accounts .......................................................................................58
7.1.1 User List Filtering ............................................................................................58
7.1.2 User List Grouping ..........................................................................................60
7.1.3 Adding new user accounts ..............................................................................61
7.1.4 Cloning existing user accounts ........................................................................62
7.1.5 Modifying user accounts..................................................................................62
7.1.6 Deleting user accounts ....................................................................................62
7.1.7 Restoring deleted user accounts .....................................................................63
7.1.8 Unlocking user accounts .................................................................................63
7.1.9 Resetting user passwords ...............................................................................63
7.1.10 Resetting the ADMIN User Account ................................................................64
7.2 Managing User Roles .............................................................................................64
7.2.1 Adding new user roles .....................................................................................65
7.2.2 Modifying existing user roles ...........................................................................65
7.2.3 Deleting user roles ..........................................................................................66
7.2.4 Restoring deleted user roles............................................................................66
7.2.5 General Functions ...........................................................................................66
7.3 Managing User Groups ..........................................................................................67
7.3.1 Adding new user groups..................................................................................67
7.3.2 Modifying existing user groups ........................................................................68
7.3.3 Deleting user groups .......................................................................................68
7.3.4 Restoring deleted user groups ........................................................................68
7.4 Audit Trail ...............................................................................................................69
7.5 Reporting ...............................................................................................................69
7.6 User Authentication Options ...................................................................................70
7.6.1 Foundation ......................................................................................................70
7.6.2 Network ...........................................................................................................70
7.6.3 SAML 2.0 ........................................................................................................72
7.6.4 OpenID Connect .............................................................................................74

7.7 Single Sign On (SSO) ............................................................................................76
7.7.1 LORENZ Single Sign On (SSO) Login ............................................................76
7.7.2 Single Sign On (SSO) across domains ............................................................77
7.8 Password Policy .....................................................................................................78
7.9 User Authorization ..................................................................................................79
7.10 User Licenses ........................................................................................................79
8. RESTful Application Programming Interface (API).........................................................80
8.1 Authentication ........................................................................................................80
9. Additional Information ....................................................................................................82
9.1 Service Ports ..........................................................................................................82
9.1.1 Port List ...........................................................................................................82
9.1.2 Port Sharing ....................................................................................................82
9.2 Server discoverability .............................................................................................83
10. Troubleshooting .........................................................................................................84
10.1 None of the services can be started .......................................................................84
10.2 Cannot install license with configPanel ...................................................................84
10.3 Service Session Timeouts ......................................................................................84
10.4 Performance issues in disconnected environments ................................................85
Disclaimer
© 2020 LORENZ Life Sciences Group
All rights reserved in whole or in part and in all forms of media throughout the world. Any
rights not expressly granted herein are expressly reserved by LORENZ Life Sciences Group.
All information and articles in this document are covered by copyright law. Articles and
documents contained in this document are the copyright of LORENZ Life Sciences Group.
Any commercial reproduction of any material included here is expressly prohibited.
Except as stated above, no part of this document may be reproduced, stored in a retrieval
system, or transmitted in any form, or by any means, electronic, mechanical, photocopying,
recording or otherwise, without prior written permission of LORENZ Life Sciences Group, or
the respective copyright owner.
Copyright includes the use of any underlying hypertext markup used in the creation of this
document.
All trademarks, service marks and logos (trademarks) of companies and products mentioned
or used in this document are the property of their respective owners.
Trademarks
The following trademarks of other companies may appear in this document:
Microsoft is a registered trademark of Microsoft Corporation in the United States and/or other
countries
Microsoft Windows, Microsoft Windows Vista and Microsoft Windows 7 are registered
trademarks or trademarks of Microsoft Corporation in the United States and/or other
countries.
Acrobat is a trademark of Adobe Systems Inc.
All other names of products or companies mentioned in this document are trademarks or
registered trademarks of their respective owner.
© LORENZ Life Sciences Group 6

1. Introduction
This guide will help you with all tasks related to installing, configuring and monitoring a
system based on the LORENZ Foundation.
The reader should ideally have a fair knowledge of the following technologies to benefit most
of the covered topics:
• Administration of Microsoft Windows operating systems (both server and client side)
• Microsoft SQL Server, ORACLE or PostgreSQL database administration
• Internet Information Services administration
• Certificate handling
• Active Directory and LDAP
1.1 How this guide is organized

This guide has been prepared focusing on the main tasks and typical activities of a
Foundation system administrator. Instead of describing the available tools and utilities
feature by feature, the documentation provides context-oriented help. The available functions
and features will be described wherever this is necessary to solve a specific problem or
execute a concrete task. While you can read this guide from first to last page, it will also be
useful as a reference handbook.
1.2 General system architecture

The LORENZ Foundation services and applications are the infrastructural base layer on
which the other LORENZ products are built upon. The Foundation layer exposes the
following shared features to all components:
• Authentication of users and system components

• Authorization of users
• Licensing and user session management
• Centralized configuration for communication between services and clients
• Database configuration, maintenance and monitoring
• Administrative tools to configure all these features
The LORENZ Foundation distinguishes between three different machine roles:
Primary Server Hosting the CoreServices and configuration data

Extension Server Hosting server components like the Job Service or web applications, that are not
installed on the primary server to realize load balancing
Client Hosting client applications like the docuBridge Explorer
Table 1-1

The roles can be combined according to the individual needs. Theoretically it is possible to
have an all in one machine, hosting all roles together on a single machine. Due to
performance reasons this is not recommended. Each system instance needs a dedicated
machine as a primary server, it’s not possible to run multiple CoreServices on the same
machine.
1.3 Utilities for Administrators

The most important utilities are the LORENZ adminPanel and the LORENZ configPanel.
Note that throughout this guide, the LORENZ prefix will be omitted when referring to these
programs.
1.3.1 LORENZ adminPanel
The adminPanel is a web application, hosted by Microsoft Internet Information Server (IIS).
On the server computer, you'll find a desktop shortcut for accessing the adminPanel.
Alternatively, or from any other computer, use the following address in your browser to
access it:
• http://MY_APPLICATIONSERVER/lorenz.adminPanel
Where “MY_APPLICATIONSERVER” is the name or IP address of the application server

hosting the LORENZ Foundation.
When you call up the adminPanel, you will be directed to the login page as shown on the
next picture.
To log on, use an account with enough privileges such as “ADMIN”. On a new system
installation, the ADMIN account has already been prepared for access to the adminPanel
and the password has been set to a default that needs to be changed upon first logon.
After a successful logon, you will be directed to the start page of the application. On the left-
hand side, you find the navigation menu. In the upper right corner, the name of the logged in
user is shown next to a hyperlink, where you can logoff when you have completed your work.

Figure 1-1
The adminPanel menu structure is:
• Monitoring
• Messaging
• User management
• Additional product related items, e.g. docuBridge or drugTrack
Depending on the authorization of the user, one or more navigation items might be disabled.
1.3.2 LORENZ configPanel
The configPanel is a Windows application that is installed by default on the server computer
only. You will find a configPanel shortcut icon on the desktop.
The configPanel application needs administrative permission when executing. Therefore, the
user executing the configPanel needs to have administrative rights.

Figure 1-2
The configPanel can be used for the following tasks:
• Initial configuration of the system after installation.

• Starting and stopping the LORENZ services.
• Checking if the system configuration is valid.
• Modifying system parameters (including licenses) as part of system maintenance.
• Generating and archiving a report as part of an installation qualification (IQ) process
to document evidence for a successful system installation and configuration.
• Creating a snapshot of the Foundation application server that includes for example
configuration files and application logs etc. (see section 6.10).
• Viewing of log files.
• Backup and restore of user configuration files.
• Update system configuration files out of the standard release scope.
For now, we will not go into detail for the different configuration dialogs. Instead, we will
explain them as part of the corresponding administrative tasks.

2. Installation
This section describes the installation of LORENZ Foundation. It has been written with the
intention to provide an experienced administrator with the required steps to install or update
a system running LORENZ Foundation.
This section has not been written as a template for any installation plan or installation protocol
as required by installation of validated computer systems.
2.1 General Installation Principles

The Foundation installer is always a “full installation package” – meaning it contains the
entire application (no matter if it is a Standard Release or a Specific Release).
2.2 Installing the LORENZ Foundation

This section will guide you through the necessary steps to install or upgrade and configure a
Foundation server. At the end of this section, you will have an overview of the process as
such and you will be able to see where required and optional steps fall into place and why.
This section is not intended to give a step-by-step instruction on how to perform the
installation and configuration. It is expected that the target audience – experienced
Foundation Administrators – are familiar with the software and the handling of the software to
understand how to perform the described actions.
2.2.1 Preparatory Work
Prior to the actual installation of the application software, a few preparatory actions are
making the process easier.
2.2.1.1 Availability of Installation Sources
The availability of the installation sources either on an easily accessible network drive or in
some local temporary directory is a pre-requisite for seamless installation.
2.2.1.2 Locations for Binaries and Shared Data
Prior to the installation and configuration, it is good practice to define where data will be
located (e.g. “Shall the application be installed into the default Program Files directory or is
another location required?”).
2.2.1.3 Database Availability
To make the configuration more smoothly, it is suggested to ask the responsible database
administrator to create and initialize the Foundation Database and the DB users before the

installation is taking place. If the database is not available beforehand, the installation and
configuration can only go so far without it.
2.2.1.4 Database Connectivity
Mentioned in the System Requirements, systems which are operating their database on an
ORACLE Server require the appropriate Oracle Instant Client installed for Microsoft .Net
Framework 4 to be available and configured on the server.
• ORACLE Data Access Components (ODAC) for .Net 4
2.2.1.5 Operating System Prerequisites
As mentioned in the System Requirements Document, the operating system of the

designated Foundation server needs to meet certain requirements – namely, the Internet
Information Server together with the Application Request Routing module and the URL
Rewrite module must be installed to properly install the system.
It should also be considered to provide a reasonable amount of CPU power and main
memory to the system, especially in virtualized environments.
Finally, the operating system should have been updated to the latest patch level using either
the Windows Update mechanism or a corporate standard. LORENZ is suggesting to not
leaving the server operating system in a state where it is allowed to download and install new
patches itself. For more details please refer to the LORENZ System Requirements
Specification.
2.2.1.6 Availability of Account Information
Finally, the availability of all required accounts and the knowledge of the account passwords
is good preparation for a seamless installation and configuration:
• User with administrator privileges for the installation
2.2.2 Installing a Foundation server
To install the Foundation server, perform the following steps:
1. Launch the Foundation Installer and install the required components.
It is possible to create a log-file while installing the Foundation. Therefore, the installation
msi file has to be executed from the command prompt using the following syntax:
[PathToSetup]\"Lorenz Foundation.msi" /l installlog.txt
2. Configure the configPanel’s “Settings” section as required

3. Configure the Database Connectivity using the configPanel.

The Foundation Database must be available and properly configured at this time. If it is not,
you will not be able to continue with this script beyond this point.
4. Use the configPanel’s “License” feature to obtain your Hardware Key and install the
new license delivered to you.
5. Start the LORENZ Services.
6. Please perform a Validation using the configPanel’s “Validation” feature. Correct
the errors if necessary and then continue.
2.2.3 Upgrading a Foundation server
To upgrade a Foundation server, perform the following steps:
1. Stop all LORENZ services via the configPanel.

2. Launch the Foundation installer and install the required components. The setup will
automatically backup and restore the user configuration files while the installation is
performed.
3. Once the installation has been performed, please verify the configuration files that
were restored via the setup.
4. Please verify the configPanel’s “Settings” section.
5. Please determine if your database schema needs an update.
The Foundation Database must be available and properly configured at this time. If it is not,
you will not be able to continue with this script beyond this point.
6. Perform a “Validation” from the configPanel and check for errors that need to be
resolved before proceeding
7. Start the LORENZ Services.
Depending on the type of upgrade, your existing license may cease to work. In such case no
services will start. You can obtain a new license from LORENZ by sending in your existing
license file and the Hardware Code of the application server.
2.2.4 Silent Installation possibilities
A silent Installation does not display messages or windows during its progress. It has
received all necessary input prior to the start of installation. Such input may be in the form of
command line switches or an answer file, a file that contains all the necessary parameters.
Parameter Description Value

INSTALLDIR Defines the install location of e.g.
Foundation. “c:\Lorenz Life Sciences\Foundation”
Default is the ProgramFiles folder.

Parameter Description Value

ADDLOCAL Defines the components which ALL
should be installed by the installer. SVC_Foundation
A comma-separated list of features adminPanel
to install locally. webLogin
“ALL” installs all features. windowsLogin
Table 2-1
2.2.4.1 Installation example
msiexec /i "C:\Install\Lorenz Foundation.msi" ADDLOCAL=ALL

ALLUSERS=1 /q /l "log_server.txt"
Code 2-1
2.2.4.2 Uninstallation example
msiexec /x "C:\Install\Lorenz Foundation.msi" /q /l

“log_uninstall.txt”
Code 2-2
2.2.4.3 Upgrade installation example
msiexec /i "C:\Install\Lorenz Foundation.msi" ALLUSERS=1

/q /l "log_server.txt"
Code 2-3
For further information about silent and unattended installations please refer to Microsoft
Online Reference about MSI.
2.3 Database
This section will guide you through the initialization of a new Foundation Database or the
steps required upgrading an existing Foundation Database to the current release.
Prior to the actual initialization or upgrade procedure, please verify the following information
is available to you:
• A database user with appropriate permission to create and alter the database
(typically a DBA user).
• When upgrading, determine the existing database schema version from either the
Release Configuration Sheet or from the database directly.
• When upgrading, ensure that you have a backup of the database prior to performing
any upgrade steps.

LORENZ provides scripts to create or upgrade a database schema through the installation
package. These scripts are located in the Database folder of the installation package. The
following sections explain what needs to be done to prepare the database setup and what is
preconfigured by LORENZ through the database scripts but can be adapted for customer
needs.
2.3.1 Database conceptual overview
• Microsoft SQL Server

• Oracle Database
• PostgreSQL
For detailed information about supported versions please refer to the System Requirements
Specification document.
General
Figure 2-1
The LORENZ Services are using a dedicated application user to access the database. This
user is assigned to the role “LORENZ_SYSTEM” which has all needed access rights for the
schema FOUNDATION. This user cannot be used to administer the database.
Please note that for a PostgreSQL database no “LORENZ_SYSTEM” role is created. The
user who is database owner can directly be used as application user to access the database.

Microsoft SQL Server
Figure 2-2
Oracle
Figure 2-3

PostgreSQL
Figure 2-4
2.3.2 Database setup
General steps
1. Create database instance (manually)

2. Create and populate schema (script driven)
3. Manage application user security / Create application user (manually)
2.3.2.1 Create database instance
A dedicated database instance (Oracle) or MsSql/PostgreSQL Catalog is needed per

application instance.
Microsoft Sql Server
For MsSQL the “Snapshot Isolation” must be enabled. This could be done by running the
script 'MsSql_configure.sql' from the foundation database creation scripts to enable snapshot
isolation. You need to be the only single DB user when executing this script.
Oracle
For Oracle no special database features are needed.
PostgreSQL
For PostgreSQL also no special database features are needed.
2.3.2.2 Manually create schemas
All scripts delivered with the Foundation will create all necessary schemas (FOUNDATION
and e.g. DOCUBRIDGE) if they don’t already exist.

Usually you can use the provided scripts without modifications for the database set-up. If you
need to adapt the preconfigured create-script to your needs, please find below a short
explanation.
For MsSQL Server there are no specific options when creating a schema.
Oracle
For Oracle a schema corresponds to a user who owns the schema with the same name.
1. The schema owner needs enough quota on the tablespace(s) to which its tables
belong.
2. The schema owner should not be assigned to any role and the only system
privileged it may have is 'unlimited tablespace'.
3. Because of (2) the schema owner is not able to connect to the instance (no 'create
session' privileged) and therefore the password is just a dummy.
Example 1 – Provided scripts:
CREATE USER FOUNDATION IDENTIFIED BY PASSWORD;

GRANT UNLIMITED TABLESPACE TO FOUNDATION;
Code 2-4
Example 2 – Customization depending on e.g. password policies etc.:
CREATE USER FOUNDATION IDENTIFIED BY MygoP201! DEFAULT

TABLESPACE LORENZ TEMPORARY TABLESPACE TEMP QUOTA
UNLIMITED ON LORENZ;
Code 2-5
The create and upgrade scripts are designed in the way that the schema will be created like
in example 1 if it does not already exist.
The admin may still create the schema owners with different tablespace and quota setups if
needed.
PostgreSQL
For PostgreSQL Server there are no specific options when creating a schema.
2.3.2.3 Create and populate schemas
The schema will be created and populated automatically when running the provided create
and upgrade scripts.
• The scripts need to be executed by a Database Administrator (DBA User)

• Please always create/upgrade the FOUNDATION schema first and then

FOUNDATION
The following scripts are delivered with the installation package:
• MsSql_foundation_create.sql
Oracle
• Oracle_foundation_create.sql
PostgreSQL
• Postgres_foundation_create.sql
2.3.3 Manage application user security / Create application user
The create and upgrade scripts delivered with the installation package create a dedicated
role (LORENZ_SYSTEM) for the application user and grant all needed privileges to this role.
The only thing left is to create a dedicated application user e.g. LORENZ and assign the role
LORENZ_SYSTEM.
1. The application user must be able to connect to the database instance / 'create
session' privileged. Because of that its credentials (e.g. password) are security
critical.
2. The application user must be granted access to all LORENZ application schemas
(FOUNDATION, DOCUBRIDGE, ...)
SQL Server
Create an application user called LORENZ and assign the LORENZ_SYSTEM role:
USE [master]
GO
CREATE LOGIN [LORENZ] WITH PASSWORD=N'Secret'
GO
USE [Database]
GO
CREATE USER [LORENZ] FOR LOGIN [LORENZ]
GO
USE [Database]
GO
ALTER ROLE [LORENZ_SYSTEM] ADD MEMBER [LORENZ]
GO
Code 2-6
Oracle

Create an application user called LORENZ and assign the LORENZ_SYSTEM role:
CREATE USER LORENZ IDENTIFIED BY <Secret>;

GRANT LORENZ_SYSTEM TO LORENZ;
ALTER USER LORENZ DEFAULT ROLE LORENZ_SYSTEM;
Code 2-7
2.3.4 Upgrade an existing Database
If the current database schema version differs from the database schema version expected
by the release you are installing, you need to upgrade the database schema manually or by
using the dbaPanel as described in 2.3.4.
Manually
To do this, please
• Locate the schema update scripts (provided with the installation package of the
Foundation Server)
• Execute the scripts required, starting from the
o RDBMS_Foundation_upgrade_[current schema]_to[…].sql to the
If you have been skipping versions of Foundation, you may have to execute multiple scripts.
• When using MS SQL Server, it is important to run these scripts either using the
sqlcmd.exe utility or – when using the SQL Server Management Studio – in SQL
Command Mode.
• When using ORACLE, you can use e.g. SQL Plus to execute the script(s).
• When using PostgreSQL, you can use e.g. psql or pgAdmin.
2.3.5 The LORENZ dbaPanel
The Foundation comes with a tool named LORENZ dbaPanel that can be used to do certain
tasks to administer the database that is used for the Foundation.
The LORENZ dbaPanel can be used to perform database related tasks like upgrade the
schema after an update installation of the software or validate the current database schema.
Location:
• C:\Program Files (x86)\Lorenz Life Sciences\Foundation\dbaPanel\

o Application: Lorenz.DbaPanel.exe
o Configuration: Lorenz.DbaPanel.exe.config
In order to get all functionalities of the dbaPanel running, there are some prerequisites
needed that need to be installed and configured in the “Lorenz.DbaPanel.exe.config”:
• Oracle DB: Oracle commandline tool SQLPlus

• MS SQL DB: MS SQL commandline tool SQLcmd

• PostgreSQL DB: PostgreSQL commandline tool psql
• WinMerge
2.3.5.1 Connections
To use the dbaPanel with an existing database, the first step is to create and configure a
connection to this database.
To create and configure a new connection, you can use the default connection that is already
displayed in the left navigation pane (New connection) and rename it. To create an additional
connection press “insert” on your keyboard or copy an existing connection using the context
menu by pressing the right mouse button. To configure the connection, please do the
following steps:
1. Select the Provider (MsSql, Oracle or Postgres)

2. Define a Connection Name
3. Define the database source
4. Enter the user to access the database
You can test your configuration by pressing the arrow left to the connection name in the
navigation pane. The dbaPanel now tries to connect to the configured database and retrieve
all relevant data. In case the connection was successful, the dbaPanel displays the
dedicated schema with its tables, Stored Procedures and Functions.
To edit an existing connection just modify the configuration of the connection in the right
pane. There is no save needed, just refresh the connection in the navigation pane.
To delete a connection, use the context menu via right mouse click on the connection in the
navigation pane.
2.3.5.2 Schema
There are different schemas available:
Schema name LORENZ Product
FOUNDATION Foundation
DOCUBRIDGE docuBridge
dbo drugTrack
EVALIDATOR eValidator
AUTOMATOR Automator
Table 2-2

2.3.5.2.1 Upgrade an existing schema
To upgrade an existing schema version, expand the connection and perform a right click on
the dedicated schema e.g. Foundation and select “Upgrade schema version”. The latest
schema version is automatically selected. Click “ok” and the upgrade is executed. The
connection tree refreshes automatically after the upgrade has finished.
It is also possible the recreate all code objects like Stored Procedures from the template by
selecting “Recreate code objects” in the context menu of a schema node.
2.3.5.2.2 Dump and restore a schema
It is also possible to dump and restore an existing schema to or from a file. This dump can
only be restored with the dbaPanel because it is a proprietary format.
To dump a current schema select it in the navigation tree, right click and select “Dump
schema to file”. After selecting the store location click “ok” and the dump will be created.
To restore a dump to an empty schema, select the schema, right click and select “Restore
schema from file”. In the following dialog you will a summary of the dump including the
schema version. During the restore process you can also select for which schema version
the dump should be restored. Click on restore to start the process.
2.3.5.2.3 Validate a schema
To check if the current database schema is valid, the dbaPanel provides the possibility to
validate the current schema against a template. Therefore, you need to right click on the
schema in the left navigation tree and select “Validate schema”. If the current schema has no
differences to the expected schema template the message “Schemas are identical” will be
displayed. In case there are differences, the result dialog displays a summary. It is possible
to display the deviations by using the “Compare in WinMerge” button.
Schema was extended
Schema was altered
Schema was reduced. Items are missing.
Table 2-3
2.3.5.2.4 Browse through a schema
To view the schema or included tables and stored procedures please use the left navigation
tree. When opening an existing connection, the dbaPanel automatically retrieves the schema
data and validates the schema against the template of the dedicated system version. If the
schema is displayed with a green cube everything is fine. A yellow cube means that there are
differences to the schema template. In that case please use the validate schema function to
investigate the details.

Schema not loaded
Schema valid
Schema invalid
Table 2-4
2.4 Certificates
The LORENZ application infrastructure is based on SOAP and REST services. The
connections in between services and clients are secured using X.509 certificates. The
following section assumes that you are familiar with the basic principles and terminologies.
2.4.1 Certificate creation
The certificates need to be created / issued by the customer. Usually the customer should be
familiar with issuing certificates and will have at least one server acting as a certificate
authority in their domain (e.g. Active Directory Certificate Services). For all other customers,
LORENZ provides the possibility to create self-signed certificates during the installation
process (see 2.4.4).
There are no special recommendations or requirements on a certificate to use it with the

LORENZ software. Besides the fact that the certificate should be valid, LORENZ
recommends a secure signature algorithm like SHA256 or higher along with a public key
length of at least 2048 bits. Any further requirements derive from their range of use and will
be described there.

Figure 2-5
2.4.2 Certificate deployment
The certificates need to be deployed to all servers hosting the LORENZ services (including
Extension Servers). This can be accomplished by using group policies or installing them
manually on each server. If you need to deploy the certificates manually, you can use the
certificate snap-in of the Microsoft Management Console.
All certificates need to be installed including their private keys in the ‘Personal’ store of the
‘Local Computer’. If the certificates are self-signed, they also need to be added to the
‘Trusted Root Authorities’ store of the ‘Local Computer’. The private keys need to be
accessible by the accounts that are used for the LORENZ services and web applications. For
the SOAP service and the client certificate the private key access is automatically granted to
the services when selecting the certificate in the configPanel.
2.4.3 Certificate ranges of use
2.4.3.1 SOAP service certificate
This certificate needs to be deployed to all LORENZ primary and extension servers. It serves
the following purposes:
• Authenticate a service towards a client: A fat client like the docuBridge Explorer or
another service acting as a client will validate the service identity using this certificate.
• Enrcypting TCP connections using TLS (Transport Layer Security) 1.2 between
service and client, as well as between two LORENZ Software Product services.
The enhanced key usage attribute of the certificate should include ‘Server Authentication’:

Figure 2-6
The certificate needs to be selected in the configPanel > Certificates > Service certificate.
Changing the certificate affects all login configuration files, which need to be redeployed to
the extension servers and client machines in that case.
2.4.3.2 SOAP client certificate
This certificate needs to be deployed to all LORENZ primary and extension servers. It serves
the following purposes:
• Authenticate a system service as a client to the LORENZ CoreServices when

establishing a system session.
• Encrypt security relevant information in the user configuration files located on the
primary server like passwords for the database, the CMS systems or the system
email account.
The enhanced key usage attribute of the certificate should include ‘Client Authentication’:

Figure 2-7
The certificate needs to be selected in the configPanel > Certificates > Client certificate.
Changing the certificate affects the system login configuration file, which needs to be
redeployed to all extension server machines. If an older certificate shall be replaced by a
newer one, the old certificate needs to remain in the certificate store until the newer one has
been selected and saved in the configPanel. Otherwise all encrypted entries in the
configuration files cannot be decrypted with the old certificate before they get encrypted
again with the new certificate.
2.4.3.3 IIS server certificates
An IIS server certificate is used to authenticate a web application towards a client and to
establish a TLS connection (https) between both.
Additional requirements:
• Enhanced key usage should include ‘Server Authentication (1.3.6.1.5.5.7.3.1)’

• The common name of the subject or one of the DNS names of the ‘Subject
Alternative Name’ property need to match the address of the web application.

Figure 2-8
To configure IIS to use https connections for the LORENZ web applications, follow these
steps:
1. Create a certificate that fulfills the requirements mentioned above. Customers can
use the certificate that can be created during the Foundation setup (see 2.4.4.1) or
via the LORENZ Certificate Utilities (see 2.4.4.2).
2. Open the Internet Information Services (IIS) Manager.
3. In IIS Manager, in the Connections menu tree (left pane), locate and click the
server name.
4. In the center pane, in the IIS section, double-click Server Certificates.
5. In the Action pane on the right, click Import.
6. Select the Certificate file (.pfx) and enter the password. Click the OK button.
7. In the Connections menu, expand the name of the server. Then expand Sites and
click the site (in most cases Default Web Site) that should be secured with the SSL
certificate.
8. In the Action pane on the right, click Bindings.
9. In the Site Bindings window, click Add.
10. In the Add Site Bindings window, do these steps:
o Type: In the drop-down list, select https.

o IP address: Select the IP address of the site or select All Unassigned.
o Port: Enter the port 443.
o SSL certificate: Select the certificate that has been imported in step 5 from the
drop-down list.
o Click the OK button.

11. The new https binding should now be displayed in the Site Bindings window.
12. Restart the IIS.
13. Open the LORENZ configPanel and navigate to Settings → General. Scroll down to
the section Web Hosting.
14. Specify the Web Host Name or leave the field empty to use the machine name.
15. Set the setting Use SSL to yes.
16. Set the setting Redirect HTTP to HTTPS to yes which will create a corresponding
redirect rule in the IIS after starting the CoreServices.
17. If you have used a self-signed certificate, each user will receive a warning in his
browser when trying to access a LORENZ web application. To circumvent this, you
can install the certificate in your 'Trusted Root Authorities' store of the 'Local
Computer' for each user (for certificate deployment see 2.4.2 or 2.4.4.2).
Depending on the browser additional actions may be required.
2.4.4 Certificate creation
LORENZ provides two possibilities to create self-signed certificates. In the Foundation setup
theres is the option to create self-signed certificates for initial installations. The setup wizard
is intended to be used by all customers that are not familiar with issuing certificates within
their IT infrastructure. Additionally, the Foundation installation package contains a tool that
has the purpose to create certificates.
2.4.4.1 Create and install self-signed certificates using the setup wizard
To create self-signed certificates, you can use the installation MSI file that includes a wizard
to create and install certificates for initial installations:
Figure 2-9
Please select “Create, install and configure a self-signed certificate now”.
In the wizard you can specify the following details:

• Common Name
o By default, the machine name of the application server
• Organization Unit
• Organization
• Valid until
• Private key exportable
o To be able to export the certificate as a file and install it on an extension
server.
By default, the wizard will create a SHA256 certificate with a key length of 2048bit which is
valid for 10 years. The server certificate will also include the DNS name of the machine with
and without domain suffix in the ‘subject Alternative Name’ property. All defaults and naming
can be overwritten by changing the corresponding items.
The certificates will be installed including their private keys in the ‘Personal’ store of the
‘Local Computer’ added to the ‘Trusted Root Authorities’ store of the ‘Local Computer’. The
private keys need to be accessible by the accounts that are used for the LORENZ services
and web applications. For the SOAP service and the client certificate the private key access
is automatically granted to the services when selecting the certificate in the configPanel.
2.4.4.2 Create and install self-signed certificates using the LORENZ Certificate
Utilities
To create self-signed certificates, you can use the tool “CertGen.exe” located in the
“CertUtils” folder of the installation package. It should be executed on the machine for which
the server certificate is intended for, typically the primary server.
By default, the tool will create a SHA256 certificate with a key length of 2048bit which is valid
for 5 years. The server certificate will also include the DNS name of the machine with and
without domain suffix in the ‘subject Alternative Name’ property. All defaults and naming can
be overwritten by changing the config file “CertGen.exe.config” of the tool.
To execute the tool, open an administrator command prompt and navigate to the “CertUtils”
folder. Execute “CertGen.exe” as shown below:
CertGen.exe [-s|-c] <password>

Optional parameter -s (Server auth. only) or -c (Client
auth. only); default = support both
Code 2-8
LORENZ recommends using two different certificates for Services and Clients. Therefore,
you will typically execute the CertGen utility twice:
CertGen.exe -s <password>
CertGen.exe -c <password>

Code 2-9
The tool will create two files for each certificate:
• A PKCS #12–formatted certificate including the private key, secured with the given
password and with the extension ‘.pfx’.
• A DER-encoded certificate without private key with the extension ‘.cer’
For the primary and extension server deployment, you will use the ‘.pfx’ file.
To easily deploy self-signed certificates you can use the tool “CertInstall.exe” instead of the
certificate add-in of the Microsoft Management Console. The tool needs to be copied along
with the certificate file(s) to the machine on which the certificates shall be installed. The tool
should be executed from an administrator command prompt:
Server install: CertInstall.exe [-p] <pfx-file> <password>

Client install: CertInstall.exe [-p] <cer-file>
Use -p as first parameter to install with peer trust.
(Trusted people store instead of trusted root authorities)
Code 2-10
For primary and extension servers, you will need to use the ‘.pfx’ file including the private key
(Server install). In this case the tool will install the certificate in the ‘Personal’ and ‘Trusted
Root Authorities’ store of the ‘Local Computer’. Do not use the parameter “p” for peer trust for
the SOAP service certificate. This may cause timeout issues on servers which are not
connected to the internet.
The client installation mode is intended for rare scenarios in which the client shall validate the
SOAP service certificate using chain or peer trust. By default, the client will validate the
certificate by comparing it to the Base64 exported version within the login configuration file.
2.5 Service and client connectivity

Any service or client will try to locate the login information to connect to a LORENZ server
instance in the following directory:
• C:\ProgramData\Lorenz Life Sciences\Foundation\CurrentConfig
The LORENZ Foundation differentiates between two types of login configurations:
system_login.xml Used by services and other system components that do not run in a user context. The
contents of this config file differ between a primary server and an extension server
machine.
user_login.xml Used by client applications to establish a user session. The config file may contain the
login information for multiple instances like Production, Test and Training.
Furthermore, it configures certain login features like ‘Allow password save’ or ‘Allow
Windows Authentication’.

Table 2-5
Templates for these files are created on the primary server on each start of the
CoreServices:
• system_login.xml:
o Created on each CoreServices start, providing system login information on the
primary server itself and for components hosted on extension servers. Needs
to be copied to the same directory on the extension server.
• user_login.xml:
o Created on each CoreServices start. Needs to be copied to the same
directory on each client machine.
• ExtensionServerConfig.zip:
o Created on each CoreServices start, containing the system_login.xml and the
log4net.xml for remote/extension servers.
The login configuration files need to be deployed to an extension server and a client machine
every time if the
• Machine or domain name of the primary server has changed

• SOAP service certificate changed.
• TCP port configuration changed (TCP base port, 8000 by default)
In addition, the system_login.xml needs to be updated on extension servers if the client

certificate changed.
2.5.1 user_login.xml
Parameter Description
allowPasswordSave Defines whether the docuBridge client is allowed to save user
passwords.
Default: false
connectTimeoutSecs Defines the maximum time in seconds a login attempt can take. For
slow connections or slow responding servers, increasing this
parameter could help to prevent error situations.
Default: 00:10:00
discoveryTimeoutSecs Defines the maximum time in seconds to wait for getting the login
methods from a server. When a user selects a server from the drop
down list of available servers at the docuBridge client, the selected
server is requested upon the available login methods.
Default: 00:10:00

discoveryMaxInstances Defines the maximum number of servers that are tried to be detected
within the network. Servers must have 'Enable Discovery' set to true
in the configPanel settings to be automatically detected within the
network.
Default: 2147483647
Table 2-6
2.5.2 Using Windows Authentication for a Client
To use Windows authentication for users to log on to a client like the docuBridge Explorer the
following prerequisites need to be configured:
1. configPanel > General > Settings > Network Connections > Mode must be set to
LogonUser
2. There are two options to configure the Windows User
a. If the Windows User matches the client user (e.g. docuBridge
user):
i. User Name: Name of the Windows User
ii. Authentication mode: Network
iii. Log on Authority: Name of the Domain
b. If the Windows User and client user (e.g. docuBridge user) don´t
match:
i. User Name: Exisiting client user
ii. Authentication mode: Network
iii. Log on Authority: Domain\Windows User
3. On the client Log on Screen (e.g. docuBridge Explorer) tick the “Use Windows
Authentication” checkbox
If you want to retrieve the correct Log on Authority of the currently logged on user, open a
command line and type “whoami”. This will display the windows identity as Domain\Windows
User. You should use exactly these to configure the Log on Authority correctly.
In case you are using Oracle as database please keep in mind that Oracle is case sensitive.
This means that the domain name and the user name must be configured with the right
capitalization.
If you are using Windows authentication, you need to run the CoreServices under the
LocalSystem account because of permissions and access rights. This also results in that the
log file for the primary server must be configured locally and not on a network share.

2.5.3 Disable 'Use Windows Authentication' on logon screen
The client logon screen (e.g. docuBridge Explorer) displays the option “Use Windows
Authentication” by default as a checkbox that can be selected by users. This option is only
working if the steps described in 2.5.2 have been executed to configure this feature.
In case this feature is not used there is a possibility to disable the display of this checkbox.
The following entry needs to be set to “False” in the “user_login.xml” file located in
“%ProgramData%\Lorenz Life Sciences\Foundation\CurrentConfig” for every client:
<add key="EnableWindowsAuthentication" value="False" />
Code 2-11

3. License Management
3.1 License overview

Every Foundation based installation needs a valid Foundation license to run. Without a fully
valid license no service will start and the configPanel is the only application that can be used.
Licenses are handled and stored on the primary server only. There is no need to install
licenses on client computers nor on extension servers.
Every primary server needs a separate license. Typically, the license is bound to the
hardware of the primary server.
The path to the current license file is:
• C:\ProgramData\Lorenz Life Sciences\Foundation\license.lic
3.2 Installing licenses with the configPanel

As a prerequisite, make sure that the new license file is available and can be accessed from
the configPanel. During license installation a copy of the license file will be created in the
Foundation configuration folder on the server computer.
• Start the configPanel and select the License menu item.

Figure 3-1
Licenses are hardware locked. For hardware locked licenses the hardware code of the
server machine is important. It must match the hardware code in the license, otherwise the
license cannot be activated. So, if you need a new hardware locked license, you must copy
the hardware code and send it to LORENZ support in order to get a customized license file.
For now, let us assume that you already received a valid license and want to install it. Please
click the “New License...” button, select the new license file in the displayed “File Open”
Dialog. The license will be loaded, verified, and activated immediately.
3.3 Viewing licenses with the adminPanel

Start the adminPanel, logon with appropriate credentials and click on the License menu item
as shown in the following picture.

Figure 3-2
Please bear in mind that you can only view the license through the adminPanel. If you want
to change the license, please use the configPanel (see 3.2)
3.4 License expiration notification

Licenses usually (but not necessarily) have an expiration date set. Since licenses are
managed on the server only, there is no direct visual interaction. In order to get information in
a timely manner about licenses expiring in the near future, you can set up an event
subscription (see section 6.7) and subscribe for the event “LICEXPWARN”. This event is
triggered by the system 90, 60, 30, 15, 10, 5, 4, 3, 2 and 1 days before the license expires.

4. Settings
This section describes various system settings and how they can be changed. While you can
use this as a reference on its own, it is mainly a container for describing actions that are
referenced from other administrative scenarios. These Settings can be configured in the
configPanel “Settings”.
4.1 General Settings
4.1.1 Logging
Log File Directory Defines the directory for the system log files.
Possible values: directory path
Default: c:\LORENZ_LOGFILES
Log Level Defines the granularity for messages that are written to the log files.
Possible values: ALL | DEBUG | INFO | WARN | ERROR | FATAL |
OFF
Default: WARN
PLEASE NOTE: The levels ALL and DEBUG should be set only on
direct advice of the LORENZ support.
Using these levels may result in very large log files and loss of
overall system performance!
Event Log Notification Interval Defines the minimum interval of notifications for event log
subscriptions.
Possible values: time interval (hh:mm:ss)
Default: 00:10:00
Table 4-1
4.1.2 Login
Instance name Option to specify an instance name different from the computer name. If not
specified, the instance name is the computer name by default.
Possible values: text
Default: empty
Enable Discovery When enabled, this docuBridge instance can be discovered within the network.
Possible values: yes | no
Default: yes
Use Windows Security When enabled, only trusted Windows users can access the login configuration
retrieval interface.

Default: no
Create Legacy Login Create login configuration files for software modules build before Foundation
Configuration Files 18.1.
Default: no
System Session Timeout Defines the time (in seconds) when a system session will be stopped because a
service has not sent a keep-alive signal to the CoreServices anymore. The
service has to be restarted in order to establish a new session.
Possible values: positive number
Default: 120
User Session Timeout Defines the time (in seconds) when a session will be stopped for a user that is
not active any more, but has not logged out from the system. As long as a user
session is alive, a license is consumed.
Default: 600
Login Sharing Binding The time (in seconds) in which the browser of a user has to contact the login site,
Timeout to start the confirmation process for the sharing of a login with desktop clients.
This helps to mitigate risks, that a malicious user can get a user with more
priviliges to share their login.
Default: 15
Lock Screen Timeout Defines the time (in seconds) when the lock screen shall appear for LORENZ
(Deprecated) web applications. Users cannot continue working until they enter their password
to unlock the screen. Please note that the lock screen has been removed from
the LORENZ web applications with 20.1. This setting is still available to support
LORENZ drugTrack versions until 19.2.
Possible values:
0 = off
positive number = on
Default: 600
Allow concurrent license When enabled a user will consume a concurrent license from a higher available
upgrade level if all licenses of his level are in use.
Default: yes
Table 4-2
4.1.3 Network Authentication
LDAP Access Mode Please do not change this value unless instructed by LORENZ Support.
Defines the access method for LDAP trees (only applicable with network
authentication).
Possible Values:

Logon User = User logs on a server in his domain to authenticate
LdapBind = Authenticate at an external directory server via LdapBind
More Information about User authentication options can be found in the
Foundation Administrator Guide.
Default: LogonUser
Enable Windows Allow users to reuse their Windows Login to log into Foundation.
Authentication Default: yes
Authentication Server Defines an enumeration of authentication servers which can be used for external
Connection authentication of users instead of the internal Foundation authentication. Click
the ellipsis button to open a 'Settings Details' window. The servers defined here
can be used for the field 'Log on Authority' in the USER records. (USER records
can be found in the adminPanel -> User Management -> Users.)
Default: 0
Table 4-3
4.1.4 OpenID Connect
Please refer to section 7.6.4 for more information about the configuration for authentication
via OpenID Connect.
4.1.5 Password Policy
Maximum Login Attempts Defines the maximum number of allowed failed login attempts before the
account gets locked. A successful user login will reset the counter to 0 for
the corresponding user.
Default: 3
Password different from The system will not allow the user's password to be identical to the user
username name if set to 'yes'.
Only applicable with Foundation authentication. This value can also be
managed using the adminPanel website.
Default: yes
Password History Defines the number of passwords kept in the history cache (per user). When
users change their passwords, the new passwords are only accepted if not
found in the history cache. Note that setting this to 0 will still keep the last
password in the cache, to prevent the users from using the same password
again.
Only applicable for users set up to use the authentication mode Foundation.
Default: 3

Maximum Password Age Defines the number of days before the users will be forced to change their
passwords (starting from the time when the password has been defined or
changed last).
Default: 1000
Minimum Password Age Defines the number of days before users are allowed to change their
passwords (starting from the time when the password has been defined or
changed last). This is useful to prevent users from overriding the history
cache.
Possible values: number
Default: 0
Minimum Password Length Defines the minimum length of user passwords. Note that this is a
convenience setting only since a more comprehensive definition is given by
the Password complexity setting.
Default: 2
Password Complexity A regular expression, which defines the required complexity for user
passwords.
Possible values: regular expression
Default: ^.{2,}$
Table 4-4
4.1.6 SAML 2.0
Please refer to section SAML 2.07.6.37.6.4 for more information about the configuration for
authentication via SAML 2.0.
4.1.7 System E-Mail Account
Host The mail server host name for sending e-mail messages.
E-mail messages can be send either via Notifications or defined
Subscriptions in the LORENZ adminPanel. Users can subscribe on Event
Codes (e.g. user actions, license expiration or job issues). More information
can be found in the section 'Event Subscriptions' in the Foundation
Administrator Guide.
Sample: mail.companymail.com
Default: empty

Port SMTP port number for e-mail messages.
The commonly used ports for SMTP are 25 when SSL is disabled and 587
when SSL is enabled.
Possible values: valid port number
Default: 587
Enable SSL When enabled, Secure Sockets Layer (SSL) is used.
Default: yes
Timeout (Milliseconds) Please do not change this value unless instructed by LORENZ Support.
Defines the timeout in milliseconds the system tries to connect to the SMTP-
Server.
Default: 60000
User Defines the user name (e.g. an e-mail address) used to logon to the defined
SMTP server.
Default: empty
Password Defines the password used to logon to the defined SMTP server.
Default: empty
Sender Address Defines the sender's e-mail address on which behalf e-mails are sent.
Sample: info@companymail.com
Possible values: e-mail address
Default: empty
Display Name Defines the display name of the sender's e-mail address on which behalf e-
mails are send.
Default: empty
Table 4-5
4.1.8 Web Hosting
Web Host Name Defines the web host name to access the LORENZ web applications. Leave
empty to use the machine name of the primary server.
Possible values: web host name
Default: empty
Use SSL Use Secure Sockets Layer (SSL) for web connections. If enabled, additional
configuration of the IIS (and a certificate) is required.
Default: yes

Redirect HTTP to HTTPS Create a redirect rule to enforce Secure Sockets Layer (SSL) for LORENZ
web applications hosted in the IIS. The rule will only be created when the
setting 'Use SSL' is enabled.
Default: yes
Share Authentication Cookie If enabled, then authentication cookies are shared across a sub-domain.
The setting must be set to 'yes', if the latest Foundation version is used
together with older versions of other LORENZ products.
It is recommended to set this setting to 'no' in case the Foundation is hosted
in certain domain environments (e.g. AWS).
Default: yes
IIS Reverse Proxy Web Site IIS Web Site for reverse proxy rewrite rules. Leave empty to use the Default
Web Site.
Possible values: Name of the Web Site
Default: empty
IIS Reverse Proxy Timeout Configures the time in seconds the reverse proxy will wait for a response
from the API.
Default: 300
TCP base port for internal REST Sets the TCP base port for internal REST service hosts. These will not be
APIs exposed to the outside directly but instead routed through the Reverse
Proxy.
Possible values: valid port number
Default: 8080
Table 4-6
4.2 Product settings

Every LORENZ Product using the Foundation has its own settings section. These settings
are described in detail in the dedicated product documentation.

5. Configuration
5.1 Export-/Import Packages

Configuration Packages have been introduced to the Foundation with 18.1 to streamline the
transfer of a configuration from e.g. a validation system to production system.
This functionality can be used to Export and/or Import configuration packages. There are
different configuration options available for all LORENZ Products that are based on the
Foundation. These options are described in more detail in the dedicated product
documentation.
Configuration package Imports are managed by restore profiles. For LORENZ Foundation a
dedicated restore profile for users, groups and roles is available at the configPanel >
Configuration > Import Package:
Figure 5-1

5.2 Files
The system can be configured depending on customer needs through user configuration
files. A list of all files can be viewed in the configPanel’s ”Files” section:
Figure 5-2
These files can be opened and edited directly from within the configPanel by double clicking
the file. All XML files will open in a built-in XML viewer that is also able to validate against a
schema.
In addition, files that have encrypted content included like the smtp.xml (Mail Password) will
be opened with decrypted passwords. After saving or closing the editor these files will be
encrypted automatically.
There is also the possibility to “Backup” and “Restore” all User Configuration Files in the
configPanel. Just click on the corresponding buttons in the “User Configuration Files” section
and follow the displayed instructions.

5.3 Product configurations

Every LORENZ Product using the Foundation could have its own configuration section.
These sections are described in detail in the corresponding product documentation.

6. Monitoring & Controlling the System

When the system has been set up and configured properly, the administrator should
regularly check the system's health. This includes the current operational status of the
system components, an overview of the users currently working with the system, verifying
the versions of the system components currently in use, and checking the system logs for
abnormalities.
6.1 System Sessions overview

1. Start the adminPanel and log in with appropriate credentials (the System
Monitoring function _MON must be authorized).
2. Click the System Sessions menu item in the Monitoring group on the left.
Figure 6-1
The site lists all system sessions that are currently connected to the Foundation.
Every service is regularly sending heartbeats while being active. The columns Active since
and Last signal show the timestamps of the first heartbeat resp. the most recent heartbeat
received from the services.
6.2 User Sessions overview

Monitoring function _MON must be authorized).
2. Click the User Sessions menu item in the Monitoring group on the left.

3. You will get a list of all users currently logged in to any client application including
adminPanel sessions. The only application not listed is the configPanel because it
does not send any heartbeats to the system.
4. The total count of users currently logged in will be displayed in bottom of the grid.
For information about sending notifications to active users, please refer to section 6.8.
6.2.1 Log-off an active user
To log-off an active user please select the user in the grid and click on the log-off icon right to
the user name.
Terminating a user session can cause data loss. The user is logged off immediately without the
chance to save his changes.
6.3 Session Log

The Session Log in the LORENZ adminPanel can be used to display, filter and report on
historic sessions. The Session Log section requires the System Monitoring function _MON.
Figure 6-2
If a user or system could establish a session by successfully authenticating against the

LORENZ CoreServices, the session is listed as Established Session, otherwise as
Rejected Session. Reasons for rejected session are e.g. Invalid Credentials, User Locked,
Wrong Password, Password Change Required or No License Available.

6.4 Version check

The Foundation system consists of multiple executables, other binaries, and configuration
files. For a given product release it is important to verify that all these components are
present with the correct version. While this is ensured by LORENZ when delivering a product
release, it is vital for the operability of your system that you monitor the version status
afterwards.
6.4.1 Version check using the configPanel
The configPanel checks during a validation run the correctness of the System Version and all
System Configuration Files. If there are any unexpected versions detected the corresponding
check will be marked red including a message about the detected problem.
6.5 Starting/Stopping services in configPanel

The configPanel provides a convenient way to start and stop the Foundation services:
• Start the configPanel and click the Services menu item to display all LORENZ
Services.

Figure 6-3
Description
Machine The name of the machine hosting the service. This is especially for Extension Servers.
Service Name The name of the service.
Status The current status of the service.
Start Mode The service start mode as used by Windows. Possible values: Automatic, Manual, and
Disabled.
Automatic:
This is the default value and also the recommended value. The service will be started
automatically when the server has been started. An interactive logon is not necessary.
Manual:
The service must be started by a user (an interactive logon is required).
Disabled:
The service will be ignored in all start/stop actions.

Description
User The user account the service is running as. For the foundation services (CoreServices),
the Local System account is sufficient. The other services can only use the Local
System account if all Foundation shared folders are located on the same server as the
services (because Local System does not have access to any network resources).
Table 6-1
By clicking the “Start all” button, the program will try to start all services in the list that are not
currently running and have a start mode other than Disabled.
During the startup of the CoreServices all configuration files will be validated. If there are any
files that are invalid, NO service will start. Please use the configPanel´s “Validation” feature to
locate the problems.
By clicking the “Stop all” button, the program will stop all services listed. Both starting and
stopping may take a moment. The view is updated automatically, but a Refresh button is also
available.
A restart of all services can be done by using the “Restart all” button. While the services are
being stopped or started, all buttons in the window are disabled.
If you changed the Start Mode or the User account for one or more services, you need to
click the Save button before closing the dialogue to save the changes made (starting and
stopping services does not require saving).
6.6 Starting/Stopping services in Windows MMC

You can also start and stop services through the MMC in Windows (Services dialogue). Look
for the name of the service you want to stop, which consists of the instance name and the
internal service name (e.g. LORENZ CoreServices).
You can start and stop single services this way. However, since the services have certain
dependencies set, stopping a service might have impact on other services too. For example,
if you try to stop the CoreServices, all other services of the corresponding instance will be
stopped too.
6.7 Event Subscriptions

You can use subscriptions in Foundation to get notifications about certain events in the
system. Examples for such events are errors, warnings or information written to the event
log.
The notifications will be delivered to the e-mail address, which has been configured for a
user account. To view or add event subscriptions, please follow these steps:

Configuration function _CFG must be authorized).
2. Click the Subscriptions menu item in the Messaging group on the left.
Figure 6-4
To use the feature, it is necessary to configure an SMTP server in the configPanel > General
Settings. If you are upgrading to Foundation from a version below 5.9 you will need to re-create
your subscriptions.
To add a new subscription:
1. Click on the New (+) button. This will open a new dialogue to enter:
a. User Name
b. Event Code (Wildcards possible e.g. LGN*)
c. Severity
2. Click the Create button. The new subscription will be added to the list in the upper
pane. It becomes active immediately.
Multiple subscriptions can be created for the same user account.
To delete an existing subscription:
1. Click on the corresponding row in the list of subscriptions and then click on the X
that is displayed right of the User Name

6.7.1 Event Codes
Event Code Severity

User was locked LGNUSRLCK Warning
Invalid username or password was LGNUSR1AL Warning

used, warning if only one logon
attempt is left
Upgrade user license level (e.g. LICUSRUPG Warning
compile instead of view)
License expires is x days LICEXPWARN Warning
License expired LICEXPIRED Error
Limit of licenses reached/running LICUSRNA Error

out: User cannot login because no
license is available
Job completed with errors or JOBISSUES Warning, Error
warnings or if the job is faulted.
Errors and Warnings have been LOGENTRIES Warning, Error
written to the LORENZ log
Table 6-2
6.8 Sending Notifications to Users

Through the adminPanel, you can send notifications to one or more active users. The
notification will be delivered to the user's e-mail account as configured in the user record.
Notifications can be helpful for example if you want to inform all active users about an
upcoming system maintenance. The notification could notify the users that they are required
to logoff in the next 5 minutes due to scheduled system maintenance tasks.
To prepare and send notifications to users, please follow these steps:
Configuration function _CFG must be authorized).
2. Click the Notifications menu item in the Messaging group on the left.
The following picture shows the web page with the user interface for sending notifications:

Figure 6-5
Notifications can be sent like a normal eMail with Recipients, a Subject and a Message Text.
To see a list of all active Users just click into the “To” text field and start typing. Additionally,
you can click directly onto the To-Button to select Active User sessions, Groups or Roles. By
clicking the Send button, your message will be sent to all users you have selected.
6.9 Logging
There are several logging features available with Foundation. Which one you should use,
depends on the issue you want to analyze or resolve. This section provides a detailed
description of all logging features.
6.9.1 LORENZ Log Files
Every Foundation service can be configured to write trace information into log files. By
default, logging is turned on with a Log Level “Warning”. To change the logging, please
follow the steps below.
1. Open the configPanel and select the “General” menu item.

2. The section Logging displays all available log configurations:
a. Log File Directory
b. Log Level
c. Event Log Notification Interval
Changes to the Log Level can be done without restarting the services. The services will start
logging according to the set Log Level immediately after you saved your changes.

By default, a new log file is created for each month. If you want to turn off the logging feature,
you can set the Log Level to “OFF”.
The log files are xml files, prepared for viewing in a dedicated log file viewer. Foundation
comes with a built-in log file viewer. To view the current log files:
1. Open the configPanel and select the Validation menu item

2. Click on the Log Files(s) button.
3. The log file viewer will be opened, and all available log files will be loaded.
6.9.2 Client-Side Logging
Log files are usually written by the server components. However, you can also instruct the
client applications to write log files.
• Copy the “log4net.xml” from the Primary Server to the Client into the same location
o C:\ProgramData\Lorenz Life Sciences\Foundation\CurrentConfig\log4net.xml
6.9.3 Event Log (adminPanel)
The Foundation Event Log is an additional instrument for system monitoring and issue
analysis.
Figure 6-6
6.9.3.1 Viewing the Event Log
1. Open the adminPanel (login with appropriate permission: the account must be
authorized for the System Monitoring function _MON).
2. Click the Event Log menu item in the Monitoring group on the left.

The upper pane contains the filter and navigation controls. Via the filter symbol you can
select the time interval for the events to be listed and you can also specify several filter
criteria for the events you are looking for.
Each event belongs to a certain event severity: Error, Warning or Info. By activating or
deactivating the corresponding checkboxes, you can choose which severity levels should be
included in the list.
The events are presented in a paged view with up to 15 events per page, sorted by date,
with the most recent events on top.
For each event, the following information is shown in the list:
Column Description
Event Time Timestamp of the event (the time the event occurred)
User The name of the user this event belongs to. When the event is not related to
a specific user account, [SYSTEM] is listed here instead.
Severity The severity of the event (Error, Warning, Info, or Audit Trail)
Event Code A specific, culture invariant event code.
Description The Description of the Event.
Host The computer name or IP address where the event occurred. In some cases,
also the name of the instance is listed (separated from the host name by a
slash).
Acknowledged Acknowledged events will show the name of the user who did the last
acknowledgment in the rightmost column.
Table 6-3
If you select an event from the list, the details for this event will be shown in a separate pane
below the list. The details vary depending on the type of the event.
6.9.3.2 Acknowledging Events
Events can be acknowledged and commented. This can be helpful to make a statement
about an error that has been resolved. Then you might want to exclude this error from any
further event lists. You can do this by deactivating the Acknowledged checkbox in the filter
pane before you perform a search for events. An event can also be acknowledged more than
once.
To add a new acknowledgment, select an event and click the Acknowledge button. Entering
a comment for an acknowledgement is optional.

6.9.3.3 Event Log Report
The displayed event log entries can be exported in XML or HTML format by clicking the
Report button in the top right corner. Please see section 7.5 for further details on reporting.
6.9.4 SQL Tracing
The Foundation system provides a SQL tracing capability to support analysis and
identification of technical problems that cannot be resolved using one or more of the other
logging features. You should only use the SQL tracing feature when you are instructed by
LORENZ support. Otherwise you risk heavy performance impacts and large amounts of hard
disk space consumption. With SQL tracing enabled, the system will write lots of trace
information to the specified location. This trace file tends to be very large.
SQL tracing can be enabled for server computers only. This can be done by creating a
configuration file called “sqllog.cfg” in the following location of the Foundation server:
• C:\ProgramData\Lorenz Life Sciences\Foundation\CurrentConfig
Please insert into the “sqllog.cfg”-file the following settings:
• enabled=true
• filename=c:\LORENZ_LOGFILES\sql.log
To disable the logging just change the enabled-setting to false.
To enable the SQL logging it is needed to restart all services once the configurations are done.
After the restart the SQL logging can be turned on and off without restarting the services if the
generated log-file “sql.log” exists.
6.10 Creating a System Snapshot

Sometimes, you may be asked by LORENZ support staff to send some information about
your system configuration or system log files. While the corresponding files and folders can
be located and copied manually, there is a more convenient alternative provided with the
configPanel. The configPanel allows compiling all necessary configuration and log files into a
compressed system snapshot archive, which can then be sent to LORENZ support.
Sending snapshots to LORENZ support will not reveal confidential information stored in the
configuration files. The configPanel ensures this by replacing any passwords included with
the files.
The following procedure describes how to take a system configuration snapshot.
1. Start the configPanel.

2. Perform a full validation by ensuring that all checks have been selected and clicking
the Analyze button. You cannot take a snapshot without running an analysis before
because analysis results are a required part of the snapshot.

3. When the analysis is completed (no matter which results it had), the Snapshot
button will be enabled.
4. Click the Snapshot button.
5. When prompted, choose the target file to save the snapshot information.
6. Wait until the snapshot has been created. Progress information will be shown, and
a completion message will appear.

7. User Management
All User Management tasks can be performed with the adminPanel. Therefore, the following
sections assume that you already started an adminPanel session by logging in with an
account that has the User Management function (_USM) authorized.
In a new installation, only the ADMIN account is available. It has been predefined with all
necessary functions for accessing the adminPanel. The default password is callisto. See
section 7.1.10 for further information.
All user management activities (create, modify, delete) on Users, Roles and Groups are
captured in the database and traceable via the User Management Audit Trail.
7.1 Managing User Accounts

The Users page lists all users that are stored in the database. By default, previously deleted
users are not displayed. The displayed users list can be sorted by clicking a column header.
Figure 7-1
7.1.1 User List Filtering
The list of users can be filter in two different ways:
• Quick Search Filter

• Users Filter

7.1.1.1 Quick Search Filter
To easily search for user name(s), just enter the text string in the User Name search field
located in the top right corner. The entered text string will be searched in all user names
stored in the database and return all users where the user name includes the entered search
string.
Figure 7-2
7.1.1.2 Users Filter
The users filter offers the following set of search criteria that can be used to reduce the
number of displayed users.

Figure 7-3
7.1.2 User List Grouping
The displayed search result can be grouped by all displayed columns. To apply a grouping
drag & drop one or multiple column headers into the grouping row displayed above the user
list:
Figure 7-4

7.1.3 Adding new user accounts
To create a new user account:
1. Click the Users menu item in the User Management group.

2. Click the New (+) button
3. Enter the appropriate values for the fields as listed in the following table.
Field Description
User Name This is a mandatory field: a unique name for the user account. A maximum of 100
characters is allowed for this field.
Description This is an optional field for describing the user account. A maximum of 240
characters is allowed here.
Department This is an optional field. You can specify the name or a description for the user's
company department. A maximum of 90 characters is allowed here.
E-mail address This is an optional field. If you want to use e-mail notifications or event subscriptions
(for this user account, you need to specify a valid e-mail address here.
Culture Defines the language and the DateTime format for the LORENZ web applications.
The default value is determined by the configured language in the browser settings.
Authentication mode A user can be authenticated by the LORENZ Foundation or by an external authority.
If you choose Foundation, you will be required to provide an initial password for the
user. If you choose Network, you need to specify the name of the Logon Authority.
See section 7.3.4 for further details and examples. If you choose a configured
SAML2.0 or Open ID Connect identity provider, please select the name of the
identity provider you want to use.
Account locked Activate this checkbox if you want to prevent a user from logging into the system
(deactivate it to re-enable a user). Note that user accounts will be locked
automatically by the system after too many failed logon attempts.
Force password change This applies to user accounts with Foundation authentication only. Activate this
on next logon checkbox if you want the user to change his/her password upon next logon.
Note that users will always be requested to change the password upon first logon.
You cannot prevent this. Even if you deactivate the checkbox Force password
change on next logon, the user must change the password. This is by design,
because it ensures that nobody can logon as this user with a false identity (not even
the administrator).
Password never expires This applies to user accounts with Foundation authentication only. Activate this
checkbox if you want to prevent password expiration for this user account. The
password expiration is defined by the password policy
Note that activating this checkbox is not recommended for normal operation.
Otherwise your system will no longer be 21 CFR Part 11 compliant.
Reset password to This applies to user accounts with Foundation authentication only.

Field Description
For new user accounts, this is a mandatory field. You can specify an initial password
of your choice. Note that the password policy does not apply here. The user will
have to change the password again upon next/first logon. You cannot prevent this.
Logon Authority This applies to user accounts with Network authentication only.
Note that this is not a mandatory field. However, without an appropriate Logon
Authority the user will not be able to log on.
For information about the format and the meaning of Logon Authority values, please
refer to.
Table 7-1
4. Click the Create Button to create the User.

5. If you already have Roles defined, you can select role membership for the new
account by selecting Roles on the Roles section via the +-button. A user can have
multiple roles assigned. For more information about roles, see section 7.1.7.
6. If you already have Groups defined, you can select them also via the +-button. A
user can be a member of multiple groups.
7. You can verify the functions assigned to the user in the displayed Foundation
Functions item. Note that the list of functions is read-only. You cannot change
function assignment through this list. As described in section 7.1.7 functions can
only be assigned through role membership.
7.1.4 Cloning existing user accounts
To clone an existing user account:
1. Click the Users menu item in the User Management group

2. Select a User
3. Click on the Clone-icon right to the user’s name
4. Enter the user details and click on Create
7.1.5 Modifying user accounts
To modify an existing user account:

2. Click on the user name to see the details page
3. Click on the Edit-icon for the user, groups or roles
7.1.6 Deleting user accounts
To delete an existing user account:

2. Select a User
3. Click on the Delete-icon right to the user’s name and confirm

4. The user account is deleted, and the page fields are cleared
The user record has not been deleted physically from the database. It has been marked as
deleted instead. The reason is that there might be historical audit trail events associated with
this account, which should not be compromised by completely removing the account record.
7.1.7 Restoring deleted user accounts
To restore a deleted user account:

2. Click the Filter button and check the filter option "Include Deleted" and apply the
filter
3. Deleted user accounts are displayed in the users list and indicated by the name
suffix "/Deleted:"
4. Click the name of the user account that shall be restored. The user details page
opens.
5. Click the Edit button
6. Remove the checkbox "Account Deleted" and click the update button
7. The user account is restored
7.1.8 Unlocking user accounts
User accounts in Foundation will be locked (disabled) automatically in case of too many
failed logon attempts. The maximum number of attempts before an account gets locked is
defined by the password policy settings (see section 7.7.2).
Failed logon attempts will be counted regardless of whether the user account uses Foundation
authentication or network authentication, so a network account can get locked if the user
exceeds the limit. This limit is not related to any such limit in the Active Directory or other
authority sites.
To unlock a locked user account:

2. Click on the user name in the user browser
4. Deactivate the checkbox “Account is locked”
5. Click the Update button
7.1.9 Resetting user passwords
If needed, the administrator can reset the user password to a new password.

This applies to user accounts with Foundation authentication only.
To reset the user password:

2. Click on the User name to display the details
3. Click on the Edit button
4. In the text field “Reset password to” type a new password. In this case, the
password policy settings will not be applied
5. Check if the checkbox “Account locked” is activated (e.g. because of too many
failed logon attempts). You need to deactivate it before saving. Otherwise the user
cannot logon.
6. Click the Update button
7. The new password becomes effective immediately
The user will be requested to change the password upon first logon.
7.1.10 Resetting the ADMIN User Account
The Foundation database contains two special stored procedures for resetting the Admin
account, which can be executed directly from the Database management tools:
7.1.10.1 Create the ADMIN user account
Stored Procedure: RECREATE_ADMIN_ACCOUNT
If the Admin account does not exist, it will be created. Then, the password for the Admin
account will be reset to callisto and all functions required to access the adminPanel will be
created and assigned. The role Admin is created, and the Admin user account will be
assigned to that role. Please change the Administrator password immediately after resetting.
7.1.10.2 Reset ADMIN user account password
Stored Procedure: RESET_ADMIN_PWD
Resets the password for the Admin account to callisto. Please change this password
immediately after resetting.
Resetting the admin account or password through stored procedures will not generate audit trail
events. You should only do this as the final alternative when no other options are left.
7.2 Managing User Roles

User roles are the means to define authorization levels for users. Instead of assigning
functions directly to users, you must configure roles and then make the user accounts

members of these roles. Each role is a collection of one or more functions. A user can have
multiple roles assigned.
7.2.1 Adding new user roles
To create a new user role:
1. Click the Roles menu item in the User Management group

2. Click the + button
3. Enter the appropriate values for the fields as listed in the following table:
Field Description
Role Name This is a mandatory field: a unique name for the role. A maximum of 100
Description This is an optional field for describing the role. A maximum of 240 characters is
allowed here.
Table 7-2
4. Click on Create
5. You can select the functions for this role from the functions list in the Functions
section. This is optional but of course a role is not useful without any functions
assigned.
a. General Functions e.g. User Management (see section 7.2.4)
b. docuBridge Functions e.g. Submission Publishing
6. If you want to assign users to this role you can do this via the Users section. This is
optional, but a role is not useful without any user accounts assigned. You can also
assign users to roles through the individual user account records (see section 7.1).
The lower pane in the Users in this Role tab lists all users already assigned to this
role. To assign new users:
a. Click the + button for Assign Users in the Users section. The user
browser dialogue is being displayed.
b. Start entering any search criteria and the search will automatically
search for matches. If you leave the filter blank and click into the
text filed, all users will be listed.
c. Select the users from the list
d. Click the OK button
e. The Users in this Role section now shows the users you have
selected.
7.2.2 Modifying existing user roles
To modify an existing user role:

2. To view the details of a role just click on the name.

3. Start editing the values via the Edit button

4. Click the Update button to save any changes made
7.2.3 Deleting user roles
To delete an existing user role:

2. Click the x button that is displayed for each role if you select it and acknowledge
the confirmation message by clicking OK
3. The role is deleted, and the page fields are cleared. Any user account
memberships for the deleted role are cleared.
The role record has not been deleted physically from the database. It has been marked as
this role, which should not be compromised by completely removing the role record.
7.2.4 Restoring deleted user roles
To restore a deleted user role:

filter
6. Deleted roles are displayed in the roles list and indicated by the name suffix
"/Deleted:"
7. Click the name of the role that shall be restored. The role details page opens.
9. Remove the checkbox "Role Deleted" and click the update button
10. The role is restored
7.2.5 General Functions
Functions are the lowest level in the authorization (please see section 7.9) process. System
functions are predefined and will be installed automatically during setup. Please see below
for the list of system functions supported by Foundation.
A function has a function code, a function name, and (optionally) a function description.
Functions can be assigned to roles (please see section 7.1.7). The following General
Functions are available in LORENZ Foundation:

Name Code Description
System Configuration _CFG Grants the user access to the Messaging section of the adminPanel. This
Management section contains the Notifications and Subscriptions pages.
If the docuBridge module is installed, this function grants the user access to
the docuBridge section of the adminPanel. This section contains the Access
Control Lists, Named Permissions and docuBridge Launcher pages.
Job Management _JOB Grants access to the jobs of other user including the possibility to suspend
the jobs and delete them. Without this function, a user can only see and
manage his own jobs.
System Monitoring _MON Grants access to the Monitoring section of the adminPanel. This section
contains Active Sessions (System Session, User Sessions), Session Log
(Established Sessions, Rejected Sessions), Event Log, License and Named
Licenses Assignment pages.
User Management _USM Grants access to User Management section in the adminPanel. This
section contains the Users, Roles, Groups and Audit Trail pages.
Table 7-3
7.3 Managing User Groups

User groups can be used to simplify object permission handling in Foundation. Instead of
setting object permission for individual user accounts, you can set the permission for one or
more groups, which will inherit the permission to all user accounts that are member of these
groups.
7.3.1 Adding new user groups
To create a new user group:
1. Click the Groups menu item in the User Management group.

2. Click the + button
3. Enter the appropriate values for the fields as described in the following table:
Field Description
Group Name This is a mandatory field: a unique name for the group. A maximum of 100
Description This is an optional field for describing the group. A maximum of 240 characters is
allowed here.
Table 7-4
4. Click on the Create button

5. Refer to the Users section in this Group if you want to assign users to this group
now. This is optional, but a group is not useful without any user accounts assigned.

You can also assign users to groups through the individual user account records
(see section 7.1).
6. The users section shows the Users in the Group tab. It lists all users already
assigned to this group. To assign new users:
a. Click the + button in User section. The user browser dialogue is
being displayed.
b. Start entering any search criteria and the search will automatically
search for matches. If you leave the filter blank and click into the
text filed, all users will be listed.
c. Select the users from the list
d. Click the OK button.
7. The Users section in this Group now shows the users you have selected.
7.3.2 Modifying existing user groups
To modify an existing user group:

2. To view the details of a Group just click on the name.
3. Start editing the values via the Edit button
4. Click the Update button to save any changes made.
7.3.3 Deleting user groups
To delete an existing user group:

2. Click the x button that is displayed for each group if you select it and acknowledge
the confirmation message by clicking OK.
3. The Group is deleted, and the page fields are cleared. Any user account
memberships for the deleted Group are cleared.
The Group record has not been deleted physically from the database. It has been marked as
this Group, which should not be compromised by completely removing the group record.
7.3.4 Restoring deleted user groups
To restore a deleted user group:
4. Click the Groups menu item in the User Management group

filter
6. Deleted groups are displayed in the groups list and indicated by the name suffix
"/Deleted:"
7. Click the name of the group that shall be restored. The group details page opens.


9. Remove the checkbox "Group Deleted" and click the update button
10. The group is restored
7.4 Audit Trail

All user management related events (create, update, delete) are captured in the database.
The Audit Trail page in the adminPanel (requires the General Function _USM) allows the
display and filtering of such events.
Figure 7-5
7.5 Reporting
The adminPanel provides a report functionality on every page in the User Management
section:
• Users page
• User details page
• Roles page
• Role details page
• Groups page
• Group details page
• Audit Trail page
The report button is always located in the right top corner. The reports can be requested in
HTML or XML format. The internal format is always XML. If HTML is selected, an XSLT style
sheet will be used to transform the XML content into HTML output. The style sheet shipped

with the Foundation setup is an example only and can be customized or replaced according
to your needs.
To request a report, follow these steps:
1. Click the menu item in the User Management section for which you want to create
a report.
2. Click on the Report button.
3. Depending on the selected report, several Options (also filters) may be displayed.
Choose the options that are appropriate for you.
4. Select the output format (HTML or XML) at the bottom of the dialogue.
5. Click the OK button. After a few seconds the report will be available.
If you select XML as output format, you can for example import the content to Microsoft Excel
and format or filter it according to your needs.
7.6 User Authentication Options

For user authentication, Foundation provides two options:
• Foundation internal authentication

• Authentication through an external authority
The authentication mode can be defined for each user account individually (see section 7.1).
7.6.1 Foundation
The Foundation authentication provides an easy to use, flexible and secure way for
authenticating users. It is fully compliant with 21 CFR Part 11. Passwords are stored as
salted hashes and a comprehensive password policy is enforced.
7.6.2 Network
The network authentication can be more suitable for you if you already have a Logon
Authority in your network (e.g. a Windows domain with Active Directory or an LDAP tree).
Whenever a user logs into the system, the credentials will then be verified by one of those
authorities. The user can use the same user name and password as for the other network
resources. To enable users to access the option on the login screen, please set the
parameter “Enable Windows Authentication” at configPanel > General > Network
Authentication to “yes”. If you want to hide the option at all, set it to “no”.
However, it is still necessary to add a corresponding account to the Foundation database

(please see section 7.1), because the roles, groups, and functions are managed there
(please see section 7.1.7).
If you want to enable network authentication for a user account, the Logon Authority in the
user record (please see section 7.1) must be specified in one of the following formats:

1. The name of a trusted logon server or the name of an authentication server as

defined in configPanel (see section 4.1.3):
a. Mode
b. Authentication Server Connection
2. The name of a trusted logon server or the name of an authentication server as
defined in configPanel with a prefix (starts with CN=) that maps the common name
part of the DN. This is the preferred scenario for Windows domains with Active
Directory where the name of the user account differs from the Pre-Windows 2000
login name:
a. Mode
b. Authentication Server Connection
3. A fully qualified LDAP connection string. It must be started with "LDAP:" (without
the quotes).
4. Using the DomainName
a. Mode
Example: Option 1 and Option 2
In the configPanel under General System Parameters the following Authentication Servers
(Server1 and Server2) are defined:
Figure 7-6
• NetworkLogonMode is set to “LdapBind”

• In the image above “172.16.1.31” is the IP address of the server hosting the domain
controller (LDAP).

Figure 7-7
Example: Option 3 (using the DomainName)
• NetworkLogonMode is set to “LogonUser”
Figure 7-8
7.6.3 SAML 2.0
The Security Assertion Markup Language 2.0 (SAML2) is a standard protocol for exchanging
authentication and authorization related information between security domains. SAML 2.0
uses security tokens to pass information about a user account between SAML 2.0 supporting
applications. SAML 2.0 enables web-based, cross-domain single sign-on (SSO), which helps
reduce the administrative user account management.
SAML 2.0 distinguishes the participating applications in different roles:
• Identity Provider (IP)

Identity Providers are applications were the user account is maintained with account
information such as user name, email address and passwords. For instance Okta,
Google, Auth0 or other vendors for user account management functionality.
• Service Provider (SP)

Users are logging on to an identity provider and service provider applications like
LORENZ Foundation can retrieve this user session from an identity provider.
IPs require a recipient URL where responses to authentication requests should be sent. This
can be created by filling in this pattern:

https://{Web Host Name}/lorenz.webLogin/saml/Login.ashx
IP initiated logins or logouts are not supported.

To configure SAML2 Authentication, please see the section at the configPanel > General >
SAML 2.0
Audience URI(s) Defines the intended audience of the SP. Usually this needs to be
configured at the IP application to target responses sent to LORENZ
Foundation.
Default: https://lorenz.cc/sso/saml2
Service Provider ID Unique Identifier of the SP application. Usually this needs to be
configured at the IP application to identify the configured SP
application.
Default: urn:LORENZFoundation
Identity Provider Metadata folder Each IP provides a metadata file (XML based file), containing the
security information for the secure communication between SP
application and the IP. At this folder location all metadata files of all
IPs have to be stored.
Default: C:\ProgramData\Lorenz Life

Sciences\Foundation\CoreServices\SAML2
Note: Please mind to save the metadata file from the IP in this folder
before continuing any configuration.
Identity Provider – ID The IP ID will be taken from the metadata file and supplied in a drop
down to select the wanted IP.
Identity Provider – Name The name of the IP will be used in the LORENZ Login dialogs to
enable the user to choose this IP to proceed a user login.
Identity Provider – User Attribute User accounts of the SP needs to be mapped to the user accounts
of the IP. Such user accounts can be identified by multiple user
attributes, each IP has specific naming conventions for their user
account attributes.
At this setting the name of the attribute of the user account at the IP,
which contains the same value as the user name or e-mail address
of an user account at LORENZ Foundation, has to be defined. If this
value is empty, the Subject of the IP is used, which is usually the
main user name of the user in the IP.
7.6.4 OpenID Connect
OpenID Connect is an additional identity layer on top of the OAuth 2.0 protocol, which allows
computing applications to verify the identity of an user.

OpenID Connect distinguishes the participating applications in different roles:
• Authorization Server (AS)

Authorization servers are instances where the user account is maintained with
account information such as user name, email address and passwords. For instance
Okta, Google, Auth0 or other vendors for user account management functionality.
• Clients
Users are logging on to an authorization server and client applications like LORENZ
Foundation can retrieve this user session from an authorization server.
To configure OpenID Connect Authentication, please see the section at the configPanel >
General > OpenID Connect
Authority Defines the URL of the AS. Usually this needs to be retrieved from
the AS and configured in LORENZ Foundation.
For instance, at Okta an Authority looks like this: https://dev-

641xx.okta.com
Client ID Unique Identifier of the client application, which is first to configure at
the AS. The same value of the client ID has to be set here.
Client Secret Secret string, similar to an account password, used for LORENZ
Foundation to communicate securely with the AS.
Note: The client secret is configured first at the AS and then the
same value has to be set here. It is possible that an AS uses no
client secret in which case this setting has to remain empty.
Local ID The local ID can be freely chosen and will be part of the redirect URL
that has to be configured in the AS. This URL can be created by
filling in this pattern: “https://{Web Host
Name}/lorenz.webLogin/openid/{Local ID}”.
Note: Please mind to choose a Local ID without any special

characters or other none HTTP friendly characters.
Name The name of the AS will be used in the LORENZ Login dialogs to
enable the user to choose this AS to proceed a user login.
Use PKCE Proof Key for Code Exchange (PKCE) is an additional security
mechanism on top of OpenID Connect. If no Client Secret is given
this has to be set to “yes”. If a Client Secret is present this is optional
but can provide a little extra security if the AS supports it.
Possible values: yes|no

User Claim User accounts of the client needs to be mapped to the user accounts
of the AS. Such user accounts can be identified by multiple user
claims, each IP has here specific naming conventions for their user
account claims.
At this setting the name of the attribute of the user account at the
AS, which contains the same value as the user name or e-mail
address of an user account at LORENZ Foundation, has to be
defined.
7.7 Single Sign On (SSO)
7.7.1 LORENZ Single Sign On (SSO) Login
The LORENZ SSO Login is used by all LORENZ web applications to authenticate the user or
to change the password. Single Sign On works with Foundation authentication, 3rd Party
Identity Provider (e.g. Okta, Auth0 or KeyCloak) and as well as with Windows Authentication.
The login screen looks as follows:
Figure 7-9
In order to use SSO with Windows Authentication, this Microsoft Windows feature needs to be
installed on the server and activated in Microsoft Internet Information Server.
In order to use SSO the machine name of the application server must be set in the
configPanel Settings > General > Web Host Name

If you are running in an environment with more than one domain, the domain name has to be
added to the machine name e.g. llsdemo.lorenz.local. In this case the created desktop link for
the adminPanel on the application server gets invalid and a new link must be created manually.
7.7.2 Single Sign On (SSO) across domains
When the Foundation Server instance and other LORENZ Applications are installed in
different domains, the Single Sign On mechanism is not working due to the issued domain in
the browser cookie.
Figure 7-10
To overcome this issue, it is possible to introduce an HTTP proxy server and route the
application traffic over the foundation server. With this, the user client will stay always inside
the same domain and the browser cookie remains valid.

Figure 7-11
To configure HTTP proxy functionality please make sure to install 'Application Request Routing
(ARR)' on the IIS of the Foundation server, see here:
https://www.iis.net/downloads/microsoft/application-request-routing
As first step for configuration, a new server farm needs to be created in the IIS Manager. The
server in that new farm must point to the server where the other LORENZ application is
hosted, e.g. “Automator.us.dev.local”. As next to rewrite the request URLs, there need to be
2 individual rules configured:
1. Add an inbound rule to route forward the traffic for the specific application:
Use match pattern option with “Wildcard” and the pattern could be like the URL of the
LORENZ product, e.g. '*Automator_webPanel*'.
Set the Action “Route to Server Farm” and choose the name of the server you want to
route to, in addition define the Path-Option as '/{R:0}'.
Repeat these steps for each of the products or servers you like to route traffic to.
2. Add an inbound rule to skip any other traffic:

Use match pattern option with “Wildcard” and the pattern could be like the URL of the
LORENZ product, e.g. '*'.
Set the Action “None”.
To finalize the configuration, please reboot the IIS and test the URLs.
7.8 Password Policy

For user accounts with Foundation authentication, the password policy can be defined using
the configPanel. For user accounts with network authentication, the password policy is not
part of Foundation and needs to be configured through the corresponding authority (e.g.
Active Directory). An exception is the maximum number of failed logon attempts, which
applies in both scenarios.
To configure the password policy with the configPanel:

1. Start the configPanel and select General > Password Policy.

2. You can now view and edit every single password parameter. When you are
finished, click the Save button to save the changes you made.
3. The changes will take effect when you restart the services.
7.9 User Authorization

In Foundation, the user authorization is based on the functions (please see section 7.2.4)
assigned to a given user account (please see section 7.1). Whenever a system function is
requested by a user, the system will check the role (please see section 7.1.7) membership
for this user. If the user has a role assigned that includes the requested function, the access
to the corresponding feature is granted. If no such role can be found, access will be denied.
7.10 User Licenses

The LORENZ Foundation provides the possibility to use “Named User Licenses” or
“Concurrent User Licenses” when logging into individual LORENZ Products.
The way users can log into the Foundation depends on the user licensing model chosen in
their LORENZ solution. It is possible that one product’s licensing uses the concurrent license
model while at the same time a second LORENZ product uses the named license model.
With “Concurrent User Licenses”, there will be a set number of users that will be able to log
into the Foundation simultaneously, regardless of their User ID.
With “Named User Licenses”, there is a limit for the number of users that can be added to the
database through the adminPanel user management dialogue.
By default, all users created will be assigned to a concurrent license. To assign a user to a
dedicated named license please follow these steps:
1. Click the Users Menu Item in the User Management group.

2. Click the User Name to display the details.
3. Click the Edit button of the LORENZ product you want the user to use a Named
License.
4. In the drop-down field for the Named License select “yes” and click the “Update”
button.
An overview of currently assigned Named Licenses can be viewed in the “Named Licenses
Assignment” menu of the adminPanel.
Changing the functions in a Role that are used by users can affect the current Named License
assignment. In case the change leads to an upgrade of the license level and no Named
Licenses of this license level are available, a warning is displayed in the adminPanel. The user
must resolve this conflict manually, otherwise no users will be able to login until this conflict has
been resolved.

8. RESTful Application Programming Interface (API)

LORENZ Foundation offers a so called Application Programming Interface via REST. By
using this interface, functionality of the Foundation can be managed via external applications.
For instance, it is possible to create a user account and grant permissions via the user
management endpoint.
The full documentation for all the endpoints and methods is supplied via a swagger URL
(please see https://swagger.io/ for details). To access the documentation at the specific
Foundation instance please open the URL https://[hostname]/api/core/swagger/ . The
hostname is the machine name by default, but can be configured in the configPanel →
General → Web Hosting → Web Host Name.
The API is versioned and LORENZ will support multiple versions at the same software
release. To access the different available versions of the API, please use the “Select a
definition” drop-down menu on the upper right of the swagger page:
8.1 Authentication
To use the API, a valid session using a user account has to be established first. Therefore a
log-in call to the web login resource has to be performed using a POST Method to this URL:
https://[hostname]/lorenz.webLogin/api/[version]/login/login .
As a request body to this call, “UserName” and “Password” of a valid user account has to be
supplied in json format. The respond of this log-in call will contain the LORENZ SSO Cookie,
which needs to be attached to any further call to the API.

Some changes to the system done via the API will be recorded at the Audit Trail as well as in
the database of Foundation. It´s recommended to use an explicit account for interacting via the
API to have a clear traceability for the origin of activities at the system.

9. Additional Information
9.1 Service Ports
9.1.1 Port List
Foundation communicates through the following ports with the listed services:
Service Port
Core Services 8000-8005
Table 9-1
9.1.2 Port Sharing
It is possible to configure the LORENZ services to share a single port in order to reduce the
number of ports that must be opened in the firewall.
Port Sharing will only work if the LORENZ services are configured to run under the LocalSystem
account.
The Net.TCP Port Sharing Service which is installed on Windows by default must be
manually enabled:
1. From the Start menu, open the Services Management Console either by opening a
Command Prompt window and typing services.msc or by opening Run and typing
services.msc into the Open box.
2. Right-click the Net.TCP Port Sharing Service and select properties from the menu.
3. In the Properties window select the General tab and in the Startup type box select
Automatic.
4. To start the service, in the Service status area, click the Start button. The service
status should now display "Started".
Navigate to '%ProgramData%\Lorenz Life Sciences\Foundation\CoreServices' and open the

file “servers.xml”. Add the attribute “portSharingEnabled” to the root element “primaryServer”
and set it to true:
<primaryServer portSharingEnabled="true"
tcpBasePort="8000"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../schemas/servers.xsd">
Code 9-1
After restarting the services, they will all share the tcpBasePort defined in the “servers.xml”.
In order to login with a client, it is also required to update the file “user_login.xml” located at

“%ProgramData%\Lorenz Life Sciences\Foundation\CurrentConfig” on the client machine.

Either modify the file by replacing the port of the instance with the tcpBasePort or run the
Server discoverability (see 9.2) functionality to automatically update the file.
9.2 Server discoverability

The Server discoverability feature makes primary servers discoverable for clients like the
docuBridge Client which can find them in the network without knowing their address.
Server Discoverability is configured in the LORENZ configPanel → Settings → General →

Login Configuration Retrieval; please set 'Enable Discovery' to 'yes', if you would like the
clients to be able to connect to any foundation servers in the same Network (e.g. for
docuBridge Clients).

10. Troubleshooting
10.1 None of the services can be started

If none of the Foundation services can be started, please check the following:
The CoreServices component is the root component for the Foundation system. All other
Foundation services depend on this service (directly or indirectly). So you should start
focusing on analyzing why the CoreServices could not be started.
Possible Causes:
• Database version is not correct

o Check via configPanel > Database Connectivity
• Configuration Files are invalid
o Check via configPanel > Validation
• License file is not installed
o Check via configPanel > License
10.2 Cannot install license with configPanel

Symptom:
When you try installing a new license with the configPanel application, you get an error
message “The requested license file is invalid and cannot be loaded.”
Resolution:
The user account configured for running the CoreServices must have “read” access to the
license file you want to install. Furthermore, this account needs “write” access to the
foundation configuration folder root (the folder where the file license.lic is stored).
10.3 Service Session Timeouts

The default session timeout for a service system session is 600 seconds.
This can be overwritten by specifying a time in seconds in the corresponding service config
file by adding the 'CoreServicesSessionTimeout' AppSetting.
Example:
Foundation Explorer Service – Timeout 300s:
• File: %PROGRAMFILES\Lorenz Life

Sciences\Foundation\Services\ExplorerService\ExplorerService.exe.config
<?xml version="1.0" encoding="utf-8" ?>

<configuration>
<appSettings>

<add key="CoreServicesSessionTimeout" value="300" />

</appSettings>
</configuration>
Code 10-1
If the corresponding config file does not exist in the folder it needs to be created.
10.4 Performance issues in disconnected environments

This section is relevant if you experience issues regarding Foundation services starting
extremely slow or not at all in environments with network connectivity but no internet access.
Background: the standard configuration of our services is using transport security since
version 5.6.0.07 / 5.6.1.0 to improve performance (compared to message security). However,
as soon a WCF service uses transport security for the client connections, Microsoft Windows
checks if certificate information of the operating system is up to date before establishing the
connection. If the certificate information is not up to date Microsoft Windows will try to
download it from ‘ctdl.windowsupdate.com’. If the OS has no access to this site, this
download attempt can be blocking for 15 seconds. In the meantime, several other timeouts
within security handshake can be hit and can make the connection attempt fail completely. In
this case one will likely see ‘socket connection has been aborted’ errors in the log files.
The following Microsoft articles explains in detail what to do: Configure Trusted Roots and
Disallowed Certificates.
Another option is to switch back to Message security. To do this, you need to change all
settings in all service config files.
Example:
Foundation Explorer Service:
• File: %PROGRAMDATA%\Lorenz Life Sciences\Foundation\WCF\

ExplorerService.exe.config
Change @:
/configuration/system.serviceModel/bindings/netTcpBinding/
binding/security
From:
<configuration>
<system.serviceModel>
<bindings>
<netTcpBinding>
<binding … >
<security mode="TransportWithMessageCredential">
<message clientCredentialType="UserName" />
</security>

To:
<configuration>
<system.serviceModel>
<bindings>
<netTcpBinding>
<binding … >
<security mode="Message">
<message clientCredentialType="UserName" />
</security>
Code 10-2

LORENZ Life Sciences Group
Internet: www.lorenz.cc | E-Mail: www.lorenz.cc/email
LORENZ Archiv-Systeme GmbH LORENZ Life Sciences Ltd. LORENZ Polska

Eschborner Landstrasse 75 No. 1 Farnham Road APC Instytut Sp. z o.o.
60489 Frankfurt/Main Guildford, Surrey GU2 4RG Al. Jerozolimskie 146 c
GERMANY UNITED KINGDOM Warsaw 02-305
POLAND
Tel +49 69 78 991-901 Tel +44 14 83 903 861 Tel +48 22 6686 823
Fax +49 69 78 991-129 Fax +44 20 76 812 676 Fax +48 22 6689 981
LORENZ International LLC LORENZ Life Sciences India Pvt Ltd. Digital Media System Co., Ltd.
1515 Market Street, Suite 1200 Olympia Tech Park, Level -2, Altius Tsukiji No. 1
Philadelphia, PA 19102 No: 01, Sidco Industrial Estate Nagaoka Building 2-3-4
USA Ekkatuthangal, Guindy Tsukiji, Chuo-ku, Tokyo 104 - 0045
Chennai-600 032 JAPAN
Tel +1 866 9567 369 INDIA
+1 866 9LORENZ Tel +91 44 42 994 219 Tel +81-3-5550 5595
Fax +1 866 2956 967 Fax +91 44 42 994 310 Fax +81-3-5550 5596

LORENZ Foundation Administrator Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

LORENZ Foundation Administrator Guide

Uploaded by

Copyright:

Available Formats

Administrator Guide

3.1 License overview....................................................................................................34

6.9.2 Client-Side Logging .........................................................................................54

7.6.4 OpenID Connect .............................................................................................74

The following trademarks of other companies may appear in this document:

Acrobat is a trademark of Adobe Systems Inc.

© LORENZ Life Sciences Group 6

1.1 How this guide is organized

1.2 General system architecture

• Authentication of users and system components

The LORENZ Foundation distinguishes between three different machine roles:

Primary Server Hosting the CoreServices and configuration data

© LORENZ Life Sciences Group 7

1.3 Utilities for Administrators

1.3.1 LORENZ adminPanel

Where “MY_APPLICATIONSERVER” is the name or IP address of the application server

© LORENZ Life Sciences Group 8

The adminPanel menu structure is:

1.3.2 LORENZ configPanel

© LORENZ Life Sciences Group 9

The configPanel can be used for the following tasks:

• Initial configuration of the system after installation.

© LORENZ Life Sciences Group 10

2.1 General Installation Principles

2.2 Installing the LORENZ Foundation

2.2.1 Preparatory Work

2.2.1.1 Availability of Installation Sources

2.2.1.2 Locations for Binaries and Shared Data

2.2.1.3 Database Availability

© LORENZ Life Sciences Group 11

2.2.1.4 Database Connectivity

• ORACLE Data Access Components (ODAC) for .Net 4

2.2.1.5 Operating System Prerequisites

As mentioned in the System Requirements Document, the operating system of the

2.2.1.6 Availability of Account Information

• User with administrator privileges for the installation

2.2.2 Installing a Foundation server

To install the Foundation server, perform the following steps:

1. Launch the Foundation Installer and install the required components.

2. Configure the configPanel’s “Settings” section as required

© LORENZ Life Sciences Group 12

2.2.3 Upgrading a Foundation server

To upgrade a Foundation server, perform the following steps:

1. Stop all LORENZ services via the configPanel.

2.2.4 Silent Installation possibilities

Parameter Description Value

© LORENZ Life Sciences Group 13

Parameter Description Value

2.2.4.1 Installation example

msiexec /i "C:\Install\Lorenz Foundation.msi" ADDLOCAL=ALL

2.2.4.2 Uninstallation example

msiexec /x "C:\Install\Lorenz Foundation.msi" /q /l

2.2.4.3 Upgrade installation example

msiexec /i "C:\Install\Lorenz Foundation.msi" ALLUSERS=1

© LORENZ Life Sciences Group 14

2.3.1 Database conceptual overview

• Microsoft SQL Server

© LORENZ Life Sciences Group 15

Microsoft SQL Server

© LORENZ Life Sciences Group 16

2.3.2 Database setup

1. Create database instance (manually)

2.3.2.1 Create database instance

A dedicated database instance (Oracle) or MsSql/PostgreSQL Catalog is needed per