OpenI assumes you have at least a J2EE server and an OLAP server (that can accept XMLA requests) installed and ready. For J2EE, we have tested OpenI on Tomcat 6.0.16 and JBoss 4.2.2, and for OLAP servers, we have tested on Mondrian 2.4.2, Microsoft Analysis Services (MSAS) 2000, and SQL Server Analysis Services (SSAS) 2005. (Click here for instructions on setting up OLAP Servers and their XMLA interfaces, and click here for a more comprehensive list of system requirements)

• OpenI assumes you have the following roles defined in your J2EE security schema. If you don't have them, add them before you access OpenI.
• openi (role to distinguish users who have access to the OpenI web application)
• app_admin (role to distinguish users who have full administrative access to the OpenI web application). Please see "Application Security" for security configuration details.
• If you are using tomcat default security, this can be done by editing <tomcat_home>/conf/tomcat-users.xml. If using JBoss default security, you can edit users.properties and roles.properties in <jboss_home>/server/default/conf (if those files are not there, you can create new files). Consult JBoss documentation if you are using a different flavor of security definitions, the bottom line is that OpenI will expect at least one user who belongs to the security roles of openi and app_admin for you to be able to log into OpenI and configure it.
• You may need to restart your J2EE server after  changing security configuration.

• If you are deploying on tomcat, download and unzip openi-2.0-alpha-tomcat.zip into an empty folder. If you are deploying on JBoss, or any other J2EE server, download and unzip openi-2.0-alpha-jboss.zip into an empty folder
• Copy the openi.war into the web application deployment folder of your J2EE server . For example, if you are running tomcat as your J2EE server on Linux:
• cp openi.war <tomcat_home>/webapps/
• Similarly, if you are running JBoss as your J2EE server on Linux (assuming "default" configuration):
• cp openi.war <jboss_home>/server/default/deploy

• Open browser to: http://localhost:8080/openi
• Log in using the user login you have created that belongs to openi and app_admin security roles (default security assumes you have an administrator login of "openiadmin/passwd" defined in your J2EE security database, and that it belongs to the security groups or roles openi and app_admin. Please see Application Security for security configuration details)
• When you log into OpenI for the first time as an administrator, OpenI will detect that you don't have a "projects folder" (when you create new reports and analyses using OpenI, they need to be stored on a special folder on the OpenI server called the "Projects Folder". A "project" is a collection of analyses belonging to a particular category like a client, or a department, etc., more on projects folder is here). OpenI will offer to create you a default "projects folder" and deploy a the sample "Foodmart 2000" application to this folder.
  
  
  
  
  OpenI creates this folder in the home directory of the user under whose privileges the J2EE server is being run.
  
  
• If you have a local Mondrian OLAP Server or a Microsoft SSAS 2005 that contains their default OLAP database (Foodmart 2000), once you have completed the abovementioned steps, you should see a screen of the sample application like this
  
  
  
  
  If you need to connect to a different OLAP database or connect to an OLAP server on a different machine, you need to configure your OLAP data source definition by going into "Preferences > Data Sources". More details on configuration of data sources are here
  
• Consult the Users Guide for more information on navigating/configuring the dashboard and the analysis views.

• Operating Systems: Independent
  Since OpenI is completely Java-based, it will run on any operating system that has a compatible JVM
• Java Runtime : Requires Version 1.5 or Higher
  Tested on Sun J2SE version 1_5_0_14 and 1.6.0_07. For JBoss deployment, we have tested with JBoss 4.2.2.GA and Tomcat 6.0.16
• OLAP Server: Supports Mondrian, Microsoft SSAS 2005, and MSAS 2000
  You can use OpenI with any XMLA-compliant OLAP server. If you are planning to use OpenI with SSAS 2005 or MSAS 2000, you need to have the XMLA interface for Microsoft Analysis Services up and running. See details on setting up XMLA interface in "Set Up XMLA Interface for OLAP Servers" section.
• Database (optional): Any Relational Database Server
  Although the default installation of OpenI doesn't directly connect to a database, the OLAP servers will require at least one database instance. While Microsoft Analysis Services uses its native drivers to connect to the database, Mondrian uses JDBC drivers to connect to the database, so you need databases with JDBC support if using Mondrian.

You will probably want to create your own build of OpenI from the source code -- mostly just for the fun of it, or sometimes it becomes a necessary evil if you want to manipulate the jars included with OpenI's WAR, or if you make some customizations either in the code or in any of the J2EE server-specific configuration files. OpenI works with any web container supporting Java Servlet 2.4 specs. However, each servlet container provides a unique set of jars in their jar library by default. You should not include any jars in OpenI's WAR that are already provided by the container in order to avoid version conflicts and ambiguity. For example, JBoss 4.2.2.GA provides JSF library jars by default, so the openi.war you deploy on JBoss 4.2.2 should not contain these JSF library jars (in fact, the JBoss-specific distro we have created, openi-2.0-alpha-jboss.zip, specifically excludes these jars).

Here are the steps to build OpenI from source:

• You will need Apache Ant and JDK version 1.5 or greater. You also need a command-line version of Subversion  client tool installed (download it from http://subversion.tigris.org/ and make sure binary executable path is set in environmental variable)
• Checkout source sf.net svn repository  into an empty folder:
  svn checkout https://openi.svn.sourceforge.net/svnroot/openi/openi_2_0/trunk
• Compile OpenI using Ant from command-line interface to produce openi.war
• cd build
• To build a WAR to deploy on Tomcat
• ant clean
• ant dist.tomcat to produce WAR file compatible on Tomcat 6.0.x
• To build a WAR to deploy on JBoss (or any other J2EE servers)
• ant clean
• ant dist.jboss (this produces WAR file compatible on JBoss 4.2.2 GA and this uses JBoss' authentication technique for user authentication)
• There also exists a special set of build instructions to create a WAR for JBoss that includes security definitions to use the hsqldb database contained within JBoss as the security database (more on this configuration is here)
• ant dist.jboss.security (this produces WAR file compatible on JBoss 4.2.2 GA and uses hsqldb database contained within JBoss for user authentication)
• This produces an openi.war file under a dist folder for J2EE web deployment
• Now, follow the steps in "Quick Start" section to set up your environment and deploy the OpenI web application.

SSAS 2005 installation is bundled with SSAS 2005 XMLA service. To enable the XMLA interface of an SSAS 2005 instance, you need to follow these steps (in the exact order):

• We are assuming you have already installed IIS and installed Microsoft SQL Server 2005 with SQL Server Analysis Services selected.
• Copy the contents of the <SQL_INSTALL_FOLDER>\OLAP\bin\isapi directory into the folder you would like to become the base for the virtual directory in IIS.(e.g. C:\inetpub\wwwroot\olap)
• Create an application pool:
  • Go to IIS Management Console
  • Right-click the Application pools to open the shortcut menu and select New, than Application Pool.
  • Name the application pool. e.g. olap
• Create a virtual directory
  • Go to IIS Management Console
  • Right-click the Web site to open the shortcut menu and select "New", than "Virtual Directory"
  • Name the virtual directory.(e.g. olap). The "Content Directory" should point to the folder you have just created. (e.g. C:\inetpub\wwwroot\olap)
  • Make sure that under the Access Permissions, only the second check box, "Run Scripts (Such as ASP)" is selected
• Set up virtual directory properties
  • Right-click your virtual directory node and select Properties from the menu.
  • In virtual directory tab:
    • Choose the application pool as one you have just created.
    • Click the Configuration button. It will show "Application Configuration" Dialog
    • Click on add button
    • In the Executable option, enter the full path name to msmdpump.dll. (e.g. C:\wwwroot\olap\msmdpump.dll)
    • Enter .dll in the Extension text box.
    • Click the OK button to accept the settings
  • In "Directory Security" tab:
    • Click to Edit on Authentication and access control. It will show "Authentication Method" dialog box
    • Enable Anonymous Access
  • Set up Web Service Extension :
    • Go to IIS Management Console, right-click the "Web Service Extensions" node and select "Add new Web Service Extension".
    • Name the extension.(e.g. olap)
    • Click the Add button and provide a path to your msmdpump.dll file
    • Check the "Set Extension Status" to "Allowed" check box.
• Verify installation: go to http://localhost/olap/msmdpump.dll you should see something like this:
  
  <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body> <soap:Fault xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <faultcode>XMLAnalysisError.0xc10e0002</faultcode>
  <faultstring>Parser: The syntax for 'GET' is incorrect.</faultstring>
  <detail>
      <Error ErrorCode="3238920194" Description="Parser: The syntax for 'GET' is incorrect." Source="Unknown" HelpFile=""/>
  </detail>
  </soap:Fault>
  </soap:Body>
  </soap:Envelope>
  
• This means the XMLA interface is set up correctly.

OpenI communicates with MSAS 2000 OLAP server, using XMLA SDK version 1.1. To enable the XMLA interface of an MSAS instance, you need to follow these steps (in the exact order):

• See Instructions at msdn site
• We are assuming you have already installed Microsoft Analysis Services. If not:
  • Install SQL 2000 (optional) and apply Service Pack 3a or latest.
  • Install Microsoft Analysis Services (MSAS) and apply Service Pack 3a or latest.
• On the machine where MSAS is installed, install IIS 6.0
• Install Microsoft XML Core Services (MSXML). Use MSXML 4.0 for the 1.1 version of the XML Download here
• Install XML for Analysis SDK 1.1 Download here
• Create virtual directory (/xmla), using path to C:\Program Files\Microsoft XML For Analysis SDK\Isapi
• Enable web service extension(name = xmla, path to C:\Program Files\Microsoft XML For Analysis SDK\Isapi\mdxisapi.dll
• Verify installation: go to http://localhost/xmla/msxisapi.dll you should see something like this:
  
  <?xml version="1.0" ?>
  - <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
      SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  - <SOAP-ENV:Body>
  - <SOAP-ENV:Fault>
    <faultcode>XMLAnalysisError.88BA0800</faultcode>
    <faultstring>The Web Service supports only the POST operation.</faultstring>
    <faultactor>XML for Analysis Provider</faultactor>
  - <detail>
  - <faultstring>
    <Error ErrorCode="2293893120"
           Description="The Web Service supports only the POST operation."
           Source="XML for Analysis Provider" />
    </faultstring>
    </detail>
    </SOAP-ENV:Fault>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>
  
• This means the XMLA interface is set up correctly. 

Once OpenI and the appropriate XMLA provider interface are installed and running, you can start using OpenI sample project (Foodmart) if you have a local Mondrian OLAP Server or a Microsoft SSAS 2005 that contains their default OLAP database (Foodmart 2000). However, if you need to connect to a different OLAP database or connect to an OLAP server on a different machine, don't forget to configure the OpenI data source definitions. A data source definition defines the XMLA interface URL that OpenI will use to discover and query the OLAP cubes. To do this:

• Go to http://localhost:8080/openi
• Select a project in project selection page (OpenI autoselects the default project if there is single project available for the user. In such case it will bypass the project selection page)
• Go to Preference | Data Sources
• There are two default OLAP data source definitions provided with OpenI: msas (which defines a local instance of SSAS 2005) and mondrian (defines a local instance of Mondrian). In the OpenI sample project Foodmart, all the analyses in the "Mondrian" folder expect their data from the mondrian data source, and the ones in "MSAS" expect from msas data source. If your default OLAP databases are in a different location, you can simply change the definitions for these 2 data source definitions. Or if you are building your own analyses by pointing to your own OLAP databases, you can create new OLAP data source.
  
• Change the data source URL with the actual URL and select the OLAP catalog for "foodmart". Use following data source URL for each XMLA provider:

  • MS XMLA 2000 : http://<xmla server url>/xmla/xmla/msxisapi.dll
  • SSAS 2005 XMLA : http://<xmla server url>/olap/msmdpump.dll
  • Mondrian : http://<xmla server url>:8080/mondrian/xmla (assuming mondrian war context name is "mondrian" and server is running on port 8080

OpenI uses the concept of projects to define a specific collection of reports, analyses, and even documents. Each project has its own look-and-feel definitions, list of reports, and security hierarchy. In fact, this concept flows over from our own real-life implementation of OpenI – where we serve different clients from a single OpenI instance and each client needs their own space carved out within the OpenI instance. So, for example, when client A accesses the OpenI URL, they only see their projects, while client B sees a completely different list of projects, and so on. We feel that this concept is more universal than just in the case of different clients needing to see separate list of projects. For example, projects can be department-specific, where within an organization, you have an “accounting” project with accounting related reports, a separate “marketing” project with marketing related reports, and so on. That way, you separately setup access rights and administration separately for each project so accounting can’t see marketing reports and vice-versa.

The default binary distribution contains one project called "foodmart". OpenI automatically creates the sample project contents into "/openi-projects" folder, if it unable to find any project folder specified at startup.

To create a new project, you can simply make a copy of the "foodmart" folder under "open-projects" and rename it (project name must be unique). Each project has the following contents:

• project.xml -- this has project-specific properties, most of them are configurable via the "Administration - Manage Project" link on the OpenI site.
• images -- folder for project-specific image files
• contents/public -- folder for "public" analyses, i.e. analysis that are visible to all users that have access to the project
• In addition, there is a folder for each user to store their "private" analyses. These analyses are only visible to the user, and hence are kept under a folder named after the username. For example if user "xyz" logs into OpenI, OpenI will automatically create a private folder for her using her username as the folder name (e.g. contents/users/xyz). Now when this user creates an analysis, and chooses saves it in her private folder, it will be saved in contents/users/xyz folder.

• Project ID: ID of the project (should be unique using valid alphanumeric characters for creating folder names)
• Project Name: Name of the project for display purposes
• Project Category : This is an additional grouping of projects, so that when you log into OpenI and you have access to several projects, instead of seeing all projects listed in one place, they are separated under different Project Category sections
• Stylesheet : Stylesheet to use for project's HTML look and feel
• Header Message : Header message to display at the top of each analysis
• Default Analysis Path : This is the first analysis a user will see when they log into the project (unless a dashboard has been defined). This requires setting the default analysis path (for e.g. "/project_id/path/xyz.analysis")
• Default Chart Color Palette : Defines the color palates to display on the Chart, you can choose various color combinations to display graphs on the report, you can add any number of color choices from project.xml, in project.xml file new color combination is added like this
  <entry>
        <string>nemo</string>
        <list>
          <awt-color>
            <red>255</red>
            <green>140</green>
            <blue>0</blue>
            <alpha>255</alpha>
          </awt-color>
          ....
          ....
        </list>
  </entry>
  see project.xml file which contains predefined color palates.
  
• Multiple Filter Selection : Setting multiple filter on will enables selecting multiple values within a filter. By default, this is off, meaning if you have an attribute under "Filter" you can only select one value. For example, let's say you have an analysis that lists a country's population, and there is an attribute called Region under the Filter section, with values East, West, North, and South. The default behavior enables you to see either the entire population, or see the population for a specific region. But what if you wanted to see the combined population of East and West? This is a case where having multiple filters turned on will let you choose multiple values under a Filter attribute.
• Write Image Maps : Check box to make write images maps on/off. Turning this on will enable the tool tip in the chart view of the analyses, so that when a user hovers over a bar chart or a line graph, the tool tip will show the exact numerical value corresponding to the particular area or point in the chart.

OpenI uses role based security provided by J2EE web container. Since each J2EE web container security configuration is not identical, we are covering JBoss 4.2.2 and Tomcat 6.0.x here since those were our test platforms. Please refer to the respective J2EE server documentation for the details about security configuration for any other J2EE server.

Every user must have a role "openi" to access the OpenI web application. This role is essentially to separate users who have access to OpenI application (in cases where you have multiple applications deployed on your J2EE server, and want to separate access to OpenI from the rest). The other roles are as follows:

• app_admin :This is application administrator role that provides full administrative privileges for the entire OpenI application, i.e. app_admin users can modify any content and any configuration for any project within OpenI
  
• <project_id>_admin : This is project administrator role that grants a user full administrative privileges for a project whose id is "<project_id>". For example, for the sample project "foodmart", "foodmart_admin" will be the name of the role providing project administrator privileges.
  
• <project_id>_user : This is a project user role that grants a user user-level privileges to a project access privileges to a project whose id is "<project_id>". For example, for the sample project "foodmart", "foodmart_user" will be the name of the role providing project user privileges. A project user (a) doesn't have access to any of the options under "Preferences" except for managing their user profile, and (b) can't modify any of the existing analyses, but can create/modify new analyses of their own.

There are 3 built-in role definitions in the OpenI web application. Here is a table summarizing their authorization rules:

If you have a Tomcat deployment using the default security database, here's how you can configure security to create an application administrator login admin/password, a project administrator login for the foodmart project foodmartadmin/password, and a project user login for the foodmart project foodmartuser/password

• Find <tomcat-home>/conf/tomcat-users.xml
• Configure roles and users as follows:
  
  <tomcat-users>
  <role rolename="openi"/>
  <role rolename="app_admin"/>
  <role rolename="foodmart_user"/>
  <role rolename="foodmart_admin"/>
  <user username="admin" password="password" roles="openi,app_admin"/>
  <user username="foodmartadmin" password="password" roles="openi,foodmart_admin"/>
  <user username="foodmartuser" password="password" roles="openi,foodmart_user"/>
  </tomcat-users>
  
  Note: all user must have "openi" role. All non-app-admin user must have either "<project_id>_user" or "<project_id>_admin" role. For example, foodmart project admin role is "foodmart_admin" and foodmart project user role is "foodmart_user".
  
• Find <tomcat-home>/conf/server.xml
• Ensure you have the following definition entry for the security realm:
  
  <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
  debug="0" resourceName="UserDatabase"/>
  
• In Tomcat's case, you have a choice of other security realms depending on where you want to store the user database (see http://jakarta.apache.org/tomcat/tomcat-5.0-doc/realm-howto.html). Based on the security realm you choose for the OpenI web application, you need to ensure that the user database has the users and roles defined in it.
• OpenI also has a feature to manage user/roles, if roles/users are configured in a jdbc database accessible to the J2EE web container. For details, see JBoss Security Configuration with JDBC User Database for reference.

For default security configuration in JBoss using text files to defines users and roles, add following files under [JBOSS_HOME]/server/default/conf:

• users.properties : contains user entries as user_name=user_password
• roles.properties : contains role entries as user_name=role_1,role_2,role_n (OpenI requires roles "openi" and "app_admin" for admin user)

To customize JBoss authentication using JDBC database (i.e. user logins and role definitions stored in relational database tables), see the following section for details. One key advantage of this approach is that with this, you can leverage OpenI's "Manage Users" feature that can do basic user profile and password management.

Download and install your favorite database engine. Make sure that there is JDBC driver available to connect with the database engine. JBoss, by default, provides driver for HSQL DB only. JDBC drivers are available for almost all popular databases. Once you download the driver, copy the driver jar file into <JBOSS_HOME>/server/default/lib folder.

Start your database, and run the queries below from your SQL prompt to create tables that store user login and role information:

    CREATE TABLE users {
       user_name varchar(50) NOT NULL,
       full_name varchar(50),      
       passwd varchar(50) NOT NULL,
       language varchar(50),
       mail varchar(50)
    }

    CREATE TABLE user_roles {
       user_name varchar(50) NOT NULL,
       role_name varchar(50) NOT NULL
    }

Also, add a sample user login "openiadmin/passwd" and assign the required roles of openi and app_admin by running the following queries:

    INSERT INTO users ('openiadmin', 'OpenI Admin', 'dqIXO+Y5MlTnL/pNbfEDCg==', 'English', 'admin@openi.org')
    INSERT INTO user_roles ('openiadmin', 'openi')
    INSERT INTO user_roles ('openiadmin', 'app_admin')

NOTE: Since password is in digested form, you can not put plain password text. Running the abovementioned SQL script will create sample admin user "'openiadmin" with default password "passwd". Once OpenI is up and running, you can change password or create new user from OpenI menu by selecting Preferences | Manage Users.

Next, you have to configure JBoss security and data source for JDBC authentication.

You need to configure JBoss security policy for application name openi. You can add this in existing <JBOSS_HOME>/server/default/conf/login-config.xml as follows:

<application-policy name ="openi">
    <authentication>
        <login-module code = "org.jboss.security.auth.spi.DatabaseServerLoginModule" flag = "required">
            <module-option name = "unauthenticatedIdentity">guest</module-option>
            <module-option name="password-stacking">useFirstPass</module-option>
            <module-option name = "dsJndiName">java:/jdbc/OpenILoginDs</module-option>
            <module-option name="principalsQuery">select passwd as PASSWORD from users where user_name=?</module-option>
            <module-option name="rolesQuery">select role_name as Role, 'Roles' from user_roles where user_name=?</module-option>
            <module-option name="hashAlgorithm">MD5</module-option>
            <module-option name="hashEncoding">base64</module-option>  
        </login-module>
    </authentication>
</application-policy>

Please note that we are using DatabaseServerLoginModule which needs the specified JNDI data source to connect with database engine. Create one JNDI data source  java:/jdbc/OpenILoginDs descriptor file openi-users-ds.xml as follows and deploy it into <JBOSS_HOME>/server/default/deploy folder :

<datasources>
      <local-tx-datasource>
        <jndi-name>jdbc/OpenILoginDs</jndi-name>  
        <driver-class>DATABASE_DRIVER_CLASS</driver-class>
        <connection-url>JDBC_URL</connection-url>   
        <user-name>database_user_name</user-name>
        <password>database_password</password>
        <min-pool-size>5</min-pool-size>
        <max-pool-size>20</max-pool-size>
        <idle-timeout-minutes>0</idle-timeout-minutes>
        <track-statements />   
      </local-tx-datasource> 
</datasources>

Example driver class and url for some popular databases:

MySql :
    Driver class    : com.mysql.jdbc.Driver
    URL format   : jdbc:mysql://[host]:[port]/[database]

SQL Server (JTDS) :
    Driver class    : net.sourceforge.jtds.jdbc.Driver
    URL format   : jdbc:jtds:<server_type>://<server>[:<port>][/<database>]

Oracle :
    Driver class    : oracle.jdbc.driver.OracleDriver
    URL format   : jdbc:oracle:thin:@[host]:[port]:[database]

Postgres :
    Driver class    : org.postgresql.Driver
    URL format   : jdbc:postgresql://[host]:[port]/[database]

ODBC :
    Driver class    : sun.jdbc.odbc.JdbcOdbcDriver
    URL format   : jdbc:odbc:[datasource]

NOTE : Don't forget to change the "Cache Timeout" value to "0" in your JBoss application server - go to the <JBOSS_HOME>/server/default/conf directory, open jboss-service.xml in text editor and under the section security there is an element <attribute name="DefaultCacheTimeout">1800</attribute>. Change this value to "0" and save the file. If the value is not set to "0" then the the changes about users/roles data on the database will not get reflected until JBoss server is restarted.

Note that the OpenI binary distribution openi-2.0-alpha-jboss.zip does not include pre-built war for JBoss with JDBC authentication enabled. If you need JDBC authentication, you need to build a JBoss specific WAR  with JDBC authentication enabled. See Build OpenI from Source Code for detailed instructions.

• OpenI 2.0 does not work with JBoss 4.2.3. JBoss 4.2.3 has some issues on not resolving clicks in navigation bar (see : http://www.icefaces.org/JForum/posts/listByUser/1736.page ).
• Jboss versions 4.2.2.GA is tested. Lower version of JBoss may not work. You should consult JBoss documentation about the built-in jars and its web container, and then create a custom build to create an openi.war that (a) includes jars not provided by JBoss and (b) excluded jars provided by JBoss.
• We have not tested OpenI with Tomcat versions prior to 6.0, so an approach to creating a custom build similar to JBoss is recommended.