Authoring UML profiles using Rational Software Architect and Rational Software Modeler


This article is a detailed guide to the UML Profile Authoring support in the IBM® Rational® Software Architect (RSA) and IBM® Rational® Software Modeler (RSM) 6.x products. It covers both the UI support and programmatic support (for users extending the tool itself). It mainly targets profile authors, but it also offers some insight into profile usage.

The covered versions (in chronological order as they were released) are 6.0 GA, iFix002, iFix003, and 6.0.1. The 6.0.1 version is forward-looking -- it has not been officially released at the time this article was written. It is clearly indicated where there is a difference in behavior between versions.

The article assumes that you have reasonable knowledge of the UML 2.0 specification, especially the part related to Profiles. It does not attempt to further describe or clarify the specification, but rather focuses on its implementation in RSA and RSM. General knowledge about Eclipse, RSA, and RSM will be useful as well. Eclipse PDE (plug-in development environment subproject) knowledge is required if you wish to create plug-in based profiles.

Creating a profile

This section covers how to create a profile and its content. It also explores various features available to you in regard to the profile definition.

RSA and RSM UML Profiles are files with the .epx extension. The tool provides creating and editing capabilities only for files that are in the workspace. However, after you create a profile it does not necessarily have to be in the workspace to be used in models that are in the workspace -- more on this in the Deployment section below.

RSA and RSM also support Eclipse's open source profile.uml2 format for the purpose of applying it to a UML Model. It does not directly support editing files in this format, although they could be edited by using the open source's editor.

The rest of this article focuses on RSA and RSM's native profile format (.epx). For more details on the Eclipse’s open source format please see the Related topics section.

The Modeling perspective is the best equipped for profile authoring. The two main views used in profile authoring are the Model Explorer and the Properties view. The Model Explorer is used to build the elements of the profile and the Properties View is used to set their properties.


You can create a new profile either by launching the New UML Profile wizard (shown in Figure 1) or the New UML Profile Project wizard. To launch the New UML Profile wizard, click File -> New -> Other and then Modeling -> UML Extensibility -> UML Profile.

Figure 1. New UML Profile wizard
New UML Profile wizard
New UML Profile wizard

The New UML Profile wizard creates a profile in the specified folder. The name of the profile does not have to match the name of the file containing it, although it probably simplifies things if they are the same. The model libraries could be imported during the profile creation but that could be done afterwards as well.

The New UML Profile Project wizard simply provides a shortcut to create a project and a profile in it at the same time. Please note that the profile does not have to be stored in Profile Project -- it could be placed in any project.

After the profile is created, it will be selected in the Model Explorer. Also, Figure 2 shows the Profile Editor associated with the .epx file that will open.

Figure 2. Profile Editor
Profile Editor
Profile Editor

The Profile Editor is associated with the .epx file itself. It only offers some informational data about the profile: profile name, file location (full path) and size, the time when the file was last modified, and whether or not the file is editable.

Please notice the (uml2) and the (UML2) entries under the profile in the Model Explorer. The (uml2) entry represents the imported UML 2.0 meta-model, which is the one being extended by the profile. The (UML2) entry represents imported UML2 Types model library. That is optional; the profile author does not have to import it.

Note: Theoretically, UML profiles could extend various meta-models, although the RSM and RSA implementation supports only the UML 2.0 meta-model.

The profile's properties (see Figure 3) are displayed in the Properties view when the profile entry (the item right below the profile file in the Model Explorer) is selected. Version- and Release-related properties are explained later (in the Change management section--see below). The Visibility property does not have any impact on your ability to apply the profile.

Figure 3. Profile properties
Profile properties
Profile properties

To add UML elements to the profile, select it in the Model Explorer, right-click it and click Add UML, as shown in Figure 4. The only UML types that can be created in a profile are Stereotypes, Classes, and Enumerations.

Figure 4. Add UML menu for profiles
Add UML menu for profiles
Add UML menu for profiles


The names of certain element types (Stereotype, Class, Enumeration, and Attribute) have to be valid Java™ identifiers. The most common violation of this rule is using the space character in the name. Depending on the exact profile structure, invalid names can cause various problems. The most serious problem is caused by invalid attribute names, which can corrupt the model where the profile is applied. With version 6.0 iFix002 and later, model corruption is prevented and in version 6.0.1 the tool does not allow invalid names to be entered in the first place.

Version has problems with Enumeration Literals whose names are not a valid Java identifier: basically, those literals cannot be used. The versions prior to (GA/iFix002/iFix003) and after (6.0.1) do not have such problems with the literals.


To create a stereotype, select the profile in the Model Explorer and right-click it, then click Add UML -> Stereotype on the context menu. This results in the view shown in Figure 5.

Figure 5. Stereotype properties
Stereotype properties
Stereotype properties

A stereotype can be used simply to mark up the element to which it is applied. However, its real power is in the extension mechanism, through which it can actually modify the metaclass definition of one or more metaclasses. This extension is not automatically propagated to all instances of the metaclass (metaclasses); the stereotype first has to be applied to the modeling element that is an instance of the particular metaclass. Of course, you can make the extension required, in which case it is automatic -- for the model where the profile is applied.

Abstract stereotypes cannot be applied to modeling elements. The abstract stereotype can be specialized by another stereotype (more on this in the Generalization section).

The Leaf and Visibility fields are mostly ignored. Stereotypes marked as Leaf -- or with Visibility values other than the default (public) -- do not exercise any special behavior, although the stereotypes with the protected or package visibility are reported as errors when the profile is validated. You are discouraged from changing the default values for these two fields, since it is very likely that some sort of behavior will be associated with them in subsequent releases.

The Icon and Shape Image fields are covered in the Presentation subsection, and the Category field is covered in the Stereotype attributes subsection.

The metaclasses being extended by the stereotype are specified on the Extensions tab in the Properties view. The Metaclass Extensions table lists all existing extensions for the stereotype, as shown in Figure 6.

Figure 6. Metaclass Extensions
Metaclass Extensions
Metaclass Extensions

You can add a new extension by clicking the Add Extension button, which starts the Create Metaclass Extension dialog shown in Figure 7. The metaclasses available for extension are those defined by the UML 2.0 meta-model. Each extension can be marked as required or not (not required is the default). That flag can be set only when the extension is created. If it has to be changed, you must first remove the old extension and then create a new one.

When an extension is required it means that the stereotype will be applied automatically to all modeling elements that are instances of that metaclass, given that the profile owning the stereotype is applied to the model. If the extension is not required then the stereotype has to be applied to the element either through a user gesture or programmatically.

Figure 7. Create Metaclass Extension dialog
Create Metaclass Extension dialog

An attribute with a name in the base$<metaclass name> format is created in the stereotype for each metaclass that the stereotype extends. Those attributes are used by the system and should not be modified.

Please note that the stereotype can be applied only to the elements whose metaclass it extends. Of course, the profile (that owns the stereotype) itself has to be applied to the element's package hierarchy (most likely to the model itself) first.

The main aspects in which a stereotype can modify the metaclass definition are:

  • Presentation
  • Additional properties
  • Additional constraints

Each of these is discussed in a separate section.


When a stereotype is applied to a modeling element it can affect its presentation in multiple ways. The most obvious way is that the system now displays (by default) the stereotype name in guillemets in the front of the element's name, where appropriate (for example, in Model Explorer or on diagrams). For example, if a stereotype S is applied to the element E, the system will display <<S>> E in Model Explorer and on diagrams for that element.

Note: The tool does not automatically make the first character of the stereotype name lower-case for display purposes, as suggested by the UML 2.0 specification (see the Related topics section). The name is displayed as is. However, the profile author can fully control the display name -- separately from the name -- using the localization mechanism (more on this in the Localization section).

A stereotype can have an icon and a shape image attached to it -- please see the General tab in the Properties view for stereotypes. Next to the Icon and Shape Image field on the General tab are two buttons: Browse and Clear. The Browse button lets you find an image file in the file system to be associated with the stereotype. The Clear button removes the specified image from the stereotype. Supported formats are BMP, GIF, JPG, and PNG for both Icon and Shape Image fields. Shape Image additionally supports files in the SVG format. Of course, neither image has to be specified -- it is entirely up to the profile author.

When a stereotype is applied to an element, the system will consult the preference settings to determine how to present the element. To invoke the preferences, click Window -> Preferences.

For Model Explorer, click Modeling -> Views. The Stereotype Style combo box in the Model Explorer settings group offers the following choices: None, Text and Decoration. None tells Model Explorer to ignore the applied stereotypes. Text means that all applied stereotypes will be listed in the guillemets in the front of the element’s name. Decoration tells Model Explorer to use the image from the Icon field of the applied stereotype. If none of the applied stereotypes has a defined icon, it defaults back to display stereotype names. Please note that if multiple applied stereotypes have defined icons, only one of them will be used.

Diagrams settings can be found in two places: by clicking Modeling -> Connectors for connectors and Modeling -> Shapes for shapes. The Stereotype style combo-box for connectors has only two options: None and Text. The shapes provide more choices: None, Text, Decoration, Decoration and Text, and Shape Image. Decoration displays the icon next to the element name -- the same as for Model Explorer, only one icon is used even when multiple applied stereotypes provide an icon. The difference is that it does not default back to stereotype name if there is no icon. Decoration and Text displays both the icon and the stereotype names, while the Shape Image option replaces the whole shape with the image specified in the stereotype.

Another interesting presentation feature for stereotypes is the Suppressed flag (found on the General tab in the Properties view). When set, it turns off the presentation capabilities of the stereotype: even if the stereotype is applied to an element neither the Model Explorer nor diagrams display any information about it. This is most useful when the intent is to use the stereotypes programmatically, to hold information or mark up elements but not to change the element’s presentation. The suppressed stereotypes can still be seen as applied in the Properties View’s Stereotypes tab for the element, unless even that is turned off through the preference settings (Window -> Preferences -> Modeling -> Views -> Properties View settings -> Show suppressed properties). The suppressed stereotypes can be applied only programmatically (they do not show up on the list of the applicable stereotypes), but they can be removed manually.

The version 6.0 iFix002 introduced an exception to this rule: suppressed stereotypes with the taggedValueSet keyword can be applied manually as well. This keyword can be set by selecting the stereotype in the Model Explorer and then going to the Stereotypes tab in the Properties view.

Stereotype attributes

Stereotype owned attributes are added to the metaclass definition as its properties, for the element instance where the stereotype is applied. For example, let's say that there is a stereotype S which extends the metaclass Actor and has an attribute named attr1. When this stereotype is applied to an actor in a model, the actor's set of properties will now include attr1 (in addition to all properties specified in the Actor metaclass, like name, visibility, and so on.)

To create a stereotype attribute, select the stereotype in Model Explorer, right-click it and click Add UML -> Attribute, as shown in Figure 8.

Figure 8. Attribute properties
Attribute properties
Attribute properties

The most important properties for an attribute (in addition to the name) are Type, Default Value, Multiplicity, and Unique.

Since the stereotype-owned attributes eventually become extended metaclass properties, their type cannot be just anything -- it has to be a type recognized by the system, for which it can provide proper handling of these properties. Supported types are:

  • Primitive types from the imported model libraries
  • Enumerations defined in the profile itself
  • Classes defined in the profile itself

Attribute must have a type. If it is not specified, the tool will ignore that attribute when determining the stereotype-contributed properties for the element where the stereotype is applied.

The default value does not have to be specified -- in that case the tool will use its own default depending on the type. For example, the default for a String typed attribute is blank string.

The multiplicity indicates if the property will be treated as a singular value or a collection (multiplicity greater than 1). When the multiplicity indicates a collection, the user should also pay attention to the Unique field to indicate if the elements in the collection have to be unique or not. By default, this flag is set to require uniqueness.

Note: The multiplicity cannot be set in RSA versions GA/iFix002/iFix003 using the General tab (even though the field is visible there) -- you are forced to use the Advanced tab. This is not the case in RSA versions and 6.0.1, nor in RSM.

The stereotype-contributed properties are displayed in the Properties view for the element to which the stereotype is applied, together with other properties. They can be found in two places: the Advanced tab and the Stereotypes tab (the Stereotype Properties table). In either case they are grouped together under the category named the same as the stereotype contributing the properties. You can override that rule: there is the Category field on the stereotype's General tab. If that value is specified then it will be used to group that stereotype's properties together instead of the stereotype name. An example when this is useful is when all stereotypes coming from the same profile need to group properties together under the same category.

Model libraries

Profiles support only 3 predefined model libraries: UML2 Types, Java Types, and Ecore Types. In order to use the types defined in one of those libraries, the library first has to be imported into the profile. The libraries can be imported when the profile is created through the New Profile wizard (by default it sets UML2 Types to be imported, but you can change that). They can also be imported at any other point by using the context menu in Model Explorer. Just select the profile and right-click it, then click Import Model Libraries.

The UML2 Types model library contains the 4 primitive types defined by the UML 2.0 specification (again, see the Related topics section for more information on UML 2.0): Boolean, String, Integer, and Unlimited Natural. The Java Types model library defines primitive types corresponding to the Java language primitive types, and the Ecore Types model library defines primitive types corresponding to the Eclipse's EMF types.

UML2 and Java types are fully supported. The Ecore types are partially supported: they can all be specified, and the tool will provide read capability for all of them. However, it supports editing capability only for the types that have a direct Java type representation. For example, the tool provides editing capability for attributes whose type is EByte, but only the read capability for those whose type is ETreeIterator. It is envisioned that such types (like ETreeIterator) will be used only in conjunction with some sort of programmatic manipulation of the profile at the runtime.

Figure 9. Selecting attribute type
Selecting attribute type
Selecting attribute type


Enumerations can be used to specify the type of stereotype attributes only if they are defined in the same profile as the stereotype itself. The values for attributes whose type is an enumeration would be enumeration literals owned by that enumeration.

The profile-owned enumerations are not generally available outside of the profile itself.


Classes can be used to specify the type of stereotype attributes only if they are defined in the same profile as the stereotype itself. Any such class can (and should) have attributes of its own. The rules for those attributes (in terms of supported types and default values) are the same as for the stereotype attributes.

The tool only partially supports stereotype attributes of a class type. Such attributes can be specified, and the tool offers the read capability. However, it does not provide any UI to manipulate such properties. So, typing stereotype attributes with a class type is useful only in conjunction with some sort of programmatic manipulation of the profile at runtime.

The default value of an attribute typed as a class is null or empty collection (when the multiplicity is greater than 1).

The profile-owned classes are not generally available outside of the profile itself.


A stereotype can specialize or generalize only another stereotype: a class cannot participate in the generalization relationship with the stereotype. The tool will let you specify generalization between the stereotype and a class but the validation of the profile will fail.

To specify a generalization relationship between the two stereotypes, select the stereotype that you wish to be the specialization in the Model Explorer and go to the Advanced tab in the Properties View. Select the Collections property and click the … button in the value field, as shown in Figure 10.

Figure 10. Stereotype collections property
Stereotype collections property
Stereotype collections property

This launches the Properties dialog. Select the Generalization collection and in the top right corner select the insert tool (the Generalization icon), as shown in Figure 11. Select the other stereotype and click OK.

Figure 11. Generalization collection
Generalization collection
Generalization collection

Profile constraints

In a profile only stereotypes can own constraints. To create a constraint, select the stereotype in the Model Explorer, right-click it, and click Add UML -> Constraint. The constraint can be named, but it does not have to be. It is a good idea to provide the name, though, since the name could be used in reporting the constraint failure by the tool.

It extends the meta-model to constrain the model where the stereotype is applied. The system automatically extends the meta-model if the specified language is supported. If the language is not supported, the constraint is ignored by the tool.

The constraint is defined in the profile but evaluated in the model, where the stereotype (that owns it) is applied.

The properties on the General tab (in the Properties view) are Name, Language, and Body, as shown in Figure 12. The two system-supported languages are OCL (Object Constraint Language) and Java. The content of the Body field depends on the specified language.

The Java-based constraints should yield better performance, might be easier to use to express complex constraints, and offer greater flexibility. On the other hand, the Java-based constraints work only with the plug-in deployed profiles (please see the Deployment section) and are more time-consuming for initial tests performed by you.

Figure 12. General constraint properties
General constraint properties
General constraint properties

Important properties on the Advanced tab (in the Properties view shown in Figure 13) are Evaluation Mode, Message Key and Severity. They are grouped under the Metamodel Constraint category.

The Evaluation Mode value could be either Batch (evaluated only on demand when you invoke the validation action) or Live (evaluated both when the change occurs and on demand). The default is Batch.

The Message Key is used to for display purposes when the constraint fails. If it is not specified, the system uses the fully qualified constraint name. If it is specified, the system looks it up in the corresponding properties file if there is one (more on this in the Localization section). If no properties file is found, the key itself is used. The single quote in the message must be escaped with another single quote.

The Severity could be Error, Warning, and Informational. The exact behavior for each of those values would depend on your preference settings. However, if a Live constraint with the Error severity is violated, the change is automatically rolled back.

Figure 13. Advanced constraint properties
Advanced constraint properties
Advanced constraint properties

Built-in OCL support

Note: This article does not attempt to clarify or explain OCL. The readers of this section should be familiar with the OCL specification (see Related topics).

The supported version of the OCL is 2.0, matching the supported UML definition (2.0).

The OCL statement is entered in the Body field of the constraint's General tab in the Properties view.

The union of the user modeled stereotype and intersection of its meta-model extensions is used as the OCL context when the constraint is defined.

For example:

  • Stereotype S1 has two attributes (a1: Integer, and a2 : Boolean), extends Class and Actor metaclasses, and has constraint profileCons1.
  • OCL statement in the profileCons1 constraint would have access to properties a1 and a2 and intersection of features defined in metaclasses Class and Actor.
  • The intersection of features defined in all extended metaclasses is used instead of the union to ensure that the constraint is syntactically valid, regardless of the element where the stereotype will be applied. The tool does not allow Class-specific features to be used in the constraint because the constraint would not be syntactically valid when the stereotype is applied to an Actor, and the other way around.

The element with the constraint's stereotype applied to it is used as the OCL context during the evaluation of the constraint.

For example:

  • Actor A1 has stereotype S1 applied to it.
  • The constraint profileCons1 is evaluated depending on the evaluation mode settings. At that time, actor A1 is used as the OCL context in the meta-model mode.

The UI provides syntax highlighting, content assist, and syntax parsing.

The constraint is evaluated during model validation in the model where the stereotype is applied. It is checked only for syntactical validity when the profile itself is validated.

If the constraint has a message associated with it (through the Message Id), the {0} variable in the message is substituted by the context element -- unless it is between single quotes.

Built-in Java support

The user can specify the Java class in the Body field of the constraint's General tab in the Properties view.

The Java class has to be specified using its fully qualified name. It has to extend the class. Both profile and the Java class have to be deployed through the same plug-in (more on this in the Deployment section).

The element with the constraint's stereotype applied to it is used as the constraint context during evaluation of the constraint.

The constraint is evaluated during model validation in the model where the stereotype is applied. It is not checked when the profile itself is validated.

If the constraint has a message associated with it (through the Message Id), it can be obtained from the IValidationContext object that is passed to the constraint by the system. The constraint can then deal with any number of the {n} variables in the message using standard Java message formatting.

Using UML profiles

The intent of this section is to provide a short overview of using UML profiles, so that you can quickly start testing the new profile. More advanced topics are covered later in other sections.

Applying profiles

Before the content of a profile (for all practical purposes, that means stereotypes) can be used in a model, the profile itself has to be applied to the model. To be precise, the profile can be applied to any package in the model, including the model itself. When the profile is applied to the model itself, it is visible in the whole model. If it is applied to some package in the model, then it is visible only in that package's sub-tree. It is usually easier to manage if the profile is applied to the model, but it is entirely up to you.

To apply a profile, select the model (package) in Model Explorer or on a diagram (if it is present there) and navigate to the Profiles tab in the Properties view, as shown in Figure 14.

Figure 14. Profiles tab
 Profiles tab
Profiles tab

The Applied Profiles table lists all the profiles that have already been applied. Don't worry too much about the Version and Release Label columns for now, those concepts are covered later on in the Change management section.

To unapply (remove) a profile, select the profile and click the Remove Profile button.

Note: Not all profiles can be removed. There are certain profiles that are required by the system and the user cannot remove them. Three of those are Basic, Intermediate and Complete. These profiles are defined by the UML 2.0 specification. The other two (Default and Deployment) are defined by RSM and RSA.

To apply (add) a new profile, simply click Add Profile, which will lunch the Select Profile dialog shown in Figure 15.

Figure 15. Select Profile dialog
 Select Profile dialog
Select Profile dialog

You can either choose one of the available (system-known) deployed profiles, or browse the file system to select a profile. More details on deploying profiles can be found later in the Deployment section. For now, the simplest way to start is to select the File option and then browse the file system to find the profile in the workspace.

Applying stereotypes

To apply a stereotype, select the modeling element in Model Explorer or on a diagram, and navigate to the Stereotypes tab in the Properties View, as shown in Figure 16.

Figure 16. Stereotypes tab
Stereotypes tab
Stereotypes tab

The Applied Stereotypes table lists all of the stereotypes that have already been applied. The Stereotype Properties table lists the element’s properties that are contributed by those stereotypes.

To unapply (remove) a stereotype, select the stereotype (s) and click the Remove Stereotypes button. If the stereotype is required (as indicated by the Required column) then it cannot be removed. To apply (add) a new stereotype, simply click Add Stereotypes, which will launch the Apply Stereotypes dialog shown in Figure 17.

Figure 17. Apply Stereotypes dialog
Apply Stereotypes dialog

The list in the dialog contains all applicable stereotypes for that element that are not already applied.

Change management

It is important to understand the change management aspects of working with profiles. When an older version of a profile is applied to a model, for instance, the migration process (to the newer version) uses the versioning mechanism built into the profile itself. That mechanism is completely independent of whatever source control system is being used. Of course, the existence of a source control system introduces even more complexity when you merge two versions of the profile, or two versions of a model using two different versions of the profile.

Profile versioning

Each profile file contains one or more versions of the profile. A new version is created every time the profile is saved, and older versions are not removed. It may help for you to imagine that a version is a runtime component of the profile, with links to its UML definition. When the profile is applied to a model, it is really the latest version (the runtime component) that is linked with the model. The profile’s UML definition is linked to the model indirectly through the version.

Only the latest version completely and accurately reflects the UML definition of the profile. All other versions only hold enough information to enable the smooth transition of a model -- with that version applied to it -- to the newest version of the profile. And that is assuming there were no incompatible changes made between the versions (more on this topic in the Compatibility rules section).

To see the current (latest) version number of the profile, select it in the Model Explorer and navigate to the General tab in the Properties View. It has a read-only Version field.

To compare it with the version that is actually applied to the model, select the model in the Model Explorer and navigate to the Profiles tab in the Properties View. One of the rows will represent the profile of interest (if it is actually applied), and there is a Version column in the table.

Releasing a profile

Releasing a profile creates a special version of the profile. It is invoked through the context menu shown in Figure 18: select the profile in the Model Explorer, right-click it and click Release. This launches the Release Profile dialog (Figure 19), where you can specify the release label that will be associated with the released version. The release label is completely arbitrary: it is any string you wish to enter.

Figure 18. Releasing a profile
Releasing a profile
Releasing a profile
Figure 19. Release Profile dialog
Release Profile dialog
Release Profile dialog

Figure 20 shows how all released versions of the profile are listed in the Releases field on the General tab in the Properties View.

Figure 20. Released profile
Released profile
Released profile

If the most recent version is released, then the Release Label field displays the label associated with it. If the profile has not ever been released, or if it has been modified since the last release, then the Release Label field will indicate that.

In addition to creating a new profile version (and marking it with the release label), all non-released versions are removed. Consequently, non-released versions of the profile should be applied only to test models. The models with intermediate profile versions applied will be able to migrate to the released version, but they will lose data: applied stereotypes and values of stereotype contributed properties.

Releasing a profile also establishes a check-point: the tool will enforce compatibility rules when you make changes to a profile that has been released.

Compatibility rules

Certain changes made to the profile result in the loss of data during profile migration. The following actions will cause compatibility problems:

  • Rename an element that existed in the previous version
  • Delete an element that existed in the previous version
  • Change the type of a Stereotype or Class attribute that existed in the previous version

The tool prevents you from making such changes, but only in regard to released versions.

For example, let's say that you create a profile with one stereotype (S1) and then release it. You then add another stereotype (S2) to the profile. The tool would let you delete (or rename) S2 but not S1.

The compatibility rules are implemented through a live constraint: from the Preferences -> Window menu, click Modeling -> Validation -> Constraints. Next, click either UML 2.0 -> Modeling -> Profiles or UML 2.0 -> Model Quality Dimensions -> Compatibility. Finally, select the Profile Compatibility Restrictions constraint.

If you must make a change that would be incompatible with a released version, for whatever reason, then there is a back door of temporarily disabling this constraint. Of course, it is strongly recommended not to go this route, but in case it is absolutely necessary the back door is there. However, be warned that in this case it is most likely that there will be data loss during profile migration.


Migration upgrades the applied profile version in the model. It upgrades the model’s links, from the version that was previously applied to it, to the newest version of the profile. The applied stereotypes and values for stereotype-contributed properties are migrated to conform to the new UML definition of the profile.

If there were incompatible changes between the versions, some of the data will be lost. For example, if a stereotype (that has been applied to some elements in the model) has been deleted from the model, then all of those stereotype applications will be lost too. The same will happen to all properties that the stereotype has contributed.

If the profile file does not contain the version that was previously applied to the model at all, then only the link to the applied profile version is updated. All applied stereotypes and values of stereotype-contributed properties are lost.

Auto migration

Automatic migration happens when a model is opened -- as shown in Figure 21, if the system detects that an older version of the profile is applied, it will prompt you to perform the migration. Of course, you may decline.

Figure 21. Profile migration warning
Profile migration warning
Profile migration warning

However, if the profile file does not have the previously applied version anymore, another dialog will precede the Profile Migration warning: the Unrecognized Schema error dialog shown in Figure 22.

Figure 22. Unrecognized Schema error
Unrecognized Schema error
Unrecognized Schema error

The most likely reason that a profile file would not contain the version is that you have either released or compressed the profile (more on those concepts in separate sections), and the old version was an intermediate version. The cause of the warning is that the profile extends the meta-model and the tool does not know how to treat certain data in the model file, since the schema defining them is missing.

The tool is not even aware that the cause is a missing profile version at this point. If you choose to ignore the unrecognized content, the model will be opened in a special mode. At this point, if the warning was caused by a missing profile version, the system will offer the profile migration. Please note that the regular migration rules still apply; since the profile file does not contain the old version, the applied stereotypes (and the values of properties contributed by them) will be lost.

Another cause of this warning might be that the profile is missing altogether. In that case, even if you open the model by ignoring the unrecognized content, the tool will simply inform you that a particular profile is missing: there will be no way to migrate.

In either case, when a model with unrecognized content is opened in the special mode and the changes are made to it, you are prompted to discard or keep this information during the save operation, as shown in Figure 23.

Figure 23. Saving a model with unrecognized content
Saving a model with unrecognized content
Saving a model with unrecognized content

Both the behavior of opening and saving the model with unrecognized content can be personalized through the preference settings (click Window -> Preferences, then navigate to the Modeling page). Your options are Always, Never, and Prompt. The default behavior is to prompt.

Manual migration

You can manually migrate at any time from the Properties view (for the selected package). To perform the migration, select the package (model) to which the profile is applied in the Model Explorer and navigate to the Profiles tab in the Properties view, as shown in Figure 24.

The table lists all applied profiles, and any profile that is out of sync is clearly marked as such. The Migrate Profile button is used to perform actual migration.

Figure 24. Manual profile migration
Manual profile migration
Manual profile migration

Compressing a profile

It is possible to purge intermediate (non-released) versions without releasing the profile. To do so, select the profile in the Model Explorer, right-click it and click Compress. It will delete all non-released versions except the last one. If the profile is dirty, then it will first create a non-released version, then save it and keep both the version it created as well as the last non-released version before that one.

This action is useful when there is a prolonged development of the profile. Since a new version is created every time the profile is saved, its size can grow quickly, which can significantly affect performance both in terms of memory usage and speed.

The Compress menu item has been introduced in the 6.0.1 version of RSM and RSA.


There are two ways to deploy profiles: file system-based deployment and plug-in deployment. In either case, it is highly recommended to have a path-map pointing to the location of the profile. Although not mandatory, it is certainly the easiest way to manage the deployment. If you don't use a path-map, then the system will store a file path (relative, if possible) in the model file where the profile is applied. That might be OK in some cases, but definitely leads to problems when the models and profiles are shared, especially if the profile location is not fixed.

Also, it is highly recommended to keep profiles in a different location from the models where they are applied – although it is not forbidden that they share a location. In some cases the tool will store a fully qualified path (prior to the 6.0.1 version) or a relative path (6.0.1 and later) in models to reference such profiles, even if there is a path-map defined for that location.

File system deployment

The profile can be deployed anywhere on the file system: it does not necessarily have to be in the workspace. Of course, you have to keep profiles in your workspace for authoring.

However, it is highly recommended that the location containing the profiles is pointed to by a path-map. To create a path-map, click Window -> Preferences, then click Modeling -> Path Maps. The result is shown in Figure 25.

Note: This list displays only user-defined path maps; it does not display tool-defined path maps.

Figure 25. Path maps
Path maps
Path maps

Click the New button to create a new path-map, opening the dialog shown in Figure 26. Again, the name is arbitrary – it is up to you to determine the naming convention. The location (folder) should point to the folder that will contain the profile.

Figure 26. New Path Map dialog
New Path Map dialog
New Path Map dialog

If the model and the applied profiles are shared, then the same path-map has to be created on every system where they are used. The tool will not enforce the existence or validity of the path map: it is up to your particular team to ensure that the path maps exist and point to valid locations. If the path map does not exist or is not valid, the model simply will not open properly since the tool will be unable to find the applied profile (please see the Change management section for details).

Please note that the profile author cannot ensure path map usage -- it is really the profile user who has to set it up.

Plug-in deployment

Profiles can be deployed through plug-ins. The plug-in mechanism gives more control to the profile author, and simplifies the job of using and maintaining the profile for the profile user. On the other hand, it does require a bit more work and knowledge from the profile author. Basically, the profile is stored in a plug-in and registered through its plugin.xml file. The plug-in is then distributed to the profile users, who must install it in their IDE (integrated development environment) -- or in the runtime environment -- depending on where they need to use the profile or plug-in.

Profiles deployed this way are managed by the system. That means that you do not have to browse for the profile in the file system, but rather select it from the drop-down list (Deployed Profile) when applying profiles. The profile author has an option to prevent the profile from showing up in this list (more on this later).

Another useful feature is that the profile author can define the path map in the plugin.xml file as well. That way the profile user does not have to worry about profile locations and path-maps either.

The profiles deployed through this plug-in mechanism can also use Java as the language for profile constraints.

The complexity of the plug-in holding the profile really depends on the profile author and the actual design. The author might create the plug-in with the sole purpose of deploying the profile, or the profile could be added to an existing plug-in where it will be just on of many artifacts. There could be code accompanying the profile, providing runtime manipulation of models where the profile is applied (again, if required).


The actual physical location where the profile is stored in the plug-in is not dictated by the tool; it is up to you to determine the directory structure that is the best for the particular plug-in. The profile can be stored as high as the root directory of the plug-in or in any subfolder. There can be one or many profiles. The folder can also contain files and folders other than profiles.

That being said, the tool uses the convention that tool-created profiles are stored in the profiles subfolder of the plug-in's root. This is recommended for the user-created profiles as well.

Note:This is a convention only. It is not required nor enforced. There is only one exception to this related to the localization in the 6.0 GA version (more on this in the Localization section).

The profile file should be included in the binary build, which is set in the file. You can set it manually in that file or through the Plug-in editor (using the Plug-in editor is covered in a separate section). You can either specify each profile separately or simply include the whole folder containing the profiles.

Here is an example of the content of the file (it assumes that the profiles are in the profiles folder):

bin.includes = plugin.xml,\,\
       <some file>,\
       <some file>

The row defining the profile location is in bold font.


The plug-in hosting the profile will need dependencies to the and plug-ins. If the profile is going to use Java-based constraints, it will also need a dependency to the plug-in.

Registering a path map

Regardless of the location in the plug-in where the profile is stored, there should be a path map defined for that location. The path map can be registered through the plugin.xml file of the plug-in.

Here is an example:


The extension point is The extension's id and name are up to you. The pathmap element has two attributes: name and path. The name is going to be referenced elsewhere and should be unique. It should also indicate the owner and intent. The path is a relative path starting at the root of the plug-in.

The plugin.xml file can also define a path map pointing to a location in another plug-in. In that case, the pathmap element has another attribute: plugin. The value of the plugin attribute is the name of the referenced plug-in, without the version information. Here is an example:


Registering a profile

The profile itself is also registered through the plugin.xml file. Here is an example using the path map MY_SAMPLE_PROFILES from the previous section, and 3 profiles (MyProfileA, MyProfileB, and MyProfileC) deployed in the profiles subfolder of the plug-in:






The extension point is The extension's id and name are up to you. The UMLProfile element has following attributes: id, name, path, required, and visible.

The id should be unique to ensure that the profile registration can be found programmatically. One could use a Java package convention for that or something like <plug-in name>.<profile name>.

The name of the profile will be used for display purposes. For example, it is used in the list of deployed profiles when applying profiles. The value is used as is unless it is preceded with a percentage sign (%). The percentage sign indicates that the name is localized and will be retrieved from the file, using the remainder of the value as the key in the properties file (the standard Eclipse behavior for providing localized strings in the plugin.xml -- read more about Eclipse in the Related topics section). So, in this example the name for MyProfileB is defined in the plugin.xml (MyProfileB) while the names for MyProfileA and MyProfileC are defined in the file using the specified keys ( and, respectively).

You can specify the path in a number of different formats but it is strongly recommended to use the path map format. In this example, all 3 profiles use path maps, although it might not seem so at first glance. The paths for MyProfileA and MyProfileB are specified relative to the plug-in's root (profiles/MyProfileA.epx and profiles/MyProfileB.epx). However, the folder profiles are covered by the MY_SAMPLE_PROFILES path map, so the tool will automatically use the path map. The registration for MyProfileC is even more explicit: it states the path map directly (pathmap://MY_SAMPLE_PROFILES/MyProfileC.epx).

The required flag should not be used. If it is specified, the value should be set to false (which is the default anyway). There might be some extreme use cases where the use of this flag is absolutely necessary, but it should be done with extreme caution. Basically, if it is set to true, this flag tells the tool to apply that profile automatically to any model that does not have it already applied.

The visible flag indicates to the tool whether or not the profile should be offered in the list of deployed profiles when applying profiles. The default is false. The value obviously depends on the intent: if the profile should be applied only programmatically, then the value should be false, otherwise it should be true.

Using the New Plug-in Project wizard and Plug-in editor

The New Plug-in Project wizard and the Plug-in editor are Eclipse concepts, so for more details on this topic please see the Related topics section. The only profile-specific information is the exact extensions for registering path maps and profiles, as described in the previous sections. However, for the sake of completeness, this section will provide a brief overview of how to create a plug-in project using a wizard, and then how to modify the plugin.xml file using the Plug-in editor.

To invoke the New Plug-in Project wizard click File -> New -> Project and then select the Plug-in Project in the Plug-in Development group, as shown in Figure 27.

Note: To use the plug-in development capabilities, the Eclipse Plug-in Development capability has to be enabled. To do so, click Window -> Preferences, then click Workbench -> Capabilities, then click Eclipse Developer and select the Eclipse Plug-in Development capability.

Figure 27. New project
New project
New project

The values for the fields in the wizard (Figure 28) depend on the intended functionality of the project. For example, if it is simply going to hold the profile, then you probably do not need Java support. If there is going to be some programmatic manipulation -- or if it is a plug-in that will have more artifacts than just profiles -- then you might need to create the Java project. It is up to you to determine the settings at this point.

Figure 28. New Plug-in Project wizard
New Plug-in Project wizard
New Plug-in Project wizard

The next step is to create a folder in the plug-in to hold profile(s). If the naming convention is used, it would be the profiles folder of the plug-in's root directory. Of course, the next logical step is to either create the profile at that location or -- if the profile already exists in another project -- copy and move it.

To register a path map and the profile in the plugin.xml you need to launch the Plug-in editor. Simply double-click on the plugin.xml file and the editor will be started, as shown in Figure 29.

Note: While you will do most of the work with the profile in the Modeling perspective, the modification of the plugin.xml file is easier done through some other perspectives, like Resource and Java perspective. Of course, nothing stops you from opening the proper view (for example, the Navigator view from the Basic category) in the Modeling perspective and using it to navigate to the plugin.xml file (Model Explorer does not display those files).

Figure 29. Navigator and the Plug-in editor
Navigator and the Plug-in editor
Navigator and the Plug-in editor

To work in the text mode, simply go to the plugin.xmland the tabs of the Plug-in editor. The syntax is the same as used in examples from the previous few sections. However, you may wish to take advantage of the more advanced features of the Plug-in editor.

The dependencies can be specified on the Dependencies tab shown in Figure 30, and in the Plug-In Selection window in Figure 31.

Figure 30. Dependencies tab
Dependencies tab
Dependencies tab
Figure 31. Select plug-in for dependency
Select plug-in for dependency

You can register the path map and the profile through the Extensions tab.

Figure 32. Extensions tab
Extensions tab
Extensions tab

Also, make sure on the Build tab (Figure 33) that the folder containing the profile is included in the binary build.

Figure 33. Build tab
Build tab
Build tab

Once the plug-in is ready for deployment, the you can export it using Eclipse's plug-in exporter. To invoke the exporter shown in Figure 34, select the desired plug-in(s) in the Navigator view, then click File -> Export. Select the Deployable plug-ins and fragments entry from the list.

Figure 34. Export plug-in wizard
Export plug-in wizard
Export plug-in wizard

Of course, the plug-in could be part of a bigger application that has its own way of packaging plug-ins.

Open-source UML2 format

RSM and RSA also support the open-source UML2 format to a certain degree. The profiles in the uml2 format (the file naming convention is <profile name>.profile.uml2) can be directly applied to models in RSM and RSA (*.emx). Both file system deployment and plug-in deployment could be used. RSM and RSA also provide export and import functionality to and from the uml2 format.

For more details on the open source UML2 format please see the Related topics section.


To invoke the Export wizard, click File -> Export -> UML2 Model. The wizard -- shown in Figure 35 -- will create a *.profile.uml2 file in the specified location.

Note: The file will have the IDs regenerated. That is, the wizard cannot be used if you plan to maintain the RSM or RSA version (*.epx), make changes there, and re-export it on a regular basis. In this case, the exported file will always have different IDs, so the models where it is applied would not migrate correctly. The wizard is more of a one-time operation, which you would use if you intend to convert your model to the UML2 format (from the .epx) and then continue maintenance in that format.

Figure 35. Export wizard
Export wizard
Export wizard


The import functionality is very similar to the export – it just works in the opposite direction. To invoke the Import wizard, click File -> Import -> UML2 Model. The wizard will create a *.profile.epx file in the specified location.

Note: As with the export, do not use the Import wizard if you plan to maintain the UML2 version, make changes there, and re-import on a regular basis. Rather, use it if you intend to convert the model to the .epx format and continue maintenance in that format.


Profiles use standard Eclipse mechanism for localization purposes. To localize the profile, you need to provide the localization file(s) in the same location as the profile file itself. The naming convention for the localization file is the same as Eclipse's:

<profile file name>[_<locale>].properties

For example, if you create the profile MyProfile.epx, the name of the default localization file would be The name of the localization file in the French locale (as an example) would be

Since there are strict rules on naming various profile artifacts, you can use the localization mechanism to provide more suitable display names. Those names could be stored in the default localization file, even if there is no plan to provide actual localization.

The following strings in a profile are localizable:

  • Names of named elements (profile, stereotypes, classes, attributes, enumerations, and enumeration literals)

    Note: the constraint names are not localizable

  • Stereotype categories
  • Constraint messages

The localization file consists of the ID-value pairs, using standard Java format. The ID for the name of a named element is the fully qualified name of that element, with the :: sequences replaced by double underscores (__). Any space characters are escaped (using the \ character). The IDs for stereotype categories and constraint messages are those strings themselves.

Figure 36 presents an example.

Figure 36. Example profile structure for localization
Example profile structure for localization
Example profile structure for localization

The stereotype S1 has a category MyCategory. Its constraint has a message ID MyMsgId. Also, please notice space in the name of the enumeration literal L 1. Here is the content of a corresponding localization file:

#Profile: MyProfileA
#Fri May 27 13:03:55 EDT 2005
MyProfileA__E1__L\ 1=L 1
MyProfileA__S1=S 1
MyCategory=My Category
MyProfileA=My Profile A
MyMsgId=My Message

RSM and RSA can pre-populate the localization file. The action is invoked from the context menu when the profile is selected (the Localize menu item). The pre-populated file will have proper IDs, and the values will be the same as the actual strings.

The action does not handle constraint message IDs: they will not be included in the pre-populated file. Also, the localization file has extension *.properties and as such is not visible in the Model Explorer. To view it you have to use some other view (like Navigator).

Programmatic support

This section is intended for situations where you plan to provide some sort of (additional) programmatic manipulation in the model where the profile is applied, or even to apply the profile programmatically. It does not address programmatically creating and modifying profiles themselves; if you plan to do that, please refer to the open source documentation in the Related topics section.

RSM and RSA mostly do not publicly expose its API for profile and stereotype support. However, there are a few classes that are exposed that would make life easier when you’re authoring profiles. Of course, since the tool is based on the open source Eclipse UML2 project, the entire open source API is freely available. The open source API has its own documentation, but this section will outline the main interfaces that could be useful to you.

To perform the programmatic manipulation, you have to deploy the code through a plug-in. The simplest structure would be to deploy both the profile(s) and the code in the same plug-in. Of course, the profile should still be registered using path maps for its location.

To use these APIs the plug-in will need dependencies on various other plug-ins. Please see the Deployment section for details about how to create a plug-in dependency.

RSM and RSA Specific APIs


The UMLModeler class can be used to obtain the profile. It is provided by the plug-in.

The following example obtains the MyProfileA profile from the location specified by the MY_SAMPLE_PROFILES path-map. If the profile is not already loaded, this code forces loading (the Boolean parameter of the getResource method) – assuming that the path provided in the URI constructor is right.

import java.util.List;
import org.eclipse.emf.common.util.URI;
import org.eclipse.emf.ecore.resource.Resource;
import org.eclipse.uml2.Profile;
Profile profile;
URI uri = URI.createURI(pathmap://MY_SAMPLE_PROFILES/MyProfileA.epx);
Resource resource = UMLModeler.getEditingDomain().getResourceSet()
         .getResource(uri, true);
if (resource != null) {
    List contents = resource.getContents();
    if (contents.size() == 1 && contents.get(0) instanceof Profile) {
        profile = (Profile) contents.get(0);

Please note that the URI class is from the org.eclipse.emf.common.util package.


Profile constraints implemented as Java classes have to extend this class. It is provided by the plug-in.

The method to override is:

public IStatus validate(IValidationContext arg0)

The argument (arg0) can be used to return the status. The IValidationContext interface defines the createFailureStatus and createSuccessStatus methods.

Open Source API

For the full documentation for the open source API please see the Related topics section.

The following sections correspond to main interfaces that might be of interest when you are dealing programmatically with profiles. Each section then lists the main relevant methods. This section is not intended to be exhaustive documentation for the open source API but rather to point the reader in the right direction in the terms of needed APIs.

All of the classes listed in this chapter are provided by the org.eclipse.uml2 plug-in.


EList getAppliedProfiles();
public Set getAllAppliedProfiles();
public boolean isApplied(Profile profile);
public String getAppliedVersion(Profile profile);
public void apply(Profile profile);
public void unapply(Profile profile);


public Set getApplicableStereotypes();
public Stereotype getApplicableStereotype(String qualifiedStereotypeName);
public Set getAppliedStereotypes();
public Stereotype getAppliedStereotype(String qualifiedStereotypeName);
public String getAppliedVersion(Stereotype stereotype);
public boolean isApplied(Stereotype stereotype);
public boolean isRequired(Stereotype stereotype);
public void apply(Stereotype stereotype);
public void unapply(Stereotype stereotype);
public Object getValue(Stereotype stereotype, String propertyName);
public void setValue(Stereotype stereotype, String propertyName, Object value);


public String getVersion();
EList getOwnedStereotypes();
Stereotype getOwnedStereotype(String unqualifiedName);


public Set getAllExtendedEClasses();
public Profile getProfile();

Best Practices

The following is a list of recommended practices:

  • Avoid using special characters (like a space) in your profile. If the special characters are needed for display purposes, use localization mechanism. Version 6.0.1 prevents you from using special characters altogether anyway (except for the enumeration literals).
  • Keep profiles and models in separate locations. If possible at all, keep them on a separate change management life cycle.
  • Always use path maps, regardless of the deployment type (file system vs. plug-in based).
  • Profiles should be considered tool extensions – not modeling artifacts.
  • Keep the profile size in check. Every time you save a profile, a new version is created in the file. Opening a profile file with 10 versions does much more than opening a profile with one version or a model. The number of versions in the profile can significantly affect the performance of the application. If you are using the 6.0.1 version, use the Compress option to reduce the size of the profile. If you have some older versions, the only recourse is to release the profile from time to time, but be aware about the consequences: it creates a checkpoint that prevents certain changes, that version cannot be deleted, and so on. There are more details on this topic in the Change management section.
  • Do not apply a non-released profile to a production model. Non-released profiles should be applied only to test models to test the profile itself. Once the profile is released, all non-released versions are deleted, resulting in the loss of data in models that were applied during migration.
  • Do not give a non-released profile to your customers, unless you make it clear that such a profile can only be used for demonstration or test purposes, and that the migration to the official (released) version will result in the loss of data.
  • When developing plug-in profile, create a path map with the same name pointing to the same location in both the development (IDE) and the runtime (target) environment. Preferably, the path map would be defined as a user path map (through the Preferences) in the development environment and in the plugin.xml file of the plug-in for the runtime environment. That way, the models can be easily shared between the two environments.

Known issues

The following is a list of profile-specific known issues. It does not list other general issues in RSM and RSA although they could (and often do) affect profiles as well. For those, please consult the release notes of the particular RSM or RSA version.

  1. Naming problems. For more details, please see the Naming sub-section of the Profile Creation section.
  2. OCL constraints do not support properly defined profile enumerations.
  3. Only partial support for attributes of a class type.
  4. There could be migration problems between non-released versions.
  5. The tool prevents a profile from being applied to a package if it is already applied to one of the package’s ancestors, including the model. However, it lets the user do the opposite (that is, apply the profile to one of the package’s ancestors even if it is already applied to the package. That may lead to problems, especially when profile migration is involved.
  6. The iFix002 and iFix003 versions unload non-RSM or RSA resources under certain conditions. This behavior affects the whole application, including profiles. Examples of non-RSM or RSA resources are the UML 2.0 meta-model and various model libraries. When that happens, the only way around is to restart the application.

Final word

UML profiles enable you to extend the UML meta-model for different purposes. In essence, that means the tool's behavior is extended as well. RSM and RSA offer extensive UI to build and use profiles. They can range from simple profiles providing some additional presentation functionality to the complex profiles deployed through plug-ins and with accompanying code taking advantage of the profile's meta-model extensions.


The author wishes to thank Kenneth Hussey, Christian Damus, Daniel Leroux, Alan Yeung, Michael Hanner, and Kim Letkeman.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

ArticleTitle=Authoring UML profiles using Rational Software Architect and Rational Software Modeler