Dodeca Installation Guide · 2021. 6. 12. · The persistence engine creates SQL statements for your selected relational database engine and communicates with the 3. ... Configure

Dodeca® Installation Guide

Copyright © 1998-2021 Applied OLAP, Inc. All Rights Reserved.

Dodeca is a registered trademark of Applied OLAP, Inc. Microsoft, Windows, Office, Excel, andInternet Explorer are registered trademarks of Microsoft Corporation. Oracle is a registeredtrademark of Oracle Corporation and Essbase is a trademark of Oracle. All other product andcompany names mentioned herein are trademarks of their respective owners.

Information in this document is subject to change without notice. The software described in thisdocument is furnished under a license agreement or nondisclosure agreement. The softwareand this documentation may be used only in accordance with the terms of those agreements.

Applied OLAP, Inc. 120 Holmes Ave. NE Suite 405 Huntsville, AL 35801 U.S.A.

Table of ContentsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Client (Standard Runtime) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Client (Standard Developer Desktop) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Client (War Deployment / Developer Desktop) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Dodeca Deployment Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Dodeca Framework Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Relational Database Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Configuration of Oracle Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Creating the Dodeca Tablespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Configuring User Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Configuration of Microsoft SQL Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Creating the Dodeca Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14


Configuration of MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Creating the Dodeca Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17


Dodeca WAR File Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Step-by-Step Instructions to Create the War File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Dodeca WAR File Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Deployment to Apache Tomcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

1

WAR File Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Deployment to Oracle WebLogic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31


Deployment to Oracle Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32


Deployment to IBM WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32


Deployment to IBM WebSphere CE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33


Deployment to JBoss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34


Dodeca-Essbase WAR File Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Essbase Outline Relational Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Specifies whether relational cache storage is turned on or off. If it . . . . . . . . . . . . . . . . . . . . . . . 36

not parsed or loaded (it may be read by default from the persistence . . . . . . . . . . . . . . . . . . . . . 37

Should only be used to increase performance at the cost of building the . . . . . . . . . . . . . . . . . . 37

If enabled, WEB-INF\classes\META-INF\persistence.xml needs to be . . . . . . . . . . . . . . . . . . . . . 37

Dodeca-Essbase WAR File Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Completing the Setup - The Application Setup Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

ClickOnce Deployment from an HTML Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Local Client Installation and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

The Dodeca Accelerator Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Contact Us. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

2

IntroductionDodeca is an application development and deployment platform that can be used to createrobust desktop applications that are deployed as simply as web applications. This guide will giveyou detailed information on the three tiers involved in the software installation process, alongwith step-by-step instructions for completing your installation.

Dodeca is architected to use three separate tiers:

• Smart Client tier

• Application Server tier

• Database tier

The Smart Client tier is architected as a .NET Smart Client that communicates with all externaldata and metadata providers using a web service paradigm. In other words, all communicationbetween the Smart Client and the Application Server is performed via XML packets transmittedvia HTTP/S. The Smart Client architecture provides for a very rich user experience, whileavoiding the most common problem that occurs with traditional rich client applications.Installation has long been a significant issue for desktop applications. With the introduction ofthe Microsoft .NET Framework and its ClickOnce deployment paradigm, Smart Clientapplications can now be deployed as easily as any web-based application.

The Application Server tier serves as the endpoint for all data and metadata requests made bythe Smart Client tier. The Application Server is responsible for unpacking the XML request,calling the appropriate service based on the arguments passed with the request, and thenpackaging and returning an XML response. The Application Server tier is architected to use Java2 Enterprise Edition (J2EE) servlets to provide additional functionality. The servlets, one forDodeca metadata services and one for Essbase services, are packaged in standard J2EE WAR (Web ARchive) files. J2EE Application Servers use WAR files as a standard deploymentmechanism. This guide provides step-by-step instructions for creating the WAR file for yourdeployment along with instructions for the actual deployment in several leading applicationservers.

The Application Server tier also serves as the deployment mechanism for the Smart Clientdeployment using ClickOnce. ClickOnce deployments are accomplished using a URL to start theinstallation process. Dodeca is packaged with some innovative tools that automate the processof creating and digitally signing the ClickOnce deployment files, including any extensions youcreate for the Dodeca product. The tools also embed the ClickOnce deployment inside yourWAR file.

Finally, the Application Server tier uses Hibernate Object-Relational Mapping (ORM) software topersist the Java metadata objects to a relational data source. The persistence engine createsSQL statements for your selected relational database engine and communicates with the

3

relational database using Java DataBase Connectivity (JDBC).

The Database tier is responsible for data storage and retrieval. The Database tier consists of oneor more relational databases and, optionally, one or more Essbase databases. These databasesmay reside on any number of physical machines in your computing environment. Typically,communication from the Application Server tier to a relational database is via standard JDBCmethods. Communication from the Application Server tier to an Essbase database is via theHyperion Essbase Java API.The following is a graphical representation of the architecture, showing the three tiers and atypical component configuration:

System RequirementsSystem requirements vary based on both the tier and the type of usage required of themachine.

Client (Standard Runtime)

4

Hardware

• Pentium class processor (1 Ghz or higher)

• 512 MB RAM or higher

• 10 Mbps Ethernet or faster

• 40 MB available disk space

Software

• .NET 2.0 Framework Runtime (preferably with Service Pack 1 or greater)

• .NET ReportViewer control (optional - for displaying MS Reporting Services views)

Client (Standard Developer Desktop)

Hardware


• 1 GB RAM or higher



Software



• Visual Studio 2005 (optional - includes the .NET 2.0 Framework Runtime and allowsdevelopers to create modular extensions to the Dodeca Framework)

• Dodeca Framework (optional - provides sample metadata, utilities, and programmingtemplates, as well as other Dodeca-specific features for required for Visual Studiodevelopment)

Client (War Deployment / Developer Desktop)

Hardware


• 1 GB RAM or higher

5



Software


• Dodeca Framework (provides sample metadata, utilities, and programming templates, aswell as other Dodeca-specific features required for Visual Studio development)


• Visual Studio 2005-2010 (optional - includes the .NET 2.0 Framework Runtime and allowsdevelopers to create modular extensions to the Dodeca Framework)

Application Server

Hardware

• Sufficient memory to run your application server, Dodeca metadata, and data servlets (Note:running Tomcat with the Dodeca metadata servlet, data servlet, and the EssbaseDeployment Services servlet takes about 42 MB of RAM to startup).

• Sufficient memory to run the expected number of simultaneous Essbase queries processed.This amount may vary greatly based on the size of the retrieval ranges in your worksheets,the number of users on the system, and the average amount of time between transactionsby each user.

Software

• Java Application Server. We support the same application server software as Oracle forEssbase Deployment Services / High Availability Services / Analytic Provider Services.Supported servers include:

◦ Apache Tomcat

◦ IBM WebSphere

◦ BEA / Oracle WebLogic

◦ Oracle Application Server

• Dodeca metadata servlet

• JDBC driver to support your chosen metadata repository

• Dodeca Essbase servlet

6

Dodeca Deployment StepsThere are several steps required to deploy Dodeca in your environment. The remainder of thisdocument contains detailed instructions for the installation. Those instructions pertain to thefollowing steps:

1. Install the Dodeca Framework which is used to create the WAR file.

2. Configure the relational server and database where Dodeca metadata will be stored.

3. Prepare the Dodeca WAR file. The preparation includes these steps:

a. Complete installation prerequisites, which may include the installation of softwarenecessary to create the Dodeca WAR file for deployment.

b. Modify the hibernate.properties file used by the Dodeca server to connect to therelational database repository.

c. Optionally, modify other configuration files.

d. Run the ClickOnce Prep Utility to generate the Dodeca WAR file for deployment.

4. Deploy the Dodeca WAR file to the Java Application Server of your choice.

5. Run the Dodeca Application Setup Utility, which creates the necessary tables in therelational database repository, seeds the metadata repository, and creates the clientinstallation URL.

6. Test the client installation.

A video tutorial series covering the basic procedure for deploying Dodeca canbe found at the following location:http://www.youtube.com/playlist?list=PL0686C273FAA441D8

Dodeca Framework InstallationThe Dodeca Framework installation installs the files and utilities needed to create a DodecaWAR file for deployment. The installation also includes files that developers may use, optionally,to write extensions for Dodeca. This installation must be performed on a Windows desktop.Each client company must have at least one desktop with the Dodeca Framework installed (atleast temporarily).

The Dodeca Framework installation is contained in an executable installation file. To install theDodeca framework, double-click on the Dodeca Framework executable. You will see thefollowing installation screen:

7

http://www.youtube.com/playlist?list=PL0686C273FAA441D8

Press the 'Next' button to proceed and show the license agreement dialog. You must agree tothe license agreement in order to proceed with the installation.

Press the 'I Agree' button to proceed.

8

Choose the folder where you would like to install the Dodeca Framework and press 'Install' toproceed with the installation.

9

If the directory already exists or the installer detects a previous installation,you will be asked how you would like to proceed in order to preventunintentional overwrites of previous installs.

Press the 'Install' button to initiate the install process. Once the install is complete, you will see aconfirmation that the installation has completed successfully.

10

Once the install is complete, your computer will have the following directory structure installedat the location you specified.

11

The directories installed include:

\bin\Dodeca Dodeca client intended for usage byapplication developers.

\bin\Bootstrapper .NET Runtime installation components.

\docs Developer documentation.

\essbase The Dodeca-Essbase servlets that provideEssbase Connectivity in Dodeca.

\metadata Sample application metadata.

\servlet The original servlet compiled by Applied OLAPthat can be used to refresh your stagingdirectory to its original, as-shipped, state.

\staging The contents of the dodeca.war file distributedinto its component directory structures. Youwill use this directory to modify and 'stage'your WAR file.

Relational Database ConfigurationOnce you have installed the Dodeca Framework, you will need to create a relational databaserepository where Dodeca metadata will be stored. The configuration and database, tablespace,or schema creation procedures vary depending on your relational database vendor. This sectionof the guide includes detailed instructions for a variety of commonly-used relational databaseservers.

Configuration of Oracle Database

Oracle Database is a relational database management system that is available for severaldifferent

operating systems. The instructions below were created for Oracle Database 11g R2.

If you are planning on storing Unicode characters in your Dodeca repository,please ensure that the database in which the Dodeca tablespace will becreated is installed with the AL32UTF8 character set.

12

Creating the Dodeca Tablespace

To create a new tablespace in Oracle Database, follow these steps:

1. Open the Oracle Enterprise Manager for the database where the new tablespace will becreated.

2. At the top of the home page, click the 'Server' tab

3. Under the 'Storage' section, click 'Tablespaces'.

4. On the right side of the Tablespaces page, click the 'Create' button.

5. Assign a tablespace name by typing into the text field labeled 'Name'.

We recommend using the tablespace name 'dodeca', but you can use anyname you wish, provided that you remember to use it during the creation ofthe Dodeca WAR file.

6. Leave the default settings for the new tablespace as they are: Extent Management as'Locally Managed', Type as 'Permanent', and Status as 'Read Write'.

7. On the right side of the page under the 'Datafiles' section, click the 'Add' button to create anew Datafile.

8. Assign a 'File Name' (we recommend using the name, 'dodeca').

9. Under the 'Storage' section, check the box for 'AUTOEXTEND', set the 'Increment' size to 10MB, and leave the 'Maximum File Size' as 'Unlimited'.

10. Click the 'Continue' button to return to the 'Create Tablespace' page and click the 'OK'button in the top right corner to finish creating the new tablespace.

Configuring User Permissions

In order for Dodeca to properly utilize the newly created tablespace, a user with the followingSystem Privileges must be used to connect to the server:

CREATE TABLE

CREATE SEQUENCE

UNLIMITED TABLESPACE

CREATE SESSION

Although an existing user account can be used, we recommend creating a dedicated user foraccessing the newly created Dodeca tablespace. To create new user in Oracle Database, followthese steps:

13

1. Open the Oracle Enterprise Manager for the database where our Dodeca tablespace wascreated.

2. At the top of the home page, click the 'Server' tab

3. Under the 'Security' section, click 'Users'.

4. On the right side of the Users page, click the 'Create' button.

5. Assign a user name and password by typing into the 'Name' and 'Password' text fields.

We recommend using the user name 'dodeca', but you can use any name youwish, provided that you remember to use it during the creation of the DodecaWAR file.

6. Click the icon to select a 'Default Tablespace' and choose the Dodeca tablespace createdin the previous section.

7. Select a 'Temporary Tablespace' as well, and then click the 'System Privileges' tab

8. On the right side of the System Privileges page, click the 'Edit List' button.

9. Add the following 'Available System Privileges' from the list and then click 'OK'.

CREATE TABLE

CREATE SEQUENCE

CREATE SESSION

UNLIMITED TABLESPACE

10. On the right side of the Create User page, click the 'OK' button to finish creating the newuser.

Configuration of Microsoft SQL Server

Microsoft SQL Server is a popular relational database server developed by Microsoft. Theinstructions below were created for MS SQL Server 2008 R2, but the procedure is very similarfor SQL Server 2008 and 2005.

Creating the Dodeca Database

To create a new database in Microsoft SQL Server, follow these steps:

1. Open the Microsoft SQL Server Management Studio and connect to the server where thenew database will be created.

2. From the Object Explorer panel on the left, right-click on 'Databases' and select 'New

14

Database…' from the context menu that appears.

3. Assign a database name by typing into the text field labeled 'Database name'.

We recommend using the database name 'dodeca', but you can use any nameyou wish, provided that you remember to use it during the creation of theDodeca WAR file.

4. For now, just leave the database owner as '<default>'. If you wish to create a dedicated useraccount for the Dodeca database, this value can be changed as per the instructions in thefollowing section.

5. Under the 'Database files' table, set the 'Initial Size (MB)' of the main database file to '25’andchange the 'Autogrowth' setting to 'By 10 MB, Unrestricted Growth'.

6. Click the 'OK' button at the bottom of the dialog to finish creating the new Database.


In order for Dodeca to properly utilize the newly created database, a login with one of thefollowing sets of database role memberships must be used to connect to the server:

db_datareader

db_datawriter

db_ddladmin

public

or:

db_owner

public

Although an existing login can be used, we recommend creating a dedicated login for accessingthe newly created Dodeca database. To create new login in Microsoft SQL Server, follow thesesteps:

1. Open the Microsoft SQL Server Management Studio for the server where our Dodecadatabase was created.

2. From the Object Explorer panel on the left, expand the 'Security' node, right-click on'Logins', and select 'New Login…' from the context menu that appears.

3. Assign a login name by typing into the text field labeled 'Login name'.

15

We recommend using the login name 'dodeca', but you can use any name youwish, provided that you remember to use it during the creation of the DodecaWAR file.

4. Select the 'SQL Server Authentication' radio button, and enter/confirm a password.

5. Set 'Enforce password policy' and 'Enforce password expiration' as desired.

6. Set the default database to the newly created Dodeca database by selecting it from thedropdown labeled 'Default database'.

7. Press the 'OK' button at the bottom of the dialog to finish creating the new login.

To assign the correct database role memberships to a new or existing login you will need tofollow one of two procedures. The first procedure (a.) assigns ownership of the Dodecadatabase to a login, while the second procedure (b.) assigns only the required read, write, andadmin privileges.

a. To assign ownership of the Dodeca database to a login:

i. From the Object Explorer panel on the left, expand the 'Databases' node and find thenewly created Dodeca database.

ii. Right-click on the Dodeca database and select 'Properties' from the context menu thatappears.

iii. From the 'Select a Page' panel on the left, choose 'Files'.

iv. Assign a database owner by typing in or selecting the login of the desired owner at thetext field labeled 'Owner'.

v. Press 'OK' to save the changes.

b. To assign read, write, and admin privileges for the Dodeca database to a login:

i. From the Object Explorer panel on the left, expand the 'Security' node and select'Logins'.

ii. Right-click on the desired login and select 'Properties' from the context menu thatappears.

iii. From the 'Select a Page' panel on the left, choose 'User Mapping'.

iv. In the table labeled 'Users mapped to this login', check the 'Map' box beside the newlycreated Dodeca database.

v. With the Dodeca database selected, select the following 'Database role membership'options from the bottom table:

db_datareader

db_datawriter

16

db_ddladmin

public

vi.Press 'OK' to save the changes.

Configuration of MySQL

MySQL is a popular open-source relational database management system that is available forseveral different operating systems. The instructions below were created for MySQL CommunityServer 5.5, but the procedure is very similar for all MySQL versions 5.0 and higher.

If you are planning on storing Unicode characters in your Dodeca repository,please ensure that the schema created in the following section is created witha utf8 collation/character set.

Creating the Dodeca Schema

To create a new schema in MySQL, follow these steps:

1. Open an instance of MySQL Workbench and connect to the database where the newschema will be created.

2. From the Object Browser panel on the left, click 'Add Schema'.

3. Assign a schema name by typing into the text field labeled 'Name'.

We recommend using the schema name 'dodeca', but you can use any nameyou wish, provided that you remember to use it during the creation of theDodeca WAR file.

3. Press 'Apply' at the bottom of the 'new_schema' dialog to review the generated SQL Script.

4. Press 'Apply' at the bottom of the 'Apply SQL Script to Database' dialog to execute the scriptand create the new schema.

5. Press 'Finish' and then 'Close' to return to MySQL Workbench.


In order for Dodeca to properly utilize the newly created schema, a user with at least thefollowing Schema Privileges must be used to connect to the server:

SELECT CREATE

17

INSERT ALTER

UPDATE DROP

DELETE

Although an existing user account can be used, we recommend creating a dedicated user foraccessing the newly created Dodeca schema. To create new user in MySQL, follow these steps:

1. Open MySQL Workbench and, under 'Server Administration', select 'Manage Security' forthe database where our Dodeca schema was created.

2. Under the 'Server Access Management' tab, click the 'Add Account' button.

3. Assign a user name and password by typing them into the 'Login Name' and 'Password' textfields.

4. Press the 'Apply' button at the bottom to finish creating the new login.

To assign the required Schema Privileges to a new or existing user, follow these steps:

1. Open MySQL Workbench and, under 'Server Administration', select 'Manage Security' forthe database where our Dodeca schema was created.

2. Under the 'Schema Privileges' tab, choose the desired user and press the 'Add Entry…'button on the right.

3. Optionally, modify the default 'Host' settings, and then select the newly created Dodecaschema and press 'OK'.

4. Go ahead and press the 'Select "All"' button at the bottom to grant the selected login allavailable privileges for the Dodeca schema.

5. On the bottom right side of the page, press the 'Save Changes' button to save the updatedschema privileges.

Dodeca WAR File PreparationThe WAR file shipped with Dodeca contains nearly everything you need to deploy a Dodecaapplication, but it needs a few adjustments to tailor it to your server environment before it isready to use. There are a variety of reasons for this:

• The actual deployment URL used for ClickOnce deployment in your environment must beincluded in the 'deployment manifest' file, and that file must be digitally signed.

• You may want to include custom modules or other files in the deployment.

• You may want to customize the update options available with ClickOnce deployment.

For these reasons, you have to prepare the WAR file for deployment in your environment.

18

Fortunately, we have created a set of tools to make this process a fairly simple task. These toolsrely on certain software that must be installed on your computer, as well as certain actionswhich must be taken in order to run them successfully.

Prerequisites

Below is a list of the tasks that must be performed, files that must be obtained, and informationthat must be gathered before you can use our tools to create your custom WAR file:

1. You must have an Authenticode signing key from an authorized Certificate Authority (or"CA", such as VeriSign), the temporary key distributed by Applied OLAP, or a temporary keyyou have created yourself. The key must be in the form of a .pfx file. If you have a key from aCA that is in the form of public key/private key file pair, you can convert it to the .pfx formatusing the pvkimprt.exe tool available from Microsoft. See http://www.microsoft.com/downloads/details.aspx?FamilyID=F9992C94-B129-46BC-B240-414BDFF679A7&displaylang=EN for more information.

2. You must have created a relational database for your Dodeca repository (we suggest yousimply use the database name 'dodeca').

3. You must obtain the proper JDBC driver (Note: the Microsoft SQL Server JDBC driver isshipped in the base Dodeca War file).

4. You must determine the proper JDBC connection string, username, and password forHibernate to function.

Step-by-Step Instructions to Create the War File

Once you have completed the above prerequisites, you are ready to start the creation of yourWAR file for deployment. In order to create the WAR file, which is a Java archive of the \stagingdirectory structure, follow these steps:

1. If you would like to start with a fresh, 'as-shipped' set of files in the \staging directory, go tothe \bin directory and find the shortcut for the Staging Refresh Utility. Running this utilitywill delete the \staging directory, recreate it, and un-war the "dodeca.war.original" file intothe new \staging directory structure.

2. Now we need to modify the "hibernate.properties" file, located in the \staging\WEB-INF\classes subdirectory. There are two ways to modify the "hibernate.properties" file. Thepreferred method (a.) uses a tool shipped with the Dodeca Framework called the JDBC TestUtility, but it requires that the Java Runtime Environment be installed on your computer. Ifyou do not have or do not wish to install Java on your computer, or if you wish to configuresome of the more advanced Hibernate properties available, you can use the alternatemethod (b.) below.

a. From the start menu or from within the \bin directory, find the shortcut for the JDBC

19

http://www.microsoft.com/downloads/details.aspx?FamilyID=F9992C94-B129-46BC-B240-414BDFF679A7&displaylang=EN



Test Utility and double-click it to launch the utility.

Start by selecting the appropriate database from the dropdown labeled 'DatabasePlatform', and the rest of the form will be populated with some default values.

Update the "Connection URL", "User Name", and "Password" fields so that they reflectthe correct application server, database, user name, and password values for therelational database that you wish to use with Dodeca. Then, press "Test Connectivity" toverify that the connection can be established.

20

If your Dodeca repository was created/configured with support forUnicode characters, depending on your relational database vendor, youmay need to make a few adjustments to the default values generatedby the JDBC Test Utility. See the notes below for vendor-specific details:

Oracle Database: For an Oracle database installed with the AL32UTF8 character set, nochanges to the default values generated by the JDBC Test Utility need to be made.

MS SQL Server: For a Microsoft SQL Server database with Unicode support, simply select'com.appliedolap.dodeca.hibernate.dialect.SQLServerUnicodeDialect' from the HibernateDialect dropdown.

MySQL: For a MySQL schema created with a utf8 collation/character set, you mustupdate the 'Connection URL' property value with the following 'useServerPrepStmts':

useServerPrepStmts=false&UseUnicode=true&characterEncoding=UTF-8

You must use the string '&' as your delimiter, so a complete 'Connection URL' for a MySQL

schema with Unicode support might look like the following line:

21

jdbc:mysql://appserver:3306/dodeca?useServerPrepStmts=false&UseUnicod

e=true&characterEncoding=UTF-8

The results of the connection attempt will be displayed at the bottom of the dialog. Ifthe connection was successful, open the "Tools" menu at the top and select "Updatehibernate.properties".

The "hibernate.properties" file has now been updated to reflect the correct settings foryour relational server and database. You can now quit the application and go to step 3.

b. If you do not wish to use the JDBC test utility, you can open the "hibernate.properties" filelocated in the \staging\WEB-INF\classes subdirectory and modify it to include the propertiesfor your selected database. Typically, there are 5 properties that must be uncommented andmodified to fully configure your database connection.

Below is an example:

22

## MS SQL Server

## NOTE: confirm there are no extra spaces after the password; hibernate does

not trim spaces in passwords

hibernate.dialect org.hibernate.dialect.SQLServerDialect

hibernate.connection.username sa

hibernate.connection.password password

[...]

## MS SQL Server 2005 version

hibernate.connection.driver_class com.microsoft.sqlserver.jdbc.SQLServerDriver

hibernate.connection.url

jdbc:sqlserver://localhost;DatabaseName=dodeca;SelectMethod=cursor

There are many other settings relating to Hibernate that you may need to change based on yourspecific implementation or needs. For example, if you would like to see the SQL that is beinggenerated by Hibernate, you can set the hibernate.show_sql property to true to have the SQLprint to standard system.out locations.

If your Dodeca repository was created/configured with support for Unicode characters, you mayneed to make a few adjustments to the 'hibernate.connection.url' or 'hibernate.dialect'property values. See the notes below for vendor-specific details:

Oracle Database: For an Oracle database installed with the AL32UTF8 character set, noadditional changes need to be made .

MS SQL Server: For a Microsoft SQL Server database with Unicode support, set the propertyvalue of 'hibernate.dialect' to'com.appliedolap.dodeca.hibernate.dialect.SQLServerUnicodeDialect'.

MySQL: For a MySQL schema created with a utf8 collation/character set, you must update the'hibernate.connection.url' property value with the following 'useServerPrepStmts':

useServerPrepStmts=false&UseUnicode=true&characterEncoding=UTF-8

You must use the string '&' as your query string delimiter, so a complete 'Connection URL' for aMySQL schema with Unicode support might look like the following line:

jdbc:mysql://appserver:3306/dodeca?useServerPrepStmts=false&UseUnicode=true

&characterEncoding=UTF-8

23

When you have finished modifying it, save and close the "hibernate.properties" file.

3. If you have configured a database other than SQL Server, you must copy the relevant JDBCdriver jars to the \staging\WEB-INF\lib subdirectory.

4. Locate the "dodeca.properties" file in the \staging\WEB-INF\classes subdirectory. This filecontains servlet settings that configure:

◦ if debug xml is printed to system.out

◦ the import and export directories for your metadata

◦ the service implementation classes for Dodeca services

The printing of debug xml can help you understand the requests and responses between theclient and the metadata server.

The import and export directories are the locations where all metadata can be imported from,or exported to, on your application server. The import and export functions read, or generate,xml files that are portable to different Dodeca servers. All metadata is exportable, and thus, theability to move the metadata from one server to another is a very easy process.

Finally, you may override our default service implementation classes with your ownimplementations on the server side. The pattern for custom implementations is that theygenerally inherit from, and extend, our built-in services through the use of protected methodsput into our code expressly for the purpose of extending the functionality. Such extensionscould be used, for example, to limit the views available to a user or make all views read-only fora limited population of users.

If you implement a custom service, you must compile your custom Java class(es) into a Java jarfile and place that jar file into the \staging\WEB-INF\lib subdirectory. Additionally, you mustchange the class reference for the desired service in the "dodeca.properties" file.

5. Optionally, locate the Hibernate mapping files (*.hbm.xml) located in the \staging\WEB-INF\classes\resource subdirectory. These files contain the mappings used from the server-side Java classes to the actual database tables on the relational server. Further, these filesare used to create the tables and their columns when you update the database schema orcreate the sample application.

Most customers will not need to modify these files.

The 'materialized_clob' datatype, which is the default for 'Character Large OBject', or CLOB,fields is mapped by Hibernate to different field types based on the relational database dialectyou have configured. In spite of this convenience, you may still need to customize how thesemappings work. The following table represents the Columns created by Hibernate with the'materialized_clob' datatype.

24

Hibernate Mapping File Table Column

BinaryArtifact.hbm.xml BINARY_ARTIFACTS ENCODED_ARTIFACT

BinaryArtifact.hbm.xml BINARY_ARTIFACTS ARTIFACT_DESCRIPTION

Comment.hbm.xml COMMENTS COMMENT_TEXT

Comment.hbm.xml COMMENTS CONTEXT

CommentAttachment.hbm.xml COMMENT_ATTACHMENTS ENCODED_FILE

MetadataAuditLogItem.hbm.xml

METADATA_AUDIT_LOG_ITEMS

OLD_VALUE

MetadataAuditLogItem.hbm.xml

METADATA_AUDIT_LOG_ITEMS

NEW_VALUE

Due to differences in how different relational databases handle large string data, the Hibernatemappings may need to be changed for the preceding tables/columns to satisfy the needs of theapplication. For example, in some less commonly used databases, the 'materialized_clob'Hibernate type might map to a 'TEXT' type in the database. However, the 'TEXT' type for thatdatabase might be limited to strings of ~65,000 characters or smaller. This column width isprobably not large enough for some of the binary artifacts you may store there, such as largeExcel templates or lengthy selector lists. To avoid that issue, you could use an alternative columndefinition to allow enough room to store the data. The entire column could be defined like this:

<property name="EncodedArtifact" column="ENCODED_ARTIFACT"

type="java.lang.String" length="2147483647" />

The following table summarizes the mapping file changes necessary by database type:

Database Notes

Oracle No mapping changes are needed.

SQL Server No mapping changes are needed.

MySQL No mapping changes are needed.

DB2 If you use the'com.appliedolap.dodeca.hibernate.dialect.DB2Dialect' Dialect,

no mapping changes are needed.

25

Database Notes

Other Contact Applied OLAP support for guidance.

Locate the "web.xml" file in the \staging\WEB-INF subdirectory. Open and modify the settings inthis file as necessary.

Most customers will not need to modify this file.

6. Optionally, locate the "AppliedOLAP.Dodeca.SmartClient.exe.config.deploy" file in the\staging\smartclient{version} directory. This file can be modified according to the followinginstructions in order to change the backing store used for caching settings in Dodeca:

Backing Store Notes

Isolated Storage (default) The isolated storage backing store utilizes theisolated storage mechanism shipped as part ofthe .NET Framework. This is a good choice formost applications and is set as the defaultbacking store. As it is the default backing store,no further configuration is necessary.

26

Backing Store Notes

Relational Cache Storage The DataBackingStore was added to supportstorage of user settings in a SQL Serverdatabase. It is a good choice for customerswho would like to have their settings persistacross multiple computers. It is also thebacking store that is supported when usingCitrix server in a distributed server farmenvironment. This backing store storessettings by creating files in the ClickOnce DataDirectory.

To configure the DataBackingStore, followthese steps before building your deployment:

1. Locate theAppliedOLAP.Dodeca.SmartClient.exe.config.deploy file in your \staging\smartclient{version}directory.

The filename may bedifferent if you havepreviously renamed your .exeusing the ClickOnce PrepUtility.

2. Open the file in a text editor.

3. Locate the <backingStores> node of the xmland comment out the entire <add> node withthe name attribute "Isolated Storage".

4. Uncomment the entire <add> node with thename attribute "Relational Cache Storage".

5. In the <cacheManagers> node, find the<add> node with the name attribute "CacheManager". In this node, change the value ofthe "backingStoreName" attribute from"Isolated Storage" to "Relational CacheStorage".

6. Locate the <section> node with the nameattribute "dataConfiguration" and uncommentit.

27

7. Locate the <dataConfiguration> node anduncomment it.

The "defaultDatabase"attribute value is"CachingConnection".

8. Locate the <connectionStrings> node anduncomment it, if necessary.

9. Locate the <connectionStrings> child <add>node with the name attribute"CachingConnection". Adjust theaccompanying connectionString attribute tobe a valid .NET connection string for thedatabase where you want to store thesettings.

10. After these steps are complete for therespective backing store, save and close the.config.deploy file.

11. Locate the \docs subdirectory and find theCreateCachingDb.cmd command file and theCreateCachingDatabase.sql file.

12. Edit the CreateCachingDb.cmd file andreplace the value of the -S parameter (i.e.,localhost) with the name of the server youspecified in the connection string above.

13. Save and close the .cmd file.

14. Double-click on the CreateCachingDb.cmdfile to execute the SQL script that builds thenecessary tables.

Backing Store Notes

Data Directory Cache Storage The DataDirectoryBackingStore was added tosupport local storage that uses FIPS compliantalgorithms for hashing and encryption. It isalso a good choice for customers who do notwant to use .NET isolated storage. Further, thisbacking store is a good choice for customerswho would like to encrypt their user settingsusing FIPS compliant AES encryption. Thisbacking store stores settings by creating filesin the ClickOnce Data Directory.

To configure the DataDirectoryBackingStore,follow these steps before building yourdeployment:

1. Locate theAppliedOLAP.Dodeca.SmartClient.exe.config.deploy file in your \staging\smartclient{version}directory.

The filename may bedifferent if you havepreviously renamed your exeusing the ClickOnce PrepUtility.

2. Open the file in a text editor.

3. Locate the backingStores section of the xmland comment out entire <add> node with thename attribute "Isolated Storage".

4. Uncomment the entire <add> node with thename attribute "Data Directory CacheStorage".

5. In the <cacheManagers> node, find the<add> node with the attribute name="CacheManager". In this node, change the attributevalue for the backingStoreName from"Isolated Storage" to "Data Directory CacheStorage".

28

After the steps are completed for the backingStore you wish to use, save and close the modified"AppliedOLAP.Dodeca.SmartClient.config.deploy" file.

8. Locate the shortcut for the "ClickOnce Prep Utility" on the Start Menu or find it in the \binsubdirectory. Double-click it to run the ClickOnce Prep Utility application. In this utility, youwill modify the property settings for your Dodeca system. At a minimum, the"DeploymentUrl" property must be updated to reference the applicationserver/port/context where the completed WAR file will be deployed.

The ClickOnce Prep Utility will look something like this:

The Deployment URL should include the application server name and portwhere the Dodeca servlet will be deployed. Its value will most likely vary fromthe value displayed in the screenshot above.

The Certificate Password for the "dodeca_temp.pfx" key provided by AppliedOLAP is "password".

29

Once the property grid entries have been modified to suit your needs, you canuse the ClickOnce Prep Utility to save the modified settings. To do this choose"Save Setting As" from the "File" menu. Enter the name under which you wantto save your settings and press "OK".

9. When you are satisfied with your settings, compile the "dodeca.war" file by pressing the"Build Deployment" button at the bottom of the dialog. While the servlet is being compiled,its progress will be reported in the bottom panel:

Once the servlet is finished being compiled, the finished "dodeca.war" will be placed in the\servlet directory.

Dodeca WAR File DeploymentOnce you have compiled the WAR file, you have to deploy it to your application server. The WARfile deployment procedure varies by application server manufacturer. This section of the guideincludes detailed instructions for a variety of commonly-used servers.

30

Deployment to Apache Tomcat

Apache Tomcat is a popular, open-source application server created by the Apache Foundation.Many companies, including Hyperion, ship Apache Tomcat as a default application server fortheir applications.

WAR File Deployment

To deploy the WAR file in Apache Tomcat, follow these steps:

1. Copy the dodeca.war file to the \webapps directory of your Apache Tomcat deployment.

2. Start the Apache Tomcat application server. The dodeca WAR file will be unpacked anddeployed into the \webapps\dodeca directory.

Deployment to Oracle WebLogic

Oracle WebLogic application server is available for several different operating systems. Theinstructions below were created for Oracle WebLogic Server 11g.

WAR File Deployment

To deploy the WAR file in Oracle WebLogic, follow these steps:

1. Open the Oracle WebLogic Server Administration Console.

2. In the 'Change Center' panel at the top left, click the 'Lock & Edit' button.

3. Click 'Deployments' in the left-hand 'Domain Structure' panel.

4. In the 'Summary of Deployments' panel that opens, click the 'Install' button.

5. Navigate to and select the dodeca.war file on your file system.

6. Click 'Next'.

7. Select 'Install this deployment as an application' and click 'Next'.

8. Click 'Next'.

9. For versions of WebLogic provided with Essbase 11.1.2 and higher, if you are installing theDodeca servlet to the EPMSystem domain (recommended), you will be given the option to'Select deployment targets' for the installation. Under the 'Clusters' section of the form, for'AnalyticProviderServices', select 'Part of the cluster' and 'AnalyticProviderServices0'.

10. Review the information and click 'Finish'.

11. When the installation has completed, click the 'Activate Changes' button in the 'ChangeCenter' panel at the top left.

31

To start the application in Oracle WebLogic, follow these steps:

1. From the 'Deployments' panel, select check box next to the Dodeca application.

2. Click the 'Start' button and choose to start servicing all requests to the web application.

3. Click 'Yes' to confirm that you want to start the web application.

Deployment to Oracle Application Server

The Oracle application server is available for several different operating systems. Theinstructions below were created for Oracle 10.1.3.1.0.

WAR File Deployment

To deploy the WAR file in the Oracle application server, follow these steps:

1. Login to the Application Server Control for your instance of the application server.

2. Access the OC4J instance for your application server by clicking on it.

3. Click on the 'Applications' link.

4. Click on the 'Deploy' button.

5. Click 'Browse' and navigate to the dodeca.war file on your file system.

6. Click 'Next'.

7. Type in 'Dodeca' as the Application Name. Leave the 'Context Root' as 'dodeca' and click'Next'.

8. Under 'Deployment Tasks', click the 'Configure Class Loading' pencil icon.

9. Under 'Configure Web Module Class Loaders', check the 'Search Local Classes First' checkbox.

10. Click 'OK'.

11. Click 'Deploy'.

12. Once the Dodeca application has been successfully deployed, click 'Return'.

Deployment to IBM WebSphere

The IBM WebSphere application server is available for several different operating systems. Theinstructions below were created for IBM WebSphere 6.1.0.0.

32

WAR File Deployment

To deploy the WAR file in IBM WebSphere, follow these steps:

1. Select and expand 'Applications' located on the left hand side of the admin console.

2. Select 'Install New Application'.

3. Click 'Browse' and navigate to the dodeca.war file on your file system.

4. Select the dodeca.war file and press 'Open'.

5. Enter "/dodeca" for the context root.

6. Leave the radio button for 'Prompt me only when additional information is required'selected.

7. Click 'Next'.

8. Click 'Next' under the section entitled 'Select installation options'.

9. At 'Map modules to servers', check the 'Select' box next to dodeca.war Module, then click'Next'.

10. At 'Map virtual hosts for Web modules', check the 'Select' box next to the dodeca.war Webmodule, then adjust the 'Virtual Host' drop down box to meet your needs.

11. Click 'Next'.

12. Review the information and click 'Finish'.

13. When the application has completed the installation, click 'Save'.

To start the application in IBM WebSphere, follow these steps:

1. Select and expand 'Applications' located on the left hand side of the admin console.

2. Click 'Enterprise Applications'.

3. Check the 'Select' box next to the Dodeca application and then click 'Start'.

Deployment to IBM WebSphere CE

IBM WebSphere CE is an IBM branded distribution of Apache Tomcat. Deployment to IBMWebSphere CE is very similar to deployment to Apache Tomcat.

WAR File Deployment

To deploy the WAR file in IBM WebSphere CE, follow these steps:

1. Copy the dodeca.war file to the \deploy directory of your IBM WebSphere CE deployment.

2. Start the IBM WebSphere CE application server. The dodeca WAR file will be unpacked and

33

deployed into the \deploy\dodeca directory.

Deployment to JBoss

JBoss is a supported and branded distribution of Apache Tomcat. Deployment to JBoss is verysimilar to deployment to Apache Tomcat. These instructions were created for JBoss 4.0.4.

WAR File Deployment

To deploy the WAR file in JBoss, follow these steps:

1. Copy the dodeca.war file to the \default\deploy directory of your JBoss deployment.

2. Start the JBoss application server. The dodeca WAR file will be unpacked and deployed intothe appropriate deployment directory.

Dodeca-Essbase WAR File PreparationIf you wish to take advantage of Essbase Connectivity in Dodeca, you will need to deploy thecorrect version (or versions) of the Dodeca-Essbase servlet provided to you by Applied OLAP.This WAR file (dodeca-essbase.war) is tailored specifically to the version of Essbase you wish toconnect to and will be located in the \essbase\\{Essbase Version}\ subdirectory of your DodecaFramework installation. Depending on the setup of your Essbase environment, you may need tomake a few modifications to the dodeca-essbase.war to ensure that it works properly.

If the Dodeca-Essbase servlet will be deployed on the same physical machineas the Analytic Provider Services instance and the APS version is 9.3.1 orhigher, you do not need to modify the dodeca-essbase.war file. Mostcustomers will not need to modify the dodeca-essbase.war file.

If you need to connect to an Essbase version lower than 9.3.1, you will need toobtain a copy of the Dodeca-Essbase Classic servlet from Applied OLAP.

If you need to modify the Dodeca-Essbase servlet for your environment, follow these steps:

1. Find the dodeca-essbase.war file located in the \essbase\\{Essbase Version} subdirectorythat corresponds to the version of Essbase you wish to connect to.

2. Because the Dodeca-Essbase servlet is packaged as a WAR file, you must un-war it beforeany changes can be made. This can be accomplished in a couple of different ways. Thetraditional method (a.) requires that you un-war and re-war the dodeca-essbase.war fileusing 'jar', the Java ARchive Tool. This tool is provided only with the Java Development Kit,so if you do not have or do not wish to install the JDK on your computer, you should use the

34

WinRAR/7-Zip method (b.) below, which only requires that a file archiver supporting WebArchives be installed. We recommend WinRAR (shareware) or 7-Zip (freeware).

a. Java Archive Tool Method

i. Open a command prompt and navigate to the \essbase\\{Essbase Version} directorycontaining the dodeca-essbase.war you wish to modify.

ii. Un-war the servlet to a known location using the following command:

jar –xvf dodeca-essbase.war

iii. Modify the relevant property files as specified in steps 3-4 below.

iv. Navigate to the location where you un-warred the servlet.

v. Re-war the servlet using the following command:

jar –cvf dodeca-essbase.war WEB-INF META-INF

b. WinRAR/7-Zip Method

i. Using a file archiver that supports Web Archives (like WinRAR or 7-Zip), open thedodeca-essbase.war that you wish to modify.

ii. Modify the relevant property files as specified in steps 3-4 below.

To modify a property file without un-warring and re-warring theentire servlet, simply double-click the file from within the archiver’sexplorer pane, make the required changes using the default editor(usually notepad), and then save the changes to the file. When youreturn to the archiver, you will be prompted to update the file inthe archive.

iii. After the dodeca-essbase.war archive has been updated, close the file archiver.

3. Open the \WEB-INF\classes\dodeca-essbase.properties file in a text editor and locate the ""property at the top of the file. The relevant section should look like this:

## Default URL to use for APS connections

#aps.url=http://localhost:13080/aps/JAPI

aps.url=embedded

4. You will need to modify the value of "aps.url" based on one of the following scenarios:

35

http://www.rarlab.com/download.htm

http://www.7-zip.org/download.html

a. For servlet instances where the Dodeca-Essbase servlet will be on the same physicalmachine as the Analytic Provider Services instance and the APS version is 9.3.1 or higher,the default "aps.url" property value should be used:

embedded

b. For servlet instances where the Dodeca-Essbase servlet will NOT be on the same physicalmachine as the Analytic Provider Services instance and the APS version is 9.3.1 or higher, the"aps.url" property value should be changed to:

http://<APS machine name>:13080/aps/JAPI

c. For all servlet instances where the Analytic Provider Services instance is lower than 9.3.1 orEssbase Deployment Services is used, see the documentation provided with the Dodeca-Essbase Classic servlet.

Essbase Outline Relational Caching

Caching Essbase outline information relationally provides many benefits, including betterperformance and greater flexibility in creating reports and input templates. The performancegains associated with Essbase outline relational caching are due to fact that one of the slowerportions of the Essbase technology stack is the retrieval of outline information via the EssbaseAPIs. Relational technology is generally very fast, so having the most frequently used Essbaseoutlines available in a relational database increases performance in certain situations. Relationalcaching of Essbase outlines is disabled, by default.

If you wish to enable relational caching of Essbase outlines in Dodeca, you will need to modifytwo files within the "dodeca-essbase.war" file using either of the modification proceduresoutlined in the previous section:

1. Open the \WEB-INF\classes\dodeca-essbase.properties file in a text editor and locate the"outline.relational.cache.enabled" property near the top of the file. The relevant sectionshould look like this:

Specifies whether relational cachestorage is turned on or off. If itis turned off then the persistence.xml is

36

not parsed or loaded (it may be read bydefault from the persistenceAPI).

Should only be used to increaseperformance at the cost of building theoutline into a separate database.

If enabled, WEB-INF\classes\META-INF\persistence.xml needs to beproperly configured.

outline.relational.cache.enabled=false

2. Above and below the "outline.relational.cache.enabled" property, modify the set ofproperties matching the "cache." and "relational.cache." naming conventions. The onlyproperty that must be modified in addition to "outline.relational.cache.enabled" is the"outline.info.*" property, which must be added for each Essbase connection to be cached inthe following form:

## This is a list of CACHED_OUTLINE_INFOS to add into the database on

startup

## (if they don't already exist)

## The format is:

## outline.info.#=ID|APPLICATION|CUBE|SERVER|URL|USERNAME|PASSWORD

## (The number '#' should increase from 0)

## Example:

## outline.info.0=example.sample.basic|Sample|Basic|essbase11121|embedded|

admin|password

outline.info.0=sample.basic|Sample|Basic|essprod01|embedded|admin|password

outline.info.1=demo.basic|Demo|Basic|essprod01|embedded|admin|password

3. Navigate to the \WEB-INF\classes\META-INF directory and rename the file"persistence.xml_disabled" to "persistence.xml".

37

4. Open the renamed \WEB-INF\classes\META-INF\persistence.xml file in a text editor andmodify the "hibernate.connection.*" properties so that they match the properties used inthe earlier-modified "hibernate.properties" file, located in the \staging\WEB-INF\classessubdirectory of your Dodeca Framework Installation. The instructions for determining thecorrect hibernate property values can be found at step 2. b. in the earlier section "Step-by-Step Instructions to Create the WAR File".

5. If you have configured a database other than SQL Server, you must copy the relevant JDBCdriver jars to the \WEB-INF\lib directory of the "dodeca-essbse.war" file.

Dodeca-Essbase WAR File Deployment

Next, you will need to deploy the Dodeca-Essbase servlet (dodeca-essbase.war) which you justmodified. It should be deployed in the same manner as the dodeca.war file was earlier,according to the instructions provided for your application server.

For example, to deploy the WAR file in Apache Tomcat, simply copy the appropriate version ofdodeca-essbase.war file to the \webapps directory of your Apache Tomcat deployment and startthe application server. The dodeca-essbase WAR file will be unpacked and deployed into thewebapps\dodeca-essbase directory.

If you wish to deploy multiple versions of the Dodeca-Essbase servlet in orderto allow Dodeca to connect to multiple versions of Essbase, you will need togive each servlet a unique filename, such as "dodeca-essbase-9.3.1.war" or"dodeca-essbase-11.1.2.war". This allows the application server to distinguishbetween servlets when a request is made by Dodeca. If you need anyadditional information, please contact Applied OLAP for support.

Completing the Setup - The ApplicationSetup UtilityIf you are an administrator performing an initial installation of Dodeca at your company, you willneed to prepare the relational database store used by Dodeca. The easiest way to assureDodeca is configured properly is to create and use the sample application that is shipped withthe Dodeca Framework. To create the sample application, follow these steps:

1. Launch the "Application Setup Utility" from the Start Menu by double-clicking its entryunder Applied OLAP\Dodeca Framework 8.0.0.0000\Utilities.

2. Enter your application server information into the appropriate fields. This information willmatch the DeploymentUrl parameter from the ClickOnce Prep Utility.

38

#step-by-step-instructions-to-create-the-war-file

#step-by-step-instructions-to-create-the-war-file

3. Press 'Next' and the Application Setup Utility will examine the database to look for therequired tables. If this is the first time Dodeca has been configured to run against therelational database repository, the database schema validation will fail. When this happens,press 'Update Database Schema' and Dodeca will create the necessary tables in thedatabase.

39

The Schema update will drop and recreate all of the tables Dodeca requires. Ifthe schema tables already exist and have data in them, that data will be lost.Unless this is a first-time installation of Dodeca, we recommend backing upthose tables before proceeding.

4. Confirm the update database schema by pressing 'OK' and then press 'Next'.

If you press 'Back' and then 'Next' again after updating the database schema,the server will test your table structure again.

5. Once the tables are present, the next step is to enter a unique tenant keyword. The unique

40

tenant keyword typically used for the sample application is 'SAMPLE'. Enter this keywordinto the appropriate textbox and press 'Next'.

By convention, tenant keywords and application IDs are normally expressed inall capital letters with only alphanumeric characters and no spaces.

6. Next, import the metadata into the database by pressing 'Import Metadata from Local ZipFile'.

41

7. Locate the sample.zip file in the \metadata subdirectory and press 'Open'.

8. On the 'Import Metadata from Local Zip File' form, click the checkbox in the title row of thegrid to select all of the metadata in the sample.zip file.

42

9. Press 'Import' and the Application Setup Utility will populate the tables in the database withthe appropriate metadata.

10. Once the import is complete, press 'Close' to exit the 'Import Metadata from Local Zip File'form and press the 'Next' button to proceed to the next screen.

11. Optionally, choose a module to update. Modules are Dodeca extensions that are stored inthe metadata. Normally you will not need to do anything at this step unless directed byApplied OLAP technical support personnel, so go ahead and press 'Next'.

43

12. Click the radio button entitled 'Select an existing application from tenant "SAMPLE"' andselect the 'ADMIN' Application ID to view, then click 'Next'.

44

13. No modifications need to be made to the 'ADMIN' application settings. Press 'Next'.

14. At this point, you have completed the sample application setup. To install the application,you will use the ClickOnce URL.

45

15. Click on the URL in the dialog to install the Dodeca client on your computer and start theADMIN application. Initially, the 'Launching Application' dialog will display while ClickOncedeployment determines if the Dodeca application has been installed on your desktop.

If you wish to launch Dodeca using a browser other than Internet Explorer, youwill need to install a ClickOnce extension/plugin. For Firefox, see the Microsoft.NET Framework Assistant extension. For Chrome, see the third-partyClickOnce for Google Chrome extension.

If the Dodeca application has not yet been run on your desktop, you will see the followinginstallation dialog.

46

https://addons.mozilla.org/en-US/firefox/addon/microsoft-net-framework-assist/

https://chrome.google.com/webstore/detail/eeifaoomkminpbeebjdmdojbhmagnncl

Press the 'Run' button to install and run the Dodeca client.

The 'Publisher' field will reflect the name of the organization who owns thedigital signing key. If you used the temporary key provided by Applied OLAP,the 'Publisher' value will be 'Unknown Publisher' (because it is a self-signedkey).

The installation will proceed and update its progress in the dialog. The amount of time requiredto install Dodeca on a client workstation will vary based on your network speed.

This installation occurs only the first time the application is run.

47

Upon completion of the download/installation, the Dodeca splash screen will be displayed,indicating the startup of the Dodeca Smart Client.

Congratulations! You have successfully launched the Dodeca Smart Client.

16. Once in the ADMIN application (assuming you have the Essbase Sample/Basic andDemo/Basic sample databases available), you need to configure the location of your Essbaseservices. To configure those services, select 'Admin' from the menu, and then select 'EssbaseConnections' to open the Essbase Connections metadata editor.

48

17. Select the 'Sample Basic' connection and modify the 'ServletPath' and (Essbase) Serverproperties to point to the proper location.

18. Once you have modified the properties, click the 'Commit' button to store the changes in

49

the metadata repository on the server.

19. Next, test the functionality by opening the 'Adhoc Analysis' view which is configured to usethe Sample Basic connection. To open the view, click on the 'Adhoc' category in the ViewSelector pane to expand open the 'Adhoc' category. Then click on the 'Adhoc Analysis' viewto launch it.

50

20. Enter your username and password and press 'OK'. The 'Adhoc Analysis' view will connect toEssbase and bring back the initial retrieve.

Now that you have successfully tested your client and server setup, you can start authoring yourown applications. The first thing you will need to do is choose a tenant keyword for use with

51

your application. The tenant key is used to segregate sets of applications within the metadataserver. For example, if you intend to implement a forecasting application and a retailmerchandise planning system for your company (ABC, Inc.), you may want to use multipletenant keys to separate the metadata for your different applications. You could, for example,decide to use ABCForecast and ABCMerchPlan for your tenant keys. When you create yourapplications, the metadata for the application(s) you create will be keyed in the database byeach of these values. These applications are completely isolated from each other even if youcreate and access them using the same Dodeca metadata server.

Once you have decided upon a tenant key, you can re-run the Application Setup Utility to createthe new tenant and import seed metadata to start your application. Typically, you will importthe smart client applications, a hierarchy, and the toolbar configurations from the MetadataStarter Kit, located under the \metadata subdirectory as a starting point for your nextapplication. To start building your application for a specific tenant, use the ClickOnce URLgenerated by the Application Setup Utility to pass your chosen tenant key to the Dodecametadata servlet, starting a Dodeca session. The tenant key is read from the query stringarguments and passed to the metadata servlet as part of each request.

ClickOnce Deployment from an HTMLLinkAfter you have built your application, you must deploy the application to users. Most customerswill want to deploy Dodeca to their end users using an HTML link on a web page. An example ofthe complete launch is below:

http://appserver:13080/dodeca/smartclient/AppliedOLAP.Dodeca.SmartClient.application?a=ADMIN&t=SAMPLE

The above URL must be typed on a single line.

You would use your tenant key in place of the 'SAMPLE' tenant in the above example. You willalso use an application key you create in place of the sample application ID 'ADMIN'.

Local Client Installation andConfigurationThe full Dodeca client is also installed on the desktop of the machine that installs the DodecaFramework using the executable installer. The client installation, consisting ofAppliedOLAP.Dodeca.SmartClient.exe and all of its dependencies, is installed with the DodecaFramework in the \bin\Dodeca subdirectory. The client installation is normally used only by

52



customer developers who wish to extend the Dodeca framework using Visual Studio. Before youcan use the client to start in this way, you must configure command-line arguments that theclient needs to communicate with the metadata server.

The following command-line arguments are used by Dodeca:

Argument Usage Mandatory

/a (or /app) Defines the application to run(which defines, among otherthings, the toolbars present inthe application).

Y

/p (or /path) Defines the URL where themetadata servlet is available.

Y

/t (or /tenant) Defines the Tenant key, whichmaintains metadataseparation between differentinternal (or external)customers.

Y

/u (or /user) Defines the username to beused for metadata updatelogging (default=WindowsLogin name).

N

You must create or modify a shortcut to the Dodeca launch executable in order to include thecommand line arguments. An example of a complete command-line string is below:

C:\Program Files\Applied OLAP\Dodeca Framework

{version}\bin\Dodeca\AppliedOLAP.Dodeca.SmartClient.exe" /a 1 /t SAMPLE /path

http://appserver:13080/dodeca/metadata-service

The above command must be typed on a single line.

The Dodeca Accelerator UtilityThe Dodeca Framework and Smart Client are shipped with a command line utility,Accelerator.exe, that dramatically reduces Dodeca’s startup time, as well as improving the

53

overall responsiveness of its user interface. The Accelerator is packaged with every ClickOncedeployment of Dodeca and needs to be run one time per Dodeca version installed on the clientmachine. The Accelerator does not run as a service, but rather, performs a one-time series ofenvironment-specific optimizations, which includes recompiling each Dodeca assemblyspecifically for the client machine. Our own internal benchmarks have consistently shown 50-75% decreases in application startup time, as well as 30-50% increases in UI operationperformance.

As the Accelerator modifies the client machine beyond .NET Isolated Storage, it does requireadministrative privileges in order to run. To run the Accelerator on a development machinewhere you have administrative privileges, follow these steps:

1. Open a command prompt and navigate to the \bin\Dodeca subdirectory of your DodecaFramework installation.

2. Type the following command and then press enter:

Accelerator.exe -ign

Depending on the processor speed/cores and the amount of RAM installed onyour system, this process may take up to 20 minutes to complete. Therelatively long completion time of this installation process is due to the factthat the Accelerator recompiles each Dodeca Assembly.

3. Once the process is complete, restart Dodeca.

From this point forward, whenever you launch an instance of the Dodeca Smart Client, yoursystem will preferentially use the natively-compiled assemblies generated by the Acceleratorinstead of the assemblies shipped with the Dodeca Framework. The Dodeca assemblies havealso been installed into the system-wide .NET assembly library, allowing the .NET CLR to bypasshash verification of each assembly at startup. This improves startup time and reduces theamount of CPU the Dodeca Smart Client consumes at launch time.

To uninstall the recompiled assemblies and reverse the system changes made by the Acceleratoron a development machine where you have administrative privileges, follow these steps:

1. Open a command prompt and navigate to the \bin\Dodeca subdirectory of your DodecaFramework installation.

2. Type the following command and then press enter:

Accelerator.exe -ugn

54

This command will uninstall only the assemblies of the current Dodeca version.To uninstall all Dodeca assemblies previously installed by the Accelerator,regardless of version, use the command line argument '-ucgn'.

For additional information about the Dodeca Accelerator, as well as some common installationstrategies for production environments, refer to the section of the Dodeca Administrator’sGuide titled "The Dodeca Accelerator Utility".

Contact UsFor further information, contact us at:

Applied OLAP, Inc.120 Holmes Avenue NE, Suite 405Huntsville, Alabama 35801256-885-4371

[email protected] www.appliedolap.com

55

mailto:[email protected]

https://www.appliedolap.com

Documents

Dodeca Installation Guide · 2021. 6. 12. · The persistence engine creates SQL statements for your selected relational database engine and communicates with the 3. ... Configure