Best Practices
Go Up to Using ER Studio DA
This section is comprised of the following topics:
- Using Descriptive Object Names
- Adding Comments to Database Objects
- Color-Coding Objects
- Using Macros for Repetitive Tasks
Using Descriptive Object Names
Every object in a data mode, such as entities, attributes, attachments, naming standards templates, and domains has a name, which identifies it in the Data Model Explorer, Data Model Window (data model workspace), logs, and reports.
To make it easier to understand data flows, make these names as descriptive as possible. For example, instead of accepting a default name such as "Entity," you might use "Customer."
- Multiple entities in a model can have the same name, however the combination of entity name and entity owner must be unique. You can edit the Owner property of an entity or table in the Entity or Table Editor.
When naming objects, you can use upper, lower or mixed case. Perhaps the easiest format for people to read and understand is mixed case, capitalizing the first letter of every word (for example, CustomerAddress).
- You can enforce naming rules by creating Naming Standards and binding them to tables and entities, or you can create Domains. For more information, see Enforcing Naming Standards Using Naming Standards Templates.
Adding Comments to Database Objects
Every object in a data model has a description or definition that is included in reports. To help document your data models, enter a description or definition for every object detailing its purpose and any other information that might be needed for a future modeler to understand the role of the object in the task. You can also add comments to most database objects. For more information, see Adding and Editing Object Comments.
Entity definitions are included as table comments when generating a physical database and in exported SQL code if the target RDBMS supports table comments.
You can also enhance your data model by documenting relationships. Relationships can also have verb phrases that describe the relationship. For example, a Company employs a Manager who supervises a Worker. You can create relationship verb phrases by double-clicking the relationship, and inserting the verb or inverse verb phrase on the Phrases tab of the Relationship Editor. An inverse verb phrase describes the relationship from the child"s point of view.
Color-Coding Objects
Use colors to make your diagrams more attractive and organized. For more information, see Setting Default Diagram Colors and Fonts and Overriding Color and Font Settings for a Specific Object.
Using Macros for Repetitive Tasks
ER Studio Data Architect includes many sample macros written in Sax Basic, that can be used as is or that can be customized as required. The tutorials in this guide provide some examples of how macros can save you time. The headers of the sample macros contain some usage documentation but a quick read through of the macro code should give you some ideas of its usefulness. We do not guarantee that the sample macros will all work in all your environments but if you have special requirements you can collaborate with other users through the online user forum or by contacting Embarcadero Support for assistance.
The Macro Editor uses a Sax Basic Engine that is compatible with Microsoft Visual Basic for Applications. This guide does not extensively describe the syntax or usage of Sax Basic, but there are lots of Visual Basic books available to guide a novice user. The tutorials provide some examples of how macros can save you time.
Repository Best Practices
This section discusses best practices you can use as you work with models with ER/Studio Repository.
Your Active Directory Folder and Getting Diagrams from the Repository
Your Active File Directory is where local files from the repository are stored when you perform a Get Diagram operation from the Repository. There are two types of Get Diagram operations:
- Repository Merge: If there is a local copy of a Diagram (dm1) in the Active File Directory then the Repository will proceed to merge the Repository dm1 with the local dm1. If there are any conflicts resulting from changes between the local dm1 and repository dm1, you will see the Review Changes Dialog which allows you to resolve the conflicts. If the local copy of the dm1 is checked in (Blue Locks on all objects), then the local copy will be opened and a Get Latest Diagram operation will be performed.
- Clean Get: If there is no local copy in the Active File Directory, then the Repository will create a new copy of the dm1. There will be no conflicts to resolve. Typically this is a faster operation than if the repository needs to merge changes between the repository dm1 and local dm1 during the get process.
You can get an entire diagram or just a submodel (partial dm1 get). For normal work on a dm1 file you should get the entire dm1. The local file name will be the same regardless of whether you retrieve a partial dm1 or the entire dm1. This makes it difficult to switch between submodels if you are retrieving partial dm1s from the Repository. If you intend to make a change to only one submodel and only that submodel, then you should get a partial dm1, but for all other use cases, you should get the entire dm1. It will be much easier to switch between submodels and the logical/physical models when the entire dm1 is retrieved. Also, the Where Used tab is not available when you retrieve only a partial dm1.
The Active File Directory should be local to your machine and not located on a network shared with other users. As you are working in the Repository you can save changes locally to the dm1 in the Active File Directory through the normal File > Save operation. Working off-line is a great way to maximize productivity. As long as you check out everything you need to work on before going off-line, you can safely save changes locally until you decide to check them back into the Repository (see Checking In/Out Objects below for more detail).
Performance Tip! If you want to get working right away with a model, you can open it directly from the active directory. The object checkout status from when you saved and closed the file will be preserved and you can start working immediately.
If you are working with multiple Repositories, you should use different active file directories for each Repository so that there are not any file name/sharing violations for similarly named dm1 files. A good practice is to create one Active Directory with subdirectories for each Repository that can be easily identified. This is usually reserved for Admin users, not normal daily work within the Repository.
- Usually a second repository is for a test environment when testing upgrades of ER/Studio. Multiple repositories are not advisable solely for segregating models.
Checking In / Out Objects
Once you have gotten a dm1 from the repository. You can check out the entire diagram or portions of it. The level of check out recommended depends on what changes you intend to make. The Check Out Diagram operation is recommended if you will be making changes throughout the dm1, such as merging models, creating/editing submodels and working in either the logical or physical. The Check In Diagram operation has been optimized for when a number of changes need to be checked back into the Repository and is typically faster than checking in/out at the object level. Checking in/out at the diagram level is recommended for normal daily work on models. If a single, incremental change needs to be made to a specific object, then you should check in/out objects individually.
There are two types of check out operations:
- Exclusive Checkout: The exclusive check out will lock the checked out objects so that the objects can only be worked on by one individual. If you check out objects, upstream and downstream dependent objects will also be exclusively checked out. It is entirely possible to exclusively check out objects and lock objects from other users without knowing they are checked out.
- Non-Exclusive Checkout (the default): The non-exclusive check out will allow other users to work on the same diagram at the same time. Conflicts will be resolved upon check in. Unless you want to make absolutely sure no other users is accessing the model you should use the default, non-exclusive check out so that you avoid unintentionally locking out objects needed by other users.
- When checking an object into the Repository, there is an option to leave objects checked out in the Check In dialog. Check this option if you know you need to do more work on a model, but you want to get some changes into to the Repository for other users to see or use. This is a great way to get working faster the next time you open the local file as it will already be checked out.
You should check in your changes at least daily so that other users can see your changes. However, check in operations are queued up sequentially, on a first-in, first-out basis, with other Repository operations such as Get Diagram, Get Latest and Login, so it is best to figure out a time that works for you where your Repository operations won't be contending with other users.
The Repository Merge Operation / Review Changes
When a model or portion of a model is checked back into the Repository, a merge operation is performed between the local dm1 in the Active File Directory and the Repository. The Repository merge will compare the changes in the local file with the changes in the Repository.
To review the changes, simply check the Resolve Conflicts option in the Check In dialog. "Soft" conflicts will show up under Additions, Updates and the Deletions nodes. "Hard" conflicts will show up under the Conflicts node. Soft conflicts are changes that exist between the local and Repository copies of the dm1. Hard conflicts are changes that conflict with changes made at the same time by another user.
For most soft conflicts, you can deselect any changes you don't want to check into the Repository. These changes will also be removed from the local file. As a best practice, you should keep dependent changes checked. For example, if you are adding a column to a table, you should also keep the dependent updates like column sequence changes selected as well.
For hard conflicts, you have only the choice of keeping your change or the other user's change. You need to pick one of them (your change will be the default). The other user will also need to resolve this change as well by performing a Get Latest Version operation and accepting the Repository change. During a Get Latest Version operation the Review Changes dialog will appear and the Repository changes will be chosen by default.
- The Check In operation is not complete until the Review Changes dialog has been closed and the dm1 has been refreshed. If you leave the Review Changes dialog open while reviewing with a colleague or leaving your desk, you could be holding up pending operations by other users. If you need to review the changes more closely, you should generate a report to analyze the changes more closely.
Summary
- Access the local file in the Active File Directory to get working faster.
- Keep items checked out.
- Check in items daily.
- Review changes to compare Repository and local file differences, but don't keep the Review Changes dialog open for too long.
- Check in/out at the diagram level to minimize Repository contact and maximize your ability to work across the entire dm1
- Check in/out at a more granular level only if you intend to make a quick change to a specific object.