Java applications

iKnowBase comes with a number of web applications that comprise the server side components of iKnowBase:

• ikbViewer is the core runtime environment, serving web pages to end users
• ikbStudio is the development environment for building new applications
• ikbWebServices provides SOAP Web Services, typically to programs and integration engines
• ikbProcessServicesWS provides SOAP Web Services for integration with Oracle SOA Suite 10g
• ikbBatch provides batch based programs, for things such as document conversion, newsletter generation, etc
• ikbWebDAV provides document access through the WebDAV and FTP protocols
• ikbActiviti is a custom packaging of the Activiti Explorer, configured with proper database information and access to iKnowBase components
• ikbInstant provides real time asynchronous messaging

Each of the applications are installed in a similar way. Also, there is no conceptual difference between a fresh install and an upgrade, although many application servers have shortcuts to reinstall a new version of an existing application. The install or upgrade process will vary from application server to application server. This chapter describes the generic concepts, while application server specific methods are described in appendixes.

Fresh install

For each of the java applications, you may need the following steps:

• Create a JDBC data source, and expose as a JNDI-reference. This step can often be shared across all applications.
• Set up JAAS-security for the application server (or servlet container), if needed.
• Deploy the application.
• Configure security roles.

Before you start

The iKnowBase applications require an application server or servlet container that supports the Java Enterprise Edition Servlets release 3.0. For many application servers, you will need to configure a separate container for iKnowBase use.

ikbWebDAV requires deployment to context root / and will typically require a separate host (virtual host or separate server depending on application server) for this purpose as ikbViewer is also deployed to /.

Cluster support

The iKnowBase web applications in general support application server clustering and session replication, provided the load balancer is configured with session persistence / sticky sessions. See application server specific documentation for more details.

Exceptions:

• ikbWebdav does NOT support clustering in version 6.4 and must not be deployed to a cluster.
• iknowbase-resources can be deployed to a cluster, but have sessions are not in use and availability/replication is therefore not needed.

Create data source

The iKnowBase web applications will look up the JNDI resource “jdbc/iknowbaseDS”, which needs to be JDBC data source referring to the iKnowBase database repository to use. For some application servers, you will first create a “connection pool” referring to the database, and then a “data source” referring to the data source; other times, you will only create a data source directly referring to the database.

The most important things to keep in mind are these:

• The data source must be called “jdbc/iknowbaseDS”.
• Specify a suitable JDBC data source implementation, typically “oracle.jdbc.pool.OracleDataSource”.
• Specify the username and password for the database login (this is db.ikbUser and db.ikbPassword in the the Quickstart property file).
• Specify the JDBC-url to the database, on the form “jdbc:oracle:thin:@//server:port/instance-name” (this is the same as db.URL in the Quickstart property file).

Deploy the applications

Deploy the applications as required by your application servers, keeping the following in mind:

• The applications are deployed using WAR-file deployment.
• The viewer application (iknowbase-viewer-webapp-VERSION.war) is typically deployed to the root path “/”.
• The studio application (iknowbase-studio-webapp-VERSION.war) is typically deployed to path “/ikbStudio”.
• The web services application (iknowbase-webservices-webapp-VERSION..war) is typically deployed to path “/ikbWebServices”.
• The batch application (iknowbase-batch-webapp-VERSION.war) is typically deployed to path “/ikbBatch”.
• The activiti explorer application (iknowbase-activitiexplorer-webapp-VERSION.war) is typically deployed to path “/ikbActiviti”.
• The process services ws application (iknowbase-processervicesws-webapp-VERSION..war) is typically deployed to path “/ikbProcessServicesWS”.
• The instant application (iknowbase-instant-webapp-VERSION..war) is typically deployed to path “/ikbInstant”.
• The webdav application (iknowbase-instant-webapp-VERSION..war) is required to be deployed to path “/”. If the viewer application is deployed to / (default), the webdav application must be on a separate host (virtual host or server depending on application server type).

Security roles

During or after deployment, you need to configure security roles for the application. Again, the configuration method will vary from application server to application server.

ikbViewer

The ikbViewer has three security roles:

• The role IKB_USERS is meant for regular users who will need to access secured content.
• The role IKB_DEVELOPERS is meant for users who will develop iKnowBase applications.
• The role IKB_SYSADMINS is meant for users who will manage iKnowBase installations.

Note that it still possible to access iknowbase applications and content without being in any of these roles. However, without being in the IKB_USERS role, all content will be presented as the public user.

ikbStudio

The ikbViewer has a single security role:

• The role IKB_DEVELOPERS is meant for users who will develop iKnowBase applications. You will not be given access to the application, unless you are in this role.

ikbWebServices

The ikbWebServices has a single security role:

• The role IKB_WEBSERVICES_TRUSTED_USERS is meant for ikbWebServices client users.

ikbBatch

The ikbBatch has a single security role:

• The role IKB_SYSADMINS is meant for users who will manage iKnowBase installations.

ikbActiviti

The ikbActiviti has no security roles.

ikbProcessServicesWS

The ikbProcessServicesWS has no security roles.

ikbInstant

The ikbInstant has three security roles:

• The role IKB_USERS is meant for regular users who will need to access secured content if using container protection for Instant topics on /ikbInstant/private.
• The role IKB_DEVELOPERS is meant for users who will develop iKnowBase applications and gives access to Instant’s ikb$console.
• The role IKB_SYSADMINS is meant for users who will manage iKnowBase installations and gives access to Instant’s ikb$console.

ikbWebdav

The ikbWebdav has three security roles:

• The role IKB_USERS is meant for regular users who will need to access secured content.
• The role IKB_DEVELOPERS is meant for users who will develop iKnowBase applications and gives access to WebDAV’s ikb$console and ikb$runner.
• The role IKB_SYSADMINS is meant for users who will manage iKnowBase installations and gives access to WebDAV’s ikb$console and ikb$runner.

Advanced topics

Deploy with “/ikbViewer” prefix

The iKnowBase Viewer application iknowbase-viewer-webapp-VERSION.war has traditionally been deployed to /ikbViewer, but is by default from 6.4 deployed to /. The application will support requests using the old context root /ikbViewer when deployed to /.

The application can still be deployed to /ikbViewer or some other path of the customers choosing, but the context root must then be explicitly changed during deployment.

Background

On a given listening port, the web server should handle all the iKnowBase applications as well as all other custom applications. A typical set of handlers (endpoints) could be this:

• /ressurs, which is the resource file directory
• /ikbStudio, which is the Development Studio application
• /ikbWebServices, which is the WebServices application
• /ikbBatch, which is the batch application
• /, which is the main runtime application

With the setup above, you can access iKnowBase-pages using “//server/mypagename”.

Deployments before iKnowBase version 6.4 used context root /ikbViewer for the main runtime application, resulting in access to iKnowBase-pages using “//server/ikbViewer/mypagename”

From an iKnowBase perspective, the following requirements must be met if you want to change the context root:

• The main runtime application (the “ikbViewer” application) can be deployed with any endpoint you choose. We typically recommend “/”, but you may use “/ikbViewer” or “/ikb” if you want.

Update domain definition to match new endpoint

The final step is to make iKnowBase generate URLs to the new endpoints. From ikbStudio, edit the domain definition served by the endpoint, and update the relevant URL-prefixes:

• “path to iknowbase application” should be set to "/ikbViewer"
• “path to iknowbase page engine” should be set to "/ikbViewer/page"
• “path to iknowbase content server” should be set to "/ikbViewer/Content"