| iKnowBase Development Toolkit | ||
|---|---|---|
| Previous | Next | |
| iKnowBase WebDav Server | User Administration | |
The iKnowBase Development Toolkit enables you to develop iKnowBase Java Plugins and assemble a customer specific edition of the iKnowBase applications containing
While the development toolkit does not replace the standard iKnowBase declarative development model, it provides the developer with a supplement and alternative.
By using the toolkit, you’ll be able to develop your own as well as include externally developed plugins. The following sections assume that you’ve set up the dev toolkit workspace as described in Getting started .
A plugin can be added using:
Some plugins are dependant of the infrastructure provided a specific iKnowBase application and is therefore restricted to that application.
The plugin projects may reuse the libraries included in the target iKnowBase application as well as bring their own libraries, provided they are not conflicting with the existing libraries.
Warning: Developers must not include other versions of the libraries already included in the iKnowBase distribution.
Library dependencies are managed in your project’s
build.gradle file.
The tookit workspace provides a "
<application>-webapp"-project for each iKnowBase application and serves as a drop box for adding libraries and configuration to the iKnowBase application’s WEB-INF directory. It may also be used for applying iKnowBase Java patches, if available.
Structure of the "
<application>-webapp" project:
You can develop your own plugins for iKnowbase and include them in your custom iKnowBase application.
The following sections discuss how to create plugin projects, which technologies and services are available to you and how you can go about solving different scenarios.
The iKnowBase applications are java web applications based on Spring MVC technology. Plugins are hosted in one or more of these applications and can extend the functionality in various areas using the infrastructure provided by the application.
The following table shows what type of extensions and modifications are available in the different iKnowBase applications:
| Plugin type | Language | Viewer | Batch | Studio | WebServices | ProcesServicesWS | Webdav | Instant |
|---|---|---|---|---|---|---|---|---|
| Spring MVC Controller | Java | X | ||||||
| Spring MVC Controller | Groovy | X | ||||||
| Spring MVC View | Java | X | ||||||
| Spring MVC View | Freemarker | X | ||||||
| Spring MVC View | Groovy | X | ||||||
| Spring MVC Static plugin-resources | N/A | X | ||||||
| Java extension | Java | X | X | |||||
| Java Activiti extension | Java | X | X | |||||
| Groovy extension | Groovy | X | ||||||
| Freemarker extension | Freemarker | X | ||||||
| Log4j configuration | Log4j | X | X | X | X | X | X | X |
Add your own plugin projects in the dev toolkit using the following steps:
include "custom-plugins" if not already activated.
project (":custom-plugins").projectDir = new File(customPluginsDirName), where
customPluginsDirName is set in gradle.properties.
include "custom-plugins:myplugin1", where myplugin1 can be named anything.
gradlew createCustomPlugins in your workspace directory.
The project is by default set up as an iKnowbase Viewer plugin. Modify the plugin’s build.gradle according to your target application.
apply from: "$ikbInstallationToolkitDir/gradle/iknowbase-viewer-plugin.gradle" (default)
apply from: "$ikbInstallationToolkitDir/gradle/iknowbase-activiti-plugin.gradle"
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 following table shows the iKnowBase specific services available to you in a Spring MVC Controller and where it can be injected:
| Service | Description | Constructor | Request | Library dependency |
|---|---|---|---|---|
| javax.sql.DataSource | DataSource for accessing the iKnowBase Database Repository. | X | ||
| com.iknowbase.api.contentservices.v2.service.DocumentService | iKnowBase Content Services API for accessing the iKnowBase Content Repository. | X | iknowbase-contentservices-api | |
| com.iknowbase.api.presentationservices.client.ActivitiClient | iKnowBase Activiti Client for accessing the Activiti process engine. | X | iknowbase-presentationservices-api | |
| com.iknowbase.api.presentationservices.client.SolrSearchClientProvider | iKnowBase Solr Search Client Provider for accessing the configured Solr Search Clients. | X | iknowbase-presentationservices-api | |
| com.iknowbase.api.presentationservices.client.SpringMvcPageEngineClient | iKnowBase Spring MVC Page Client for accessing the iKnowBase Page Engine. | X | iknowbase-presentationservices-api |
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 controller’s constructor using @Value-annotation:
| Configuration option | Default value |
|---|---|
| @Value(“${JAVA_HOME}”) String javaHome | not set |
| @Value(“${JAVA_HOME:#{null}}”) String javaHome | null |
| @Value(“${JAVA_HOME:null}”) String javaHome | “null” |
| @Value(“${com.iknowbase.pageEngine.contentCacheEnabled:false}”) boolean contentCacheEnabled | false |
| @Value(“${thisKeyShouldNotBePresentUseDefault:default_value}”) String thisKeyShouldNotBePresentUseDefault | “default_value” |
If a default value has not been specified, the configuration MUST exist. If the configuration is missing, the controller will fail to start.
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.
src/main/resources/META_INF/resources/plugin-resources
META_INF/resources/plugin-resources
//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 can be placed under /custom-resources, see iKnowBase Installation Guide . The plugin project “custom-resources” will be created as part of the Development Toolkit and default “mounted” on /custom-resources when run in the IDE. The custom-resources war can be deployed using the same techniques used for deploying iknowbase-resources (/ressurs).
iKnowBase Viewer will scan for and start controllers under the
com.iknowbase.plugin package level. Your controller can be added anywhere below this package, but will not be started if placed outside of this package.
Several services are available for use by your plugins if the required library dependency is added to your project. With the exclusion of the “iKnowBase APIs” added as part of the applied gradle plugin, you are prohibited from using any java libraries prefixed with "
iknowbase-" as they are internal to the iKnowBase application.
The following Spring MVC Controller samples are included when installing the Development Toolkit:
| Sample name | Description | Target application(s) |
|---|---|---|
| sample-activiti-viewer-controllers | Demonstrates using DataSource, DocumentService and ActivitiClient. | Viewer |
| sample-viewer-plugin-config | Demonstrates accessing iKnowBase Configuration options. | Viewer |
| sample-viewer-plugin-freemarker | Demonstrates various ways of using freemarker as presentation view technology. | Viewer |
| sample-viewer-plugin-groovy | Demonstrates writing controllers in groovy and use freemarker as presentation view technology as well as various ways of using groovy as presentation view technology. | Viewer |
| sample-viewer-plugin-hello | Demonstrates a very simple controller for a minimal start. | Viewer |
| sample-viewer-plugin-msoffice | Demonstrates using a third party library for generating Excel files. | Viewer |
| sample-viewer-plugin-static-content | Demonstrates using static content, such as css, js and images. | Viewer |
The samples demonstrate access to and use of the services provided by iKnowBase as well how you can build using Spring MVC Controllers. They are all included in the iknowbase-plugins workspace, but each component must be enabled in the
<application>-ide-helper if you want to include it in your custom iKnowBase application.
You may extend iKnowBase using plain Java or Groovy. These components may be used from controllers, groovy or from Activiti process instances.
A standard Java or Groovy class is accessible from controllers as you normally would use java classes.
Java or Groovy classes may be used from Groovy. The Groovy code can be part of a plugin or part of the traditional iKnowBase development model (templates, presentation styles). This enables you to create reusable components in plugins and access them in both the plugin and the traditional development model.
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.
A client for accessing the Activiti process engine is available for injection in controllers. See Available services .
The following Activiti related samples are included when installing the Development Toolkit:
| Sample name | Description | Target application(s) |
|---|---|---|
| sample-plugins:sample-activiti-process-definitions | Demonstrates a project containing Activiti process definitions. Also demonstrates how to map the iKnowBase RepositoryModel, listeners and service task. | |
| sample-plugins:sample-activiti-viewer-controllers | Demonstrates using DataSource, DocumentService and ActivitiClient. | Viewer |
| sample-plugins:sample-activiti-extensions | Demonstrates task and execution listeners for Activiti. Also demonstrates how to use the iKnowBase RepositoryModel. | Viewer, Batch |
| ikb-plugins:ikb-process-studio | The iKnowBase Process Studio implemented as a plugin. Demonstrates developing a full plugin (not a technology sample). | Viewer |
As the Activiti process engine runs in both iKnowBase Viewer and Batch, listener extension plugins must be added to both applications.
Most of the iKnowBase application configuration is set according to Installation Guide > Configuration , but the log4j configuration is not.
Log4j configuration files are present under WEB-INF/classes in each iKnowBase application and you may add additional configurations or override configurations by adding files to the
<application>-webapp projects. Files added here take presedence over files found in the standard iKnowBase application.
You may also start the
<application>-ide-helper with a specific log4j configuration by adding the jvm option
-Dlog4j.configuration=file://<your configuration file> to the run configuration in your IDE.
The custom iKnowBase applications are assembled with the Gradle build system:
Access your iknowbase-plugins directory from command line and issue the appropriate command:
| Command | Description |
|---|---|
| gradlew tasks | List all available tasks. |
| gradlew assembleAll | Assemble all custom iKnowBase applications in plugin root project. |
| gradlew assemble-batch | Assemble custom iKnowBase Batch with plugins. |
| gradlew assemble-custom-resources | Assemble custom resources. |
| gradlew assemble-instant | Assemble custom iKnowBase Instant with plugins. |
| gradlew assemble-processervicesws | Assemble custom iKnowBase Process Services WS with plugins. |
| gradlew assemble-studio | Assemble custom iKnowBase Studio with plugins. |
| gradlew assemble-viewer | Assemble custom iKnowBase Viewer with plugins. |
| gradlew assemble-webdav | Assemble custom iKnowBase Webdav with plugins. |
| gradlew assemble-webservices | Assemble custom iKnowBase Web Services with plugins. |
Assembled applications will be added to
target/distribution in your workspace directory.
Developers are strongly encouraged to participate in a workshop with the iKnowBase product development team before starting with the Development Toolkit.
Due to the availability of the Activiti Process Designer in Eclipse and the initial focus of extending Activiti in iKnowBase through plugins, the Eclipse based Spring Tools Suite (STS) is currently the recommended IDE for working with the iKnowBase Development Toolkit. The following sections will provide a step-by-step approach to setting up your environment with STS 3.4.0 as your IDE.
The Development Toolkit uses the Gradle build system for
Gradle is supported by several of the major IDEs, enabling you to import the iknowbase-plugins application.
Unzip iknowbase-6.5-bin.zip in a directory. The zipfile contains an iKnowBase-6.5 directory, from now on referred to as "
IKB_DIST_DIR".
Create a directory that will contain your iKnowBase Development Toolkit, from now on referred to as "
IKB_DEV_ROOT_DIR".
Extract the contents of "
IKB_DIST_DIR\dev\workspace.zip" to "
IKB_DEV_ROOT_DIR". Optionally rename the resulting "
workspace" directory to a name of your choice. We’ll assume that you used the name "
workspace" throughout this tutorial.
Edit "
IKB_DEV_ROOT_DIR\workspace\gradle.properties"
<IKB_DIST_DIR>
<IKB_DEV_ROOT_DIR>
db.*" configuration options according to your iKnowBase Database Repository.
Edit "
IKB_DEV_ROOT_DIR\workspace\settings.gradle"
gradle.properties modified in the previous step.
Start a command line shell and navigate to "
IKB_DEV_ROOT_DIR\workspace".
gradlew createDeveloperEnvironment" to set up everything defined in your
settings.gradle
path_to_gradle_installation). Normally to "
USER_DIR\.gradle\wrapper\dists\gradle-<VERSION>-all\<instance id>\gradle-<VERSION>", but will depend on your environment. We’ll need this directory in the Spring Tools Suite IDE.
Start Spring Tools Suite and add the following components:
Adjust Gradle installation
path_to_gradle_installation"
IKB_DEV_ROOT_DIR/workspace"
Navigate to "
viewer-ide-helper".
Create a run configuration for "
viewer-ide-helper":
Verify that you can access:
When importing the iknowbase-plugins project with subprojects in Eclipse, the classpath defaults generated by the eclipse plugin is not correctly ordered. The iKnowBase Quickstart library must be added before the war-file WEB-INF libraries.
Resolve the issue with
At the time of this writing, the newest GRECLIPSE plugin has support for Groovy v2.1, but the included Groovy in iKnowBase is v2.2. This will generate a warning on Groovy projects. Set the Groovy compiler to 2.x And you’ll be able to proceed.
You may encounter issues when building the gradle project model during import in Eclipse. Adjust your
gradle.properties file and enable
org.gradle.jvmargs=-Xms128m -Xmx256m
The following libraries will be excluded from .war file when the custom .war is assembled:
| Previous | Top | Next |
| iKnowBase WebDav Server | User Administration |