This (video) tutorial shows how to create GEO charts, starting with a simple background layer. Watch the video or continue reading to learn more about maps in instantOLAP.

This tutorial uses the beta version of instantOLAP 3. Creating Geo Charts with instantOLAP 2.6 works exactly the same way, you’ll only need to design your report with the instantOLAP Workbench, because the web query editor is a new feature of version 3.

The OLAP System uses standard ESRI Shapefiles for the maps. Because the ESRI Shapefile format is very common, nearly every kind of map is available. Various shapefiles can be found for free in the internet or purchased. The instantOLAP default installation contains the free “world_countries_shp” shapefile with the world countries borders, which will be used for this example.

First of all, you will have to create a new block inside your report and change its format into the “Geo Chart” format. After you did this, a number of new properties will appear for this block.

Maps in instantOLAP are organized in background and foreground layers. Each kind of layer can be displayed as polygons, texts or symbols.

The background layers will always be rendered, independend of the table data or anything else. You can use the background layers to display the fixed background information you need for your report, e.g. country borders and country names.

First of all, we will a add a simple background layer to the chart. Simply tell the system where to find the shapefile on the hard disk by filling the property “BG 0 Sourcefile”. Fill in the absolute path here, because shapefiles don’t need to be located inside the instantOLAP repository. Also, if your background and frontend server are located on different machines, this path should be visible for the frontend server.

For this example, the path would be “<instantOLAP>/repository/geodata/World_countries_shp.shp” – whereby <instantOLAP> is the installation path of your instantOLAP server.

After you located the shapefile, it’s time for a test. Execute the report and you should see your first map inside instantOLAP. It displays the world country borders as black borders with empty polygons.

Now you can change some properties of the background layer to change its presentation, e.g. by assigning colors to the properties “BG 0 Background” and “BG 0 Color” (which is the border color).

Now we’ll display the country names in a second background layer. Shapefiles can contain additional informations for each polygon which are stored in a simple DBase database (located in the same folder as the Shapefile itself). There are a number of tools you may use to open and view/edit this database files, including Microsoft Excel.

You max have noticed that additional properties were added to the chart property list after you edited the “BG 0 Sourcefile” property. The editor automatically adds properties for an additional layer whenever you assign a value to a layer sourcefile and this is the location where to add the second layer.

Use the same shapefile for the property “BG 1 Sourcefile” and set the “BG 1 Type” property to “Text” – this will turn the layer  into a text layer. Now you must tell the system which database information you want to display as the text. In our example Shapefile, the country names are stored in the column “NAME” – simply enter this attribute name into the property “BG 1 Text Attribute”.

Data layers are similar to background layers but they only display the fragments of the Shapefiles related to the table data. E.g. a data layer could highlight single countries in certain colors, dependend on a cube value like the turnaround for that country.

Each row of your OLAP query will be related to a single map fragment. Therefore, a data layer needs additional information to link the fragments to the rows of your query. This is realized by matching the header text of the Y-axis with a text attribute of the Shapefile database. E.g. if your query contains ISO country codes in the Y-headers, there must be a database field in the Shapefile with exactly mathing ISO codes.

Adding a data layer works the same as adding a background layer: Enter the absolute path of the shapefile in the property “Data 0 Sourcefile” to create a new layer.

Now you’ll have to match the table with the Shapefile segments: For our example, add a fact (e.g. turnaround) to the X-axis of the table and the level “COUNTRY” of the agency dimension to the Y-axis. Because the COUNTRY level contains the ISO contry codes as keys and the World_countries_shp Shapefile contains these codes as attribute, we can tell the system how to match the headers to the Shapefile. The Shapefile attribute is named “ISO_2″, therefore you’ll have to enter this name in the attribute “Data 0 Text Attribute”.

If you execute the report now you’ll see some new numbers in some countries. This is the table content, mapped to the regions identified by the Y-axis headers which are mapped to the Shapefile regions.

A number of table properties are straight forward displayed in the map, including the background and foreground color of your table cells. Therefore, color coding for maps works the same as for tables – simply change the background color of the Y-axis headers and the polygons in the map will have the same colors as the table would.

In our example, you can add a simple color coding by entering the following expression into the background expression of the Y-Axis header: “IIF( Amount() < 30000000, ‘red’, ‘green’ )”. This will turn the background color to “red” if the turnaround for a country is less than 30 million or to “green” if not.

In instantOLAP, every Cube is by default a ROLAP cube. This is because we believe creating a new cube is very productive with adhoc cubes: You can add new dimensions to cubes or modify mappings and then instantly test the new results without any aggregation process (which may take time).

After you finished the first production quality version of your cube it is time to test its performance and to improve it if neccesary. This is when Offline Stores come into sight.

Since version 2.6 building offline stores is very easy and comfortable: Use the context menu of the cube to add a new Offline Store to it. Then you must decide, which dimensions you want to add to the cube and how you want them to be loaded.

After you added the store, a new column will appear right to the mappings. In this new column you can define, which dimensions and facts you want to be added to the new Store.

Now it’s time to create the most simple form of a store: Add every dimension and fact to the store by clicking into the related cells of the column. A checkmark will show that the dimension or fact is now part of the Store.

Now you should open the Model Manager and fill the Store with data. Locate the Model in the Manager, open the Model Information dialog for “demo/demo” by double clicking the model and switch to the Cubes tab in the dialog.

Here you can see the new Store which replaced its source cube in the Cubes tab. The most important information for Stores is the “State” columns which shows if the Store is currently available (online), not available (offline) or building (online + building or offline + building).

Because our cube is not loaded yet, its state is “offline”. To load the Store, select it and use the “Rebuild” button from the toolbar at the right side. Then wait a few seconds and use the “Refresh” button from the toolbar to view the current state.

Now the store is loaded and the execution time of the demo reports will shrink from seconds to milliseconds. There are a couple of new informations in the table: The build time, the error message for the case the build process stopped with an error, the number of raised warning while loading the data and the Store size.

The Store size, the last reload timestamp and the build time are simple informations from the loading process. The build time show how long it took to load and aggregate the source data and the size shows the effective (compressed) size of the Store. This is not the number of cells the Store can deliver but the number of informations instantOLAP wrote to the local disk. In this oexample, the Store needs 73,863 records to deliver data for 151,632,000 cells, a compression of 2000:1!

The error message and the warnings are very important informations for the case your cube delivers no or wrong data or didn’t load at all.

There are two different ways how to aggregate the values for higher levels of a dimension: By doing a rollup or by querying each single level.

Rolling up means that the system will only query the lowest level and single mapped keys from the database and calculate every upper level manually. Querying the levels means the system will perform one SQL query per level.

Be careful with the query scheme, because usually your Store contains more than one dimension. E.g. if you have three dimensions with three levels, this will perform 27 queries to the database. Ten dimensions with three levels means 118.000 queries, one for each possible combination of each dimension level!

But why should you use the query scheme? There are some reasons you might need this:

• One of your facts uses a COUNT DISTINCT aggregation, and this cannot be calculate by performing a rollup in some cases
• Your hierarchy cannot be calculated by rolling up data because a key value is not the SUM, AVG or else of its children
• Sometimes it can be faster to perform many small queries than a single, large one

Also for facts you can change the aggregation scheme, but here you can change the aggregation formula the system uses. The default value is “default” – then the Store automatically determines the aggregation type from the SQL expression you mapped the fact with. But can also change it manually to one of the aggregations “SUM”, “AVG”, “MIN”, “MAX” etc. This is needed whenever the system is unable to automatically determine the aggregation from the SQL expression or simply want something different.

There are some pitfalls when loading the data of a Cube into a Store. The Store might raise an error or collect warning while its building process. Whenever an error is raised you should, of course, fixed it and reload the Store again. But even warning should always be fixed, because they can be a reason for wrong data. But why can a Store raise errors or warnings when original cube works correct?

There two main reasons and they are not always easy to understand:

• In ROLAP cubes, the cube will of course only load data for the requested dimensions and facts. Which also means it will only use the tables containing information for this dimension and facts. But if you combined, for example, two different fact tables in one cube, the Store will perform one SQL query to gather both facts – and combining two fact tables means a full permutaion of both tables, the numbers get exponentially higher. Maybe with the ROLAP version of your cube you didn’t see the error, because you always used only one of the facts, but the Store combines everything.
• Your cube may deliver data for more keys than a dimension contains. E.g. if you build a product dimension and filter the dimension to load only yellow products, you must apply the same filter to the cube. Otherwise, the cube will load facts for keys which are not part of the dimension, warn you (in fact, this is 99.99% of all warning a cube will raise are “missing keys”) and drop the row. Dropping the data itself is not the problem, because you don’t want the cube to load data for unknown keys, but your original ROLAP does it!  E.g. if the ROLAP cube is queried for the Amount of 2010 for all products, the ROLAP Cube will simply generate no WHERE statement for products, because you want all of them. But the store will calculate this value by rolling up all product data and the value will be less than the ROLAP value. This is not an error in the Store, it is originally located in the ROLAP Cube!

As you can see, the source for all problems with Stores is the ROLAP Cube itself. Therefore, you should always look for error messages and warnings and try to eliminate the problems in you cube.

Also important for warnings: You need to know how to find them, because the model information only shows the number of raised warnings but not the warnings itself. The warnings are sent to the log while building the Store, therefore you should open the log console before starting your first Cube aggregations. It is also important to switch of the session filter before building the Store, because this is a system process not related to any (or your) user session.

Our simple approach to load all dimensions into a single Store is good for small Cubes, but with a raising number of dimensions the Store size will grow exponentially (this is, because the number of cells in a Cube is the product of all dimension sizes).

Adding more and more dimensions to a MOLAP Cube will bring every OLAP system to its limit -  including instantOLAP. We have a good experience with cubes up to one billion compressed datasets (Stores of this size can hold up to 5000 billion cells), but even if this number sounds very high it can easily be reached by combining 20 or more large dimensions. And aggregating this number of cells can take many hours.

Therefore, we have a different approach for this problem: Combining of multiple Stores. In practice, there are several combinations of dimensions which are used often and other combination which are used never or very seldom. This means, you can aggregate a ROLAP Cube into more than one Store, and each Store holds a smaller number of dimensions the original Cube contains.

In this example we combined two Stores, one holding the Campaing dimension, the other the Manufacturer dimension. The system will now automatically choose the correct Store whenever a user queries the cube.

Now you might say “Okay, but what happens if the user queries all dimensions together or an unknown combination?”. This is where HOLAP comes into play: The “H” in HOLAP stands for hybrid – a mixture between offline MOLAP Stores and adhoc ROLAP Stores. You can create subset Stores and tell the system to use the orignial ROLAP Cube whenever an unknown combination of dimensions is queried. This means, you can deliver performant Stores but also a fallback solution for unmapped combinations.

How to turn an MOLAP Cube into an HOLAP Cube? There is a property for Cubes, “Keep Adhoc Cube With Stores”. Simply set the property to “true” and redisplay the Cubes in the Model Information dialog. Now you will see the original ROLAP Cube behind your Stores. And, because the order of Cubes and Stores is important in instantOLAP, the system will use the ROLAP cube only, if none of the Stores can deliver the wanted data.

You can see this in the Model Information also: When switching the property “Keep Adhoc Cube With Stores” to “true”, the original Cube appears behind the Stores. Simple but effective.

This is the last question: When will the system build or refresh my Stores? Of course, you don’t want to create the Stores manually after creating them. Therefore, there are two different ways to keep Stores up to date: Dimension triggered (automatic refresh) or time triggered (crontab refresh).

The automatic refresh will always start the build of a Store whenever it is offline or one of its source dimensions changed (in this case, the Store must be rebuild otherwise it would contain corrupted data). To turn the automatic refresh on, set the switch “Build Offline Store Immedialtey” of the configuration / model to true.

The alternative to automatic refresh is to refresh a Store triggered by a cron pattern. This cron pattern, which is a property of the Stores, you can manually control when the Store should be rebuild. Whenever a source dimension of the Store changes, the Store will fall back into the ROLAP mode and the data will be queried from the underlying database.

Usually, it is more comfortable to use automatic refresh, but there are sometimes reasons to manually controll the cron pattern. E.g. if you don’t want to stress your source database with the large SQL queries at daytime or if a source database is not available at certain times.

Basically, each chart in instantOLAP is bound to a single pivot table. Overlay charts work generally in the same way, but because an overlay chart is composed from two or more charts, we will also need more than one pivot table to feed the chart with data – each table feeds a single chart. So the first step is to create a block which contains multiple tables.

To create the first table, just use the “New pivot table” button from the right toolbar of the query editor. A new block, containing a single and empty table, will appear. Now drag a fact and a data series to the table, in out example this will be the “Amount” Fact and PRODUCT level from the Product dimension of the instantOLAP demo model.

Now you can add a second pivot table to the existing block by opening the context menu of the block (use the right mouse button on the title bar of the block). Use the menu item “Add pivot table” of the menu to add a second and emtpy table.

Because we want the new table to show data for the same samples, you should use the same iteration for the x-axis of the new new table as you did in the previous table. Only the fact in the y-axis will be a different one, in our example we will use the “Quantity” fact from the demo model.

This was the basic step for each chart generation: creating the source table(s) for your chart.

It’s time to turn the table into chart: Use the context menu of the block and choose one of the overlay chart types. In out example we’ll use the “Bar / Line” chart which turns the first table into a bar chart and the second into a line chart.

If you execute the query now, you may recognize that there are really two charts, but the second one (the line chart) only displays a flat line at the bottom of the image. This is because till now both charts share the same range and the values for the fact “Amount” much bigger than for the fact “Quantity” (or its line). Therefire it’s down to the bottom. and we’ll have to add a second range to the chart and to scale the line to this new range.

First of all you’ll have to activate the second range. There is a property named “Range 2 On” which has to be set to “true”. If you execute the query now you will see a second range, but the rest of the chart will look like before, including the  flat line chart.

This is because you must assign each of the chart to the ranges. By default, both charts are assigned to the range number 1, which is the default range at the left side of the chart. To re-assign the second (the line) chart to the new range at the right side, use the property “(Overlay) Series Range” property and set it to “2″ (use “1″ for the first range and “2″ for the second). If you execute the query now you’ll recognize the line beeing scaled over the full image.

Now, you have created an overlay chart with two source tables and two ranges.

Because of copyright reasons, only a few drivers are included in the instantOLAP standard distribution (an open source driver for Sybase and Microsoft SQL-Server and a second driver for HSQLDB databases). For all other database servers, you can find the driver in the internet. This is a list of the common database servers and some internet addresses where to find the driver.

If you use Apache Tomcat as your Application Server (which is the default Application Server installed together with instantOLAP), installing a new driver is very simple:

1. Download the driver from the vendors driver page
2. If neccesary, extract the driver or execute the driver installer to extract the driver files onto your hard disk.
3. Locate the driver files (they always end with .jar) and copy them into the library folder of your Tomcat server. Depending on the Tomcat version, the library folder is <tomcat>/common/lib (for Tomcat 5.5) or <tomcat>/lib (for Tomcat 6)
4. Restart Tomcat

After you installed the driver in your Application Server you can use from instantOLAP. Generally there are two different ways to access a driver or database: You can connect the server directly out of instantOLAP or you can use a predefined datasource, which has to be prepared inside the Application Server. For testing, developing or small installations, we recommend the first alternative.

To connect a database directly out of instantOLAP, simply use the “Add datasource” button when you are inside the “Datasources” section of a configuration. This will open a datasource wizard, which asks you for the name, driver, connection URL and credentials of the target database. Refer our online documentation for more details.

There are at least two good drivers for the Microsofts SQL-Server: The original Microsoft JDBC driver and the open source driver jDTS for Microsoft SQL and Sybase databases, which is included in the instantOLAP standard distribution.

The original Microsoft JDBC driver can be found and downloaded from the Microsoft page.

• Download: Microsoft SQL Server JDBC Driver 2.0
• Driver file(s): sqljdbc.jar
• Driver class: com.microsoft.sqlserver.jdbc.SQLServerDriver
• Connection-URL: jdbc:sqlserver://<server>[:<port>];databasename=<database>

Escpecially in older versions of the originial driver, it is important to know how to form the connection URL. You must include the database name in your URL, otherwise you will be able to see the tables but not to access their content.

jDTS is an open source alternative for Microsoft SQL and Sybase databases and already included in the instantOLAP standard distribution.

• Download: http://jtds.sourceforge.net
• Driver files(s):  jdts-<version>.jar
• Driver class: net.sourceforge.jtds.jdbc.Driver
• Connection-URL: jdbc:jtds:sqlserver://<server>[:<port>][/<database>]

When using MySQL databases, make sure to use the most current available driver version, because older drivers may cause problems with newer versions of the database.

• Download page: http://dev.mysql.com/downloads/#connector-j
• Driver file(s): mysql-connector-java-<version>-bin.jar
• Driver class: com.mysql.jdbc.Driver
• Connection-URL: jdbc:mysql://<server>/<database>

For Oracle databases it is imporant to use the correct version of the driver which matches the version of your database server. The drivers for all version can be downloaded from the Oracle page, but you will need to create an account before (if you don’t have already).

• Download: Oracle JDBC/UCP Download Page
• Driver file(s): ojdbc15.jar or ojdbc16.jar
• Driver class: oracle.jdbc.driver.OracleDriver
• Connection-URL: jdbc:oracle:thin:@<server>:1521:<database>

Like in the case of Microsoft SQL Server, you can use the original Sybase driver or the open source driver jDTS to connect a Sybase driver.

• Download: jConnect – Software Developer Kit
• Driver file(s): jconn3.jar
• Driver class: com.sybase.jdbc2.jdbc.SybDriver
• Connection-URL: jdbc:sybase:Tds:<server>[:<port>]/<database>

jDTS is an open source alternative for Microsoft SQL and Sybase databases and already included in the instantOLAP standard distribution.

• Download: http://jtds.sourceforge.net
• Driver file(s): jtds-<version>.jar
• Driver class: net.sourceforge.jtds.jdbc.Driver
• Connection-URL: jdbc:jtds:sybase://<server>[:<port>][/<database>]

For all current versions of DB/2 you can use the Universal Database Driver (UDB) from DB/2. However, when you wan’t to connect a DB/2 database running on a mainframe system, you’ll have to purchase an additional license from IBM.

• Download: IBM – Application Development with DB/2 (Follow the links and download the DB/2 client)
• Driver file(s): db2jcc.jar
• Driver class: com.ibm.db2.jcc.DB2Driver
• Connection-URL: jdbc:db2://<server>[:<port>]/<database>

Since IBM bought the Informix database, you can find the Informix drivers on the IBM homepage now, too:

• Download: IBM Software Downloads
• Driver file(s): ifxjdbc.jar
• Driver class: com.informix.jdbc.IfxDriver
• Connection-URL: jdbc:informix-sqli://<host>:<port>/<database>:informixserver=<dbservername>

The tool is very useful whenever instantOLAP loads its data from a data-warehouse and you want to rebuild certain models, dimensions or cubes after the ETL tool rebuild the warehouse or added new data to it.

This article describes, how to use the tool from batch-files or other Java applications (most ETL tools can call native Java commands) and which operations are available.

The console is delivered as a simple Java archive (jar file) and is located in the folder <instantOLAP>/tools/console. You can use the archive from this location or copy it to another computer – no other resource (except a local Java installation) is needed to execute the application.

To start the console in the interactive mode, use the command:

java -jar iolapConsole.jar <server-url> <user> <password>

where <server-url> is the complete url to the backend-service of your instantOLAP-server and <user> and <password> are the credentials for your administrator account. E.g. the command for a local installation on port 8080 and with the administrator account would be:

java -jar iolapConsole.jar http://localhost:8080/iolapWS admin admin

If the jar file is not located in the current folder, you can also type its whole path (relative or absolute). After you logged successfully into the server, you will see the following welcome message:

instantOLAP console
(c) 2006-2009 Thomas Behrends Softwareentwicklung e.K.
Connecting server http://localhost:8080/iolapWS...
ok
>

Now you can use one of following commands to control the server:

This command rebuilds a single dimension of a model (and all dimensions being dependend on this). The command expects the model name and dimension name as argument.

Example:

> BUILDDIMENSION demo/demo Product
Building dimension Product of model demo/demo...

This command rebuilds all dimensions of the specified model. The only argument the command expects is the name of the model.

Example:

> BUILDDIMENSIONS demo/demo
Building dimensions of model demo/demo...

The command BUILDSTORE rebuilds a single store of the specified model, the store name has to be passed as second argument.

Example:

> BUILDSTORE demo/demo store1
Building store store1 of model demo/demo...

Rebuilds all stores of the specified model.

Example:

> BUILDSTORES demo/demo
Building stores of model demo/demo...

Use the command CLEARCACHE to empty a single cache of the model. After the execution, the cache still exists but contains no entries.

Example:

> CLEARCACHE demo/demo cache1
Clearing cache cache1 of model demo/demo...

This command clear all caches of the specified model.

Example:

> CLEARCACHES demo/demo
Clearing caches of model demo/demo...

Clears a single store of the model and brings it into the “offline” state. Dependend on the configuration settings, the model will continue using the original adhoc version of the store, otherwise the system will immediatley start to rebuild the store again.

Example:

> CLEARSTORE demo/demo store1
Clearing store store1 of model demo/demo...

This command clears all stores of the model. Like in the CLEARSTORE command, the system will immediatley rebuild all stores dependend on the configuration settings.

Example:

> CLEARSTORES demo/demo
Clearing stores of model demo/demo...

This command returns a list of all dimensions of the specified model.

Example:

> LISTDIMENSIONS demo/demo
Agency
Anim
Campaigns
Manufacturer
Product
Time

Returns a list of all models on your server, including the active and inactive ones. For each model, the current state is append as text. The following states are possible:

• ONLINE: The model is started and ready
• BUILD: The model is currently starting
• CLOSED: The model is currently not started
• CLOSING: The model is currently shutting down
• SYNC: The model is started and currently synchronizing its dimensions and / or cubes
• ERROR: The model is not started because an error ocurred while starting it

Example:

> LISTMODELS
demo/demo (ONLINE)
eventlog/eventlog (ONLINE)

This function returns the state of a specific model. The state is returned as number in this functions, the following states are possible:

• 0 = CLOSED
• 1 = BUILD
• 2 = ONLINE
• 3 = SYNC
• 4 = ERROR
• 5 = CLOSING

Example:

> MODELSTATE demo/demo
Request model-state for demo/demo...
State = 2

This command stops the console.

This function starts the synchronize process for a model, in which it is checking its cubes and dimensions if they are outaged. You must pass the timeout for the synchronize process in ms as second argument. This function is only useful if you want to synchronize the model immediatly, because the system synchronizes all its online models each minute.

Example:

> STARTSYNC demo/demo 1000
Starting model demo/demo synchronize...

This command starts the specified model.

Example:

>START demo/demo
Starting model demo/demo asynchron...

This command shuts down the specified model.
Example:

> STOP demo/demo
Stopping model demo/demo...
ok

This command simply waits the given number of seconds.

The batch mode can be used to call the console from external batch files and to execute commands without user interaction. To execute a command, just add it and its arguments behind the standard arguments of the console, the syntax for the batch mode is:

java -jar iolapConsole.jar <server> <user> <pwd> <command> [<arg1> [<arg2> [...] ] ]

If you call the console in batch mode, it will immediatley execute the passed command and then exit. E.g. the following line

java -jar iolapConsole.jar http://localost:8080/iolapWS admin admin START demo/demo

would start the model “demo/demo” on a local server running on port 8080 and then return.

Note that all commands except STARTSYNC, also in the interactive mode, only fork the requested operation on the server and then return without waiting for the operation to be finished. However, if you send a number of commands for the same model to server, they will be queued and executed in sequential order.

Therefore, this article describes, how to update instantOLAP when using the Apache Tomcat application server with some easy steps. The Tomcat server is included in the standard distribution of instantOLAP.

Basically, updating instantOLAP is simple, there are only 6 simple steps you have to perform. But you have to be careful and must execute these steps in the right order, otherwise you may harm your Tomcat installation:

Of course, before you start the update, you should download the new files of instantOLAP and put them somewhere (not in in the instantOLAP folder yet). On our download page, we always offer the files for manual installations at the bottom of the page, below the complete installation files.

These files end with the extension “.war” and are just zipped folders which are known and unpacked by the Tomcat server. Usually, you will need three files for a complete update of instantOLAP:

• iolap.war: This is the Web-Portal of instantOLAP
• iolapWS.war: This is the backend (OLAP-Engine) of instantOLAP
• iolapWorkbench.war: This is the Webstart version of the instantOLAP Workbench. If all of your users use the Windows installation of the Workbench, you won’t need this file.

This is the most important step at all, because removing the webapp folders as described in the next step will destroy parts of your tomcat configuration and it will no longer work.

By default, Tomcat unpacks all war files into its subfolder “webapps”. Each war file becomes one folder and the server will not use the updated war files as long as their unpacked versions exist here. Therefore you’ll have to remove the folders “iolap”, “iolapWS” and “iolapWorbench” from here.

Now you can move or copy the war files into the instantOLAP folder. The location where you must copy the files is <instantOLAP>/tomcat/iolap_webapps.

We always suggest to make a backup of the previous files in this folder before you replace them with the newer version.

Now you can start the server again. After a couple of seconds, the Tomcat will start to unpack the war files into the webapps folder and instantOLAP will be available again.

Thats it.

Beginning with version 2.6, the standard installation of instantOLAP will have a different Tomcat configuration and the server will no longer unpack the war files in the webapps folder.

Then you will no longer need to delete this folders when updating the system and cannot harm the server if you forget to shut down the server before removing this folders. Even better: Tomcat automatically recognizes the new war files in the iolap_webapps folder and updates itself without the need to stop/start itself.

If you want to, you can change this setting in your Tomcat installation, too. Stop the server, then open the file <instantOLAP>/tomcat/conf/server.xml and search for the entry unpackWARs=”true”. Simply change it from “true” to “false”. Now you should remove the instantOLAP folders from the <instantOLAP>/tomcat/webapps folder and can restart the Tomcat server.

This article describes how to implement such access rules in two steps for the customer / region example.

Before you can use the user information in access rules, you must make them available inside the model. The only ways to do this is to load the information into a dimension. Use normal SQL-KeyLoader to access the user-database and to load the user information. There are two basic rules when creating a user dimension:

• The dimension must at least contain the exact user-IDs at keys. The user keys can be loaded to the top-level or they can be grouped (e.g. to users groups), but they must be inside the dimension and contain the login-IDs.
• All IDs for keys from other dimension to which the user should have access to must be stored as attributes in the user-keys. E.g. the list of all region IDs could be loaded as attribute “regions”. Later, you can use this attribute to match its values with the region-keys.

Now you can add access rules to your other dimension by referencing the current user-key and its attributes. Switch to the access rule editor by selecting the “Access” tabulator and start adding the rules to the dimension, e.g. to this “Customer” dimension.

The first part of your access rule has to find the current user key in the “User” dimension, because the user key is not automatically selected when the user executes a query. You could select the user in the query itself (in its “Filter” property) or you can use the FIND function in the access rules. The last solution is the better one because in this case you does not need to change every query (and you cannot forget this in future queries). The expression to find the current user is:

FIND( User, USER() )

where “User” is the name of your user dimension (you need to change it if your user-dimension has a different name). The function USER returns the name of the current user (his login). Because we search with the users login-name, it must exactly match the ID of the key in your dimension.

After you located the user key, you can use its attributes. E.g. if the user key has an attribute “regions”, which contains alle region id the user should have access to, the expression

FIND( User, USER() ).regions

will return the region codes. The result can contain no, one or multiple values (of course, a sales representive could be more responsible for more than one region).

Now the last thing is to match this region codes with the customer dimension. It is important to use relative expressions here and to match the REGION level (!) with the attribute, not the keys of the Customer dimension. E.g. the expression

{REGION} IN FIND( User, USER() ).regions

would convert the region name of the current customer, region (or whatever currently is selected) into a string and test its occurence in the region list of the user. Because REGION is a relative expression, this works for all levels of dimension: A customer is only visible if it belongs to a listed region, the regions itself is only visible if listed, and the root key of the Customer dimesion is only visible if one of the regions is listed.

Of course, you could also match the lowest level or match more than one level, but in most cases this is the typical expression we use for access restrictions. Sometimes it is neccesary to use dimension links – e.g. if the customer and region are stored in different dimensions, you would have to change the expression into something like:

{CUSTOMER.region} IN FIND( User, USER() ).regions

This only works, if the customer and region dimension are linked.

The last step is to add access rules for administrators or CEOs, which usually are allowed to see all keys of all dimensions. This can be done by a role-check in an additional access rule. The simple expression

HASROLE( 'iolapAdmin' )

would grant access to all keys for a user owning the role “iolapAdmin”. The expression always returns “true” if the user own this role, independend on the keys.

This must be done before sending any SQL statement to the databases and in instantOLAP this is realized with the internal “ToDo List”, which lists all needed cells and tries to resolve the source for each cell (when running a reports, you can see the generation of the ToDo-List in the Log). There is a maximum size for ToDo-Lists, and if the lists exceed this limit, the system raises the “Query too complex” error. The default maximum size for this ToDo-List is 250.000 cells, but it can be changed easily in the configuration. However, increasing the maximum will result in longer running and more memory-using reports.

There are several possible strategies to avoid large ToDo-List, and some of them are only available in our new version 2.5 or later:

1. Try to calculate as much as possible inside the database: E.g. if you only have a “Quantity” and “Product price” stored in the database, the “Turnaround” (calculated by Quantity * Price) could be realized with a formula. But this formula would add 2 additional entries to the ToDo-List (for each “Turnaround” cell, an additional “Quantity” and “Price” would be necessary) and the list would become three times bigger than needed. If you use the database to calculate this fact and use a SQL expression like “SUM( table1.quantity * table.price)”, the SQL cube could deliver the fact on itself and the ToDo-List would remain small.
2. Use LOOKUPs: When creating large and sparse reports, where only a small percentage of the cells will be filled with data, instantOLAP will also generate ToDo-Entries for this empty cells. If you use the LOOKUP function to eliminate empty rows or columns in ahead, you can reduce the size of the ToDo-List dramatically.
3. CLUSTER your selections: One of the main reasons for large ToDo-Lists are multiple- and range-selectors. E.g. if you have a small pivot table but a range-selector for months and a display aggregated fact (like SUM(Amount()) in your cells, the system will need to load the amount for each cell in combination with each selected month. So, the ToDo-list for 15 selected months would be 15 times larger than for a single month. But you can use the CLUSTER function in your query filter and reduce the number of selected keys for the time dimension. The CLUSTER function replaces selection by their parent, if all of its children are selected. E.g. if you select a whole year, the function will replace the months by their parent year key.
4. Use offline cubes: Since version 2.5, there is no need for any ToDo-List if every cube in the model is in the offline mode. Then, instantOLAP has to generate no SQL statements (and no ToDo-Lists) and every data will be loaded directly out of the offline stores.