iKnowBase Process Services for Activiti

The iKnowBase Process Services for Activiti is a set of tools and techniques that enables the building of process-centric applications using the combined power of iKnowBase® and Activiti®. The iKnowBase Process Services for Activiti comprises the following items:

• An embedded Activiti process engine, inside the iKnowBase ikbViewer application
• Extensions to the Activiti engine, providing easy access to the iKnowBase repository from Activiti ScriptTasks
• Extensions to the iKnowBase engine, providing easy access to the Activiti process engine from iKnowBase scripts
• An “Activiti form” portlet, providing Activiti form display capabilities from iKnowBase applications
• iKnowBase Process Studio (optional iKnowBase web application plugin), a web-based tool for starting and monitoring processes and completing user tasks (mainly intended as a demo application)
  • Also contains Activiti process samples that can be executed in iKnowBase Process Studio

Preparations

In order to use the iKnowBase Process Services for Activiti, the following must be done:

• The Activiti repository tables must be installed into the iKnowBase database. This is described in the Installation Guide, in the chapter Database Repository.
• The Activiti engine must be enabled. This is described in the Installation Guide, in the chapter Configuration.
• Developers must download Eclipse, and install the Activiti designer plugin. For more information, see the http://www.activiti.org web site.
• Install iKnowBase Process Studio plugin. This module was automatically installed in iKnowBase < 7.0 but is now an optional plugin. See installation guide for details regarding plugin installation.
• Optionally, the Activiti process samples may be deployed. These are available for download from the resource directory, often deployed as http://www.example.com/ressurs/iknowbase.

Developing process applications

Developing process applications typically comprises the following steps:

• Develop the BPMN process, using Activiti Designer:
  • Wherever you want to have user interaction, set up a a UserTask in Activiti. Declare the form items you want to edit in the process model.
  • Save the BPMN file to disk, give it the extension .bpmn20.xml, and install into the repository: iknowbase <propertyfile> deployActivitiResource <bpmn file>
• Develop the iKnowBase applications, using the iKnowBase Development Studio:
  • Use the ScriptViewer portlet to load information from Activiti, for things such as inboxes and process overviews (presentations, generally).
  • Use the Activiti Form portlet to configure forms that start Activiti processes and complete Activiti UserTasks.
  • Use the ScriptAction to implement custom controllers.

The integration mechanisms between the two technologies (iKnowBase and Activiti) are kept intentionally simple:

• From Activiti, the Activiti ScriptTask has access to a script object called “iknowbase”, which provides access to the iKnowBase ServiceAPI and database
• From iKnowBase, any Groovy template (the ScriptViewer and the ScriptAction in particular) has access to a script object called “bpmClient”, which provides access to the Activiti API

iKnowBase ships with a ProcessStudio application that contains sample data.

Accessing Activiti data from a ScriptViewer

This groovy script shows the fundamentals of accessing and presenting data from an iKnowBase component:

// Prepare some utitlity variables 
def engine = bpmClient.activitiEngine

// Create a query using Activiti apis, and load data
def query = engine.historyService.createHistoricProcessInstanceQuery().startedBy("orcladmin").orderByProcessInstanceId().desc()
def rowcount = query.count()
def instances = query.listPage(1, 20)

// Render data using the groovy MarkupBuilder which is automatically supplied
html.div {
    h1 ("Process instances started by orcladmin, ordered by processInstanceId (rows 1-20)")
    table {
        tr {
            th ("Process Definition Id")
            th ("Process Instance Id")
            th ("Start time")
        }
        instances.each { instance ->
            tr {
                th (instance.processDefinitionId)
                th (instance.id)
                th (instance.startTime)
            }
        }
    }
}

Accessing iKnowBase data from a ScriptTask

This groovy script shows the fundamentals of accessing and working with iKnowBase data from an Activiti ScriptTask:

import com.iknowbase.api.contentservices.v2.model.*

// Init
def userref = new UserReference().withUsername(initiator)
def docref = new DocumentReference().withId(ikbDocumentId)

def document = iknowbase.documentService.getDocument(
    userref,
    docref,
    GetOperationEnumeration.MIN,
    GetOperationEnumeration.NONE,
    GetOperationEnumeration.NONE
)

document.setDescription(document.getDescription() + "<p>Activiti process: Document approved</p>")

iknowbase.documentService.saveDocument(
  userref,
  document,
  SaveOperationEnumeration.MERGE,
  SaveOperationEnumeration.NONE,
  SaveOperationEnumeration.NONE,
  null, null, null, false
)

Using a form to start processes and complete UserTasks

First, define an Activiti StartEvent or UserTask with the relevant form properties. The XML below is an extract from the Activiti BPMN definition:

<userTask id="registerissue" name="Register issue" activiti:assignee="${initiator}"
          activiti:formKey="urn:iknowbase:form:guid:C26AD8CA297355DCE040000A180062E2">
    <extensionElements>
        <activiti:formProperty id="hdTitle" name="Title" type="string" required="true"></activiti:formProperty>
        <activiti:formProperty id="hdDescription" name="Description" type="string"></activiti:formProperty>
        <activiti:formProperty id="hdPriority" name="Priority" type="long"></activiti:formProperty>
        <activiti:formProperty id="hdCategory" name="Category" type="long"></activiti:formProperty>
    </extensionElements>
</userTask>

Then, in iKnowBase, define a page with an Activity Task Form component based on a FreeMarker template such as this one:

[#macro showForm]
<h2>Comments</h2>
[@form.form]
    <table>
	<tr>
		<td>[@form.label bind="task.hdTitle" /]</td>
		<td>[@form.input name="task.hdTitle" /]</td>
	</tr>
	<tr>
		<td>[@form.label bind="task.hdDescription" /]</td>
		<td>[@form.input name="task.hdDescription" type="textarea" /]</td>
	</tr>
	<tr>
		<td>[@form.label bind="task.hdPriority" /]</td>
		<td>[@form.input name="task.hdPriority" type="select" attribute="IKB_PRIORITY" /]</td>
	</tr>
	<tr>
		<td>[@form.label bind="task.hdCategory" /]</td>
		<td>[@form.input name="task.hdCategory" type="select" attribute="IKB_SUBJECT"  /]</td>
	</tr>
    </table>
    [@form.button name="submit"      action="submit" attributes='accesskey="x"'      ]Complete task[/@form.button]
[/@form.form]
[/#macro]

[#macro thankyou]
<h1>Thank you!</h1>
<p>Your comment has been submitted. Click to view
<a href="/dev/activiti/processdefinitions/processinstance?processInstanceId=${form.data["task"].processInstanceId}">process details</a>.</p>
[/#macro]

[#if form.currentCommand.action! == 'submit']
    [@thankyou /]
[#else]
    [@showForm /]
[/#if]

A couple of items of interest:

• The Activiti UserTask defines a “formKey” attribute, which could be used to reference the target (e.g. referring to the guid of the FreeMarker template)
• The iKnowBase Activiti Form uses the FreeMarker directives form.form, form.label, form.input and form.button to generate the form
• The template form items use a name on the format "task. <propertyname>" to refer to the UserTask properties
• The template items “task.hdPriority” and “task.hdCategory” in the example refer to an iKnowBase attribute to get a proper control with proper defaults
• The template is used both for initial rendering and after submit, and uses the test “form.currentCommand.action! == 'submit'” to detect the phage

See the chapter Activiti Form Viewer in iKnowBase API Reference for further details.