3DEXCITE PICTUREBOOK Technical System Description III
3DEXCITE PICTUREBOOK 2018 TECHNICAL SYSTEM DESCRIPTION
3DEXCITE PICTUREBOOK Technical System Description III
CONTENTS
Requirements 1
Client Requirements 1
Server Requirements 1
Installation Guide PICTUREBOOK on Microsoft Windows 2
Server preparation 2
Installation 3
Configuration of PICTUREBOOK server using PICTUREBOOK Admin 3
Licensing 3
Migration 4
Server Settings 4
Additional optional setting tabs 5
Database settings 5
Initializing PICTUREBOOK server installation 6
Starting the PICTUREBOOK server 7
Installation Guide PICTUREBOOK on Linux with GUI 7
Server preparation 7
Installation 7
Configuration of PICTUREBOOK server using PICTUREBOOK Admin in LINUX 9
Licensing 9
Migration 9
Server Settings 9
Additional optional setting tabs 10
Database Settings 10
Initializing PICTUREBOOK server installation 11
Starting your PICTUREBOOK server 11
Installation of PICTUREBOOK Manually 12
Server preparation 12
Licensing 12
Additional optional settings 13
Database Settings 13
Initialization of the PICTUREBOOK server 15
Starting the PICTUREBOOK server 15
Connect DELTAGEN to PICTUREBOOK server 16
Create your own HTTPS Keystore / SSL Setup 17
Create Keystore 17
Additional SSL settings 17
Preparation for Replication 18
Setting the replication to encrypted 18
Other Replication settings: 19
PICTUREBOOK server - starting / stopping 20
Linux 20
Microsoft Windows® 20
Access PICTUREBOOK 21
PICTUREBOOK Management Console 21
Appendix - LDAP 22
Enabling LDAP on the Backend 22
Appendix - External User Synchronization & Single Sign On 23
Synchronization settings 23
Single Sign On (SSO) 24
Appendix - Misc. Settings 24
Signup 24
Reset password 25
Appendix - Image Conversion Settings 25
General Setup 25
Image Conversion Settings 25
Appendix - E-mail Settings 26
Appendix - POWERHOUSE Settings 26
PICTUREBOOK Service Settings 26
PICTUREBOOK MediaStore User Settings 27
3DEXCITE PICTUREBOOK Technical System Description III
Service Port Settings 27
POWERHOUSE Integration Settings: 27
Appendix - Meeting Settings 28
Render Node reservation 28
Stream resolution for 3D meetings 29
Timing Settings 29
Zabbix logging settings 29
Further internal settings 30
Appendix - PDM Integration Settings 30
PDM Connector Settings 30
General Settings 30
Appendix - Application Plug-ins 31
Plug-in description 31
Plug-in management 31
Appendix - Data Migration 32
Using migration wizard 33
Manual migration 33
Appendix - Backup 34
Appendix - Change Log-files Location 35
Linux 35
edit log file configuration file by opening a text based editor and load the file 35
Microsoft Windows® 35
change the log file location via the PICTUREBOOK Admin or manually edit the log file configuration file by
opening a text based editor and load the file 35
Appendix - Configuration of ports for PICTUREBOOK 35
Appendix - Using HTTPS and how to install certificates 36
Installing a certificate on Internet Explorer 36
Installing a certificate on Firefox 38
Appendix - Suggested configuration for a DMZ 39
Apache HTTPS frontend 39
Apache and SSL Configuration 39
Appendix - Additional PICTUREBOOK Admin features 41
Appendix - About PICTUREBOOK 41
Appendix - Usage Statistics 42
Appendix - PICTUREBOOK Server Pages 42
Active Sessions 42
Job Monitor 42
Memory usage 42
Assignment conditions 42
About 42
Appendix - Large file upload 43
Appendix - Adapting Frontend options 43
Appendix – Enable Microsoft Office Preview Generation 44
Setup on Windows 44
Configuration 44
Troubleshooting 45
PostgreSQL installation on Windows 45
Changing maximum connections on PostgreSQL 45
Using PostgreSQL 9.0 45
Running out of disk space 45
MSSQL connection issues on Windows 45
Cannot connect to PICTUREBOOK from DELTAGEN via HTTPS 46
“File not found” Icon is shown instead of the preview image 46
HTTPS and Mozilla Firefox 47
Empty Message box when installing certificate in Internet Explorer 47
“Unknown Server Error” message before login screen 47
Session expired after login 47
OutOfMemory Error 47
Oracle 10g XE issues 48
Oracle Open Connections 48
Asian Character support in PDF 48
3DEXCITE PICTUREBOOK Technical System Description III
Reading PDF without embedded fonts 48
Large file upload with Java fails with DFS (Distributed File System) 49
Cannot Install another PICTUREBOOK version aside 49
3DEXCITE PICTUREBOOK Technical System Description 1
REQUIREMENTS
Client Requirements
Validated client platforms
• Microsoft Windows® 7 Enterprise with Internet Explorer 10 or 11 and Firefox 35 • Microsoft Windows® 10
• Apple Mac OS10.10
Additional Notes:
• Make sure the Browser has Flash Player 23.x or higher installed
• In order to upload files larger than 2GB onto PICTUREBOOK use the Java upload mechanism.
Therefore, make sure Java Runtime Environment (JRE) version 7 or higher is installed.
• Minimum display resolution for clients is 1280x1024. For the meeting feature: 1600x1200
• Firewalls and Antivirus Software could influence the communication for PICTUREBOOK
server. Be sure the following ports are not blocked: 8080 / 8443 (if using default
installation ports).
Server Requirements
Recommended production system (minimum requirements)
• Windows Server 2008 R2 64Bit
• Windows Server 2012 R2 64Bit
• SUSE Linux Enterprise Server 11 SP3 64Bit +
• CPU: Dual Core with 3 GHz + or comparable
• RAM: 4 GB+
• Network: 1 GBit+
• HDD: 100 GB - 1 TB / RAID 5 or RAID 10
(Depending on amount of models & usage of external filespace - Model data, rendering,
additional media data and its previews will be saved into the server’s local filespace.)
Extra recommendations for the 3D Meeting feature usage • Only Windows OS can be used
• Network:
• upstream (PictureBook - client): recommended 1 GBit (minimum 100MBit) – rule of
thumb is 10MBit for each meeting participant
• in the cluster: 1 GBit
• Maximum number of meeting participants: 10 (as long as network bandwidth requirements
are met)
• Machines (in the cluster) running POWERHOUSE
• Minimum configuration: DELTAGEN’s recommended system configuration, please
see graphics card information on our Software Services Website.
• Homogenous amount of RAM
• As scenarios involving POWERHOUSE are generally rather complex, we recommend
requesting our in-house consulting along with the deployment of POWERHOUSE.
Validated databases • PostgreSQL 8.4 or higher
• Oracle 11g or higher
• Microsoft SQL 2008 or higher
Communication between PICTUREBOOK servers and clients • HTTPS (default installation port 8443) / HTTP (default installation port 8080)
• For secure data exchange HTTPS is recommended.
• For performance reasons, use an Apache proxy installation (for details on how to properly
set Apache, please see the POWERHOUSE documentation – “Tweaks and Fine Tuning”
chapter).
3DEXCITE PICTUREBOOK Technical System Description 2
Additional Notes:
• To use PICTUREBOOK Admin, a minimum display resolution of 1024x768 is needed.
• Ghostscript 32 bit version 9.06 (validated version) will have to be installed for the “preview
generation” feature to work.
• If you use POWERHOUSE and Composer functionality, please see the technical
documentation and requirements of POWERHOUSE.
• When choosing PICTUREBOOK’s filestore to be placed in a network share you should
count with considerable data-transfer performance loss. To improve this situation, place
the picturebook_cache and the picturebook_temp folders on the local hard drive and leave
only the picturebook_filstore in the share.
IMPORTANT
If you use Windows 7 or Windows Server 2012, you need administrator rights when installing.
When running the server application from the Windows Program Files directory you will need
full Administrator rights too since these folders are protected by Windows. PICTUREBOOK is
writing some log files and therefore requires also creation and editing rights.
When having some trouble with these rights, install PICTUREBOOK into another directory e.g.
C:\Program Files\Dassault Systemes\3DEXCITE\PICTUREBOOK_X.Y
After installing a new PICTUREBOOK Server version or DELTAGEN plug-ins on an existing
PICTUREBOOK installation, clean the Flash Player’s cache on all client machines to make sure
the clients are using the latest version and not older, cached ones.
1. open Control Panel > Flash Player (32 bit)
2. in the Flash Player settings Manager - storage tab click Delete all…
3. in the Delete all site Data in Flash Player dialog box make sure Delete all site Data anD settings is selected
4. click Delete Data
Compatibility Notes:
PICTUREBOOK 2018 has been validated with DELTAGEN 2017x and 2018 in
PICTUREBOOK Browser scenario.
PICTUREBOOK 2018 for Composer / Meeting scenario has been validated with
POWERHOUSE 2018 and DELTAGEN 2018 (on the render nodes).
Additional configurations can be validated on demand.
INSTALLATION GUIDE PICTUREBOOK ON MICROSOFT WINDOWS
Server preparation
Please make sure, that no application on port 8080 or 8443 is running on your server.
Any preinstalled Sun Java Runtime Environments (JRE) is not needed.
PICTUREBOOK includes his own JRE 1.7.
It is recommended to install and use the bundled PostgreSQL database (further information on
project webpage http://www.postgresql.org/).
If you use the bundled PostgreSQL please make sure, that no other PostgreSQL database is
installed on your server.
The user to install the PICTUREBOOK and PostgreSQL database must have Administrator rights
on your server, because further users (for database) will be created.
Default ports used:
8080 (HTTP Protocol by installation)
8443 (HTTPS Protocol by installation)
5432 (default port for PostgreSQL database)
3DEXCITE PICTUREBOOK Technical System Description 3
Installation 1. execute the setup file picturebook_setup_X.Y.exe to start the installer
2. follow installation routine
The installation dialog box will give you the option to select the components to be installed.
It is recommended to install the bundled PostgreSQL database if you do not have any database
installed yet. More information is provided when selecting the green question mark.
For additional information please also check the PostgreSQL project homepage
http://www.postgresql.org/. If you have an older version of PostgreSQL installed prior to 8.4,
migrate to the latest recommended version.
You can follow up with starting the PICTUREBOOK Admin in order to configure your installation.
3. select start PiCtUreBooK aDMin now
CONFIGURATION OF PICTUREBOOK SERVER USING PICTUREBOOK ADMIN
The configuration of the PICTUREBOOK server can be done with the PICTUREBOOK Admin,
which is a tool to configure and edit all settings for PICTUREBOOK Server in a comfortable way.
All configurations can also be done manually by editing the respective files. This is described
in later chapters.
1. start the PictureBooK Admin
You can either select the Start menu item: Start > Programs > Dassault Systemes > 3DEXCITE >
PICTUREBOOK Admin or execute the file directly: <installation_dir>\startPictureBookAdmin.cmd.
Licensing 2. copy the license file
PICTUREBOOK requires a 32 Bit
version of GhostScript 9.06 in
order to generate previews of
Office documents and PDF’s.
GhostScript is not bundled with
this installer, hence you will
have to download it and install it
by yourself. Missing GhostScript
installation will not break your
system but previews will not be
generated.
There is a dummy license file
already in the target directory.
Confirm overwriting that
dummy file when installing a
new license.
3DEXCITE PICTUREBOOK Technical System Description 4
PICTUREBOOK Admin assists you in the installation process of the license file for PICTUREBOOK.
To get a valid license, please contact our Support.
The license information is displayed on the first tab of the application. Version and the
expiration date are checked and will be marked in red if there is a problem for example when
the license is expired.
Migration After a new installation, a dialog offers you to migrate from a previous PICTUREBOOK version
when selecting “PICTUREBOOK Settings” in the left menu bar.
3. decide if you want to migrate from a former version or not
In case you want to migrate, see chapter “Data Migration”.
If you want to perform a completely new installation you can skip the migration step.
4. close this dialog with skip or perform the steps for the migration
The PICTUREBOOK settings file: picturebookConfig.properties is loaded automatically.
The file can be found here: <installation_dir>\tomcat\webapps\picturebook\WEB-INF\classes
Now you can set up the configuration of PICTUREBOOK that fits to your environment.
Server Settings
The most important setting is the Server ID a unique ID of the PICTUREBOOK installation used
to identify a certain PICTUREBOOK server in the network of multiple servers.
The Server ID is very important for the PICTUREBOOK internal workflow and should always be
the same for each PICTUREBOOK instance. It must also be used if this PICTUREBOOK server is
moved or migrated. It is also important for the setup of trusted hosts for replication.
5. select the paths where the physical data should be stored:
PICTUREBOOK is saving files with a hash name in the picturebook_filestore directory.
The picturebook_temp directory is used during runtime and when uploading files to the server.
The picturebook_cache is used to cache the thumbnails and screenshots of the assets.
Default settings are:
fileStore=C:/pdata/picturebook_filestore
tmpDir=C:/pdata/picturebook_temp
imageCache=C:/pdata/picturebook_cache
DO NOT change this Server ID
after the server was initialized
with this id. It could harm
your system!
3DEXCITE PICTUREBOOK Technical System Description 5
6. define the log-file path and log level:
This value defines the location for the log files written by tomcat and the PICTUREBOOK
application. By default the tomcat logging directory is selected. All files inside that directory
can be cleaned up automatically, see notes below.
Furthermore, you can define the level of log details that shall be written to the files. Choose
between four options: “error”, “warn”, “info”, “debug”. While “debug” is the most detailed log
and “error” the least detailed.
7. set Progress logging:
You can switch on progress logging which gives you detailed information about the background
processes for replication and notification. The progress log time limit is set to 10 days by
default. That means log entries older those 10 days will be removed automatically from the
database. You can access the entries inside the “ManagementConsole” under the term “System
logging”.
8. set user logging and notification:
Switching on the user logging functionality will log almost every action of the user into
the database. Based on this functionality there are features like folder tracking and e-mail
notification that informs users on changes of certain content that they observe. The
“notification cycle time” indicates when the notification thread shall check for changes on
content, inform users and defines how long the thread shall wait for the next cycle. The default
value is set to 60 minutes.
9. set the Cleanup Files:
In addition, you can enable an automatic cleanup of outdated user log entries. Therefore set the
value for removing old entries to a number that fits your needs. On default automatic cleanup
is disabled. The default value for cleaning up is set to one year.
Enable the cleanup if you want to remove outdated server log files from your hard drive if they
are older than the specified age. The cleanup thread runs in background and checks periodically
for files to delete.
Additionally, you can enable to clean up the PICTUREBOOK’s temporary directory when
starting the server. Files inside that directory are removed if they are older than the specified
age. This clean up performs only once when starting the server application.
10. save the changes
Additional optional setting tabs
Replication Settings: see chapter “Preparation for Replication”
SSL Settings: Detailed information: “Additional SSL settings”
Tomcat Settings: see chapter “Appendix - Configuration of ports for PICTUREBOOK”
LDAP Settings: If you use an LDAP server, see chapter “Appendix - LDAP”
E-mail Settings: If you want to use notification feature and e-mail functionality, see chapter
“Appendix - E-mail Settings”
Image Conversion Settings: see chapter “Appendix - Image Conversion Settings”
Misc. Settings: see chapter “Appendix - E-mail Settings”
POWERHOUSE Settings: see chapter “Appendix - POWERHOUSE Settings”
Meeting Settings: see chapter “Appendix - Meeting Settings”
About Settings: see chapter “Appendix - About PICTUREBOOK”
Database settings 11. start your database
12. in the left menu of the PictureBook Admin select Database settings
Switching off user logging will
disable the folder tracking and
e-mail notification.
The bundled PostgreSQL
database should already be
started as a service.
3DEXCITE PICTUREBOOK Technical System Description 6
If you have Oracle selected as
your database, you can add
some hints to improve the
fetching performance when
loading the folder tree and when
checking rights of users.
The settings are loaded from the files applicationContext-core.xml and applicationContext-
localDatasource.xml.
For the bundled PostgreSQL database there is no need to modify the default settings.
13. click on initialize DataBase
This creates the database,create tables and related components (PICTUREBOOK database
schema). It uses the settings of the database you have previously configured.
A console appears for the initialisation and creation.
14. follow the initialisation steps
15. click Test Connection after the successful initialization
This tests if the database was initialized successfully.
16. save your changes
Initializing PICTUREBOOK server installation
Creating a Keystore 17. click on initialize Keystore
This generates a valid keystore file for the server. The keystore file is needed by Apache Tomcat
to run it also properly in HTTPS mode. For more Information see chapter: “Create your own
Keystore”.
Initialization of the PICTUREBOOK server
The initialization of PICTUREBOOK inserts some default entries into the database like labels,
system user, default content etc. This is an important step. Without having PICTUREBOOK
initialized you cannot login into the application or working with the server.
You can start that script from the PICTUREBOOK Admin:
18. select in the left menu init Phases
19. click on initialize PiCtUreBooK
If you already have an existing
database or you want to create a
database on your own, please
make sure that the used
encoding of this database is
UTF8.
3DEXCITE PICTUREBOOK Technical System Description 7
Starting the PICTUREBOOK server
With the PICTUREBOOK Admin you have different choices to start the PICTUREBOOK server.
• You can install PICTUREBOOK as a service and start/stop it via the PICTUREBOOK Admin.
• You can use PICTUREBOOK in Console mode and start/stop it via PICTUREBOOK Admin
You can start PICTUREBOOK alternatively via Startmenu > Program > Dassault Systemes >
3DEXCITE > PICTUREBOOKX.Y > Start PICTUREBOOK
The start script will also start the XMLRPC and OpenOffice in console mode.
The tomcat console window should be opened with some log output:
[...]
org.apache.coyote.http11.Http11Protocol start
INFO: Starting Coyote HTTP/1.1 on http-8080
org.apache.coyote.http11.Http11Protocol start
INFO: Starting Coyote HTTP/1.1 on http-8443
org.apache.jk.common.ChannelSocket init
INFO: JK: ajp13 listening on /0.0.0.0:8009
org.apache.jk.server.JkMain start
INFO: Jk running ID=0 time=0/31 config=null
org.apache.catalina.startup.Catalina start
INFO: Server startup in 54148 ms
For more information, check chapter “PICTUREBOOK server”.
IMPORTANT
If you change any server or database settings for PICTUREBOOK, you have to restart the server
to apply changes.
INSTALLATION GUIDE PICTUREBOOK ON LINUX WITH GUI
Please make sure that you have “root” rights on this machine.
Server preparation
Please make sure, that no application is running on port 8080 or 8443 of your server.
Any preinstalled Sun Java Runtime Environments (JRE) is not needed.
PICTUREBOOK includes his own JRE 1.7.
Default installation ports used: 8080(HTTP Protocol)/ 8443(HTTPS Protocol)
IMPORTANT
There is no bundled PostgreSQL database for any Linux installation. Please install a PostgreSQL
8.4 or higher database manually, if necessary. If you have a prior version installed, update the
database to the latest recommended version.
Installation 1. start installer executing the script:
./PICTUREBOOK_Setup_X.Y.sh
You can start the installer on your console to install PICTUREBOOK without a GUI based
installation guide.
For that please check out chapter ”Installation Guide PICTUREBOOK Manually Setup”.
2. click next
3. select the directory where you want to install picturebook
4. click next
3DEXCITE PICTUREBOOK Technical System Description 8
5. choose the components you want to install
We recommend installing all components in order to user PICTUREBOOK in a proper way.
6. follow installation routine
The installation might take a while for copying all files to the installation directory.
You can follow up with starting the PICTUREBOOK Admin in order to configure you installation.
7. check start PiCtUreBooK aDMin now
PICTUREBOOK requires a 32 Bit
version of GhostScript 9.06 in
order to generate previews of
Office documents and PDF’s.
GhostScript is not bundled with
this installer, hence you will
have to download it and install it
by yourself. Missing GhostScript
installation will not break your
system but previews will not be
generated.
3DEXCITE PICTUREBOOK Technical System Description 9
CONFIGURATION OF PICTUREBOOK SERVER USING PICTUREBOOK ADMIN IN LINUX
The configuration of the PICTUREBOOK server can be done with the PICTUREBOOK Admin,
which is a tool to setup and edit all settings for PICTUREBOOK in a comfortable way.
1. start the PiCtUreBooK aDMin with the following script:
<installation_dir>/startPictureBookAdmin.sh
Licensing 2. copy the license file
PICTUREBOOK Admin supports you installing the license file for PICTUREBOOK (icense.lic).
To get a valid license, please contact our Support.
The license information is displayed on the first tab of the application. Version and the expiration
date are checked and will be marked in red if there is a problem e.g. when the license is expired.
Migration After a new installation, a dialog offers you to migrate from a previous PICTUREBOOK version
when selecting “PICTUREBOOK Settings” in the left menu bar.
3. decide if you want to migrate from a former version or not
In case you want to migrate, see in “Data Migration Version”
If you want to perform a completely new installation you can skip the migration step.
4. close this dialog with skip or perform the steps for the migration
The PICTUREBOOK settings file: picturebookConfig.properties is loaded automatically.
The file can be found here: <installation_dir>\tomcat\webapps\picturebook\WEB-INF\classes
Now you can set up the configuration of PICTUREBOOK that fits to your environment.
Server Settings The most important setting is the Server ID a unique ID of the PICTUREBOOK installation used
to identify a certain PICTUREBOOK server in the network of multiple servers.
The Server ID is very important for the PICTUREBOOK internal workflow and should always be
the same for each PICTUREBOOK instance. It must also be used if this PICTUREBOOK server is
moved or migrated. It is also important for the setup of trusted hosts for replication.
5. select the paths where the physical data should be stored:
PICTUREBOOK is saving files with a hash name in the picturebook_filestore directory. The
picturebook_temp directory is used during runtime and when uploading files to the server. The
picturebook_cache is used to cache the thumbnails and screenshots of the assets.
Default settings are:
fileStore=/pdata/picturebook_filestore
tmpDir=/pdata/picturebook_temp
imageCache=/pdata/picturebook_cache
6. define the log-File Path anD log level:
This value defines the location for the log files written by tomcat and the PICTUREBOOK
application. By default the tomcat logging directory is selected. All files inside that directory
can be cleaned up automatically, see notes below.
Furthermore, you can define the level of log details that shall be written to the files. Choose
between four options: “error”, “warn”, “info”, “debug”. While “debug” is the most detailed log
and “error” the least detailed.
7. set Progress logging:
You can switch on progress logging which gives you detailed information about the background
processes for replication and notification. The progress log time limit is set to 10 days by
default. That means log entries older those 10 days will be removed automatically from the
database. You can access the entries inside the “ManagementConsole” under the term “System
logging”.
There is a dummy license file
already in the target directory.
Confirm overwriting that
dummy file when installing a
new license.
Server ID after the server was
initialized with this id. It could
harm your system!
DO NOT change this
3DEXCITE PICTUREBOOK Technical System Description 10
8. set User logging anD notiFiCation:
Switching on the user logging functionality will log almost every action of the user into
the database. Based on this functionality there are features like folder tracking and e-mail
notification that informs users on changes of certain content that they observe. The
“notification cycle time” indicates when the notification thread shall check for changes on
content, inform users and defines how long the thread shall wait for the next cycle. The default
value is set to 60 minutes.
9. set the CleanUP Files:
In addition, you can enable an automatic cleanup of outdated user log entries. Therefore set the
value for removing old entries to a number that fits your needs. On default automatic cleanup
is disabled. The default value for cleaning up is set to one year.
Enable the cleanup if you want to remove outdated server log files from your hard drive if they
are older than the specified age. The cleanup thread runs in background and checks periodically
for files to delete.
Additionally, you can enable to clean up the PICTUREBOOK’s temporary directory when
starting the server. Files inside that directory are removed if they are older than the specified
age. This cleanup performs only once when starting the server application.
10. save the changes
Additional optional setting tabs
Replication Settings: see chapter “Preparation for Replication”
SSL Settings: see chapter “Additional SSL settings”
Tomcat Settings: see chapter “Appendix - Configuration of ports for PICTUREBOOK”
LDAP Settings: If you use an LDAP server, see chapter “Appendix - LDAP”
E-mail Settings: If you want to use notification feature and e-mail functionality, see chapter
“Appendix - E-mail Settings”
Image Conversion Settings: see chapter “Appendix - Image Conversion Settings”
Misc. Settings: see chapter “Appendix - E-mail Settings”
POWERHOUSE Settings: see chapter “Appendix - POWERHOUSE Settings”
Meeting Settings: see chapter “Appendix - Meeting Settings”
About Settings: see chapter “Appendix - About PICTUREBOOK”
Database Settings 11. start your database (if the database service is not running yet, please start it in order to proceed)
For PostgreSQL (user: postgres):
su postgres
initdb -D /var/lib/pgsql/data
postmaster -i -D /var/lib/pgsql/data
For manual creation of the database and the database user use the following commands,
otherwise continue with step 13.
12. create the picturebook database
PICTUREBOOK needs a new database/SID where the tables and the data are being stored.
In case you haven’t created a new database yet, please create one in order to proceed. Make
sure the database uses UTF8 encoding.
Additionally you will need a dedicated database user to run PICTUREBOOK with.
For PostgreSQL (user: postgres):
createdb –E UTF8 -O picturebook -U picturebook picturebook
(-E = encoding, -O = owner of the db, -U = database user, database name)
Switching off user logging will
disable the folder tracking and
e-mail notification.
13. create a user
createuser -s -W <username>
(W = set password, Username = picturebook)
3DEXCITE PICTUREBOOK Technical System Description 11
For m
14. in the DataBase settings tab click initialize DataBase
The database settings are loaded from the files applicationContext-core.xml and
applicationContext-localDatasource.xml.
Initialization uses the settings of the database you configured and saved before to initialize
your database.
The settings like username and password are passed to the “init_database” script as parameter.
The default database path needs to be set within the script.
You can give the following parameter to the script:
initDatabase_<databasename>.sh databasename port user password
15. click test ConneCtion
This tests if the database was initialized successfully.
16. save your changes
Initializing PICTUREBOOK server installation
Creating a Keystore
17. click initialize Keystore in order to generate a valid keystore file for the server
The keystore file is needed by Apache Tomcat to run properly in HTTPS mode.
For more Information see chapter: “Create your own Keystore”
Initialization of the PICTUREBOOK server 18. in the left menu select init Phases
19. click on initialize PiCtUreBooK
Starting your PICTUREBOOK server 20. go to the server console
21. type: <installation_dir>/startpicturebook.sh
The start script also starts the XMLRPC and OpenOffice in console mode.
See <installation_dir>/tomcat/logs/catalina.out for server logs:
[...]
org.apache.coyote.http11.Http11Protocol start
INFO: Starting Coyote HTTP/1.1 on http-8080
org.apache.coyote.http11.Http11Protocol start
INFO: Starting Coyote HTTP/1.1 on http-8443
org.apache.jk.common.ChannelSocket init
INFO: JK: ajp13 listening on /0.0.0.0:8009
org.apache.jk.server.JkMain start
INFO: Jk running ID=0 time=0/31 config=null
org.apache.catalina.startup.Catalina start
INFO: Server startup in 54148 ms
22. to stop the picturebook server, run the following script:
<installation_dir>/stopPictureBook.sh
ore information see chapter: “PICTUREBOOK Server”.
IMPORTANT
If you change any server or database settings for PICTUREBOOK, you have to restart the server
to apply changes.
If you have Oracle selected as
your database, you can add
some hints to improve the
fetching performance when
loading the folder tree and when
checking rights of users.
If you already have an existing
database or you want to create a
database on your own, please
make sure that the used
encoding of this database is
UTF8.
3DEXCITE PICTUREBOOK Technical System Description 12
INSTALLATION OF PICTUREBOOK MANUALLY
Server preparation • Please make sure, that no application is running on port 8080 or 8443.
• Any preinstalled Sun Java Runtime Environments (JRE) is not needed. PICTUREBOOK includes his own JRE 1.7.
Default installation ports used: 8080 (HTTP Protocol) / 8443 (HTTPS Protocol)
1. start installer script (linux only)
./PICTUREBOOK_Setup_X.Y.sh
2. follow the instruction
We recommend using the default settings. Please make sure that you have “root” rights on
this machine.
Licensing 3. copy license file into the directory:
<installation_dir>/tomcat/webapps/picturebook/WEB-INF/classes
To get a valid license, contact our Support.
Server Settings
4. edit main configuration
The main configuration settings are in the file:
<installation_dir>/tomcat/webapps/picturebook/WEB-INF/classes/
picturebookConfig.properties
Inside this configuration file you’ll find some short description for each setting. Here are the
most important settings mentioned and explained what to set up there.
Common settings: The most important setting is the Server ID a unique ID of the PICTUREBOOK installation
used to identify a certain PICTUREBOOK server in the network of multiple servers.
The Server ID is very important for the PICTUREBOOK internal workflow and should always be
the same for each PICTUREBOOK instance. It must also be used if this PICTUREBOOK server is
moved or migrated. It is also important for the setup of trusted hosts for replication.
serverId=<unique_12_chars_id>
Server ID must be set in UPPERCASEfor example: 00AB120034FF.
Filestore settings:
PICTUREBOOK is saving files with a hash name in the picturebook_filestore directory. The
picturebook_temp directory is used during runtime and when uploading files to the server. The
picturebook_cache is used to cache the thumbnails and screenshots of the assets.
Default settings for Linux are:
fileStore=/pdata/picturebook_filestore
tmpDir=/pdata/picturebook_temp
imageCache=/pdata/picturebook_cache
Default settings for Windows are:
fileStore=c:/pdata/picturebook_filestore
tmpDir=c:/pdata/picturebook_temp
imageCache=c:/pdata/picturebook_cache
Log-file settings:
This value defines the location for the log files written by tomcat and the PICTUREBOOK
application. By default the tomcat logging directory is selected. All files inside that directory
can be cleaned up automatically. Enable the cleanup if you want to remove outdated server log
files from your hard drive if they are older than the specified age. The cleanup thread runs in
background and checks periodically for files to delete.
logFileDir=<installation_dir>/tomcat/logs
enableAutoLogFileCleanup=false
PICTUREBOOK requires a 32 Bit
version of GhostScript 9.06 in
order to generate previews of
Office documents and PDF’s.
GhostScript is not bundled with
this installer, hence you will
have to download it and install it
by yourself. Missing GhostScript
installation will not break your
system but previews will not be
generated.
There is a dummy license file
already in the target directory.
Use the name “license.lic” for
the license file in case your
license file is named different.
DO NOT change this
Server ID after the server was
initialized with this id. It could
harm your system!
3DEXCITE PICTUREBOOK Technical System Description 13
cleanupLogfilesOlderThan=180
Progress logging: You can switch on progress logging which gives you detailed information about the background
processes for replication and notification. The progress log time limit is set to 10 day by default.
That means logs entries older than 10 days will be removed from the database automatically.
cleanProgressLogTimeLimit=10
enableProgressLogging=true
User logging and notification Switching on the user logging functionality will log almost every action of the user into the
database. Based on this functionality there are features like folder tracking and e-mail notification
that informs users on changes of certain content that they observe. The “notification cycle time”
indicates when the notification thread shall check for changes on content, inform users and
defines how long the thread shall wait for the next cycle. The default value is set to 60 minutes.
You can enable an automatic cleanup of outdated user log entries. Therefore set the value for
removing old entries to a number that fits your needs. On default the automatic cleanup is
disabled. The default value for cleaning up old entries is set to one year.
enableEmailNotification=true
notificationCycleTime=60
enableUserLogging=true
enableAutoCleanupUserLogs=false
cleanUserLogOlderThan=365
For more information open the main configuration file mentioned at the beginning of this
chapter. Every property in this settings file has a comment explaining the purpose of it.
Additional optional settings
Replication Settings: Detailed information in chapter: “Preparation for Replication”
SSL Settings: Detailed information: “Additional SSL settings”
Tomcat Settings: Detailed information in chapter: “Appendix - Configuration of ports for
PICTUREBOOK”
LDAP Settings: If you use an LDAP server, see chapter: “Appendix - LDAP”
E-mail Settings: If you want to use notification feature and e-mail functionality, see chapter:
“Appendix - E-mail Settings”
Image Conversion Settings: Detailed information in chapter: “Appendix - Image Conversion
Settings”
Misc. Settings: Detailed information: “Appendix - E-mail Settings”
POWERHOUSE Settings: Detailed information: “Appendix - POWERHOUSE Settings”
Meeting Settings: Detailed information: “Appendix - Meeting Settings”
About Settings: Detailed information: “Appendix - About PICTUREBOOK”
Database Settings 5. edit database settings
The database settings must be configured in the following file:
<installation_dir>/tomcat/webapps/picturebook/WEB-INF/classes/
applicationContext-localDataSource.xml
By default PICTUREBOOK is using a connection pool to avoid too many open connections to
the database. The connection pool settings are defined in the applicationContext-core.xml.
<!-- C3P0 Connection pooling – PostgreSQL settings --> <bean id=”dataSource” class=”com.mchange.v2.c3p0.ComboPooledDataSource”>
<property name=”driverClass”> <value>org.postgresql.Driver</value>
</property> <property name=”jdbcUrl”>
<value>jdbc:postgresql://<hostname>:5432/picturebook</value> </property>
Switching off user logging will
disable the folder tracking and
e-mail notification.
3DEXCITE PICTUREBOOK Technical System Description 14
<property name=”user”><value>picturebook</value></property> <property name=”password”><value>picturebook</value></property>
</bean>
If you do not want to use the connection pooling, you can enable the normal connection
settings:
<bean id=”dataSource” class=”org.springframework.jdbc.datasource. DriverManagerDataSource”>
<property name=”driverClassName”> <value>org.postgresql.Driver</value>
</property> <property name=”username”><value>picturebook</value></property> <property name=”password”><value>picturebook</value></property> <property name=”url”>
<value>jdbc:postgresql://<hostname>:5432/picturebook</value> </property>
</bean>
Other DBMS:
PostgreSQL: org.postgresql.Driver
jdbc:postgresql://<hostname>:5432/picturebook
Oracle 9i/10g/11: oracle.jdbc.driver.OracleDriver
jdbc:oracle:thin:@<hostname>:1521:picturebook
MSSQL 2005 / 2008: net.sourceforge.jtds.jdbc.Driver
jdbc:jtds:sqlserver:
//<hostname>:1433;DatabaseName=picturebook
Setting up hibernate dialect manually 6. open the following file:
<installation_dir>\tomcat\webapps\picturebook\WEB-INF\classes\applicationContext-core.
xml
7. type
<prop key=”hibernate.dialect”>
org.hibernate.dialect.PostgreSQLDialect
</prop>
Other DBMS:
PostgreSQL: org.hibernate.dialect.PostgreSQLDialect
Oracle 9i/10g: org.hibernate.dialect.Oracle9Dialect
It is very important
that hibernate dialect
matches to the database
settings in the
applicationContext-
localDataSource.xml!
MSSQL 2005 or higher: org.hibernate.dialect.SQLServerDialect
8. create database and import the prepared schema
You can also use the one of the appropriate scripts to import the schema in your database.
9. choose the right script for your database.
10. start the appropriate script and follow the instructions.
<installation_dir>/scripts/initDatabase_<databasename>.sh (Linux)
<installation_dir>/scripts/initDatabase_<databasename>.cmd (Win)
Settings like username and password can be set as parameter for the init-script. The default
database path needs to be set within the script.
You can give the following parameter to the script:
initDatabase_<databasename>.sh databasename port user password
initDatabase_<databasename>.cmd databasename port user password
Import schema manually If you don’t want to use the above script, you can setup the database schema manually and use
the appropriate schema in
<installation_dir>/scripts/schema.
If you already have an existing
database, please make sure that
the used encoding of this
database is UTF8.
PostgreSQL:
11. if you don’t have a database already created, go to your postgresQl bin directory and can create it
with the command:
createdb –E UTF8 -O picturebook -U picturebook picturebook
3DEXCITE PICTUREBOOK Technical System Description 15
(-E = encoding, -O = owner of the db, -U = database user, database name)
12. use the following command to import the schema into your database:
psql -d picturebook -f /scripts/schema/postgresql-schema-create.sql -q -X -p 5432 -U
picturebook
(-d = database, -f = script file, -p = port, -U = user)
Tip: for help, see http://www.postgresql.org/docs/8.4/static/app-psql.html
Initialization of the PICTUREBOOK server 13. execute the following script
<installation_dir>/scripts/initPictureBook.sh (Linux)
<installation_dir>/scripts/initPictureBook.cmd (Windows)
This creates the file store folders and writes initial information into the database.
14. generate a valid keystore file for the server executing the appropriate script:
<installation_dir>/scripts/initKeystore.sh (Linux)
<installation_dir>/scripts/initKeystore.cmd (Windows)
The keystore file is needed by Apache Tomcat to run it also properly in HTTPS mode. For more
Information see chapter: “Create your own Keystore”
Starting the PICTUREBOOK server 15. start the server on console with
<installation_dir>/startPictureBook.sh (Linux)
<installation_dir>/startPictureBook.cmd (Windows)
The start script starts the XMLRPC and OpenOffice in console mode.
PICTUREBOOK on Linux needed
a running X11 server to work
properly in the past. The
X11server connection was
needed for the creation of
thumbnails for formats like psd,
See <installation_dir>/tomcat/logs/localhost.log for tomcat log and picturebook.log for detailedtga or tiff. If you have trouble
server logs:
[...]
org.apache.coyote.http11.Http11Protocol start
INFO: Starting Coyote HTTP/1.1 on http-8080
org.apache.coyote.http11.Http11Protocol start
INFO: Starting Coyote HTTP/1.1 on http-8443
org.apache.jk.common.ChannelSocket init
INFO: JK: ajp13 listening on /0.0.0.0:8009
org.apache.jk.server.JkMain start
INFO: Jk running ID=0 time=0/31 config=null
org.apache.catalina.startup.Catalina start
INFO: Server startup in 54148 ms
16. to stop the picturebook server, run the following script:
<installation_dir>/stopPictureBook.sh (Linux)
<installation_dir>/stopPictureBook.cmd (Windows)
For more information see chapter: “PICTUREBOOK Server”.
IMPORTANT
If you change any server or database settings for PICTUREBOOK, you have to restart the server to
apply your changes.
with this release, start an X11
server and try again
3DEXCITE PICTUREBOOK Technical System Description 16
CONNECT DELTAGEN TO PICTUREBOOK SERVER
3DEXCITE DELTAGEN connects to PICTUREBOOK via the “PICTUREBOOK Browser” plug-in.
The PICTUREBOOK installer contains suitable plug-ins for the current and previous release of
DELTAGEN. Nevertheless, make sure the DELTAGEN or DELTAVIEW plug-in are installed for the
right version on the server.
DELTAGEN downloads the plug-in from the server and shows the flex login screen. If there is
no dedicated plug-in installed, DELTAGEN cannot connect to PICTUREBOOK.
See chapter “Appendix Application Plug-ins” for details about plug-ins.
1. start deltagen
2. navigate to file > picturebook > open
Here you can choose existing server connection, manage them or create new connections.
Opens the dialog to create a new server connection.
Edits the current selected connection.
Removes the current selected connection.
3. enter the server url for picturebook server and a name for this connection.
The server URL consists of the following parts:
HTTP: http://<IP or hostname>:8080/picturebook
HTTPS: https://<IP or hostname>:8443/picturebook
Note: If you want to use https make sure you have installed a valid certificate on this client and
use the hostname that the certificate is created for. To install the certificate open your Internet
Explorer and type in the https URL to the server. Don’t use the IP here.
Maintain in the line “Service url“ the URL to the PICTUREBOOK server and set a unique name
in the line “Label“. The URL should look like:
• Protocol (http or https) followed by “://”
• IP address or hostname (if https should be used the complete hostname with which the
certificate was created)
• the used port (:8080 for http or :8443 for https)
Examples: http://10.10.10.10:8080/picturebook
http://hostname:8080/picturebook
https://hostname.muc.de:8443/picturebook
Login Use default credentials after installation, unless you have changed the password already
User: superuser
Password: superuser
If you want to use https make
sure you have installed a valid
certificate on this client and use
the hostname that the
certificate is created for. To
install the certificate open your
Internet Explorer and type in the
https URL to the server. Don’t
use the IP here.
If you use https you have to set
the server name for which the
SSL certificate was created.
Normally this is the DNS
hostname of the Server.
3DEXCITE PICTUREBOOK Technical System Description 17
CREATE YOUR OWN HTTPS KEYSTORE / SSL SETUP
Create Keystore
Apache Tomcat server needs a valid keystore file to run properly. You have to create such a file
during installation process.
1. use the PiCtUreBooK aDMin or one of the following scripts to create automatically a keystore file
(with current hostname as common name):
<installation_dir>\scripts\initKeystore.cmd - Windows
<installation_dir>/scripts/initKeystore.sh - Linux
The keystore file is now located in <installation_dir>\tomcat\keystore
Additional SSL settings
Each PICTUREBOOK server that’s taking part in encrypted replication process must have
installed a client side certificate of the remote servers. To extract such a client side certificate
out of the server to trust, use the following keytool command on the server:
Automatic creation You can use the PICTUREBOOK Admin to import and export the certificates.
2. export your own certificate from the keystore that you have created during installation procedure
of PICTUREBOOK.
3. exchange the certificate file (*.cer) with the certificate of the remote server that you want to trust.
4. import the remote certificate file into the truststore of picturebook. use the same alias to
import as you have used when exporting this certificate.
5. additionally you can use the following script to create automatically a certification file:
<installation_dir>\scripts\exportCertificate.cmd - Windows
<installation_dir>/scripts/exportCertificate.sh - Linux
The certification file is now located in <installation_dir>\cert-file_<computername>.cer
This certification file needs to be copied to other PICTUREBOOK Server into their installation
directory and needs to be imported there.
6. import a certificate using the following scripts (use the ‘picturebook_<computername>’ as alias):
<installation_dir>\scripts\importCertificate.cmd - Windows
<installation_dir>/scripts/importCertificate.sh - Linux
IMPORTANT
The certification files needs to be in the root installation directory of PICTUREBOOK.
3DEXCITE PICTUREBOOK Technical System Description 18
Manual creation 1. execute the following script
<installation_dir>\jre\bin\keytool -export -alias picturebook_<computername> –
keystore <installation_dir>\tomcat\keystore -rfc -file cert-file
The certificate is now exported into file cert-file.
To import this certificate at client-side use the following keytool command:
<installation_dir>\jre\bin\keytool -import -alias picturebook_<computername>
-file cert-file -keystore <installation_dir>\truststore
The file <installation_dir>\truststore has now the certificate imported.
You can check this with command:
<installation_dir>\jre\bin\keytool –list -keystore <installation_dir>\truststore
This has to be done vice versa, so that all sides trust each other.
PREPARATION FOR REPLICATION
By default, replication is not activated after installation of PICTUREBOOK. For safe data
replication we recommend HTTPS encryption. All PICTUREBOOK servers which want to use
SSL transport have to install a server-side SSL key on the web server side. See chapter “Create
your own HTTPS Keystore“ in this documentation for further information.
Each PICTUREBOOK server that is taking part in encrypted replication process must have
installed a client side certificate of the other servers. To extract such a client side certificate out
of the server to trust, use the following keytool command on the server:
Setting the replication to encrypted 1. start the picturebook admin
2. in the left menu click PiCtUreBooK settings
3. click on loaD settings
4. switch to the rePliCation settings tab
You can edit the settings manually by open the main server configuration file in a text based
editor.
Truststore and keystore file are
two separate files! The truststore
contains certificates of other
servers, not its own one. The
keystore contains only its own
key used to create certificates.
Replication between different
major release versions of
PICTUREBOOK is not supported
due to changes on the
replication feature and the
technical interface.
<installation_dir>\tomcat\webapps\picturebook\WEB-INF\classes\
picturebookConfig.properties
5. find the line “# replication” and change its settings to the following:
Possible replication modes can be: on / off / scheduled
Setting replication mode to “off” disables the replication but will start the thread in case the
state will be changed during runtime via ManagementConsole.
Setting the mode to “on” forces the replication thread to replicate thoroughly in specified
intervals (default 5 min).
Setting replication mode to “scheduled” forces the replication thread to start and to replicate
in defined time periods that are defined for the hosts inside the ManagementConsole. These
3DEXCITE PICTUREBOOK Technical System Description 19
settings can be changed during runtime inside the ManagementConsole but when restarting
the server next time, the value from the settings file is used again.
replicationMode=off
Replication is now set to encoded mode. You have to specify the trustore file where the trusted
Host keys are imported. Per default the trustore file in the installation root of PICTUREBOOK
is selected.
sslTrustStoreFile=truststore
6. click on save Changes
When the server configuration is changed, the server must be restarted that new settings are
used.
7. restart the server
Other Replication settings:
replicationDefaultTimeout (in PBAdmin “Remote Server Response timeout”): Defines the time after how many seconds the replication shall run into the timeout if there is
no connection to another server. The default is set to 60 seconds.
replicationPingTimeout (in PBAdmin “Remote Server Ping timeout”): Defines the time after how many seconds the ping to another host shall stop and run into a
timeout. The default is set to 5 seconds.
replicationDefaultInterval (in PBAdmin “Replication cycle time”): It defines the time interval for the replication thread. It indicates after how many seconds a new
replication cycle should run. The default is set to 5 minutes (300 sec).
fetchContentsInterval (in PBAdmin “Replication cycle time”): Define the maximum number of Assets to fetch from the remote server in a single call. The
default is set to 50. The maximum shall be not more than 100.
remoteServiceRootPath (not shown in PBAdmin): Defines how one host can reach another host. This value is part of the URL that is needed to
connect to a host. It defines the name under which PictureBook is reachable: [protocoll]://[ip]/
[remoteServiceRootPath]/services/
replicationParallel: Defines if replication should be processed in parallel per share (default is true).
compressedReplication: Defines if replication should use compression for files per asset (Zip-compression).
compressionAlgorithm: Defines the used algorithm compression (lzma2, deflate)
compressionMIMETypes: Defines file MIME-Types being considered for compression (if list is empty, no file will be
compressed; if ‘all’ every file is being subject to compression)
compressionMaximumFileSize: Defines the maximum file size when compression should be applied. This setting is only valid
for lzma2-compression. The setting is in MB. High values could slow down the servers implied
in replication for compressing and decompressing.
3DEXCITE PICTUREBOOK Technical System Description 20
PICTUREBOOK SERVER - STARTING / STOPPING
Linux
PICTUREBOOK server start & stop You can start / stop the PICTUREBOOK server with scripts in the console:
<installation_dir>/startPictureBook.sh
<installation_dir>/stopPictureBook.sh
You also need to start two other PICTUREBOOK components that are the XMLRPC server
and the OpenOffice server. These components are starting automatically with the start of
PICTUREBOOK executing the above mentioned script. For detailed information regarding these
components, please see “Appendix - Image Conversion Settings”
In case you want to start them individually, the start scripts are located here:
<installation_dir>/scripts/startXMLRPCServer.sh and
<installation_dir>/scripts/startOpenOffice.sh
For RedHat and SuSE you can also use the provided init.d scripts at:
<installation_dir>/scripts/picturebook-RedHat
<installation_dir>/scripts/picturebook-SuSE
Copy the script to /etc/init.d/picturebook and start / stop the PICTUREBOOK Server with:
/etc/init.d/picturebook start
/etc/init.d/picturebook stop
Log-Files
All actions and movements at the PICTUREBOOK server can be retraced afterwards. This
information will be written in the Log-Files. One Log-file per day.
You can find the Log-Files in:
<installation_dir>/tomcat/logs
Microsoft Windows®
PICTUREBOOK server start & stop
On a Windows machine there are two ways to start / stop PICTUREBOOK server. You can do
that either with the PICTUREBOOK Admin in section Init Phases or on the console with a script.
For this please use the scripts:
<installation_dir>\startPictureBook.cmd
<installation_dir>\stopPictureBook.cmd
You also need to start two other PICTUREBOOK components that are the XMLRPC server
and the OpenOffice server. These components are starting automatically with the start of
PICTUREBOOK executing the above mentioned script. For detailed information regarding these
components, please see “Appendix - Image Conversion Settings”
In case you want to start them individually, the start scripts are located here:
<installation_dir>/scripts/startXMLRPCServer.cmd and
<installation_dir>/scripts/startOpenOffice.cmd
Install PICTUREBOOK server as Microsoft Windows service To install the PICTUREBOOK server and the XMLRPC as well as the OpenOffice as a Windows
service use the PICTUREBOOK Admin, section “Init Phases” or use the following script:
<installation_dir>\installServices.cmd
This script will install three services:
“PICTUREBOOK Server Tomcat” (Service ID = “Tomcat7”),
“PICTUREBOOK OpenOffice” (Service ID = “PBOpenOffice”) and
“PICTUREBOOK XMLRPC Server” (Service ID = “PBXMLRPC”)
The init.d scripts are using the
default PICTUREBOOK
installation path (/opt/
PICTUREBOOKx.y/). If you use a
custom location please edit the
file to reflect the changes.
3DEXCITE PICTUREBOOK Technical System Description 21
Additional service scripts
installServices.cmd installs the PICTUREBOOK application server service
removeServices.cmd removes the PICTUREBOOK application server service
startPictureBookService.cmd starts the PICTUREBOOK server service
stopPictureBookService.cmd stops the PICTUREBOOK server service
Log-Files All actions and movements at the PICTUREBOOK server can be retraced afterwards. This
information will be written in Log-Files. One Log-file is created for each day.
You can find the Log-Files in:
<installation_dir>\tomcat\logs
ACCESS PICTUREBOOK
• Please make sure, that there is no popup blocker activated and cookies should be accepted
automatically
• Privacy settings at most “High” (you may add your PICTUREBOOK server as one of your
trusted sites)
After successfully installing and configuring PICTUREBOOK you can access the user interface
via URL:
http://<hostname>:8080/picturebook or
https://<hostname>:8443/picturebook
PICTUREBOOK Management Console
To administer user, user groups, replication, hosts, tags and access roles, login into the
PICTUREBOOK Management Console:
http://<hostname>:8080/picturebook/admin or
https://<hostname>:8443/picturebook/admin
IMPORTANT
Do not forget to change the password of the pre-installed superuser in the user section!
User: superuser
Default Password: superuser
3DEXCITE PICTUREBOOK Technical System Description 22
APPENDIX - LDAP
Enabling LDAP on the Backend
The PICTUREBOOK server user authentication can take advantage of a LDAP directory server.
You need to set it up properly. You can use the PICTUREBOOK Admin to adapt these settings.
1. define whether to use ldap or not
If value is set to true, then the user passwords will be checked against the defined LDAP server
instead of the local database (except the superuser)
useLdap=false
2. define the ldap server connection parameters (e.g. ldapserver=ldap://nt123:389)
Ldaps is also allwed to use. In this case, please the certificate needs to be imported into Tomcat
server
ldapServer=ldap://ldap.example.com:389
The system account that is used to login to the LDAP user
ldapUser=demo
ldapPassword=demo
The query used to authenticate the system user. Example:
uid=${username},ou=people,ou=project users,dc=com or
ldapUserQuery=cn={username},ou=Picturebookusers,dc=rtt,dc=ag
It depends how the user was created in LDAP
ldapUserQuery=cn={username},ou=Picturebookusers,dc=3dexcite,dc=com
The base of the LDAP search (base DN)
ldapSearchBase=dc=3dexcite,dc=com
3. define the name of the attribute that holds the user id.
ldapSearchQuery=cn={username}
4. define the Query used to authenticate the picturebook user (see ldapuserQuery)
ldapPictureBookUserQuery={username}
5. click test ConneCtion to test the connectivity
or edit this script file at the end (add your username and password for the test) if needed
6. execute the following script:
<installation_dir>\checkLDAP.cmd Microsoft Windows
<installation_dir>/checkLDAP.sh Linux
You can find this line in the console window if the connection check was successful:
[INFO] ag.rtt.picturebook.core.util.LdapSupport::main : Successfully authenticated
user=[yourUserName] against ldap server.
The LDAP directory support
only checks the user password
against the LDAP server.
However, you have to create
each user in the PICTUREBOOK
Server ManagementConsole..
If using LDAPS protocol, the
LDAP server certification must
be imported first using the
import Certificate button in the
SSL tab of the
PICTUREBOOKAdmin.
3DEXCITE PICTUREBOOK Technical System Description 23
Enabling LDAP on the Frontend
With this release, PICTUREBOOK GUI by default is disabled for using LDAP functionality.
Changing the LDAP flag in the PICTUREBOOK Admin tool will write the setting to the frontend
configuration files already.
In case you want to update the frontend manually, change the “useLdap” flag in the following
file and set it to true.
tomcat\webapps\picturebook\config\applicationContext.properties and
tomcat\webapps\picturebook\admin\config\applicationContext.properties
Additionally you have to enable it in all configuration files for your application plugins.
All plugins are listed in the tomcat\webapps\picturebook\plugins directory by their
applicationPliginID
e.g. 001C11F9-EA0E-444C-828E-936BD9F64F54\50.90.001\
These plug-ins also have the applicationContext.properties in the config directory.
APPENDIX - EXTERNAL USER SYNCHRONIZATION & SINGLE SIGN ON
PICTUREBOOK can synchronize external user databases with its own local user database.
The synchronization is executed in defined time intervals and creates user accounts in
the user database of PICTUREBOOK. The users which are subject to the synchronization
need to be assigned to one or more user groups in the external user management system.
One or more of these user groups need to be declared in the PICTUREBOOK Admin tool.
Both user databases, the external as well as PICTUREBOOK’s user database,
are using most likely different user attributes. Therefore make sure you define
a proper attribute mapping explained in the following configuration properties section.
The synchronization of PICTUREBOOK’s user database with external user systems (e.g. LDAP)
makes only sense if the password authentication takes also place of via the latter. Hence it is
required to enable LDAP on PICTUREBOOK as described in Chapter: “Appendix - LDAP” on
page 22.
Synchronization settings Three properties need to be set for the External User Synchronization:
1. activate the external User synChronization thread
The synchronization thread will be started during the server startup.
enableExternalUserSynch=false
2. define the time interval of the synchronization thread to be executed in seconds
(default value: 1800, min value: 60; max value: 1000000)
externalUserSynchCycleTime=1800
3. define the user attributes mapping between picturebook user attributes and external user
attributes
{(PICTUREBOOK)attributeName=(EXTERNAL USER)attributeName},{...}
3DEXCITE PICTUREBOOK Technical System Description 24
Mandatory PICTUREBOOK user attributes:
loginName,externalUserId, firstName and/or lastName (at least one of each)
externalUserSynchMappedUserBeanAttributes=loginName=cn,externalUserId=uid,f
irstName=givenName,lastName=sn,email=mail
Optional PICTUREBOOK user attributes: language[possible values: en/de/kr/cn/es],email,comp
any,department,description,mobile,phone
Single Sign On (SSO) It is recommended to use Signle Sign On only in combination with LDAP. SSO is not activated
by default. The PICTUREBOOK SSO feature is checking for a USERID transmitted as header
parameter information in each HTTP request.Before you activate SSO at your PICTUREBOOK
installation please contact your Administration to get the name of the parameter embedded in
the HTTP request header.
Flag for activating SSO: useSSO=false
Name of the SSO authentication header parameter: authHeaderParameterNameSSO=id-user
APPENDIX - MISC. SETTINGS
Within this section you can enable or disable the functionality to use a sign up page to let user
create their own PICTUREBOOK account and you can enable or disable a password reset page
that user can use to get new passwords if they have lost theirs.
Signup The sign up to PICTUREBOOK is only working if an Administrator has set up some rules for new
users who want to get a PICTUREBOOK Account.
These rules are bound to the email address a user has to use for the login name. According to
that email address, a condition can be created to assign this user automatically to an existing
user group so he gets automatically rights on folder where the user group has been assigned to.
To set up these conditions, you need to login as Administrator into PICTUREBOOK
ManagementConsole
use the following link:
http://localhost:8080/picturebook/assignmentConditionManagement.do
or click on the “sessions” button in the right upper corner
This forwards you to the PICTUREBOOK server pages.
The signup page itself can be accessed with the following link:
The attribute ‘password’ cannot
be considered for the external
user synchronization. (LDAP
does not deliver plain text
passwords). A mockup will be
set automatically.
3DEXCITE PICTUREBOOK Technical System Description 25
http://localhost:8080/picturebook/signup.do
Reset password
The reset password page can be accessed with the following link:
http://localhost:8080/picturebook/resetpassword.do
APPENDIX - IMAGE CONVERSION SETTINGS
General Setup
PICTUREBOOK uses two separate components for converting various image formats and to
convert and generate page previews for office documents and PDF’s. These components are
the XMLRPC server and the OpenOffice.
The XMLRPC server is using Python Image Library and ImageMagick to convert images.
OpenOffice is used to convert office documents and to create images out of every page.
In order to accomplish that, ImageMagick needs GhostScript 32Bit version 9.06 to be installed.
make sure both components are running and their ports are not blocked
OpenOffice is listening on 2002 by default and XMLRPC is using port 8800.
You can change the port for OpenOffice in the cmd scripts for starting this component and in
the OOConverter.py located in tomcat/webapps/picturebook/WEB-INF/lib/Lib.
All supported formats are defined in the converterMapping.properties that is located in tomcat/
webapps/picturebook/WEB-INF/classes. The configuration is defined in a JSON structure that
is explained within this settings file.
Our in-house consulting can provide more specific conversion on demand such as a conversion
for FBX models into CSB models using POWERHOUSE.
Image Conversion Settings PICTUREBOOK is trying to create a thumbnail of every asset containing a preview and for any
other image that is used for instance for folder previews.
The default dimension for those thumbnails is set to 400x400. All thumbnails are saved to
the picturebook_cache. If you change the resolution, all thumbnails have to be generated
again. Same if you empty the cache folder. The file size limitation is set to 150MB per default
to avoid low performance. This value is dependent on the memory settings you define for
PICTUREBOOK and on the physical memory.
You also can define if all pages of PDF or Office documents shall be converted to single image
previews. This includes the page preview generation after a document was uploaded into
PICTUREBOOK. Disabling the options here will also disabling the preview creation on upload
for such documents.
Furthermore you can define the default height and width for these page previews. The current
limit according page size is set to 200. That means a document having more than 200 pages
will not be converted. This is due to performance and speed since a conversion of such a file
can take a while up to minutes.
The default address to communicate with the XMLRPC server is set to: http://localhost:8800
These two features are
dependent on a proper email
setup because users will be
notified via email when signing
up or when resetting their
password.
3DEXCITE PICTUREBOOK Technical System Description 26
APPENDIX - E-MAIL SETTINGS
switch to the e-Mail settings tab to configure the settings for e-mail functionality of picturebook.
These settings are used for the e-mail functionality of PICTUREBOOK e.g. to notify a user if a
project was modified If no valid server e-mail is set, the notification functionality doesn’t work.
To configure the look and content of these e-mails, load the default e-mail template by clicking
on the “Load Template” button. You can use plain text or html code to configure this template.
If you want to use e-mail service provider like Google mail which requires TLS authentication,
please make sure the trustore file in the installation root of PICTUREBOOK is defined in the SSL
trustore settings.
APPENDIX - POWERHOUSE SETTINGS
POWERHOUSE is the name of a system consisting of a set of our services and a scalable SOA
distribution layer to access these services.
PICTUREBOOK Service Settings One integral part of this architecture is the service MediaStore. MediaStore is a distributed
storage frontend, which enables other POWERHOUSE components to access files or data.
One possible data source for the MediaStore is a PICTUREBOOK server. To make this possible,
you have to setup your PICTUREBOOK server to act as a service that can be queried by the
MediaStore.
Register service at Powerhouse RAM: This checkbox must be checked, if this PICTUREBOOK
instance should be used by a MediaStore.
Service protocol: The MediaStore identifies data using URI’s. A URI could look similar to this:
pwhpb://repo1/?uid=123834872342_123876123. This setting configures the protocol part,
which is used for contents and files hosted on this PICTUREBOOK server. You usually shouldn’t
change this value.
Content Repository Name, File Repository Name: In a MediaStore URI the part after the protocol is
called the repository name. In case of pwhpb://repo1/?uid=123834872342_123876123 the
Do not delete the
“messagePlaceholder” in the
template! This placeholder will
be replaced by the message that
comes from the PICTUREBOOK
Server.
3DEXCITE PICTUREBOOK Technical System Description 27
repository name would be “repo1”. The MediaStore uses this repository name, to decide two
things:
• To which PICTUREBOOK server does this URI refers.
• Does it refer to a PICTUREBOOK Asset (e.g. a Model, a FileSet or a File – everything that is
selectable from the Asset View in the PictureBook) or to a concrete File added to an Asset
(accessible via “Files” in the details of a selected Asset).
To make sure, that the MediaStore can identify the server and type of an URI correctly, you
need to make sure that both repository names are unique in your whole POWERHOUSE cluster.
That means as long as you have only one PICTUREBOOK server, you can leave this settings as
they are. But if you add another server, you need to change them to e.g. repo3 and repo4 for
the new server.
PICTUREBOOK MediaStore User Settings
The POWERHOUSE service MediaStore needs to access PICTUREBOOK in order to download
models and surroundings, which are loaded within the 2DArt or Angle feature. Set credentials:
1. enter a user name in the text field.
2. set a password by using the provided button.
The same user and password will have to be stored in the configuration file of your
POWERHOUSE Installations. To do so, the password first needs to be encrypted:
1. on a machine where powerhouse is installed, browse http://localhost:4282/mediastore/
2. enter the password in the text field and select “encrypt password”
3. within the installation folder of your powerhouse installation open etc\powerhouse.conf, find
the “picturebook” settings and insert the username and the encrypted password
4. restart the mediastore service on that machine
Service Port Settings
“Service Port HTTP”, “Service Port HTTPS”: These settings are used, when registering your
service at the POWERHOUSE RAM. Make sure, that the two ports match the configuration of
your Tomcat servlet container in which the PICTUREBOOK is deployed.
To make sure, that your PICTUREBOOK registered itself correctly as a POWERHOUSE service,
check your local Powerhouse installation:
1. go to http://localhost:2080/ram/ in a web browser
2. click on your local host name
Now you should see an entry with the following values:
• class: picturebook
• version: 1
• port: 8443
• status: repository=repo1 repository=repo2
POWERHOUSE Integration Settings: Another important task of the POWERHOUSE architecture is to provide the possibility to
perform rendering on remote render services (DELTAGEN).
If you use 2DArt or Angle, your PICTUREBOOK uses a remote DELTAGEN to perform all
the rendering. Producing high quality renderings can be a very time consuming task and is
therefore performed asynchronously. The following settings configure how this asynchronous
rendering is performed.
“Thread Pool Size”: A thread pool is used to run render tasks in the background. This setting
defines the size of the thread pool. This should be higher than the maximum number of parallel
render tasks running in peak times.
Usually you shouldn’t change the above sleep time settings. However if you get a lot of errors
while rendering, where some shots are successful and others aren’t, you can try to increase
these values a little.
Note that only a hash of the
password will be stored.
The encrypted password in the
POWERHOUSE configuration
file is not the same encryption
mechanism as is used in the
PICTUREBOOK Admin. You
cannot copy the hashed
password from one
configuration file to the other.
Changing these settings does
not change the actual Tomcat
ports and vice versa – if
changing ports, you need to
change them in the Tomcat
settings and in the Powerhouse
settings.
3DEXCITE PICTUREBOOK Technical System Description 28
APPENDIX - MEETING SETTINGS
In order to use 3D models in your meetings, some configuration must be done.
When you add 3D models to a meeting, the server will load those models on a so called render
node. A render node is a server that runs DELTAGEN with the POWERHOUSE render backend
enabled. Note that the same render nodes are used for 3D meetings and for the Composer
feature of PICTUREBOOK. A render node is not multi-user-capable, that means it cannot be
used for multiple meetings or for a Composer session at the same time.
Render Node reservation Meetings can be scheduled for an arbitrary time in the future. To allow the server to check
whether or not enough render nodes for a meeting are available at the scheduled time, the
server needs to know how many render nodes are available and should be used for meetings.
The user who is scheduling a meeting shouldn’t have to know about render nodes. He wants
to display models in a meeting, and therefore he configures a number of models that should be
available for a meeting. The server will use the following two settings to determine how many
render nodes are required for the user’s number of models and whether that many render
nodes are available at the specified time:
Number of reservable render nodes: This setting specifies how many render nodes should be used
by the meeting server. If you set this to 0, no models can be added to any meeting. Make sure
that at least that many render nodes exist in your cluster at any time. They also need to be
available for the PICTUREBOOK server and should not be used by any other POWERHOUSE
component.
Model slots per render node: This number specifies how many models of one meeting may be
loaded on one render backend. In general it is safest, to set this to one. If you increase the
number, one meeting can use more models per render node, however this may have two side
effects:
• If a render node runs out of memory (RAM or graphic card), it crashes. That means if you
have models with high memory consumption, a number bigger than one might lead to
errors. All models on that render node will be temporarily unavailable, until the server
manages to reload them on a different render node (which in turn might crash again if the
memory is insufficient).
• If a render node performs a time consuming operation like e.g. loading a model or
surrounding, all other models of that node are unresponsive and cannot be used for that
time.
The maximum number of models that can be added to meetings is the product of those two
settings. If you have five render nodes with three slots per node, up to 15 models can be added
to meetings. As stated above, a render node can only be used for exactly one meeting. Thus
it is not possible to use some of the slots of one node for one meeting and some for another.
To reflect this, a user can increase or decrease the model slots only in steps that are equal to
the model slots per node.
One more thing should be considered with the number of reservable nodes: Meetings and the
Composer use the same render nodes. If a user starts a composer session, the server will use
any available render node for that. If a meeting requires a render node, the server will also
first try, to find an unused render node. If however no more render nodes are available, the
3DEXCITE PICTUREBOOK Technical System Description 29
render node of the composer user will be revoked from the user and used for the meeting.
If you want to guarantee some availability of render nodes for composer, you should not give
all render nodes to the meeting feature. If your cluster e.g. contains ten render nodes, you
could configure the number of reservable render nodes to e.g. seven. In this case three render
nodes will always be available for composer. The other seven can also be used for composer,
but might be revoked for a meeting.
Stream resolution for 3D meetings Here you can define the width and height of the streamed model data. This setting can only be
set for the whole server and is valid for all users.
Thus the chosen resolution must be displayable by all users that participate in a meeting. When
setting this value, consider possible clients with small screen resolutions, like e.g. Netbooks.
Also note that high resolutions dramatically increase network bandwidth and resource
consumption on the server. If you have either lots of concurrent meetings or meetings with
many participants, high resolutions might lead to problems. Please, contact our support if you
need advice for proper settings.
Timing Settings Preloading time for meetings: Loading a model on a render node might take quite some time.
For big models up to 15 minutes are common. To make sure that models are available for a
meeting once the meeting starts, the server will start preloading those models some time prior
to the meeting. This time (in minutes) can be configured with this setting. Depending on the
expected size of your models and the number of models per render node, a reasonable value
is probably between 15 and 30 minutes. Note that this setting influences the reservations for
render nodes; during the preloading time the render node cannot be used for another meeting
or for composer. If you e.g. schedule a meeting from 2pm until 3pm and have a preloading
time of 30 minutes, the server will implicitly reserve the render nodes from 1:30pm until 3pm.
End inactive meeting sessions after minutes: The server will automatically end running meetings
after a specified time of inactivity. Normally there should not be inactive meetings; this may
only happen if e.g. all participants get disconnected from a meeting due to network trouble or
something similar. Ending those meetings is important to free the meeting license which is
used by them.
Delete expired meetings after days: The server will not delete meetings, whose scheduled time is
over, immediately. If a user wants to reuse the configuration of an old meeting, he can do so
by rescheduling it to any time in the future. After some time however, the server will remove
those meetings to save resources.
Zabbix logging settings The messaging library, which is used within the PICTUREBOOK’s meeting module, supports to
log various statistics to a Zabbix monitoring system. These statistics include e.g. the throughput
of messages, the type of those messages and of course error counters for multiple scenarios. If
you don’t need this or don’t use Zabbix, this logging should be disabled. Set the property cola.
zabbix.logenabled to false to disable all Zabbix logging.
If you want to use this however, you first need to prepare your Zabbix to support the counters
which will be logged. At this appoint we assume that you know how to use and configure
Zabbix. Import the template “Collaboration_template.xml” into your Zabbix installation and
add your host to the group “Collaboration servers”.
Afterwards enable Zabbix logging and configure the hostname and port of your Zabbix
installation in the picturebookConfig.properties, something like this:
cola.zabbix.logenabled=true
cola.zabbix.server=someserver.somedomain.com
cola.zabbix.port=10051
The following property allows switching the actual logging on or off. If you want logging, set
it to true.
cola.zabbix.defaultlogenabled=true
The library which sends data to Zabbix can either fire and forget these data or check the
response of the Zabbix server to determine whether the server was able to process all sent
counters. Checking the response may be helpful if your Zabbix does not seem to receive any
data. In this case set this property to true and activate debug logging. Afterwards all replies
Note that enabling this logging
can have an impact on
performance and should
normally not be done.
3DEXCITE PICTUREBOOK Technical System Description 30
which indicate any errors will be logged. However since performance is increased heavily by
setting this value to false, you should disable this once you verified that everything is working.
cola.zabbix.checkresults=false
Further internal settings
The picturebookConfig.properties file contains some more meeting specific settings. These
settings already reflect that future versions of PICTUREBOOK might support multi-server-
scenarios, where users from different servers may participate in a meeting. Due to architectural
reasons, a single-server-scenario is handled pretty much the same as a future multi-server-
scenario, with the difference that there is only one participating server.
To allow future multi-server-scenarios we already use messaging mechanisms to communicate
with this local server. Therefore these settings are also required for the current single-server-
scenario. Please do not change any of the following values:
conferencingBroadcastInterval=15000
conferencingBroadcastTimeoutFactor=3
conferencingMeetingTimeoutOnSlave=61
conferencingKnownHosts=
dgConferencingPresenceTimeout=4000
dgConferencingPresenceCheckInterval=2000
There is one exception:
conferencingInvitablesFactor=40
In order to be able to invite users to a meeting, we need to know which users exist on each
server. In respect to the multi-server-architecture, each participating server periodically
publishes its invitable users to all other servers. In the current scenario, the one local server
periodically publishes its own users to itself. The setting above determines how often that
happens. Since sending these users is an expensive operation (users must be queried from the
database, converted, serialized, transferred and deserialized), this should not be done too often.
However this means that newly created users will not be available for meetings right away.
Only once the server updated its invitable users, the new ones can be invited.
In the current implementation of the multi-server-architecture, an inter server communication
happens every 15 seconds. However only after every x’th communication the users are sent.
The setting above defines x. The actual interval, in which updated user information is sent, is
the product of this setting with 15 seconds. A low value increases the costs of sending the
users. A high value increases the time it takes to be notified of user changes on a server. Since
users are usually not changed very often, we consider an interval of 10 minutes sufficient,
which can be achieved by the value of 40.
APPENDIX - PDM INTEGRATION SETTINGS
PICTUREBOOK supports the integration of PDM systems by loading PLMXML data into the
system.
PDM Connector Settings The connector implementation that comes with this release needs the change of some settings
to suit your needs. All connector settings are defined in the:
<installation_dir>\tomcat\webapps\picturebook\WEB-INF\classes\
PLMXML60Connector.properties
General Settings
pdmSystemId: This should be a unique id for all PDM connectors that are deployed on
PICTUREBOOK server to identify the right connector.
pdmName / pdmVersion: These two settings are shown on the frontend when selecting the PDM
connector. They indicate to which PDM system and version this connector can connect.
importFolderLocation: Setting which defines the location of models to import into the System.
defaultPartLibraryFolderPrefix: Setting which defines the prefix for the default PartLibrary folder
name.
plmxmlValidation: Setting which defines whether PLMXML source file validation against schema
definition shall be used or not.
3DEXCITE PICTUREBOOK Technical System Description 31
pdmImportThreadPoolSize: the number of threads used during PDM import is recommendet to be
set to the value 5.
APPENDIX - APPLICATION PLUG-INS
PICTUREBOOK supports the possibility to use application plug-ins to provide additional
functionality to clients like DELTAGEN. These plug-ins are provided directly by 3DEXCITE and
are defined in the applicationPlugins.xml in the WEB-INF/classes directory.
Plug-in description Within this xml file a plug-in is described as followed:
<applicationPlugin>
<id>001C11F9-EA0E-444C-828E-936BD9F64F54</id>
<name>DELTAGEN Integration for PICTUREBOOK Browser</name>
<description>DELTAGEN Integration for PICTUREBOOK Browser</description>
<version>2018.2018.001</version>
<author>3DEXCITE</author>
<dependencies>
<dependency>core</dependency>
</dependencies>
<applicationId>7F1AC85B-CDD7-491C-BC52-F751A34F9763</applicationId>
<applicationName>DELTAGEN</applicationName>
<applicationVersion>2018</applicationVersion>
<mainFile>../../../PictureBook.swf?integrationPluginsPath
=001C11F9-EA0E-444C-828E-936BD9F64F54/2018.2018.001</mainFile>
<files>
</files>
</applicationPlugin>
<file>
<name>../../../PictureBook.swf?integrationPluginsPath
=001C11F9-EA0E-444C-828E-936BD9F64F54/2018.2018.001</name>
</file>
The id is the id of this plug-in and will be used to identify it. This id will be always the same
for this plug-in. The name and the description are for the user to see what kind of plug-in it is.
The version of the plug-in is important. It is a combination of the PictureBook version (e.g. 65),
the DELTAGEN/DELTAVIEW version (e.g. 100) and the version of the plug-in itself (e.g. 001).
The dependency indicates on which module of PICTUREBOOK it has a dependency and uses
some functionality.
The applicationId indicates to which version of DELTAGEN/DELTAVIEW this plug-in is
compatible. The applicationName and applicationVersion are for the user to show which version
and which application is meant by this applicationId. The Client e.g. DELTAGEN will ask the
server for the list of plug-ins that are suitable for this DELTAGEN specified by his applicationId.
A newer version of DELTAGEN might have a different applicationId.
The mainFile property defines the main plug-in file that can be loaded from the server.
In addition there could be some additional files (e.g settings files ) that the plug-in uses.
Plug-in management To manage the application plug-ins in a comfortable way, you can use the PICTUREBOOK
Admin tool. In the “Application Plug-ins” section are listed all installed plug-ins for this
PICTUREBOOK installation.
1. select the plug-in
2. click on PlUg-in Details
All the information for this plug-in are read from the applicationPlugins.xml and shown in a
separate dialog.
3. click aDD new PlUg-in
4. select a new plug-in to add
This plug-in will be provided by us and comes as a zip file with all necessary files. Within this
zip file there is the plugin.xml which describes this plug-in and all the files structured in the
directory named like the plug-in id and within a folder named as the plug-in version.
There can be only one plug-in
with the same plug-in id and
applicationId in combination,
but there can be several Plug-ins
with the same Plug-in id but
different applicationId’s.
3DEXCITE PICTUREBOOK Technical System Description 32
For example:
plugin.zip
• plugin.xml
• 001C11F9-EA0E-444C-828E-936BD9F64A54
- 71.100.001
* PictureBook.swf
* sample.properties
The information out of the plugin.xml is added to the applicationPlugins.xml and all files are
extracted into the picturebook/plugins directory according their structure of the zip file.
If you want to add a new plug-in manually:
1. extract the file to the plugins directory
2. copy the content of the plugins.xml into the applicationplugins.xml in web-inf/classes
To update a plug-in:
1. select the plug-in you want to update
2. click UPDate PlUg-in
You are asked for the plug-in file.
The information about this plug-in will be read from the plugins.xml of the zip file and
overrides the settings for this plug-in in the applicationPlugins.xml according the pluginId and
the applicationId. All old files of this plug-in will be removed and the new plug-in files will be
extracted into the plugins directory.
To remove an old plug-in:
1. select the plug-in you want to delete
2. click reMove PlUg-in
The information about this plug-in will be removed from the applicationPlugins.xml and all files
of this plug-in will be removed from the picturebook/plugins directory.
The PICTUREBOOK Browser plug-in is the only plug-in that will be shipped with this release. It
provides browser functionalities for PICTUREBOOK inside DELTAGEN and DELTAVIEW.
IMPORTANT
If you add, remove or update any plug-in, you have to restart the server to apply changes.
APPENDIX - DATA MIGRATION
Database and filestore contents can be migrated from any PICTUREBOOK X-1.Y server to any
PICTUREBOOK X.Y server.
IMPORTANT
Migration works only from previous version to current version. Migration from an older version
to the current is not possible due to database changes.
1. backup your previous picturebook database / filestore
First backup your existing PICTUREBOOK database and the filestore. Therefore, stop the runing
PICTUREBOOK server and make a backup of the current filestore and create a dump of your
database. Additionally, backup your old installation to save your old settings.
In case you are using the bundled PostgreSQL database, you can use the following script to
create a backup of your database. Modify the script to use different database settings if needed.
<installation_dir>\scripts\backupDatabase_postgresql.cmd
2. install the new picturebook version (or the following maintanance release)
Install the new PICTUREBOOK release to a different location than where your current
PICTUREBOOK is installed.
3. install a valid license for the new picturebook
Please contact our Support, if you have not received a valid license yet.
4. in order to continue switch to PiCtUreBooK settings tab
A dialog will ask you if you want to use the migration wizard, guiding you through the
3DEXCITE PICTUREBOOK Technical System Description 33
migration steps. You also can skip the wizard and continue manual migration.
Using migration wizard
The wizard offers three migration steps.
The first helps you to migrate the settings of the previous installation towards the new one.
1. select the new installation and execute “migrate settings”
The second step assists you for migrating your database schema.
Depending on the first step, the database settings are taken.
2. execute the “migrate database”
The third step triggers the migration inside the database and the filestore.
3. click on Migrate PiCtUreBooK Data
Manual migration 1. configure picturebook using the picturebook admin tool
2. set the database and the main server settings as they were set up on picturebook in the prior
version
VERY IMPORTANT
3. set your server iD as it was in the prior version!
3DEXCITE PICTUREBOOK Technical System Description 34
Update Database Schema 4. run the suitable update sQl-script on the picturebook database
This can be found in <installation_dir>/scripts/schema.
Update SQL scripts are available for the following databases: PostgreSQL, Oracle and Microsoft
SQL Server.
You can use one of the appropriate update scripts in <installation_dir>/scripts/
5. therefore start:
updateDatabase_<databasename>.cmd / updateDatabase_<databasename>.sh
Linux: On Linux you need to modify the updateDatabase_postgresql.sh to set the database
credentials like database name etc.
IMPORTANT
6. check the log output for the database update if there are any sQl errors
If this happens don’t continue with migration. Check your database for the error and restore
your database dump before trying a second time.
Starting update procedure 7. start the database service if it does not run
8. create a new keystore for https if the key. use picturebook admin or run the script:
<installation_dir>\scripts\initKeystore.cmd Microsoft Windows
<installation_dir>/scripts/initKeystore.sh Linux
9. make sure all settings are set up correctly
10. start the picturebook server
<installation_dir>\startPictureBook.cmd Microsoft Windows
<installation_dir>/startPictureBook.sh Linux
11. clean your browser cache
12. reload the picturebook web site http://<server>:8080/picturebook
13. login as “superuser” with default password “superuser”
14. run the script
<installation_dir>\migrateData.cmd Microsoft Windows
<installation_dir>/migrateData.sh Linux
APPENDIX - BACKUP
The database and filestore data should be backed up regularly. We recommend creating a
database dump once per day. In case of emergency only a full restore is currently possible.
Example backup strategy (use with bundled database)
1. stop picturebook server
2. backup filestore / binary data
Make sure that your database is
UTF8 encoded.
Location Description
<set in properties file>\
picturebook_filestore
Models, etc IMPORTANT
<set in properties file>\
picturebook_temp
Temp store opt
<set in properties file>\
picturebook_cache
Preview cache recommended
3. backup bundled database (you can use the backup script of picturebook)
Location Description
<postgres_installation_dir>\
PostgreSQL\data
Database IMPORTANT
4. settings / licence / ssl keys / logs
3DEXCITE PICTUREBOOK Technical System Description 35
Location Description
<installation_dir>\tomcat\
logs
Log files opt
<installation_dir>\tomcat\
webapps\
picturebook\WEB-INF\
classes
Settings recommended
<installation_dir>\tomcat\
keystore
SSL Keys recommended
<installation_dir> Trustore file recommended
Live dump of running database (only for bundled PostgreSQL database): For backup see example script:
<installation_dir>\backupDatabase_postgresql.cmd
To restore database see example script:
<installation_dir>\restoreDatabase_postgresql.cmd
Backup settings: PICTUREBOOK Admin offers a function to store and restore your current configuration.
1. go to the main menu
2. choose under tools the option save CUrrent ConFigUration or restore ConFigUration FroM File
APPENDIX - CHANGE LOG-FILES LOCATION
Linux
edit log file configuration file by opening a text based editor and load the file
<installation_dir>/tomcat/webapps/picturebook/WEB-INF/classes/log4j.xml
<appender name=”file” class=”org.apache.log4j.DailyRollingFileAppender”>
<param name=”datePattern” value=”’.’yyyy-MM-dd” />
<param name=”file” value=tomcat/logs/picturebook.log” />
<layout class=”ag.rtt.picturebook.common.log4j.PBPatternLayout”>
<param name=”ConversionPattern” value=”%B %d{ISO8601} [%p] %c : %m%n “/>
</layout>
</appender>
Microsoft Windows®
change the log file location via the picturebook admin or manually edit the log file configuration
file by opening a text based editor and load the file
<installation_dir>\tomcat\webapps\picturebook\WEB-INF\classes\log4j.xml
<appender name=”file” class=”org.apache.log4j.DailyRollingFileAppender”>
<param name=”datePattern” value=”’.’yyyy-MM-dd” />
<param name=”file” value=”tomcat/logs/picturebook.log” />
<layout class=”ag.rtt.picturebook.common.log4j.PBPatternLayout”>
<param name=”ConversionPattern” value=”%B %d{ISO8601} [%p] %c : %m%n “/>
</layout>
</appender>
IMPORTANT
If you change the log file settings for PICTUREBOOK, you have to restart the server to apply
changes.
APPENDIX - CONFIGURATION OF PORTS FOR PICTUREBOOK
PICTUREBOOK uses Tomcat as a base. The default ports on installation (8080 for http and
8443 for https) on which PICTUREBOOK is listening can be changed if needed. You can replace
the port easily to the standard port 80 for http and 443 for https or you can add additional
settings for new ports.
To edit the port settins you can either use the Tomcat tab in the PICTUREBOOK settings area
Log files are not deleted
automatically. If you are running
out of disk, you can clean up old
log files.
3DEXCITE PICTUREBOOK Technical System Description 36
of your PICTUREBOOK Admin or edit the server.xml directly. You can find the server.xml in the
installation directory:
.../tomcat/conf/server.xml
modify the following settings and put ports you like to use:
<Connector port=”8080” protocol=”HTTP/1.1”
connectionTimeout=”20000”
compression=”on”
compressionMinSize=”2048”
noCompressionUserAgents=”gozilla, traviata”
compressableMimeType=”text/html,text/xml,text/plain,
text/css,text/javascript” />
<Connector port=”8443” protocol=”HTTP/1.1” SSLEnabled=”true”
maxThreads=”150” scheme=”https” secure=”true”
enableLookups=”false” disableUploadTimeout=”true”
clientAuth=”false” sslProtocol=”TLS” keystoreFile=”keystore”
compression=”on”
compressionMinSize=”2048”
noCompressionUserAgents=”gozilla, traviata”
compressableMimeType=”text/html,text/xml,text/plain,
text/css,text/javascript” />
APPENDIX - CONFIGURATION OF LISTEN ADDRESS FOR PICTUREBOOK PICTUREBOOK Tomcat can be configured that it is listening on a dedicated address instead on
all addresses. In order to do so, please adapt the server.xml of the Tomcat.
Official Tomcat documentation: http://tomcat.apache.org/tomcat-7.0-doc/config/http.html#Standard_Implementation
The parameter “address” needs to be set. For servers with more than one IP address, this
attribute specifies which address will be used for listening on the specified port. By default, this
port will be used on all IP addresses associated with the server.
APPENDIX - USING HTTPS AND HOW TO INSTALL CERTIFICATES
In order to use secure connection to PICTUREBOOK, you can use the https (SSL encrypted) URL
to the PICTUREBOOK server: https://<hostname>:8443/picturebook
This requires that a valid certificate was created on the server. See Chapter “Create your own
HTTPS Keystore” how to do that.
We recommend using a trusted certificate created by official companies like VeriSign.
This certificate needs to be installed on every client and for every browser that wants to access
the server via https.
IMPORTANT
The certificate should be installed with administrator rights.
Installing a certificate on Internet Explorer This example describes how to install the certificate using Internet Explorer.
If you connect the first time to a PICTUREBOOK server via https, you get a warning page of
Internet Explorer.
Use the hostname for the server
that the certificate was created
for. Do not use the IP of this
server. The certificate needs the
hostname in the URL.
3DEXCITE PICTUREBOOK Technical System Description 37
1. click on the ContinUe to this weBsite… link in order to continue
After that the address bar is marked red. Next to that you can see the warning for the error.
2. click in this certificate error field in order to install the certificate from the server
3. click on view CertiFiCates to continue
4. click on install CertiFiCate… to start the install wizard of internet explorer to install the certificate
5. follow the steps and click on next
6. click on Browse… to select the place for the certificate.
7. click on Finish
Set the place to store the
certificate to “Trusted Root
Certification Authorities”.
3DEXCITE PICTUREBOOK Technical System Description 38
A dialog appears to confirm the installation.
8. close the internet explorer
9. re-open it again.
Now, when connecting via https to the server you see the lock beside the address bar which
indicates that the certificate was installed successfully.
10. to verify, you can click on the lock to see that ie identifies this site as trusted.
If you have trouble installing this certificate, check the chapter “Troubleshooting”.
Installing a certificate on Firefox If you prefer Mozilla Firefox, this example will show you how to install the server certificate
for this browser. If you connect the first time to a PICTUREBOOK server via https, you get a
warning page of Firefox.
1. click on the i UnDerstanD the risKs link in order to continue
2. click on aDD exCePtion… to install the certificate from the server
3. click on get CertiFiCate
4. click on ConFirM seCUrity exCePtion to install the server certificate
After an automatic refresh of this page the lock icon in front of the address bar indicates that
the certificate was installed successfully.
5. click on this blue icon to see that firefox identifies this site as trusted
6. open your Control Panel
7. go to internet oPtions
8. open the CertiFiCate window under the tab Content where you can import the certificate
When using HTTPS for file
upload with Mozilla Firefox, the
certificate needs to be imported
to “Trusted Root Certification
Authorities” in your Internet
options.
3DEXCITE PICTUREBOOK Technical System Description 39
APPENDIX - SUGGESTED CONFIGURATION FOR A DMZ
Below is depicted the most generic configuration about a DMZ setup. We can see the two
network levels; the first level is related to the connection to the external firewall the second level
is related to the Render Backend.
The above configuration is the suggested configuration in order to overcome the most common
security problem and to avoid trouble related to the PICTUREBOOK Flash frontend Sandboxing.
The solution to the above described problem is to install and configure an Apache HTTPD web
server as frontend for PICTUREBOOK Server.
Apache HTTPS frontend You can setup the Apache Fronted for standard HTTPS. HTTP is strongly discouraged in the
open internet environment due to the plain text communication for password and login.
Therefore we will explain how to install the Apache server and configure it for the HTTPS.
Adding an Apache HTTPD server as frontend will also increase the HTTPS performances.
Apache and SSL Configuration In order to setup the described environment, you have to follow these steps and use this
Software:
• Install Apache server
• Install Openssl package
• Install mod_jk.so
1. install the apache web server on the picturebook server
2. install the vc+ redistributable
3. install with the openssl package (not delivered with picturebook installation)
The openssl package is used only to generate the certificate; no other particular integration with
Apache is needed because Apache already has the ssl module included into the distribution.
4. generate the certificate.
In a windows environment you have to enter these commands:
cd C:\OpenSSL-Win32\bin
openssl genrsa 1024 > server.key
openssl req -new -x509 -nodes -sha1 -days 365 -key server.key > server.crt
openssl x509 -noout -fingerprint -text < server.crt > server.info
type server.crt server.key > server.pem
The certificate is being generated.
5. copy the following files into the apache configuration directory
Files to be copied:
server.crt
server.key
Use as CN the PICTUREBOOK
server machine name; otherwise
the certificate will not be
correctly installed on the
browser side.
3DEXCITE PICTUREBOOK Technical System Description 40
server.pem
Apache configuration directory:
C:\Program Files (x86)\Apache Software Foundation\Apache2.2\conf
6. copy mod_jk.so into the apache2.2/modules directory
It is provided with the installation and can be found in the “inst” folder.
7. modify the apache configuration file
Here we will include the proxy directives and the httpd-ssl configuration file. The Apache config
file is httpd.conf located into
C:\Program Files (x86)\Apache Software Foundation\Apache2.2\conf
8. to skip chunk encoding to be sent to tomcat, add the following
LoadModule headers_module modules/mod_headers.so
<Location /picturebook/servlets/getFile>
<IfModule headers_module>
RequestHeader unset Transfer-Encoding
</IfModule>
</Location>
To proxy the ajp requests we use the mod_jk module:
LoadModule jk_module modules/mod_jk.so
JkWorkersFile conf/worker.properties
JkLogLevel error
JkMountCopy On
JkMount /picturebook* worker1
9. add the following file in the apache2.2/conf for the workers:
# Define 1 real worker using ajp13
worker.list=worker1
# Set properties for worker1 (ajp13)
worker.worker1.type=ajp13
worker.worker1.host=localhost
worker.worker1.port=8009
10. comment out the following entry
# Secure (SSL/TLS) connections
Include conf/extra/httpd-ssl.conf
11. load the ssl_module commenting out the following entry in the configuration file:
LoadModule ssl_module modules/mod_ssl.so
12. identify the inter-process section and change accordingly with your apache directory link.
# Inter-Process Session Cache:
# Configure the SSL Session Cache: First the mechanism
# to use and second the expiring timeout (in seconds).
SSLSessionCache “dbm:C:/Apache2.2/logs/ssl_scache”
SSLSessionCache “shmcb:C:/Apache2.2/logs/ssl_scache(512000)”
SSLSessionCacheTimeout 300
13. change the virtual host section in httpd-ssl.conf
14. add the jkmountcopy on
…
JkMountCopy On
…
When Apache is to be installed
onto a 64bit machine the
software will be located into
“Program Files (x86)“ directory,
the Apache does not correctly
understand the path, so the user
has to create a link in the root
“c:\Apache2.2“ and modify
accordingly the configuration
files.
You have to modify the http
configuration file in order to
match the Apache2.2 path.
3DEXCITE PICTUREBOOK Technical System Description 41
APPENDIX - ADDITIONAL PICTUREBOOK ADMIN FEATURES
PICTUREBOOK Admin provides some additional tools that can be found in the menu beneath
the “Tools” entry.
These tools are:
File editor: A built in editor to change files directly within the admin tool.
Environment Info: This will give you some information about your network interfaces, system
variables and more.
Analyse filestore: This tool will check your database for missing files and checks your filestore for
orphaned files that are not longer referenced in the database. The result will be logged into the
analyseFilestore.log file.
Remove unreferenced files: Those files that were detected as orphaned in the filestore meaning no
longer referenced will be deleted.
Generate PICTUREBOOK WAR archive: This option will trigger the script to generate a *.war archive
from the current PICTUREBOOK with all its settings. This war file can be used to deploy
PICTUREBOOK on IBM WebSphere. To be able to generate this archive, make sure you have a
JDK installed on your machine.
Backup filestore: This small tool can help you to copy your filestore to another location. It can be
used as well to copy anything else.
Save current configuration: Option to create a backup of current configuration files.
Restore configuration from file: Option to restore the backed up settings from a different
PICTUREBOOK installation.
Note that you can restore only settings from the same PICTUREBOOK version.
PICTUREBOOK Migration Wizard: Small tool that helps migrating settings files from a former
PICTUREBOOK version to the current. Note, this is not the data migration that you have to do
for the database and the filestore.
The menu option “Logs” provides you the possibility to open some log files directly with the
built in file editor.
APPENDIX - ABOUT PICTUREBOOK
add some support contact information
For example you might add the Support e-mail: [email protected].
This information is shown on the frontend and could be replaced by contact information of
your company. The application label is also shown in the header bar of the main frontend
beside the application logo icon.
You can get some information about PICTUREBOOK using
http://localhost:8080/picturebook/about.do.
It shows the version and the BuildID of the Server as well as the installed modules.
Additionally to this about page you have the possibility to click on the PICTUREBOOK logo on
the frontend after login which gives you beside the server information the GUI information.
3DEXCITE PICTUREBOOK Technical System Description 42
APPENDIX - USAGE STATISTICS
PICTUREBOOK is providing a statistic document showing the current usage of content and
filestore.
click the “show statistics” button inside the managementconsole
Additionally, you can access it directly via http://localhost:8080/servlets/getUsageStatistics
The result will be an Excel file looking like this:
APPENDIX - PICTUREBOOK SERVER PAGES
Active Sessions PICTUREBOOK is providing a page that lists all active sessions on the server. Within that list,
user information, browser agent and machine information like IP address are shown.
1. click the “show active sessions” button inside the managementconsole. or directly via http://
localhost:8080/picturebook/session.do.
Job Monitor
On that page all backend long-term jobs like notification and short-term jobs like image
conversion and preview generation are listed. It provides detailed information to each job
including trigger time and job specific data and settings.
Memory usage This page shows the current Java memory usage of the server.
Assignment conditions For details, please chapter “Appendix – Misc. Settings - Signup”
About For details, please chapter “Appendix - About PICTUREBOOK ”
You need to have a valid session
and be logged in with
administrator rights.
3DEXCITE PICTUREBOOK Technical System Description 43
APPENDIX - LARGE FILE UPLOAD
PICTUREBOOK allows uploading files larger than 2 GB. Therefore it uses Java technology to
upload the file via a Java Applet.
Every client who wants to use this functionality needs to have a Java Runtime installed.
PICTUREBOOK supports JRE 1.7 and higher.
Additionally, you have to enable the upload of large files in the frontend under the settings
section.
1. inside the general page select the large File UPloaD check mark
In some cases, the browser blocks the Java plugin by default
2. enable the java plugin.
Once the Java plugin is enabled, the browser prompts you tp accept the Certificate of the Java
applet. This Java Applet is signed with a certificate created by our company. This certificate
needs to be accepted otherwise the Java applet will not work and the user cannot upload files
bigger than 2GB.
APPENDIX - ADAPTING FRONTEND OPTIONS
PICTUREBOOK allows configuring frontend user options. With this functionality you can
control which features and options are available on frontend side for a certain permission level.
The available options and default assignments are defined in
<installation_dir>\tomcat\webapps\picturebook\WEB-INF\classes\
optionAssignments.properties
1. open the file in an editor tool
2. remove the options from the permission level you want to adapt.
The option assignments are based on the permission level from 0 to 5, meaning from “Read”
right to “Grant” right.
Taking any option from a higher permission level to a lower level will not work since the server
is checking the permission level, not the options for the frontend. So you can modify only the
options that are already predefined for the permission level.
For questions and more details, please contact our Support.
Sample of option assignments for content type “FILE” for all permission levels:
FILE 0=
FILE 1=DOWNLOAD_ASSET
FILE__2=CREATE_ANNOTATION,CREATE_PREVIEW,CREATE_FILEREFERENCE,COPY_
ASSET_TO_FOLDER,DOWNLOAD_ASSET
FILE 3=CREATE_ANNOTATION,CREATE_PREVIEW,CREATE_FILEREFERENCE,COPY_
ASSET_TO_FOLDER,EDIT_ASSET,RENAME_ASSET,EDIT_METADATA,DOWNLOAD_ASSET
FILE 4=CREATE_ANNOTATION,CREATE_PREVIEW,CREATE_FILEREFERENCE,COPY_
ASSET_TO_FOLDER,EDIT_ASSET,RENAME_ASSET,EDIT_METADATA,MOVE_ASSET_
TO_FOLDER,DELETE_ASSET,DELETE_ANNOTATION,DELETE_PREVIEW,DELETE_
FILEREFERENCE,DOWNLOAD_ASSET
FILE 5=CREATE_ANNOTATION,CREATE_PREVIEW,CREATE_FILEREFERENCE,COPY_
ASSET_TO_FOLDER,EDIT_ASSET,RENAME_ASSET,EDIT_METADATA,MOVE_ASSET_
TO_FOLDER,DELETE_ASSET,DELETE_ANNOTATION,DELETE_PREVIEW,DELETE_
FILEREFERENCE,DOWNLOAD_ASSET
All options can be defined independently of their content type, for instance you can have
If you want to enable Sketching
and Annotations, you have to
enable also option to edit an
asset since these are part of an
asset.
3DEXCITE PICTUREBOOK Technical System Description 44
different options defined for content type “FILE” and “FILESET” even though they can be
together in one folder.
All options are defined for the whole frontend and are not user specific. These option
assignments apply to all users and types of content.
3. check the following file if a certain content type is defined as an item of another content type
<installation_dir>\tomcat\webapps\picturebook\WEB-INF\classes\allowedItems.properties
If this is the case, then you must do the following:
4. change the option assignment for this content type respectively.
APPENDIX – ENABLE MICROSOFT OFFICE PREVIEW GENERATION
PICTUREBOOK allows generating preview images out of Office documents. Therefore, the
application is shipped with the free OpenOffice in order to ensure conversion functionality.
Although it works for most of the cases, there are Office documents that may not be exactly
converted due to compatibility issues of OpenOffice to Microsoft Office. In order to overcome
these issues, PICTUREBOOK comes with conversion scripts to utilize Microsoft Office in order
to penetrate exact preview images.
Setup on Windows 1. copy the three files fROm fOldER InsT Of yOUR PICTUREBOOK InsTallaTIOn InTO ThE WIndOWs fOldER
C:\WIndOWs\sysWOW64\:
pythoncom26.dll
pythoncomloader26.dll
pywintypes26.dll
2. create a folder called “desktop” in both windows folders:
C:\Windows\SysWOW64\config\systemprofile and
C:\Windows\System32\config\systemprofile
Configuration 1. stop picturebook service
2. open the file: convertermapping.properties
It is in tomcat\webapps\picturebook\WEB-INF\classes\ path.
3. comment out the default setting of officedocumentconversion
4. uncomment the other officedocumentconversion setting and the dedicated conversion setting with
the name of the msofficedocumentconverter script:
5. save the settings file and restart picturebook service
In case you want to use
Microsoft Office preview
generation, please make sure
you have MS Office installed on
the server machines and is
properly licensed. We do not
provide any Microsoft license.
This need to be handled on
customer side.
3DEXCITE PICTUREBOOK Technical System Description 45
TROUBLESHOOTING
PostgreSQL installation on Windows
If you want to install the bundled PostgreSQL database which comes with the installer for
PICTUREBOOK, use a password for this postgres windows account that fulfil the requirements
of your domain restrictions. If the password is too weak the installation of this database will
fail and rolled back.
If you tried to install the PostgreSQL database and it failed for any reason, it could happen
that the windows account for postgres was already created but could not be removed by the
rollback of the installer.
1. remove the “postgres” user account manually
2. delete the user data directory from “c:\documents and settings\”.
If you do not remove this data, every attempt to install PostgreSQL will fail again.
Changing maximum connections on PostgreSQL If you encounter exception due to limited amount of database connections, you can define the
max connection for your PostgreSQL installation.
1. edit the postgresQl.conf file
It can be found in the data directory of your PostgreSQL installation.
2. check for “max_connections” and increase the number to your needs.
Default setting is 100.
Using PostgreSQL 9.0 Using the new PostgreSQL version 9.0 you have to change the default binary settings to the
old default value of 8.x.
1. edit the postgresQl.conf file
It can be found in the data directory of your PostgreSQL installation.
2. check for “bytea_output”
3. set to ‘escape’.
For more information check out:
http://developer.postgresql.org/pgdocs/postgres/datatype-binary.html
Running out of disk space
If you have not much space on your hard drive where your filestore is located do the following:
1. delete all the files from the picturebook_temp directory.
This folder is used when uploading files into PICTUREBOOK but in some cases the files could
not be cleaned up because a process has still access to it.
2. additionally you can delete old log files from the tomcat/logs directory.
If the disk is full, PICTUREBOOK will sooner or later stop working cause for every action there
are some log entries written to the database and to the log file. If you free up some space, at
least you can login again and are able to delete some assets.
MSSQL connection issues on Windows If you have a Microsoft SQL Server 2005 installation and you cannot connect to the database,
it could be related to the port where the database is listening on.
By default this port should be 1433 but in some MSSQL installation it is set to a different port.
In order to change the listening port go to your “SQL Server Configuration Manager” and
browse to the “SQL Server 2005 Network Configuration” do the following:
1. select the “protocols for “sQlexpress”
2. open via context menu the properties of the “tcp/ip” setting.
3. make sure it is enabled.
4. in the settings dialog change the port to the default value 1433 for all ip connections.
If you uninstall PICTUREBOOK
and the bundled PostgreSQL
database the “data” directory of
PostgreSQL will not be deleted
for security reasons. For another
successful install you must
delete this directory manually.
3DEXCITE PICTUREBOOK Technical System Description 46
1. select the connection and open the server properties.
“Login failed for user ‘username’. The user is not associated with a trusted SQL Server connection.”
If you get such an error message check the authentication mode of your database setup. You
can check this setting within the “Microsoft SQL Server Management Studio Express”.
2. change the server authentication to mixed mode “sQl server and windows authentication mode”.
Cannot connect to PICTUREBOOK from DELTAGEN via HTTPS
If you try to connect to a PICTUREBOOK server via https using DELTAGEN or DELTAVIEW, make
sure you have installed a proper certificate on your machine. DELTAGEN is using the Microsoft
Internet Explorer engine to show the PICTUREBOOK interface inside DELTAGEN. That’s why
the certificate needs to be installed in Internet Explorer.
Check chapter “Appendix using HTTS and how to install certificates” for more details.
Make sure you are using in the URL the hostname of the server for those the certificate was
generated for. Additionally, check if you are using the hostname of the PICTUREBOOK server in
the connection credentials. The certificate is generated for the hostname that’s why the usage
of the IP does not work for HTPS.
“File not found” Icon is shown instead of the preview image In PICTUREBOOK there is a “File not found” icon shown as a preview thumbnail if the file of
this asset could not be found physically in the filestore.
In PICTUREBOOK you can identify those assets and repair them by uploading the files again or
simply remove the assets.
3DEXCITE PICTUREBOOK Technical System Description 47
HTTPS and Mozilla Firefox
Due to the fact that Mozilla Firefox is creating another thread for uploading files, this thread
needs also a confirmation for using a self-signed certificate.
In order to enable HTTPS file upload with Firefox, the certificate needs to be imported as
“Trusted Root Certificate”.
Please see chapter Appendix - Using HTTPS and how to install certificates.
Empty Message box when installing certificate in Internet Explorer
If a normal user without admin right try to install a certificate gets an error due to a bug in
Internet Explorer and Windows XP. Apple Safari for Windows uses the same technology of IE
when installing the certificate, that’s why this happens here as well.
you can solve this by installing the certificate with admin rights on the client machine.
“Unknown Server Error” message before login screen If there is a popup message with an unknown server error that occurs right after the pre-
loader is finished, then this could be related to the shared objects of Adobe Flash. Within
this shared objects the UI state is saved and additionally the flag for automatic login.
To get rid of the message and to be able to login again, delete the shared object from the Flash
shared objects directory.
• In Windows you can find it in “%APPDATA%\Macromedia\Flash
Player\#SharedObjects”.
• For Apple MAC you will find it in “~/Library/Preferences/Macromedia/Flash
Player/#SharedObjects”.
• Under Linux check “~/.macromedia/Flash_Player/#SharedObjects”.
1. removing the appropriate folder or files
2. try to login again to picturebook.
Session expired after login
If you encounter the “session expired” message right after login into PICTUREBOOK, it could be
related to the use of underscores within the hostname.
http://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_host_names
Using underscores in hostname will cause a session lost on Internet Explorer. Mozilla Firefox
can handle this underscores and will work in such a case.
OutOfMemory Error In case the application does not react anymore and seems to be frozen also for other clients.
1. check the picturebook logs for: java.lang.outofmemoryerror: java heap space
This could occur if the Server has to handle huge amount of Data at once which requires
allocating a lot of memory. If you encounter this Issue, you can fix it by increasing the Java
memory.
2. set the catalina_opts increase the values for -xms512m -xmx1024m within the
startpicturebook.cmd /.sh script.
In case you have PICTUREBOOK running as a Windows Service, you can change the settings
inside the tomcat6w.exe application that the service is pointing to.
1. open this tool and switch to the java tab.
2. you can modify the memory pool settings and increase the value according to your physical available
ram.
3DEXCITE PICTUREBOOK Technical System Description 48
In case you have a java.lang.OutOfMemoryError: PermGen space Error in you picturebook.log:
1. increase the maxpermsize value of the catalina_opts or inside the tomcat6w.exe
2. restart the server applictaion.
3. check out the http://localhost:8080/picturebook/memoryjvm.do to get an overview about the
memory usage of your picturebook installation.
Oracle 10g XE issues
If you use Oracle XE it uses the port 8080 by default for the Oracle Homepage (APEX):
http://127.0.0.1:8080/apex which will collide with PICTUREBOOK running on the same ports
with default installation settings. Additionally, the PICTUREBOOK Admin shows a wrong server
status (server is not running).
Configure either the default ports of PICTUREBOOK server or the port of Oracle. We recommend changing the ports for the Oracle XE.
In order to change the Oracle HTTP port:
1. login into the database as system
2. use the following procedure to change the port:
SQL> -- get current status
SQL> select dbms_xdb.gethttpport as “HTTP-Port” from dual;
HTTP-Port
---------
8080
SQL> -- set http port and ftp port
SQL> begin
dbms_xdb.sethttpport(‘80’);
end;
/
PL/SQL procedure successfully completed.
Oracle Open Connections It could happen that the maximum open connections to Oracle are exceeded when having
heavy load on the server.
change the maximum open connection settings by using the following sQl statements with 500 as
recommended processes and sessions:
SQL> alter system set processes=500 scope=spfile;
SQL> alter system set sessions=500 scope=spfile;
Asian Character support in PDF
The creation of PDF documents (like Asset Report) with Chinese, Korean, Japanese, Hindi, and
Malayalam etc. characters will work only if the machine where PICTUREBOOK server is running
has installed a font that supports such characters.
Currently, the font used, which supports such characters is “Arial Unicode MS” (Microsoft font).
This font is licensed and therefore cannot be redistributed.
In case the server does not have it, you can either install the required font or use another one
that supports such characters and is installed.
If you want to use another font, you can modify the template files (*.xsl) or the fop.xml file
which defines the default font. These files can be found in tomcat/webapps/picturebook/
WEB-INF/classes of your PictureBook installation. In case the font is not found, a log message
appears.
Reading PDF without embedded fonts While it is recommended to embed all fonts for greatest portability not all PDF producer
applications will do this. When displaying a PDF it is necessary to find an external font to use.
PICTUREBOOK is using a PDF library which uses default fonts like Arial when substituting
fonts. If a font could not be substituted, the text in the rendered PDF image is not shown at all.
Large file upload with Java fails with DFS (Distributed File System)
Using the Java file upload (“large file upload”) together with a virtual file structure does not work
under Windows 7 and Windows Server 2008.
The Java file chooser dialog cannot open the distributed folder.
Please see Oracle’s Bug description:
http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=7030987
update the jre to the latest version but minimum 1.7
Cannot Install another PICTUREBOOK version aside If you want to install another PICTUREBOOK with the main version you will run into the issue
where the installer tells you that you cannot install the new version since there is already one
PICTUREBOOK with this version installed.
This issue is related to a bug in the installer application itself and occurs if you have installed
PICTUREBOOK under the default location proposed by the installer. This applies to both Linux
and Windows installations.
rename the previous installation so the default installation path is not used by the previous installation
Our 3DEXPERIENCE® platform powers our brand applications, serving 12 industries, and provides a rich portfolio of industry solution experiences. Dassault Systèmes, the 3DEXPERIENCE® Company, provides business and people with virtual universes to imagine sustainable innovations. Its world-
leading solutions transform the way products are designed, produced, and supported. Dassault Systèmes’ collaborative solutions foster social innovation, expanding possibilities for the virtual world to improve the real world. The group brings value to over 170,000 customers of all sizes in all industries in more than 140 countries. For more information, visit www.3ds.com.
Americas
Dassault Systèmes 175 Wyman Street Waltham, Massachusetts 02451-1223 USA
Europe/Middle East/Africa Dassault Systèmes
10, rue Marcel Dassault CS 40501 78946 Vélizy-Villacoublay Cedex France
Asia-Pacific
Dassault Systèmes K.K. ThinkPark Tower 2-1-1 Osaki, Shinagawa-ku, Tokyo 141-6020 Japan
©2
01
4 D
ass
au
lt S
yst
èm
es.
All
rig
hts
re
serv
ed
. 3
DE
XP
ER
IEN
CE
®,
the
Co
mp
ass
ico
n a
nd
th
e 3
DS
lo
go
, C
AT
IA,
SO
LID
WO
RK
S,
EN
OV
IA,
DE
LM
IA,
SIM
UL
IA,
GE
OV
IA,
EX
AL
EA
D,
3D
VIA
, B
IOV
IA,
NE
TV
IBE
S,
an
d 3
DE
XC
ITE
are
co
mm
erc
ial
tra
de
ma
rks
or
reg
iste
red
tra
de
ma
rks
of
Da
ssa
ult
Sy
stè
me
s o
r it
s su
bsi
dia
rie
s in
th
e U
.S.
an
d/o
r o
the
r co
un
trie
s. A
ll o
the
r tr
ad
em
ark
s a
re o
wn
ed
by
th
eir
re
spe
ctiv
e o
wn
ers
. U
se o
f a
ny
Da
ssa
ult
Sy
stè
me
s o
r it
s su
bsi
dia
rie
s tr
ad
em
ark
s is
su
bje
ct t
o t
he
ir e
xpre
ss w
ritt
en
ap
pro
val.