Skip Headers
Oracle® Fusion Middleware Business Process Composer User's Guide for Oracle Business Process Management
11g Release 1 (11.1.1.7)

Part Number E15177-11
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

E Preparing Processes for Import into BPMN

This appendix provides information on how to modify your Microsoft Visio and XPDL processes so that they are more easily converted to BPMN.

This appendix contains the following sections:

E.1 Preparing a Visio File to 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 map file defines how each Visio element is mapped to a BPMN flow object. It is located in the following directory in the Oracle 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 a file called VisioUserMap.xml.

The user map is used to extend and/or override the master map. After parsing VisioMasterMap.xml Business Process Composer checks to see if VisioUserMap.xml exists. It then modifies its rules accordingly.

The Visio import module is designed for extensibility. You can 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 default defined in 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 new mappings or overwrite existing entries in the main map. VisioUserMap.xml should contain only the extended or overridden entries and should not repeat all the original entries.

Example E-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>

E.1.1 How to Update 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 named Report, that you want to map to a data object. By default, VisioMasterMap.xml maps this shape to a send task. If you to use it strictly as an input /output object, it is more accurate to map it to a Data Object.

  1. 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"/>
    
  2. 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 E-2 shows how an object can be mapped to an exiting BPMN object with additional or different attributes by using the Extends attribute.

Example E-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 the above example, the Visio object conditional flow is mapped to the SequenceFlow BPMN flow object, but has added the attribute “ConditionType” to the value “Expression.”

E.1.2 Valid BPMN Element Values

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.

E.1.3 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 E-1 show the valid attributes and values for BPMN tasks.

Table E-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 E-2 show the valid attributes and values for BPMN subprocesses

Table E-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 E-3 show the valid attributes and values for BPMN events.

Table E-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 E-4 show the valid attributes and values for BPMN gateways.

Table E-4 Gateway Attributes and Values

Attribute Values

GatewayType

Parallel, Inclusive, Exclusive, Complex

ExclusiveType

Event, Data

MarkerVisible

true, false


Sequence flow attributes and values

Table E-5 show the valid attributes and values for BPMN sequence flows.

Table E-5 Sequence Flow Attributes and Values

Attribute Values

ConditionType

None, Expression, Default


Association attributes and values

Table E-6 show the valid attributes and values for BPMN data objects.

Table E-6 Association Attributes and Values

Attribute Value

Direction

None, One


Pool attributes and values

Table E-7 show the valid attributes and values for BPMN pools.

Table E-7 Pool Attributes and Values

Attribute Values

BoundaryVisible

true, false


E.2 How to Customize XPDL Import Using XSL Doc

The conversion of models from source to target often 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. When this occurs, an XSLT transform may be used to create a better match between the original XPDL diagram and converted BPMN process.

The following section describes the recommended procedures 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. When performing the conversion, Business Process Composer searches 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 the XSLFilePaths.xml, the vendor name is 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.

  1. Create a custom XSLT file.

    Using an XML editor, create a new XSLT file. You should place the XSLT file in the XML directory that contains XSLFilePaths.xml.

  2. Open the XPDL you are importing, 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”.

  3. 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_Home>\jdeveloper\jdev\extensions\tutor\xml
    
  4. 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 shown in the following 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.

  5. Import the XPDL file in Oracle BPM. Your file will be transformed and processed according to the rules specified in the custom XSLT file.

E.3 Preparing an XPDL File to be Imported as a BPMN Process

When importing XDPL files that do not conform to XPDL 2.1 or might be missing elements that Oracle BPM expects, you can customize the conversion using XSLT. See Section E.1, "Preparing a Visio File to Import as a BPMN Process" for instructions on integrating custom XSLT to produce the best results.

This section provides several sample XSLT templates to handle common situations that you may encounter when importing XPDL files.

The files mentioned in this appendix are located in a directory named XML in the Oracle Tutor install directory. These are located in the JDeveloper install directory at:

<Jdeveloper_Home>/jdeveloper/jdev/extensions/tutor/xml.

The following are requirements apply when importing business processes into Oracle BPM:

E.3.1 Handling Namespaces

You should 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.

If your XPDL document contains a different default namespace, the elements and attributes are treated as conforming to XPLD 2.1 during import. This will probably produce poor results. XPDL source documents that do not conform to XPDL 2.1 must be transformed via XSL into valid XPDL 2.1 format.

The following possible scenarios are possible:

  • The source XPDL elements user the default namespace and conform to XPDL 2.1.

  • The source XPDL elements are in default namespace but they don't conform to XPDL 2.1.

  • The source XPDL elements are not in default namespace and they don't conform to XPDL 2.1.

  • The source XPDL elements are not in default namespace but they conform to XPDL 2.1.

Example E-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 root element of the stylesheet. 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 E-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>

E.3.2 Handling Relative Coordinates

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 the coordinates provided for pools are relative, then Business Process Composer renders all pools overlapping each other. Business Process Composer 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 the 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 transform, 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.

E.3.3 Handling Extended Attributes

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.

E.3.4 Handling redrawConnections

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 E-4 shows how to set this attribute.

Example E-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/>.

E.3.5 Handling isRelativeObjectCoordinates

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 then every coordinate is measured from the 0,0 point at the top left corner of the diagram. 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. Otherwise, you should include templates in your style sheet to make them conform to the relative coordinates rules.

Example E-5 shows how to include the <ExtendedAttribute/> element in the <ExtendedAttributes/> element, which is a child of the <Package/> element, is given below.

Example E-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>

E.3.6 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. Thus you may find some differences as formerly invisible elements will be visible in the converted BPMN process.

To resolve this issue, you must remove these elements from the XPDL with the help of an XSL style sheet templates as shown in Example E-6.

Example E-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>

In this example 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 E-7 shows how to remove invisible activities.

Example E-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>

E.3.7 Handling the Orientation Attribute

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 E-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 E-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>

E.3.8 Specifying the View Type for Subprocesses

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 E-9 shows a style sheet used to add the view attribute to <Subflow> elements.

Example E-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 E-10 shows a sample style sheet template that adds the View attribute to <BlockActivity> elements. This template will work XPDL files generated by Oracle Business Process Management Studio. 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 E-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>

E.3.9 Handling the Object Pin

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 E-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 E-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> 

E.3.10 Modifying the Height and Width of Activities

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 E-12 is an event element which does not have width and height defined.

Example E-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 E-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 Oracle BPM Studio XPDL files.

Example E-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>

E.3.11 Modifying the Height and Width of Lanes

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.

E.3.12 Modifying the Height and Width of Pools

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

E.3.13 Location of Activities

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.

E.3.14 Including Missing Elements

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 E-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 E-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>

E.3.15 Checking the Correctness of Activities

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 E-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.