Database repository

iKnowBase uses an Oracle Database for storing both data, metadata and applications. Inside the database, iKnowBase also stores a lot of system code, as well as public APIs for manipulating the data.

Fresh install

A fresh install of the Oracle repository is pretty simple, and consists of only a few steps:

• The database schema where iKnowBase is installed must be created, and it must be given the proper permissions. Also, an installation specific database package must be created.
• The database schema must be populated with startup data. These data can be loaded from an existing installation (for example, when doing a fresh install of a test environment, where the startup data comes from an existing production environment), or they can be loaded from the iKnowBase distribution.

A full set of typical commands is shown below:

$ quickstart.sh iknowbase.properties createUser
$ quickstart.sh iknowbase.properties uploadFile IKB_MASTER.DATA
$ quickstart.sh iknowbase.properties importFile IKB_MASTER.DATA IKB_MASTER
# Optionally download and display import log
$ quickstart.sh iknowbase.properties downloadFile IKB_MASTER.DATA.LOG .
$ cat IKB_MASTER.DATA.LOG

Prepare the database schema

Installing the database schema is most easily done using the Quickstart program. Assuming that you have created a file “iknowbase.properties” with the proper information, use the following command:

$ quickstart.sh iknowbase.properties createUser

This command will perform three actions:

• First, as user SYS, it will create the user specified in the property file, with the password also specified there.
• Next, as user SYS, it will grant required permissions to that user. A full list of permissions can be seen in the log file after executing the command.
• Finally, as the newly created user, it will create the database package IKB_GLOBAL_PREFS with default variables.

Import startup data

You can import startup data with any mechanims you choose, but once again the Quickstart program is the preferred and supported mechanism. Using the Quickstart program has two steps: First you upload the startup data, and then you import them:

$ quickstart.sh iknowbase.properties uploadFile IKB_MASTER.DATA
$ quickstart.sh iknowbase.properties importFile IKB_MASTER.DATA IKB_MASTER

The first command will upload the file IKB_MASTER.DATA from the local directory, and store in an Oracle Directory on the server. The default (and recommended) directory is called DATA_PUMP_DIR, and is often available under /app/oracle/admin//dpdump. Note that if you import data from another existing database, the file may have any other name. This command will run as the iKnowBase-user.

The second command will import the file IKB_MASTER.DATA from the Oracle Directory into the iKnowBase schema. The Quickstart program will in fact use Oracle Datapump to perform this import. For the datapump import to succeed, the name of the database user that exported the schema must be specified. In the distribution, and by convention, the name of the datafile reflects the name of the exporting user; here, it is IKB_MASTER.

If something fails during import, Oracle Datapump will store log messages in a LOG-file. Use the following command to download the logfile to your local directory:

$ quickstart.sh iknowbase.properties downloadFile IKB_MASTER.DATA.LOG .

When using Quickstart, the name of the logfile is always the same as the name of the datafile, with a .LOG-suffix. Note that this file is created in the Oracle Directory where the DATA-file exists, so you may also view the logfile on the server without downloading it first.

Note that it is often useful to store a copy of the logfile even when there are no appearent failures.

Upgrade

Upgrading an iKnowBase-installation is technically more comples than a fresh install, mostly because there are already existing data that must not be deleted. An upgrade therefore have the following steps:

• If you want, take a copy of existing source code for post-upgrade troubleshooting
• Next, update and verify the user/schema settings
• Run through schema upgrade scripts for all required versions, and install the latest code (types, packages, functions and procedures)
• Recompile any invalid packages

$ quickstart.sh iknowbase.properties exportSource scripts.zip
$ quickstart.sh iknowbase.properties configureUser
$ quickstart.sh iknowbase.properties upgradeAll
$ quickstart.sh iknowbase.properties compileInvalid

Export existing scripts

Export existing scripts is entirely optional, but we recommend this for easier post-upgrade troubleshooting. You may use any available tool for this process, but once again the Quickstart has an easy-to-use mechanism:

$ quickstart.sh iknowbase.properties exportSource scripts.zip

The above command will use DBMS_METADATA to recreate scripts for all TYPEs, PACKAGEs, PROCEDUREs and FUNCTIONs in the iKnowBase schema, and store it in a zip file. The zip-file will also contain compile-scripts for each of the object types, as well as a compile script that compiles everything.

Prepare the database schema

Various versions of iKnowBase require different permissions, and have different information in the IKB_GLOBAL_PREFS-package. It is therefore necessary to configure the database schema to the new requirements:

$ quickstart.sh iknowbase.properties configureUser

This command will perform two actions:

• First, as user SYS, it will grant required permissions to that user. A full list of permissions can be seen in the log file after executing the command.
• Then, as the iKnowBase user, it will recreate the database package IKB_GLOBAL_PREFS with default values.

Upgrade schema and install latest code

The most complex step in the upgrade process is to upgrade the schema and install the latest code. For convenience, use the Quickstart program’s upgradeAll feature:

$ quickstart.sh iknowbase.properties upgradeAll

This command does in fact comprise a number of schema upgrade steps (one for each schema version), and then a single code installation step.

Note that after installing the latest code, open database connections and open cursors may cache database type information that is no longer correct. It is therefore recommended to restart all application servers, email readers, search crawlers etc that may have open database connections.

Recompile invalid packages

After the upgrade step, it may be required to recompile invalid packages in the Oracle schema:

$ quickstart.sh iknowbase.properties compileInvalid

This command utilizes DBMS_UTILITY.RECOMPILE_SCHEMA for recompiling only invalid packages.

De-installation

De-installation of the iKnowBase installation is pretty simple: Remove the user and all it’s data:

$ quickstart.sh iknowbase.properties dropUserCascade

Note that you may have to set the value “allowDropUserCascade=true” in the property file before this command will work.

Note also that while a simple “drop user cascade” from sql*plus may work, it also may not: When a schema has Oracle AQ-tables (Advanced Queing), it is sometimes required to manually drop these queues first. The Quickstart command handles this, and is therefore the recommended way of deleting a user.

And finally, a word of warning: The dropUserCascade command is utterly unrecoverable, and if you drop a user by accident, you will have to reload data from a backup. Take care!

Advanced topics

Duplicate an existing installation

Often, you will want to duplicate an existing installation. For example, you may have a development, test and production instance, and you may need to copy from production to test. Doing so is very simple:

$ quickstart.sh IKB_PROD.properties exportFile IKB_PROD.DATA
$ quickstart.sh IKB_TEST.properties importFile IKB_PROD.DATA IKB_PROD

In the example above, there are two property files. IKB_PROD.properties contain information about the production schema, while IKB_TEST contain information about the test schema. Data is first exported from the production schema, then imported into the test schema.

Note that the first time you do this, you will also need to run the createUser-command. Of course, if the IKB_PROD and IKB_TEST schemas reside on different Oracle-instances, you will also need to move the DATA-file between the instances, either using a combination of downloadFile and uploadFile, or by using some other file transfer mechanism.

Running iKnowBase in a Oracle Enterprise Edition database

By default, an iKnowBase installation is prepared for running in a Oracle Standard Edition database. It you are licened for running Oracle Database Enterprise Edition then run the following command to speed up queries displaying (or sorting) document popularity.

$ quickstart.sh iknowbase.properties dbscript source/common/mv_log_document.sql logfile

To switch back to the standard edition version do:

$ quickstart.sh iknowbase.properties dbscript source/common/view_log_document.sql logfile

Configuring the Activiti BPM Engine tables

In order to use the Activiti BPM Engine with iKnowBase, you will need to install the Activiti tables into the iKnowBase repository. This is done through the quickstart program, which has three discrete commands for configuring the Activiti database tables. Use one of the commands below:

$ quickstart <propertyfile> createActivitiSchema
$ quickstart <propertyfile> upgradeActivitiSchema
$ quickstart <propertyfile> dropActivitiSchema

Note: Dropping the Activiti schema will drop all process data. Use with care!