Table of Contents

Table of Contents
Yellowfin ®
Release 5.1
Installation Guide
Under international copyright laws, neither the documentation nor the software may be copied, photocopied,
reproduced, translated or reduced to any electronic medium or machine-readable form, in whole or in part, without
the prior written permission of Yellowfin International Pty Ltd, except in the manner described in the software
agreement.
The information in this document is subject to change without notice. If you find any problems with this
documentation, please report them to Yellowfin in writing at [email protected] Yellowfin does not warrant
that this document is error free.
Copyright © Yellowfin International 2011. All rights reserved.
Portions © Copyright Microsoft Corporation. All rights reserved.
Trademarks:
Yellowfin and the Yellowfin Logo are registered trademarks of Yellowfin International.
All other product and company names mentioned herein are the trademarks of their respective owners.
Version: 1
Published: June 2011
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Yellowfin is an easy-to-use, self-service environment for non-technical users,
delivering drag-and-drop simplicity for formatting and data selection. It also provides
advanced features for power-users.
Yellowfin provides a Web delivered user interface into a JAVA based technical
architecture and employs vendor neutral implementations for data sourcing and
application server functionality such as web server and web container services.
This guide is intended for technical staff who implement and support the application.
Such staff should have a good knowledge of: java, basic J2EE architecture, SQL-92
and of the SQL dialect that the implemented database supports (if any SQL queries
have been hand coded and use vendor specific features).
Do you have a suggestion on how we can improve our documentation? Is there
something you particularly like or have found useful? Drop us a line, and we will do
our best to ensure that your suggestion is included in the next release of our
documentation: [email protected]
Note: If your issue concerns the Yellowfin product and not the documentation, please
contact our Customer Support experts. For information visit: www.yellowfin.com.au
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Yellowfin stores the all application configuration data such as authorisation and
authentication permissions, logical views of the data, report definitions, field
definitions, execution statistics and information about this data (metadata) in the
Yellowfin database.
Users and administrators define these data items via a Browser Interface. Yellowfin
then converts these various data components into an SQL query at runtime and
generates the required report and delivers it to the user interface. From there users
can choose the format in which is stored eg. Spreadsheet, PDF, html report etc.
Yellowfin follows the Java platform standard for delineating component functions and
responsibilities. The technical components comprising Yellowfin are:
Figure 1 Yellowfin Technical Architecture
This provides the User Interface via Web Browser. Yellowfin is designed to run under
®
Microsoft Internet Explorer Version 5 and upwards, Firefox and Opera.
This provides workflow and business logic.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Web Server - This component processes and sends HTML pages across the WWW.
Yellowfin uses Apache Tomcat.
Web Container - This component interprets the HTML requests, performs the
required business logic, writes persistent data to the database and dynamically
generates the required web pages. Yellowfin uses Apache Tomcat.
This stores the data required by the application on a persistent basis.
Database - Yellowfin can be configured to support any JDBC 2.0 compliant database
®
e.g. Microsoft SQL Server, Oracle, IBM UDB, MySQL and Progress
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Yellowfin requires that the customer has installed the following products prior to
installing the Yellowfin product:
The server hosting the Yellowfin application MUST have Java 1.5 or higher installed
on it. The Java JRE is sufficient for this purpose. Refer to the Sun web site for
download and installation instructions (www.java.sun.com)
The database software which will contain the Yellowfin database should already be
installed. Suitable jdbc drivers to enable the database to communicate with the
Yellowfin application should also be installed. It is not necessary for the database
server to reside on the same machine as the Yellowfin application.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Yellowfin is provided as a java archive file called Installer.jar. Copy the file to a
temporary directory on the server onto which the application is to reside.
Step
Page Display
Step 1. Language Selection
Before you can begin you will be asked to
select a language for the installation
process.
Step 2. Welcome Screen
The welcome screen is the first screen in
the installation process. It mentions
installation pre-requisites and other
information. Click the Next button to
continue, or click the Quit button at any time
to exit the installation process.
Step 3. Terms and Conditions.
The terms and conditions page lists the
Yellowfin Software License agreement.
When you have read the license agreement
check the “I accept the terms of this license
agreement” radio button to agree and click
the next button to continue.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Step 4. Required Components
You will have to install the core software for
Yellowfin but you do have the option of
installing the tutorial database, sample
usage reports, and Language translation
files.
Click the next button to continue.
Step 5. License File
The Yellowfin Installer will ask for a licence
file. You will have received a licence file that
uses computers host name. This will be
delivered to you as a .LIC file.
Select the licence file from your file system
using the browse button. Once selected
click the next button to continue.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Step 6. Select General Options
This screen enables you to select the
application server port that Yellowfin will
listen to for HTTP requests. As per standard
internet conventions it will default to port 80.
If there are already web servers installed on
the machine that Yellowfin is being installed
on then there may be port clashes and
Yellowfin will fail to function correctly.
Select a port number which is not in current
use by a Web Server on the machine. Port
numbers like 8080, 8081 and so on are
good candidate port numbers. If there are
no other web servers on the machine that
Yellowfin is being installed on, accept the
default port number of 80.
This screen will also enable you to install
Yellowfin as a Windows Service on the
server. This will mean that it will
automatically start up whenever the
Windows Server is booted and save having
to be manually started.
Once you have selected you port, click the
next button to continue.
Step 7. Database Selection
Choose the database that you wish to install
the Yellowfin Repository database into.
You will be able to select from: DB2, Oracle,
PostgreSQL, Progress, SQLServer / MSDE
Based on your selection the next few steps
will vary. Click the next button to continue.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Step 8. Installation Path
You will have to define the installation
directory for Yellowfin. This will default to
different directories based on the operating
system you are installing to.
You can change the default installation
directory by directly typing in a new path, or
using the browse button to navigate the file
system.
When you have chosen your installation
destination click the next button to continue.
Note: Windows users installing into a 64bit
version will need to ensure they choose a
path outside of the Program Files directory.
Step 9. Check the Installation progress
This screen will enable you to observe the
progress of the software installation.
Depending on the server hardware and
software capacity this could take a few
minutes.
You will be able to click next to move to the
next window once the installation is
complete.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Step 10. Short Cuts
This screen enables you to select the
Windows Program Group that Yellowfin
„shortcuts‟ will be installed into.
Select the Program Group for the shortcuts
by selecting the options from the List Box.
You can override the name for the Program
Group by entering a name in the text box at
the bottom of the Window.
Select whether you wish the shortcuts to be
provided to only the current user or all users
by selecting either the „current user’ radio
button or „all users’ radio button
respectively.
Click the next button to continue.
Step 11. Installation Completion
This screen will be displayed at the end of a
successful installation of the Yellowfin
Application Server.
Note: an uninstall function has been created
for you under the directory nominated in
Step 7. Select the Installation Path.
If you do not see this Window, contact your
Yellowfin representative or contact Yellowfin
Support.
Click the Done button to complete the
installation procedure.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Most problems related to the Yellowfin application server installation relate to
database connectivity and administration issues.
As mentioned previously, a log is kept of the database installation and can be found
in $INSTALL_DIRECTORY\uninstall directory.
The most likely problem will be the incorrect setting or misspelling of the parameters
entered in Step 6 Configure the Database Connection and User parameters eg.
database name, port, IP address etc.
Customers using Microsoft SQLServer or Microsoft MSDE should ensure that the IP
addresses and configuration are consistent with the parameter values entered. The
Microsoft program svrnetcn.exe (SQLServer Network Utility) can be used to check
that the SQLServer IP stack (including the JDBC port number) has been configured
correctly. It can be used for both SQLServer and MSDE.
Network error IOException: Connection refused: connect()
This error means that the installer cannot connect to your MS SQL server instance.
This error occurs before authentication takes place. This means that either:
1. SQL Server is stopped on the server you are trying to connect to.
2. The connection details you entered were incorrect.
3. You have a network problem that stops the computer you're running the installer
on connecting to the SQL server host (Unlikely if you are connecting to your
localhost).
Verify these settings on the Configuration DB Parameters screen on the installer.
1. Database Server Name - This will probably be the "localhost".
2. Database Server Port - This should be 1433
3. Database Name - This is the name of the database you want Yellowfin to install to.
This should be "yellowfin". This is used for Yellowfin configuration and operational
data. It is not the database you wish to report off.
4. Create Database - Click this to create the new Yellowfin database. We suggest
removing the Yellowfin database if your installation failed previously.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
5. DBA User: This could be "sa"
6. DBA Password: This could be "sa"
7. Reports UserId:Set this to "yellowfin_user"
8. Reports UserId password: Set this to "yellowfin_user" or whatever you prefer.
9. Create user id - Check this checkbox.
If you are experiencing other installation issues the Yellowfin forum is a good place to
look for answers. Go to http://www.yellowfinbi.com/YFForum.i4 to explore previous
posts or seek help from other users and Support Members. Some useful
troubleshooting posts include:
1. http://www.yellowfinbi.com/YFForum-ERROR-Yellowfin-Installation-on-MSServer-08-?thread=103838
2. http://www.yellowfinbi.com/YFForum-install-Yelliowfin-on-SQL-Server-2005?thread=89809
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Yellowfin has two main functional components involved in the startup and shutdown
procedures:
1. Database
2. Application Server
The sequence for startup is to startup the database and then startup the application
server. The sequence for shutdown is to shutdown the application server and then
shutdown the database.
The Database must be started up and brought up successfully before the
Application Server is started. If the database is not ready to accept database
connections and calls before the application server is started, the Yellowfin
Application server will fail to start up.
In the case of an unsuccessful start up of the database DO NOT attempt to start up
the application server. Instead, determine the cause of the database start up failure
and resolve the problem before attempting to start up the application server.
If the application server starts up and fails as the result of an unsuccessful database
start up, wait until the startup sequence completes. Once it has completed, shutdown
the application server.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
After the database has been successfully started up, startup the application server.
If Yellowfin has been installed as a service:
The Yellowfin application server will be controlled by the Service Manager (ie. Start 
Programs  Administrative Tools  Services under Windows 2000).
If Yellowfin has NOT been installed as a service:
The Yellowfin application server can be started and stopped by selecting the the Start
Yellowfin Server and Stop Yellowfin Server icons respectively in the Yellowfin
Program Group.
Yellowfin can also be started and stopped using the startup.bat and
shutdown.bat files located in the $INSTALL_DIRECTORY\appserver\bin
directory.
Once the Yellowfin server has been successfully started, check that the application is
functioning correctly by selecting the Yellowfin Home Page in the Yellowfin Program
Group.
When first logging in to Yellowfin it is suggested that you use the
[email protected] user. This user will permit you to undertake administration
activities such as creating new source connections and views.
When Yellowfin is installed 4 default users are provided in each of the default security
user roles. If your license does not include the required number of users then you will
only have a single administration user.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
User ID
Description
[email protected]
This user has full Administrative privileges. Any
user with these authorities has the maximum
capabilities with the system. It is recommended
that very few users have access to this userid.
[email protected]
This user has Corporate Administrator privileges.
Users with these authorities can configure the
metadata required to run the system.
[email protected]
This user has Report Writer/Display capabilities.
Users which will create reports on behalf of other
users should be granted these sorts of privileges.
These users will have a high level of education
with the Yellowfin product.
[email protected]
This user has Report Consumer capabilities.
These sorts of users will run pre-built reports
entering any optional parameters.
The initial password for each of these users is test.
It is highly recommended that these default password of default users be changed as
soon as the installation has completed successfully for security reasons.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
If you need to add additional connection drivers then:
1. Copy your JDBC driver JAR file(s) into the
Yellowfin/appserver/webapps/ROOT/WEB-INF/lib/ directory.
2. Edit the file Yellowfin/appserver/webapps/ROOT/WEB-INF/web.xml
Add the class name for your driver to the list in the JDBCDrivers parameter.
3. You will then need to restart Yellowfin for the new driver to become available.
The TCP/IP port is used for the connection from the browser. You may have to
change the port number if you have another service running on the Yellowfin server
which has a port conflict. Choose a Port number which is not being used by another
service.
To update you port number open the server.xml file located in:
Yellowfin/appserver/conf/server.xml
There are two ports that are used by Yellowfin by default, and two more that can be
configured:
1. The port that Tomcat listens on for shut down requests (used internally by Tomcat)
2. The port that Tomcat listens on for HTTP browser connections
3. The port that Tomcat listens on for HTTPS browser connections
4. The port that Tomcat listens on for AJP connections (used when connecting
Tomcat to IIS or Apache)
(see below)
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
<Server port="8085" shutdown="SHUTDOWN">
(1)
<Service name="Catalina">
<Connector port="80"
(2)
maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" redirectPort="8443" acceptCount="100"
connectionTimeout="20000" disableUploadTimeout="true"
URIEncoding="UTF-8"
compression="on"
compressionMinSize="2048"
noCompressionUserAgents="gozilla, traviata"
compressableMimeType="text/html,text/xml,text/plain"
/>
<!-- Uncomment this for an SSL connector running on port 8443 (change
the port as required). You will need to generate a certificate
and save it in this directory as "tomcat.key" (change the
keystoreFile and keystorePass values as required).
See: http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html -->
<!-<Connector port="8443"
(3)
maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS" URIEncoding="UTF-8"
keystoreFile="${catalina.home}/conf/tomcat.key"
keystorePass="password"
/>
-->
<!-- Uncomment this for an AJP connector, to connect tomcat to another
web server such as Apache or IIS -->
<!-<Connector port="8009" protocol="AJP/1.3" />
(4)
-->
<Engine name="Catalina" defaultHost="localhost">
<Host name="localhost" appBase="webapps"
unpackWARs="true" autoDeploy="false"
xmlValidation="false" xmlNamespaceAware="false">
</Host>
</Engine>
</Service>
</Server>
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Yellowfin can be configured to broadcast electronic mail on an adhoc or scheduled
basis. A SMTP server must be running for outgoing mail to be sent successfully.
By default the Yellowfin application will use localhost as the SMTP server. If you
would like to use another SMTP server (such as an ISP SMTP server) you must
manually modify the SMTP configuration using the Administration Configuration
page.
Warning: Generally in an OEM deployment you may not wish to have your clients
modify the some configuration items. There is a risk that your users may modify a
key attributes which will break their instance of Yellowfin. Use role management to
remove the associated functions from their roles.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
The web.xml file provides configuration and deployment information for the Yellowfin
application. The Yellowfin web.xml file is located in the directory:
Yellowfin\appserver\webapps\ROOT\WEB-INF
A number of installation-specific settings are stored in web.xml when Yellowfin is
installed. These settings are critical to Yellowfin starting and running successfully.
The <ENTITY> line near the top of the file must correctly specify the Yellowfin path as
a URL:
<!ENTITY jsps SYSTEM "file:/C:/Program
Files/Yellowfin/appserver/webapps/ROOT/WEB-INF/web-jsps.xml">
Or
<!ENTITY jsps SYSTEM
"file:/usr/Yellowfin/appserver/webapps/ROOT/WEB-INF/webjsps.xml">
The connection parameters for the Yellowfin configuration database must be set
correctly in web.xml for Yellowfin to function. These settings are within the <servlet>
section named InitConnectionPool. The connection parameters are:
JDBCDriverClass The name of the JDBC Driver class
Required
JDBCUrl
The JDBC URL to connect to the database
Required
JDBCUser
The username used to connect
Required
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
JDBCPassword
The password used to connect
Required
JDBCPasswordE Whether or not the password in JDBCPassword is
ncrypted
encrypted. (true/false)
Optional (Defaults
JDBCMinCount
Required
The minimum number of connections to open to
to false)
the database
JDBCMaxCount
The maximum number of connections to open to
Required
the database
JDBCTimeout
PSCacheSize
How long a connection may be in use for before
Optional (Defaults
being closed (in seconds)
to 300)
How many Prepared Statements to cache per
Optional (Defaults
connection (maximum). Setting this to zero
to 20)
disables Prepared Statement caching.
There are a number of general startup parameters that affect various parts of
Yellowfin. These settings are within the <servlet> section named MIStartup. The
parameters are:
ReportCacheSize
Number of result sets to store in the
report result cache
ReportCacheMaxAge
Optional
Defaults to 20
The maximum age of result sets in the
report result cache (in milliseconds)
Optional
Defaults to 24 hours
BIRTPath
The path to the BIRT support files
Optional
ScanJarFiles
Whether or not to scan for JDBC drivers
Optional
at startup (true/false)
JDBCDrivers
Defaults to true
JDBC driver class names to search for at Optional
startup, separated by commas. If
ScanJarFiles is false, use this to specify
the available drivers.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Clustering allows Yellowfin to be run on multiple servers off the same database. In
order to cluster Yellowfin, the following will need to be added into the web.xml file,
with your web services information filled in.
<!-- Cluster Management -->
<servlet>
<servlet-name>ClusterManagement</servlet-name>
<servlet-class>com.hof.mi.servlet.ClusterManagement</servlet-class>
<init-param>
<param-name>ServiceUser</param-name>
<param-value>[email protected]</param-value>
</init-param>
<init-param>
<param-name>ServicePassword</param-name>
<param-value>test</param-value>
</init-param>
<init-param>
<param-name>ServiceAddress</param-name>
<param-value>/services/AdministrationService</param-value>
</init-param>
<init-param>
<param-name>ServicePort</param-name>
<param-value>80</param-value>
</init-param>
<init-param>
<param-name>ClusterHosts</param-name>
<param-value>
192.168.4.196
</param-value>
</init-param>
<load-on-startup>11</load-on-startup>
</servlet>
Clustering will make sure that:
1. If changes are made to ref codes on one server, all other servers reload their ref
codes.
2. If a view is changed, the old version will be removed from the cache of all
servers.
3. If a new licence is uploaded, all servers are updated.
Note: You will also need a special licence, which you will have to contact Yellowfin for
([email protected]).
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Other than increasing hardware capacity, e.g. faster CPU and memory allocation,
there are a number of ways that Yellowfin can be performance tuned. For more
information on capacity and configuration settings please refer to the server capacity
white paper.
The Tomcat WebServer default and maximum connections can be adjusted to enable
more concurrent connections although the default settings should handle up to 100
users.
These parameters can be set in the $INSTALL_DIRECTORY
\appserver\webapps\ROOT\WEB-INF\web.xml file.
The context in the file is against the servlet 'InitConnectionPool'.
The Yellowfin Application server requires a connection to the Yellowfin database
server to access the report repository and meta-data. This connection can be tuned
to allow more through-put depending on the number of concurrent users expected in
your installation.
The database connection default and maximums can be changed in
$INSTALL_DIRECTORY\appserver\webapps\ROOT\WEB-INF\web.xml file.
The current defaults are 2 (minimum) and 5 (maximum). Amending this connection
limit would help performance.
Note: if Yellowfin performance in an issue then changing the connection parameters
may assist. However, you will also have to consider your hardware configuration to
ensure that it is setup to support the number of concurrent users you have. Please
refer to the server capacity white paper for more information.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Yellowfin has hard memory limits that are set in configuration files. The application
will never allocate more memory once it reaches these limits, even if the server has
more free memory. In some cases this can cause errors if Yellowfin needs more
memory.
Instructions for increasing the JVM Max Memory depend on how Yellowfin is started.
Windows Service
When the Yellowfin service is first installed, the memory limits are taken from the
Yellowfin\appserver\bin\service.bat file. This file can be modified to provide different
defaults, but this will only be read when the service is installed. To modify the memory
limits for an existing service, follow this process:
1. Open the Command Prompt and change to the appserver\bin directory under the
Yellowfin installation directory.
2. Run the command:
tomcat5w.exe //ES//Yellowfin
This will run the service manager for the Yellowfin service. Go to the "Java" tab, and
change the "Initial memory pool" and "Maximum memory pool" values:
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
3. Restart the Yellowfin service to pick up the changes.
Windows Start Menu
If you start the Yellowfin server from the Windows Start Menu, the memory limits are
in the startup batch files.
1. Shut down Yellowfin
2. Edit the file Yellowfin\appserver\bin\catalina.bat
3. Find the section:
rem Memory limits.
rem Use these options to set the Java memory limits.
rem -Xms128m sets the initial Java heap size to 128Mb
rem -Xmx512m sets the maximum Java heap size to 512Mb
rem To set memory limits uncomment the following line:
rem set JAVA_OPTS=%JAVA_OPTS% -Xms128m -Xmx512m
4. Remove the "rem" from the start of the last line, and change the Xmx option to
your desired max memory setting.
5. Restart Yellowfin to pick up the changes.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Linux/Unix/Mac OSX
If you run Yellowfin on Linux/Unix/Mac OSX, the memory limits are in the startup scripts.
1. Shut down Yellowfin
2. Edit the file Yellowfin/appserver/bin/catalina.sh
3. Find the section:
# Memory limits.
# Use these options to set the Java memory limits.
# -Xms64m sets the initial Java heap size to 64Mb
# -Xmx256m sets the maximum Java heap size to 256Mb
#JAVA_OPTS="$JAVA_OPTS -Xms64m -Xmx256m"
4. Uncomment the last line, and change the Xmx option to your desired max memory
setting.
5. Restart Yellowfin to pick up the changes.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Yellowfin has internationalisation and localisation capability. This means that
Yellowfin can be deployed in multiple languages and supports double byte character
sets. This chapter provides you with details on the steps required to localise Yellowfin
for your particular language installation.
Yellowfin uses Struts internationalisation for its process. (See
http://www.exadel.com/tutorial/struts/5.2/strutstutorials-i18n.html for more details).
Text within the JSP has a <bean:message key="key"/> tag. See example from
the dashboard jsp below.
<img src="images/rpt_add.gif" alt="<bean:message key="mi.text.newtab"/>"
border="0" />
<a href="javascript:on_submit('newTab');"><bean:message key="mi.text.tab"/></a>
The bean then references the resources file for the message key mi.text.tab=Add
Tab
The language code specified within the bundle allows multiple languages to be
deployed within a single site. Yellowfin will detect the users default browser language
setting and display text accordingly.
Figure 2 Double Byte Translation
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
The login page is usually configured per installation as a result Yellowfin has not
internationalised this page. You will have access to the JSP and can create your own
look and feel which would include localisation as required.
If using single-sign on you will by-pass the login page and as a result will not need to
edit this jsp at all.
Yellowfin can export report data to PDF files. For double byte character sets the
customer must choose the default PDF export fonts. Since the font will be embedded
in the PDF. This font can differ from the output font that is displayed on the screen.
The end user may have the option to change these fonts (eg there are 4 Chinese
variations).
1. If using Chinese, Korean or Japanese font sets for report out put you will have to
select a default font set for PDF export.
2. Navigate to the Administration panel and click the configuration link.
3. Select the PDF from type from the default drop down list.
4. If you wish to enable your users to change the font at the time of printing the report
set the allow users to change to „Yes‟
All displayed text within Yellowfin – excluding your own content can be translated
based on the users browser settings. This is achieved via two mechanisms –
management of the application resource file – which is used predominantly for display
text, and the Yellowfin reference code tables which are generally used for drop down
menus.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
In the directory Yellowfin/webapps/ROOT/WEB-INF, create the directory structure
classes/com/hof.
1. Copy the Application Resource file – Eg. for Japanese ApplicationResource_ja.properties into the hof directory.
2. Restart Yellowfin, and the Japanese translations will become available.
The translations shown are based on the settings of your browser; this allows multiple
translations off the same instance of Yellowfin.
Yellowfin generally maintains a localized translation for its internal reference codes of
all its supported languages. However if you wish to update these manually you can
do so by updating the ReferenceCodeDescription table directly.
In this table you will see the short and long description for each reference code used
within the application, and a language code for specific languages. Generally only
the short description is displayed. Update the short description to changed the
displayed text.
A configuration option exists within Yellowfin to determine the default date format that
is used throughout the application.
For example Yellowfin comes with a standard date format of day/month/year.
However, your local custom is to use month/day/year.
By updating the configuration item your users will always be presented with dates in
the preferred format.
1. To update the date format access the administration > configuration form.
2. Set the date format using the options available.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
To configure the default name format you can change the order in which names are
printed out on the page.
Select the name format that is appropriate for your local.
To configure the default decimal and thousand separator formats select the name
format that is appropriate for your local.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Yellowfin allows you to manage your license either via an external page (without
logging in) or from the administration panel. The Administration panel also provides
you with an overview of your license variables such as number of users and expiry
dates.
After you have installed Yellowfin you may need to update your license file. Generally
the license key you receive with the installer is for a limited time only. When you
receive your new license key or a regenerated license key you can update it via
Administration > Licence Details
Figure 3 Licence Upload
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
If your license is invalid you will be presented with a license error message. Confirm
the license is valid (dates, hostname) by viewing the parameters in a text editor. If all
parameters appear to be valid contact Yellowfin for support.
To load a new license file you must do so from the server on which Yellowfin is
installed. If you do not do so the following error is displayed.
Once you login to Yellowfin you will be able to view and update your license from the
administration panel.
1. Login as an administrator and navigate to the Administration panel via the
administration link from the main Yellowfin navigation links.
2. Click the License details link to open the license management screen.
3. You will now see a screen as detailed below. This will provide an overview of the
number of licenses and users you have. You will also be able to load a new license
file into the application.
Figure 4 License Management
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Yellowfin does not come with a specialised backup or recovery facility. We
recommend that the application code and data is backed up as per your standard
Disaster Recovery procedures.
The Yellowfin database is the single most important component that requires
frequent backing up and should be ear marked for rapid recovery in the case of a
system or media failure. There are many methods for ensuring recoverability of data
including RAID, file system backups and vendor specific backup and image copy
facilities.
At a minimum it is recommended that a database dump be made as frequently as
possible and stored on a device separate to the production database server. The
database administrator should devise a suitable backup strategy.
The Yellowfin application server contains the code base which performs all the
processing. Whilst it is possible to reinstall the application it is recommended that file
system backups of this code base be made as per existing customer procedures. This
will lead to a faster and more efficient application recovery than re-installing the
product in the case of system or media failure.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
To apply a patch to a Yellowfin installation, please follow these steps:
1. Shutdown the Yellowfin server
a. If you are running Yellowfin as a Windows service, stop the service
b. If you are running Yellowfin from the Windows Start Menu, please select
“Stop Yellowfin Server” from the Start Menu.
c.
If you are running Yellowfin a Linux command link, please run
Yellowfin/appserver/bin/shutdown.sh
2. Follow the patch steps as you would have in the initial installation:
Step
Page Display
Step 1. Welcome Screen
The welcome screen is the first screen in
the installation process. It informs you what
version of Yellowfin you are updating to.
Click the Next button to continue, or click
the Quit button at any time to exit the
installation process.
Step 2. Terms and Conditions.
The terms and conditions page lists the
Yellowfin Software License agreement.
When you have read the license agreement
check the “I accept the terms of this license
agreement” radio button to agree and click
the next button to continue.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Step 3. Installation Path
You will have to define the installation
directory for your current version of
Yellowfin. This will default to different
directories based on the operating system
you are installing to.
When you have chosen your installation
destination click the next button to continue.
Step 4. Style Updates Option
You will now be asked if you want to
preserve your current Yellowfin styles or
implement the new 5.2 options. There was a
significant change in interface styling for the
release of 5.2 and if you have custom styles
in place it‟s important to keep this in mind.
If you do plan on applying the new style you
will need to back up any custom styling as
these may be overwritten during the
upgrade process.
Once you have selected the styling option,
click next to continue.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Step 5. Check the Installation progress
This screen will enable you to observe the
progress of the software update. Depending
on the server hardware and software
capacity this could take a few minutes.
You will be able to click next to move to the
next window once the installation is
complete.
Step 6. Installation Completion
This screen will be displayed at the end of a
successful update of the Yellowfin
Application Server.
Click the Done button to complete the
update procedure.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Yellowfin provides you with multiple channels for accessing support, these include:
1. Access to the online Frequently Asked Questions (FAQ) Knowledge
Base: http://forum.yellowfin.com.au
2. Email [email protected] to get access to the online Support
Centre
The support forum provides a knowledge base of common deployment,
configuration, and content issues within Yellowfin. This should be your first port of call
for general enquiries.
The major categories on the forum include:
Installation & Integration – Technical questions related to installation and
integration of Yellowfin
General Discussion – General discussion of Yellowfin, dashboards and enduser functionality
Source & Administration – Discussion on administration of Yellowfin and
connecting to databases
Beacon – Guide our product development to ensure an enhanced Yellowfin
that continues to meet your needs.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
The online support centre has update information, tutorial and documentation
downloads, and migration information. To access the site contact
[email protected] to get a username and password setup.
When you have queries that are not general enquiries, but either defects or significant
deployment issues, contacting support is appropriate.
Standard Support Hours
1. Normal office hours: 8am to 7pm Australian EST
2. Business days: Monday to Friday (excluding Australian and Victorian public
holidays)
Out of Hours Support
To ensure identification of critical issues within your business hours, Yellowfin
provides a suitably qualified person in Australia to be on-call for your critical issues
(Priority A).
Support Process
Yellowfin logs all incoming requests for assistance. A Unique tracking number is
assigned to each issue entered into the Request Tracker.
You will receive a confirmation email with the number attached for later reference.
Your request will be prioritised and a due date assigned based on our SLAs.
All status updates are delivered by a reply to the requestor within the ticket, or by
telephone or email. Upon resolution, Yellowfin staff will document the resolution in the
ticket tracking system, notify you that the problem has been resolved and how, and
then close the ticket.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
To make it easier to ensure a rapid response please provide a comprehensive brief to
Yellowfin, consisting of:
1. A documented example of the defect or error
2. Screen shots of any error messages or the problem itself
3. Confirmation that the error has been replicated
4. Operating environment information (check out info.jsp)
We also may ask you to increase the log level, trigger the error and send us the log
files.
Possible Issues:
1. Invalid or expired license file.
There will be error messages in the Yellowfin application log or STDOUT log
relating to the license. The license file is attached to a specific host name. If the
host name is:
a. mistyped
b. the server host name has changed
c.
Yellowfin is moved to another server – the license will no longer be valid.
2. Port conflicts.
There will be error messages in the Tomcat info log or STDOUT log relating to the
Tomcat endpoint. This means that another program is using the same port as
Yellowfin – try changing the port.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
The information JSP provides a list of all the environmental variables that Yellowfin is
running with. This page is used to assist with debugging Type 2 JDBC drivers, where
native libraries are required in the Yellowfin class path.
It also shows license details and operating system information. You may be
requested to send the details from this page to Yellowfin support if you are having
technical issues. Access the info page via http://<yourservername>/info.jsp
When escalating a problem to Yellowfin support, the output of this page will help us to
diagnose the issue. Yellowfin must be running for this page to be available.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
During normal operation, Yellowfin writes to a number of log files. Information written
to these files includes error messages, system information and diagnostic messages.
The most important log files are the Yellowfin application log, STDOUT log, and the
Yellowfin config db log. Often it will be useful to temporarily increase the detail level of
the Yellowfin application log when a problem occurs.
Log
Description
Use
Tomcat info log
Contains information on Tomcat start up
If there is a problem
and shutdown. Includes any error
at the Yellowfin start
messages during Tomcat initialisation,
up or shut down.
such as port conflicts.
Note: all information logged to the
Tomcat info log is also logged to the
STDOUT log.
STDOUT log
Contains start up information printed out
Used for general
by Yellowfin, as well as information
issues or areas.
logged to the Tomcat info log. Yellowfin
application errors will usually be
included.
Yellowfin
Contains information messages printed
Used for any
application log
by Yellowfin.
application errors.
Service info log
Contains information about that Windows
Used if there is an
service start up and shutdown.
error related to the
configuration
database.
Yellowfin config
Contains information on the Yellowfin
Used for Yellowfin
database log
configuration database connection pool.
errors related to the
configuration
database.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Data source logs
Each data source in Yellowfin has its
Used for Yellowfin
own log file. The location of the file is
errors related to the
configured when the data source is
source database.
created, and can be changed while
Yellowfin is running.
The log file location can be either an
absolute path name on the Yellowfin
server, or a path name relative to the
Yellowfin logs directory
(Yellowfin\appserver\logs).
Yellowfin log files are saved into the directory: Yellowfin\appserver\logs
E.g. if Yellowfin was installed into
C:\Progam Files\Yellowfin 4.0\
Then the logs directory is:
C:\Program Files\Yellowfin 4.0\appserver\logs
The names of various log files depend on the Operating System, and the startup
method.
Windows Installation
Start Menu
Tomcat info log
Service
Linux Installation
Startup Script
catalina.YYYY-MM-
catalina.YYYY-MM-
DD.log
DD.log
STDOUT log
console window
stdout_YYYYMMDD.log
catalina.out
Yellowfin
yellowfin.log
yellowfin.log
yellowfin.log
application log
Service info log
jakarta_service_YYYYM
MDD.log
Yellowfin config
jdbc.log
jdbc.log
jdbc.log
configurable
configurable
configurable
db log
Data source logs
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Apr 12, 2007 10:58:03 AM org.apache.coyote.http11.Http11BaseProtocol init
INFO: Initializing Coyote HTTP/1.1 on http-8090
Apr 12, 2007 10:58:03 AM org.apache.catalina.startup.Catalina load
INFO: Initialization processed in 852 ms
Apr 12, 2007 10:58:04 AM org.apache.catalina.core.StandardService start
INFO: Starting service Catalina
Apr 12, 2007 10:58:04 AM org.apache.catalina.core.StandardEngine start
INFO: Starting Servlet Engine: Apache Tomcat/5.5.20
Apr 12, 2007 10:58:04 AM org.apache.catalina.core.StandardHost start
INFO: XML validation disabled
Apr 12, 2007 10:58:17 AM org.apache.coyote.http11.Http11BaseProtocol start
INFO: Starting Coyote HTTP/1.1 on http-8090
Apr 12, 2007 10:58:17 AM org.apache.catalina.startup.Catalina start
INFO: Server startup in 13699 ms
Lines starting with SEVERE indicate error messages.
SEVERE: Error starting endpoint java.net.BindException: Permission denied:80
SEVERE: Error initializing endpoint java.net.BindException: Address already in
use:80
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
=================== i4 Logging System ==================================
|
| Reading configuration file...OK
|
| System Type: FreeBSD
| Configuration file name: /home/joynt/yf/appserver/webapps/ROOT/WEBINF/
log4j.properties
|
========================================================================
Java stacktraces indicate errors.
java.lang.Exception: All attempts at connecting to Database exhausted
at com.hof.util.DBConnectionBroker.A(Unknown Source)
at com.hof.util.DBConnectionBroker.<init>(Unknown Source)
at com.hof.servlet.InitConnectionPool.init(Unknown Source)
at org.apache.catalina.core.StandardWrapper.loadServlet(StandardWrapper.java:
1105)
YF:2007-04-11 10:42:15: INFO (MIDashboardEntryAction:execute) MIDashboardEntryAction entered
YF:2007-04-11 10:42:15: INFO (MIDashboardEntryAction:execute) MIDashboardEntryAction exiting with action: MIDashboard
YF:2007-04-11 10:42:15: INFO (MIPreDashboardAction:execute) MIPreDashboardAction entered
YF:2007-04-11 10:42:16: INFO (MIPreDashboardAction:execute) MIPreDashboardAction exiting with action: success
YF:2007-04-11 10:42:20: INFO (LogoAction:execute) - Logo Action entered
YF:2007-04-11 10:42:20: INFO (LogoAction:execute) - Logo Action exiting
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Log messages have one of four levels:
a. DEBUG
b. INFO
c.
WARN
d. ERROR
By default, INFO level messages and above are written to the log file. To change the
detail level, edit the file Yellowfin\appserver\webapps\ROOT\WEB
INF\log4j.properties. Towards the bottom of this file, find the line:
log4j.category.com.hof=INFO
Change this level to the desired level. For example to only print error messages,
change it to:
log4j.category.com.hof=ERROR
Note that changing this to DEBUG may cause the log file to grow very quickly.
This file contains information about the Windows service start up and shutdown
processes.
----------------------------------------2007-04-12 10:58:07
Starting DBConnectionBroker
db Driver = org.postgresql.Driver
db Server = jdbc:postgresql://localhost/yf31
db Login = joynt
Log File = /usr/home/joynt/yf/appserver/logs/jdbc.log
Log Append = true
Debug Lvl = 3
min connections = 2
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
max connections = 5
Total refresh interval = 4.0 hours
maxCheckoutSeconds = 300
PS Cache Size = 20
----------------------------------------[INFO] 2007-04-12 10:58:07 Opening connection 0
[INFO] 2007-04-12 10:58:07 Opening connection 1
Log messages have one of three levels:
a. INFO
b. WARN
c.
ERROR
The file used for this log can be changed by editing the file:
Yellowfin\appserver\webapps\ROOT\WEB-INF\web.xml
Find the section:
<init-param>
<param-name>JDBCLog</param-name>
<param-value>/home/joynt/yf/appserver/logs/jdbc.log</param-value>
</init-param>
Change the path to a valid location on the Yellowfin server. Restart Yellowfin for the
change to take effect.
The contents of the data source logs are similar to the Yellowfin config db log.
Additionally, the log detail level can be set to INFO, WARN, ERROR or None.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Yellowfin start up batch files contain a number of parameters which affect how
Yellowfin runs. Important parameters include the Java installation directory, the
Yellowfin installation directory and memory usage limits.
The batch files are located in the directory Yellowfin\appserver\bin.
These parameters are set in the file catalina.bat on Windows, and catalina.sh on
Linux. There are also parameters in the file service.bat, which are used for installing
and removing a Windows system service.
Configurable parameters are contained in a section labelled Yellowfin Options near
the top of the file.
rem -------------------------------------------------------------------------rem Yellowfin Options
rem $Id$
rem set JRE_HOME to value chosen in installer
set JRE_HOME=C:\Program Files\Java\jre1.6.0
rem set CATALINA_HOME to install directory
set CATALINA_HOME=C:\Program Files\Yellowfin 3.1\appserver
rem Memory limits.
rem Use these options to set the Java memory limits.
rem -Xms128m sets the initial Java heap size to 128Mb
rem -Xmx512m sets the maximum Java heap size to 512Mb
rem To set memory limits uncomment the following line:
rem set JAVA_OPTS=%JAVA_OPTS% -Xms128m -Xmx512m
rem If you are experiencing "java.lang.OutOfMemoryError: PermGen space"
rem errors, uncomment the following line:
rem set JAVA_OPTS=%JAVA_OPTS% -XX:PermSize=64m -XX:MaxPermSize=128m
rem --------------------------------------------------------------------------
Lines starting with “rem” are ignored.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
The JRE_HOME parameter must be set to the Java installation directory. The
CATALINA_HOME parameter must be set to the Yellowfin installation directory. The
JAVA_OPTS parameter may be used to modify the Java memory usage limits. The
PermSize options should only be used if you encounter the error:
java.lang.OutOfMemoryError: PermGen space
This file is the Linux equivalent to catalina.bat and contains a similar Yellowfin
Options section:
# --------------------------------------------------------------------# Yellowfin Options
# $Id$
# set JAVA_HOME to value chosen in installer
JAVA_HOME="/usr/local/diablo-jdk1.5.0/jre"
# set CATALINA_HOME to install directory
CATALINA_HOME="/home/joynt/yf/appserver"
# enable headless mode
CATALINA_OPTS=-Djava.awt.headless=true
# Memory limits.
# Use these options to set the Java memory limits.
# -Xms128m sets the initial Java heap size to 128Mb
# -Xmx512m sets the maximum Java heap size to 512Mb
# To set memory limits uncomment the following line:
# JAVA_OPTS="$JAVA_OPTS -Xms128m -Xmx512m"
# If you are experiencing "java.lang.OutOfMemoryError: PermGen space"
# errors, uncomment the following line:
# JAVA_OPTS="$JAVA_OPTS -XX:PermSize=64m -XX:MaxPermSize=128m"
# ------------------------------------------------------------------
Lines starting with # are ignored. The JAVA_HOME parameter must be set to the
Java installation directory. The CATALINA_HOME parameter must be set to the
Yellowfin installation directory. The JAVA_OPTS parameter may be used to modify
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
the Java memory usage limits. The PermSize options should only be used if you
encounter the error:
java.lang.OutOfMemoryError: PermGen space
This file is used to install and remove the Windows system service. Configurable
parameters are contained in a section labeled Yellowfin Options near the top of the
file:
rem ------------------------------------------------------------------rem Yellowfin Options
rem $Id: service.bat,v 1.2 2007/02/21 02:58:55 steve Exp $
rem set JAVA_HOME to value chosen in installer
set JAVA_HOME=C:\Program Files\Java\jre1.6.0
rem Memory limits.
rem Set JvmMs to minimum JVM stack size (in Mb)
rem Set JvmMx to maximum JVM stack size (in Mb)
set JAVA_OPTS=%JAVA_OPTS% --JvmMs 128 --JvmMx 256
rem ------------------------------------------------------------------
Lines starting with “rem” are ignored. The JAVA_HOME parameter must be set to the
Java installation directory. The JAVA_OPTS parameter may be used to modify the
Java memory usage limits.
The service can be installed during Yellowfin installation. It can also be installed or
removed at a later time from the command line.
Change to the directory Yellowfin\appserver\bin
To install the Yellowfin service, run “service install Yellowfin”
To uninstall the Yellowfin service, run “service remove Yellowfin”
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Yellowfin makes extensive use of application logging for trouble shooting and tuning
purposes. Yellowfin errors and messages will be recorded in different files /
applications, depending on the nature of the error. These include:
If you start Yellowfin manually (not as a service) and it‟s running under a Console
Window will be started up. Most errors, including any start up ones, can be found
here. If you have errors on startup this is the most appropriate location to begin your
investigation of the issue.
If Yellowfin is started as a service, the console output is re-directed to a file called
tomcat.log.
Any application server messages (ie.Tomcat messages) and uncaught java
exceptions generated by the application will be found in the Application Server Log.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
All standard application logging by the application (mainly for debugging and tuning)
can be found here (along with console output if Yellowfin was started as a service).
The logging level for the debugging and tuning can be controlled by the file:
$INSTALL_DIRECTORY\appserver\webapps\ ROOT\WEBINF\log4j.properties
It is suggested this is left as default unless instructed by Yellowfin technical support.
The directory that the log files can be found in is
$INSTALL_DIRECTORY\ appserver\logs.
If you have deployed Yellowfin under another application server (i.e not Tomcat) then
the logging locations will differ. Please refer to application server manuals for details.
All JDBC errors related to connections will be logged in a file and directory of your
choosing. When setting up a new JDBC connection Yellowfin you will be prompted to
define a log file and log directory path.
Note: An exception to this is OLAP sources. There is no error logging for OLAP /
XMLA source connections – since these are web services and do not use JDBC.
Some databases require specific configurations for JDBC connections to be
successful. These issues and the resolution of them are outside the context of this
guide. Please refer to individual guides for your specific database, for example:
Access, Progress and Lotus Notes.
Copyright
Yellowfin International pty ltd 2011
www.yellowfin.com.au
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement