Knowledge Services are SwitchYard Services that leverage KIE, and thus, Drools and/or jBPM:
Given that Drools and jBPM are very tightly integrated under KIE, much of their runtime configuration can be shared by both SwitchYard's BPM component and its Rules component. Therefore, documentation on this page refers to elements that are either exactly, or structurally, identical to both the BPM and Rules components. That is to say, any configuration element you see here can be used in the same way for both BPM and Rules. Sometimes, however, the context of the element is significant, so cases like that will be identified where applicable.
For some of the configuration elements below, you might wonder why it is a shared element between both the BPM and Rules components. For example, Channels are something only applicable to Rules, right? Yes, however what if your BPM process has a node which executes business rules, and those rules reference channels? In that case, you need a way to configure channels for the rules within your process. Thus, it is documented here.
Operations are how Knowledge Services know how to map service operation invocations to their appropriate runtime counterparts. For example, when method "myOperation" is called, what should happen? Execute some business rules? Start a business process?
Using the XML below as reference, when the SwitchyYard service’s "myOperation" operation is invoked, an operation of type "OPERATION_TYPE" will be taken. Note that "OPERATION_TYPE" is just a placeholder here. Actual OperationTypes are specific to the BPM and Rules components. Please refer to the specific documentation on those pages.
At this time, the eventId attribute is only applicable to the Rules component.
Please see the Mapping section below for an explanation of the globals, inputs, outputs and faults sections.
XML
<operations>
<operation eventId="myEventId" name="myOperation" type="OPERATION_TYPE">
<globals>
<global from="" to=""/>
</globals>
<inputs>
<input from="" to=""/>
</inputs>
<outputs>
<output from="" to=""/>
</outputs>
<faults>
<fault from="" to=""/>
</faults>
</action>
</operations>
Mappings are the way to move data in or out of an operation. You can specify as many mappings as you like for an operation, and they get grouped as globals, inputs, outputs or faults:
Global mappings are used to provide data that is applicable to the entire action, and is often used in classic in/out param (or data-holder/provider) fashion. An example of a global mapping is a global variable specified within a Drools Rule Language (DRL) file.
Input mappings are used to provide data that represents parameters being fed into an action. An example of an input mapping for BPM could be a process variable used while starting a business process. For Rules, it could be a fact to insert into a rules engine session.
Output mappings are used to return data out of an action. An example of an output mapping would be a BPM process variable that you want to set as the outgoing (response) message’s content.
Fault mappings are used to return fault data out of an action. An example of a fault mapping would be a BPM process variable that you want to set as the outgoing (response) application Exception to be thrown.
All of the different mapping types support a from and to attribute. Those attributes get configured with MVEL expressions, which themselves support variables that can come from process or global variable names, implicit variable names (see below), or variables that get resolved from properties.
Implicit Variables
context - The current org.switchyard.Context.
message - The current org.switchyard.Message.
Some examples:
from="message.content" - This is the same as message.getContent().
from="context[‘foo’]" - This is the same as context.getProperty("foo", Scope.MESSAGE).getValue(), in a null-safe manner.
Specifying attributes is often optional, but this depends on the usage. For example, if you are specifying a global variable for a rule, or a process variable to put into (or get out of) a BPM process, then it is required. However, if the result of the expression is to be used as facts for rule session insertion, than specifying a "to" isn’t applicable.
Drools supports the notion of "Channels", which are basically "exit points" in your DRL. They can be used in both stateful and stateless sessions. Here is an example:
package com.example
rule "example rule"
when
$f : Foo ( bar > 10 )
then
channels["Bar"].send( $f.getBar() );
end
XML
<channels>
<channel class="com.example.BarChannel" name="Bar"/>
</channels>
Channels must implement org.kie.api.runtime.Channel.
SwitchYard provides an out-of-the-box Channel which allows you to invoke (one-way) other SwitchYard services directly and easily from your DRL. Here is an example:
XML
<channel name="HelloWorld" reference="HelloWorld" operation="greet"/>
Attribute Reference:
class = The channel implementation class. (Default is SwitchYardServiceChannel.)
name = The channel name. (default = simple name of the implementation class)
reference = The service reference qualified name.
operation = The service reference operation name.
Listeners are used to monitor specific types of events that occur during Knowledge execution. An example of this would be to audit a BPM process, and save the audit details into a database while the process progresses. Then at a later time, these details can be reported against. There are many out-of-the-box Listeners that Drools and jBPM provide, and you can write your own. The only restriction in writing your own Listener is that it must, at the minimum, implement java.util.EventListener. However, your Listener won’t actually be registered for anything unless it also implements one of the respected KIE/Drools/jBPM Listener interfaces. For example, org.drools.core.event.WorkingMemoryEventListener, org.kie.api.event.rule.AgendaEventListener, org.kie.api.event.process.ProcessEventListener, or similar.
If the Listeners provide a Constructor taking a single KieRuntimeEventManager (or KnowledgeRuntimeEventManager) as a parameter, that is used and it is assumed it will do the work of registering itself with the passed-in event manager (OOTB {{WorkingMemoryLogger}}s do this). Otherwise, a no-arg constructor is assumed, and SwitchYard will do the work of registering the Listeners for each of the respected interfaces it implements.
XML
<listeners>
<listener class="org.drools.core.event.DebugProcessEventListener"/>
<listener class="org.kie.api.event.rule.DebugWorkingMemoryEventListener"/>
<listener class="com.example.MyListener"/>
</listeners>
Loggers
Loggers are special types of Listeners, and are used to output the events that occur during Knowledge execution. Support for Loggers is done using a dedicated configuration element. Events can be logged to the CONSOLE or to a FILE (or THREADED_FILE). If they are directed to a file, that log can later be opened via the Drools Eclipse tooling.
XML
<loggers>
<logger interval="2000" log="myLog" type="THREADED_FILE"/>
<logger type="CONSOLE/>
</loggers>
The only configuration element more important than Operations is the Manifest, which is where you specify where the "intelligence" of the component comes from. For the BPM component, this will be, at the minimum, the location of the BPMN 2 process definition file. For the Rules component, this will most likely be the location of DRL, DSL, DSLR or XLS files. There are two ways to to configure the Manifest:
With a KIE Container. This relies upon the existence of a META-INF/kmodule.xml configuration file.
With a manually defined list of Resources.
These two options are mutually exclusive: You have to choose one or the other!
The following examples assume there is a DRL file located at classpath: com/example/MyRules.drl
META-INF/kmodule.xml
<kmodule xmlns="http://jboss.org/kie/6.0.0/kmodule">
<kbase name="com.example">
<ksession name="my-session"/>
</kbase>
</kmodule>
XML
<manifest>
<container sessionName="my-session"/>
</manifest>
In addition to the sessionName attribute, you can also specify baseName and releaseId, if desired.
Also, scanning for updates is supported only with the container option (not the resources option). To enable this, simply set scan="true" and, optionally, scanInterval=<# of milliseconds>.
XML
<manifest>
<resources>
<resource location="com/example/MyProcess.bpmn" type="BPMN2"/>
<resource location="com/example/MyRules.drl" type="DRL"/>
</resources>
</manifest>
Properties are the way to provide "hints" to the underlying KIE/Drools/jBPM runtime on how certain options are configured. Rather than having to expose every single KIE/Drools/jBPM option as a configurable element or attribute within SwitchYard, they can be set as open-ended properties.
Properties are an advanced topic, so setting them should be done with care. All possible property names and values will not be listed here, but as a starting point, in your IDE open up a Type Heirarchy with a root of org.kie.api.conf.Option. That is your full list. Here are just a couple examples:
XML
<properties>
<property name="drools.clockType" value="pseudo"/>
<property name="drools.eventProcessingMode" value="stream"/>
</properties>