Persiflage and Piffle

When starting a new model I seldom want to start from a blank canvas; instead I’d like to use a template to get us going. Within RSA/RSM there are already some templates provided, and whilst useful, they are (necessarily) very generic.

A simple way to enable this is to create a model from an existing model from the New UML Model wizard page.

Whilst this approach is workable for an ad-hoc approach to copying models, it’s far from ideal, especially in an environment where you would like your modelling team(s) to be using a consistent set of templates. A better approach would be to hook into the “Create model from standard template” mechanism. Whilst this isn’t particularly difficult to do, it doesn’t appear to be that well documented, with the only reference I found being a support page relating to RSA v6 (which is using an export wizard that doesn’t appear to be available in v7).

The way it’s done is by creating an Eclipse plug-in with an extension of the “com.ibm.xtools.modeler.ui.wizards.template” extension point. Under this extension you specify a directory which contains the model to be used as a template, an image to be used in the wizard page and a template definition file that pulls the whole thing together and provides some descriptive text.

Since I think that it’s likely that it’s likely there are people out wanting to do this who are not Eclipse plug-in developers, and in fact may not even be a developer (in the case of business analysts, for example). I’ll go through it in a lot more detail. Trust me, it’s simple, and you won’t need to write a single line of code.

1. Create a plug-in project
The first step is to create a new plug-in project (File-> New Project->Plug-in Development->Plug-in Project). Give your project a name. It’s typical to keep the project name and plug-in identifier the same; you should also be aware that the plug-in identifier will need to be unique, so use a reverse domain name style of notation. I’ll use com.pnp.modelling.templates.blog. The other thing you should do is untick the “Create a Java Project” check box - see, I told you we wouldn’t be writing code Now click Next.

On this second page, change the plug-in version from 1.0.0 to 1.0.0.qualifier. I’ll explain later why; for now just trust me, it’s plug-in development good practice to suffix the version number with .qualifier. Click Finish (you don’t need to change any other options so don’t click Next). You’ll be prompted on whether you want to change perspective to the “Plug-in Development perspective“. It’s upto you whether you do or not; if you’re unsure, select No.

2. Adding the extension
Once the plug-in project has been created, the tool will automatically open the plug-in manifest editor, which allows us to make changes to the plug-ins that we’re defining. If you accidently close this, don’t panic, just right-click your plug-in project and select PDE Tools->Open Manifest. At the bottom of the editor are a number of tabs called Overview, Dependencies, Runtime, etc. The one we want is called “Extensions” so click that now.
From here, you need to click the Add button to allow us to add the extension we need. Untick the check box “Show only extensions from the required plug-ins” and in the “Extension Point filter” type “*model*wizard“. Select the extension called “com.ibm.xtools.modeler.ui.wizards.template” and click Finish.
You will get a prompt asking if you want to add some dependencies, you must click “Yes”.

You’ll now be back at the manifest editor. Right click com.ibm.xtools.modeler.ui.wizards.template in the “All extensions” list, and select New->directory. On the right the “Extension Element Details” will show a path; the default it put for me was “com.pnp.modelling.templates.blog.directory1“, change this to “templates“. Select File->Save All.

3. Create the resources
Right click the plug-in project, select New->folder. The folder name must be the same as the name we put into the template extension; so for us that’s “templates“.

In this directory we need to put three things; a model file (i.e. a .emx file), an image (e.g. a 48×48 pixel gif file) and a template definition file.
3a. Create the image

Let’s start with the image, this is easy. You can use any image editing program that’s capable of producing GIF files. (It’s quite possible that other file formats work too; that’s not something I’ve tested) The image I created was 48×48 pixels and is quite a simple image with just the words “Foo” and “Bar” on it. Once created I simply copied it into the template directory in the plug-in project (you can even just drag it from your explorer window onto the directory in RSA - no need to right-click->Copy right-click->Paste).

3b. Create the model
Next is the model; now you could create a new model from scratch by right-clicking the templates directory and selecting New->Other…->UML Model. It’s more likely that you already have an existing model that you want to copy. For this, I suggest opening a new view within the tool since the project explorer view tries to be a little clever by hiding the underlying model files. Although this is useful most of the time, it’ll be a pain for us right now. Therefore we’re going to use the Navigator view; from the top menu, select Window->Show View->Other… In the “type filter text” text box at the top of the dialog type “Nav” and you should have a single entry left, which is the Navigator view (in the General category). Select Navigator and click Ok.
In the navigator view, you can see the raw file system resources. In my case I already have a model file I want to use as a template called foobar.emx in the Nermal UML project. To copy, just right click the model file and select “Copy” (or press Ctrl-C) and then right click the templates directory and select “Paste” (or select it and press Ctrl-V). (N.B. You can also copy it by dragging the model file onto the templates directory whilst holding down the Ctrl key - without the control key you’ll move it rather than copy it). See the two screen shots below of the before and after.

3c. Create the template definition file
Create a new file by right clicking the templates directory (in either the Navigator or Project Explorer views) and selecting New->File. The file suffix must be .templatedef.ve and it’s sensible to keep the name consistent with the model name. So, for me, the file name is foobar.templatedef.ve.

The contents of the file are as follows:

# Unique id for the template
# (use plugin id + model name)
id=com.pnp.eclipse.modelling.templates.foobar
# file name of the template's model file
templateFile=foobar.emx
# file name of the template's image
icon=foobar.gif

# Descritive name of the template
name=FooBar Model
# Longer description of the template
description=Create a new FooBar Model.
# default name of the new model created
# from the template
modelName=FooBar Model

All the lines starting with # are comments and so are ignored. This leaves six entries that need to be completed: id, templateFile, icon, name, description and modelName.

4. Test it works
To test that this works, we can either export the plug-in and test it in our installation (jump to the next section for that) or you can test it by ‘self-hosting‘. Although this is done from within the RSA tool, it does involve starting up a new running copy of RSA which means you’ll not be able to do this very easily if you’re using a memory contrained computer.

To do this we need to open the PDE’s perspective (Window->Open perspective->Plug-in Development). Now select Run->Run… then right-click “Eclipse Application” and select “New“. Now we select “Run” and wait for the new instance of RSA to open.

(Depending on the capabilities of your machine, it may take a couple of minutes to launch the new RSA instance.)

When it (eventually) starts, open the modeling perspective and select File->New->UML Model. You’ll get the same dialog as always asking whether you want to create from a “standard template” or an “Existing Model”. Make sure “standard template” is selected and click “Next”.

Note the “FooBar” template is listed, and see the entries from the definition file in the dialog.

5. Export the plug-in

To be able to use the plug-in properly we need to export it so that we can deploy it within the tool. First we need to configure the plug-in’s build settings to indicate what needs to be exported. You need to be in the plug-in’s manifest editor (if you closed it, right-click your plug-in project and select PDE Tools->Open Manifest).

Select the “Build” tab at the bottom. In the binary build tree, click the “templates” folder (you’ll notice that the resources within the templates folder are automatically selected.

Make sure everything is saved (File->Save All).
To exprot the plug-in you need to export as a deployable plug-in. To do this, from the menu select File->Export->Plug-in Development->Deployable plug-ins and fragments. In the export dialog, make sure that the plug-in is selected. Enter a directory where you want the export to put the deployable plug-in and click Finish

After exporting, you’ll see that a “plugins” directory has been created under the directory you specified. Within this is a single jar file that contains your deployable plug-in.

Note that the name of the JAr file is the plug-in identifier followed by the plug-in version; although the ‘qualifier‘ part of the version has been replaced with a date/timestamp. This means that exporting the plug-in twice (mode than a minute apart) will create two distinct plug-in versions. This is a good thing and I’d strongly recommend allowing this. If this is something you really don’t want then either select a specific qualifer value on export (in the Options tab of the Export dialog) or remove the ‘.qualifier‘ suffix from the plug-in version.
To deploy this, copy the JAr file to <InstallLocation>\SDP70\plugins (i.e. for me C:\IBM\SDP70\plugins) and restart RSA.
If you’ve followed these steps, the new template will now be available when you create a new UML model - honest.

6. Next steps
To make deployment easier within a team, you should strongly consider create an update site and hosting it on a development or departmental server - see Eclipse - How To Keep Up To Date.