iKnowBase Development Toolkit

The iKnowBase Development Toolkit enables you to develop iKnowBase Plugins in your IDE and assemble a customer specific edition of the iKnowBase application including the required plugin changes.

While the development toolkit does not replace the standard iKnowBase declarative development model, it provides the developer with a supplement and alternative.

Getting started

Developers are strongly encouraged to participate in a workshop with the iKnowBase product development team before starting with the Development Toolkit.

Read the other chapters after “Getting started” for detailed information about iKnowBase plugins and technology.

About the build system

The Development Toolkit uses the Gradle build system for

• build logic
• project structure
• managing project dependencies
• start from command line (or some tool invoking the Gradle build)
• assemble from command line (or some tool invoking the Gradle build)

Gradle is supported by several of the major IDEs, enabling you to import the Gradle project into the IDE.

Requirements

Your should already have (or do it now):

• Java SE Development Kit matching your target environment (see release notes for supported Java version)
• The IDE of your choice (the sample build system requires gradle support)
• Downloaded iKnowBase distribution files for development (see next section)
• Database access to an installed iKnowBase Database Repository

Distribution files for development

The iKnowBase distribution files for development are

• sample-starter-singleproject-7.2.4.zip
• sample-starter-multiproject-7.2.4.zip
• sample-plugin-projects-7.2.4.zip

sample-starter-*

The sample-starter-* are complete examples for a Gradle setup for plugin development. You may use it as is, or develop your own build based on elements in the sample.

• gradle (directory): gradle wrapper for bootstrapping the build system
• gradle.properties: build properties
• application.properties: iKnowBase application configuration
• settings.gradle (multiproject only): project hierachy declarations

While the decision of single vs multi (hierarchical) project setups are entirely up to the developer, a few notes on the different types might be useful to get you started:

The sample-starter-singleproject is the simplest way to get started with development of a single plugin. It contains sample code for single plugin (sample-plugin-hello) to demonstrate what goes where. Recommended if you want to share this plugin with other projects/teams/customers.

The sample-starter-multiproject is intended when you want to maintain multiple plugins and you may deploy all projects contained within sample-plugin-projects-7.2.4.zip to this project. Recommended if you develop a set of plugins for a customer and you don’t intend to share these plugins.

sample-plugin-projects

The sample-plugin-projects zip contains a set of technology samples to help you get started developing plugins for iKnowBase. Intended used in a multi-project setup.

Step-by-step setup

1. Extract the provided development .zip files

Start with the sample-starter-* of your choice to create a build workspace.

sample-starter-multiproject only: If you want to add the sample projects, we suggest an extraction directory structure like this:

sample-starter-multiproject
    sample-plugins
        // contents of sample-plugin-projects here

2. Configure build

iKnowBase build script plugins

The starters contain references to a set of Gradle script plugins for iKnowBase plugin development. If you prefer you may download these and load them from you local file system.

The scripts are used in:

• sample-starter-multiproject: gradle.properties has reusable variables for these scripts. The variables are used in build.gradle.
• sample-starter-singleproject: build.gradle

settings.gradle (sample-starter-multiproject only)

Add your plugin projects here. The file contains examples for including the iKnowBase samples as well as set up your custom plugins.

When adding your own plugins, you need to create the project structure that goes with it. The directory structure depends on the type of plugins you create. Each project should contain a build.gradle file (see next section for build.gradle description).

Example:
For the project definition in settings.gradle:

    include 'custom-plugins'
    include 'custom-plugins:custom-java-jar-plugin'
    include 'custom-plugins:custom-groovy-jar-plugin'
    include 'custom-plugins:custom-java-war-plugin'

You need to create the project structure:

    sample-starter-multiproject

        custom-plugins

            custom-java-jar-plugin
                build.gradle
                src
                    main
                        java
                        resources
                        
            custom-groovy-jar-plugin
                build.gradle
                src
                    main
                        groovy
                        resources                        

            custom-java-war-plugin
                build.gradle
                src
                    main
                        java
                        resources
                        webapp


              

build.gradle for your plugin projects (sample-starter-multiproject only)

We recommend using a build.gradle file per project as shown above. The build.gradle will set up plugin project specifics such as:

• Build plugins
• Dependencies

For all projects: Apply the iKnowBase project configuration to get the basic configuration and dependency setup

// iKnowBase project configuration
apply from: "$iKnowBaseGradleProject"

For a java (.jar) project the script above will the basics. Nothing more is required.

For a groovy (.jar) project:

apply plugin: 'groovy'

For a java web application (.war) project:

apply plugin: 'war'

// Customized war that will add module source as jar to WEB-INF/lib instead of the usual WEB-INF/classes
// This facilitates easy plugin deployment and avoids name collision for war resources with the same name (
// like "spring.factories") when patching with multiple war files
war {
	// First we'll remove the main build output from the classpath
	classpath = classpath.filter {!(it.name.equals('main'))}
	// And then add the module's jar archive
	classpath jar
}

See sample projects for relevant build.gradle content.

build.gradle for your root project (sample-starter-multiproject only)

Include your plugin projects in the dependencies section (NOT in buildscript dependencies!).

3. Configure application.properties

• application.properties:

- Set spring.datasource.url, spring.datasource.username and spring.datasource.password to match your existing iKnowBase database repository

4. Test from command line

Start a command prompt in the project root directory.

The first gradle command entered will trigger download of the gradle binaries and iKnowBase dependencies.

To provide a list of build tasks available to you:

    gradlew tasks

To list all projects in your build (sample-starter-multiproject only):

    gradlew projects

To start the iKnowBase web server with all plugins (that you’ve added to the root project runtime) on localhost:

    gradlew bootRun

You can access the iKnowBase installation at http://localhost:8080 and verify that everything is up and running.

5. Import in your favorite IDE

Now that you know that the base build is OK, it’s time to import it into an IDE and start development.

Note: If you change gradle build scripts (settings.gradle, build.gradle) you need to re-import / refresh to get the updates in your IDE.

IntelliJ IDEA

Open the root project’s build.gradle. The IDE will import and setup the project for you. IntelliJ IDEA is recommended.

Eclipse

Eclipse requires additional gradle plugin: https://github.com/spring-projects/eclipse-integration-gradle/. Once installed, import the root project’s build.gradle. After import select all projects and adjust project properties for Gradle: Project > Properties > Gradle: Classpath sorting strategy: As returned by build script

6. Setup iKnowBase web server run configuration in IDE

To start iKnowBase with all plugins from the IDE, add an application run configuration with:

• Classpath of root project (or a project that has applied the iknowbaseGradleruntimeEngine configuration)
• Main class: com.iknowbase.BootEmbeddedApplication
• Program args: <no arguments>

Assemble your plugins

All projects may be assembled using:

    gradlew assemble

The resulting jar/war will be generated in <project dir>/build/libs/.

See Installation Guide > Java applications > Installing plugins and patches for deployment details.

Plugin assembly

By using the toolkit, you’ll be able to develop your own as well as include externally developed plugins.

Once developed, a plugin will be assembled to one of two forms:

• .jar (Java archive)
• .war (Web archive) (should only contain .jar files, see war packaging section)

.jar plugin

A .jar plugin contains

• compiled classes
• resources

and is the typical choice if you do not require additional libraries.

You may still use the .jar plugin if you require additional libraries, but you must then collect all the library .jars yourself.

.war plugin

A .war plugin contains:

• jar files (classes and resources)
• [WebLogic] web application configuration
• [WebLogic] web application resources

and is the typical choice if you need more than what is offered through a .jar.

Note: [WebLogic] When assembling a new war, the content in the resulting plugin .war file will override the existing content in the source iKnowBase .war.
Note: [Embedded] Since the embedded server can only add jar’s to the classpath, an assembled .war file must be extracted and the directory’s WEB-INF/lib must be added to loader.path.

Libraries

Note: All libraries in use by the iKnowBase web application are, due to the current build system, available to your plugin at both compile and runtime. However, all “com.iknowbase” packages except “com.iknowbase.api” are considered internal to iKnowBase and use of these packages are prohibited and without support.

All dependencies are managed in your project’s build.gradle file.

The plugin projects will get all libraries distributed through the iKnowBase application with the script plugin:

// iKnowBase project configuration
apply from: "$iKnowBaseGradleProject"

The project may also bring additional libraries, provided they are not conflicting with the existing libraries.

Additional libraries will automatically be included in the resulting plugin .war file when using the .war plugin.

The iKnowBase application container

The iKnowBase application is a java web application based on the Spring Framework (http://projects.spring.io/spring-framework/) and Spring Boot (http://docs.spring.io/spring-boot/docs/@spring-boot.version@/reference/htmlsingle/). Your code will need to be deployed into this application, and can then be used from several points and for several purposes.

Extension points

The table shows what type of extensions and modifications are available

Configuring the application container

The Spring container keeps track of java beans for the lifetime of the iKnowBase application, and many plugins will need to provide their own beans. To expose your beans, you will need to create and expose a configuration class:

• Create your own Spring @Configuration class for bootstraping your plugin
• Create a file “META-INF/spring.factories” containing information about the configuration class

In your source code, this typically looks like this:

• src/main/java/YOUR_PACKAGE/YOUR_SPRING_CONFIGURATION_MODULE (or /src/main/groovy/...)
• src/main/resources/META-INF/spring.factories

The Spring Configuration classes are plain Java/Groovy classes annotated with @Configuration (org.springframework.context.annotation.Configuration). A configuration class allows Spring Bean generation and web application context customizations. The class may set up @ComponentScan and/or contain methods annotated with @Bean (org.springframework.context.annotation.Bean) where the resulting bean name is the name of the method and the bean type is the declared and returned object.

To load the Spring Configuration class, create src/main/resources/META-INF/spring.factories in your plugin project with:

org.springframework.boot.autoconfigure.EnableAutoConfiguration=<YOUR_PACKAGE/YOUR_SPRING_CONFIGURATION_MODULE>

Spring @Beans

Spring beans are objects managed by the Spring container. You add them manually from a @Configuration class or automatically thorough @ComponentScan on your @Configuration class.

Inject services

The table below shows the iKnowBase specific services that you can @Autowire in your Spring beans. Note that these services are not available as resolved method arguments in a Spring Controller.

The services below are available directly for backward compatibility reasons. They can (and should) be accessed through the ContentServicesEngine or PresentationServicesEngine above.

Inject configuration

The iKnowBase applications can be configured as described in Installation Guide > Configuration . You may also add your own configuration keys to this set.

The configurations can be injected in the @Autowired or a @Configuration class’s @Bean methods using @Value-annotation. In the latter case, you pass the values to your actual bean when constructing the bean.:

If a default value has not been specified, the configuration MUST exist.

Spring MVC Controller

The Spring MVC Controller is used to expose your extension at the specified web request path. See the Spring documentation and the provided iKnowBase Development Toolkit samples.

The concept of using a Spring MVC Controller is as follows:

• Make sure you have a @Configuration class that bootstraps your plugin.
• If using @ComponentScan:
• Create a java-class (a controller), annotated with @Controller.
• If manually created with @Bean:
  • Create a java-class (a controller), annotated with @RequestMapping.
  • Create an instance of this java-class in your @Configuration class.
• At runtime, the application will look for a managed Bean with a @RequestMapping that matches the request, and run it.

Inject services and configurations

Since a Spring MVC Controller is just a regular Spring Bean, you can wire services and configurations as for any @Bean.

Inject method arguments

When Spring runs your @RequestMapping method, it will automatically pass parameter values to that method. In addition to the default argument resolving available for Spring MVC (like HttpServletRequest, HttpServletResponse, etc), the iKnowBase web application supports it’s own set of services and resolved arguments.

The following table shows the iKnowBase specific services available to you in the Spring configuration and controller classes and where it can be injected.

Security

Controllers may be annotated with Spring Security annotations if you want to restrict access to a controller method.

Some examples of standard expressions included with Spring Security:

In addition to the standard Spring Security annotations, the following iKnowBase specific annotations are supported:

executionUser and authenticatedUser will normally be the same, but if an administrator has switched to a different user in the current session, the authenticatedUser will be the administrator and the executionUser will be the switched to user.

Static web resources

Static web resources, such as css, javascript and images, can be included in your plugin project. The resources will be assembled and served from jar files.

• Directory in plugin source tree: src/main/resources/META_INF/resources/plugin-resources
• Directory in assembled jar file: META_INF/resources/plugin-resources
• Web path: //server/application-root/plugin-resources

Note! The static resources namespace will be shared among all plugins. Be sure to use plugin specific directories for your static content.

Alternatively, static web resources may be served as an additional war project of your choosing, like /custom-resources. The /ressurs is by default taken by the iknowbase-resources. See iknowbase.properties if you need to override this behavior.

Activiti

Activiti processes can be extended using Execution Listeners , Task Listeners and Service Tasks .

The iKnowBase Repository Model is accessible from task and execution listeners and service tasks, provided is has been mapped in the process definition.

Using a plugin from iKnowBase Development Studio groovy components

Java or Groovy classes may be used from groovy components you define in iKnowBase Development Studio. This enables you to create reusable components in plugins and access them in both the plugin and the traditional development model.

Solr Server

The iKnowBase application server provides a SolrClient-object for easy access to the search functionality of a Solr server. This is often configured using the installation properties of an installation, but if you need more control of the SolrServer connection, you can use the Development Toolkit to configure the server yourself:

@Bean(name="acmeInternetSearch")
public SolrServer createSolrServer() {
    CloudSolrServer cloudSolrServer = new CloudSolrServer("zookeeper.solr.acme.com");
    cloudSolrServer.setParser(new XMLResponseParser());
    return cloudSolrServer;
}

When the above @Bean is exposed to the application container (through a @Configuration class), iKnowBase will automatically discover it, and use it as the basis of a search connection. The name specified in the @Bean will be used for the search server.

Form

iKnowBase simplifies form development that targets iKnowBase documents with

• Bean-to-document mapping
• Form Processor Macros
• Classic integration (External Forms)

See sample: sample-plugin-form

Bean-to-document mapping

To easily convert between an iKnowBase document and a standard Java Bean (Not a Spring Bean), iKnowBase provides annotations for use in the Java Bean that enables automatic conversion and efficient development.

Form Processor

The iKnowBase Presentation Services Form Processor aids with conversion, loading, insert and update of iKnowBase AttributeMapping annotated beans (see previous section). It also provides FreeMarker macros to ease integration with the Java Bean and iKnowBase Metadata.

Form integration with iKnowBase Classic components

An iKnowBase Classic Form may now also be configured as an External Form. An External Form supports mapping against a URL path, where the plugin containing the requested form is available.

If you store the External Form reference on the document, the plugin form will be used in generic iKnowBase Classic edit links.

An External Form may also be connected to document types and set as default form to allow using the plugin form on documents that have no specific form registration.

Normal Quicklink and Target integration for forms also applies to an External Form.

You may convert a Clasic Form component between Classic Form and External Form and thus keep the preexisting form GUID used on the documents.

Java based versions of News Article and Admin Form are available in iKnowBase Content Studio and External Form data has been registered. The form is classic by default, but may easily be converted to an External Form supported by Java. See source code for the forms and their required metadata.

Available samples

The following samples are available:

iKnowBase Reference Plugins

While the samples listed above are focused on demonstration of technology, the iKnowBase distribution includes two complete real life plugins that you may use as reference. The source code is provided alongside the distribution.

Troubleshooting

Classpath issues in Eclipse based IDEs

When importing the iknowbase-plugins project with subprojects in Eclipse, the classpath defaults generated by the eclipse plugin is not correctly ordered.

Resolve the issue with

• During Gradle project import: Uncheck "Enable dependency management"
• For all IDE helper projects:
  • Project Properties > Gradle > Classpath sorting strategy: Select "As returned by build script"

Out of memory issues when building gradle project model

You may encounter issues when building the gradle project model during import in Eclipse, especially if you are lading all the sample projects.
Adjust your gradle.properties file and enable

org.gradle.jvmargs=-Xms128m -Xmx1024m

Accented (Norwegian) text loaded using resource bundle has wrong encoding

Make sure the property files (*.properties) are located in source tree ‘src/main/resources’ and NOT ‘src/main/java’. Encode all accented characters using unicode notation "\u".