Oracle® Fusion Middleware Business Process Composer User's Guide for Oracle Business Process Management 11g Release 1 (11.1.1.6.3) Part Number E15177-10 |
|
|
PDF · Mobi · ePub |
This appendix provides information for each of the BPMN flow object properties. It contains these topics:
Section B.1, "Preparing a Visio File to Import as a BPMN Process"
Section B.3, "Preparing an XPDL File for Import as a BPMN Process"
You can import Visio files into Business Process Composer. Business Process Composer maps Visio elements to BPMN flow objects using a map file named VisioMasterMap.xml.
This file defines how each Visio element is mapped to a BPMN flow object. It is located in the following directory in the JDeveloper home directory:
.../jdeveloper/jdev/extensions/tutor/xml.
Note:
Do not edit this file. You can override the mappings in this file by creating and editing VisioUserMap.xml.
Business Process Composer checks for a VisioUserMap.xml file after it has parsed VisioMasterMap.xml and then modifies its rules accordingly. The user map serves to extend and/or override the master map.
The Visio import module is designed for extensibility. Users may add an XML file to support alternate Visio stencils and specify the mapping of additional Visio master shapes to BPMN objects. This file must be named “VisioUserMap.xml”, and it must be placed in the same directory as the “VisioMasterMap.xml” file.
This file should have the same root element as the supplied “VisioMasterMap.xml” file, including the reference to the VisioMasterMap.xsd. “VisioUserMap.xml” must have the same format as the master map, which may be used as a reference. Entries added to the user map either add mappings or overwrite an existing entry in the main map. It should contain only the extended or overridden entries and should not repeat all the original entries.
Example B-1 Example Entry for VisioUserMap.xml
<?xml version = '1.0' encoding = 'UTF-8'?> <Masters xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.oracle.com/oracle/tutor/visio/masterMapElements VisioMasterMap.xsd" xmlns="http://www.oracle.com/oracle/tutor/visio/masterMapElements"> <!— custom <Master/> elements go here -- > </Masters>
The following procedure describes a possible scenario for importing a Visio file to a BPMN process.
To update VisioUserMap.xml
In this scenario, assume that the source Visio file contains a shape named Report, that you what to map to a data object. By default, VisioMasterMap maps this shape to a send task. If you use it strictly as an input /output object, it is more accurate to map it to a Data Object.
In the VisioMasterMap.xml file, locate the master definition for DataObject which appears as:
<Master Name="data object"> <BPMNObject>DataObject</BPMNObject> </Master>
This definition is followed by a series of additional master elements that use the Like attribute to clone the first definition and map additional Visio objects:
<Master Name="sequential data" Like="data object"/> <Master Name="data" Like="data object"/>
To add or modify a mapping for a Visio Report element, add the following code to the VisioUserMap.xml file:
<Master Name=”Report” Like=”data object”/>
Example B-2 shows how an object can be mapped to an exiting BPMN object with additional or different attributes by using the Extends attribute.
Example B-2 Mapping a Visio Object to a BPMN Object Using the Extends Attribute
<Master Name="flow"> <BPMNObject>SequenceFlow</BPMNObject> </Master> <Master Name="conditional flow" Extends="flow"> <Attributes> <Attribute Name="ConditionType" Value="Expression"/> </Attributes> </Master>
In this example, the Visio object conditional flow is mapped to the SequenceFlow BPMN flow object, but has added the attribute “ConditionType” to the value “Expression.”
The following are the valid values for the <BPMNObject> element:
Task
Subprocess
Event
Gateway
DataObject
Group
Annotation
Lane
Pool
MessageFlow
SequenceFlow
Association
null
Note:
When you assign the null value to a Visio element, no BPMN flow object is created.
The following tables show valid values for BPMN attributes based on the basic BPMN types of BPMN flow objects:
Task attributes and values
Table B-1 show the valid attributes and values for BPMN tasks.
Table B-1 Task Attributes and Values
Attribute | Values |
---|---|
TaskType |
None, Script, Reference, Service, User, Manual, Send, Receive |
LoopType |
Standard, MultiInstance |
isForCompensation |
true, false |
Subprocess attributes and values
Table B-2 show the valid attributes and values for BPMN subprocesses
Table B-2 Subprocess Attributes and Values
Attribute | Values |
---|---|
isExpanded |
true, false |
isATransaction |
true, false |
LoopType |
Standard, MultIinstance |
isForCompensation |
true, false |
AdHoc |
true, false |
Event attributes and values
Table B-3 show the valid attributes and values for BPMN events.
Table B-3 Event Attributes and Values
Attribute | Values |
---|---|
EventType |
Start, Intermediate, End |
Trigger |
Trigger None, Message, Timer, Conditional, Signal, Multiple, Error, Cancel, Compensation, Link, Terminate |
Gateway attributes and values
Table B-4 show the valid attributes and values for BPMN gateways.
Table B-4 Gateway Attributes and Values
Attribute | Values |
---|---|
GatewayType |
Parallel, Inclusive, Exclusive, Complex |
ExclusiveType |
Event, Data |
MarkerVisible |
true, false |
Sequence flow attributes and values
Table B-5 show the valid attributes and values for BPMN sequence flows.
Table B-5 Sequence Flow Attributes and Values
Attribute | Values |
---|---|
ConditionType |
None, Expression, Default |
Association attributes and values
Table B-6 show the valid attributes and values for BPMN data objects.
Pool attributes and values
Table B-7 show the valid attributes and values for BPMN pools.
Often the conversion of models from source to target follows general transformation rules and has guidelines and constraints. If an XPDL document is imported and does not produce desirable results, there may be a mismatch between the format Business Process Composer is expecting and the format of the XPDL document. Under such circumstances, an XSLT transform may be used to create a better match between the original XPDL diagram and the Business Process Composer results.
The following procedure describes the recommended process for incorporating an XSL style sheet to modify the output of an Oracle BPM conversion. Oracle BPM ships with several XSLT files that may serve as examples to XSLT developers.
To customize XPDL Import Using XSL Doc:
Business Process Composer uses XSLT transformations to parse XPDL files and generate a consistent format before the data is passed to BPMN and displayed as a diagram. Business Process Composerwill search for a transformation file associated with an XPDL document.
Typically, an XPDL file contains a <Vendor/> element that provides the vendor name. By adding the Vendor's name and the path to an XSL file to Oracle BPM's “XSLFilePaths.xml”, the vendor name will be searched to locate the associated transformation file's path.
The file path is retrieved from index file, and Business Process Composer applies the XSLT transformation on the XPDL file.
Create a custom XSLT file.
Using an XML editor, create a new XSLT file. To view examples, see Appendix 3: XPDL Technical Details. It is best to put the XSLT file in the “XML” directory that contains “XSLFilePaths.xml”.
Open the XPDL file to be imported and locate the <Vendor/> element under the <PackageHeader/> element, and note its value.
For example, if the XPDL looks like this:
<Package xmlns="http://www.wfmc.org/2004/XPDL2.0alpha" Id="6" Name="Untitled Document 6"> <PackageHeader> <Vendor>Global 360</Vendor> … </PackageHeader> … </Package>
The Vendor element's value is “Global 360”.
Locate the “XSLFilePaths.xml” file.
This file is located in a folder named “XML” which is nested beneath your JDeveloper install directory as follows: [JDeveloper install]\jdeveloper\jdev\extensions\tutor\xml.
Add a new <XSLFilePath/> element with a Vendor attribute containing the name of the vendor, and provide the relative path to the XSLT file as the value.
For example:
<XSLFilePaths xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="filesPaths PatchFilesPaths.xsd" xmlns="filesPaths"> … <XSLFilePath Vendor=”Global 360”>Global360Patch.xsl</XSLFilePath> </XSLFilePaths>
Note:
In this example the file name “Global360Patch.xsl” has no additional path information. Business Process Composer will search for this file in the same folder that contains the “XSLFilePaths.xml” file.
If additional path information is present, Business Process Composer will search for the file relative to the \xml folder.
Import the XPDL file in Oracle BPM. Your file will be transformed and processed according to the rules specified in the custom XSLT file.
For importing XDPL files that do not conform to XPDL 2.1 or might be missing elements that Oracle BPM expects, conversion is extensible through the use of XSLT. See Section B.1, "Preparing a Visio File to Import as a BPMN Process" for instructions on integrating custom XSLT to produce the best results. This appendix will provide several sample XSLT templates to handle common situations that an Oracle BPM user might encounter when importing XPDL files.
If you are using Tutor the files mentioned in this appendix are located in a directory named “XML” in the Tutor install directory. If you are working with BPM, they located under your JDeveloper install directory, then navigate to /jdeveloper/jdev/extensions/tutor/xml.
The following are requirements for importing business processes into Oracle BPM:
Oracle BPM supports importing XPDL 2.1 files. The following namespace must be present in the root element [i.e. “<Package/>”] of the XPDL source document as the default namespace: http://www.wfmc.org/2008/XPDL2.1
If the XPDLsource file targeted for import does not conform to XPDL 2.1, then an XSLT must be performed to generate the correct XPDL format for import into Oracle BPM. The following sections provide some guidance for creating those transforms.
You must be familiar with namespaces handling in XSLT when importing XPDL. The default namespace used by Oracle BPM is:
http://www.wfmc.org/2008/XPDL2.1.
In some cases a source file may be XPDL 2.1 compliant, but still lack elements required by Oracle BPM. In such cases, XSLT can be used to add those elements. Refer to the scenarios below for a reference to such a transformation.
Any other default namespace in an XPDL document will result in elements and attributes being treated as conforming to XPLD 2.1 during import, which will likely produce poor results. XPDL source documents that do not conform to XPDL 2.1 must be transformed via XSL into XPDL 2.1 result documents.
The following possible scenarios exist:
The source XPDL elements user the default namespace and conform to XPDL 2.1 See stylesheet “BizAgiPatch.xsl” as an example for handling this scenario.
The source XPDL elements are in default namespace but they don't conform to xpdl 2.1. See stylesheet “patch.xsl” as an example for handling this scenario.
The source XPDL elements are not in default namespace and they don't conform to XPDL 2.1. See stylesheet “ALBPMPatch.xsl” ” as an example of handling this scenario.
4. The source XPDL elements are not in default namespace but they conform to xpdl 2.1. See stylesheet “TibcoPatch.xsl” as an example of handling this scenario
Example B-3 shows an XSL that copies elements written using a local namespace in the source document to the default namespace in the result document.
Note:
The local namespace is added in the stylesheet's root element. When matching elements in the source XPDL document, the local namespace prefix is required for a match to be successful. This example uses ANY_LOCAL_NAMESPACE.
Example B-3 Copying Elements From Local Namespace to the Default Namespace
<xsl:stylesheet version = "1.0" xmlns:xsl = "http://www.w3.org/1999/XSL/Transform" xmlns:ANY_LOCAL_NAMESPACE = "http://www.someURI" > <xsl:output method = "xml" indent = "yes"/> <xsl:template match="@*|node()"> <xsl:copy> <xsl:apply-templates select="@*|node()"/> </xsl:copy> </xsl:template> <xsl:template match = “ANY_LOCAL_NAMESPACE:Activity”> ………… </xsl:template> </xsl:stylesheet>
XPDL documents may have object coordinates defined as relative or absolute. An XPDL document using absolute coordinates will import all coordinates as absolute coordinates.
When importing XPDL documents into Oracle BPM using relative coordinates you should be aware of the following conditions:
Pool coordinates are absolute
Lane coordinates are relative to their parent pool
Node coordinates not in a subprocess are absolute
Node coordinates in an embedded subprocess (expanded or collapsed) are relative to the upper-left corner of the subprocess
Sequence Flow path coordinates connecting nodes in a subprocess are relative to the upper-left corner of the subprocess
All other flows are absolute
An XPDL document with relative coordinates must be converted to meet the above conditions. The following information may be helpful in converting coordinates from relative to absolute or vice versa when necessary:
Pool coordinates
Pool coordinates must be absolute. If coordinates provided for Pools are relative, then OBPC will render all Pools overlapping each other. OBPC assumes Pools contain absolute coordinates. To override this, convert Pool coordinates to absolute.
Lane coordinates
Lane coordinates must be relative to their parent pool. In some instances, lanes have absolute coordinates but the model has relative coordinates. In this case lane coordinates can be converted as follows.Lane X-Coordinate can be taken as the difference between lane X-coordinate and its parent pool X-Coordinate. The same logic applies to the Y-coordinate.
The following XSL example shows how to perform this conversion:
<xsl:template match = "xpdl2:Lane/xpdl2:NodeGraphicsInfos/xpdl2:NodeGraphicsInfo/xpdl2:Coordinates"> <xsl:copy> <xsl:copy-of select = "@*[name() != 'XCoordinate' and name() != 'YCoordinate']"/> <xsl:attribute name = "XCoordinate"> <xsl:value-of select = “ancestor::xpdl2:Pool/xpdl2:NodeGraphicsInfos/xpdl2:NodeGraphicsInfo/xpdl2:Coordinates/@XCoordinate - @XCoordinate"/> </xsl:attribute> <xsl:attribute name = "YCoordinate"> <xsl:value-of select = "ancestor::xpdl2:Pool/xpdl2:NodeGraphicsInfos/xpdl2:NodeGraphicsInfo/xpdl2:Coordinates/@YCoordinate - @YCoordinate"/> </xsl:attribute> <xsl:apply-templates/> </xsl:copy> </xsl:template>
Node coordinates not in a subprocess
Node coordinates not in a subprocess must be absolute. If node coordinates are relative to their parent lane or pool, convert them to absolute.Coordinates for activities relative to the parent pool can be converted to absolute by adding their pool coordinates to the activity coordinates.Coordinates for activities relative to parent Lanes, which are relative to the parent Pool, can be converted to absolute by assigning the sum of the activity, parent lane and parent pool coordinates to activity coordinate.
The following example shows how to calculate activity coordinates if they are relative to the parent lane and the lane coordinates are relative to the parent pool where the pool coordinates are absolute.
<xsl:template match="xpdl2:Activity/xpdl2:NodeGraphicsInfos/xpdl2:NodeGraphicsInfo/xpdl2:Coordinates"> <xsl:copy> <xsl:copy-of select="@*[name()!='YCoordinate' and name()!='XCoordinate']"/> <xsl:variable name="LaneId"> <xsl:value-of select="ancestor::xpdl2:NodeGraphicsInfo/@LaneId"/> </xsl:variable> <xsl:variable name="PoolId"> <xsl:value-of select="//xpdl2:Lane[@Id=$LaneId]/ancestor::xpdl2:Pool/@Id"/> </xsl:variable> <xsl:attribute name="YCoordinate"> <xsl:value-of select="//xpdl2:Pool[@Id=$PoolId]/xpdl2:NodeGraphicsInfos/xpdl2:NodeGraphicsInfo/xpdl2:Coordinates/@YCoordinate + //xpdl2:Lane[@Id=$LaneId]//xpdl2:NodeGraphicsInfos/xpdl2:NodeGraphicsInfo/xpdl2:Coordinates/@YCoordinate + @YCoordinate"/> </xsl:attribute> <xsl:attribute name="XCoordinate"> <xsl:value-of select="//xpdl2:Pool[@Id=$PoolId]/xpdl2:NodeGraphicsInfos/xpdl2:NodeGraphicsInfo/xpdl2:Coordinates/@XCoordinate + //xpdl2:Lane[@Id=$LaneId]//xpdl2:NodeGraphicsInfos/xpdl2:NodeGraphicsInfo/xpdl2:Coordinates/@XCoordinate + @XCoordinate"/> </xsl:attribute> </xsl:copy> </xsl:template>
Node coordinates in an embedded subprocess
Node coordinates in an embedded Subprocess (expanded or collapsed) must be relative to the upper-left corner of the Subprocess For child nodes of a Subprocess, coordinates are relative to the parent Subprocess. If coordinates of child nodes of a Subprocess are not relative to the parent Subprocess, it is necessary to determine whether the coordinates are relative to the parent Lane or parent Pool. To make Node coordinates relative to the Subprocess, subtract the appropriate Subprocess coordinates from the node coordinates and assign the resulting values to the node coordinates.A sample style sheet template is given below that calculates the coordinates of the child nodes of a Subprocess. This template will work if the child node coordinates are not relative to a Subprocess.
<xsl:template match = "xpdl2:ActivitySet/xpdl2:Activities/xpdl2:Activity/xpdl2:NodeGraphicsInfos/xpdl2:NodeGraphicsInfo/xpdl2:Coordinates"> <xsl:variable name = "ActivitySetId"> <xsl:value-of select = "ancestor::xpdl2:ActivitySet/@Id"/> </xsl:variable> <xsl:copy> <xsl:copy-of select = "@*[name() != 'XCoordinate' and name() != 'YCoordinate']"/> <xsl:attribute name = "XCoordinate"> <xsl:value-of select = "@XCoordinate – //xpdl2:Activity[@Id = $ActivitySetId]/xpdl2:NodeGraphicsInfos/xpdl2:NodeGraphicsInfo/xpdl2:Coordinates/@XCoordinate"/> </xsl:attribute> <xsl:attribute name = "YCoordinate"> <xsl:value-of select = "@YCoordinate – //xpdl2:Activity[@Id = $ActivitySetId]/xpdl2:NodeGraphicsInfos/xpdl2:NodeGraphicsInfo/xpdl2:Coordinates/@YCoordinate"/> </xsl:attribute> </xsl:copy> </xsl:template>
Sequence Flow path coordinates
Sequence Flow path coordinates connecting nodes in a subprocess must be relative to the upper-left corner of the subprocess.
In your XSL, you should determine whether Sequence Flow path coordinates are relative to Subprocess or not. If not, convert them to relative to upper-left corner of the Subprocess.
Simple program logic can be used to convert coordinates to relative. Such logic would subtract the Subprocess coordinates from the Sequence Flow path coordinates. All other Flows must be absolute.
Also, in your XSL code you should determine whether coordinates are relative or absolute. If coordinates are not absolute, convert them. To convert, include templates in a style sheet that contains logic to add the parent Pool coordinates to the Flow coordinates and then assigns these values to the Flow coordinates.It is important to note the following if coordinates are relative to the parent pool or the parent lane:
If sequence flows are relative to the parent pool, add the pool coordinates to the flow coordinates.
If Sequence Flows are relative to the parent Lane, add the parent Pool coordinates and the parent Lane coordinates to the Flow coordinates.
Two extended attributes are used by Business Process Composer to parse XPDL files. These extended attributes are optional but can be very useful when working with XPDL documents that employ relative coordinates for Flows. These attributes are:
redrawConnections
isRelativeObjectCoordinates
These extended attributes are not standard XPDL elements but can be used to mitigate the amount of work required to convert Flow coordinates from relative to absolute or from absolute to relative. Although the <ExtendedAttributes> element is found in many elements of the XPDL document, Oracle BPM will search for it under <Package/> element. Place the <ExtendedAttributes> element under <Package/> element to ensure it is located by Oracle BPM.
Setting this attribute to true will let Oracle BPM redraw flow connections instead of using the original coordinates. This is useful when coordinates of flows need to be converted to relative or absolute. If it is hard to convert coordinates of flows to relative or absolute, then setting this attribute to true will let Oracle BPM recreate the coordinates for flows.
When this attribute is set to true, there is no need to convert coordinates to absolute or relative. Oracle BPM will not consider the original coordinates of flows but will create the most suitable coordinates to flows.
Oracle BPM will use the original coordinates when the ExtendedAttribute is not included in XPDL file or is set to false.
Therefore, use of this attribute should be considered when retaining the layout of the original model is of lesser importance than providing a shorter development time.
Example B-4 shows how to set this attribute.
Example B-4 Setting the ExtendedAttribute when Handling redrawConnections
<xsl:template match="xpdl:Package/xpdl:ExtendedAttributes"> <xsl:copy> <xsl:copy-of select="@*"/> <xpdl:ExtendedAttribute Name="redrawConnections" Value="true"/> <xsl:apply-templates/> </xsl:copy> </xsl:template> <xsl:template match="xpdl:Package"> <xsl:copy> <xsl:copy-of select="@*"/> <xsl:if test="not(child::xpdl:ExtendedAttributes)"> <xpdl:ExtendedAttributes> <xpdl:ExtendedAttribute Name="redrawConnections" Value="true"/> </xpdl:ExtendedAttributes> </xsl:if> <xsl:apply-templates/> </xsl:copy> </xsl:template>
The above templates add the 'redrawConnections' ExtendedAttribute to the <ExtendedAttributes/> element as a child of < Package/>.
The isRelativeObjectCoordinates extended attribute is used to notify Oracle BPM that object coordinates in the XPDL file are relative or absolute.
If the source XPDL file presents ALL object coordinates in absolute form [every coordinate is measured from the 0,0 point at the top left corner of the diagram], then this attribute should be used and its value set to false.
Setting this extended attribute to true informs Oracle BPM that all coordinates in the source XPDL file are relative in conformance with the 'Relative Coordinates' rules of Oracle BPM as specified above.
Oracle BPM by default assumes all coordinates of input document comply with the 'Relative Coordinates' rules of Oracle BPM as outlined above. When this attribute is set to true or is omitted, make sure that all coordinates meet the Relative Coordinates rules of Oracle BPM. Otherwise, include templates in your style sheet to make them conform to the Relative Coordinates rules specified in this document.
Example B-5 shows how to include the <ExtendedAttribute/> element in the <ExtendedAttributes/> element, which is a child of the <Package/> element, is given below.
Example B-5 Including the ExtendedAttribute in the ExtendedAttributes Element
<xsl:template match="xpdl21:Package/xpdl21:ExtendedAttributes"> <xsl:copy> <xsl:copy-of select="@*"/> <xpdl21:ExtendedAttribute Name="isRelativeObjectCoordinates" Value="false"/> <xsl:apply-templates/> </xsl:copy> </xsl:template> <xsl:template match="xpdl21:Package"> <xsl:copy> <xsl:copy-of select="@*"/> <xsl:if test="not(child::xpdl21:ExtendedAttributes)"> <xpdl21:ExtendedAttributes> <xpdl21:ExtendedAttribute Name="isRelativeObjectCoordinates" Value="false"/> </xpdl21:ExtendedAttributes> </xsl:if> <xsl:apply-templates/> </xsl:copy> </xsl:template>
Oracle BPM considers all graphical elements of the source XPDL file to be visible elements, even if their visibility is set to false. Thus you may find some differences as formerly invisible elements have now become visible.
The only way to resolve this issue is to remove these elements from the XPDL with the help of some XSL style sheet templates as shown in Example B-6.
Example B-6 Removing Invisible Elements
<xpdl:Activity Name="ProcessGroup" Id="ProcessGroup"> <xpdl:NodeGraphicsInfos> <xpdl:NodeGraphicsInfo ToolId="XYZ" LaneId="PMCoE" IsVisible="false"> <xpdl:Coordinates XCoordinate="7740.0" YCoordinate="80.0"/> </xpdl:NodeGraphicsInfo> </xpdl:NodeGraphicsInfos> ………………….. </xpdl:Activity>
Here the Activity's visibility is set to false, but when this model is imported into Oracle BPM, you will still see this Activity. To eliminate invisible elements include a style sheet template to remove them.
Example B-7 shows how to remove invisible activities.
Example B-7 Removing Invisible Activities
<xsl:template match="xpdl:Activity"> <xsl:variable name="isVisible"> <xsl:choose> <xsl:when test="xpdl:NodeGraphicsInfos/xpdl:NodeGraphicsInfo/@IsVisible = 'false'"> <xsl:text>false</xsl:text> </xsl:when> <xsl:otherwise> <xsl:text>true</xsl:text> </xsl:otherwise> </xsl:choose> </xsl:variable> <xsl:if test="$isVisible = 'true'"> <xsl:copy> <xsl:copy-of select="@*"/> <xsl:apply-templates/> </xsl:copy> </xsl:if> </xsl:template>
Orientation is an attribute found in many XPDL documents to specify the orientation of the model. This attribute must have HORIZONTAL or VERTICAL as its value. XPDL documents generated by some tools may have coordinates that identify the model as horizontal when the model is actually in vertical orientation and vice versa.
Make sure the model has correct coordinates with respect to the model orientation.
If model has mismatching coordinates, include style sheet templates to swap the coordinates.
The orientation attribute of model is also important to Oracle BPM for calculating dimensions of pools and lanes (which will be discussed later in this document). The orientation attribute can be found in Pool elements. If this attribute is not found in the XPDL document then the model is assumed to be in Horizontal orientation by Oracle BPM.
If the orientation attribute is in a tool specific namespace it must be made available to Oracle BPM by creating an orientation attribute on the pool elements and setting their values to the one found in tool specific namespace.
Example B-8 shows how to set orientation of pools. This template tries to find the orientation of pools. If it is not found then this template will set the orientation attribute to HORIZONTAL.
Example B-8 Setting the Orientation of Pools
<xsl:template match="xpdl:Pool"> <xsl:variable name="orientation"> <xsl:choose> <xsl:when test="not(@Orientation)"> <xsl:text>HORIZONTAL</xsl:text> </xsl:when> <xsl:otherwise> <xsl:value-of select="@Orientation"/> </xsl:otherwise> </xsl:choose> </xsl:variable> <xsl:copy> <xsl:copy-of select="@*"/> <xsl:attribute name="Orientation"> <xsl:value-of select="$orientation"/> </xsl:attribute> <xsl:apply-templates/> </xsl:copy> </xsl:template>
The view attribute of <BlockActivity/> and <Subflow/> elements specify whether the subprocess is an expanded or a collapsed subprocess. Oracle BPM assumes the default view type of subprocess elements is COLLAPSED. For this reason, if a model has an expanded subprocess element but its' view' type is not given in XPDL file, Oracle BPM will render this element as a collapsed subprocess element.
Note:
Subflow elements of an XPDL file cannot be rendered with their child elements into Oracle BPM, only the subflow elements themselves will be found in the imported model. It is possible to identify the Subprocess according to its view type. If the subflow is expanded Oracle BPM will render this element as an expanded subflow element.
The following example shows <BlockActivity/> and <Subflow/> elements that do not have a view type specified. Their corresponding interpretation by Oracle BPM will result in a collapsed subprocess.
<xpdl2:BlockActivity ActivitySetId="_gJ5DQeE3Ed6tmt0cZVxmlA"/> <xpdl2:SubFlow Id="_swKUEGyzEd6oxIP3ZfQL-g" PackageRef="ProcessPackage"/>
If the view attribute is not found in <BlockActivity> element, it may be present in a tool specific namespace. If so, include templates in XSL to create view attribute on <BlockActivity> or <Subflow> elements.
Example B-9 shows a style sheet used to add the view attribute to <Subflow> elements. This template will work for BizAgi generated XPDL files.
Example B-9 Adding the View Attribute to a Subflow Element
<xsl:template match="xpdl21:SubFlow"> <xsl:copy> <xsl:copy-of select="@*"/> <xsl:attribute name="View"> <xsl:choose> <xsl:when test="ancestor::xpdl21:Activity/xpdl21:NodeGraphicsInfos/xpdl21:NodeGraphicsInfo/@Expanded='false'"> <xsl:text>COLLAPSED</xsl:text> </xsl:when> <xsl:otherwise> <xsl:text>EXPANDED</xsl:text> </xsl:otherwise> </xsl:choose> </xsl:attribute> </xsl:copy> </xsl:template>
Example B-10 shows a sample style sheet template that adds the View attribute to <BlockActivity> elements. This template will work for Oracle BPM Studio XPDL generated files. This template also shows how to create the View attribute on <BlockActivity> elements by accessing the View attribute value from a tool specific namespace.
Example B-10 Adding the View Attribute to BlockActivity Elements
<xsl:template match="xpdl:Activity/xpdl:BlockActivity"> <xsl:copy> <xsl:copy-of select="@*"/> <xsl:choose> <xsl:when test="ancestor::xpdl:Activity/xpdl:Extensions/albpm:ALBPMExtensions/albpm:FeatureSet/albpm:BooleanFeature[@ name='collapsed']/@value='true'"> <xsl:attribute name="View"> <xsl:text>COLLAPSED</xsl:text> </xsl:attribute> </xsl:when> <xsl:otherwise> <xsl:attribute name="View"> <xsl:text>EXPANDED</xsl:text> </xsl:attribute> </xsl:otherwise> </xsl:choose> <xsl:apply-templates/> </xsl:copy> </xsl:template>
In some tools the coordinates provided for activities are given for the upper-left corner of the activity object, but for others the coordinates are based on the center of the activity object. These coordinates serve as the object pin.
When an XPDL document containing an object pin at center of activities is imported into Oracle BPM, the activities may occur at different positions than expected. This is because the object pin for activities is located in the center but Oracle BPM expects the object pin in the upper left corner. To resolve this discrepancy the activity coordinates must be recalculated.
You can use simple logic to calculate these coordinates, such as subtracting half of the activity's width from its XCoordinate and subtracting half of the activity's height from its YCoordinate.
Example B-11 shows a style sheet template that does this recalculation. Note that this template will work only if width, height, x, and y-coordinates are provided for activities.
Example B-11 Recalculating the Location of an Object Pin
<xsl:template match = "xpdl:Activity/xpdl:NodeGraphicsInfos/xpdl:NodeGraphicsInfo/xpdl:Coordinates"> <xsl:copy> <xsl:copy-of select = "@*[name() != 'XCoordinate' and name() != 'YCoordinate']"/> <xsl:attribute name = "XCoordinate"> <xsl:value-of select = "@XCoordinate - ancestor::xpdl:NodeGraphicsInfo/@Width div 2 "/> </xsl:attribute> <xsl:attribute name="YCoordinate"> <xsl:value-of select = "@YCoordinate - ancestor::xpdl:NodeGraphicsInfo/@Height div 2"/> </xsl:attribute> <xsl:apply-templates/> </xsl:copy> </xsl:template>
Some tools do not provide height and width for activities in their XPDL files. But coordinates and dimensions of activities are needed to import an XPDL file into Oracle BPM. So include templates in an XSL style sheet that will set height and width for activities and lanes. If the XPDL file does not contain height and width for activities, set some default dimensions for them. For instance, set 80x40 width and height for tasks, collapsed subprocesses, and set 30x30 width and height to events and gateways.
It can be especially difficult to set the height and width for expanded <BlockActivity> and <Subflow> elements, as an expanded <BlockActivity> element may also contain another expanded <BlockActivity> elements. Here the innermost BlockActivity height and width should be calculated first and then its parent BlockActivity. This recursion must bubble up to the topmost <BlockActivity>. It can be difficult to code this recursion process in XSL. For this reason Oracle BPM provides a feature which calculates height and width of expanded Subprocesses. To use this feature set the height and width of <BlockActivities> to 0,0 using XSL templates.
Example B-12 is an event element which does not have width and height defined.
Example B-12 Event Element that Does Not Contain Height and Width Defined
<xpdl:Activity Name="Begin" Id="Begin"> <xpdl:Event> <xpdl:StartEvent Trigger="None"/> </xpdl:Event> …………………………….. <xpdl:NodeGraphicsInfos> <xpdl:NodeGraphicsInfo LaneId="Accounting" IsVisible="true"> <xpdl:Coordinates XCoordinate="36.0" YCoordinate="110.0"/> </xpdl:NodeGraphicsInfo> </xpdl:NodeGraphicsInfos> </xpdl:Activity>
Example B-13 shows a sample style sheet template used to set height and width of activities. This template can be used if height and width of activities are not given in the XPDL document. This example sets 80 x 40 dimensions (width, height) for task elements and collapsed BlockActivities, it will set 30 x 30 dimensions to route and gateways, and it will set 0x0 dimensions to expanded BlockActivities and thus lets Oracle BPM calculate the dimensions for these expanded BlockActivity elements. This template will work for BPM studio XPDL files.
Example B-13 Setting the Height and Width of Activities
<xsl:template match = "xpdl:Activity/xpdl:NodeGraphicsInfos/xpdl:NodeGraphicsInfo"> <xsl:variable name = "activityType"> <xsl:choose> <xsl:when test = "ancestor::xpdl:Activity/xpdl:Implementation/xpdl:SubFlow"> <xsl:text>SubFlow</xsl:text> </xsl:when> <xsl:when test = "ancestor::xpdl:Activity/xpdl:Implementation"> <xsl:text>Task</xsl:text> </xsl:when> <xsl:when test = "ancestor::xpdl:Activity/xpdl:Event"> <xsl:text>Event</xsl:text> </xsl:when> <xsl:when test = "ancestor::xpdl:Activity/xpdl:Route"> <xsl:text>Route</xsl:text> </xsl:when> <xsl:when test = "ancestor::xpdl:Activity/xpdl:BlockActivity"> <xsl:choose> <xsl:when test = "ancestor::xpdl:Activity/xpdl:Extensions/albpm:ALBPMExtensions/albpm:FeatureSet/albpm:BooleanFeature[@ name = 'collapsed']/@value != 'true'"> <xsl:text>ExpandedBlockActivity</xsl:text> </xsl:when> <xsl:otherwise> <xsl:text>CollapsedBlockActivity</xsl:text> </xsl:otherwise> </xsl:choose> </xsl:when> </xsl:choose> </xsl:variable> <xsl:copy> <xsl:copy-of select = "@*"/> <xsl:attribute name = "Width"> <xsl:choose> <xsl:when test = "$activityType = 'Task' or $activityType = 'CollapsedBlockActivity' or $activityType = 'SubFlow'"> <xsl:text>80</xsl:text> </xsl:when> <xsl:when test = "$activityType = 'Route' or $activityType = 'Event'"> <xsl:text>30</xsl:text> </xsl:when> <xsl:when test = "$activityType = 'ExpandedBlockActivity'"> <xsl:text>0</xsl:text> </xsl:when> </xsl:choose> </xsl:attribute> <xsl:attribute name = "Height"> <xsl:choose> <xsl:when test = "$activityType = 'Task' or $activityType = 'CollapsedBlockActivity' or $activityType = 'SubFlow'"> <xsl:text>40</xsl:text> </xsl:when> <xsl:when test = "$activityType = 'Route' or $activityType = 'Event'"> <xsl:text>30</xsl:text> </xsl:when> <xsl:when test = "$activityType = 'ExpandedBlockActivity'"> <xsl:text>0</xsl:text> </xsl:when> </xsl:choose> </xsl:attribute> <xsl:apply-templates/> </xsl:copy> </xsl:template>
In many XPDL documents, width or height dimensions for lanes is provided depending on orientation of the parent pool. For instance, if the orientation of the parent pool is horizontal then the width of the Lane might be found in the XPDL document but not its height. As mentioned before, the height and width of lanes and activities are needed for Oracle BPM to determine the sizes of graphical elements. If the lane height or width is not found in the XPDL document, set these attributes to a value which is sufficient to hold all its containing elements.
If the height of lanes is provided but not their width, simple logic can be used to set the width of lanes. Find the largest sum of x-coordinate plus the widths of Activities, and set this value to the widths of all lanes. If the lane width is merely sufficient to hold all elements, you can find the lane right border running from the right border of activity that has the largest sum of x-coordinate and width. A small padding value can also be added to the largest sum to extend the lanes enough to allow them to appear as the containers of the other objects.
The above logic will work if all activities contain width and height values. But there are cases where activities might not contain height and width values. In such cases it is difficult to calculate lane widths using XSLT with the above logic as each activity height and width should be calculated before calculating lane height or width. To resolve this problem, Oracle BPM provides a feature that will set the lane widths or heights.
To use this feature set the missing dimension of lane to zero using XSLT. This feature assumes one dimension was provided for the lane.
If height and widths are provided for pools, Oracle BPM will use those dimensions for Pools. If these values are absent, Oracle BPM will try to calculate them. Oracle BPM will calculate both dimensions even if one of dimensions is provided. The source XPDL document must contain both dimensions for Pools to circumvent this feature
When coordinates and dimensions are provided in the XPDL file, Oracle BPM will use those values without manipulating them. But if some dimensions are missing, such as dimensions for Lanes dimensions or Subprocesses, Oracle BPM will try to calculate these dimensions. In the process of calculating dimensions, Oracle BPM will add some padding to the dimensions for the model to be friendlier but this model will look good only if the activities have some space around them. Otherwise the imported model may have borders of activities or lanes running on top of other activities or lanes. To avoid this problem position activities with some space around them.
Problems may occur when importing models containing duplicate ids for more than one lane or activity into Oracle BPM. Oracle BPM cannot create more than one lane or activity with the same name. Only one lane or activity from the source will be created, and the results will not accurately reflect the original model.
To avoid this problem, create model elements with unique ids.
If the XPDL source document is missing elements or attributes required for Oracle BPM to properly perform its conversion, then add those elements and attributes using XSLT.
For instance, there are 8 types of tasks in XPDL. For Oracle BPM to recognize these task types, a <Task> element should contain another child element which specifies whether the Task is a service task, a receive task, and so on. If these child elements are not found under a source <Task> element, that <Task> element will be converted to a default <Task> element.
For example, the <Task> element shown below is a user task but does not have a child <TaskUser> element. Hence it is assumed to be a default Task element by Oracle BPM
<Implementation> <Task /> </Implementation>
In order for the activity to be identified by Oracle BPM as user task, a <TaskUser> element must be added under Task element as follows:
<Implementation> <Task> <TaskUser> .... </TaskUser> </Task> </Implementation>
As mentioned before many attributes may be given under tool specific namespaces. If task type is not found under the XPDL namespace, try finding it in the tool specific namespace and include templates in the style sheet to include these elements under the Task element.
Example B-14 demonstrates how to include a <TaskService> element as a child of <Task> element whenever it finds an “Automatic” Task element. This template will work for XPDL source files generated by Oracle BPM Studio.
Example B-14 Including a TaskService Element as a Child of the Task Element
<xsl:template match="xpdl:Activity/xpdl:Implementation/xpdl:Task"> <xsl:copy> <xsl:copy-of select="@*"/> <xsl:if test="ancestor::xpdl:Activity/xpdl:Extensions/albpm:ALBPMExtensions/albpm:FeatureSet/albpm:StringFeature[@name='type']/@value='AUTOMATIC' and not(child::xpdl:TaskService)"> <xpdl:TaskService/> </xsl:if> <xsl:apply-templates/> </xsl:copy> </xsl:template>
Be sure that the source XPDL contains the correct elements to represent activities when they are exported as XPDL from the source tool. For example, if a model contains an event activity and while exporting that model into XPDL the tool creates <Route> or <Task> element for that Event Activity, this element must be replaced with an element that accurately represents an Event Activity.
Consider the XPDL element shown below. The activity is a start event, but instead of an event element under the <Activity> element, you find a <Route> element. When this model is imported into Oracle BPM, this activity is converted into a route activity rather than as an event activity.
Example B-15 Checking the Correctness of Activities
<xpdl:Activity Name="Group$Begin" Id="Group$Begin"> <xpdl:Route GatewayType="XOR" MarkerVisible="true"/> ………………….. </xpdl:Activitiy> The correct notation for the above element should be: <xpdl:Activity Name="Group$Begin" Id="Group$Begin"> <xpdl:Event> <xpdl:StartEvent Trigger="None"/> ………………….. </xpdl:Event> ………………………. </xpdl:Activity>
If this problem is found in your source XPDL, include templates in a style sheet to replace the incorrect elements with correct elements.