Add-ons

Installation Instructions

Release Notes

Feature List

Support

License

Support Forum

SECTION 01 | Introduction
Thank you for your interest in Orthogonal Toolbox; we hope you will find this utility useful! Further, we hope these release notes will answer any questions you may have regarding this product. We also encourage you to visit us on the web for further information, support, and resources:

www.orthogonalsoftware.com

SECTION 02 | System Requirements
The following is required in order to use Orthogonal Toolbox:

Microsoft® Visio® (2002/Version 10) for Enterprise Architects as bundled with Microsoft Visual Studio® .Net 2002/2003 Enterprise Architect Edition. This is the only version of Visio that supports the ORM/ER Source Models that this tool enhances. However, this tool also supports Microsoft Visio 2002/2003 Professional, but only for Database Model Diagrams (there are no ORM/ER Source Models in Visio Professional, and thus some features of this tool will be disabled).

The Microsoft .Net Framework (1.0.3705.0 or later). If this is not installed, you can download the framework from Microsoft. As of the time of this writing, you can find the .Net Framework via: http://windowsupdate.microsoft.com/.

If applicable to the supported version of Visio you have installed, we also recommend that you have (at a minimum) installed Visio for Enterprise Architects 2002 Service Release 1 (SR-1). As of the time of this writing, that service release can be found at:

http://www.microsoft.com/downloads/release.asp?ReleaseID=37591&area=search&ordinal=7.

SECTION 03 | Installation Instructions
To install Orthogonal Toolbox:

1. Download the zip file and extract the contents of the zip file to any (temporary) location.
2. Run (Start | Run… then Browse… to the extract location) setup.exe.
3. Follow the instructions of the installation utility.
4. Once installation is complete, you can access Orthogonal Toolbox by opening/creating an ORM Source Model and/or a Database Model Diagram within Visio.
5. Look for the toolbar titled “Orthogonal Toolbox”. If the toolbar is not visible, it can be made visible via View | Toolbars | Orthogonal Toolbox.
6. Once the toolbar is visible, you can use the utility by clicking the button labeled “Orthogonal Toolbox”.

SECTION 04 | Features
Orthogonal Toolbox currently contains the following features/functionality:

• XML export of the majority of the meta-model information contained in the ORM Source Diagram
• XML export of much of the meta-model information contained in the Database Model and ER Source Model Diagrams
• User selection of an XSLT style sheet to apply to the XML export
• User selection of model element types to be exported
• Bulk Import of fact types into ORM Source Models
• Model Element browser that displays element properties and can delete most model elements
• Model selector to limit the open models you wish to export from/import into/browse
• Full integration with Microsoft Visio 2002 for Enterprise Architects and Microsoft Visio 2002/2003 Professional
• Corresponding XML Schema definition
• Sample XSLT style sheet for formatting XML results as an HTML report
• Sample XSLT for generating an XML Schema (XSD) from a Database Model Diagram

SECTION 05 | ORM Import File Specification
The ORM Import tool will import a text file of fact types into the (user) selected ORM Source Model. It will import (and create, where necessary) object types and predicates; at this time, it will not import constraints, subtype declarations, nested object type declarations, or the more complex alternate readings (see below). It assumes each line in the text file is one fact type. For the most part, the ORM Import mimics the input functionality of the Visio Fact Editor in freeform mode.

Object types are denoted by one of the following methods: a) the first letter of each object type is capitalized, or b) the object type is enclosed in brackets. The default option for the ORM Import tool is to denote every capitalized word not enclosed in brackets as distinct object types and any words enclosed in brackets as one object type. Brackets are mandatory when you have an object type name that is two or more words long. Note that if you wish to have any predicate text in upper case, you must select the “[Bracketed] only” mode and enclose every object type in brackets.

The remaining words are treated as predicate text. Generally speaking, this text is assumed to be the forward reading starting with the first object type. Simple binary fact types (described below) can also be imported with an inverse reading. For complex binary, unary, and nary (e.g. ternary) fact types, only one reading (i.e. the “forward” reading) is supported at this time.

A simple binary fact type is one that follows the [Object Type] predicate [Object Type] pattern (with no predicate text before the first or after the second object types). For this specific fact pattern, the ORM Import tool will recognize the reverse reading as being after a single forward slash (/). For example: [Person] drives/is driven by [Car] is interpreted as “[Person] drives [Car]” with an inverse reading of “is driven by”.

Any line (or portion of a line) proceeded by a pair of forward slashes (//) is treated as a comment and not parsed into object types or predicates.

Any line that has no recognizable object types (i.e. no capitalized/bracketed words) is ignored. This includes empty lines, lines containing only white spaces (spaces, tabs, etc.), and any other text with no object types specified.

If a line contains only object types, only object types will be created. In other words, you must have at least one word of predicate text in order to create a fact type. If no predicate text is supplied, the object types will still be imported.

Object types with names and reference modes that already exist in the ORM Source Model are not created again; the existing object type is used for the creation of the (new) fact type. Fact types with the same object types and (forward) predicate reading as a fact already in the ORM Source Model are ignored.

Reference modes are indicated by enclosing the reference mode in parenthesis immediately after the object type (no spaces), for example: “Person(ssn)” or “[Person(ssn)]” and not “Person (ssn)” or “[Person (ssn)]. Value types can be denoted by placing empty parenthesis immediately after the object type, for example: “[Phone Number()]. You only have to declare a reference mode for a given object type the first time it appears in the input file; the parser assumes that any subsequent usage of the given object type name (with or without the reference mode) refers to the same object type.

The following table illustrates some example input and what the parser will do:

SECTION 06 | Frequently Asked Questions

1. Can I only export some of the models currently open (instead of all of them)?
   
   Starting with version 1.5, yes. Simply check the model files you wish to work with (extract, import into, and/or browse) and clear the ones you do not wish to work with.
   
2. How can I sort the XML elements?
   
   Currently, Orthogonal Toolbox exports the model elements in the order they are contained within Visio. One way to sort the elements would be to create a style sheet (XSLT) to transform the extracted XML into your preferred format.
   
   
3. Why are there extra roles and constraints that are not associated with any facts?
   
   Those roles and constraints correspond to the roles an object plays as a subtype or supertype of another object. Each subtype relationship should spawn 2 roles with readings of “is a”. Further, each role should have a uniqueness constraint and the subtype role should be mandatory (i.e. the subtype must have a parent supertype).
   
   
4. How come some of the model information in my Visio model is not exported?
   
   Orthogonal Toolbox exports all of the information made available via the modeling library interface of Visio. Unfortunately, this interface does not expose all of the meta-data that can be stored in a Visio model. For example, fact example data, stored procedures, and some of the meta-data stored about entities and attributes is not exposed and thus cannot be exported.
   
   
5. The Orthogonal Toolbox toolbar is not visible, how do I get it back?
   
   The Orthogonal Toolbox is only visible when an either an ORM Source Model or a Database Model Diagram are in the active window of Visio.
   
   Otherwise, you may have closed the toolbar; to get it back, select “View | Toolbars | Orthogonal Toolbox”.
   
   
6. What is a maximum cardinality of “-1”?
   
   A maximum cardinality of -1 is equivalent to “many” and/or “n” which means the parent may have any number of children. If the maximum cardinality is any value but -1, then that value is the exact maximum number of possible children a parent may have.
   
   
7. What is the “Style Sheet” section for?
   
   If an XSLT style sheet is specified, Orthogonal Toolbox will add the appropriate tags to the XML output. XSLT style sheets are used to transform XML into other formats such as HTML.
   
   To see an example of this, open an ORM source and/or Database Diagram model and open the Orthogonal Toolbox dialog. Then, select “set style sheet” and browse to a location of an XSLT style sheet. For example, there is a sample located in the “StyleSheets” subdirectory of the installation location (e.g. C:\Program Files\Orthogonal Software Corporation\Orthogonal Toolbox\StyleSheets\OrthogonalToolboxXSLTExample1_5.xslt).
   
   Once you have selected a style sheet, export the XML model and open the XML file using Internet Explorer 6.x. If you have selected the example style sheet above, you should see the XML transformed into a sample HTML-based report that sorts the model elements into tables.
   
    
8. Where can I learn more about Object-Role Modeling (ORM)?
   
   Orthogonal Software also sponsors www.objectrolemodeling.com, an ORM portal and web log.
   
    
9.  Are there other style sheets I can use?
   
   The hope is that users of the toolbox will create useful style sheets and share them with other Orthogonal Toolbox users. As people donate them, we will post them on our website(s).
   
    
10. I’m getting error messages about Visual Basic for Applications or about disabled macros when doing an XML export of ORM Source data or opening an ORM Source Model.
    
    Macros are used for part of the ORM Source data extraction. If you are certain that the ORM Source Model you are trying to use is safe (e.g. you created it yourself and didn’t attach any macro viruses to it) you can set macro security in Visio (Tools | Macros | Security…) to medium or lower and/or click “Enable Macros” when prompted.
    
     
11. What does the “Export using v1.0 Schema” checkbox do?
    
    The underlying XML Schema for the XML export was enhanced (i.e. changed) for version 1.5. If you have any XSLT layers that rely on the 1.0 schema, you can set this check box to mimic the old version. However, this backwards compatibility will only be supported for a limited time; please update your XSLT layers to account for the (minor) schema changes.
    

SECTION 07 | Known Issues
As of the time of this writing, there are no known bugs/issues with this software.

However, the sample XSLT style sheet provided with the software (in the “StyleSheets” subdirectory of the installation directory) produces unexpected results if the source XML file has multiple models that have overlapping element IDs.

For example, if 2 Database Model Diagrams are open during XML export and those models each have an Attribute with duplicate Attribute IDs, both Attribute Names will appear in various places in the resulting transform of OrthogonalToolboxXSLTSample.xslt.

Under most circumstances, this is not an issue but if it does happen one workaround is to export the models with the overlapping IDs to separate XML files.

SECTION 08 | Removal Instructions
Should you want to completely remove Orthogonal Toolbox from your system, open the Add/Remove Programs applet of your system’s Control Panel, select “Orthogonal Toolbox”, then click “Remove”, and follow the instructions of the uninstall utility.

To temporarily disable Orthogonal Toolbox (i.e. keep it from loading in when Visio loads), open the registry editor (Start | Run | regedit.exe) and change the “LoadBehavior” value of HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Visio\Addins\OrthogonalToolbox.Connect to 0.

To enable Orthogonal Toolbox, set the above value to 3

SECTION 09 | Documentation, Support, Updates & Further Resources
Documentation, support, updates and further resources for this product (and tangential topics such as the use of ORM, data modeling, etc.) can be found on our website (www.orthogonalsoftware.com).

Interactive support is available via the forums at ObjectRoleModeling.com

If you believe you have discovered a bug, please post the following details to the Orthogonal Toolbox Support Forum:

1. The exact actions you performed to cause the problem
2. A description of the problem
3. A description of the expected behavior
4. If possible/applicable, the exact copy of the input and output file(s). Any information in those files will be held in the strictest of confidence, shared with no one outside of Orthogonal Software Corporation, used only for product support purposes, and promptly destroyed once no longer needed.

For general support requests, please visit the Orthogonal Toolbox Support Forum.

If you have any suggestions for enhancing future versions of this product, feel free to post them to the Orthogonal Toolbox Feature Request Forum.

Please do not telephone or e-mail us with support requests, bug reports, or suggested enhancements.

SECTION 10 | Contact Orthogonal Software Corporation
To contact Orthogonal Software Corporation for any reason, you may visit us on the web (www.orthogonalsoftware.com).

SECTION 11 | Acknowledgments
Many people and organizations – one way or another – have been instrumental in the development of this software and have our deepest gratitude. In alphabetical order, they are:

Justin Bieganek, Mike Bisek, AJ Durham, Ryan Farley, Ross Grayum, Terry Halpin, Paul Leska Jr., John Miller, Peter Mulvey, Curt Teunissen, and Yan Zang.

The problem with acknowledgement lists is that inevitably someone gets left out. If this is the case, please assume it is because of benign absentmindedness and not due to slight, malice, disrespect, or ungratefulness.

SECTION 12 | Version History
Version 1.5 was released on September 8th, 2004. This version supports bulk import of ORM fact/object types, a model element browser to view element properties and/or delete most element types, the ability to export/browse ER Source Models, Visio 2002/2003 Professional Database Model Diagrams, and the ability to select a subset of the open models to work with.

Version 1.0 was released on May 30th, 2002. This version supports an XML export of ORM Source Model and Database Model Diagram meta-model information.

SECTION 13 | License & Warranty
The End User License Agreement (EULA) can be found in the installation directory (e.g. C:\Program Files\Orthogonal Software Corporation\Orthogonal Toolbox\EULA.rtf) or on the web at http://www.orthogonalsoftware.com/OrthogonalToolboxEULA.html. This file also contains a disclaimer of warranties for this product.

The use of this software is subject to the terms of this agreement.

Microsoft Visio and Microsoft Visual Studio are registered trademarks of Microsoft Corporation.