1. Introduction

iKnowBase iKnowBook is a wiki solution for iKnowBase, developed as an iKnowBase JavaSDK plugin.

The solution is a simple, user-friendly tool for writing and maintaining structured documentation in a wiki-style way, ie iknowbooks. The solution contains logic for creating, maintaining and displaying iknowbooks, structured in chapters. Access rights are controlled per iknowbook and per section. Different users can edit different sections simultaneously.

2. Metadata

There are two document types in use: IKNOWBOOK and IKNOWBOOK_SECTION

An iKnowBook is stored as an iKnowBase document with document type IKNOWBOOK. Chapters are stored as subdocuments with document type IKNOWBOOK_SECTION.

The solution uses standard iKnowBase metadata in addition to custom iKnowBook metadata. The plugin contains scripts which may create and update metadata upon plugin startup. See Configuration for more details.

3. User interface

The iKnowBook solution consists of an overview page and a detail page. The overview page is available at /<context-root> and lists all the iknowbooks. The detail page is available at /<context-root>/<book-id> and displays the content of an iknowbook, including a navigational table of contents.

Iknowbooks are presented as thumbnails on the overview page. To get thumbnails of the same size, you should use images which are larger than the configured thumbnail transformation and with the same ratio.

Tip
After uploading an image, you can edit the image and crop it using the defined iknowbook crop area in the image picklist/image archive.

Click on a book on the overview page to open the detail page for the book. The detail page is available in two modes: view and edit. Enter edit mode to enable inline edit of titles and text content.

Access to create iknowbooks is controlled by the iKnowBase iKnowBook ACL. Access to the iknowbooks themselves are controlled by ACLs on the iknowbook and section documents.

4. Installation

  1. The ACL configured in no.acando.iknowbase.plugin.iknowbook.adminAclExternalKey (Default value IKNOWBOOK_ADMIN_ACL) must be created before you deploy the application.

  2. Set REQUIRED configuration options, see Configuration section below.

  3. Application deployment: See the iKnowBase Installation Guide for instructions for Java Plugin installation.

4.1. Dependencies

The application has these library dependencies, which you’ll need to deploy as well:

The application also relies on iKnowBase Content Studio. This is almost always deployed, but if not you’ll need to deploy that as well.

4.2. Metadata

The iKnowBase iKnowBook plugin requires a set of metadata, which automatically gets installed upon startup of the plugin. You may disable this behaviour, see the configuration table below.

4.3. Configuration

4.3.1. Configuration options

Note
You must disable Spring Boot’s default flyway integration to avoid conflict with Spring Boot’s Flyway setup.

The following configuration options are available for iKnowBase iKnowBook:

Property Description

flyway.enabled

REQUIRED: Set this to false to disable Spring Boot’s default flyway integration. We’re handling this our selves and per plugin.

no.acando.iknowbase.plugin.iknowbook.adminAclExternalKey

External key for the ACL to be used to control access to create iknowbooks. Default value IKNOWBOOK_ADMIN_ACL.

no.acando.iknowbase.plugin.iknowbook.databaseMigration.enabled

Execute database migration (metadata) upon startup. Default value true.

no.acando.iknowbase.plugin.iknowbook.databaseMigration.repair

Execute repair for failed database migrations (metadata). Default value false.

no.acando.iknowbase.plugin.iknowbook.databaseMigration.tableName

Name of database table to be used for database migrations (metadata). Default value IKNOWBOOK_FLYWAY.

no.acando.iknowbase.plugin.iknowbook.databaseMigration.baselineVersion

The version to tag an existing schema with when executing baseline. Default value 1.

no.acando.iknowbase.plugin.iknowbook.logoutLink

The link used to log out from the application. Default value /ikb$auth/logout.

no.acando.iknowbase.plugin.iknowbook.thumbnailTransformation

The image thumbnail transformation to use on the overview page. Default value image:png:resize:700:500:best-fit-shrink.

no.acando.iknowbase.plugin.iknowbook.thumbnailImageDefault

Url to an image to use as default thumbnail on the overview page.

no.acando.iknowbase.plugin.iknowbook.valueSetAclExternalKeys

Comma separated list of external keys for ACLs which should be available for use in the iknowbooks. No default value supplied, ie all ACLs will be available for use.

4.3.2. Crop area

Add a crop area with the same width and height as the thumbnail transformation. This can be used during image edit to crop an image to a ratio which matches the configured transformation.