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.

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.

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.

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.

1. In the VisioMasterMap.xml file, find the master definition, which appears as:

   <Master Name="document" Extends="task">
       <Attributes>
         <Attribute Name="TaskType" Value="Send"/>
       </Attributes>
     </Master>
   

   This definition is followed by additional master elements that use the Like attribute to clone the first definition and map additional Visio objects as mentioned below:

   <Master Name="sequential data" Like="data object"/>
   <Master Name="data" Like="data object"/>
   <Master Name="report" Like="report" />
   

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="report"/>
   

<Master Name="flow">
    <BPMNObject>SequenceFlow</BPMNObject>
</Master>
 
<Master Name="conditional flow" Extends="flow">
    <Attributes>
      <Attribute Name="ConditionType" Value="Expression"/>
    </Attributes>
</Master>

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

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>

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.

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.