D Preparing Processes for Import into Oracle BPM
This appendix describes how to improve the results of importing process models created in Microsoft Visio and tools that support XPDL (Process Definition Language).
This appendix includes the following sections:
D.1 Preparing a Visio File to Import as a BPMN Process
You can import Visio files directly into Business Process Composer. Business Process Composer maps Visio elements to Business Process Model and Notation (BPMN) flow objects using special mapping files named VisioMasterMap.xml and VisioUserMap.xml.
However, Oracle only supports modifying the Visio mapping when using Business Process Management (BPM) Studio within Oracle JDeveloper.
The instructions in this section describe how to customize the mapping for BPM Studio. After importing models into BPM Studio, you can move the models to Business Process Composer by exporting your project and then importing it into Business Process Composer.
The mapping files define the target BPMN flow object for each Visio element. These files are located in the following directory within the Fusion Middleware home directory:
.../soa/plugins/jdeveloper/extensions/oracle.bpm.converter.
Note:
Do not edit VisioMasterMap.xml directly because this file may be overwritten during an upgrade. You can override the mappings in this file by creating and editing a separate file called VisioUserMap.xml.
To change the default mapping defined in VisioMasterMap.xml:
D.1.1 Working of Visio Shape Mapping
Microsoft Visio is a diagramming tool that allows users to draw any kind of diagram. However, only process models can be imported into Business Process Composer. Since Visio includes several different process modeling templates and stencils and there are many more available from third parties, the converter attempts to map each Visio shape object (rectangles, lines, polygons, and so on) to an appropriate BPMN symbol. It does this by using the VisioMasterMap.xml and VisioUserMap.xml files.
Each shape added to a Visio drawing page from a stencil is tagged with the name of the master object from which it was created. For example, if a Visio user drags several rectangle shapes named Task from a stencil onto the page and then renames them, each shape still has the master name Task associated with it. You can see this in Visio by selecting a shape and then choosing Format > Special from the menu.
Note:
If you don't see the menu item Format > Special, select Tools > Options > Advanced, and check the box Run in developer mode. This option may be in a different location depending on your version of Visio.
If a shape does not have a master, which is the case for objects drawn directly from the Drawing toolbar (such as plain rectangles and circles), the converter looks at the shape Name field, which you can also see in the Format > Special dialog.
Oracle Business Process Composer then looks for an entry in VisioUserMap.xml and VisioMasterMap.xml that matches the shape master name. For example, if the shape master is Task, the converter finds the following map entry:
<Master Name="task"> <BPMNObject>Task</BPMNObject> </Master>
This tells the converter that all shapes with a master of Task should be imported as a BPMN Task symbol.
Note:
Master names are not case sensitive, so task matches Visio masters task, Task, and TASK.
Master map entries can also define additional BPMN properties. The following entry maps the Visio master named gateway to the BPMN Gateway symbol, but also sets some BPMN attribute values:
<Master Name="gateway"> <BPMNObject>Gateway</BPMNObject> <Attributes> <Attribute Name="ExclusiveType" Value="Data"/> <Attribute Name="GatewayType" Value="Exclusive"/> <Attribute Name="MarkerVisible" Value="false"/> </Attributes> </Master>
Attributes can be set to a text, numeric, or boolean value (true and false) depending on what the BPMN standard requires.
Attribute values can also be derived from properties defined in the Visio shape itself. The following master map entry for a task shape in the Visio 2010 BPMN stencil sets the BPMN attributes TaskType and Implementation from corresponding shape properties.
<Master Name="Vis2010 Task" Extends="Vis2010 Activity"> <BPMNObject>Task</BPMNObject> <Attributes> <Attribute Name="TaskType" Value="Prop.BpmnTaskType" SrcType="visio" /> <Attribute Name="Implementation" Value="Prop.BpmnImplementation" SrcType="visio" /> </Attributes> </Master>
The XML attribute "srcType" tells the converter how to interpret the attribute value. Setting srcType to visio indicates that the value is defined in the Visio object's "ShapeSheet". To view the ShapeSheet of a Visio shape, select the shape and choose Window > Show ShapeSheet. The most common properties are defined in the Custom Properties and User-defined Cells sections, which correspond the Prop and User prefixes respectively. Property names can also be derived from the XML tag hierarchy in Visio files saved in the *.vdx format.
D.1.1.1 Conditional Mapping
The master map files also support conditional mapping. This is useful when two different Visio stencils use the same master names, but use different Visio properties to store BPMN attribute values. For example, the following entry uses a condition to detect whether an Intermediate Event shape from the TrisoTech BPMN stencil is a Throwing or Catching event:
<Master Name="Intermediate Event" Extends="Triso Object"> <BPMNObject>IntermediateCatchEvent</BPMNObject> <Conditions> <Condition Name="Direction" Value="Prop.direction" SrcType="visio" Equals="Catching" /> </Conditions> <Attributes> <Attribute Name="Trigger" Value="Prop.IntermediateEvent_trigger" SrcType="visio" /> </Attributes> </Master>
A special condition attribute of NotNull (not case sensitive) can be used to test if a specific Visio property exists. The following master map entry is matched if the master name is Start Event and it contains a property named Prop.StartEvent_Trigger:
<Master Name="Start Event"> <BPMNObject>Event</BPMNObject> <Conditions> <!-- this condition confirms that this is from Trisotech stencil --> <Condition Name="Is Triso shape" Value="Prop.StartEvent_Trigger" SrcType="visio" Equals="NotNull" /> </Conditions> <Attributes> <Attribute Name="EventType" Value="Start" SrcType="bpmn" /> <Attribute Name="Trigger" Value="Prop.StartEvent_Trigger" SrcType="visio" /> <Attribute Name="isInterrupting" Value="Prop.StartEvent_Interrupting" SrcType="visio" /> </Attributes> </Master>
If there are more than one master map entry with the same name, the first one encountered with conditions that are all true is used. If no conditional entries match, the first unconditional master map entry for the master name is used. The VisioUserMap.xml file is processed first, so any matching master map entries in this file supersedes all other entries with the same name in VisioMasterMap.xml.
A special master map entry name of "*" is used to match all masters. This must only be used with conditions. This is useful for Visio templates that allow the user to change the BPMN object type (such as from Task to Sub Process) after adding the shape to the diagram. In this scenario, the shape master is set to the original master, even though the shape has been changed to look like a different symbol. For example, the following entries use the "*" wildcard to match entries based only on a shape property value:
<Master Name="*" Extends="Vis2010 Task"> <Conditions> <Condition Name="Activity Type" Value="Prop.BpmnActivityType" SrcType="visio" Equals="Task" /> </Conditions> </Master> <Master Name="*" Extends="Vis2010 Subprocess"> <Conditions> <Condition Name="Activity Type" Value="Prop.BpmnActivityType" SrcType="visio" Equals="Sub-Process" /> </Conditions> </Master>
If a Visio master name or shape name is not matched by any entry in VisioUserMap.xml or VisioMasterMap.xml, the BPMN object type is determined by examining the shape attributes. The basic rules are:
-
If a shape is a connector (usually a line used to connect other shapes), it is imported as a
SequenceFlow. -
A rectangle shape that contains text, but has no border and no fill color is imported as a Text Annotation.
-
A shape that is a circle or an ellipse is imported as an event.
-
A rectangle that encloses other shapes is imported as an expanded Sub Process if no sequence flows cross the boundary of the shape.
If a sequence flow connects to a shape inside the boundary of the rectangle, it is treated as a BPMN Group symbol, but since Oracle BPM does not support the Group symbol, it will be ignored.
-
Any shape that does no match the above rules is imported as a Task.
Note:
Be careful when using the Visio Group command to combine shapes. This is sometimes convenient when moving and rearranging shapes in Visio, but confuses the converter since a group of shapes is treated as a single object during import and does not have a master, so is likely be imported as a single task.
D.1.2 Visio Modelling Tips
Consider the following tips when you create your Visio files:
-
Use a good stencil.
-
Ensure all shapes are based on a master shape.
-
Glue all connectors to other shapes on both ends.
-
Do not create flows by connecting shorter lines end-to-end.
Use one continuous connector for each flow.
-
Do not group objects manually.
-
Always label shapes and lines by selecting and typing.
Do not create separate text boxes.
-
Do not invent new symbols that do not cleanly map to BPMN objects.
-
Verify that all masters that you use are defined in VisioMasterMap.xml or VisioUserMap.xml.
-
Do not use on-page and off-page connectors or link events.
They are not supported by BPM.
D.1.3 Updating VisioUserMap.XML
This section describes a possible scenario for importing a Visio file into a BPMN process.
To update VisioUserMap.xml:
In this example, the original Visio file contains a shape with the master Report that we want to map to a Send task. Since Report is not currently mapped in VisioMasterMap.xml, the shape is being imported as an abstract task. By default, VisioMasterMap.xml maps this shape to a Send task. If you use it strictly as an input or output object, it is more accurate to map it to a BPMN data object.
An object can be mapped to an existing BPMN object with additional or different attributes by using the Extends attribute, as shown here:
<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.
D.1.4 Valid BPMN Element Values
The following are valid values for the <BPMNObject> element:
-
Task:
-
UserTask
-
ManualTask
-
ReceiveTask
-
SendTask
-
ServiceTask
-
ScriptTask
-
BusinessRuleTask
-
-
Subprocess:
-
AdHocSubprocess
-
CallActivity
-
-
Event:
-
StartEvent
-
EndEvent
-
IntermediateCatchEvent
-
IntermediateThrowEvent
-
BoundaryEvent
-
-
Gateway:
-
ExclusiveGateway
-
InclusiveGateway
-
ParallelGateway
-
ComplexGateway
-
EventBasedGateway
-
-
DataObject:
-
DataObjectReference
-
-
Group:
-
Annotation
-
TextAnnotation
-
-
Lane
-
Pool:
-
Participant
-
-
MessageFlow
-
SequenceFlow
-
Association
-
null
Note:
When you assign the null value to a Visio element, no BPMN flow object is created.
D.1.5 BPMN Element Attributes
The following tables show valid values for BPMN attributes based on the basic BPMN types of BPMN flow objects:
Task attributes and values
Table D-1 shows the valid attributes and values for BPMN tasks.
Table D-1 Task Attributes and Values
| Attribute | Values |
|---|---|
|
TaskType |
None, Script, Reference, Service, User, Manual, Send, Receive |
|
LoopType |
Standard, MultiInstance |
|
isForCompensation |
true, false |
|
Implentation |
Any text |
|
OperationRef |
Any text |
Subprocess attributes and values
Table D-2 shows the valid attributes and values for BPMN subprocesses
Table D-2 Subprocess Attributes and Values
| Attribute | Values |
|---|---|
|
isExpanded |
true, false |
|
isATransaction |
true, false |
|
LoopType |
Standard, MultIinstance |
|
isForCompensation |
true, false |
|
AdHoc |
true, false |
|
IsCollapsed |
true, false |
|
SubprocessType |
Embedded, Reusable, Reference |
|
ExpandedWidth |
number |
|
ExpandedHeight |
number |
|
ModelReference |
text |
|
CalledElement |
text |
|
TriggeredByEvent |
true, false |
|
LoopMaximum |
number |
|
LoopCounter |
number |
|
LoopCondition |
text |
|
MultiInstanceCondition |
text |
|
MultiInstanceIsSequential |
true, false |
Event attributes and values
Table D-3 shows the valid attributes and values for BPMN events.
Table D-3 Event Attributes and Values
| Attribute | Values |
|---|---|
|
EventType |
Start, Intermediate, End |
|
Trigger |
Escalate, None, Message, Timer, Conditional, Signal, Multiple, Error, Cancel, Compensation, Link, Terminate |
|
EventDirection |
Throw, Catch |
|
IsInterrupting |
true, false |
|
CancelActivity |
true, false |
|
TimeCycle |
text |
|
TimeDate |
text |
Gateway attributes and values
Table D-4 shows the valid attributes and values for BPMN gateways.
Table D-4 Gateway Attributes and Values
| Attribute | Values |
|---|---|
|
GatewayType |
Parallel, Inclusive, Exclusive, Complex |
|
ExclusiveType |
Event, Data |
|
MarkerVisible |
true, false |
Sequence flow attributes and values
Table D-5 shows the valid attributes and values for BPMN sequence flows.
Table D-5 Sequence Flow Attributes and Values
| Attribute | Values |
|---|---|
|
ConditionType |
None, Expression, Default |
|
ConditionExpression |
text |
Association attributes and values
Table D-6 shows the valid attributes and values for BPMN data objects.
Table D-6 Association Attributes and Values
| Attribute | Value |
|---|---|
|
Direction |
None, One, Both |
|
AssociationDirection |
None, One, Both |
Pool attributes and values
Table D-7 shows the valid attributes and values for BPMN pools.
Table D-7 Pool Attributes and Values
| Attribute | Values |
|---|---|
|
BoundaryVisible |
true, false |
|
IsHorizontal |
true, false |
Lane Attributes and Values
Table D-8 shows the valid attributes and values for BPMN Lanes.
Table D-8 Lane Attributes and Values
| Attribute | Values |
|---|---|
|
BoundaryVisible |
true, false |
|
IsHorizontal |
true, false |
D.1.6 Handling Extraneous Text
When Business Process Composer imports a Visio file, it creates a separate process for each pool that it finds in the source file. Since BPMN models can also depict a process without a visible pool boundary, Visio shapes that are not inside a pool or lane, including legends, titles, and so on, are added to a separate process. This may result in a BPM process containing only extraneous elements that are not process objects. To avoid converting these shapes, you can add entries to the VisioUserMap.xml file that map the corresponding shape masters to null, which causes the converter to ignore the shape. If the shape doesn't have a master, the converter looks for an entry that matches the shape name as defined in Visio's Format Special dialog. For example, if your Visio file contains an object named SheetName, mapping that value to null in VisioUserMap.xml causes it to be ignored during import:
<Master Name="SheetName">
<BPMNObject>null</BpmnObject>
</Master>
D.2 Customizing XPDL Import Using XSLT
XPDL is an interchange format created by the Workflow Management Coalition for exchanging process model information between workflow automation tools. BPM supports importing XPDL revisions 1.0, 2.0, 2.1, and 2.2.
There are currently many process modeling tools that support XPDL, but not all tools implement the standard in the same way. Oracle BPM supports XPDL files that adhere strictly to the official XPDL specification (available at http://www.xpdl.org) and uses Extensible Stylesheet Language Transformation (XSLT) to transform non-conforming formats into the format that BPM expects. The XPDL importer also recognizes several extended attributes that triggers special transformation logic for common differences so that complex XSLT logic is not required.
D.2.1 Common Transformation Requirements
The most common transformations include the following:
-
Adjust object coordinates from being relative to a parent container to being relative to the upper-left corner of the drawing page.
-
Adjust object coordinates to represent the upper-left corner of the object.
-
Recreate sequence flow routing.
-
Create missing elements and attributes.
-
Removing elements.
-
Move element and attribute values from a vendor-specific namespace to the XPDL namespace.
D.2.2 Overview of Transformation Logic
This section includes instructions on handling some of the common requirements. The examples can help you create your own transformation rules to handle any other requirements you may encounter.
When importing XPDL files using BPM Studio, the import process uses special files located in the following folder:
ORACLE_HOME>/soa/plugins/jdeveloper/extensions/oracle.bpm.converter
The file XSLFilePaths.xml serves as map between various vendor formats and the appropriate XSL file to use for the transformation. Following is a sample entry in this file:
<XSLFilePath Vendor="Bizagi Process Modeler">BizagiPatch.xsl</XSLFilePath>
The Vendor attribute must match the value of the XML element /Package/PackageHeader/Vendor in the source file. Following is an example fragment from a Bizagi XPDL file that matches the line above:
<?xml version="1.0" encoding="utf-8"?><Package xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance Id="bf8a25f5-275d-4546-8d07-dfa02666c51d" Name="Sample" xmlns="http://www.wfmc.org/2009/XPDL2.2"> <PackageHeader> <XPDLVersion>2.2</XPDLVersion> <Vendor>Bizagi Process Modeler</Vendor> <Created>2013-07-29T19:17:31.931003-07:00</Created> <ModificationDate>2013-07-29T19:18:53.207857-07:00</ModificationDate> <Description>Phases</Description> <Documentation /> </PackageHeader>
As an alternative to the Vendor attribute, you may specify a Condition attribute that contains a valid XPATH expression. If the expression evaluates to true for a source file, the corresponding XSL file is used. Following is an example that uses the Condition attribute:
<XSLFilePath Condition="substring(/Package/PackageHeader/Vendor/text(), 0, 22)='Metastorm ProVision 6'">ProvisionPatch.xsl</XSLFilePath>
This expression compares the first 22 characters of the Vendor attribute to the string "Metastorm ProVision 6". This technique may be used to match a combination of Vendor and Version, for example.
After a specific XSL file is identified, the importer applies the XSLT transformation against the source file and then imports the transformed XML. If no Vendor or Condition matches the source file, the importer uses the file patch.xsl.
D.2.3 Special Attributes
The XPDL importer looks for optional attributes, defined using XPDL's extensibility feature, that serve as instructions to the importer for handling special cases that are difficult to code as XSLT. These attributes must be located in the /Package/ExtendedAttributes section as follows:
<Package> <Extended Attributes> <ExtendedAttribute Name="attribute name" Value="value" /> <Extended Attributes></Package>
Table D-9 Extended Attributes and Valid Values
| Attribute Name | Valid Values | Default Values | Description |
|---|---|---|---|
|
redrawConnections |
true, false |
false |
Ignore sequence flow path attributes and create new paths programmatically. |
|
activitiesObjectPin |
Upperleft Lowerleft Center |
Upperleft |
Indicates that the X, Y coordinates of an activity (flow node) correspond to either the upper-left corner of the rectangular bounds of the symbol, the lower-left corner, or the center of the symbol. |
|
lanesRelativeToPools |
true, false |
false |
Indicates that the X, Y coordinates of lane objects are relative to their parent pool. |
|
activitiesRelativeToLanes |
true, false |
false |
Indicates that the X, Y coordinates of activities are relative to their parent lane. |
|
activitiesRelativeToPools |
true, false |
false |
Indicates that the X,Y coordinates of activities are relative to their parent lane. NOTE: activitiesRelativeToLanes and activitiesRelativeToPools cannot both be set to true. |
|
subProcessChildPositionRelative |
true, false |
false |
Indicates that the X, Y coordinates of activities that are inside of a subprocess are relative to the subprocess. |
|
recalculatePoolsAndLanesPositions |
true, false |
false |
Forces the importer to calculate the X, Y coordinate of pools and lanes based on the position and height of the pools and lanes that precede it. This must be set to true if the source model does not include positional coordinates for pools and lanes. |
D.2.3.1 Object Coordinates
The XPDL specification states that all object coordinates specify the upper-left corner of the object's bounding rectangle on a page coordinate system with the origin (0,0) in the upper-left corner of the page. For the purposes of this example, the height of pool 1 in Figure D-1 is 100 units, pool 2 is 200 units tall, and each lane in Pool 2 is 100 units tall.
Figure D-1 Example BPMN Process
Using the global coordinate system of the XPDL specification, the X, Y coordinates of the objects depicted in the diagram are as follows:
- Pool 1 - (0,0)
- Pool 2 - (0, 200)
- Lane 1 - (40, 200)
- Lane 2 - (40, 300)
- Task 1 - (175, 15)
- Task 2 - (175, 215)
- Task 3 - (325, 315)
A source file specifying these coordinates is imported correctly into BPM with no transformation required, since all coordinates are relative to the upper-left corner of the page.
Consider a tool where object coordinates stored in the XPDL are relative to their parent pool and lane. In this case, the coordinates are:
- Pool 1 - (0,0)
- Pool 2 - (0, 200)
- Lane 1 - (40, 0)
- Lane 2 - (40, 100)
- Task 1 - (175, 15)
- Task 2 - (175, 15)
- Task 3 - (325, 15)
Note that lane 1 in Pool 2 has a Y coordinate of 0. Since this tool stores lane positions relative to their parent pool, a value of 0 indicates that the top edge of the lane coincides with the top edge of the pool. Likewise, the Y coordinate of Lane 2 is 100, indicating that it is 100 units below the top edge of the pool.
Each task has a Y coordinate of 15, indicating that its upper-left corner is 15 units below the top edge of its respective lane.
In order for this diagram to be correctly imported into Oracle BPM, the following extended attribute values must be set:
Table D-10 Extended Attribute Values
| Attribute Name | Value |
|---|---|
|
lanesRelativeToPools |
true |
|
activitiesRelativeToLanes |
true |
The XSLT code to add these attributes to the XPDL are as follows:
<xsl:template match="Package/ExtendedAttributes">
<xsl:copy> <xsl:copy-of select="@*"/> <ExtendedAttribute Name="lanesRelativeToPools" Value="true"/> <ExtendedAttribute Name="activitiesRelativeToLanes" Value="true"/> <xsl:apply-templates/> </xsl:copy> </xsl:template>
A minor variation is when lanes are relative to their parent pools, but activities are relative to their parent pool, not their parent lane. In this scenario, the object coordinates may be as follows:
- Pool 1 - (0,0)
- Pool 2 - (0, 200)
- Lane 1 - (40, 0)
- Lane 2 - (40, 100)
- Task 1 - (175, 15)
- Task 2 - (175, 15)
- Task 3 - (325, 115)
Pool 1 - (0, 0)
The only difference is that the Y value of Task 3 is 115 instead of 15. In this scenario, the extended attributes must be set to:
Table D-11 Extended Attributes and Values
| Attribute Name | Value |
|---|---|
|
lanesRelativeToPools |
true |
|
activitiesRelativeToPools |
true |
D.2.3.2 Activity Local Coordinate System
The XPDL specification dictates that activity positions represent the location of the upper-left corner of the bounding rectangle on the page coordinate system. However, some tools use the center of the object as the location on the page. This is known as the local coordinate system of the object.
The easiest way to understand this is to imagine pinning a postcard onto a cork board with a push pin. The hole that the pin makes in the board represents the position of the card on the board. Measuring from the left edge of the board to the pin provides the X coordinate and measuring from the top edge of the board to the pin provides the Y coordinate. However, the placement of the pin in the card itself also contributes to the correct positioning of the card. If the pin is placed in the extreme upper-left corner of the card, the position will be different than when the pin is directly in the center of the card.
Using the BPMN example in Figure D-1, an XPDL tool that uses the center of an activity as the local pin location have task coordinates as follows:
- Task 1 - (220, 50)
- Task 2 - (220, 250)
- Task 3 - (370, 350)
The X coordinates are shifted to the right by 45 units (task boxes are 90 units wide) and the Y coordinates are in the vertical center of each lane, (which are 00 units high).
When an XPDL tool uses the center of activities as the basis for their position on the page, after importing into BPM they are shifted down and to the right by half their width and height because the importer is expecting all coordinates to represent the position of the upper-left corner. To correct this, you must set the following attribute:
activitiesObjectPin CENTER
The XSLT code for this is:
<xsl:template match="Package/ExtendedAttributes"> <xsl:copy> <xsl:copy-of select="@*"/> <ExtendedAttribute Name="activitiesObjectPin" Value="CENTER"/> <xsl:apply-templates/> </xsl:copy> </xsl:template>
D.2.3.3 Removing Invisible Elements
Oracle BPM considers all graphical elements of the source XPDL file to be visible elements, even if their visibility is set to false. Therefore, you may find some differences as formerly invisible elements are visible in the converted BPMN process, like the activity elements shown here:
<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>
In this example the activity's visibility is set to false, but when this model is imported into Oracle BPM, you can see this activity. To eliminate invisible elements include a style sheet template to remove them:
<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>
D.2.3.4 Handling Proprietary Namespaces
Some XPDL tools use a proprietary namespace in addition to the standard XPDL namespace. This is often to support special features and attributes of their tool, but sometimes information is stored in a proprietary namespace that should be in the XPDL namespace.
Considering the following XPDL file header, which defines multiple namespaces:
<?xml version="1.0" encoding="UTF-8"?> <Package Id="1" xsi:schemaLocation="http://www.wfmc.org/2004/XPDL2.0alpha http://www.wfmc.org/standards/docs/TC-1025_bpmnxpdl_24.xsd" xmlns="http://www.wfmc.org/2004/XPDL2.0alpha" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xpdl="http://www.wfmc.org/2004/XPDL2.0alpha" xmlns:ix="http://www.igrafx.com/2007/igrafx-document" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:igxpdl="http://www.igrafx.com/2008/igrafx-xpdl2">
The body of the XML document uses the default namespace for standard XPDL elements, but uses the igxpdl namespace for defining document pages.
<igxpdl:Page Name="Update Spreadsheet" ID="Page1" IgnorePools="true"> <PageLayout xmlns:i="http://www.igrafx.com/2007/igxmldoc" xmlns="http://www.igrafx.com/2007/igrafx-document"> <Page UseDocumentSettings="false" Orientation="Landscape" Width="16837" Height="11905"> <FitTo PagesWide="1" PagesTall="1" /> </Page> </PageLayout> </igxpdl:Page> <igxpdl:Page Name="Submit Instructions" ID="Page2" IgnorePools="true"> <PageLayout xmlns:i="http://www.igrafx.com/2007/igxmldoc" xmlns="http://www.igrafx.com/2007/igrafx-document"> <Page UseDocumentSettings="false" Orientation="Landscape" Width="16837" Height="11905"> <FitTo PagesWide="1" PagesTall="1" /> </Page> </PageLayout> </igxpdl:Page> </igxpdl:Pages>
The XPDL importer does not recognize any namespace other than the XPDL namespace and expects to find a Pages element in that namespace. To support this requirement, create an XSLT template that creates the XPDL Pages element and children by copying the information from the custom namespace elements.
<xsl:template match="//xpdl21:Package"> <xsl:copy> <xsl:copy-of select="@*"/> <xsl:if test="child::igxpdl:Pages"> <xsl:element name="Pages"> <xsl:for-each select="//igxpdl:Pages/igxpdl:Page"> <xsl:element name="Page"> <xsl:attribute name="Id"> <xsl:value-of select="./@ID"/> </xsl:attribute> <xsl:attribute name="Name"> <xsl:value-of select="./@Name"/> </xsl:attribute> </xsl:element> </xsl:for-each> </xsl:element> </xsl:if> <xsl:apply-templates/> </xsl:copy> </xsl:template>
The result is a new section in the default namespace as shown below:
<Pages> <Page Id="Page1" Name="Update Spreadsheet" /> <Page Id="Page2" Name="Submit Instructions" /></Pages>
D.2.3.5 Supporting Multiple XPDL Versions
If you are using a tool that has been upgraded to support newer versions of XPDL, you may have models that have been saved using different XPDL formats. When creating XSLT templates for multiple XPDL versions, you may have to include rules for each namespace.
For example, consider a tool that saved files in XPDL 2.1 format and later in XPDL 2.2 format and used different namespace values of xpdl21 and xpdl22 respectively. The XSLT file must define both namespaces and they must match the namespaces that appear in the tool's XPDL files.
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xpdl21="http://www.wfmc.org/2008/XPDL2.1" xmlns:xpdl22="http://www.wfmc.org/2009/XPDL2.2">
You then define separate templates for each namespace, such as:
<!-- Set extended Attribute for xpdl 2.1 --> <xsl:template match="xpdl21:Package/xpdl21:ExtendedAttributes"> <xsl:copy> <xsl:copy-of select="@*"/> <xpdl21:ExtendedAttribute Name="subProcessChildPositionRelative" Value="true"/> <xpdl21:ExtendedAttribute Name="activitiesObjectPin" Value="CENTER"/> <xsl:apply-templates/> </xsl:copy> </xsl:template> <!-- Set extended Attribute for xpdl 2.2 --> <xsl:template match="xpdl22:Package/xpdl22:ExtendedAttributes"> <xsl:copy> <xsl:copy-of select="@*"/> <xpdl22:ExtendedAttribute Name="redrawConnections" Value="true"/> <xpdl22:ExtendedAttribute Name="subProcessChildPositionRelative" Value="true"/> <xpdl22:ExtendedAttribute Name="activitiesObjectPin" Value="CENTER"/> <xsl:apply-templates/> </xsl:copy> </xsl:template>
The logic for each XPDL format can be the same or different depending on the requirements.
D.2.3.6 Testing and Debugging XSLT
Oracle highly recommends that you create and test your custom XSLT using a programming IDE (Interactive Development Environment), such as Oracle JDeveloper, that supports validation of the XSLT and interactive execution so that you can view the output XPDL and fix issues easily. To view a demonstration explaining how to edit and debug XSLT in Oracle JDeveloper, open the following link in your browser:
http://www.oracle.com/technetwork/developer-tools/jdev/xml-viewlet-swf-089240.htmlhttp://www.oracle.com/technetwork/developer-tools/jdev/xml-viewlet-swf-089240.html