How the Harmonized Model Repository
Works, And How to Work With It
The purpose of this note is the inform members of ISO TC 211 how to build a editing
environment for the Harmonized model. A slightly different but related note is available at:
https://www.seegrid.csiro.au/wiki/bin/view/AppSchemas/ConfiguringUMLToolForHollowWorld
Description of an Editing Environment
A working client (UML editor) for the Harmonized Model repository has 3 components
involved, as follows:
1. The SVN (Subversion) Server at JRC, in Italy.
2. An SVN Client on the editor's machine.
3. A working copy of Enterprise Architect (EA, almost any recent version, 8 or later is
preferred).
The same setup could act as a viewer, but the overhead for SVN would need to be balanced
against the need for the “absolutely latest model.” If ‘timeliness” is not an issue, the HMMG files
on the ISO TC 211 web will still be available for viewing.
The SVN Server maintains an organized structure of text files. For EA purposes, each one of
them is an XMI file for a version of one of the controlled packages. For the Harmonized model,
these packages include:
1.
2.
3.
4.
one dated package per document per edition at FDIS or above,
one package for each ISO number containing all dated versions,
a drafts package for project documents and
one package (usually in Drafts) per active project or editing committee.
The Server also maintains a complete copy and history of every controlled package check-in, or
check-out operations by user. Given justification, a maintenance person with the proper
privileges can restore the data or any part of the data to any state at any prior check-in operation.
Anyone can copy a state to their machine for a particular date or version. Because of the
information subversion maintains, who changed what in any part of the HM is discoverable.
Using functions in EA, the precise nature of those changes can be listed. The SVN client allows
the user to keep a 'current-state' copy of any part of the repository local to the client machine.
The EA application (UML editor) is the only program that actually interacts with the data; the
client and server just move files around. All interactions by the editors with the model should be
through the EA application and not any other direct SVN application. Most of the EA editor
works the same whether or not the packages are controlled. The differences are the package
control operations, most of which are available in the context menu for packages.
The Client at the request of the EA application interacts with the SVN Server at the repository,
mostly through SVN-specific XMI exports and imports. During set-up, the client records username and password for the repository and uses it whenever called upon by the EA application to
interact with the server (usually either writing a newly edited package in XMI that is passed to
the server, or checking dates on the server and client and importing updated XMI into the EA
file). When the user checks out a package, the client locks the package on the server, gets a most
recent copy of the XMI and EA loads it and allows the editor to modify that package. When the
user checks that same package in, the client cascades the current copy of the XMI to the Server
and unlocks it. EA locks any package not currently checked-out by the user in the client
application’s view of the model.
The final working state of these three software components and the repository is:
Repository ↔ Server ↔ Client (local XMI copy) ↔ EA (file)
At any given time, there are 3 copies of the current data, the official files in the repository (with
all backups), a local copy of the most recent files synchronized by the client, and the current
working copy in the EA editor's file. When the editor does a check-in for all locked controlled
packages or does a "get all latest," all 3 copies of the model are identical.
NOTE: When doing a “get all latest” you are offered to read-all regardless of date. This will take
some time and normally if you do “get all latest” on a regular basis, only a few packages will
have been changed recently. If you select the “import changed files only” the update will be
quicker.
Getting a command prompt in Windows
If you know how to do this, skip to the next section. You can get a command window by:



Using the start menu, and run ‘cmd’ (in Win7 use the search box on the start menu) or
Using a browser context menu for the directory to “open command prompt here” (XP and
earlier).
You can also create a shortcut to C:\Windows\system32\cmd.exe (may be slightly different
depending on your Windows version and how it was built). Most versions of Windows will
recognize a shortcut target of “%windir%\system32\cmd.exe”. Clicking on it should open the
‘dos-like’ command window with a ‘command-line’ interface while clicking on the cmd.exe
file will open up the window in the wrong directory (probably \system32) for what you want
to do, but you can change directories with a ‘cd’ command once in the window. In the
window “help <command-name>” brings up ‘dos’ help text. For the shortcut options in the
property dialog from the context menu, I’d suggest:
o Start in: %HOMEDRIVE%%HOMEPATH%
o Run: “Normal Window”

o Under “Advanced” you may need to “run as administrator” depending on your
machine setup.
“exit” closes a command window.
SETTING UP THE SYSTEM ON THE CLIENT MACHINE
This section describes how to create an EA editing environment for the harmonized model
repository at JRC. You will need:
a. A user-name and password for the repository [only you edit the model],
b. A Subversion client installed on the machine and
c. A reasonable recent edition of Enterprise Architect.
1. If you do not already have a SVN client, download and install the CollabNet
Subversion Command-Line Client from http://www.collab.net/downloads/subversion.
Other clients are available, but I've never use them. SVN is a 'standard' and most all
clients should work - but you have no guarantees.
2. If you do not already have a user-name and password, contact the HMMG convenor
for one. It may take a few days to get. If you are only looking for read access, use the
ISO TC 211 Document Registry and password (as of Feb. 2011, pass = T***). If you
do not like the password you get, change it immediately since it will be stored in the
setup. If you change it latter you will have to redo part of the set-up
3. If do not have an EA editor, acquire one from SPARX
(http://www.sparxsystems.com.au/). If your current copy is older than version 8, you
probably should download the latest build and install it (there have been very useful
user interface improvements for 8 that are helpful in editing [or dealing with] the
HM). Because you need to construct files during set-up, you need an editor, the
viewer will not suffice.
4. In the directory you've chosen for a local copy of the repository, in a command
window (see above for how) using your user-name <username> run:
svn checkout https://inspire-twg.jrc.it/svn/iso/ --username <username>
--password <password>
[You can now leave the <username> out. It will not ask for password. The JRC repository
assumes that all new SVN connections are read-only. It will skip steps 5 and 6. The resulting
document is read only and you can stop at this unless you need to edit part of the Harmonized
Model. If you need a password to edit (and are an official editor of a draft ISO TC
211doucment), contact the Convenor of the HMMG.]
5. When you run the ‘svn’ by hitting ‘enter’, you'll get a long error/informational
message, ending in "accept permanently?" Accept by entering the single letter: p
6. It will ask for a password. Give it the one that goes with the username. ]
7. It will then load a copy of the isotc211 model repository in your current directory. It
will be called "iso" and have a special icon for ‘svn.’ At this point, you've got the
bottom of the final structure in place except that the local copy is as yet blank:
repository ↔
server ↔
client (local copy)
8. Type exit at the prompt to quite the ‘cmd’ window. You’ll populate the local copy in
the next step.
To complete the system and read in the data, when the previous step is done:
9. Open EA and create an empty EA model file.
10. Use the main menu to open a Version Control Dialog:
Project → Version Control → Version Control Settings
11. Set the following in the dialog:
Don't click private,
Unique ID:
Type:
Working Copy Path:
your working copy is a shared model
isotc211
Subversion
(the path to 'iso' from SVN step, i.e. where svn’s ‘iso’
directory is)
Subversion Exe Path: (location of svn.exe for the client – probably like
C:\Program Files\CollabNet Subversion Client\svn.exe)
Click save and wait for it to finish.
12. Once that it done, go to the model browser (usually on the right) and use the context
menu:
Package Control → Get Package.
13. The dialog will ask for the repository (from step 8), and you pick from a drop down
menu (should be only one choice at this time).
14. It then shows you a list of XMI files in the repository, pick iso/isotc211
15. When that is done, there should be a new package in the model called "ISO TC211.' It
is really an empty shell at this time.
16. Using the same context menu as before:
Package Control → Get All Latest.
17. There is an option to load only changed models. Since you're just starting it won't
make a difference, since all of them are 'new.' The import should take a while and
load all the sub-packages of the model; the model browser is a good indication of
what is happening and how far it has gotten, since it is update when each XMI
mentioned in the isotc211 root is loaded.
18. At this point, all packages are locked, but you can browse. The full structure is now in
place:
Repository ↔ Server ↔ Client (local XMI copy) ↔ EA (file)
19. When editing you need to check-out (don’t use branch, it is incompatible with
pessimistic locking, and the way the HM is maintained).
20. If you need to create a package for an entire document; during the dialog box to give
it a name, be sure that you indicate that the package is to be controlled. That will lead
to another dialog to give a place for the new XMI of the package to do within the
SVN repository. Most drafts will go in iso/isotc211/drafts/trunk and should be given a
mnemonic name, usually something to fit this pattern:
ISO <project-number>[-<part-number>][:date][document short name]
21. The final position and name of the IS model will be determined by the HMMG,
probably through a then-current policy.
Each time you begin, it is probably wise to repeat the "Get All Latest." Only the packages not
currently checked-out will be refreshed.
Before you can edit anything you will need to do a 'check out' for the controlled package where
your edits will be most directly contained. Packages higher up the hierarchy need not be checked
out.
When you're done editing, check it back in. In special circumstances it is reasonable to keep
something checked out between sessions - but if you always have a net connection, it is not
worth the risk. SVN can roll back to (recover) any ‘check-in’ point.
If you try to edit that which you have not checked out, EA will not let you.
If you try to check out things you do not have write access to, EA and SVN will not let you.
Both the CollabNet and SPARX have additional information in both help and web documents.
Getting SVN to ask for your password. (just in case)
This will allow you write access to the parts your user has access to using the EA editor. If you
do not read write access, skip this.
Since the JRC assumes read-only, you have to trick it in to asking for your user name.
If you want to use the command line interface, use the EA suggestion:
 Open EA Help, search for the “Verify the SVN Workspace” topic
 Follow the directions completely. Delete any file you created
If you have Tortoise SVN installed, you can do a similar thing using its context menu.
In your respository, if you have access to Drafts, go to …\iso\isotc211\Drafts\trunk and use SVN
to check-out, and then to check-in “Temporary.txt.”
]
ADDITIONAL POSSIBLITIES AND CAVEATS
This system uses a "pessimistic lock" and so if a user checks out a common resource (such as the
"Drafts" package where new drafts are created), while it is checked out no one else can change it.
For this reason, common resource packages should always be checked in once edits have moved
to a controlled sub-package of the common package or elsewhere.
SVN client-server interaction does not work across some firewalls. Home network firewalls are
not usually a problem. If your company firewall blocks SVN, you may look into the "guest"
network most companies use for visitors. They are usually more open. Public networks do not
seem to be a problem.
Any user can be used on multiple machines. If you commonly use more than one machine, you
can repeat the above setup on each. Just make sure to check in everything on a machine before
you move to another, since the machines are probably not sharing the same local files.