| Oracle Agile Engineering Data Management Enterprise Integration Platform Administration Guide Release e6.2.0.0 E52568-02 |
|
 Previous |
 Next |
| Oracle Agile Engineering Data Management Enterprise Integration Platform Administration Guide Release e6.2.0.0 E52568-02 |
|
Previous |
Next |
The Business Process Management (BPM) solution enables you to handle more complex processes inside the Enterprise Integration Platform. In general, transfer processes consist of several steps, e.g. checking the existence of an item in the target system, if it does not exist, creating the item and creating the BOM, if it exists, updating the item and updating the BOM and at the very end sending an e-mail notification to the end-user and so on. Before EIP 2.0 it was necessary to either deal with such scenarios by developing the logic inside the source system (e.g. by using LogiView in Agile EDM) or by developing the logic inside the target system, which receives all necessary data and performs the necessary operation.
Now most or all of this processing logic can be handled inside the BPM engine of the Integration Platform. It allows defining the control flow (switch, while, sequence, flow), message flow (receive, invoke, reply) and data flow (variables) of a process. Consider that being a workflow for the Integration Platform with the connectors (not human beings) being the participants of the workflow. It orchestrates the XML messages that are sent between the applications, which are connected to the Integration Platform.
The BPM solution consists of the following new components:
The BPM engine/connector, which runs the business processes. The BPM engine is configured inside the configuration file eai_ini.xml.
The Business Process Definition files (one file per process definition), which are "written" in an XML language called BPEL (Business Process Execution Language). They are used to "model" the processes, which you want to implement.
The business process transformation files, which allow modifying process variables during the runtime.
The BPM process monitor in the Admin GUI (described in the Process Monitor: Tools)
Although the BPM engine is shipped and installed with EIP, it needs to be activated first. In the EIP configuration file eai_ini.xml you need configure the following entries:
definition of the BPM connector
workflows for the BPM connector
Following settings need to be added to the configuration file:
<connector name="bpm" version="2.2.0" active="true" class="com.eigner.eai.connector.bpm.BpmConnector">
<bpm-home>${eai.home}</bpm-home>
<data-dir>${bpm.home}/conf/bpm</data-dir>
<data-filter>^bpel</data-filter>
<data-interval directory="30" file="5"/>
<engine-id>1</engine-id>
<activity persistence="all"/>
<invoke asynchronous="true">
</connector>
Details of the XML tags:
| Element | Description | Values |
|---|---|---|
| bpm-home | Home directory of the BPM Engine | default: ${eai.home} |
| data-dir | Directory where all process definition files are located | default: ${bpm.home}/conf/bpm |
| data-filter | A filter that defines which files in <data-dir> should be loaded by the BPM Engine upon startup. A regular expression is expected (see http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html).
Examples: "^bpel" read all files where the name starts with "bpel" "^bpel_[:alnum:]*.xml" read all files where the name: starts with "bpel_" has any number of alphanumeric characters in between ("[:alnum:]*") ends with ".xml" |
default: ^bpel
i.e. all files where the name starts with "bpel" |
| data-interval |
|
time in seconds |
| engine-id | Unique number of the BPM Engine | only numbers |
| activity |
|
all (default), fault, final (state: completed, fault, terminated), off |
| invoke |
|
true (default), false |
EIP needs to know when you want to use the BPM engine for managing the message transfer. Please consider that it is still possible to run EIP without BPM being activated.
Imagining a scenario where the BPM engine should handle the message transfer between Agile EDM and an ERP system, the following configuration is recommended:
The BPM connector can send to ERP
<workflow name="bpm-erp" active="true" type="asynchronous">
<source>bpm</source>
<target>erp</target>
<!-- there should be no pipe since the transformations are done in the BPM engine --></workflow>
<workflow name="plm-bpm" active="true" type="asynchronous">
<source>plm</source>
<target>bpm</target>
<!-- there should be no pipe since the transformations are done in BPM engine -->
</workflow>
Agile EDM can send to the BPM connector
<workflow name="plm-bpm" active="true" type="asynchronous">
<source>plm</source>
<target>bpm</target>
<!-- there should be no pipe since the transformations are done in BPM engine -->
</workflow>
Generally spoken, every connector that can be involved in a BPM-based transfer process needs to be listed in a workflow definition, where the BPM connector is either the source or the target connector.
The following new files and directories were added for the BPM solution underneath <eai.home>:
conf/bpm/bpel4ws_agile.xsd -> XML Schema for validating XML/BPEL process files
conf/bpm/bpel*.xml -> XML/BPEL process files
conf/bpm/*.xsl -> Process Variable mapping files
The XML schema file bpel4ws_agile.xsd should be used to ensure a correct syntax of the BPEL processes. The schema is based on the BPEL version 1.1 with some Agile extensions and restrictions (e.g. features, which are deactivated in the current BPM engine).
It is an absolute requirement to validate all executable processes against the XML schema before starting up the BPM engine.
As already mentioned above, all executable business processes need to reside in the directory <bpm.data>. They are read by the BPM engine upon startup.
The business processes need to conform to the BPEL syntax, which will be described below.
The element <process> is the root element of the business process definition.
<process name="PLM BOM Release"…>
The <components> refer to the EIP connector, which should be involved in that process (as source or target connectors). Upon startup of the process, it will be checked whether these connectors are set active in the configuration file "eai_ini.xml".
<components>
<component name="plm"/>
<component name="erp"/>
</components>
The <variables> are used to store information when running the process. All information is stored as XML in the variable. For example, the XML messages coming from a source connector can also be stored in a variable. You can modify the values of the variables by using the <transform> or <assign> activities.
<variables>
<variablename="plm:createItem"/>
<variablename="erp:createMaterial"/>
<variablename="erp:resultCreateMaterial"/>
<variablename="bpm:dummy"/>
<variablename="bpm:processVariables"/>
</variables>
The <faultHandlers> can be used for catching exceptions, which have been thrown during the process, but have not been caught explicitly (with <catch>) directly after the activity, which caused the fault.
<faultHandlers>
<catch faultName="Technical_001">
<invoke component="mail" businessObject="MAIL" verb="SEND" inputVariable="plm:receive" outputVariable="mail_info"/> <terminate/>
</catch>
<catchAll>
<terminate/>
</catchAll>
</faultHandlers>
The <sequence> tells the BPM engine, that here the "real process" starts. All next level activities will be executed sequentially. In general, the <sequence> activity is used to group some activities, which should be executed in sequential order.
<sequence>
Each process must start with the <receive> activity. The BPM engine will check, whether the information inside the inbound XML message (source connector, noun, verb) match the attributes (component, businessObject, verb) of the <receive> activity.
<receive component="plm" businessObject="ITEM" verb="CREATE" variable="plm:createItem" createInstance="yes"/>
The <transform> activity takes the XML data inside the "fromVariable", runs it through the XSL transformation file and assigns the result of the transformation to the "toVariable".
<transform fromVariable="plm:createItem" toVariable="erp:createMaterial" transformation="${bpm.data}/plm_erp_matcreate.xsl"/>
The <invoke> activity allows to call a "target connector". The XML data inside the "inputVariable" will be passed on (underneath <record> in the XML message). The result (<record>) provided by the target connector will be stored in the variable "outputVariable".
<invoke component="erp" businessObject="ITEM" verb="CREATE" inputVariable="erp:createMaterial" outputVariable="erp:resultCreateMaterial"/>
Each business process must end with either a <reply> to the initial source connector or the activity <terminate>. The "component" in the <reply> activity must match the "component" in the <receive> activity, which initially kicked off the process. The "variable" must contain the XML data, in particular <record/return>, which will be returned back to the source connector.
<reply component="plm" businessObject="ITEM" verb="CREATE" variable="erp:resultCreateMaterial"/>
</sequence>
</process>
In this chapter, each of the BPEL elements, which are supported by the BPM engine, are described in more detail. BPEL elements, which are included in the standard definition (as described in the BPEL V1.1 Specification) but are not listed below, are not supported by the BPM engine!
|
Note: Some of the behavior described below is in particular to the EIP BPM engine and may deviate from the behavior of other BPM engines (not provided by Oracle)! |
| <components>, <component> | The <component> elements in <components> describe which connected systems may be involved in the process. The element "name" must match the name of the connector in the configuration file eai_ini.xml!
Example:
<components>
<component name="plm"/>
<component name="erp"/>
</components>
|
| <variables>, <variable> | The <variable> elements in <variables> define all XML data containers, which may be used during the process execution.
The variable "sys:info" is created at the beginning of a process and contains process information. It can be used for references. In addition there are two variables which will be created automatically by the engine in case of errors: "sys:internal" and "sys:external". They can used to evaluate the reason of an error. Example:
<variables>
<variable name="plm:createItem"/>
<variable name="erp:createMaterial"/>
<variable name="erp:resultCreateMaterial"/>
<variable name="bpm:dummy"/>
<variable name="bpm:processVariables"/>
</variables>
|
| <faultHandlers>, <catch>, <catchAll> | The <catch> activity can be used to catch exceptions, which have been thrown in previous/parent activities, e.g. <invoke> or by an explicit <throw> activity. If the "faultName" matches the exception description as generated by the BPM engine, this <catch> sub-tree is executed, i.e. child activities of <catch> are executed. The "faultName" can be represented by a regular expression.
The <faultHandlers> can be used for catching exceptions, which have been thrown during the processes, but have not been caught explicitly after the respective activity, which caused the fault. In case that none of the <catch> statements in the <faultHandler> matches the type of fault, the <catchAll> is executed instead. Please note: more information about regular expressions can be found at: Example:
<faultHandlers>
<catch faultName="Technical_001">
<terminate/>
</catch>
<catchAll>
<terminate/>
</catchAll>
</faultHandlers>
|
| <sequence>, <flow> | <sequence> can be used to combine any number of activities, which are then executed in the sequence they are defined (no parallel, but sequential processing)
Example:
<sequence>
<activity1/>
<activity2/>
</sequence>
<flow> can be used to combine any number of activities, which are then executed in parallel (no sequential processing). The order in which the sub-activities are finished is undefined. Example:
<flow>
<activity1/>
<activity2/>
</flow>
|
| <assign>, <copy>, <from>, <to> | The element <assign> allows bundling 1 or many copy-from-to constructs.
The <from> element may either contain a - "variable/query" combination or an - "expression". The "variable/query" allows copying the whole XML tree or a sub-tree of the "variable". The "query" defines which part of "variable" should be copied. "Query" may contain any XPath construct. If the XPath points to an XML element as result of the query, the sub-elements of this element are copied over to the <to> variable. The alternative "expression" in the <from> element can be used to evaluate expressions and copy the result. In addition, some functions are provided for convenience:
These functions are allowed in "expression". If the function getVariableElement is used, "query" is also required and should provide a number value (e.g. "count") as a result. The <to> element contains a "variable/query" combination, whereas the "variable" defines the target variable of the copy operation. When the "query" is provided, the target XML sub-tree can be defined, which the copied data should replace. If that sub-tree does not yet exist in the "variable", the sub-tree will be created. In case that the "query" is omitted, the XML data will be copied to the root of the "variable". Example:
<assign>
<copy>
<from variable="plm:topLevelItem" query="/record/data/XML-ART"/>
<to variable="plm:item" query="/record/data/XML-ART"/>
</copy>
<copy>
<from expression="'abc' + 'def'"/>
<to variable="bpm:processVar" query="/bpm/test"/>
</copy>
</assign>
Please note: more information about the expressions can be found at: Mathematical Expression Parser |
| <while> | The <while> element allows to loop over a sequence of activities. The "condition" defines if the while-loop should be executed or not. Any XPath expression is allowed in the "condition". The "condition" should provide a Boolean value (true/false) as result.
The function getVariableData is allowed in "condition" (see paragraph assign). Example:
<while condition="getVariableData('bpm:processVariables', '/props/itemProcessesCount') < getVariableData('bpm:processVariables, '/props/plmBomPosCount')"> <activity/>
</while>
Please note: incorrect loop definitions may result in infinite loops! |
| <switch>, <case>, <otherwise> | The <switch" allows to combine many <case> elements and one <otherwise> element. The "condition" in the <case> element must return a Boolean value.
The function getVariableData is allowed in "condition" (see paragraph assign). Example:
<switch>
<case condition="getVariableData('bpm:processVar', '/bpm/number1') < 11">
<activity/>
</case>
<case condition="erp:material/[@materialid == '']">
<activity/>
</case>
<otherwise>
<activity/>
</otherwise>
</switch>
|
| <receive> | <receive> should be the first activity in a <process>. The BPM engine will check, whether a XML message was received by a source connector, where the "component", "businessObject" and "verb" combination matches the combination of source connector name, noun and verb in the XML messages. If this test is positive, a new process instance will be created and the process gets started. The <record> element of the incoming XML message is assigned to the "variable".
Example: <receive component="plm" businessObject="ITEM" verb="CREATE" variable="plm:createItem" createInstance="yes"/> |
| <invoke> | <invoke> kicks off a message transfer to a connector "component". This "component" must be defined as target connector in a workflow, where the BPM connector is the source connector! The "businessObject" and "verb" are set as noun and verb in the XML message. The XML data in the "inputVariable" will replace the <record> element in the outgoing XML message. The <record> element of the incoming XML message is assigned to the "outputVariable".
Example:
<invoke component="erp" businessObject="ITEM" verb="CREATE" inputVariable="erp:creMat" outputVariable="erp:resCreMat">
<catch faultName="Business_M3238">
<activity/>
</catch>
<catchAll>
<activity/>
</catchAll>
</invoke>
|
| <reply> | Sends a reply to the original source connector "component". After <reply> the process will be terminated, since this is supposed to be the last activity of every process. This "component" must be defined as source connector in a workflow, where the BPM connector is the target connector! The "businessObject" and "verb" are set as noun and verb in the XML message. The XML data in the "variable" will replace the <record> element in the outgoing XML message.
Example: <reply component="plm" businessObject="ITEM" verb="CREATE" variable="erp:resCreMat"/> |
| <terminate> | This activity will terminate the process, i.e. the BPM engine will stop any activity related to this process. First, all open activities will be terminated, and then the process will be terminated. In general, it should be avoided to use <terminate> since no result will be returned to the original source connector which kicked off this process.
Example: <terminate/> |
| <throw> | This will throw a new fault, which could be caught by the appropriate <catch> activity (based on the "faultName"). First, all open activities will be terminated, and then the fault will be thrown. This fault will be handled by the "faultHandlers" of the process.
Example: <throw faultName="Business_1234"/> |
| <empty> | This activity does nothing and the process will continue with the next activity.
Example: <empty/> |
| <wait> | Pauses the process for a while. A period is defined by "for" and a moment is defined by "until". The value of "for" is based on the XML schema type duration and the value of "until" is based on the XML schema types dateTime or date (see XML schema part 2: Datatypes Second Edition).
Example: <wait until="2005-12-31"/><wait for="PT1H12M13S"/> |
There are two types of external exceptions, which can be thrown when "invoking" connectors (<components>): Technical Exceptions and Business Exceptions.
Technical exceptions are thrown when technical problems occurred, e.g. the target connector lost the connection to its system. Technical exceptions are further described in the "code" attribute of the element <controlarea/error> in the XDO, which is coming back from the invoked connector (see upper box in the screenshot below).
Business exceptions are normally thrown by the connectors due to an issue inside the application, e.g. material could not be updated. They are further described in the <code> element inside the <dataarea/record/data/return> section of the XDO (see blue box in below screenshot).
<?xml version='1.0' encoding='ISO-8059-1'?>
<bod verson ='2.0.0'>
<controlarea>
<guid>3faf91ab-84d0-4100-9dc5-830f2d532399</guid>
<initial>plm</initial>
<source>plm</source>
<target>erp</target>
<creation-date>2004-08-01</creation-date>
<creation-time>12:00:00,000</creation-time>
<owner>EDB-EIP</owner>
<language>ENG</language>
<version>1</version>
<type>response</type>
<flags synchronous='false' finished='true'/>
<correlationid/>
<error status='E' code='001' message='ERP connector not available'/>
</controlarea>
<dataarea>
<record type='BOM' verb='RELEASE'>
<key>1-1</key>
<params/>
<data xalns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
</data>
<return>
<status>E</status>
<code>M3238</code>
<message>The material P00001 was locked</message>
</return>
</record>
</dataarea>
</bod>
Technical Exception
<error status='E' code='001' message='ERP connector not available'/>
Business Exception
<status>E</status> <code>M3238</code> <message>The material P00001 was locked</message>
Either the FaultName, as being used in the <catch> element of the business Process, consists of the string "Business_" or "Technical_", and the respective error code, as you find it the respective sections of the XDO.
Example related to the screenshot above: "Technical_001" or "Business_M3238"
In addition to specifying the complete exception name in the FaultName as shown above, you could also use a regular expression instead, e.g. "Business_.*", which catches all business exceptions since you defined a regular expressions, which queries for all exception names starting with "Business_" followed by a string of arbitrary length.
If an external exception is not handled inside <invoke> by a respective <catch> or <catchAll>, detail information about the root of the problem is provided in a system variable called "sys:external".
Example of the content of sys:external:
<external>
<fault>
<name>Business_-1</name>
<text>com.eigner.commons.mail.MailException: Sending the mail failed [javax.mail.SendFailedException: Sending failed]</text>
</fault>
<activity>
<name>Invoke (null)</name>
<id>15</id>
<level>2</level>
<info>Invoke (15/1)</info>
<component>mail</component>
<businessObject>MAIL</businessObject>
<verb>SEND</verb>
<variable>mail:message_result</variable>
</activity>
<process>
<name>plm_bom_mail</name>
<id>040761ec-d116-46f6-ae12-829e5da711d4</id>
<info>plm_bom_mail (040761ec-d116-46f6-ae12-829e5da711d4)</info>
</process>
</external>
Internal exceptions are thrown whenever something is going wrong inside the process, but is not related to invoking a connector, e.g. a transformation exception due to a wrong XSL file in the <transform> activity. Internal exceptions can be caught by using the faultName "Process_Internal":
<faultHandlers>
<catchfaultName="Process_Internal">
<....>
</catch>
</faultHandlers>
Detail information about the reason for the first internal exception is provided in the system variable "sys:internal".
Example of content of sys:internal:
<internal>
<exception>
<type>UninitializedVariableException</type>
<text>Invoke (6/1) (component: 'mail'): variable 'plm:message' is not initialized. (Process: plm_bom_mail (af747626-b603-4799-9c55-a948d99fc884)</text>
</exception>
<activity>
<name>Invoke (null)</name>
<id>6</id>
<level>2</level>
<info>Invoke (6/1)</info>
</activity>
<process>
<name>plm_bom_mail</name>
<id>af747626-b603-4799-9c55-a948d99fc884</id>
<info>plm_bom_mail (af747626-b603-4799-9c55-a948d99fc884)</info>
</process></internal>
The system variables "sys:info", "sys:external" and "sys:internal" do not have to be defined by you because they will be created and populated by the process engine automatically. The variable "sys:info" is valid all over the process and the other variables both are only valid inside <faultHandlers>. The data in these system variables could be used in an <assign/copy> activity or could be directly returned to the calling connector via <reply>.
Example of the content of sys:info:
<info>
<correlationid>1::667ca728-747a-4036-867e-8ae49b7a1154</correlationid>
<eip-server>
<host-name>localhost</host-name>
<host-address>127.0.0.1</host-address>
</eip-server>
</info>
Details of the XML tags:
| Tag | Description |
|---|---|
| correlationid | ID of the business process |
| host-name | Name of the host where the EIP is running |
| host-address | IP address of the host where the EIP is running |
All common arithmetic operators are supported. Boolean operators are also fully supported. Boolean expressions are evaluated to be either 1 or 0 (true or false respectively).
Operations:
| Operation | Operand | Number | String |
|---|---|---|---|
| Addition | + |
x | x |
| Boolean And | &&, & | x | - |
| Boolean Not | !, ~ | x | - |
| Boolean Or | ||, | | x | - |
| Division | / |
x | - |
| Equal | ==, = | x | x |
| Greater or Equal | >= | x | - |
| Greater Than | > | x | - |
| Less or Equal | <=, >= | x | - |
| Less Than | <, > | x | - |
| Modulus | % |
x | - |
| Multiplication | * |
x | - |
| Not Equal | !=, <> | x | x |
| Power | ^, ** | x | - |
| Subtraction | - | x | - |
| Unary Minus | -x | x | - |
| Unary Plus | +x | x | - |
Functions:
| Name | Function | Number |
|---|---|---|
| Absolute Value / Magnitude | abs() | x |
| Arc cosine | acos() | x |
| Arc sine | asin() | x |
| Arc tangent | atan() | x |
| Ceiling | ceil() | x |
| Cosecant of angle | csc() | x |
| Cosine | cos() | x |
| Cotangent | cot() | x |
| Cube root | cubert() | x |
| Exponential | exp() | x |
| Factorial | fact() | x |
| Floor | floor() | x |
| Logarithm base 2 | log2() | x |
| Logarithm base 10 | log10() | x |
| Natural logarithm | ln(), log() | x |
| Random number (<= 0 && < 1) | rand() | x |
| Round | round() | x |
| Secant of angle | sec() | x |
| Sine | sin() | x |
| Square root | sqrt() | x |
| Tangent | tan() | x |
An "x" indicates that the operator can be used with the specific type of variable.
Constants:
| Constant | Value | Number | String |
|---|---|---|---|
| pi | 3.1415926535897932384626433832795 | x | x |
| e | 2.71828182845904523536028747135266249 | x | - |
