DIgSILENT

PowerFactory 2018

Advanced Installation and Configuration Manual

I N T EG R AT E D P O W E R S Y S T EM A N A LY S I S S O F T WA R E F O R
T R A N S M I S S I O N / D I S T R I BU T I O N / I N D U S T RY / G EN E R AT I O N / I N T EG R AT I O N O F R EN E WA B L E S
 DIgSILENT GmbH
Heinrich-Hertz-Straße 9
72810 Gomaringen / Germany
Tel.: +49 (0) 7072-9168-0
Fax: +49 (0) 7072-9168-88
info@digsilent.de

Please visit our homepage at:

http://www.digsilent.de

Copyright ©2017 DIgSILENT GmbH

All rights reserved. No part of this
publication may be reproduced or
distributed in any form without permission
of DIgSILENT GmbH.

November 29, 2017

PowerFactory 2018
Revision 3
 CONTENTS

Contents

1 Introduction 1

1.1 Typographic Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.3 DIgSILENT Download Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.4 Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.5 Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.5.1 PowerFactory 2017 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.5.2 PowerFactory 2016 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2 PowerFactory Editions Overview 3

3 System Requirements 5

3.1 PowerFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3.2 Network Licence Server (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4 Advanced Installation Options 7

4.1 Licence Server Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4.1.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4.1.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

4.1.3 Licence Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

4.2 Workspace and Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

4.2.1 Export and Import Workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4.2.2 Workspace Directory Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4.3 Multi-User Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4.3.1 Installation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4.3.2 Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

DIgSILENT PowerFactory 2018, Advanced Installation and Configuration Manual i

CONTENTS

4.3.3 Microsoft SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4.3.4 Vault (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

4.3.5 Housekeeping (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

4.4 Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

4.4.1 Workspace directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

4.4.2 PowerFactory Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

4.5 Offline Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

4.5.1 PowerFactory in Normal Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

4.5.2 Offline Proxy Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

4.5.3 PowerFactory Offline Mode Configuration . . . . . . . . . . . . . . . . . . . . . . 36

4.5.4 PowerFactory Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

4.6 Database Read-only Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

4.7 Database in-memory Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

4.8 Active Directory Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

4.8.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

4.8.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

5 Licence Management 49

5.1 Network Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

5.1.1 HTTP Proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

5.1.2 Firewall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

5.2 Virtual Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

5.3 Activating a Licence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

5.4 Updating a Licence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

5.5 Moving a Licence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

5.6 Selecting a Licence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

5.7 Hot Standby Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

5.8 Floating Licences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

6 Upgrade and Migration 59

6.1 Licence Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

6.1.1 Using PowerFactory 15.2 or earlier with a PowerFactory 2017 Licence . . . . . 59

6.2 Upgrade PowerFactory Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

ii DIgSILENT PowerFactory 2018, Advanced Installation and Configuration Manual

 6.3 Data Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

6.3.1 Local Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

6.3.2 Multi-User Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

6.3.3 Complete vs. Minimal Database Migration . . . . . . . . . . . . . . . . . . . . . . . 63

7 Reference 67

7.1 PowerFactory Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

7.2 PowerFactory Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

7.2.1 General Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

7.2.2 Database Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

7.2.3 Workspace Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

7.2.4 External Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

7.2.5 Network Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

7.2.6 Geographic Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

7.2.7 Advanced Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

7.3 PowerFactory Command Line Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 76

7.3.1 /config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

7.3.2 /housekeeping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

7.3.3 /ini . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

7.3.4 /lang . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

7.3.5 /migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

7.3.6 /readonlymode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

7.3.7 /inMemory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

7.3.8 /username, /password, and /passwordHash . . . . . . . . . . . . . . . . . . . . . 77

7.4 PowerFactory Silent Installation Options . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

7.4.1 Command line options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

7.4.2 Error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

7.4.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
 CHAPTER 1. INTRODUCTION

Chapter 1

Introduction

1.1 Typographic Conventions

Typographical conventions used in this document:

• Products of DIgSILENT GmbH are printed in bold italic.

• Third party products are printed in bold.
• File names, directories, listings and values the user is asked to enter are written in fixed width
font.

• Button and window captions or menu entries the user is asked to click or select are written in bold
fixed width font.
• Menus and sub menu structures are denoted by an arrow → in front of the first element and all
following sub entries e.g. Menu → Sub Menu→ Sub Sub Menu.

1.2 Overview

Depending on the installation type, a PowerFactory system can have several components which have
to be installed and configured separately.

• The Getting Started document covers the basic installation options.

• More advanced installation options e.g. multi-user database, installation on an application server,
and the Offline mode installation are covered in this document.

1.3 DIgSILENT Download Area

Additional Software, Documents, and Examples for PowerFactory can be downloaded from the Down-
load Area on the DIgSILENT website
http://www.digsilent.de/index.php/downloads.html

Please note that access to the Download Area is granted for registered users only. The user registra-
tion can be done via the support page http://www.digsilent.de/index.php/support.html.
It initially requires the input of the company credentials that can be found in the licence agreement
document.

DIgSILENT PowerFactory 2018, Installation Manual 1

CHAPTER 1. INTRODUCTION 1.4. KNOWLEDGE BASE

1.4 Knowledge Base

A “Knowledge Base” database of information, based on an FAQ format, is available for any users
(whether registered or not) to look for answers to their questions.

Knowledge Base: http://faq.digsilent.de/powerfactory.html

1.5 Changes

1.5.1 PowerFactory 2017

• Due to PowerFactory ’s dependence on CodeMeter, the .NET 4.5.1 runtime and the Visual C++
Redistributable, the installer package has been further extended and now uses the common boot-
strapper approach. Its format has therefore changed to a standard executable.
• Oracle ODBC client is now supported (see section 4.3.2.5 on page 16).
• It might be necessary to update existing licences in order to access full functionality of Power-
Factory 2017. At the end of the installation process, the Licence Manager will be launched
allowing for an online search for updates (see section 5.4 on page 53 for more details on licence
updates).
• A new Upgrade Assistant allows to transfer the applications settings (e.g. workspace directory,
database settings...) of an already existing installation. The older installation must be from version
2016 or higher to be found by the Upgrade Assistant.

1.5.2 PowerFactory 2016

• PowerFactory now uses the Windows Installer Engine and is therefore shipped as MSI package.

• The installation procedure has been greatly simplified.

• The whole licensing is now based on WIBU CodeMeter® technology.

2 DIgSILENT PowerFactory 2018, Installation Manual

 CHAPTER 2. POWERFACTORY EDITIONS OVERVIEW

Chapter 2

PowerFactory Editions Overview

The Single User Edition is intended to be installed on a workstation with a local dongle or softkey.

Figure 2.0.1: Single User Edition

The Multi User Edition allows for a dedicated licence server to be used. Such a licence server provides
easy licence sharing and concurrent work for multiple users1 within same local network.

Figure 2.0.2: Multi User Edition

1 Depending on the number of licensed concurrent users.

DIgSILENT PowerFactory 2018, Installation Manual 3

CHAPTER 2. POWERFACTORY EDITIONS OVERVIEW

The Team Edition extends the PowerFactory system architecture with a database server for cen-
tralised storage. It consists of a central licence server and allows usage of a central multi-user database.

Figure 2.0.3: Team Edition

4 DIgSILENT PowerFactory 2018, Installation Manual

 CHAPTER 3. SYSTEM REQUIREMENTS

Chapter 3

System Requirements

3.1 PowerFactory

DIgSILENT PowerFactory is an application for standard Windows® operating systems. Both a 32-
bit and a 64-bit version are available. For running PowerFactory efficiently the computer should be
equipped with, as a minimum:

• Operating system:
– Windows Vista / Windows 7 / Windows 8 / Windows 10
– Windows Server 2008(R2) / Windows Server 2012(R2) / Windows Server 2016
– .NET Framework 4.5
– The 64-bit version of PowerFactory requires a 64-bit operating system
– The 32-bit version will run on both architectures
Note: Installation on Windows 8.1 and earlier operating systems requires KB2999226. To install
through Windows Update, make sure you install the latest recommended updates and patches
from Microsoft Update before you install the Windows SDK.

• Processor with 2 GHz

• Main memory of 2 GB RAM
• Hard disk space of 2 GB plus additional 5 GB per user

• SVGA graphic card with a resolution of at least 1280x1024 pixels

Additional requirements:
• Internet connection for licence activation, transfer and regular licence validity checks (every 30
days)

• Administrator privileges for the installation process

Optional requirements for data export / import:

• MS Excel 2003 or newer

• MS Access 2003 or newer with ODBC drivers with the same architecture (32 or 64 bit) as Power-
Factory

DIgSILENT PowerFactory 2018, Installation Manual 5

CHAPTER 3. SYSTEM REQUIREMENTS 3.2. NETWORK LICENCE SERVER (OPTIONAL)

Optional requirements for Multi-User Database

• Microsoft SQL Server Database

– SQL Server 2008 or newer
– ODBC drivers for SQL Server (typically shipped with the operating system)

• Oracle Database
– Oracle server 10g, 11g, or 12c
– Client libraries version 12c Release 1 with the same architecture (32 or 64 bit) as PowerFac-
tory (both full client and Instantclient are supported)

3.2 Network Licence Server (optional)

For network licences it is recommended to set-up a dedicated network server. The machine should fulfil
requirements as follows:

• Dedicated server:
– The server machine should be used exclusively for PowerFactory .
– Virtualisation:
* For softkey licences, a physical machine is required.
* For dongle based licences (hardlock) a virtual machine can be used (in conjunction with
an appropriate USB dongle server, see 5.2).

• Operating system:
– Windows Vista / Windows 7 / Windows 8 / Windows 10
– Windows Server 2008(R2) / Windows Server 2012(R2) / Windows Server 2016
– .NET Framework 4.5

• Processor: x86- or x64-bit with 1 GHz or faster

• Memory: 2 GB RAM minimum

Additionally:

• Fast network with short latency (100 Mbit/s or higher) connection between the licence server and
the machines where PowerFactory is running.
• Internet connection for licence activation, transfer and regular licence validity checks (every 30
days)

• Administrator privileges for the installation process

See also 4.1 for installation and configuration.

6 DIgSILENT PowerFactory 2018, Installation Manual

 CHAPTER 4. ADVANCED INSTALLATION OPTIONS

Chapter 4

Advanced Installation Options

The installation variants in this chapter usually make only sense in a multi-user context with PowerFac-
tory running in a server environment.

• Instead of activating a workstation licence on each computer with a PowerFactory installation,

you can use a central licence server that provides a network licence for all users in your network
(see section 4.1 on page 7).
• PowerFactory stores user data in a Workspace on the hard disk. The Workspace functionality is
described in section 4.2 on page 8.
• A multi-user database allows several PowerFactory users to work concurrently and share their
data (see section 4.3).
• Several users can work on the same application server (see section 4.4 on page 25).

• Offline Mode is based on a multi-user database. It allows to run PowerFactory without a perma-
nent connection to the server (see section 4.5 on page 27).

4.1 Licence Server Components

Running PowerFactory requires a valid licence. This can either be a workstation licence that is acti-
vated on the same machine as the PowerFactory installation, or a network licence that is granted by a
licence server in your local network.

This section describes the installation and configuration process of a PowerFactory licence server.

Note: A licence server typically provides a network licence for a number of client machines (Multi User
or Team Edition licence). Although it is possible to install a workstation licences on a server
machine, this licence will not be accessible by client computers in your network.

4.1.1 Installation

Please run the Licence Server Components installer and follow the on-screen instructions which will
guide you through the installation process. The following components are installed:

• WIBU CodeMeter® Runtime Server as Windows service

DIgSILENT PowerFactory 2018, Installation Manual 7

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.2. WORKSPACE AND BACKUP

• Licence Manager required for activating the network licence on the server machine
• Installer package for Legacy Licence Service . This service allows PowerFactory 15.2 or 15.1
versions to be executed with a recent PowerFactory licence. A separate installation is required.
See 6.1.1.
• Licence Validation Service as a windows service. The installation of this service is optional.
It performs regular online validation locally from the licence server without the need to configure
online access on any PowerFactory client.

4.1.2 Configuration

For network licences, two settings are critical:

• Correctly configured internet connection: see 5.1 for details.

• Licence server status: for a server licence to be visible in the local network, it is mandatory to start
a licence server on the server machine. The installation process includes steps to automatically
start the licence server. However, if problems with licence visibility occur, the licence server status
can be reviewed in a separate tab of the network settings dialog (see 4.1.1).

Figure 4.1.1: Licence Server Status

4.1.3 Licence Management

The handling of a network licence regarding activation, update, and moving does not differ from that of a
workstation licence. Please follow the instructions given in Section 5.3 in order to activate your network
licence on the server machine.

Once the licence has been activated, it should automatically be detected by all PowerFactory installa-
tions on computers in your local network. If a client machine has trouble to access the network licence,
explicitly select the network licence on that computer as described in Section 5.6.

4.2 Workspace and Backup

PowerFactory stores data in a workspace directory in the Windows user profile. When a user named
Frodo runs PowerFactory , the application data is stored usually in e.g.

8 DIgSILENT PowerFactory 2018, Installation Manual

4.2. WORKSPACE AND BACKUP CHAPTER 4. ADVANCED INSTALLATION OPTIONS

C:\Users\Frodo\AppData\Local\DIgSILENT\PowerFactory 2017\Workspace.ComHLsIb

The workspace directory contains

• The local database including all projects and libraries.

• Result files (e.g. results of simulation calculations)
• Log files which are very useful when analysing application problems.
• Temporary files.

4.2.1 Export and Import Workspace

It’s possible to manipulate e.g. backup and copy Workspace directories directly. However PowerFac-
tory provides functionality for saving a workspace (including all files in all subdirectories) as a conve-
nient *.zip archive which can be used as data backup. Similarly an exported workspace *.zip file
can be easily be re-imported into the same PowerFactory installation (i.e. restoring a backup) or into
a completely different PowerFactory installation on another computer (data transfer, data migration).

The workspace functions are available in the TOOLS → Workspace sub menu:

• TOOLS → Workspace→ Show Workspace Directory: opens a Windows Explorer showing the
workspace directory.
• TOOLS → Workspace→ Export Workspace: packs your workspace into ZIP archive. This may
take some time.
• TOOLS → Workspace→ Import Workspace: deletes your current workspace and replaces it with
a workspace ZIP archive.

Note: It’s strongly suggested to create workspace backups on a regular basis.

Note: A Workspace import replaces the current Workspace with the imported Workspace i.e. the
current Workspace is completely deleted and can not be recovered.

4.2.2 Workspace Directory Configuration

Storing the Workspace in the Windows user profile is convenient, but it might not be suitable under
some special circumstances. Customers might want to choose a different Workspace directory:

• A company-wide policy recommends that application data should be stored inside a given direc-
tory (e.g. D:∖Data) which is part of the company-wide backup strategy.
• Several Windows users e.g. Frodo, Sam, and Pippin want to work on the very same local
database. Though they can’t work concurrently at the same time, they might work in turns. Then
the workspace should be in a directory accessible by all three users.
• Several Windows users are running PowerFactory concurrently on an Application Server. The
installation on Application Server is described in section 4.4 on page 25.

Under these circumstances it makes sense to adapt the Workspace directory, see section 7.2.3 on
page 71 for details.

DIgSILENT PowerFactory 2018, Installation Manual 9

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.3. MULTI-USER DATABASE

Note: We strongly advise not to use a network share for the Workspace directory if the local database
driver is used. Using a network share under these circumstances might lead to data loss.

4.3 Multi-User Database

Normally PowerFactory stores the user data in a local database on the computer where PowerFactory
is installed. This means if multiple users want to work on the same project, one has to export it into a
file and another one has to re-import the copy into his database (see figure 4.3.1).

Figure 4.3.1: Local Databases

In a multi-user database all data is stored in one central database server (see figure 4.3.2).

Figure 4.3.2: Multi-User Database

Advantages of a multi-user database are

• read-only or read-write sharing of projects

• project locking mechanisms
• better organisation of company-wide data (e.g. library, DPL scripts, template projects)
• backups have to be taken only from one database

PowerFactory supports two common commercial database systems:

• Oracle Database Server (see section 4.3.2 on page 11)

• Microsoft SQL Server (see section 4.3.3 on page 17)

10 DIgSILENT PowerFactory 2018, Installation Manual

4.3. MULTI-USER DATABASE CHAPTER 4. ADVANCED INSTALLATION OPTIONS

4.3.1 Installation Overview

Generally, the following steps are required for setting up a multi-user environment:

1. Install PowerFactory (see section 4.4 on page 25). Verify that the application runs smoothly
before proceeding with the next actions
2. Install and configure Oracle Database Server (see section 4.3.2 on page 11) or Microsoft SQL
Server (see section 4.3.3 on page 17) and configure connection settings in PowerFactory
3. (Optionally) Set up and configure a Vault directory (see section 4.3.4 on page 21)
4. Administrate the PowerFactory database e.g. create PowerFactory user accounts and user
groups.
5. (Optionally) Import projects, libraries, or other data from other PowerFactory installations

4.3.2 Oracle

4.3.2.1 Requirements

PowerFactory uses Oracle’s OCCI/OCI programming interface to communicate with the server. OCCI/OCI
itself uses a proprietary communication scheme on top of TCP/IP.

PowerFactory supports Oracle versions as shown below:

• Server: 10g, 11g, or 12c

• Client: 12c Release 1:
– PowerFactory 32bit (x86) requires the 32bit Oracle Client and Visual C++ Redistributable
Packages for Visual Studio 2013
– PowerFactory 64bit (x64) requires the 64bit Oracle Client and Visual C++ Redistributable
Packages for Visual Studio 2013

Hint: For installations on Windows Server 2016 the Visual C++ Redistributable Packages for Visual
Studio 2012, 2013 and 2015 will additionally be required. These can be obtained directly from:
https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads

Server Requirements: The Oracle server machine should fulfil requirements as follows:

• Dedicated server: the server machine should be used exclusively for PowerFactory .
• CPU: two or more cores/processors
• Memory: 2GB RAM or more
• Hard disk: 100 GB or more
• High network bandwidth (100 Mbit/s or higher) connection between the Oracle server and the
machines where PowerFactory is running.

Depending on the number of users and projects the above numbers have to be adapted.

This section describes the installation and usage of the Oracle database server and client.

Before you set up and configure the client computers in section 4.3.2.3 (Client Installation), the server
must be prepared as explained in section 4.3.2.2 (Server Installation).

DIgSILENT PowerFactory 2018, Installation Manual 11

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.3. MULTI-USER DATABASE

4.3.2.2 Server Installation

Install the Oracle server software on the server computer (ORACLESERVER being the server computer
name used in this section). Please follow the Oracle Server installation instructions.

Let us assume that ORACLESERVER is accessible by the name oracleserver.domain.com in the net-
work. In order to use the Oracle server for PowerFactory you have to do the steps as follows:

• Create a new Oracle database with a database name (SID) of PFSERVER (stands for: Power-
Factory Server) or use an existing one. The character set for the Oracle instance should be
WE8MSWIN1252.

– An Oracle listener is needed on the server, in order to pass on connection requests from
clients to the database. If you created the database with the Oracle installer, the listener
is configured for you automatically. If you create the database manually, then configure the
listener using the Oracle Net Configuration Assistant tool.
– (Recommended but not essential) create the database with redo log files sized at 500MB.
• PowerFactory needs a place to store its data. Oracle stores data in so-called tablespaces. It is
suggested to create a new tablespace where PowerFactory (and only PowerFactory) stores its
data. You might adapt and use the SQL statement below to your purposes:

CREATE TABLESPACE "POWERFACTORYTABLESPACE"

LOGGING
DATAFILE ’D:\ORACLE\ORADATA\DIGSI\POWERFACTORYTABLESPACE.ora’
SIZE 5000M REUSE
EXTENT MANAGEMENT LOCAL

The statement creates a new tablespace named POWERFACTORYTABLESPACE which is stored in a

POWERFACTORYTABLESPACE.ora file in the given directory. The file size is restricted to 5000M i.e. about
5GB.

 In order to use the Oracle instance for PowerFactory one new Oracle schema is required. Create
a new schema with the default profile. We suggest the schema name PF.
 Define a password for PF. In this example we use aPasswordForPf.
 Associate default and temporary tablespaces to schema PF. It is assumed that a temporary ta-
blespace TEMP is available.

 Grant the roles CONNECT and RESOURCE and the system privileges UNLIMITED TABLESPACE and
ALTER SESSION to PF. You might use and adapt the SQL script below to create the schema:

CREATE USER PF
PROFILE DEFAULT
IDENTIFIED BY aPasswordForPf
DEFAULT TABLESPACE POWERFACTORYTABLESPACE
TEMPORARY TABLESPACE TEMP
ACCOUNT UNLOCK;

GRANT UNLIMITED TABLESPACE TO PF;

GRANT CONNECT TO PF;
GRANT RESOURCE TO PF;
GRANT ALTER SESSION TO PF;

 Start the Oracle instance process and Oracle listener process if they are not already started.

12 DIgSILENT PowerFactory 2018, Installation Manual

4.3. MULTI-USER DATABASE CHAPTER 4. ADVANCED INSTALLATION OPTIONS

Note: The amount of tablespace space PowerFactory requires depends heavily on how PowerFac-
tory is used. The space is roughly proportional to the number of objects in PowerFactory .
Observe the tablespace fill-state regularly (e.g. once per month) and increase the size limit ac-
cordingly.

Note: Regarding the recommended sizing of the redo log files when creating the database; this con-
figuration of the redo log files is to increase performance. PowerFactory can generate very large
quantities of redo data in short bursts. This is particularly the case when importing data, copying
large projects or deleting large projects. If for other reasons you require smaller redo log files, (for
example to reduce database recovery time), you should increase the number of log file groups as
an alternative to increasing the file size.

Note: It is highly recommended to backup the Oracle schema on a daily basis. A backup procedure is
described in section 4.3.2.6 on page 17

4.3.2.3 Client Installation

Two Oracle client packages can be used:

• (Normal) Oracle Client: This package includes many Oracle tools (e.g. management console,
management tools, networking services, utilities etc.) which are not actually required for using
PowerFactory ; supports TNS names.
• Oracle Instant Client: This package contains only the files required for using PowerFactory ;
doesn’t support TNS names.

Both (normal) Oracle Client and Oracle Instant Client are available for 32bit applications and 64bit
applications. PowerFactory 64bit requires a 64bit Oracle Client; PowerFactory 32bit requires a 32bit
Oracle Client.

Note: The required architecture of Oracle Client depends on PowerFactory only. This is not neces-
sarily identical to the architecture of the Windows operating system. E.g. PowerFactory 32bit
requires Oracle Client 32bit even if executed on Windows 64bit.

Install and configure Oracle Instant Client

Instant Client is a package of DLL files which can be downloaded freely from the Oracle website. The
package names are:

• 32bit: instantclient-basic-nt-12.1.0.1.0.zip
• 64bit: instantclient-basic-windows.x64-12.1.0.1.0.zip

The packages are ZIP archives that can be extracted anywhere e.g. to c:∖instantclient 12 1 (see
figure 4.3.3). PowerFactory uses these DLL files in order to communicate with the Oracle Database
server.

DIgSILENT PowerFactory 2018, Installation Manual 13

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.3. MULTI-USER DATABASE

Figure 4.3.3: Database Figure: Oracle Instant Client installation directory

Install and configure (normal) Oracle Client

• Please use the newest version of the 12.2 client and follow the installation documentation. When
asked for choose to install the ”Runtime” installation option. It is assumed that the client software
is installed in C:∖app∖client∖product∖12.1.0∖client 1 (see figure 4.3.4).

Figure 4.3.4: (Normal) Oracle Client installation directory

• (Optionally) It’s possible to add an TNS name entry for PFSin the configuration file

C:\app\client\product\12.1.0\client_1\network\admin\TNSNAMES.ORA

The entry could be e.g.

PFS =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)(HOST = oracleserver)(PORT = 1521))
)
(CONNECT_DATA =
(SERVICE_NAME = PFSERVER)

14 DIgSILENT PowerFactory 2018, Installation Manual

4.3. MULTI-USER DATABASE CHAPTER 4. ADVANCED INSTALLATION OPTIONS

)
)

Then the PFS TNS name can be used in the PowerFactory configuration.

4.3.2.4 PowerFactory Configuration via Client Libraries

Start PowerFactory in configuration mode (see refsectionsec:conf).

 Switch to the Database page

 Insert the database connection settings as described below:

Figure 4.3.5: PowerFactory Configuration for Oracle Server

Database driver select Oracle (Client Version 12.1)

Database service this field describes the connection. It must be conform to the format

//host[:port][/servicename]

With the values used above (host=oracleserver, port=1521 (default port), and SID=PFSERVER)
the connection name is

//oracleserver/PFSERVER

If we had used a non-default port=8888 the connection name would be

//oracleserver:8888/PFSERVER

If you’ve installed a (normal) Oracle Client and made an entry (e.g. PFS) in the TNSNAMES.ORA
configuration file, you can use the TNS name instead. Then the Database service is just

PFS

DIgSILENT PowerFactory 2018, Installation Manual 15

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.3. MULTI-USER DATABASE

Username and Password During the Oracle server setup an Oracle schema PF with the password
aPasswordForPf has been created. Enter these values in the Username and Password fields.

PowerFactory uses files in the Oracle Client installation folder the communication with the server. In
order to find them, the installation folders must be configured explicitly:

 Switch to the Advanced page

 Insert the folders as described below (see figure 4.3.6)

Figure 4.3.6: PowerFactory Configuration for Oracle Server

Additional directories in PATH

• Oracle Instant Client installed e.g. in C:∖instantclient 11 2:

C:\instantclient_12_1\vc11
C:\instantclient_12_1

• (Normal) Oracle Client installed e.g. in C:∖app∖client∖product∖12.1.0∖client 1:

C:\app\client\product\12.1.0\client_1\oci\lib\msvc\vc11
C:\app\client\product\12.1.0\client_1\bin

4.3.2.5 PowerFactory Configuration via ODBC

Oracle also provides ODBC drivers for their database clients. The drivers and installation instructions
can be downloaded from Oracle directly.

Note: The ODBC driver must be registered to use at least version 12c Release 1 of the Oracle client
libraries.

The Microsoft Windows ODBC Data Source Administration tool provides a list of installed drivers. Once
the installation of the Oracle ODBC driver has been completed they will be listed there. This tool can
also be used to briefly test if the driver was installed correctly.

16 DIgSILENT PowerFactory 2018, Installation Manual

4.3. MULTI-USER DATABASE CHAPTER 4. ADVANCED INSTALLATION OPTIONS

The ODBC driver name is the only additional information required in the PowerFactory database set-
tings, everything else can be set up as described in 4.3.2.4. Make sure to spell the driver name exactly
as shown in the ODBC Data Source Administration tool.

When using the Oracle ODBC driver, specifying the driver location in the Additional directories in PATH
setting is not required.

4.3.2.6 Backup

Create Backup

Describing Oracle’s backup facilities is far beyond the scope of this installation manual. In this section
only a simple technique is described. Please consult the Oracle documentation for detailed information
or other backup strategies. One backup method is the creation of database dumps. The exp.exe and
imp.exe tools are part of the Oracle distribution. To export all data of the schema PF run the exp.exe
tool:

exp.exe PF/aPasswordForPf@PFS file=d:\backups\database.dump owner=PF

where PF is the schema, aPasswordForPf is his password, PFS is the TNS name, and d:∖backup
∖database.dump is the filename of the dump file.

Note: During the export or import process no PowerFactory user should must not be active. This
backup strategy is suitable only for e.g. nightly backups.

Oracle also supports so-called hot backups where clients can still use the database during the backup
process. Please consult the Oracle documentation for this backup strategy.

Restore Backup

To re-import a database dump, first drop and re-create the Oracle schema PF. Then run the imp.exe
tool:

imp.exe PF/aPasswordForPf@PFS file=d:\backup\database.dump fromuser=PF touser=PF

If you import the dump into another Oracle instance ensure that there is a tablespace with the same
name as the source instance.

4.3.3 Microsoft SQL Server

Microsoft provides several editions of its relational database system SQL Server. Depending on Version
(2008 or newer) the availability of the editions may vary.

DIgSILENT PowerFactory is capable to use all editions as database engine. The free Express Edition
provides almost the same functionality as the other editions but limits database size to 4 GB and lacks
some of the more advanced administration tools. For a complete list of features for all editions consult
the official SQL Server Homepage.

DIgSILENT PowerFactory 2018, Installation Manual 17

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.3. MULTI-USER DATABASE

SQL Server operates as a service. Services are applications that run as background processes. The
behaviour of services differs from that of other applications. For example, while most applications
are executed only when a user launches the application from the Start menu, services such as SQL
Server are generally started and stopped by the operating system environment. A service runs in the
background and waits for processing requests. In the case of SQL Server, these requests are for
database operations.

All actions described in this section are to be done on the server computer. Throughout this section
SERVERNAME is used as computer name.

4.3.3.1 Server Installation

 Install the SQL Server software according to its documentation.

4.3.3.2 Server Configuration

Before the SQL Server service can be used it must be configured to allow for connections over the
network.

 From the Start Menu select:

• Microsoft SQL Server 20xx, depending on the version installed
• Configuration Tools
• SQL Server Configuration Manager

 Expand the SQL Server 20xx Network Configuration node

 Click on Protocols for SQLEXPRESS node (or the instance name you configured during installa-
tion respectively)
 On the right side, right click the TCP/IP entry and select Enable from the context menu

 Click on the SQL Server 20xx services node

 On the right side, right click the SQL Server (SQLEXPRESS) entry and select Restart from
the context menu. The value in braces is the instance name, so make sure to select the correct
one.
 On the right side, right click the SQL Server Browser entry and select Start from the context
menu if it’s not already running.

Your newly installed instance is now configured to allow network connections. With the next steps a
database for PowerFactory is created.

 Again, from the Start Menu select:

• Microsoft SQL Server 20xx
• SQL Server Management Studio Express
 Change Authentication to SQL Server Authentication

 Enter the login name sa and enter the Password for sa, chosen during installation
 Select File → New→ Query with Current Connection
 Enter the following lines in the Query Window to the right:

18 DIgSILENT PowerFactory 2018, Installation Manual

4.3. MULTI-USER DATABASE CHAPTER 4. ADVANCED INSTALLATION OPTIONS

sp_addlogin pf, aPasswordForPf

GO
CREATE DATABASE pfdb
GO
ALTER DATABASE pfdb SET ALLOW_SNAPSHOT_ISOLATION ON
GO
USE pfdb
GO
sp_grantdbaccess pf
GO
GRANT CREATE TABLE TO pf
GO

 Click Execute in the toolbar

You have now created a database named pfdb with a corresponding login named pf which uses the
password aPasswordForPf. Feel free to change the values according to your needs.

Note: It is highly recommended to create daily backups of the database. The backup procedure for
SQL Server is described in section 4.3.3.4

4.3.3.3 PowerFactory Configuration

Start PowerFactory in configuration mode (see section 7.2 on page 67).

 Switch to the Database page

 Insert the database connection settings as described below (see figure 4.3.7)

Figure 4.3.7: PowerFactory Configuration for SQL Server

Database driver select Microsoft SQL Server

Database service The Database service uses the format server name∖instance name. If you
used the default values SQL Server provides, it would be SERVERNAME∖SQLEXPRESS for the 2008
edition. SERVERNAME is our virtual server name during this manual, as stated earlier.
Username, Password, and Database name for this manual it would be pf as username, aPasswordForPf
as password and pfdb as database name.

DIgSILENT PowerFactory 2018, Installation Manual 19

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.3. MULTI-USER DATABASE

4.3.3.4 Backup

Create a Backup

As with Oracle, SQL Server’s backup facilities are far beyond the scope of this documentation. It is
highly suggested you consult the official Microsoft documentation for detailed backup strategies. We
present a very simple method to backup a database and must stress that this method only satisfies the
most basic needs.

A full SQL Server database backup can be easily created from a DOS console on the server computer.

 Open a command prompt and enter (all in one line):

sqlcmd -S SERVERNAME\SQLEXPRESS -U sa -P aPasswordForSa -e

-Q "BACKUP DATABASE pfdb TO DISK=’d:\backupdir\pfdb.dump’ WITH INIT"

This dumps the database named pfdb to a file d:∖backupdir∖pfdb.dump, sa and

aSecurePasswordForSa are username and password of the database administrator user.

It is suggested to create a batch script which performs this task. To do so:

 Open a new batch file e.g. d:∖backupdir∖backup.bat with a text editor (e.g. Windows’ Notepad
editor).
 Insert the above text into the file (all in one line!).
 Close the file.

Windows’ Scheduled Tasks utility allows you to run this batch script automatically, for example every
day at midnight.

 Open the scheduler manager Windows Start menu:

Start → Programs→ AccessoriesSystem Tools → Scheduled Tasks
 Add a new scheduler task PowerFactory backup and configure it as follows (see the Windows
documentation for further information)
 Enter the backup script d:∖backupdir∖backup.bat to be run.
 Select the daily option and 00:00 as start time.

This configuration creates nightly backups. The pfdb.dump file is overwritten each time. If you want to
keep the latest three backup dumps enhance the above backup.bat script as follows.

 Open the batch script created earlier

 Replace its contents with the following lines (again, the sqlcmd command in one line)

copy d:/backupdir/pfdb2.dump d:/backupdir/pfdb3.dump

copy d:/backupdir/pfdb1.dump d:/backupdir/pfdb2.dump
copy d:/backupdir/pfdb.dump d:/backupdir/pfdb1.dump
sqlcmd -S SERVERNAME\SQLEXPRESS -U sa -P aPasswordForSa -e
-Q "BACKUP DATABASE pfdb TO DISK=’d:/backupdir/pfdb.dump’ WITH INIT"

 Save the file.

20 DIgSILENT PowerFactory 2018, Installation Manual

4.3. MULTI-USER DATABASE CHAPTER 4. ADVANCED INSTALLATION OPTIONS

Restore a Backup

The RESTORE DATABASE command recovers a database from a dump file. To restore a database
backup on the same database server where it was created follow the instructions below.

 Run sqlcmd from the command prompt

sqlcmd -S SERVERNAME\SQLEXPRESS -U sa -P aPasswordForSa

 Run the following commands inside sqlcmd

DROP DATABASE pfdb

GO
RESTORE DATABASE pfdb FROM DISK=’c:/backupdir/pfdb.dump’ WITH RECOVERY
GO

Restoring the database on a different SQL Server installation is more complicated. Let c:∖msde2 be
the installation folder of the target SQL Server. All commands are to be run inside sqlcmd.

 First create a database user pf for PowerFactory usage.

sp_addlogin pf, aPasswordForPf}

GO

 Import the database dump as follows:

RESTORE DATABASE pfdb

FROM DISK = ’d:\backup\pfdb.bak’
WITH MOVE ’pfdb’ TO ’C:\msde2\mssql\data\pfdb.mdf’,
MOVE ’pfdb_log’ TO ’C:\msde2\mssql\data\pfdb.ldf’,
RECOVERY
GO

 Adjust the access rights of the pf user

USE pfdb
GO
sp_change_users_login AUTO_FIX, pf
GO

4.3.4 Vault (optional)

The Vault is a shared directory where all PowerFactory instances can read and write files. Two Pow-
erFactory features require a Vault:

• Shared Result Files: PowerFactory stores almost all data in the database. Result Files are an
exception. Result Files are binary files containing the result of simulation calculation. Due to
performance reasons (these results can be arbitrarily large) they are not stored in the database
but directly in files on the hard disk of the local computer.
Result Files are actually redundant since they are re-created when re-running the calculation.
However since a simulation calculation can take hours to finish, it’s worth to keep them at hand.

DIgSILENT PowerFactory 2018, Installation Manual 21

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.3. MULTI-USER DATABASE

In a multi-user database scenario where two PowerFactory users USER1 and USER2 work on
the very same project, USER2 cannot access the Result Files created by USER1 because they’re
stored on USER1’s hard disk.
Result Files in a Vault directory can be accessed by all PowerFactory users working on the same
multi-user database (see figure 4.3.8).
• Project Archiving: since PowerFactory version 15.1 users can ”archive” their projects. The
projects are exported into an Archive folder in the Vault directory and then deleted from the
database. Users can restore them later. The Housekeeping configuration allows to archive
projects that have not been used for a long time automatically.

Figure 4.3.8: Fileserver Vault

Any shared directory (e.g. on a file server) can act as a Vault if all PowerFactory users (i.e. the
Windows users running PowerFactory ) have read and write access to it. The Vault directory path has
to be configured in PowerFactory .

Start PowerFactory in configuration mode (see section 7.2 on page 67).

 Switch to the Database page

 Insert the database connection settings as described below (see figure 4.3.9)

Figure 4.3.9: PowerFactory Configuration for SQL Server

22 DIgSILENT PowerFactory 2018, Installation Manual

4.3. MULTI-USER DATABASE CHAPTER 4. ADVANCED INSTALLATION OPTIONS

Vault Directory specify a path e.g. a mapped network drive

E:\path\to\vault\directory

or the raw network path.

\\vaultserver\path\to\vault\directory

The specified directory must exist and the current Windows user must have read and write access
to this directory.

Note: A Vault directory is required only in rare scenarios e.g. when PowerFactory users often run
long-running simulations and work on the very same shared project, or when using the project
archiving feature. In all other cases don’t set up a Vault.

Note: It’s strongly suggested to create backups of the Vault directory on a regular basis.

4.3.5 Housekeeping (optional)

Over the course of time the database grows and is cluttered with old data that might have a general
negative impact on the database performance. PowerFactory provides a Housekeeping job that can
be configured to be run as periodical background job e.g. every night.

• Deletion of items older than a configurable age in all users’ recycle bin.
• Archiving (or even complete deletion) of projects that have not been activated recently.
• Regular purge of project storage.

Housekeeping has to be configured in PowerFactory database by the Administrator as described in

the PowerFactory User Manual.

4.3.5.1 Scheduling Housekeeping

This is an optional installation step that can be carried out at a later date. Housekeeping is described in
the Program Administration chapter of the PowerFactory User Manual.

Housekeeping is executed via a Windows Scheduled Task from a computer with PowerFactory in-
stalled. Typically this will be a terminal server (e.g. Citrix) or some other application server. Housekeep-
ing makes use of a command line initiation of PowerFactory . An example execution is as follows:

"C:\Program Files\DIgSILENT\PowerFactory 2017\PowerFactory.exe" /housekeeping:8:60

In the example above, 8 specifies the maximum run duration of the housekeeping as eight hours. If
the housekeeping is scheduled to start at 11 p.m. and is still not finished at 7 a.m., it will exit after
completing its current action.

In the example above, 60 specifies the sleep period, in seconds, after a housekeeping action. If there
were no sleep period the housekeeping would place a heavy workload on the system, possibly affecting
other active users.

DIgSILENT PowerFactory 2018, Installation Manual 23

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.3. MULTI-USER DATABASE

Housekeeping connects as a special administrative PowerFactory user called Housekeeper, which is

automatically created when housekeeping is run for the first time.

The housekeeping execution should be triggered via a Windows Scheduled Task (Windows 2008: Con-
trol Panel/Administrative Tools/Task Scheduler/Create Task). An example of the action configuration is
shown in figure 4.3.10.

Figure 4.3.10: Configuring a scheduled task to run housekeeping

Program/script Insert the path to the PowerFactory executable e.g.

"C:\Program Files\DIgSILENT\PowerFactory 2017\PowerFactory.exe"

The leading and trailing quote characters (") are required since the path contains space charac-
ters.
Add arguments (optional) Insert the housekeeping parameters e.g.

/housekeeping:8:60

Windows scheduled tasks can be automatically stopped. It is preferable to configure this via the house-
keeping maximum run duration parameter, but the scheduled task configuration can be used as a ‘back-
stop’. When configuring the scheduled task, choose an appropriate operating system user to run the
task. The user does not need to be logged on.

24 DIgSILENT PowerFactory 2018, Installation Manual

4.4. APPLICATION SERVER CHAPTER 4. ADVANCED INSTALLATION OPTIONS

4.4 Application Server

An Application Server (e.g. Citrix Application Server) allows to run an application several times in
parallel Windows sessions. A typical scenario for a PowerFactory installation is shown in figure 4.4.1.
Several machines and components are involved:

Many Workstations The actual PowerFactory user works locally on his Workstation. When the user
starts the application, a PowerFactory process is started on the Application Server. The applica-
tion windows is shown on the Workstation.
One or more Application Servers One or more instances of PowerFactory are running on this server.
There might be several Application Server Computers organised in a Server Farm.
Database Server Manages the central PowerFactory database. All PowerFactory instances com-
municate with it.

Vault File Server (Optional) provides a shared Vault directory (section 4.3.4 on page 21).
Licence Server Installed along with the Licence Components (see section 4.1 on page 7). The Li-
cence Server Components doesn’t have to run necessarily on a separate computer, it can be
hosted on the Application Server.

Figure 4.4.1: Application Server Environment

Installing PowerFactory on an Application Server offers several advantages over a ”normal” multi-user
database installation:

• PowerFactory has to be configured only once on the Application Server computer, but can be
used by potentially hundreds of Workstations.

• A high-bandwidth network connection is necessarily required between PowerFactory and a database

server. Bigger companies have their PowerFactory users distributed over several remote loca-
tions with low-bandwidth network.

Figure 4.4.1 suggests that all components have to be installed on different machines. But it’s possible
to deploy several components on the same computer e.g. the Application Server machine can host
PowerFactory , Licence Server Components , and the Vault directory.

Note: PowerFactory is executed in its entirety on the application server. It is important that the server
complies with PowerFactory ’s computing requirements: RAM, CPU(s), hard disk space, etc.

DIgSILENT PowerFactory 2018, Installation Manual 25

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.4. APPLICATION SERVER

This section describes how to configure PowerFactory on application server for three Windows users
Frodo, Sam, and Pippin. It is assumed that

• PowerFactory is already installed on the computer.

• Additionally a multi-user database should be up and running as described and PowerFactory is
configured to use it section 4.3 on page 10.

The PowerFactory installation directory (usually C:∖Program Files∖DIgSILENT∖PowerFactory 2017)

contains

• PowerFactory the application binary PowerFactory.exe along with several DLL files
• the configuration file PowerFactory.ini
• other data e.g. a template for initial database content, Demo examples etc.

C:\
+ Program Files
+- DIgSILENT
+- PowerFactory 2017
+- PowerFactory.exe // executable
+- PowerFactory.ini // configuration
+- ...

Each Windows user that runs PowerFactory requires a separate workspace directory which will hold
temporary data and log files. The workspace directories are subfolder of a common workspace directory
e.g. d:∖Data∖PowerFactory Workspaces:

D:\
+- Data
+- PowerFactory Workspaces
+- Frodo // Frodo’s workspace directory
+- Sam // Sam’s workspace directory
+- Pippin // Pippin’s workspace directory
+- ...
+- vault // (optional) common Vault data

The vault directory is optional (see section 4.3.4 on page 21). The workspaces directory must not be
necessarily on a local hard disk. It can be on an network drive instead e.g. ∖∖SERVER∖PowerFactory
Workspaces.

4.4.1 Workspace directories

 Create a root directory for all Workspaces e.g.

D:\Data\PowerFactory Workspaces

 Create a Workspace directory for each Windows user:

D:\Data\PowerFactory Workspaces\Frodo
D:\Data\PowerFactory Workspaces\Sam
D:\Data\PowerFactory Workspaces\Pippin

26 DIgSILENT PowerFactory 2018, Installation Manual

4.5. OFFLINE MODE CHAPTER 4. ADVANCED INSTALLATION OPTIONS

Verify that each Windows user has read and write access to his Workspace directory
 (optional) Create a Vault directory e.g.

D:\Data\PowerFactory Workspaces\vault

Verify that each Windows user has read and write access to the Vault directory.

4.4.2 PowerFactory Configuration

Start PowerFactory in configuration mode (see section 7.2 on page 67).

 Switch to the Workspace page

 Uncheck Use Default Workspace Directory
 Insert as Directory

D:\Data\PowerFactory Workspaces\%USERNAME%

%USERNAME% will be replaced by the current Windows username.

%USERNAME% will be replaced by the current Windows username.

(Optional) If your using a vault directory, set the Vault Directory on the Database as described in
section 4.3.4 on page 21.

4.5 Offline Mode

Since Version 15.0 PowerFactory provides the ability to work in Offline Mode when a network con-
nection to the database server is unavailable. The required project data is cached to the user’s local
machine, which can then later be synchronised to the server database. Floating Licences can be gener-
ated which allow to work without a permanent connection to the Licence Server Components . More
information on Floating Licences can be found in chapter 5.8.

Note: Offline Mode requires the Multi-user database module and the Floating Licence Server feature.

Note: Offline Mode can not be combined with the Project Archiving functionality.

This section describes the installation and configuration of the Offline Proxy Service , a software com-
ponent of PowerFactory to be used with the Offline Mode database driver. Figure 4.5.1 gives an
overview over all components.

DIgSILENT PowerFactory 2018, Installation Manual 27

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.5. OFFLINE MODE

Figure 4.5.1: Offline Mode Components Overview

The installation procedure consists of the following steps:

1. First a PowerFactory environment in normal (i.e. not-offline) mode has to be set up. It contains at
least a PowerFactory installation, the Licence Server Components , and a multi-user database
server (Oracle or SQL Server) (see section 4.5.1).
2. Installation of the Offline Proxy Service on an application server (see section 4.5.2).

3. Configuration of an Offline PowerFactory (see section 4.5.3).

A final section describes the procedure when upgrading to a newer PowerFactory version (see sec-
tion 4.5.4).

4.5.1 PowerFactory in Normal Mode

Before Offline Mode can be set up PowerFactory must be installed and a multi-user database must be
configured and initialised (see section 4.3 on page 10).

Figure 4.5.2: Offline Mode Components Overview for Online PowerFactory

The Database page of the PowerFactory Configuration might resemble figure 4.5.3

28 DIgSILENT PowerFactory 2018, Installation Manual

4.5. OFFLINE MODE CHAPTER 4. ADVANCED INSTALLATION OPTIONS

Figure 4.5.3: PowerFactory Database Configuration

Relevant for the Offline Proxy Service configuration are the parameters below:

• Oracle Database Server parameters

– Connection specifier (e.g //servername/instancename)
– Oracle user name (e.g. schemaname) and password
– A network path to the vault directory (e.g. ∖∖vaultserver∖vaultfolder)
• SQL Server parameters
– Connection specifier (e.g servername∖instancename)
– SQL Server user name (e.g. schemaname) and password
– SQL Server database name
– A network path to the vault directory (e.g. ∖∖vaultserver∖vaultfolder)

4.5.2 Offline Proxy Service

Figure 4.5.4: Offline Mode Components Overview for Offline Proxy Service

4.5.2.1 General Requirements

The Offline Proxy Service requires Microsoft .NET Framework 3.5.

DIgSILENT PowerFactory 2018, Installation Manual 29

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.5. OFFLINE MODE

4.5.2.2 Requirements for Oracle

Either Oracle Instant Client 11.2 or a normal Oracle Client 11.2 is required. The architecture must
match the one of the Offline Proxy Service to be installed, either 32 Bit or 64 Bit.

Oracle Instant Client

To be able to access the Oracle Database you need to install a driver called Oracle Instant Client. It
is also used with PowerFactory and can be obtained from the Oracle Homepage. The Offline Proxy
Service requires version 11.2.

 Download the ZIP package from there.

 Unzip the package to the hard drive, preferably to C:∖oracle∖instantclient 11 2.

(Normal) Oracle Client

Install the Oracle Client using the installer.

4.5.2.3 Requirements for SQL Server

There are no additional requisitions.

4.5.2.4 Offline Proxy Service Installation

The Offline Proxy Service is installed using a Microsoft Installer (MSI) package. The installer files can
be downloaded from our website. They are also shipped on the installation media, subfolder contents.

Both a 32 Bit and a 64 Bit version are available. The Offline Proxy Service architecture does not
necessarily match the PowerFactory architecture, 32 Bit and 64 Bit can be mixed freely.

 Run the appropriate MSI installer and follow the on-screen instructions.

The Offline Proxy Service executable and configuration files are (for the 64 Bit version) by default
located in the folder

C:\Program Files\DIgSILENT\PowerFactory Offline Service x.x\

30 DIgSILENT PowerFactory 2018, Installation Manual

4.5. OFFLINE MODE CHAPTER 4. ADVANCED INSTALLATION OPTIONS

Figure 4.5.5: Offline Proxy Service Installation Directory

Before starting the Offline Proxy Service , it must be configured.

4.5.2.5 Configuration file offline.ini

Navigate to the directory where you have installed the Offline Proxy Service and find the file offline.ini.
Open it with any Text Editor, for example Notepad. It will look like this:

[Network]
Port=9401

[Database]
Type=Oracle
DataSource=//servername/instancename
UserId=schemaname
Password=schemapassword
VaultPath=\\vaultserver\vaultfolder

[Folders]
DataRoot=E:\temp\offline
AdditionalPath=C:\oracle\instantclient_11_2

The different sections and their contents in detail:

Network Settings

[Network]
Port=9401

Port This port is opened by the server machine to accept incoming connections. It may be necessary
to add an inbound rule to the Windows Firewall. This is covered later in this document.

DIgSILENT PowerFactory 2018, Installation Manual 31

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.5. OFFLINE MODE

Database settings for Oracle

[Database]
Type=Oracle
DataSource=//servername/instancename
UserId=schemaname
Password=schemapassword
VaultPath=\\vaultserver\vaultfolder

Type Must be set to Oracle

DataSource A string defining the server machine and Oracle instance to connect to.
UserId The Oracle user/schema id where the PowerFactory database schema is stored.

Password The encrypted (!) password for the Oracle user. Must be set using the console.exe using
the /setdbpassword command from a command shell. Open a command window in the installa-
tion directory and type

console /setdbpassword <password>

VaultPath the vault network folder by PowerFactory

These values should match the Database settings in the Online PowerFactory log on dialogue as
described in section 4.5.1.

Database settings for SQL Server

[Database]
Type=SqlServer
Server=servername\instancename
UserId=sqlserverUsername
Password=sqlserverPassword
Database=sqlserverDatabase
VaultPath=\\vaultserver\vaultfolder

Type Must be set to SqlServer

Server A string defining the SQL Server machine and the instance name.
UserId The SQL Server user id

Password The encrypted (!) password. Must be set using the console.exe using the /setdbpassword
command from a command shell. Open a command window in the installation directory and type:

console /setdbpassword <password>

Database the database name

VaultPath the vault network folder by PowerFactory

These values should match the Database settings in the Online PowerFactory log on dialogue as
described in section 4.5.1.

32 DIgSILENT PowerFactory 2018, Installation Manual

4.5. OFFLINE MODE CHAPTER 4. ADVANCED INSTALLATION OPTIONS

Folder settings

[Folders]
DataRoot=E:\temp\offline
AdditionalPath=C:\oracle\instantclient_11_2

DataRoot This is a directory for temporary files created by the Offline Proxy Service . It may be
necessary to change the access rights on this directory. This is covered later in this document.
AdditionalPath The directories added here are temporarily added to the system PATH variable for
this application only. This can be used to tell the Offline Proxy Service where to find the Ora-
cle Instant Client libraries without modifying the systems PATH variable using Windows system
settings.

Per default, the Offline Proxy Service will write log messages to the Windows application log. This
behaviour is configurable through the file service.exe.config.

4.5.2.6 Setting up Security and Access Rights

The Offline Proxy Service is run as using the system NETWORK SERVICE user account.

• It is mandatory for the NETWORK SERVICE account to have read and write access to the directory
specified as Folders/DataRoot folder. It is also mandatory to allow incoming connections on the
port specified under Network/Port.
• It is mandatory for the NETWORK SERVICE account to have read&write access to the directory
specified as Database/VaultPath
• It is mandatory for the NETWORK SERVICE account to have read&write access to the folder con-
figured for logging C:∖Program Files∖DIgSILENT∖Offline Service
• Oracle only: Besides the NETWORK SERVICE account requires a read access to the Oracle Instant
Client directory.

4.5.2.7 Firewall Settings

To allow connections from remote clients to the Offline Proxy Service , the configured port must be
added as Inbound Rule to the Windows Firewall. Open the Windows Firewall with Advanced Secu-
rity MMC Snap-In. It can be searched for via the Start Menu in Windows 7 and above.

 Right click on Inbound Rules and select New Rule...

 Set Rule Type to Port and click Next
 Set Protocol to TCP. Enter the Port number that is configured in the configuration file for Net-
work/Port and click Next.
 Select Allow the Connection and click Next.
 Check whatever is suitable for when this new rule is to be applied. This depends on your corporate
network policy and click Next.
 Enter a Name and Description and click Finish.

Service Configuration in the MMC: No special actions needed. All general settings are working as usual.

DIgSILENT PowerFactory 2018, Installation Manual 33

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.5. OFFLINE MODE

4.5.2.8 Verify Configuration

Log on to the server as the Windows user, which will run the Offline Proxy Service as Windows
service.

 Open a DOS console

 Change directory to the installation directory
 Run console

Now the Offline Proxy Service is started as a normal console application and writes messages into
the console window:

C:\Program Files\DIgSILENT\Offline Service>console

2011-11-09 14:48:50,343 [1] INFO Offline.Program - Acting as OfflineProxy Server.

2011-11-09 14:48:50,390 [1] DEBUG Offline.Engine - Engine.Start() ...
2011-11-09 14:48:50,781 [1] DEBUG Offline.Sockets.SocketServer -
FileServerHandler(’d:\tmp\offline_tmp’) ...
2011-11-09 14:48:50,781 [1] DEBUG Offline.Sockets.SocketServer - ...
FileServerHandler(’d:\tmp\offline_tmp’)
2011-11-09 14:48:50,781 [1] DEBUG Offline.Sockets.SocketServer -
FileServerHandler(’\\oracleserver\fullshared\offline_vault’) ...
2011-11-09 14:48:50,781 [1] DEBUG Offline.Sockets.SocketServer - ...
FileServerHandler(’\\oracleserver\fullshared\offline_vault’)
2011-11-09 14:48:50,781 [1] DEBUG Offline.Engine - ... Engine.Start()
Press Return to exit

Verify that no errors are reported.

 press Return key and close window

If there are any errors, adapt the configuration accordingly and restart console until there are no more
errors.

4.5.2.9 Start the Offline Service

Having resolved all configuration errors Offline Proxy Service is ready to run as a Windows Service.
Open Windows Services console window and start the Service.

 Right-click on Offline Service, and select Start in the context menu (see figure 4.5.6).

34 DIgSILENT PowerFactory 2018, Installation Manual

4.5. OFFLINE MODE CHAPTER 4. ADVANCED INSTALLATION OPTIONS

Figure 4.5.6: Windows Services

Adapt the service settings:

 Right-click on Offline Service, and select Properties in the context menu

An Offline Service Properties dialogue is shown.

 Set the Startup type to Automatic.

DIgSILENT PowerFactory 2018, Installation Manual 35

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.5. OFFLINE MODE

Figure 4.5.7: Offline Service Properties

 Eventually adapt the Windows user in the Log On tab.

The service writes messages into the log file

C:∖Program Files∖DIgSILENT∖Offline Service∖service.log

Before you proceed with the next section, verify that this log file was created and that there are no error
messages in the log file.

4.5.3 PowerFactory Offline Mode Configuration

On each of the Workstations PowerFactory has to be configured in order to communicate with the
Offline Proxy Service (see figure 4.5.8).

36 DIgSILENT PowerFactory 2018, Installation Manual

4.5. OFFLINE MODE CHAPTER 4. ADVANCED INSTALLATION OPTIONS

Figure 4.5.8: Offline Mode Components Overview for Offline PowerFactory

Start PowerFactory in configuration mode (see section 7.2 on page 67).

 Switch to the Database page

 Insert the database connection settings as described below (see figure 4.5.9)

Figure 4.5.9: PowerFactory Configuration for Offline Mode

Database driver select Offline Proxy Server

Database service insert the host name or IP address of the Offline Server machine, followed by ”:”
and the port number e.g. servername:9401 or 192.168.32.367:45600
Use Floating Licence check this option if the offline mode should work without a permanent connec-
tion to the licence server (default).
• Validity: floating licences can be generated for a maximum of 30 days.
• Renewal before expiry: when getting close to expiration a floating licence can be renewed to
extend its validity. In offline mode, PowerFactory reminds the user a configurable number
of days before expiry and offers to start the renewal procedure (please note that renewal
requires connection to the floating licence server).

DIgSILENT PowerFactory 2018, Installation Manual 37

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.5. OFFLINE MODE

4.5.4 PowerFactory Upgrade

This section describes the steps to take when PowerFactory is upgraded to a new version e.g. from
15.0.3 to 15.2.0.

4.5.4.1 Step 0: Create Data Backups

Before changing the system create backups of

• Oracle Schema or SQL Server database used for PowerFactory

• the Vault directory on the Vault file server
• workspaces of all Offline PowerFactory instances

4.5.4.2 Step 1: Upgrade PowerFactory Online instance(s)

Figure 4.5.10: Upgrade PowerFactory Online instance(s)

 Run the PowerFactory installer and replace the existing version with the new version.

4.5.4.3 Step 2: Migrate Online Database

With the upgraded PowerFactory installation it’s possible to upgrade the database on the Database
server (see figure 4.5.11).

Figure 4.5.11: Migrate Database

38 DIgSILENT PowerFactory 2018, Installation Manual

4.5. OFFLINE MODE CHAPTER 4. ADVANCED INSTALLATION OPTIONS

 Start an upgraded online PowerFactory installation

 Confirm when asked for database migration.

4.5.4.4 Step 3: Upgrade Offline PowerFactory instances, migrate Offline Database

Figure 4.5.12: Migrate Offline Database(s)

 Run the PowerFactory installer and replace the existing version with the new version.
 Start PowerFactory . The local offline database is migrated automatically.

4.5.4.5 Step 4: Upgrade Offline Proxy Service

Figure 4.5.13: Upgrade the Offline Proxy Service

 Make a Backup of all configuration files: console.exe.config, offline.exe.config, and offline.ini

 Stop the service
 Uninstall the service using the Add or remove programs tool

 Install the new service

 Restore the configuration files
 Restart the service

DIgSILENT PowerFactory 2018, Installation Manual 39

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.6. DATABASE READ-ONLY MODE

4.6 Database Read-only Mode

PowerFactory can be started in a ”read-only mode”. In this mode the application reads data from an
existing database, but never writes data back to the database i.e. all data changes are lost when the
application is closed.

Its purpose is a parallel calculation on the same data e.g. several PowerFactory engines perform
similar calculations on the very same project. Without read-only mode this scenario would require for
each concurrent engine a separate PowerFactory user, each owning a separate copy of the project.
With read-only mode all engines can use the same project and the same PowerFactory user.

Note: In read-only mode the functionality is restricted e.g. database-related operations like creation of
versions, PFD export etc. are not available.

Though all engine instances read from the very same database, each engine instance requires a sepa-
rate instance directory within the workspace directory where instance-specific temporary data is stored
e.g. the log file or other temporary files.

Usage: the read-only mode is enabled by the command line switch /readonlymode. The instance
identifier can be set with /instance. Please note that the instance argument is mandatory for starting
multiple instances from same working directory. Example:

PowerFactory.exe /readonlymode /instance INST1

PowerFactory uses now a db-INST1 directory. If it’s not there it’s created automatically:

WORKSPACE
+- db // normal workspace data
| +- log
| +- tmp
| +- ...
|
+- db-INST1 // workspace data for instance INST1
+- log
+- tmp
+- ...

C++-API example: start a read-only engine instance for user USERNAME and password PASSWD with the
instance identifier INST1.

CreateApiInstanceV1(
"USERNAME",
"PASSWD",
"/readonlymode /instance INST1");

4.7 Database in-memory Mode

PowerFactory can be be started in a ”in-memory” mode when using a local database. Once the
application running in that mode is terminated all database modifications are lost. This mode is intended
for automation purposes.

40 DIgSILENT PowerFactory 2018, Installation Manual

4.8. ACTIVE DIRECTORY AUTHENTICATION CHAPTER 4. ADVANCED INSTALLATION OPTIONS

Note: In contrast to the read-only mode described above, the in-memory mode does not put any limita-
tions on the running PowerFactory instance. This means all operations that modify the database
can be executed, like importing and exporting data, creation of versions etc.

This mode of operation is especially useful if the instances need to import data from external sources
before they can perform their work. Once the instance has been terminated all the imported data is
gone, preventing the accidental accumulation of data. As the in-memory mode uses a copy of the
existing local database, it is very easy to prepare a baseline of information required for the instances to
do their work. Libraries, scripts, template projects etc. can all be provided in the normal local database
and are then available to all in-memory clients.

As with the read-only mode above, multiple instances need a dedicated instance directory for their log
files, temporary files, result files etc.

Usage: the in-memory mode is enabled by the command line switch /inMemory. An instance identifier
can be set with /instance e.g.:

PowerFactory.exe /inMemory /instance INST1

PowerFactory uses now a db-INST1 directory. If it’s not there it’s created automatically:

WORKSPACE
+- db // normal workspace data
| +- log
| +- tmp
| +- ...
|
+- db-INST1 // workspace data for instance INST1
+- log
+- tmp
+- ...

In some cases it might be convenient to provide the in-memory switch via the PowerFactory.ini configu-
ration file, eg:

[database]
inMemory = true

Possible values are true and false.

4.8 Active Directory Authentication

Since Version 15.0.1 PowerFactory provides a mechanism for the external authentication of Power-
Factory users via Microsoft Active Directory. As implied in Figure 4.8.1 the Active Directory Au-
thentication Service fills the gap between an Active Directory Domain Controller and PowerFactory
instances which are running on workstations.

DIgSILENT PowerFactory 2018, Installation Manual 41

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.8. ACTIVE DIRECTORY AUTHENTICATION

Figure 4.8.1: Components for Active Directory Authentication

Note: The Active Directory Authentication Service and PowerFactory workstations must be in the
same Active Directory Domain.

Note: The external authentication via Microsoft Active Directory will work properly only for users
whose PowerFactory and Windows user names are identical.

4.8.1 Installation

This section describes the installation of the Active Directory Authentication Service .

4.8.1.1 Prerequisites

The installation of the Active Directory Authentication Service requires:

• PowerFactory Version 15.0.1 or higher and

• Microsoft .NET Framework 3.5 or higher.

Elevated privileges are needed for installing the Active Directory Authentication Service .

4.8.1.2 Installer Package

The Active Directory Authentication Service is installed by means of a Microsoft Installer (MSI)
package. The installer package can be downloaded from the DIgSILENT website.

Both a 32 Bit and a 64 Bit version are available. The Active Directory Authentication Service ar-
chitecture must not necessarily match the PowerFactory architecture; 32 Bit and 64 Bit can be mixed
freely.

42 DIgSILENT PowerFactory 2018, Installation Manual

4.8. ACTIVE DIRECTORY AUTHENTICATION CHAPTER 4. ADVANCED INSTALLATION OPTIONS

4.8.1.3 Service Installation

Install the Active Directory Authentication Service by running the appropriate MSI installer and follow
the on-screen instructions.

The Active Directory Authentication Service executable and configuration files are (for the 64 Bit
version) by default located in the folder

C:\Program Files\DIgSILENT\PowerFactory AdAuthentication Service x.x

Figure 4.8.2: Active Directory Authentication Service Installation Directory

4.8.2 Configuration

This section presents the configuration of the Active Directory Authentication Service and Power-
Factory for enabling the external authentication via Active Directory.

4.8.2.1 Service Settings

The Active Directory Authentication Service installation folder as illustrated in Figure 4.8.2 contains
two configuration files: adservice.exe.config and console.exe.config. As the name implies, the
first pertains to the Active Directory Authentication Service , the second to the console.exe test
application for debugging installation problems. The configuration files are almost identical:

<?xml version="1.0" encoding="utf-8" ?>

<configuration>
<configSections>
<section name="log4net" type="System.Configuration.IgnoreSectionHandler" />
</configSections>
<appSettings>
<add key="port" value="9501" />
<add key="ad_contexttype" value="" />
<add key="ad_container" value="" />
<add key="ad_name" value="" />
<add key="ad_contextoptions" value="" />
<add key="pf_group" value="" />

DIgSILENT PowerFactory 2018, Installation Manual 43

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.8. ACTIVE DIRECTORY AUTHENTICATION

</appSettings>

...

</configuration>

The Active Directory Authentication Service listens by default to requests from PowerFactory on
port 9501. Adapt the value of the port attribute in the configuration files, if a different port number should
be used instead.

<add key="port" value="9501" />

Note: Ensure that the configured port is not blocked by a firewall on the computer which is used as
Authentication Server. PowerFactory workstations will send their authentication requests via this
port to the Authentication Server.

Optionally an Active Directory group for PowerFactory users can be configured by means of the at-
tribute pf group. If the pf group attribute is configured, the Active Directory Authentication Service
checks the user credentials as to whether a user is also member of the configured Active Directory
group. The group name is empty by default. This means that group membership is not checked.

<add key="pf_group" value="" />

Note: When the Active Directory Authentication Service is started it checks if the configured Active
Directory group actually exists. If the group does not exist the service stops immediately.

The Active Directory Domain Controller is detected automatically. So the following attribute values in
the configuration files are empty by default:

<add key="ad_contexttype" value="" />

<add key="ad_container" value="" />
<add key="ad_name" value="" />
<add key="ad_contextoptions" value="" />

Note: Microsoft provides a robust mechanism for the automatic detection of a currently available Ac-
tive Directory Domain Controller. Especially in larger environments with replicated Domain Con-
trollers, the default settings are the best way of configuring the communication with the Domain
Controllers.

Nevertheless, the detection of the Domain Controller and the communication between Active Directory
Authentication Service and Domain Controller can be configured as follows:

• ad contexttype Specifies the Active Directory Store. The required configuration attributes change
depending on the used store. The internal default value for this attribute is Domain. The allowable
values are:
– Machine
– Domain
– Application Directory

44 DIgSILENT PowerFactory 2018, Installation Manual

4.8. ACTIVE DIRECTORY AUTHENTICATION CHAPTER 4. ADVANCED INSTALLATION OPTIONS

• ad container All queries are performed under this root. For Domain and ApplicationDirectory
context types, this attribute is the container on the store to use as the root of the context, i.e.
fabrikam.com. Let the attribute empty if the container is not specified or if Machine context type
is used.
• ad name The name of the domain or server for Domain contexts types, the host name for Machine
context types, or the name of the server hosting the ApplicationDirectory instance. Let the
attribute empty if the name is not specified.
• ad contextoptions Specifies the options that are used for binding to the server. It is possible
to specify more than one option. A single space character can be used as a separator between
the options. The internal default value for this attribute is: Negotiate Signing Sealing. All
allowable context options are listed below:
– Negotiate
– SimpleBind
– SecureSocketLayer
– Signing
– Sealing
– ServerBind

The following links provide detailed explanations regarding the above mentioned configurations:

https://msdn.microsoft.com/en-us/library/system.directoryservices.accountmanagement.
contexttype(v=vs.100).aspx

https://msdn.microsoft.com/en-us/library/system.directoryservices.accountmanagement.
principalcontext.container(v=vs.100).asp

https://msdn.microsoft.com/en-us/library/system.directoryservices.accountmanagement.
principalcontext.name(v=vs.100).aspx

https://msdn.microsoft.com/en-us/library/system.directoryservices.accountmanagement.
contextoptions(v=vs.100).aspx

4.8.2.2 Windows Service

The Active Directory Authentication Service is installed with an appropriate Windows Service
which is named PowerFactory AdAuthentication Service X.X (Figure 4.8.3). The service logs on by
default as Network Service user.

Open Windows Services console window and start the service.

 Right-click on PowerFactory AdAuthentication Service X.X, and select Start.

Adapt the service settings:

 Right-click on PowerFactory AdAuthentication Service X.X, and select Properties in the

context menu.

Configure the following settings in the Properties dialogue (Figure 4.8.3):

 Set the Startup type to Automatic

DIgSILENT PowerFactory 2018, Installation Manual 45

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.8. ACTIVE DIRECTORY AUTHENTICATION

 If necessary adapt the Windows user in the Log On tab

Figure 4.8.3: Windows Service properties

If the service runs as Network Service it writes messages into the log file
C:∖Windows∖ServiceProfiles∖NetworkService∖AppData∖Local∖Temp∖
ActiveDirectoryAuthenticator∖adservice.log.

Check the log file after starting the Windows Service for errors.

4.8.2.3 PowerFactory Configuration

Start PowerFactory in configuration mode (see section 7.2 on page 67).

 Switch to the Advanced tab on the Advanced page (see figure 4.8.4)
 Insert the authentication server settings as described below

46 DIgSILENT PowerFactory 2018, Installation Manual

4.8. ACTIVE DIRECTORY AUTHENTICATION CHAPTER 4. ADVANCED INSTALLATION OPTIONS

Figure 4.8.4: Authentication Server Configuration

Authentication Server insert the host name or IP address of the machine where the Active Directory
Authentication Service is deployed, followed by ”:” and the port number e.g. servername:9501
or 192.168.1.191:9501. The port number must be consistent with the configured port attribute
as described in section 4.8.2.1 on page 43.

In addition to the configuration of the Authentication Server, the configuration of PowerFactory users
who should be authenticated via Active Directory is required. This configuration can only be done by
the PowerFactory administrator.

 Log on to PowerFactory as Administrator

 Open the Data Manager and select the root node Database in the tree view

 Use the action Detail Mode Class Select in the local menu bar to filter for user objects as
implied in Figure 4.8.5
 Enable the tick box in Force Authentication Server usage for the relevant users

Figure 4.8.5: Enable Authentication via Authentication Server

DIgSILENT PowerFactory 2018, Installation Manual 47

CHAPTER 4. ADVANCED INSTALLATION OPTIONS 4.8. ACTIVE DIRECTORY AUTHENTICATION

48 DIgSILENT PowerFactory 2018, Installation Manual

 CHAPTER 5. LICENCE MANAGEMENT

Chapter 5

Licence Management

PowerFactory uses the CodeMeter® technology by WIBU-SYSTEMS for software protection and li-
censing. The CodeMeter® runtime is implicitly installed as a Windows service by both the PowerFac-
tory and the Licence Server Components installers. CodeMeter® can be configured via the WebAd-
min web interface: http://localhost:22350. Modifying CodeMeter® settings directly, however, is
usually not necessary and should only be done under the guidance of DIgSILENT support.

The Licence Manager is the primary tool for handling PowerFactory licences. It allows the user to
activate a licence on a workstation or a licence server, to update an already installed licence, and to
move a softkey licence to another computer. Furthermore, on machines with access to multiple licences,
the specific licence to be used by a PowerFactory installation can be selected.

The Licence Manager can be started by:

• Opening the Windows’ Start menu and running Windows Start button → All Apps→ PowerFac-
tory 2017 → LicenceManager

• Running the LicenceManager∖LicenceManager.exe in the PowerFactory installation directory

• Launching it from PowerFactory via the TOOLS → Licence menu

The Licence Manager presents the task selection page on startup:

DIgSILENT PowerFactory 2018, Installation Manual 49

CHAPTER 5. LICENCE MANAGEMENT 5.1. NETWORK CONFIGURATION

Figure 5.0.1: Startup page of the Licence Manager

Note: The Licence Manager can generate a Licence Support Package via the respective button in the
lower left corner of the program window. That package is a ZIP archive containing log files and
additional diagnostic information about your system. Please include the support package when
consulting the DIgSILENT support with licence-related issues.

5.1 Network Configuration

Online access is mandatory for all computers with PowerFactory installations as well as PowerFactory
licence servers for two different reasons:

• The licence transfer (activation, update, move) requires communication with the DIgSILENT server.
• Activated licences perform a periodic online check in order to verify their validity (30 day interval).

All network communication uses the HTTP/HTTPS protocol.

You can check the Internet connectivity of your local machine in the Network Settings dialogue that is
opened by the respective link at the bottom of the Licence Manager program window.

5.1.1 HTTP Proxy

If your PowerFactory machine (workstation or licence server) is located behind a HTTP proxy, please
enter the proxy configuration in the Network Settings. The Licence Manager supports anonymous as
well as authenticating HTTP proxies. For authenticating proxies it is recommended to use the auto-
select authentication scheme.

The proxy settings are written to the registry and thus shared with other installations of PowerFactory
on the same PC. In some environments it can be necessary to overwrite the proxy settings for specific
installations. This can be done by manually editing the [network] section in the PowerFactory.ini file:

50 DIgSILENT PowerFactory 2018, Installation Manual

5.2. VIRTUAL ENVIRONMENTS CHAPTER 5. LICENCE MANAGEMENT

[network]
useHttpProxy = true
httpProxyHost = myproxyserver.com
httpProxyPort = 8080
httpProxySecure = false
httpProxyAuth = 0
httpProxyUser =
httpProxyPassword =
disableSslVerification = false

Note: Authenticating proxies need additionally to be configured in the WIBU CodeMeter® settings. The
respective configuration page of the web frontend is reachable by the URL:
http://localhost:22350/configuration/proxy.html

5.1.2 Firewall

In case of a network licence the instances of the licence service use port 22350 to communicate be-
tween client and licence server in the intranet. The network port 22350 is registered at IANA (Internet
Assigned Numbers Authority) and uniquely assigned for CodeMeter communication.

If your PowerFactory machine (workstation or licence server) is located behind a firewall, please make
sure it allows outgoing HTTP/HTTPS (TCP ports 80 and 443) connections from that machine to the
following destinations:

• https://lc.codemeter.com/23827/gateways/

• http://cmtime.codemeter.com/

5.2 Virtual Environments

Due to copy protection reasons the activation of a softkey in a virtual environment is not supported.
Nevertheless, server virtualization is possible with a USB dongle holding a network licence. In this
scenario, the USB dongle needs to be plugged either to the USB port of the physical machine hosting
the VM or to a ”USB via network solution” device. Then, the dongle can be connected to the VM
(exclusive mode).

The following list of providers for ”USB via network” devices is incomplete, but shows a range of example
providers that have basically tested their products for compatibility with CodeMeter technology:

• Belkin (Network USB-Hub)

• Silex (USB Device Server)

• Gridconnect (Lantronix)
• Digi International (AnywhereUSB)

• SEH Computertechnik GmbH (USB Device Server)

• W&T Interfaces (USB-Server Industry)

DIgSILENT PowerFactory 2018, Installation Manual 51

CHAPTER 5. LICENCE MANAGEMENT 5.3. ACTIVATING A LICENCE

5.3 Activating a Licence

A PowerFactory licence is either a single-user workstation licence that needs to be activated on the
computer where PowerFactory is installed, or a network licence that has to be activated on the machine
acting as licence server. The online activation process is the same for both types of licences.

Please start the Licence Manager on the machine where you want to activate a licence and select
Activate Licence. You will then be prompted to enter the ”Activation Key”:

Figure 5.3.1: Online licence activation using the Licence Manager

If you are a new customer, you have received your Activation Key as part of the Licence Agreement.
Users of former versions of PowerFactory 15.x, however, need to migrate their old licence first (please
visit: http://www.digsilent.de/index.php/LicenceMigration).

Please enter the Activation Key and press Next. The following page displays information about the
licence associated with the entered Activation Key. If you have purchased a USB dongle licence, you
are also asked to select the container you want the licence to be stored in. In this case, please plug in
the USB dongle you have received with the PowerFactory installation package, hit the refresh button,
and select the dongle in the drop-down list.

Hint: A licence container stores a single PowerFactory licence and may either be a USB dongle or a
softkey that is located on a specific machine. The type of container in which a licence can reside
is a property of the licence, i.e., dongle licences cannot be stored in a softkey and vice-versa. A
licence container is identified by a serial of the format 123-12345678 or 3-12345678.

After clicking Activate the licence will be transferred from the DIgSILENT server to your computer
and is then ready to be used. The activated licence should be automatically detected by PowerFactory
on the next startup (see also 5.6 for licence selection).

Hint: After successful activation the Licence Manager offers to download and replace the licence ac-
tivation file. This is necessary if you have purchased your licence after the release date of the

52 DIgSILENT PowerFactory 2018, Installation Manual

5.4. UPDATING A LICENCE CHAPTER 5. LICENCE MANAGEMENT

PowerFactory version you want to use or if you have recently prolonged your maintenance con-
tract. In all other cases, an update of the activation file will not have any effect on your installation.

5.4 Updating a Licence

There are two reasons why a customer should update a licence:

1. the customer wants an upgrade of a licence, e.g. buy additional modules or increase the bus
count. DIgSILENT sales will provide an update in this case that the customer can fetch via the
update mechanism of the Licence Manager .
2. the customer installs a new major version and wants to access new functions and features that
are separately licensed. In this case, the update is automatically generated and can be fetched
via the update mechanism of the Licence Manager .

Please start the Licence Manager on the machine where your existing licence(s) have been activated
and select Update Licence.

Figure 5.4.1: Online licence update using the Licence Manager

Clicking ’Next’ will start an online search for updates for all your local licences. The serial numbers of
the licences with an update available will be listed on the next page. You can select for each licences
whether it should be updated or not.

DIgSILENT PowerFactory 2018, Installation Manual 53

CHAPTER 5. LICENCE MANAGEMENT 5.5. MOVING A LICENCE

Figure 5.4.2: Selection page for updates using the Licence Manager

Note: In case a customer bought a specific upgrade for one licence, he receives the activation code
together with the Licence Agreement and might not want to perform an online search for update.
In this case the specific activation code can be entered on the first update page. Clicking ’Next’
will in this case lead to a direct update of the licence under consideration.

5.5 Moving a Licence

A PowerFactory software licence (softkey) can be moved between computers a limited number of times
per year. The licence move is a two-stage process:

1. An activated licence needs to be transferred back to the DIgSILENT server via the Deactivate
Licence feature of the Licence Manager .
2. The deactivated licence can be activated again on any computer as described in Section 5.3.

For initiating a licence move, please start the Licence Manager and click on Deactivate Licence
on the startup page. The Licence Manager will then scan your computer for local licences and prompt
you to select the one you want to deactivate:

54 DIgSILENT PowerFactory 2018, Installation Manual

5.6. SELECTING A LICENCE CHAPTER 5. LICENCE MANAGEMENT

Figure 5.5.1: Licence deactivation as first step of a licence move

After you have made your selection and pressed Deactivate, you will get notified about the remaining
number of moves that are allowed for the selected licence in the current year. If you confirm the de-
activation, the Licence Manager will return the licence to the DIgSILENT server. After the successful
deactivation, the Licence Manager will display the Activation Key to use for re-activating the licence on
another machine.

5.6 Selecting a Licence

By default, PowerFactory scans the local machine and the local network for available licences and
automatically picks a suitable one on startup. When there are multiple licences, or if the auto-search
fails, it might however be necessary to explicitly define the licence to be used by a PowerFactory
installation. This can be done on the Select Licence page of the Licence Manager :

DIgSILENT PowerFactory 2018, Installation Manual 55

CHAPTER 5. LICENCE MANAGEMENT 5.7. HOT STANDBY SERVER

Figure 5.6.1: Licence selection page of the Licence Manager

There exist three licence access modes:

• automatic search: The licence is dynamically selected by PowerFactory on each startup.

• local softkey / USB dongle: PowerFactory uses a specific licence that is either locally installed or
stored on a USB dongle plugged into the local machine. The licence is identified by the serial of
the container it is stored in. If the selected licence is not available, PowerFactory does not start.
• network licence: PowerFactory uses a specific network licence that is identified by the server
address (hostname or IP) and container serial. If the specified licence is not available, PowerFac-
tory does not start.
Hint: All available licence servers are usually listed in the drop-down list. In more complex net-
work setups, such as virtual private networks, however, the server broadcast might fail. In
this case, please enter the server address directly and hit the refresh button: If the licence
server is reachable from your local machine, it should now be found.

A summary of the currently selected licence is displayed on the right of the selection page.

Please make your selection and click Save. The licence configuration is then written to the PowerFactory.ini
file in the PowerFactory installation directory, using the following section and keys:

[license]
container = 128-8130814
server = mylicenceserver.domain.com

5.7 Hot Standby Server

A network licence server grants licences to several PowerFactory processes running in a computer
network. If this server for any reason does not respond, it will not be possible to run PowerFactory

56 DIgSILENT PowerFactory 2018, Installation Manual

5.8. FLOATING LICENCES CHAPTER 5. LICENCE MANAGEMENT

. The licence availability can be increased by providing a second licence (with a separate dongle /
softkey) on another server within the local network. This second licence is called a Hot Standby licence

In general, PowerFactory will contact the main licence server. Only if the main licence server does not
respond, the Hot Standby licence server will be contacted. If the Hot Standby licence server does not
respond, PowerFactory will be closed with an appropriate error message.

To configure PowerFactory for the use of a Hot Standby licence, first configure the main licence using
the Licence Manager as described in chapter 5.6. Afterwards, the PowerFactory.ini file has to be
edited manually. In the [licence] section, add the keys hotStandbyServer and hotStandbyContainer:

[license]
container = 128-8130814
server = mylicenceserver.domain.com
hotStandbyContainer = 128-8130921
hotStandbyServer = myhotstandbyserver.domain.com

Hint: The serial number of your Hot Standby licence can be determined using the Select Licence
page of the Licence Manager : chose network licence and select the server holding the Hot
Standby licence. The serial number is shown in the drop-down list.

5.8 Floating Licences

Floating Licences are time-limited local workstation licences that can be generated on demand from a
Floating Server Licence. After generation of a Floating Licence only n-1 user licences will be available
on the Floating Server Licence for the validity period of the Floating Licence. A Floating Server Licence
is a network licence with the Floating Server feature enabled (separately licensed). Floating Licences
are typically used in PowerFactory offline mode (see chapter 4.5) where they are generated implicitly
according to the offline mode configuration. However, it is also possible to generate, renew and return
Floating Licences manually from within PowerFactory :

Generate a Floating Licence

A Floating Licence can be generated from PowerFactory via the TOOLS → Licence menu. To gen-
erate a Floating Licence PowerFactory must be configured to use a Floating Server Licence. During
the generation procedure PowerFactory will terminate, generate the Floating Licence and adapt its
configuration to use the newly generated licence. PowerFactory will use this licence from the next
start.

Renew a Floating Licence

A Floating Licence can be generated for a maximum of 30 days. When getting close to expiration,
the Floating Licence can be renewed to extend its validity. The renewal option can be found in the
PowerFactory TOOLS → Licence menu. Please note, that PowerFactory has to be able to reach the
Floating Server Licence via the network to successfully perform the renewal.

Return a Floating Licence

A Floating Licence is time-limited and will automatically be returned to the Floating Server Licence after
expiration (i.e. the number of licensed users on the server will be increased by 1). However, if a Floating

DIgSILENT PowerFactory 2018, Installation Manual 57

CHAPTER 5. LICENCE MANAGEMENT 5.8. FLOATING LICENCES

Licence is no longer needed, it can manually be return via the PowerFactory TOOLS → Licence menu.
Please note that PowerFactory has to be able to reach the Floating Server Licence via the network to
successfully perform the return.

58 DIgSILENT PowerFactory 2018, Installation Manual

 CHAPTER 6. UPGRADE AND MIGRATION

Chapter 6

Upgrade and Migration

This chapter addresses typical scenarios where an existing PowerFactory installation is modified.

• Licence Migration: an existing licence is migrated (see section 6.1 on page 59)
• Upgrade to a newer PowerFactory version e.g. from 15.2 to 2017 (see section 6.2 on page 61).

6.1 Licence Migration

With the release of PowerFactory 2016 the licensing system has been re-implemented and is based
on a new technology since. Users of former versions of PowerFactory (15.x or previous), need to
migrate their old licence when upgrading to PowerFactory 2016, 2017 or later. Please visit: http:
//www.digsilent.de/index.php/LicenceMigration. After you have received the Activation
Key of your migrated PowerFactory licence from DIgSILENT sales, please activate it as described in
Section 5.3.

6.1.1 Using PowerFactory 15.2 or earlier with a PowerFactory 2017 Licence

Users who have already migrated their PowerFactory licence but nevertheless need to run earlier
versions of PowerFactory (15.x or previous) from time to time, will have to install a new version of the
PowerFactory licence server, which is called LegacyLicenceService.

Hint: The LegacyLicenceService requires a local licence (dongle connected to the local machine
or softkey activated on the local system). PowerFactory instances however can connect to the
LegacyLicenceService from any PC in the network.
Also note that - due to changes in the functionality contained in PowerFactory base package
from PowerFactory 15.x to PowerFactory 2016 and later - it is only possible to run an older
PowerFactory version with a recent PowerFactory licence that contains at least the following
additional modules (which are contained in any migrated licence): Contingency Analysis, Quasi-
Dynamic Simulation, Network Reduction, Techno-Economical Analysis, Scripting and Automation.

6.1.1.1 Installation of Legacy Licence Service

The installer for LegacyLicenceService can be found in the PowerFactory 2017 installation directory
(folder Legacy Licence Service). After running the installer, the Licence Service Utility tool can be
started by:

DIgSILENT PowerFactory 2018, Installation Manual 59

CHAPTER 6. UPGRADE AND MIGRATION 6.1. LICENCE MIGRATION

• Opening the Windows’ Start menu and running Start → All Programs→ PowerFactory Legacy
Licence Service→ Licence Service Utility or
• Running the LicenceServiceUtility.exe in the Legacy Licence Service installation directory.

Hint: This tool can only be started if a migrated PowerFactory licence is available on the local machine.

Within this tool press the Install Legacy Licence Service button. If there are different Power-
Factory licences available on the local computer, it is important to select one licence before starting the
service (see 6.1.1.2).

After installing, LegacyLicenceService will start automatically when rebooting your system. However,
LegacyLicenceService depends on the start of CodeMeter. To configure this dependency, open a
command prompt with administrator rights and type:
sc config LegacyLicenceService depend= CodeMeter.exe

6.1.1.2 Configuration and start of PowerFactory

Configuration for PowerFactory Workstation Licence

If using a PowerFactory workstation licence, PowerFactory has to be configured as workstation. Run

TOOLS∖Configure.bat in the installation directory of your old PowerFactory version. The PowerFac-
tory configuration dialog opens. Navigate to page Licence and select PowerFactory Workstation. Close
the dialog.

For using a workstation licence it is important to stop the old PowerFactory licence service (DIgLis-
eService) on the local system (if all your licences have been migrated to the new licence system you
can uninstall the service.).

Configuration for PowerFactory Network Licence

If using a PowerFactory network licence, PowerFactory has to be configured as server. Run

TOOLS∖Configure.bat in the installation directory of your old PowerFactory version. The Power-
Factory configuration dialog opens. Navigate to page Licence and select PowerFactory Server. In
the Server Name field enter 127.0.0.1 or the IP address of the PC where LegacyLicenceService is
running. Go to the Advanced tab and change the RPC-Endpoint to 4010. Close the dialog.

Selection of a specific PowerFactory Licence

If there are more than one migrated PowerFactory licences available on the local system, it is important
to configure the licence to be used by pressing the button Select Licence Container in Licence
Service Utility. This will open the Select Licence page of the Licence Manager which is described
in 5.6.

Afterwards the file LegacyLicenceService.ini (located in the installation directory) should contain a
[licence] section similar to the following:

[license]
container = 128-8130889

Hint: Licence configuration takes effect after restarting the LegacyLicenceService.

60 DIgSILENT PowerFactory 2018, Installation Manual

6.2. UPGRADE POWERFACTORY VERSION CHAPTER 6. UPGRADE AND MIGRATION

Start PowerFactory

Make sure Legacy Licence Service is running. It can be started from the Licence Service Utility tool
(see 6.1.1).

Then start your old PowerFactory version as usual.

Figure 6.1.1: Licence Service Utility

6.2 Upgrade PowerFactory Version

Beginning with PowerFactory 2016, upgrade installations are no longer supported. Each PowerFactory
release must be installed as a separate, new product.

6.3 Data Migration

A data migration is required when switching from one major release to another one, e.g. from version
2016 to version 2017. There is no migration required if only the service pack number changes. In the
latter case, only the following folders are updated:

• System
• Library

Please make sure these folders do not contain any custom data. They are reset in the process

6.3.1 Local Database

Since version PowerFactory 15.1 workspaces (including the local database) can be easily exported
and imported.

DIgSILENT PowerFactory 2018, Installation Manual 61

CHAPTER 6. UPGRADE AND MIGRATION 6.3. DATA MIGRATION

 Start the former PowerFactory and export the workspace to a *.zip file (section 4.2.1 on page 9)
 Start the new PowerFactory and import the *.zip file.

6.3.2 Multi-User Database

Since version 14.0 PowerFactory can access and use multi-user database from former versions. The
database is migrated automatically when the new PowerFactory version is started. The PowerFactory
Administrator password is required.

Note: A multi-user database is always migrated in-place. After migration the former PowerFactory
version won’t be able to use the database anymore. Ensure that the former version is disabled or
completely removed.

Note: The database migration temporarily requires more data space for e.g. intermediate tables or
table indexes which are dropped at the end of the migration. On Oracle ensure that the temporary
tablespace TEMP can grow up to at least 10 percent of the size of the OBJECT table.

The migration resets all changes in these top-level objects:

• System
• Library

Before you migrate, please make sure that these folders don’t contain any data you need afterwards.

 Inform all PowerFactory users about the migration.

 (Optional) Disable the former PowerFactory version (e.g. on Application Server).
 Ensure that no PowerFactory user is logged on.

 Create a database backup.

 The new PowerFactory installation must be configured to use the same database connection
parameters.
 Start the new PowerFactory version. A warning dialogue is shown (see figure 6.3.1).

Figure 6.3.1: DB Migration Dialogue

62 DIgSILENT PowerFactory 2018, Installation Manual

6.3. DATA MIGRATION CHAPTER 6. UPGRADE AND MIGRATION

 Press Yes to start the migration.

Before the migration is started you’re asked for the PowerFactory Administrator password.

The existing database is now migrated to the new PowerFactory database structure. Depending on
the size of the database this may take several minutes up to several hours. Please don’t interrupt the
migration process. When the migration is completed a success dialogue will appear (see figure 6.3.2).

Figure 6.3.2: Successful Database Migration

6.3.3 Complete vs. Minimal Database Migration

Earlier PowerFactory versions always migrated the database completely. A complete migration—
especially on a multi-user environment—could run for several days depending on the database size
(i.e. the number of users, the number of projects, and the project sizes) and the available hardware
resources. PowerFactory users could not use the application during that period.

Since PowerFactory version 15.2 it’s possible to run a Minimal Migration, that reduces the downtime
period for big database essentially. It only alters the database structure, but doesn’t migrate the users’
projects.

Before the actual migration is started a dialogue allows to choose between Complete and Minimal
migration (see figure 6.3.3).

Figure 6.3.3: Database Migration Settings Dialogue

• Complete (recommended): alters database structure and migrates all projects right now. This
may take very long depending on the number of projects and their sizes.
• Minimal: alters only the database structure. Projects will be migrated later on first activation.

After a Minimal Migration the Data Manager displays not-migrated projects in a grey-coloured font with-
out any content (see figure 6.3.4). Not-migrated can be renamed, moved, and deleted like normal
projects. They’re automatically migrated on activation.

DIgSILENT PowerFactory 2018, Installation Manual 63

CHAPTER 6. UPGRADE AND MIGRATION 6.3. DATA MIGRATION

Figure 6.3.4: Not-migrated project

Some projects might not be used any more, and stay un-migrated forever. However, in some cases it
might be desirable to enforce the migration of the projects. On account of this PowerFactory can be
started in Migration Mode with the /migration command line argument:

PowerFactory.exe /migration:<maximum duration in hours>[:<sleep interval in seconds>]

It migrates not-migrated projects sequentially and stops either after a given time period has passed, or
there aren’t any more projects to migrate.

PowerFactory.exe /migration:8

runs for up to 8 hours. An optional parameter allows to set a sleep time between migrating two projects
in order to reduce the load on the database server. The command below runs the migration for up to 8
hours, pausing for 60 seconds after each project.

PowerFactory.exe /migration:8:60

The migration order of the projects can be influenced by the PowerFactory users. A relative migration
priority can be set in the project dialogue (see figure 6.3.5). First all projects with a High priority are
migrated, then all projects with Medium priority, and finally projects with Low priority. Projects with the
most recent activation date are favoured. Base projects are automatically migrated before their derived
projects.

64 DIgSILENT PowerFactory 2018, Installation Manual

6.3. DATA MIGRATION CHAPTER 6. UPGRADE AND MIGRATION

Figure 6.3.5: Migration Priority of a project

Here’s a possible scenario for upgrading a big multi-user database:

1. Minimal Migration: during that time the system can not be used by any PowerFactory user.
2. A Windows task is created and scheduled to start PowerFactory in Migration Mode to run for
some hours during each night. During that time users might change the migration priority to High
of projects they think they need in the next days. After all projects have been migrated, the job
can be removed.
3. Immediately after the Minimal Migration PowerFactory users can use the system, and migrate
the projects that they’re actually working on.

DIgSILENT PowerFactory 2018, Installation Manual 65

CHAPTER 6. UPGRADE AND MIGRATION 6.3. DATA MIGRATION

66 DIgSILENT PowerFactory 2018, Installation Manual

 CHAPTER 7. REFERENCE

Chapter 7

Reference

7.1 PowerFactory Administrator

Some functions (e.g. user management or changing the configuration in the PowerFactory database)
require to start PowerFactory as Administrator user (Administrator Mode).

A separate short cut starts PowerFactory in Administrator Mode.

 Open Windows’ Start menu and run Windows Start button → All apps→ PowerFactory 2017 →
PowerFactory (Administrator).

Alternatively it’s possible re-start PowerFactory and log as Administrator via the menu Tools → Switch
User....

Usually the PowerFactory Administrator user has a password. Therefore you’re asked to insert a
password.

 Insert the password (The default Administrator password is Administrator).

 Press OK.

7.2 PowerFactory Configuration

A separate short cut starts PowerFactory in Configuration Mode.

 Open Windows’ Start menu and run Windows button → All Apps→ PowerFactory 2017 → Pow-
erFactory (Configuration).

A PowerFactory Configuration dialogue is shown. Alternatively you can review and change the configu-
ration from within a running PowerFactory via the menu Tools → Configuration....

The Configuration dialogue contains several pages which are explained in the next sub sections.

7.2.1 General Settings

See figure 7.2.1.

DIgSILENT PowerFactory 2018, Installation Manual 67

CHAPTER 7. REFERENCE 7.2. POWERFACTORY CONFIGURATION

Figure 7.2.1: General Settings

Language Specifies the application language.

7.2.2 Database Settings

Depending on the database type the there are different settings.

7.2.2.1 Local Database

See figure 7.2.2.

Figure 7.2.2: Database Settings (Local Database)

7.2.2.2 Oracle native client

The Database page allows to set the Oracle connection settings (see figure 7.2.3).

68 DIgSILENT PowerFactory 2018, Installation Manual

7.2. POWERFACTORY CONFIGURATION CHAPTER 7. REFERENCE

Figure 7.2.3: Database Settings (Oracle native client)

Database driver select Oracle (Client Version 12.1)

Database service this field describes the connection. It must be conform to the format

//host[:port][/servicename]

With the values used above (host=oracleserver, port=1521 (default port), and SID=PFSERVER)
the connection name is

//oracleserver/PFSERVER

If we had used a non-default port=8888 the connection name would be

//oracleserver:8888/PFSERVER

If you’ve installed a (normal) Oracle Client and made an entry (e.g. PFS) in the TNSNAMES.ORA
configuration file, you can use the TNS name instead. Then the Database service is just

PFS

Username and Password During the Oracle server setup an Oracle schema PF with the password
aPasswordForPf has been created. Enter these values in the Username and Password fields.

Vault Directory (Optional) Vault directory as described in section 4.3.4 on page 21.

Note: Usually the Oracle Client installation directory path must be configured on Advanced page.
Otherwise PowerFactory can’t find the required Oracle Client Runtime files.

7.2.2.3 Oracle ODBC client

The Database page allows to set the Oracle connection settings (see figure 7.2.4).

DIgSILENT PowerFactory 2018, Installation Manual 69

CHAPTER 7. REFERENCE 7.2. POWERFACTORY CONFIGURATION

Figure 7.2.4: Database Settings (Oracle ODBC client)

Database driver select Oracle via ODBC

Database service, Username, Password, Vault Directory see the Oracle native client section.
ODBC driver The name of the ODBC driver.

Note: Usually the Oracle Client installation directory path must be configured on Advanced page.
Otherwise PowerFactory can’t find the required Oracle Client Runtime files.

7.2.2.4 SQL Server

The Database page allows to set the SQL Server connection settings (see figure 7.2.5).

Figure 7.2.5: Database Settings (SQL Server)

Database driver Select Microsoft SQL Server

Database service The Database service uses the format

host\instancename

70 DIgSILENT PowerFactory 2018, Installation Manual

7.2. POWERFACTORY CONFIGURATION CHAPTER 7. REFERENCE

e.g.

MYSERVER\SQLEXPRESS

Username and Password The SQL Server name and password.

Database name The database name.

Vault Directory (Optional) Vault directory as described in section 4.3.4 on page 21.

7.2.2.5 Offline Proxy Server

PowerFactory ’s Offline Mode (section 4.5 on page 27) requires to configure a server.

Figure 7.2.6: Database Settings (Offline Mode)

Database driver Select Offline Proxy Server

Database service Specify server host name and port, separated by a colon e.g.

OFFLINEPROXYSERVER:9401

Floating licence Configure floating licence usage. For details see section 4.5.3 on page 36.

7.2.3 Workspace Settings

The Workspace page allows to change the Workspace directories (see 7.2.7).

DIgSILENT PowerFactory 2018, Installation Manual 71

CHAPTER 7. REFERENCE 7.2. POWERFACTORY CONFIGURATION

Figure 7.2.7: Workspace Settings

Use Default Workspace Directory Uncheck this option to specify a own Workspace directory.
Workspace Directory Path of the current Workspace directory.
Open Workspace Directory Opens Windows Explorer showing the Workspace directory.

Use Default Backup Directory Uncheck this option to specify a own Workspace Backup directory.
This directory is used when workspaces are exported.
Backup Directory Path of the current Workspace Backup directory.
Open Backup Directory Opens Windows Explorer showing the Workspace Backup directory.

Note: Be careful when changing the Workspace Directory. The new workspace directory is not
initialised with the current workspace directory. First export the workspace to a *.zip file and
re-import it afterwards.

7.2.4 External Applications

The External Applications page allows to change the configuration when using external applica-
tions (see 7.2.8).

72 DIgSILENT PowerFactory 2018, Installation Manual

7.2. POWERFACTORY CONFIGURATION CHAPTER 7. REFERENCE

Figure 7.2.8: External Applications Settings

7.2.4.1 Python

Settings for running and editing Python scripts.

Version choose which Python version should be used. The Python version is expected to be installed.

Editor choose an application to edit Python script files

7.2.4.2 Visual Studio

Settings for compiling DSL models.

Version choose which Visual Studio version should be used. The Visual Studio version is expected to
be installed.
Shell Extension Allows to choose a different Shell Extension

7.2.4.3 PDF viewer

PowerFactory ’s documentation is delivered as PDF documents. Here you can specify which applica-
tion is used for displaying these documents

system viewer use the Window’s default PDF viewer

SumatraPDF use the built-in viewer

custom insert the path to an arbitrary viewer application

7.2.5 Network Settings

Allows to configure general network parameters. These are used for loading background maps from
Map servers and licence checks. It’s possible to configure an HTTP proxy, optionally with authentication.
See figure 7.2.9.

DIgSILENT PowerFactory 2018, Installation Manual 73

CHAPTER 7. REFERENCE 7.2. POWERFACTORY CONFIGURATION

Figure 7.2.9: Network Settings

7.2.6 Geographic Maps

Settings for accessing Map Servers. See figure 7.2.10.

Figure 7.2.10: Geographic Maps Settings

Use default map cache directory Map data is downloaded from the Map Server and cached locally.
You can specify a directory to share map tiles between users e.g. on a file server.
Preferred tile size The size of the fetched tiles
Max server connections Maximum number of concurrent downloads.
Download timeout Timeout used for server or network problems.
Google Maps/Bing Maps/Geoportail Access data for specific Map Server providers.

7.2.7 Advanced Settings

See figure 7.2.11.

74 DIgSILENT PowerFactory 2018, Installation Manual

7.2. POWERFACTORY CONFIGURATION CHAPTER 7. REFERENCE

Figure 7.2.11: Advanced Settings

Additional directories in PATH A set of directories (each directory on a separate line) where Power-
Factory should look for *.dll files e.g. the Oracle Client Runtime.
Directories for external digex libraries Set of paths that are searched for such DLL files.

The Advanced sub page allows to specify some really advanced settings (see figure 7.2.12).

Figure 7.2.12: Advanced page, Advanced tab Settings

Debug Runs PowerFactory in Debug mode.

Master in Distributed Simulation If checked: this PowerFactory instance acts as Master, otherwise
as slave.
Unattended Mode If checked: PowerFactory runs in non-interactive mode i.e. there no dialogues are
shown which wait for user input.
Run simulation in separate thread Allows to run a simulation calculation a separate thread (experi-
mental)
Startup Commands List of commands that are executed when PowerFactory is started.
Authentication Server Specifies an Authentication Server.

DIgSILENT PowerFactory 2018, Installation Manual 75

CHAPTER 7. REFERENCE 7.3. POWERFACTORY COMMAND LINE PARAMETERS

7.3 PowerFactory Command Line Parameters

PowerFactory can be started with optional command line parameters.

"C:\Program Files\DIgSILENT\PowerFactory 2017\PowerFactory.exe"

"/parameter1:value" "/parameter2:another value"

Alternatively you can use the format below:

"C:\Program Files\DIgSILENT\PowerFactory 2017\PowerFactory.exe"

/parameter1 "value" /parameter2 "another value"

The double quote characters ("") can be omitted if the argument contains no spaces.

7.3.1 /config

Show and edit PowerFactory configuration (see section 7.2 on page 67).

7.3.2 /housekeeping

Execute a database Housekeeping in the database (section 4.3.5.1 on page 23).

7.3.3 /ini

PowerFactory reads the configuration from the file PowerFactory.ini in the installation directory.
In some scenarios it might be convenient to have several configuration files PowerFactory 1.ini,
PowerFactory 2.ini etc. These files can be in any directory, not necessarily in the installation di-
rectory. For each configuration follow the procedure below.

1. Edit and save PowerFactory configuration (see section 7.2 on page 67). The configuration is
saved to the PowerFactory.ini in the installation directory
2. Copy PowerFactory.ini to e.g. C:∖PowerFactory Configurations∖PowerFactory 1.ini

3. Start PowerFactory with the /ini parameter:

"C:\Program Files\DIgSILENT\PowerFactory 2017\PowerFactory.exe"

/ini "C:\PowerFactory Configurations\PowerFactory_1.ini"

7.3.4 /lang

/lang:<LANGUAGE> Ignore the Language setting in the configuration, and run PowerFactory with a
different language. Valid are

• /lang:cn: Simplified Chinese,

76 DIgSILENT PowerFactory 2018, Installation Manual

7.3. POWERFACTORY COMMAND LINE PARAMETERS CHAPTER 7. REFERENCE

• /lang:en: English,
• /lang:es: Spanish,

• /lang:de: German,
• /lang:fr: French,
• /lang:ru: Russian, or
• /lang:tr: Turkish

7.3.5 /migration

Migrate all not-migrated projects after a Minimal Database Migration (see section 6.3.3 on page 63 for
details)

7.3.6 /readonlymode

Database read-only mode (see section 4.6 on page 40 for details).

7.3.7 /inMemory

Database in-memory mode (see section 4.7 on page 40 for details).

7.3.8 /username, /password, and /passwordHash

/username:<USERNAME> specifies which PowerFactory user is to be used. Example: start as Frodo

Baggins user.

"C:\Program Files\DIgSILENT\PowerFactory 2017\PowerFactory.exe"

/username "Frodo Baggins"

Optionally a password can be specified with /password:<PASSWORD>:

"C:\Program Files\DIgSILENT\PowerFactory 2017\PowerFactory.exe"

/username "Frodo Baggins" /password "Frodos password"

Using the cleartext password as command line parameter might not be desirable in some environments.
Alternatively the hash of the password can be specified with /passwordHash:<PASSWORDHASH>. (The
password hash is displayed in the IntUser dialog of the user):

"C:\Program Files\DIgSILENT\PowerFactory 2017\PowerFactory.exe"

/username "Frodo Baggins" /passwordHash "D41D8CD98F00B204E9800998ECF8427E"

DIgSILENT PowerFactory 2018, Installation Manual 77

CHAPTER 7. REFERENCE 7.4. POWERFACTORY SILENT INSTALLATION OPTIONS

7.4 PowerFactory Silent Installation Options

The PowerFactory installer can be run in silent mode via the command line. The easiest way to trigger
a silent installation of PowerFactory is by executing the command

PowerFactorySetup-2018_x64.exe -quiet -install

in the directory where the PowerFactory setup executable is located.

Please note that this command will execute the installation in a new process, no graphical user inter-
face will be shown and no other interaction with the installation process is possible. Per default the
setup program will install all features and packages of the product to the default installation location
%PROGRAMFILES%\DIgSILENT\PowerFactory 2018\.

Note: Administrator privileges are required to successfully run the setup. The silent setup will be
executed in a separate process and after issuing a setup command the command line will immediately
return. The setup process continues to run in the background until it finishes or is cancelled due to an
error (see subsection 7.4.2).

7.4.1 Command line options

To start any silent setup operation, type the name of the PowerFactory setup executable, the argument
-quiet and one of the following operation arguments:

-install installs PowerFactory .

-uninstall removes an existing PowerFactory installation. If no PowerFactory installation is
present, this command will have no effect.

Figure 7.4.1: Operation commands for silent setup

The setup program supports the following additional command line arguments when using -install:

• INSTALLDIR: Specifies the installation directory. Must be a full path where the application should
be installed. The installer will not create a subfolder for the product.

• CREATEDESKTOPICON: Enables or disables the creation of a shortcut for the application on the
user’s desktop. Possible values are ”yes” or ”no”. The default value is ”yes”.

Note that the following rules must be satisfied for any chosen installation path:

• the installation path defined by the INSTALLDIR parameter must be given in quotes and may not
end with a backslash (\). If you want to install PowerFactory into the directory E:\PF 2018,
for instance, use INSTALLDIR="E:\PF 2018". Do not use INSTALLDIR="E:\PF 2018\" or
INSTALLDIR=E:\PF 2018.
• The installation path must be given as an absolute path to the desired installation folder (e.g.
D:\path\to\folder, not \relative\path or D:\path\to\file.xyz).
• The corresponding drive of the chosen path

– must exist,
– must not be a read-only drive (such as a DVD drive),
– must not be a network drive

78 DIgSILENT PowerFactory 2018, Installation Manual

7.4. POWERFACTORY SILENT INSTALLATION OPTIONS CHAPTER 7. REFERENCE

– and must have sufficient free disk space.

• The administrator of your system needs reading and writing rights for the installation path.

• The installation folder must be empty.

During all setup operations (installation, removal), log files are created. By default they are written to
%LOCALAPPDATA%\Temp\PowerFactory*.log. However, you may specify a custom log file location
by using the -log command argument:

PowerFactorySetup-2018_x64.exe -quiet -install -log "D:\path\to\log-file.txt"

Besides the main log file, additional log files for the separate packages of the installation bundle are
created in the same directory and use the name of the main log file as prefix.

7.4.2 Error codes

Whenever the setup operation finishes or is canceled, an error code is returned to indicate what went
wrong (if something went wrong).

The error code of the setup operation will be written into the log file and it may be easily found by
searching the log text for the term ’Exit code: 0x’. For instance, the output Exit code: 0x7
means that the operation yielded the error code 0x7 (see figure 7.4.2 ).

The following error codes may be returned by the setup program:

Error code Explanation

0x0 No error occured. The operation was finished successfully.
0x1 An internal MSI package error occurred. One of the packages issued an error mes-
sage. The package ID and error message have been written to the log file.
0x2 Not enough space on operating system drive. Your operating system’s root drive
(typically C:\) does not have enough free disk space for installation. Please note
that regardless of the chosen installation path, setup also requires disk space on the
operating system drive.
0x3 Not enough space on target installation drive. The root drive of the chosen installa-
tion path does not have enough free disk space.
0x4 The selected installation folder is not empty.
0x5 The chosen installation path is invalid. Note that the installation path must be given
as an absolute path to the desired installation folder.
0x6 The chosen installation path is on a network drive. Note that PowerFactory cannot
be installed on a network drive.
0x7 The root drive of the installation path does not exist or does not allow installation.
0x8 Access to the installation path was denied. Note that setup requires administrator
privileges and the administrator needs to have reading and writing rights for the se-
lected installation path.
0x9 A 64 bit version of the setup program is being executed on a 32 bit operation system.
0xa Administrator rights were not granted for the setup program. Note that setup requires
administrator privileges.
0xb Access to a system component (such as the Registry) was denied. Maybe an anti-
virus program is blocking the setup application. It may help to temporarily deactivate
the anti-virus program and run the setup again.
0xc An unknown error occurred. Please provide the log file to the DIgSILENT Support
Team for a concise error analysis.

Figure 7.4.2: Setup error codes

DIgSILENT PowerFactory 2018, Installation Manual 79

CHAPTER 7. REFERENCE 7.4. POWERFACTORY SILENT INSTALLATION OPTIONS

7.4.3 Examples

To install PowerFactory silently to the directory E:\PowerFactory 2018, use the command

PowerFactorySetup-2018_x64.exe -quiet -install INSTALLDIR="E:\PowerFactory 2018"

To remove an existing PowerFactory installation and create the log file D:\temp\log.txt, use

PowerFactorySetup-2018_x64.exe -quiet -uninstall -log "D:\temp\log.txt"

80 DIgSILENT PowerFactory 2018, Installation Manual

DIgSILENT
Company Profile

PowerFactory Monitor (PFM) is a multi-

functional Dynamic System Monitor which
fully integrates with DIgSILENT PowerFactory
software. PFM features grid and plant mon-
DIgSILENT is a consulting and software com- power system analysis software PowerFactory, itoring, fault recording, power quality, grid
pany providing engineering services in the field which covers the full range of functionality characteristics analysis and grid code com-
of electrical power systems for transmission, from standard features to highly sophisticat- pliance verification. It provides easy access
distribution, generation and industrial plants. ed and advanced applications including wind to recorded data and test results and allows
power, distributed generation, real-time for the analysis of trends and the verification
DIgSILENT was founded in 1985 and is a fully simulation and performance monitoring for of system upset responses. PFM supports the
independent and privately owned company system testing and supervision. For wind power latest standards and protocols.
located in Gomaringen/Tübingen, Germany. applications, PowerFactory has become the
DIgSILENT continued expansion by establish- power industry’s de-facto standard tool, due DIgSILENT Consulting
ing offices in Australia, South Africa, Italy, to PowerFactory models and algorithms pro- DIgSILENT GmbH is staffed with experts of
Chile, Spain, France and the USA, thereby facil- viding unrivalled accuracy and performance. various disciplines relevant for performing
itating improved service following the world- consulting services, research activities, user
wide increase in usage of its software prod- DIgSILENT StationWare is a reliable cen- training, educational programs and software
ucts and services. DIgSILENT has established a tral protection settings database and asset development. Highly specialised expertise is
strong partner network in many countries such management system, based on .NET technol- available in many fields of electrical engineer-
as Mexico, Malaysia, UK, Switzerland, Colom- ogy. StationWare stores and records all set- ing applicable to liberalised power markets
bia, Brazil, Peru, China and India. DIgSILENT tings in a central database, allows modelling and to the latest developments in power
services and software installations have been of relevant workflow sequences, provides generation technologies such as wind power
conducted in more than 140 countries. quick access to relay manuals, interfaces with and distributed generation. DIgSILENT has pro-
manufacturer-specific relay settings and inte- vided expert consulting services to several pro-
DIgSILENT PowerFactory grates with PowerFactory, allowing powerful minent PV and wind grid integration studies.
DIgSILENT develops the leading integrated and easy-to-use settings coordination studies.

DIgSILENT GmbH T +49 7072 9168-0 DIgSILENT GmbH is certified

Heinrich-Hertz-Straße 9 F +49 7072 9168-88 to the ISO 9001:2015 standard.
72810 Gomaringen mail@digsilent.de More information is available at
Germany www.digsilent.de www.tuv-sud.com/ms-cert