NORMA August 2024 Readme 

This file supersedes the previous readme.txt and older readme.htm files. This readme has parallel indexing mechanisms: by topic, and by release date (starting with the October 2008 (2008-10) release). The file will be extended for future product releases.

The August 2024 release adds support unary negation, adds isSUBTYPE columns to absorbed object types in the relational mapping, and allows entry of default values in the model. See detailed change notes below for general details.

-Contents

-August 2024 Changes

+Previous Releases

Installing NORMA

1. 2019-03  The Visual Studio 2017, Visual Studio 2019 and Visual Studio 2022 versions of NORMA no longer have an .msi-based installation process. They are now part of the Visual Studio Marketplace and install as a normal extension. All installation directions below this item apply to Visual Studio 2015 and earlier versions only.
   • To install using the Marketplace, start Visual Studio, open the Tools and Extensions dialog from the Tools menu in Visual Studio 2017. For later release, this dialog has moved to Extensions/Manage Extensions.
   • Choose Online/Visual Studio Marketplace. You will now be able to search for NORMA.
   • Make sure your package is digitally signed by ORM Solutions, LLC before installing to make sure you have an official release of NORMA and schedule the installation to run when Visual Studio closes. Updates will be shown in this dialog as they are made available, but will not automatically install.
   • 2022-08  Users now have the option of installing the normal package (requiring admin rights) or a PerUser version of NORMA. Only one of these should be chosen, and if the other has been previously chosen it should be uninstalled before switching. The PerUser package can be installed without admin rights and can automatically update if an update is provided. After installation, the only difference is that IntelliSense help for NORMA-installed schemas is no automatically available in any NORMA file opened in the Visual Studio XML editor. To get schema support NORMA makes it easy to open the small number of schema catalog files in NORMA. Any schema that is opened in a current editor window (or is listed in a open catalog file) is recognized and gets the same level of help as an installed schema file. To open these files, choose XML\Load NORMA Schemas with an XML file open. If you do not see the menu item then create a new .ORM file and close without saving to form the NORMA package to load.
2. Updating NORMA to the latest version requires Setup.bat to be run from the downloaded .zip file, which should be chosen based on your Visual Studio version (2015, 2013, 2012, 2010, 2008, 2005). NORMA does not share installation files between versions, so you must choose your target when you download the installation package.
3. Any previous NORMA versions for the selected Visual Studio target will be automatically uninstalled and reinstalled by the Setup.bat file. Make sure Visual Studio is not running during the installation pocess. Please be patient with the uninstall, which takes roughly the same amount of time as the install. Killing installation processes (the setup command prompt, msiexec, devenv) can leave you with a system that requires manual intervention to restore.
4. Full Visual Studio studio configuration on version 2010 and higher will not be completed until after Visual Studio has restarted. Some slowdown should be expected on Visual Studio launch, the first time the 'File/New' dialog is opened, and the first time an .orm file is opened.
5. First extract the files from the .zip file first unless you open them with the standard 'Compressed (zipped) Folders' viewer, in which case you can usually run Setup.bat without pre-expanding the zip file. Vista is likely to recommend expansion even with the standard viewer.
6. 2008-10  The setup process must be run with admistrative permissions on Vista, Windows7, and later operating systems. You can either right-click the Setup.bat file and choose 'Run as Administrator', or you can run SetupVistaOrLater.bat instead of Setup.bat and agree to the security warnings. [Note that SetupVistaOrLater.bat relies on a system where a .js extension is treated as an executable scripting file. Some other products (especially some from Adobe) may override this default system setting. If SetupVistaOrLater.bat does not appear to do anything, then explicitly run Setup.bat as an administrator.]
7. (Visual Studio 2005 Install Only) The DSLToolsRedist.msi included with this release will not automatically upgrade if you have an older DSL installation on your machine. If you were an early user of NORMA or other DSL products and have not previously upgraded, or have experience designer issues on Windows Vista, then you may want to explicit uninstall the 'Microsoft DSL Tools Redistributable' product before running NORMA setup.

General Use

1. You can selectively turn off display of specific classes of errors. This only affects display, not the underlying error state, which is always tracked. Errors are displayed in the Error List, Model Browser, Verbalization Browser, all diagrams, and in generated reports. Turning off error display affects all of these visualizations. To modify this setting, click on any diagram and choose the 'ErrorDisplay' property.
2. Direct keystroke access has been added for all of the tool windows. For example, Ctrl-W, Ctrl-F (hold down the control key and type WF) will open the 'ORM Fact Editor' tool window. Other keystrokes correspond to the accelerator keys on the ORM Designer context window. To see the key associations, place focus anywhere in the ORM designer and press the context menu key followed by 'w' to open the 'ORM Tool Windows' sub menu. The accelerator characters shown correspond to the default key bindings for the second key (note that F is underlined for 'ORM Fact Editor').
3. 2008-10  The key bindings now work with the focus in all tool windows except the ORM Fact Editor, where Ctrl-W is bound to the 'Select Current Word' command.
4. 2008-10  The ORM Model Browser tool window now has a Diagrams node that shows an alphabetized list of all current diagrams. The name of a diagram can be edited directly in the browser with the standard F2 command (except for diagrams that have 'rename' disabled on the diagram tab). Commands are available on the context menu to select the diagram in either the current document window or the Diagram Spy tool window.
5. 2008-10  Added the ORM Diagram Spy tool window to assist model navigation. The Diagram Spy is a view on an existing diagram in the model, unlike the Context Window which populates a new diagram when an item is selected. The Diagram Spy window, along with the Model Browser, is a selection-enabled tool window, meaning that changing the selection in the Diagram Spy will update the state of all other tool windows. This also means that all editing capabilities supported in the main document window are also supported in the Diagram Spy window.
   
   The diagram spy works together with the new hyperlink features in the Verbalization Browser to enable rapid movement through even complex ORM models. This is easiest to accomplish if you place these two tool windows so that they are both visible instead of on the same set of tabs. This can be accomplished by dragging the tool window tab and docking it in a separate location (I like the Verbalization Browser at the bottom of the document window). The verbalization option (available on the Verbalization Browser toolbar) to direct hyperlinks to the Diagram Spy window is on by default.
   
   Commands are provided to jump from any shape selection in a main document view to the same shape in the Diagram Spy window, and vice versa. The 'Select on Diagram' command applied from the Diagram Spy will remain in the spy window. The Model Browser commands have also been extended to allow selection in either the main set of diagrams or in the Diagram Spy.
6. 2008-12  The ORM Model Browser tool window contains some nodes that are links to other elements. Link nodes are marked with a shortcut overlay glyph, and selecting these nodes is equivalent to a selection of the target node. Double-clicking a link node will select the target node. Link nodes to the constrained FactTypes have been added to external constraint expansions, and column reference links appear in multiple places in the Relational Schema.
7. 2009-05  If a new shape is created for a FactType via control-drag, dragging to a new diagram, or dragging from the model browser, then you can easily get a FactType shape with no attached role players. If the role player is set for a role, then dragging that role onto the diagram surface will automatically add a new shape for the role player.
8. 2010-02  Role display order within a shape can be changed by dragging one role and dropping on another. NORMA provides cursor feedback to distinguish this action from setting a role player or adding a new shape. Note that dropping on an item always selects the drop target (a role), which for a binary fact type will move to the location of the dragged role when the role reorder action is complete. The resulting experience is that the selection rectangle does not move when reordering binary roles.
9. 2010-12  ORM elements can be dragged from one model to another. Cross-model drag is supported from the model browser and from any diagram. All newly dragged elements are merged based on pattern-matching with existing elements. All required support elements (internal constraints, identifier parts, supertypes, etc) are copied with a given element. Moving the same element twice from one model to another may create a new shape, but will not create a new element if the matching properties of the original have not changed.
   
   Dragging Tips:
   • If the user drops elements from extensions that are not turned on in the drop target then a prompt will be given to automatically load the required extensions in the target model. If the extensions are turned on then the drag operation will need to be repeated.
   • An entire group can be dragged from one model to another to copy all of the elements included in that group. The group should be dropped on a diagram, but a group drag does not bring across any shapes. Expanding the group in the target model will let you drag elements from that group onto the diagram to create new shapes.
   • Drag operations including constraints can result in the dreaded 'no-drop' symbol because constraint shape display requires a shape to be present for all of the constrained fact types. You can use a temporary group to drag a constraint (and all constrained fact types) to a separate model as follows:
     1. Right-click the constraint in the Model Browser and use the Groups submenu to add it to a new group.
     2. Drag the group to the target model.
     3. Delete the group in target model.
     4. Undo the last change in the source model to remove the temporary group.
   • The pattern matching backing cross-model drag operations allows element duplicate by modifying the element in an external model. If you drag an element between models and drag it back without modifying it, then you will simply get a new shape for the element. However, if you modify the readings and/or role player names for a fact type, then dragging the modified fact type back to the source model will not find a match and will create a new fact type. Note that if any resolved readings (with the placeholders replaced by role players) match then the fact type is considered equivalent and the readings are merged.
10. 2010-12  Hovering over a diagram tab (at the bottom of the designer) during any drag operation will activate that diagram. Hovering over the left edge of the leftmost tab will scroll the diagrams to the left. Combined with the Visual Studio support for activating a file by hovering over the file tabe and bump scrolling within a diagram, this makes it much easier to drag items between models and copy shapes within models. Without this support, cross-diagram drag required both the source and target diagrams to be visible in either multiple document windows or the Diagram Spy tool window.
11. 2011-06  A Zoom submenu enables zooming to a specific percentage or with incremental zoom in/zoom out commands. There are corresponding mouse gestures and hotkeys cooresponding to these commands. All of these commands work with both 'Control-Shift' and 'Control' modifiers (following standard web browser keystrokes). Pressing control-shift will change the designer cursor to a magnifying glass, indicating zoom.
    Mouse and keyboard zoom commands:
    • Zoom In: Control-Shift-EqualsKey, Control-EqualsKey, Control-Shift-LeftClick, Control-MouseWheel, Control-Shift-MouseWheel
    • Zoom Out: Control-Shift-MinusKey, Control-MinusKey, Control Control-Shift-RightClick, Control-MouseWheel, Control-Shift-MouseWheel
    • Zoom Restore: Control-Shift-0, Control-0 (Zero Key, correspond to Zoom/100%). Note that Control-Shift-0 is a default system hotkey used for keyboard switching in Vista and later operating systems (even if you don't have multiple keyboards installed), so use Control-0 is Control-Shift-0 has no effect on your system.
    • Scroll: MouseWheel for vertical scroll, Shift-MouseWheel for horizontal scroll.
12. 2011-06  Keyboard nudging of selected shapes depends on the zoom level. At maximum zoom (400%) the keyboard nudge distance is very small with the intent of allowing extremely fine-grained shape alignment. The nudge distance is fixed from 10% to 100% zoom, at which point it linearly decreases to the fine-grained setting at maximum zoom.
13. 2013-12  Disabling the display of specific errors (by class and category) is possible through the ErrorDisplay property on the model. However, with the large number of validation errors in NORMA, it is not always obvious which error class or category corresponds to a displayed error. For a more direct approach to error management, the Validation Errors submenu on the NORMA context menu has an additional Display Error Display submenu listed after the validation errors for the current context. Selecting an error in the main Validation Errors submenu attempts to activate an editing action that will repair the error (not all errors have activators). Expanding this submenu repeats the displayed errors, but selecting the error disables the display for all errors in that error class instead of activating the error (NORMA does not control display of individual errors, just the error class).
    
    If a selected diagram shape has disabled errors, then an additional Enable Error Display submenu will also appear showing the undisplayed errors. Selecting a validation error in this list will reenable error display. Enabling error display will immediately display error feedback on the diagram, and reopening the Validation Errors submenu will offer the error in the error activation list.
14. 2013-12  ORM theory states that all readings with the role player names inserted should be unique within a model. The reading text itself does not have to be unique. For example, Person drives Car and Cowboy drives CattleHerd can coexist in the same model without conflict. NORMA takes this one step further and normalizes the readings by expanding combined object types names, normalizing spaces, and removing any hyphen-binding markup. This is done so that different representations of the same name (CattleHerd, cattleHerd, Cattle Herd, cattle herd) used in different implementations and verbalizations of the model are always unique across the model. For example, the signature for the reading Cowboy drives CattleHerd is cowboy drives cattle herd, and placing the reading Cowboy drives cattle- Herd in the same model will create a duplicate reading signature validation error because the signature is already in use, even though the role players are different (Herd instead of CattleHerd).
    
    One unexpected place you will see this error is with an objectified fact type that has the same object type in multiple roles. NORMA always creates link fact types for asserted objectified fact types, so an objectification of Person likes Person will automatically add a link fact type for each role. The readings for each of these fact types will be Person is involved in PersonLikesPerson and PersonLikesPerson involves Person. You will always get two duplicate signature errors in this situation because these initial forward and reverse link fact type readings are the same. Activating the error (via the Validation Errors submenu on the diagram context menu, error hyperlinks in the Verbalization Browser, or the Error List tool window) will select the role corresponding to the first of the duplicate link fact types, expand the Implied Fact Type Readings branch, and activate the editor for the given reading. Changing the reading (to something like first- Person is involved in PersonLikesPerson) will remove the first error, and editing the reverse reading will remove the other. Although there will be no errors at this point, we recommend at this point that you select the other role in the objectified fact type as well and create a corresponding reading for the other link fact type.
    
    Note that link fact types are also created for implicitly objectifications (binary fact types with a spanning uniqueness constraint or any n-ary fact type). You will not see an error for these implied link fact types, but these readings can affect names in physical implementations of the model. You can edit these link fact types yourself using the same role-selection technique and the Reading Editor.
    
    There are numerous designer operations—ranging from role player changes to object type name changes to objectifying a fact type—that can introduce duplicate reading signatures in the model. The designer will only throw an exception to block the addition of a duplicate reading signature if the user is making a direct edit to the fact type reading using either the Reading Editor or Fact Editor tool windows. Any other edit that introduces a duplicate reading signature will just add the duplicate signature error to the set of validation errors.
    
    The Fact Editor also checks for a single existing fact type with a matching signature before committing a new fact type. If a matching fact type is found, then the editor adds a new shape for that fact type, not a new conflicting fact type. If the forward and reverse readings entered in the fact editor match different fact types then you will see a duplicate reading signature exception when the fact editor line is committed.
15. 2020-05  ORM theory adds implied mandatory constraints for any object type that is not independent and does not play at least one non-identifying mandatory role. These implied mandatory constraints are given lower precedence in certain mapping situations when we are determining the absorption direction for an unbalanced one-to-one fact type, meaning a one-to-one fact type with a mandatory constraint on one role but not the other. The problem with this system is that there is nothing stopping a user from adding the implied mandatory constraints, and in fact some modelers prefer viewing the implied constraints. However, performance of the mapping layer is heavily dependent on the ability to identity as many unbalanced one-to-one fact types as possible early in the analysis of the model. To remedy this situation we have added the notion of an inherent mandatory constraint, which is defined as any mandatory constraint that would be implied if it were not explicitly specified. For mapping purposes these constraints are treated the same as an implied mandatory constraint unless the inherent constraint is opposite an implied constraint in a one-to-one fact type. Saving these constraints adds additional XML to an .ORM file which will cause a schema validation error in earlier versions of the tool, so all users should upgrade to the latest version for their Visual Studio environment or they will be forced to load with schema validation off (by holding down the shift key). There is currently no visual feedback that a mandatory constraint is considered inherent.
16. 2024-08  Unary fact types were previously binary fact types with an implied Boolean value role under the covers. This caused many issues, especially when trying to deal with the 'known false' state, which could not be attached to constraints or objectified. The unary binarization has been removed. A unary fact type now only supports the true state unless the UnaryPattern property is changed to indicate that an explicit false state should also be supported, which creates a second unary fact type to represent the 'known false' state. While unary fact types cannot have simple mandatory constraints because this would mean the fact type is always populated (and, therefore, meaningless), the pair of inverse unary fact types (the positive fact type and its negation) can be disjunctively mandatory. The UnaryPattern property also enables a mandatory unary pair (with the True/False pattern), along with optional default values (true or false).
    
    If a unary fact type has a negation it will display with a small circled + sign in the space on the role box edge where a simple mandatory constraint draw. This will change to a mandatory color (deontic or alethic) around the plus sign if the unary pair is mandatory.
    
    The minus sign is used for the negation fact type if the shape is shown. The negation (along with implied exclusion and possibly mandatory constraints) are in the expansion of the positive unary in the Model Browser, which can be used to add these shapes to the diagram. However, as this is cumbersome, a new 'Drag Inverse Unary' command has been added to the context menu to easily add a shape for the negation. This allows an inverse reading to be displayed as well as objectification and constraints to be applied to the negated state.
    
    Old-style unary fact types will transform on load. This is transition is unidirectional, so saving your models will make them incompatible with earlier NORMA versions. The import keeps the True/False/Unspecified UnaryPattern, which relationally maps the same as the previous binarized unary structure. You should review the unary fact types in the model-these are easy to spot in the Model Browser Fact Types list-and set the UnaryPattern accordingly. If you do not want explicit false support, just change the UnaryPattern property to True/Unspecified.
17. 2024-08  Any role with a role player ultimately identified by a single value now supports a DefaultValue property. This maps to a column default value in the relational mapping. However, default values cannot be generated for absorbed object types (subtypes, etc.) because this would make every new row of the supertype to automatically have data for a subtype with declared defaults. If the defaults are important on the subtype then place it in a separate table.
    
    A default value must be parsable by the context data type and satisfy all context value constraints. A default can be specified on the value type itself, but this serves only as a contextual default for the attached roles (there is no affect on generated artifacts). A role with a contextual default value gets that default if another is not specified. The role can also be modified to hide a context default by choosing the <No Default Value> entry in the dropdown for the DefaultValue property.

Window Management in Visual Studio

• Document Window Commands
  • The New Window command, located on the Window menu, is supported by the ORM designer. This command lets you open a second view on the same document. You will see the document tabs numbered (SampleModel.orm:1, SampleModel.orm:2) after applying this command. For NORMA, this means that you can have multiple diagrams or different parts of the same diagram open simultaneously in different document windows.
  • When more than one document window is open, the New Horizontal Tab Group and New Vertical Tab Group commands enable you to look at multiple document windows side-by-side instead of one at a time. These commands can be found on the context menu of any document tab (the tab with the file name), and can also be activated by dragging any document tab and dropping it on the document space below the tab. Document windows can be moved between existing tab groups (or reordered within the same tab group) by using the drag-drop gesture on the tabs. Once you have created a new tab group you can simultaneously view two or more .orm diagrams from the same file. NORMA supports dragging one or more shapes from one diagram to another.
• Tool Window Commands

  Visual Studio supports a large number of tool window states. A tool window can be docked (attached to one of the sides of the Visual Studio environment), floating (hovering over the environment, including outside the bounds of IDE), or treated as a document window (giving you the same window management capabilities as a normal document window, minus the New Window command). NORMA wakes up with all of its tool windows except the ORM Model Browser docked in the same container, so you can view the contents of exactly one tool window at any given time. This can be a suboptimal working environment for some tasks. For example, examining the ORM information backing a relational model is easily done with both the Verbalization Browser and Diagram Spy windows visible, plus either a document window (showing the Relational View) or the Model Browser (expanded to show the relational schema). Selecting a relational column will populate the Verbalization Browser, and the Verbalization Browser hyperlinks can then be used to select individual items in the Diagram Spy, which will change the Verbalization Browser contents (recurse as needed via hyperlinks). Obviously, this experience is significantly enhanced if the Verbalization Browser and Diagram Spy windows are both visible.

  • A tool window can be switched to a floating state, or to another new or existing tool window group, simply by dragging the tool window tab. Visual Studio provides a large variety of potential docking positions, which can be previewed by dragging over the various popup windows offered by the environment when you start your window drag.
  • A floating tool window can be returned to a docked form by double-clicking the tool window title bar, or by opening a context menu on the tool window title bar and choosing Floating. Similarly, a tabbed tool window can be switched to a floating state by double-clicking on its tab.
  • Choosing Tabbed Document on the context menu of a floating tool window title bar or docked tool window tab is used to move the tool window into the document window space. The Floating and Dockable commands are also available on tab for a tool window in the document space to restore them to the normal tool window locations.
  • Tool windows can also be hidden at any time using the Hide command on a tool window tab context menu. If you need additional screen real estate, you can also enable the Auto Hide feature, which makes the tool window retractable.
• 2008-12  The Diagram Management extension model can be selected to enable diagram reordering and position caching across sessions.
  • Diagram reordering is available via the context menu on the page tab section of the document window. Pages can be reordered by selecting the item and using the up/down buttons (Alt-Up and Alt-Down as shown on the button tooltips), or by drag-drop in the list. Note that primary selected item is distinguished by a solid selection rectangle with normal text (this is not my first choice, it is a control issue).
  • The active diagram, as well as the center position and zoom for the last active view on a page, will be remember when the model is saved. If the SaveDiagramPositions property selection (available on any diagram) is set to false, then the position will not be saved with the file.
  • Diagram position and activation changes do not support undo/redo. Activating a diagram or change the scroll/zoom state also does not cause the document to be marked as dirty, so you must explicitly save the file if other changes have not been made.
• 2009-10  Delayed activation of text fields in the Model Browser can be enabled in the 'Tools/Options' dialog. To enable this option, select the 'Delay Activate Text Editing' in the 'Model Browser' category of the 'ORM Designer' page. If this option is enabled, then selecting the text of an item with an editable name will place it in edit mode. Select the item's icon instead of the text to avoid activation. Regardless of this option, inplace editing can also be activated with the View.EditLabel command, which is generally associated with the F2 key.
• 2023-03  A new DataTypeAutoGenerated property is available for signed integer 2/4/8 byte data types, along with the new Numeric:UUID data type. This property defaults to False for the integer types and True for a UUID. The property is also shown on the 'classic' AutoCounter data type, where it has a reaonly True value (AutoCounter is an 8 byte signed integer).
  Two new popular intrinsic reference modes have been added with a UUID data type, .UUID and .Uuid. Although these have the same pattern and default data type, having multiple casings is consistent with other reference mode patterns like .Id. The UUID name can also have unexpected side effects with name generation. The (by design) issue is that acronyms (multiple adjacent capitals) are treated as fixed case, so do not respect name generation casing choices. If you see UUID appear in your tables where you want uuid, then either use Uuid or add a recognized phrase in the Abbreviations dialog for Relational Names (under Name Generation Settings in the ORM Model Browser tool window). The phrase should replace UUID (exact casing) with uuid.
  These new UUID reference modes are intentionally Popular, not General. This indicates that the identifier populations are conceptually different sets, just like the .Id reference mode, so we do not want to share a single UUID value type with other identified entity types (the General reference mode pattern).
  The successful use of an auto-generated UUID data type depends on the database generation target. This support varies by target RDBMS:
  • SQL Server has a native UNIQUEIDENTIFIER type and supports the NEWSEQUENTIALID() and NEWID() functions. The former function is documented as higher performant so is used in situations where it is allowed.
  • PostgreSQL has a native UUID type and a uuid_generate_v4() function that is enabled when the uuid-ossp extension is enabled. The generated DDL now ensures this extension is enabled if a UUID type is used.
  • Oracle does not have a native type, but does have a SYS_GUID() function. We use RAW(16) as the UUID type, which is the return type of the generator function.
  • MySQL also has a generator function but returns the less efficient string form of the UUID, so we map to a BINARY(16) column and use UUID_TO_BIN(UUID()) as the UUID generator.
  • DB2 does not have native UUID support, so the default value is left off (meaning this is no longer auto-generated). The CHAR(16) FOR BIT DATA data type is used for the column.
• 2023-03  Custom reference modes (available in the ORM Reference Mode Editor tool window) now have a default data type like intrinsic reference modes. As with intrinsic reference modes, this data type is only used when the reference mode pattern is first established with the RefMode property. After this point the user is free to change the data type of the identifed entity type, and change the default data type has no effect on existing uses. The exception to this is with a General reference mode, which binds to a single value type in the model. In this case, if the corresponding value type is used only for reference mode patterns then its data type is changed when the reference mode data type changes.

Fact Editor

1. The Fact Editor supports entering one line at a time, the current selection determines if a new FactType is created or if the selected FactType is edited. If you want to create a new FactType, make sure that an existing FactType is not selected.
2. Fact Editor lines are committed using the Control-Enter keystroke.
3. The Fact Editor responds to changes in ObjectType and Role selection. Selecting roles in a non-default order in a FactType prompts the Fact Editor to edit the reading for that role order. You can also add new readings between object types by multi-selecting the target ObjectTypes. For example, to add a new FactType between ObjectTypes A and B, hold down the control key, click on A then B, then type WF (with the control key still down) to activate the FactEditor with the caret between the two Object Types.
4. Selection of an objectified FactType is interpreted by the Fact Editor as a FactType selection, not an ObjectType selection. Selecting the ObjectType name (shown in quotes above the objectified FactType) is treated as a selection of the ObjectType.
5. Entering one or more ObjectType names in the Fact Editor, including the trailing () to indicate a ValueType or (.id) for a simple reference scheme, will add just the ObjectTypes as long as text is not specified between any of the ObjectType names. So 'Person(.id) Car(.code) PersonName()' followed by Control-Enter will add two EntityTypes and one ValueType to the model.
6. 2009-01  Selecting a binary FactType with an inverse reading only will display the inverse reading in the Fact Editor using a forward slash before the reading text. A /s B indicates an inverse reading, but no forward reading, for the selected order {A,B} order. This allows you to see an existing inverse reading without changing your selection, and to enter an inverse reading without a forward reading. If you leave a leading or trailing forward slash and a reading exists for that direction then the reading will be deleted. For example, changing A r/s B to A r/ B will remove the inverse s reading. However, changing to A rr B will modify the forward reading without touching the inverse reading.
7. 2024-08  The Fact Editor has always committed the line with Ctrl-Enter, which automatically placed the fact type on the diagram. Finding and properly placing the fact type could be cumbersome on complex diagrams. The Alt-Enter command is added to make the new fact type a drag source that can be directly placed on the diagram. A few notes:
   • There is a new toolbar on the left edge of the fact editor with one button for each command. If you focus the fact editor, then a mouse hover over the buttons will also remind you of the shortcuts.
   • The original Ctrl-Enter created the backing elements (fact types and object types) and placed shapes in a single undo-action. Alt-Enter splits this into two stages. If you cancel the drag operation it will NOT remove the elements from the model.
   • A fact type will drop with just the fact type, not attached role players. If the role players are not already on the diagram, simply drag a role box and drop it on the diagram to create shapes for the object types.
   • If the fact editor sees only object type names (space delimited) where all names have a lead capital letter, then it will ensure each of those object types exist--and add a shape for each if the use commits with Ctrl-Enter. With Alt-Enter, each object type will be given one click in the drag operation, which will clear when all object types have been clicked onto the diagram.
8. 2024-08  The Fact Editor can force a unary negation and add a reading for the negation. The chosen separator character is the tilde (~), which works similarly to the forward slash (/) for reverse binary readings. The text inside the ~ is for the selected unary (assumed to be positive if no fact type is currently selected), and text outside ~ is associated with the negation reading. ~ can appear before or after the inverse readings. Some examples:
   • Create a unary with negation support but no explicit reading on the negation: Action is allowed~
   • Create a unary with negation support and a reading for the negation: Action is allowed~is disallowed
   • Place the ~ before the object type name to use a front-text style reading: disallow~allow Action
   • If the negation fact type is selected, the tildes reverse: allow~disallow Action

Verbalization

1. 2008-10  The nearest value constraint (theoretically the most restrictive, although this condition is not validated yet in NORMA) is verbalized along with any EntityType that is identified by a single restricted value. Before this change, the value range for an EntityType with a reference mode would only verbalize with the identifying FactType or the implied ValueType. The designer showed the allowed values with the EntityType, but the verbalization and report engines did not.
2. 2008-10  The preferred reading order is respected for all verbalization. The preferred reading order can be set using the 'ORM Reading Editor' dialog, but the order did not affect verbalization until this fix.
3. 2008-10  Many elements in the Verbalization Browser have hyperlinks on them. The links are graphically non-invasise because most of the elements have the potential to eventually be hyperlinks. You will see a cursor change and subtle background color change when you mouse over a hyperlinked area. The following elements currently have links:
   
   • ObjectTypes: Clicking the ObjectType name navigates to the ObjectType.
   • FactTypes: Clicking the predicate text selects the FactType. If the text for an implied FactType is shown (implied FactTypes result from explicit and implicit objectification and are frequently in the FactType path for relational columns) then the corresponding role for the objectified FactType is selected in a diagram. You can see and edit the readings for the implied binary FactType in the ORM Reading Editor tool window with this selection.
   • Errors: Clicking a validation error hyperlink has the same effect as double-clicking the corresponding error in the Visual Studio Error List window, selecting the error from the 'Validation Errors' menu, or double-clicking a hashed red shape on a diagram. The action is to first select the item with the error, the attempt to activate the necessary tool to fix the problem. For example, clicking an error indicating that a ValueType does not have a DataType specified will select the ValueType, open the Properties Window, select the DataType property, and open the dropdown. Note that error hyperlinks always select shapes in the main document window and cannot be redirected to the Diagram Spy window. This is done so that automatic tool activation has the best chance of success without covering the current selection [this design choice is still an open issue].
   
   While the hyperlinks are great for navigating, they can produce strange results if the resulting HTML is copied and pasted. An alternate set of verbalization snippets have been provided to allow you to verbalize without hyperlinks. To turn off hyperlinks, open the Tools/Options dialog, select the 'ORM Designer' page, and open the dropdown for the 'Alternate Verbalization Text' property in the Verbalization category. In the tree control, expand 'Core ORM Verbalization' and 'Browser Settings'. Double-click the checkbox beside 'Default, No Hyperlinks' to choose the alternate verbalization. You can later select the 'Default Verbalization' setting to restore hyperlinks.
4. 2008-10  All FactTypes associated with an ObjectType are shown with the verbalization for that ObjectType. This is turned on by default to facilitate navigating through a model using the hyperlinks in the Verbalization Browser. You can turn off FactType display by setting the 'Verbalize FactTypes with ObjectType' option in the 'ORM Designer' tab of the Tools/Options dialog to False.
5. 2008-10  Table elements verbalize all of the top-level ObjectTypes that correspond to the table. The full FactType path is also verbalized for each column selection. These verbalizations, along with the new Diagram Spy window, allow the user to navigation through and edit ORM space while the Relational View remains the primary selected document.
6. 2009-10  If hyphen-binding is used in reading text and a hyphen directly precedes the hyphen/space character pair that triggers the hyphen-binding interpretation, then the additional hyphen will be verbalized with no trailing space. So (here, an underscore (_) indicates a space), ADJECTIVE--_ROLEPLAYER will verbalize as ADJECTIVE-ROLEPLAYER. If ADJECTIVE-_ROLEPLAYER is the desired output, then the user can add an extra space to the reading text. Symmetric rules apply to reverse hyphen-binding.
7. 2010-02  Join paths for set comparison constraints (subset, equality, exclusion) are correctly verbalized. Join paths for simple, unambiguous patterns where joined fact types share a role player or pass through an objectification are generated automatically. More complicated join paths are also verbalized, but cannot be entered with this release of NORMA. The tool(s) to enter these paths will be available in future releases and versions of the product. Note that paths are also automatically generated for uniqueness, frequency, and ring constraints, but join paths are not yet verbalized for these patterns.
8. 2010-07  Join paths for uniqueness and frequency constraints verbalized correctly, leaving joined ring constraints as the only non-verbalized constraint types (adjustment to previous item). Verbalization is correct for common uniqueness patterns such as using objectified and non-objectified roles in the same constraint.
9. 2012-01  The Object Type Name Display option in the Verbalization section of the ORM Designer tab on the Options page (available on the Tools menu) modifies the form of verbalized object type names. A multi part name (as indicated by spaces and/or internalCapitalization) is first split into its component parts using the same rules as the relational name generator, then the names are recombined according to the specified option. Examples of three name patterns and their standardized forms are shown below:
   
   

   AsIs	SeparateCombinedNames	CombineNamesLeadWithUpper	CombineNamesLeadWithLower
   FirstName	first name	FirstName	firstName
   Second name	second name	SecondName	secondName
   thirdName	third name	ThirdName	thirdName

10. 2012-04  The Possible Populations option has replaced the Verbalization Default Constraint option in the Verbalization section of the ORM Designer tab on the Options page (available on the Tools menu). This option now applies to the possible populations of spanning internal uniqueness constraints in addition to many-to-one binary fact types.
11. 2013-01  As an enhancement to automatic name separation and casing of object type names (see Verbalized object type name options), punctuation and symbol characters are recognized in addition to upper cases and numeric characters.
    • All symbol and punctuation characters form word boundaries.
    • Most special characters remain in the final name and do not get extra spaces around them.
    • The new Object Type Name Removed Characters options lists special characters that should be replaced with a space when names are separated, and eliminated when names are explicitly combined. The default setting replaces the .:_ (period, colon, and underscore) characters with a space in a sepated name and removes these characters in a combined name.
12. 2022-08  Roles are not generally verbalized outside the fact type simply because there is no new information to add. However, it is possible to add additional information to a role. The most common additional data is a role name. Custom properties also have data associated with roles. Roles are now verbalized if there is a role name (like Role for ROLEPLAYER, named NAME) or if there are child verbalizations, either for custom properties or for role constraints. Role custom properties in particular are very confusing without the role context because there is no way to see the role affinity from a property name/value pair. If the role name is not unique the subscript role numbers are based on the positions in the verbalization of the context fact type.

Sample Population

1. 2008-10  Some of the sample population keyboard navigation issues have been addressed. We have not reached the point where you get a spreadsheet-like experience, where you can simply start typing in a text field and you automatically enter edit mode, but there were a number of improvements made that should improve the overall editing experience even without the automatic activation. In addition to the arrow keys used for moving between cells within the sample population grid, there are three keystrokes that are used for edit activation.
   • F2 activates an in-place edit control if one is not currently active
   • Escape deactivates an in-place control. Note that if you have a dropdown open, the first escape closes the dropdown, and the second escape deactivates the in-place editor. Be very careful with the third escape, which is associated with the global Visual Studio Window.ActivateDocumentWindow command, which deactivates the current tool window and reactivates the document window.
   • Alt-Down opens a dropdown window for the active in-place editor. You can use Alt-Down at any time instead of clicking the displayed down button.
   Several bug fixes have been made for the 2008-10 drop.
   • The Escape key is handled directly if an in-place editor is active. Previously, the keystroke was caught and handled by the global command handler, which activated the document window.
   • If a cell is expanded, the Down key from the first element in the cell will move down the expanded tree, not to the next numbered row in that column. If a cell has a closed expansion, then Right will expand it and Left will collapse it. A second Right will move to the next column. You can also move to the next column without expanding with a Tab, but not if an in-place editor is open (Tab in this case will select the dropdown button).
   • Only leaf nodes (ones without an expansion button) support direct text editing. However, non-leaf nodes were also activated with a read-only text box, which trapped navigation keys in the text box. Expandable cells are activated with just the dropdown button and pass all keystrokes except Alt-Down and Tab to the main grid control. What this means for you is that, except for leaf nodes, the arrow keys work the same whether or not the dropdown button is visible.
2. 2008-10  Sample population supports population of subtypes without their own identifiers via a direct reference to an instance of the supertype that provides the identifier. Text editing is not enabled for subtype instances in the editor. Instead, the use can either choose from a pick list of existing supertype instances that are not currently link to another instance of the subtype, or expand the subtype node to add a new supertype instance. As the identifying supertype may not be an immediate supertype of the element, add an instance to a subtype will automatically populate intermediate supertypes.
3. 2008-10  Objectified FactTypes can be directly referenced and populated in the Sample Population editor. All FactType roles are displayed for any reference to an instance of an objectified FactType, even if the identifier only spans a portion of the roles in the FactType. Inline editing of a FactType instance is accomplished the same way as inline editing of complex identifiers, namely with an expansion within the editing cell that allows existing instances to be edited and new instances to be defined.
4. 2008-10  Most objectified FactTypes use one of the internal uniqueness constraints of the FactType as the preferred identifier. However, any identification scheme (reference mode, complex, subtype, etc) can also be applied to an objectifying EntityType. By convention, an objectified FactType with an external identifier is shown with an extra lead column for the identifier. If the identifier is complex, then the contents of the first column are expandable. New validation errors have been added to verify that all objectified FactType instances are associated with an identifier instance, and vice versa. Unattached FactType instances are shown in the sample population editor, while unattached identifier instances are available in the instance picker dropdown in the first column. Activating the population error (via a double-click in the Error List, selecting the error in the 'Validation Errors' submenu, double-click the error shape, or clicking an error hyperlink in the Verbalization Browser) will activate the Sample Population Editor with the appropriate selection for fixing the error. To delete an external identification, select it as the identifier of an empty FactType instance, select the row by clicking the first column, and the press delete.
5. 2008-10  In previous builds, indirect editing of a ValueType used as an identifier would modify the value for all relationships. This is the expected behavior for popular reference modes, where the underlying ValueType is reference via a single relationship. However, it is completely inappropriate for general and unit-based reference mode patterns, where a single value can be used to identify multiple instances. To handle this case, a new value is created if the old value participates in other FactType instances. To change all uses of a ValueType instance, select the ValueType itself and edit the instance.
6. 2008-10  Most models have a number of FactType populations that are fully implied by one of the role players. The most common of these cases is the standard reference mode pattern, where the population of a one-to-one FactType is implied by the identified EntityType. Other FactType patterns that are implied are SubtypeFacts where the subtype uses a supertype identifier and the binary FactTypes implied by an objectification pattern. Implied FactTypes appear read-only in the sample population editor.
7. 2009-05  The delete key can be used at any time to delete a cell with a value in it. Deleting the last value-containing cell deletes the instance for that row. To delete a row instance directly without deleting its parts, place the selection in the first column (with the numbers) before pressing delete.
8. 2009-06  Automatic activation of sample population errors has been extended to support disjunctive mandatory constraints. Activating a 'population mandatory' error through a specific role by selecting the item in the 'Validation Errors' context submenu or double-clicking the role adds a new fact instance for the context FactType with that role prepopulated. If you want to add the other value to another fact instance, simply escape any active editors and undo the last action. Activating a disjunctive mandatory error through the error list will populate the first role player mentioned in the error text.
9. 2009-10  Selecting a fact type that is part of the identification scheme for an entity type shows a read-only implied population in the Sample Population Editor. However, selecting a role in an implicitly populated fact type displays the editable population of the identified entity type.
10. 2023-03  The dropdown for any field with auto-generated data has an <Auto Generate> entry in the dropdown right after <Unspecified>. For numeric auto generated values, choosing this value this will pick the number after the highest number used in the set of values (starting with 1 if the set is empty). For a UUID this enters the text form of a new UUID.

ORM Notation

1. The displayed reference mode notation corresponds to notational changes introduced in Information Modeling and Relational Databases (Second Edition by Terry Halpin and Tony Morgan, March 2008). A . (period) is prepended to popular reference modes and a : is appended to unit-based reference modes. We will eventually expand the : notation to formally recognized units of comparable dimension (length, for example). Entering either of these notations will automatically introduce a new recognized reference mode pattern to the model. You can see the reference modes you've added in the 'ORM Reference Mode Editor' tool window.
2. A solid subtyping line indicates that the subtyping relationship leads to the preferred identifier directly or indirectly (over other supertypes). The old notation marked a primary supertype even if the subtype had an explicit preferred identifier. If multiple paths lead to the preferred identifier then all paths will be solid. The old 'IsPrimary' notion will be updated when the .orm file is loaded. Loading a modified file on a previous NORMA version will give schema validation errors on load, but the file should load successfully if the Shift key is held down during load (follow the directions in the schema validation error dialog).
3. There is an option called Binary FactType Multiplicity Display in the Entity Relationship Learning Mode category on the 'ORM Designer' tab of the Tools/Options diagram. Enabling this options overlays common Entity Relationship (ER) multiplicity notations on binary FactTypes on the ORM diagram. You can choose CrowsFoot only (displays many), Barker notation (crowsfoot plus dotted line on mandatory roles), or Information Engineering (line symbols correspond to the UML-ish derived Multiplicity property in the Properties Window when a Role is selected). The display changes impact binary role player links only—the multiplicity concept breaks down badly when applied to non-binary facts. Thanks to Dr. Gordon Everest for the suggestion. The Barker option only applies to multiplicity settings; it does not add the tick on the line indicating a part of the identification scheme. The 'Mandatory Dot Placement' option is ignored when ER learning mode is enabled, so mandatory dots will always be displayed on the Role end of the relationship.
4. 2008-10  Although derivation rules in NORMA are still informal, they are displayed in the right place. All derivation rules were originally displayed on the FactType and the SubtypeFact. This convention rapidly breaks down for SubtypeFact relationships because one subtype can have multiple supertypes, and because there is no good way to indicate the presence of a subtype derivation rule on the diagram.
   • Derivation rules are available for any subtype, and are no longer available on the SubtypeFact relationship.
   • The presence of a derivation rule on a Subtype is indicated with a * decoration on the Subtype.
   • Any existing derivation rules on the SubtypeFact will be moved to the Subtype when an existing document loads.
   • If you have a subtype derivation rule but delete the subtype relationship, then the rule will be remembered but ignored and not saved, so changing the subtype relationship in the same session will not lose your derivation rule.
   • Verbalization of derivation rules has not been done.
5. 2009-05  Subtype lines are automatically displayed between a subtype shape and the nearest supertype shape on the diagram. However, it is not uncommon to use both a subtype and its supertype on a secondary diagram that does not need to display the subtyping relationship between the two types. This can often lead to an awkward subtype line being drawn across the diagram that can (previously) only be fixed by adding a second shape for the subtype or supertype nearer to the other endpoint. The DisplayRelatedTypes property displays on all object type shapes (and all objectified fact type shapes) where the associated object type participates in either end of at least one subtyping relationship. You can choose to display lines to supertypes, lines to subtypes, lines to neither, or lines to both (the default) for each object shape.
6. 2009-05  ORM2 specifies freeform placement of role name shapes. The modeler is responsible for placing the role names in such a way that the clutter of connector lines back to the associated roles are not needed. Additional highlighting has been added to the NORMA designer, so that moving the mouse over a role will highlight the corresponding role name shape, and vice versa. The highlighting is subtle (the background darkens in the role box and on the role name shape), but is sufficient to indicate that the role name/role box pairs without selecting the role box and examining its properties.
7. 2009-10  Individual shapes for value constraints have two additional display properties, MaxColumns and MaxValues, that enable value constraints with multiple items to be displayed on more than one line. MaxColumns controls the maximum number of columns that should be displayed, and MaxValues allows truncation of the total number of values. If the full list of values is truncated, hover over the value constraint shape will display a tooltip with the full list of values.
8. 2010-02  Value constraints are displayed with locale-specific list separators and locale-specific numeric formatting based on machine settings. Value constraints are also entered based on the machine settings for list and decimal separators. So, in an US English systems you would enter {1.5..2, 3..4}, whereas a German system would use {1,5..2; 3..4} for the same value constraint. The value constraint display will change when the system settings are changed. If the user-entered form of a number cannot be interpreted as the same number in the new locale, then an invariant form of the number is used. For example, a US English user might enter the floating point number .5. If the file is then opened on a German system, the user will see 0,5 for this value. Similar adjustments are made for displayed sample population values.
9. 2010-02  Special delimiter characters used in value constraint definitions can be specified inside single-quotation characters. For example, a,b,c for a string data type is parsed and listed back as {'a', 'b', 'c'}, while 'a,b,c' is treated as a single string value. Use two adjacent single quotes to represent a single quote in a string ('''abc''' represents the string 'abc'), and use '' to represent the empty string.
10. 2011-06  The DisplayAsObjectType property on a shape for an objectified fact type enables uncluttered use of the objectified fact type as an entity type. The display is exactly the same as an object type shape with name and reference mode fields, except that a miniature role box to the left of the text fields indicates the objectifying nature of the entity type and the arity of the objectified fact type. Other shapes attached to the fact type (reading shapes, role value constraints, role name shapes, and the name shape for the objectified entity type) are removed from the diagram and recreated when DisplayAsObjectType is changed from true to false.
11. 2011-06  Link fact types represent the relationship between an objectifying entity type and each of the role players of its objectified fact type. A link fact type is implied and automatically create by NORMA for each role in an objectified fact type. Readings for these fact types can be modified in the 'Implied Fact Types' branch of the 'ORM Reading Editor' tool window when a single role is selected in an objectified fact type. Readings can also be modified by selecting the fact type in the 'ORM Model Browser' tool window and expanding the 'Implied Fact Types' child node. In most cases there is no need to display these fact types. However, it is not uncommon for the objectifying-entity-type-attached role to participate in a set comparison constraint. Shapes are never automatically generated for link fact types, but an explicit shape can be added by dragging an implied fact type node from the model browser.
    Notes on link fact type shapes:
    • Link fact type shapes are displayed with dashed lines on the role boxes.
    • The link fact type role attached to the objectifying entity type will always have single role uniqueness and mandatory constraints. These constraints are part of the objectification pattern and cannot be deleted or edited.
    • The far role (opposite the objectifying entity type) will show an internal uniqueness constraint for unary and many-to-one (internal uniqueness on one role in a binary fact type) objectification patterns. If the far constraint is the preferred identifier for the objectifying entity then it will display with a double line. This is a duplicate display of the constraint on the objectified fact type, but cannot be edited from a link fact type selection.
    • Apart from simple mandatory and uniqueness constraint display, no other constraints will be shown as attached to the far role.
    • Role names and value constraints are not shown on the fact role of a link fact type. These are the same as the corresponding role on the objectifed fact type and are not duplicated.
    • Some other editing actions are unavailable for far roles on link fact types (group operations, for example). The primary reason to show these is to attach constraints to the objectified roles, and this scenario is satisfied without full editing capabilities on the far roles.
12. 2011-06  Three new ring types and corresponding combinations provide additional positive ring possibilities and a stronger form of intransitivity. The new values are:
    • Transitive requires the transitive closure of the item to be provided. If A plays B and B plays C then A must play C. The display is the same as intransitive without the tick mark at the bottom of the triangle.
    • Reflexive requires an instance to play itself itself if it participates in any instance of the restricted fact type. The display is the same as irreflexive without the tick mark.
    • Strongly Intransitive adds a recursive component to the intransitive ring type. With straight intransitivity, if A plays B and B plays C, then A cannot play C. However, if C also plays D, then the basic intransitive ring type places no restriction on A plays D. Strong intransitivity blocks this possibility. The display adds a fourth dot on the right leg of the intransitive triangle.
    The addition of these three ring types greatly increases the total number of simple ring types (from 7 to 10) and combinations (from 4 to 16). As 26 options is an unreasonable number for a dropdown pick list, the ring type dropdown now contains check boxes and single values. The editor feedback is as follows:
    • A bold and checked item is part of the current selection.
    • A bold item that is not checked is compatible with the current selection and can be added without reducing the current selection.
    • A gray-checked item (never bolded) is implied by the current selection. This provides a useful reminder of how the ring types compose. For example, asymmetric implies irreflexive and antisymmetric.
    • Ring types are ordered by negative followed by positive (reflexive, symmetric, and transitive are positive types). The negative items are ordered by the somewhat subjective notion of strength, starting with the weakest ring type (irreflexive).
    Designing consistent glyphs for the new combinations required some minor display modifications to published ring display: the tick mark for irreflexive has been moved from the bottom of the shape to directly opposite the dot, the interior circle for symmetric+irreflexive has been moved to the left edge of the symmetric oval and shares the left dot, and an interior tick mark has been added to purely reflexive to distinguish it from reflexive and visually indicate the and no other part of this ring type.
13. 2013-01  Selected external constraints can now be connected simultaneously to a subtyping relationship and a normal role. The following constraint combinations are supported:
    • External mandatory constraints (both inclusive and exclusive).
    • Exclusion constraints with one column. If a subtyping relationship is included in a new exclusion constraint in the constraint editor, then it is assumed that this is a single-column constraint and the displayed numbers refer to the row number, not the column number. Reactivating an exclusion constraint that includes a subtype will fix the editor in single-column mode, so you must remove the subtype relationship (control-click the subtype line), commit (double-click on a remaining role), and reactivate a constrained role to reenter normal multi-column set comparison constraint editing mode.
    • Subset constraints from a subtyping relationship to a single role. The editing behavior is the same as with an exclusion constraint. The editor will allow selection of a subtyping relationship only on the first click, and menu items to reorder the role sequences are disabled.
    Other set comparison constraints (equality and subset from a role to a subtype relationship) were intentionally omitted. Both of these constructs indicate that instance playing the role is always the subtype of the subtyping relationship. The correct model in this case should change the role player to the subtype instead of the supertype. Adding a subset constraint from a subtyping relationship to a role on the relationship subtype (or another of its subtypes) indicates a similar situation, so a new validation error is generated in this case.
14. 2013-12  Value comparison constraints are used to enforce an ordering (or equality or inequality) over two related role players. A cardinality constraint item has been added to the toolbox, with editing gestures the same as an external uniqueness constraint and all other non-set comparison constraints. Value comparison constraints will produce errors if either role player does not map to an object type, or if an operator is not specified, or if the selected role players cannot be compared. Comparison is done at the data type level, so the role players do not need to be compatible if the data types can be compared. However, if either data type has a unit-based reference scheme, then that unit must match to allow comparison. Value comparison constraint cannot include unary roles.
    
    Value comparison constraints support equality and inequality operators for comparisons between incompatible role players. If the role players have compatible types, then equality and inequality value comparison constraints are more easily represented using equality and exclusion set comparison constraints.
    
    The December 2013 release introduces value comparison constraint notation, validation, and verbalization, but does not yet map these constraints to the generated relational model or other physical representations.
15. 2013-12  Cardinality constraints specify restrictions on the total number of instances of an object type in model population. These constraints can also be applied to unary fact types, limiting the number of different roles players that are allowed to play the given role player. A new cardinality constraint is added with the CardinalityConstraint property on an object type or unary fact type. This property acts like the ValueRange property by adding a cardinality constraint shape to the diagram. The shape can then be selected to edit the cardinality or set other properties (constraint name, modality, etc.).
    
    Care should be taken when selecting a unary fact type that the fact type itself is selected, not the unary role. There are some visual feedbacks on the diagram during mouse hover than will help you disinguish the two: the highlighted background is different with the full fact type highlighting some space outside the shape and the role highlight affecting only the role; the mouse cursor is different for the two different objects, with a move cursor for the fact type and a pointer cursor for the role.
    
    Cardinality constraints support multiple ranges, including the value of zero. The default cardinality (without a constraint) is always zero or more. Of course, the zero corresponds to an empty population, which you will always have with an initial database. If you set a cardinality that does not include zero, then you're saying that you are planning on providing seed data for your system that will be provided before the cardinality constraint is enforced. If you want your constraint to apply only when some population is present, then provide multiple cardinality ranges, the first of which is exactly zero. For example, '0,2' says that if any instances are present then you must have exactly two instances.
    
    Cardinality ranges are displayed in the cardinality constraint shape starting with a '#' and using '..' for a range and '≤≥' for open ended ranges. Multiple ranges are shown in curly braces separated with the list separator specific to your machine locale (a comma in English). A leading '=' is provided if a single value is given. So, #=2 means exactly two instances, #{2,4} means two or four instances, #{0,≥3} means 0 or 3 or more instances, and 5..10 means between five and ten instances. The editor for these ranges, including the CardinalityConstraint property, is not exactly the same as the display because not all of the display characters are easily typed. Full directions for recognized patterns are shown in the description pane of the Property Browser when the CardinalityConstraint property (or the Ranges property of an existing constraint) are selected. As an example, #{0,≥3} is entered as 0,3.. or 0,>2 or 0,>=3.
    
    The December 2013 release introduces cardinality constraint notation, validation, and verbalization, but does not yet map these constraints to the generated relational model or other physical implementations.
16. 2022-08  Allowing machine-specific display options (in the ORM Designer options page) to cause changes in the saved state of a file is not a good idea. When this happens, loading and saving a file with no additional changes will cause a significant change to the file and potentially lose data. Unfortunately the Display Reading Indicator and Display Role Names options fell into this category of destructive machine options because they could change the shape sizes (which are saved) as well as remove user-positioned role name shapes and even add auto-position role name shapes. Several changes have been made in this area to introduce a better design pattern for these and future display settings.
    • These two options on the ORM Designer page have been moved from the Appearance category in the options page to the new Appearance (New File Defaults) category. As such, changing them will only affect the display options for a new file, not existing files.
    • An new-file-default option has been added for Binary Reverse Readings, which can be set to (default) Show Reverse Reading or the newly available One Reading Only value. This option and the corresponding properties discussed below determines if an available reverse reading is shown on a binary fact type. These are informative, but meaningful readings can be long and introduce significant clutter to the diagram, so this is now configurable.
    • Each ORM Diagram now displays two additional expandable properties in the Display Options category. These are GlobalDisplayOptions and LocalDisplayOptions. The first will be same for all diagrams, and the second customizes options on the selected diagram. These will show values of (Default) or (Custom), with the latter bolded, to indicate if any of the expanded properties are non-default.
    • Both of the expandable properties contain values for ReadingDirectionIndicator, ReverseReadings and RoleNames. As with other properties values, these are bolded if they are not default. The default state for the global options is the same on all system (irrespective of the options page settings) while the local options are default if they match the corresponding global option. For example, if the global ReverseReadings option is set to the non-default Only One Reading then this value is shown in bold, the container value changes to (Custom), and the correspond local display property changes to Default (Only One Reading). The local option can be locked into a value at any time by moving off the default value.
    • In addition to the global and diagram-local values, each fact type shape can control these values individually using properties beginning with Display (DisplayReadingDirection, DisplayReverseReading, DisplayRoleNames). These use the diagram-local options as the default, which can in turn defer to the global defaults.
    With these multiple levels of control (global, local diagram, individual shape) you get fine-grained control over your preferred display settings, and these are now all a part of the file instead of at the whim of the appearance settings for a specific machine.
17. 2022-08  The ExpandRefMode property has been available since the initial NORMA release, and it has been a workflow problem just as long. ExpandRefMode=false indicates that the reference mode field should be shown on the object type shape. Setting this to true is meant to indicate that the reference mode field is not needed in the shape because additional shapes are shown for the fact type and value type elements forming the reference mode scheme identification pattern. There are several issues with this:
    • ExpandRefMode=true may represent the expanded form when it is first set, but there is no guarantee that the expansions remain because they are frequently deleted. In this case, ExpandRefMode=true simply means to hide the RefMode shape on the object type.
    • For economy of space, hiding both the reference mode field and expanded shapes is normal modeling behavior. The user should not constantly be forced to deal with the identification scheme each time a new shape is created for a popular object type.
    • Deleting the shapes is a hassle for an experienced modeler, especially on a crowded diagram. For a new modeler it is very easy to delete the underlying elements instead of the shape. In fact, the tool issues a prompt for this.
    • Switching display forms on an objectification could actually recreate the deleted shapes because the ExpandRefMode property is propagated between shapes, and setting it will recreate shapes for the identifying components.
    There is a better way, so we're retiring ExpandRefMode from the NORMA UI and replacing it with a new property called RefModeDisplay. (If you're feeling nostalgic and want to see ExpandRefMode we have not changed the file format for this change, so you can see it in the .orm file viewed as XML.)
    • RefModeDisplay refers to the visibility of the RefMode field on the shape instead of the visibility of the pattern shapes, so RefModeDisplay=Show is the default state and matches the old ExpandRefMode=true.
    • RefModeDisplay=Hide simply hides the RefMode field. It does not remove pattern shapes.
    • RefModeDisplay=Hide (Create Shapes) removes the field (if shown previously) and creates the shapes, just like the old ExpandRefMode=true. If you can select this you will immediately revert to the hide value.
    • The pattern shapes are still removed when transitioning to RefModeDisplay=Show, just like they were removed with ExpandRefMode=false.
    • A new global display option HideNewShapeRefMode has been added. When this is true then an object type shape created from the fact editor, model browser or toolbox will have the RefModeDisplay property set to Hide instead of the default Show. Shapes copied from other existing shapes (both in the same model and across models) retain of the properties of the source shape, so this option does not apply in this case.
    Although the retirement of ExpandRefMode may be an adjustment for some we feel like this new pattern will remove unnecessary steps from the common task of creating a new shape for a popular object type.

Notes and Informal Definitions

1. An informal definition field is available for FactType and ObjectType elements. The 'ORM Informal Definition Window' works like the 'ORM Notes Window' (changes are committed on focus change). You can also enter informal definition text in the properties window. Definitions verbalize and can also be displayed in tooltips with the 'Show Definition Tooltips' option, which is off by default. Informal definitions are not formal derivation rules and have no impact on the formal interpretation of the model. We will eventually support links to other terms, but for now this field is just plain text.
2. 2008-10  The Notes and InformationDefinition semantics are supported with a Model selection. The resulting information is verbalized and appears in the generated reports.

Groups

1. 2009-02  The Groups menu and corresponding Model Browser node is a facility for applying arbitrary grouping across elements of a model. This can be used to track groups of elements within a model in any way the user chooses. However, the full power of groups will be more apparent in future tool releases that apply additional meaning to these groups of elements through the notion of Group Types. Note that there are no group types installed with the initial (February 2009) release, we've just added the facility.
   • A new group can be added via the context menu on the Groups node in the Model Browser, or by the Groups/Include In/New Group command. Groups can be renamed the same as any other element (via the Properties Window, or by pressing F2 to edit the name inline in the Model Browser).
   • Most elements can be dragged onto a Group node to add them to the group. Any element than cannot be dragged (for example, Role and Internal UniquessConstraint) can be included in a group using the Groups menu, or by dragging the individual elements from another branch of the model browser.
   • Elements can be deleted from a group using the Groups menu or by using 'Delete' with the linked element selection in the Model Browser.
   • 2013-12 An element can be selected inside its group using the Select In submenu on the groups menu.
   • Double-clicking a linked element in the Model Browser will navigate to the specified element.
   • It is possible for a grouped element to have no corresponding primary node in the tree. These elements do not provide a link indicator on the icon.
   • [The remaining points are part of the grouping facility, but are not applicable until group types are added in future releases.] The GroupTypes property contains a checked list of Group Types, which can be added to the system by extension models. Multiple group types can be specified for one group. A group type can automatically add member elements to a group as well as blocking elements from inclusion in the group.
   • The GroupTypeCompliance property is used to determine how tightly the group types control constrain group membership. The default setting (Not Excluded) allows element inclusion as long as no group type explicitly excludes the element. The other two settings (Approved by Some Type and Approved by All types) require one or all associated group types to either formally recognize or automatically include the element. Any automatically included elements can be explicitly excluded by the user, and will appear greyed out with an 'x' on the icon. If an element is automatically included by one group type and excluded by another then an error state is display with a '?' on the group member icon and a validation error '!' on the group node icon.
2. 2020-05  (This is used for NORMA extensions and will have no effect without extensions that leverage it.) There have been a number of significant extensions to allow greater flexibility for group types to add elements within a group. Previously a group type could either add elements automatically or respond to elements added explicitly by the user (or another group type). However, there was no way to use both explicit (user-defined) content and automatic content in the same group. For example, if a group type wants to automatically add the role players (and track changes) when a fact type is explicitly added to the group then that group type needs support for both explicit and automatic group content. The grouping extensions were also enhanced to enable custom expansions within the group itself, allowing for much more advanced classification and nesting of grouped elements.

Relational Extensions

1. A relational model is generated automatically in NORMA when you turn on the 'Map to Relational Model' extension. All extensions are available using the 'Extension Manager...' dialog on the main NORMA designer context menu. The tool supports 'live' regeneration of the relational model, but does not yet support incremental generation. The clearest evidence you'll see of the regeneration is that the Tables expansion in the Relational Schema (shown in the model browser) will collapse when significant changes are made to the model. Some things are incremental (name changes, mandatories on one-to-many binary fact types), but the majority of ORM changes will result in a full regeneration of the relational model.
2. Once you've turned on the 'Map to Relational Model' extension, you will have a 'Relational Schema' node in the 'ORM Model Browser' (available under 'ORM Tool Windows' on the context menu,Ctrl-W,Ctrl-M). You can expand the nodes here to see what will be generated. As noted earlier, the displayed relational model is frequently regenerated. Usability note: the * key on your number pad (or via Num Lock on a laptop keyboard) recursively expands treeview nodes.
3. The 'Relational View' extension provides a live view on the relational model, but is not required to see the relational information. The 'Relational View' is also a placeholder for later work and can be a performance drain. Selecting a table or column in the relational view is equivalent to selecting the same table or column in the 'ORM Model Browser' window. The Relational View performs very badly because the shapes are fully regenerated (and the lines rerouted) for most ORM changes. As with the 'Relational Schema' expansion in the model browser, property changes made to the model are not validated and will be overwritten the next time the relational model is generated. A performant and well designed relational view has been specified (see 'Documentation\Relational Designer' in the source code), but requires fully incremental relational changes to be successful.
4. The displayed relational model is not yet self-validating (we simply generate a correct model), so there are a number of changes that can be made that are inconsistent with the ORM model and other parts of the relational model, such as changing the Column.IsNullable or UniquenessConstraint.IsPrimary properties. These changes will be lost on the next regeneration triggered by an ORM modification. Also, the algorithm version used to generate the relational model is stored with the .orm file. Opening an existing file with newer version of NORMA may result in a regeneration of the relational model.
5. The exception to 'change at your own risk' with generated relational properties is the DataType property displayed on a column. Changing the DataType (and related DataTypePrecsion/DataTypeLength/DataTypeScale properties) on the column makes the corresponding change directly on the underlying ValueType in the ORM model. The implications of these DataType are easiest to see in the 'Relational View' with datatype display enabled.
6. You will see additional properties on SubtypeFacts and ObjectTypes when the extension models are turned on. These properties are displayed under the 'Relational Mapping' category and allow you to control absorption/separation/partitioning of tables. Partitioning is offered only when an XOr constraint exists between all subtypes (the exclusion and mandatory constraints must be joined, select both and use the 'Combine as Exclusive Or Constraint' context menu to create a formal relationship between the two constraints).
7. We have two parallel generation algorithms examining the ORM model. The current algorithm is only used when generating DDL and for the LinqToSqlAttributeMapping generator (Visual Studio 2008 only). The older code generation pieces (Plix Implementation in the generator settings dialog) are not yet using the new information. If you have an existing project with old DDL generation, it is likely you are not picking up the new generator. To fix this problem, select the .ORM file in the Solution Explorer, open the 'ORMGeneratorSettings' dialog, and expand the 'Intermediate and Secondary Files' and 'DCIL' nodes. The DCIL node should contain the 'ConceptualDB to DCIL' and 'OIAL to DCIL' generation choices. Make sure the first one is selected. This will also automatically load the required extensions when you 'Save Changes' in the 'ORM Generator Selection' dialog. In the future, all generation will use the same absorption source.
8. Column name generation has an extensive set of options. Names should be shorter and less repetitive with other names. The main point of control for name generation is specifying how popular, unit-based, and general reference mode patterns are used when referencing EntityTypes or specifying identifying columns. The default settings for these are available on the model itself (under the 'Relational Mapping' categories) and are repeated under the 'Name Generation Settings' branch (specifically the Column Specific refinement of the 'Relational Names' branch). Overrides for individual EntityTypes are available by selecting that EntityType.
9. Additional abbreviation of individual ObjectType names as well as specific phrases are available in the 'Abbreviations' dialog for any of the Name Generation Settings nodes. Phrase abbreviations can include multiple words and can map to empty strings, which will omit the phrase. Phrases are treated case insensitively for replacement. Note that each child node in the Name Generation Settings branch is a refinement of the parent node and affects the scope where the abbreviation is supplied and all children. For example, changes made with the Relational Names node selected apply to both column and table names.
10. 2009-06  Name collapsing (showing only one of two equivalent adjacent names) is performed on a whole-word basis to avoid overaggressive collapsing of partial words. For example, in previous releases, BidId would reduce to Bid and FemaleMale to Female, which was clearly incorrect. To balance this fix, the notion of a whole word has been enhanced by recognizing each part of a multi-part word in the conceptual model as a whole word. Any word with embedded capitalization that does not also have two adjacent capitals is automatically treated as a multi-part word (ObjectType, etc). Recognition of these word patterns also enables easier word replacement. For example, replacing the phrase Employee with Emp will affect both Employee and ContractEmployee.
11. 2010-07  Analysis of chained 1-1 fact types has been enhanced to provide an experience more consistent with non-chained 1-1 fact types in two ways:
    • If there are multiple 1-1 fact types that can fully absorb an object type (similar to a subtype absorption) towards different object types, then consider the choice arbitrary and do not allow either absorption option.
    • Prioritize otherwise equivalent 1-1 chains based on mandatory patterns.
12. 2010-12  Generated relational names treat adjacent capital letters as a single word with a fixed case. If lower case letters occur after multiple capital letters, then the last capital is considered part of the following word. Numbers are also treated as word breaks. A lower case letter following a number is treated as part of the number. For example, 'ORMModel' is split into {ORM,Model} and 'NameCasing1aDetails' is split into {Name,Casing,1a,Details}. This change extends the prior compound name interpretation by breaking apart names with adjacent capital letters.
13. 2012-01  Prior to this release, regenerating the relational schema (a frequent occurrence when the ORM model is changing) results in the loss of any name customizations in the relational schema. In addition, the column order shown in NORMA (sorted by primary key columns, then by column name) differed significantly from the column ordering in the generated DDL (sorted by columns in the mandatory key, non-nullable columns, columns in other uniqueness constraints, and remaining unordered columns). This release provides some relief for these issues.
    
    
    • Table and column names can be customized by changing the name in the Relational View or ORM Model Browser (press F2 to activate in-place editing for column names in the relational view, or for any name in the model browser), or by setting the Name property in the Properties Window. The Properties Window displays a customized name with bold text. The name can be restored to the generated value by setting it to an empty string, or by using the Reset item in the context menu for the Name property in the Properties Window.
    • Automatic column sort order can be customized using the ColumnOrder property with a Table selection in either the Relational View or ORM Model Browser. This property provides common grouping options for sorting columns. Columns are also ordered by name inside each of the groups. The ColumnOrder property defaults to <Schema Default>, and the default setting can be modified with the DefaultColumnOrder property on a Schema node in the model browser, or with a background diagram selection in the Relational View.
    • Column order can be customized by dragging a column onto another column in the same table in the model browser and relational view.
      • Custom-ordering columns will set the Table.ColumnOrder property to Custom, and the ordering can be reset by modifying this property.
      • Columns added to custom-ordered tables will add new columns to the end of the table using the schema-default column order.
      • An attempt is made to recognize column ordering (and names) when columns switch tables due to model changes, including separating and partitioning subtypes in table. The column order in a newly separated table will be marked as custom ordered if more than one custom ordered column is moved from another table, and will have the schema default order otherwise. Reabsorbing a partitioned table will likely lose column customizations (both names and positions) on re-absorbed columns.
    
    Opening and saving files with the relational extensions enabled will automatically update to use the new column orders. Generated DDL will also be updated when the file is saved.
14. 2013-01  Prior to this release, the DDL generated for SQL Server used ANSI standard data type names, but these are not supported by default in SQL Server 2012. The default has now been changed to use native SQL Server data type names. The generator that produces ANSI data types is still included. To use the ANSI types, expand the SQL_SQLServer node in the ORM Generator Settings dialog and choose DDIL to SQL Server (ANSI Types) instead of the default DDIL to SQL Server.
    
    You will need to open and save a model file to see the new data types, or right-click the .ORM file in the Solution Explorer and choose the 'Run Custom Tool' menu item.
15. 2013-12  Prior to this release, the native data types (see previous item) mapped all of the ORM temporal data types to the 'datetime' data type. SQL Server has supported time- and date- only temporal types for several releases, so this has been expanded. The {Date, Time, Date & Time, Auto Timestamp} temporal data types now map to the {date, time, datetime, rowversion} data types.
    
    You will need to open and save a model file to see the new data types, or right-click the .ORM file in the Solution Explorer and choose the 'Run Custom Tool' menu item.
16. 2022-08  In the past if a user chose to absorb a subtype (or other structurally similar 1-1 where absorption is offered) then NORMA would proceed with the absorption even if no columns remained for the subtype in the absorbing table. Now, the choice to absorb is treated as a suggestion that is only respected if evidence (at least one produced column) of the absorbed subtype exists in the supertype's table. Otherwise this is ignored. This change will be applied on load.
17. 2023-03  Oracle added support for native IDENTITY columns in version 12c. All prior version are past end-of-life, so this is always generated in the Oracle DDL.
18. 2024-08  If a subtype is absorbed into a relational table (instead of separated into its own table) and the subtype has no mandatory roles (including no played roles), then we will now generate a column with the name isSUBTYPE, where SUBTYPE is based on the name of the absorbed object type (possibly adjusted to satisfy name generation settings). This allows all subtypes to be definitively asserted if the subtype state cannot be inferred from other data.
    
    This pattern is also applied to other absorbed objects. For example, an objectified unary fact type will absorbed just like a subtype, except that the column naming will be based on the unary fact type readings instead of the object type name. This means that if the unary objectification itself plays roles with an explicit or implied mandatory constraint, then the data column for the unary itself will not be mapped. This makes the mapping for objectified unary fact types and subtypes highly consistent. As noted in the whitepaper and video linked for this change, the main different here is that the objectified unary fact type can be independent. In this case, the extra column will be produced if IsIndependent is false (or if there are no roles). This differs from the subtype, which cannot be independent. Therefore, all subtypes that do not play any explicit mandatory roles will have an isSUBTYPE column.

Database Import

1. When you add a new file you will see both an 'Object-Role Modeling File' and 'Object-Role Modeling (DBImport)' choice. We currently support import from SQL Server and MySQL databases. You will be asked to choose a single schema during import. Importing multiple schemas in a single step is not currently supported.
2. After you choose your import schema, you will be prompted twice for various options. This happens because the wizard portion of the importer generates an XML file in DCIL format (the format we use during generation to represent a database). This file is then run through the normal import mechanism, which recursively runes XSLT transforms against the starting XML until the result of the transform can be loaded natively. For database import, we run three transforms. The first has no options, the second generates an ORM model with core elements only (the first prompt), the third transform (the second prompt asking about shape population) adds diagram information and produces a designer-compliant file format.

Code Generation

1. There are currently several options for generating an object model from an ORM model, but only one (LinqToSqlAttributeMapping on Visual Studio 2008) is up to date. The older generation layers are based on an XSLT absorption algorithm that is several generations behind our current absorption algorithm. The other generation layers (PLiX_Implementation, PHPEntitiesImplementation) are included for those who already use them, but we can't recommend that you base extensive development on them. We will note in the readme when this status changes.
2. 2008-10  The settings file for the LinqToSqlAttributeMapping layer has been updated. This file is generated once then left for you to edit. We will eventually have a mechanism for automatically updating the settings file to integrate your settings with new schema information, but this feature has not been completed. You will need to use the ORMGeneratorSettings dialog to turn off the generated layer, save your changes, then reopen the dialog to turn the generator back on. You will need to reapply any customizations you made to the settings file (copy them before the file is regenerated).
3. If you are using the PLiX_Implementation generation classes, then the global support classes (shown in the generators dialog as PLiX_Support) must be selected for exactly one model in your project. This is no longer an automatic prerequisite because this forces it to be generated for all .ORM files, which will block compilation.

Instructions for reporting issues in NORMA

1. NORMA issues should be reported to the GitHub issue tracker. All reports should include the Visual Studio version and NORMA version. Of course, as with any git repository, you can also fork the repository and make pull requests if you want to dive into the source code.
2. The posted NORMA versions are debug builds. This means that asserts are enabled in the code base. The asserts basically say 'you've reached a state that wasn't expected'. Assert dialogs are not crashes. They are meant to help the developer determine how an unexpected state was reached and handle the case. You will see three buttons on the dialog box (Abort, Retry, Ignore). Your default reaction to an assert dialog should be to:
   • Ctrl-C to copy the assert dialog contents, which will include a message and a callstack. Paste into notepad to make sure you have the contents before closing the dialog.
   • Press Ignore to continue with NORMA. Abort will end the program immediately, Retry will attempt to attach a debugger. Obviously, if the asserts keep coming you may eventually have to quit, but most of these asserts can be ignored and you will be able to save.
   • Attempt to reproduce the condition and report the issue.
3. You may also see 'crash' dialogs from Visual Studio. NORMA is written in managed .NET code, while VS itself is a native (C++) framework. If you see a crash dialog, it generally means that an exception made it past the .NET code, but was handled by the native code. In most cases, you can safely continue and keep running. Do not panic and abort the program unless the dialog keeps coming back. You should also be able to get a callstack. The following extraction from a 27 August 2013 ORM Foundation post describes different classes of NORMA errors and how to callstack that can be used to track the problem.
   
   
   There are three classes of errors in NORMA:

   1. Errors that happen during a model change. Each item that shows up on the undo list is a single model change. These all happen under a transacted object model, and the model will return to the exact state as before the change, then report the error. This type of bug (which I've found to be the most common, and includes this one) are the easiest to track because they can be immediately reproduced by replicating the change.
   2. Errors that happen during playback of atomic changes in a single model change. These happen during the initial change, undo, and redo and always occur after the model change has been committed. The general source of these errors is one of the tool windows. NORMA is built with custom framework components that prevent one error from one rogue tool window during event processing (this stage) from bringing down the system. If an error occurs it is recorded but does not terminate playback. An error dialog is shown after the transaction playback is complete, and the system remains stable.
   3. Errors that happen during rendering of the diagram or one of the tool window states. These are generally the bugs that will lead to a crash, and are the hardest to reproduce because they can take the system down.

   If you get a reproducible failure that does not crash the system, then you can attach a debugger and get a callstack at the point the error occurs. NORMA installs the .pdb (debug symbol) files, so the callstack is generally readable. To do this (this looks long, but takes about 15 seconds the second time you do it. This should already be familiar for those who are developers as well as modelers).

   1. Open a second instance of Visual Studio.
   2. Choose the 'Attach to Process' command on the Tools menu (usually Ctrl-Alt-P).
   3. Before attaching your process, make sure the Attach to: settings are correct. You need to attach to the right version of Managed code, which varies depending on the Visual Studio version you're using. If the automatic setting matches what you need you may use it, but we recommend explicitly choosing your debugger type.
      • There are two kinds of managed code you can attach to—those before .NET 4.0 (versions 1.1, 2.0, 3.0, 3.5) and those after (currently 4.0 and 4.5). Visual studio 2005 and 2008 use the earlier managed code, and 2010 and higher use the latter.
      • If you aren't sure you'll attach to the right kind of debugger code, then use the Select… dialog to lock in the correct kind of debugging. Attaching a native code debugger to Visual Studio will give you a much slower debugging process, so make sure that you do not have this selected. Just select the Managed version that corresponds to your Visual Studio version.
   4. In the Available Processes list, choose to the 'devenv.exe' instance that is hosting the NORMA designer, then click the Attach button. You're attached to the NORMA Visual Studio process Visual Studio status bar stops flashing new messages and the title bar of Visual Studio includes the term (Running).
   5. Try to reproduce the bug. You may stop in the debugger at the point the error is thrown. If you don't, do the following:
      • Using the dialog from Tools/Options menu, choose the 'Debugger' category and uncheck the 'Just My Code' option, then choose OK to commit your options.
      • Open the Exceptions dialog from the Debug menu (usually Ctrl-Alt-E) and check the 'Thrown' column for the 'Common Language Runtime' category, then commit the dialog.
      • You should now stop somewhere in the code when you reproduce the bug.
   6. You may be prompted for a source location when the debugger stops. You can either ignore this, or pull the source code onto your machine from sourceforge. This is easiest if you have SVN and/or TortoiseSVN installed. Make sure you get the right changeset (the changeset number is shown in this file with the summary of the most recent changes). If you click the 'Code' page from orm.sf.net you'll see instructions on how to get a read-only copy. This can take two or three minutes. This step is optional. Obviously, it is really nice to have an exact line in the code, and this is easy if you already have SVN on your machine, but the problem can almost always be determined from the callstack (next step).
   7. Once the debugger is stopped, use the Debug/Windows/Call Stack menu to see the callstack.
      • If you see [External Code] in the list (this won't happen if 'Just my Code' is off), then right click in the dialog and choose 'Show External Code'.
      • You can also make sure that all of the options at the bottom of the context menu are checked (Show Module Names through Show Byte Offsets) to get the most information.
   8. With focus in the Call Stack tool window, Select All and Copy to get the callstack (Ctrl-A/Ctrl-C, or use the items on the context menu).
   9. Provide the callstack with the error report (a .txt attachment is fine).

   Please note that not all thrown exceptions that are thrown during normal operation are actual problems. In general, NORMA minimizes the number of thrown exceptions during normal processing cases, but that is not true for all of the VS components used by NORMA. Generally, if you attach a debugger after the .orm file is loaded then you will see very few 'false negative' exceptions, but you may see a ton during system startup and file load.
   
   NORMA is a good-sized code base, with well over half a million lines of active code. Unfortunately, there is very little the NORMA team can do with an error report that is extremely general ("I occasionally have problems", "I saw this error once", etc.). If you're using the tool, please take the required 5 minutes if you see a problem to get a callstack and/or reproduce the scenario from scratch. Please don't assume that we know about the problem. The bottom line is that there is no way to fix an issue that we don't know about and/or can't reproduce.

Unresolved issues in Visual Studio 2010 (and above)

These are areas that are incomplete and known issues with Visual Studio 2010.

1. If the .orm designer is opened simultaneously with more than one other file (such as when opening a solution) and is the active file immediately after load, then the ORM designer tool windows and menu items will not activate properly. Activating a second document (of any type) and reactivating the ORM designer will fix the problem. This is a Visual Studio 2010 bug (I can reproduce similar behavior with missing menus with one XML and one Text file).
2. The NORMA help files are not installed or integrated with Visual Studio 2010. [The installer merge modules used for help integration in VS2005 and VS2008 are not included with the VS2010 SDK.]
3. The FrequencyConstraint and Reading shapes are larger in Visual Studio 2010.
4. The document tab after a database import using File/New displays the full path of the temporary file instead of the base file name.

Mystery Bugs

If you encounter these issues or have a reproducible scenario, please let us know.

1. We have had cases where the Custom Properties extension does not work correctly on Vista. The 'PropertiesEditor' property is available on the model, but the custom properties do not appear on the target elements. This does not happen on all machines, but when it does, the workaround is to launch VS2008 as an administrator instead of as a normal user.
2. The FactEditor has refused to load properly immediate after installation on Visual Studio 2008. Restarting Visual Studio fixed the problem.
3. Occasionally when closing Visual Studio, a message appears stating that a modal dialog is open, and VS must be forcibly terminated with the task manager.
4. Reloading a model can reveal duplicate name errors on generated names for UniquenessConstraint and ImpliedMandatoryConstraint. The UniquenessConstraint errors are easily fixed because they can be selected in the model browser (double click the error, delete the name to regenerate one of the names), but the implied mandatory constraints cannot be selected. The are two ways to fix these: open the .orm file with an xml editor (Open With in Visual Studio, notepad also works) and delete one of the offending name occurrences then reload in NORMA, or use the Store Viewer (a debug command on the context menu) to determine an Object Type associated with the offending constraint. In the Store Viewer, select and recursively expand the ORMStore/Partition/Links/ObjectTypeImpliesMandatoryConstraint node (recursive expansion is done with the * key on the number pad), then scan for the offending constraint name, note the ObjectType name above it, and close the dialog. Find that ObjectType in the model and toggle (twice) either the IsIndependent property on the ObjectType or the IsMandatory property on an optional attached role. The naming error will go away. My apologies for the hassle, I just haven't managed to reproduce the scenario that causes this problem, and the issue is not visible until the file is reloaded. Update on this issue: The underlying problem has not been fixed, but duplicate generated names are automatically regenerated on reload. The intent of this change was to make it easier to merge models under source control, but it also has the side-effect of making this bug even more obscure. The error will be visible only as duplicate names in generated code, not in the designer. Reload the model and explicitly save to clean the file.

Version Numbers

(This is a historical discussion. Versioning is now git-based, as described at the end of this section.)

The NORMA version numbering scheme was changed in January 2011 to make better use of the available build numbers. A build number (for example, 1.0.1106.6281) has four parts separated by periods (.): Major (1), Minor (0), Revision (1106), and Build (6281). The major and minor numbers are self-explanatory. The third revision number is the last two digits of the year combined with the month number (1106=June 2011). The revision number is explicitly configured in the source code and generally changed once per official release. The final number is a build number that encodes the day the file was built.

Originally, the first two digits of the build number were a month counter beginning at 01 in January 2006, with the last two digits representing the day in the month. So, build 6031 was created on day 31 of month 60 (December 31, 2010). Starting with January 2011 (month 61), the first two digits will only be incremented on a quarterly basis, effectively tripling the available remaining 4-digit revision numbers. Of course, the day numbers for the three months in a quarter cannot all begin with '1', so we partition as follows:

• The first month in each quarter (January, April, July, October) gets the range 1-31 (subtract 0 to get the day).
• The second month in each quarter (February, May, August, November) gets the range 34-64 (subtract 33 to get the day).
• The third month in each quarter (March, June, September, December) gets the range 67-97 (subtract 66 to get the day).

So, build 6281 represents the fifteenth day of the third month in the second quarter of 2011 (June 15, 2011).

Although the version information does not directly contain any source code version control information, the build date can generally be cross-referenced against the revision history to find the corresponding changeset.

For Visual Studio 2017 and later versions, the downloaded NORMA extension version will be based on the GIT tagging system. NORMA is now under source control on https://github.com/ormsolutions/NORMA instead of in Sourceforge. The final SVN change number is 1564. The extension version numbers will generally look like 1.0.3xxx.0, with the 3 artificially injected so that the GIT version numbers are always greater than the date-based system. This will allow us to seamlessly change file versions to match the extension version in the future. The final number is a revision count of changes after the last tag and will generally be 0 on official releases.

As of September 2020 the quarter-based versioning system described above moved to 100, which pushed the quarter-based versioning to five numbers. Setup (for VS2015 and earlier) identifiers assume a 4-digit revision and setup cannot be built with five revision digits, so all future builds will now be based on the git build numbers. Git build numbers are determined by explicit tags added to the source repository and revision numbers are now the number of revisions past the last tag. This also means the file version numbers will match the installer version number in VS2017, VS2019 and VS2022.