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 and developer 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 engine must be enabled. This is described in the Installation Guide, in the chapter Viewer module.
• 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 and easily available using the Help-link in iKnowBase Process Studio.

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 .bpmn, and install into the repository: iknowbase <propertyfile> deployActivitiResource <bpmn file> or by using iKnowBase Process Studio
• Develop the iKnowBase applications, using the iKnowBase Development Studio:
  • Use the Template Viewer 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 Script Target to implement custom controllers.

The iKnowBase applications may also be implemented in Java.

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 Template Viewer and the Script Target in particular) has access to a script object called “bpmClient”, which provides access to the Activiti API

Your process data will be available in iKnowBase Process Studio.

Accessing Activiti data from a Template Viewer

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.

Associating an Activiti Process with an iKnowBase Document

For associating an Activiti process instance with an iKnowBase document, we recommend that you use a process instance variable named “documentId” of type “long”. iKnowBase Process Studio provides filtering mechanisms for this variable.