Dabase modelling: problems with the Entity shape

I'm using the reverse engineering wizard to help me build
documentation for an existing database. It creates a diagram
composed of Entity shapes. I've found that the Entity shape is really
meant for desiging databases, not for documenting them. I've having
trouble dealing with the resulting mismatch.

The root problem is that Entity is designed to represent the fields in
a table and nothing more. For documentation, that's just pointless.
To make my work useful I have to give information about how the
associated application uses the table, what data is stored in it, how
it relates to other tables, etc. Entity has no place for any such
information.

I thought I could work around the problem by putting notes in a
rectangle below each Entity and grouping each Entity/rectangle pair
together, but Entity is fighting me there, too. An Entity is
impossible to resize, so I can't match its width to the width of the
corresponding rectangle. It seems impervious to snap and glue, so I
can't even align a pair of shapes without an excessive amount of work.

I've starrted reading about how to modify stencils, and eventually I
may figure out how to make Entity behave as I want. For now, though,
I'm seeking ideas on how to get the results I need -- or any
presentable approximation -- without the learning curve.

What version if Visio are you working with?


Aaron Rykhus, MCP, MCDST
Online Support Engineer
Microsoft Corporation
----------------------------------------------
This posting is provided "AS IS" with no warranties, and confers no rights.

On Thu, 15 Nov 2007 21:17:08 GMT, (Aaron
Rykhus [MSFT]) wrote:

What version if Visio are you working with?

2007 Professional.

I've found that I can get a better looking result by placing the
Entity inside the Rectangle, instead of stacking them. That
eliminates most of the ugliness caused by inability to resize the
Entity.

The obvious next step is to group the two together, but I discovered
that Entity refuses to let itself be grouped! Whoever created the
database stencil seems to have taken pains to make it impossible to
use in any but the precise way the designer intended.

Database modeling just reverse engineers the database like you mentioned.
There's not a way to have it read how it relates to the application. But
there is UML modeling diagrams and other software modeling diagrams in the
Visio Professional edition. Also, checking out the stencils may give you
some ideas too. I'm not sure if you're aware, but there is a special
edition of Visio that comes with Visual Studio 2005 Team System called
Visio for Enterprise Architects 2003 which is basically just like Visio Pro
2003 but with Database forward engineering and UML reverse and forward
engineering, and reporting. There is currently not an edition to match up
with Visio Pro 2007 though.

As for the workarounds you have tried (e.g. putting notes on rectangle)
there is a Notes section in the Database Properties. If you actually want
to show something on the page next to the Entity shape you could have Shape
Data in the Entity shape and have a Data Graphic to display the shape data
next to the Entity shape. You can get to the Shape Data and Data Graphics
by right-clicking the shape and pointing to Data. The Visio Help files (F1)
also have documentation on data graphics and shape data.



Best Regards,

Aaron Rykhus, MCP, MCDST
Online Support Engineer
Microsoft Corporation
----------------------------------------------
This posting is provided "AS IS" with no warranties, and confers no rights.

Thank you for your assistance. I've been studying your suggestions,
and have some further observations and questions.


But there is UML modeling diagrams... I'm not sure if you're aware,
but there is a special edition of Visio... with Database forward
engineering and UML reverse and forward engineering, and reporting....


I know about the UML stencils, and I will try them out when I have
time. I also know about the UML reverse engineering feature, but
Visual Studio does not support the language that the software I'm
documenting is written in. That's why I'm not using Visual Studio,
and why I chose to use the ER stencil rather than the UML stencil.

My client is much more concerned about the database structure than the
application itself, and since I have to document the application
structure by hand, I'm not trying to document it in the degree of
detail that UML diagrams invite.

...there is a Notes section in the Database Properties. If you
actually want to show something on the page next to the Entity shape...


I have to. For this client Visio is a documentation tool, not a
development tool. I can't ask the developers to use it to read my
documentation.

...you could have Shape Data in the Entity shape and have a Data
Graphic to display the shape data next to the Entity shape....


I wasn't aware of this feature. I've learned the rudiments of it now,
and it looks like it may become a good solution to my problem.

Not everything is working as it should, though.

I opened the document stencil's Entity shape and defined a Shape Data
item named Comment, of type String, then edited the Data Graphic to
display Comment as text. I set the Data Graphic's default callout
position to Left, Below Shape.

The Comment text appears where I want it to, but Entity displays
Comment as a number, even though it is defined as String. It
positions the text flush right, and an empty Comment displays as
0.0000.

Also, the text fills only part of the width of the Entity shape. That
looks very ugly when the Comment text is long. And the text is
displayed in a tiny font size that I can't figure out how to change.

Last but not least, even I edited Entity in the document stencil, new
objects created by dragging a table from the database model to the
drawing are created with the original Shape Data and the original
empty Data Graphic! I've got to solve this problem, or the whole idea
of using Shape Data and a Data Graphic will be a near-miss; it will
create more work for me than it will save.

If I'm understanding this correctly, you want to document not just the
database but how it relates to the application. In short, the database
modeling solution in Visio is for documenting a database, not for how it
relates to the application on top of the database. The only way I can think
of documenting how the application relates to the database would be to
manually "tag" that on the shape. I'm not sure how it would be possible to
reverse engineer the application relationships to the database unless it
was in the database tables itself. But even then there isn't anything that
Visio would have to reverse engineer that.

There's a change that there may be an add-in or application one of our
partners has created to accomplish this additional functionality, although
I didn't find anything like this though on the partners directory at
http://directory.partners.extranet.microsoft.com/

...using the advanced search and selecting
-Specialization=Data Visualization
-Specialization Business Scenarios=Database Modeling



Best Regards,

Aaron Rykhus, MCP, MCDST
Online Support Engineer
Microsoft Corporation
----------------------------------------------
This posting is provided "AS IS" with no warranties, and confers no rights.

On Mon, 26 Nov 2007 22:49:48 GMT, (Aaron
Rykhus [MSFT]) wrote:

If I'm understanding this correctly, you want to document not just the
database but how it relates to the application.... The only way I can think
of documenting how the application relates to the database would be to
manually "tag" that on the shape.

Yes, that's exactly what I'm doing. I'm a technical writer, and that
is one of the services people pay me for.

There's a change that there may be an add-in or application one of our
partners has created to accomplish this additional functionality, although
I didn't find anything like this though on the partners directory at
http://directory.partners.extranet.microsoft.com/

I infer that the problems I identified have no solutions within the
Microsoft stencils. That's unfortunate -- they're general problems,
not at all unique to the particular use I want to make of the Data
Graphic Feature. I believe they seriously limit its utility.

I'll take a look at the add-in you suggested. I don't think my
client is likely to spend money for an additional software tool in the
middle of the project, but it could be useful for similar future
efforts.

Jonathan - some suggestions:

If you edit a Master in the local document stencil, then be sure to change
the "Match master by name on drop" property of the local master to True,
otherwise you will create a new Master when you drag from the original Visio
stencil.

The Shape Data window and dialog only display a single line, although you
can enter upto 64k of text in each one. If you want multiple lines, then
use Notepad as your text editor, but you'll have to copy and paste backwards
and forwards from Notepad to your shape data row each time.

You can use the custom callouts from the bottom of the Callouts stencil to
display these multiline shape data rows in your Entity shapes.

The display "0.0000" is because you left a null string in the Value of the
shape data. You could set the default to an empty string "" by typing in
anything then deleting it.

"Jonathan Sachs" wrote in message
...
Thank you for your assistance. I've been studying your suggestions,
and have some further observations and questions.


But there is UML modeling diagrams... I'm not sure if you're aware,
but there is a special edition of Visio... with Database forward
engineering and UML reverse and forward engineering, and reporting....


I know about the UML stencils, and I will try them out when I have
time. I also know about the UML reverse engineering feature, but
Visual Studio does not support the language that the software I'm
documenting is written in. That's why I'm not using Visual Studio,
and why I chose to use the ER stencil rather than the UML stencil.

My client is much more concerned about the database structure than the
application itself, and since I have to document the application
structure by hand, I'm not trying to document it in the degree of
detail that UML diagrams invite.

...there is a Notes section in the Database Properties. If you
actually want to show something on the page next to the Entity shape...


I have to. For this client Visio is a documentation tool, not a
development tool. I can't ask the developers to use it to read my
documentation.

...you could have Shape Data in the Entity shape and have a Data
Graphic to display the shape data next to the Entity shape....


I wasn't aware of this feature. I've learned the rudiments of it now,
and it looks like it may become a good solution to my problem.

Not everything is working as it should, though.

I opened the document stencil's Entity shape and defined a Shape Data
item named Comment, of type String, then edited the Data Graphic to
display Comment as text. I set the Data Graphic's default callout
position to Left, Below Shape.

The Comment text appears where I want it to, but Entity displays
Comment as a number, even though it is defined as String. It
positions the text flush right, and an empty Comment displays as
0.0000.

Also, the text fills only part of the width of the Entity shape. That
looks very ugly when the Comment text is long. And the text is
displayed in a tiny font size that I can't figure out how to change.

Last but not least, even I edited Entity in the document stencil, new
objects created by dragging a table from the database model to the
drawing are created with the original Shape Data and the original
empty Data Graphic! I've got to solve this problem, or the whole idea
of using Shape Data and a Data Graphic will be a near-miss; it will
create more work for me than it will save.

On Tue, 27 Nov 2007 10:30:33 -0000, "David Parker"
wrote:

,,,change the "Match master by name on drop" property of the local master
to True...

That fixes the problem of getting the original Entity style when I
drag a table to the drawing. Thank you.

The Shape Data window and dialog only display a single line...

Yes, I discovered that early on. It’s a pain, but I can live with it.

You can use the custom callouts from the bottom of the Callouts stencil to
display these multiline shape data rows in your Entity shapes.

I’m puzzled by this, and I wonder if we’ve lost sight of the original
reason for using shape data. If I add a custom callout and link it to
the shape data, how is that better than typing my note into a
Rectangle, as I have been doing? I still have two shapes where there
should be one. I still can’t group them or use snap and glue to align
them. The only differences I can see are the drawbacks: the callout
gives me less control over the appearance of the note, and the shape
data forces me to enter my note in a fixed-single-line field.

I was only offering suggestions to overcome shortcomings in the DB modelling
solution...:-)


"Jonathan Sachs" wrote in message
...
On Tue, 27 Nov 2007 10:30:33 -0000, "David Parker"
wrote:

,,,change the "Match master by name on drop" property of the local master
to True...

That fixes the problem of getting the original Entity style when I
drag a table to the drawing. Thank you.

The Shape Data window and dialog only display a single line...

Yes, I discovered that early on. It's a pain, but I can live with it.

You can use the custom callouts from the bottom of the Callouts stencil to
display these multiline shape data rows in your Entity shapes.

I'm puzzled by this, and I wonder if we've lost sight of the original
reason for using shape data. If I add a custom callout and link it to
the shape data, how is that better than typing my note into a
Rectangle, as I have been doing? I still have two shapes where there
should be one. I still can't group them or use snap and glue to align
them. The only differences I can see are the drawbacks: the callout
gives me less control over the appearance of the note, and the shape
data forces me to enter my note in a fixed-single-line field.