A custom navigation control can be defined for some object in a model to link one or more other objects and to navigate to these linked objects. The custom navigation control resembles the cross-model relations control, which supports navigating between elements in models of different metamodels. Custom navigation controls can only be created in the BPMN metamodel and can be used on objects in BPMN models to link to objects in models of other metamodels, but also within BPMN models. Multiple navigation controls can be created for one object.


To create a custom navigation control, follow the steps below. To illustrate the procedure, the following example is used:

A navigation control is created for BPMN tasks. The control can be used to refer and then navigate to a related system in an ArchiMate model. The systems are represented by application components. Once an application component has been linked to the task, the control will be visible:


Depending on how the navigation control is configured, the object can be linked to only one other object or to multiple objects. In case of one object, clicking the control directly navigates to the referred object. If multiple objects are linked, clicking the control will open the list of referred objects:



On this page:


Creating the navigation control

Make sure that you have opened the BPMN metamodel in the Metamodeler.

  1. In the Create  pane, click the  Profile  element , click in the Custom Profile Definition view, and type the name for the profile. The name is the profile's identifier, its internal name for Enterprise Studio. It can only contain letters, digits, and underscores. Spaces are not allowed.



  2. Select the profile, click  to open its properties window, and set the following properties.

    extends: Select default profile CustomNavigation (location: Foundations > Component > Profiles > Default Profiles).

    hidden: Set to true if the profile should not be shown on the Profiles tab of the Properties pane once the control is used. To make sure the profile including all its attributes will not be visible, make all attributes of the profile hidden (further on in this procedure). Take note that the profile name in the element is shown in italics once the profile is made hidden.

    always assigned to: Select the object type(s) on which the navigation control must be available.



  3. Add a first attribute to the profile to define the object reference(s), they are the objects to be navigated to.

     In the  Create  pane, click the  Attribute  element , click on the profile element in the view, and type a name for the referred objects. Alternatively you can use the quick-create pop-up window to add an attribute. The attribute name is the internal name (identifier) for Enterprise Studio. It can only contain letters, digits, and underscores. Spaces are not allowed.



  4. Select the newly created attribute, and set its properties. Follow one of the following procedures, depending on whether the control should support linking to only one object or to multiple.

    1. In type, select object type  MM_Object (location: Foundations > Base > Profiles > Default Profiles).

    2. Set  hidden to true if the attribute should not be shown on the Profiles tab of the Properties pane once the control is used.

      If you want to make the profile and its attributes hidden, but want to be able to play with the control settings during the preview in order to determine its final display and position, do not hide the attribute yet until you have specified the final settings for the control in the Metamodeler




    1. Add a "List" data type  to the view, and name it. The name is the data type's internal name ( identifier ) for Enterprise Studio. It can only contain letters, digits, and underscores. Spaces are not allowed.

    2. Open the data type's properties window and in element type, select object type  MM_Object (location: Foundations > Base > Profiles > Default Profiles).



    3. Open the properties window of the attribute in the profile element, and in type, select the newly created data type (location: Metamodel > Profiles > Custom Profiles).



    4. Set hidden to true if the attribute should not be shown on the Profiles tab of the Properties pane once the control is used.

      If you want to make the profile and its attributes hidden, but want to be able to play with the control settings during the preview in order to determine its final display and position, do not hide the attribute yet until you have specified the final settings for the control in the Metamodeler.



  5. Add a second attribute to the profile to specify the position of the navigation control on the element, and set the following properties.

    identifier : Enter the name  customNavigationPosition.

    type : Select object type CustomNavigationPosition   (location: Foundations > Component > Profiles > Default Profiles).

    default value : Specify the position of the control on the element. Enter  topright_outside or bottomright_outside , depending on where the control must appear.

    hidden : Set to true if the attribute should not be shown on the Profiles tab of the Properties pane once the control is used.

  6. Add a third attribute to specify the definition of the navigation control, and set the following properties.

    identifier : Enter the name  customNavigationControls.

         type : Select object type CustomNavigationControls  (location: Foundations > Component > Profiles > Default Profiles).

    default value : Specify the icon and display of the control. It is configured by the following properties. The complete specification is enclosed in  [{  }] .

    [{attrName:' ',background:{B: , G: , R: },fillOpacity: ,foreground:{B: , G: , R: },lineOpacity: ,linewidth: ,symbol:' ',title:' ',typeName:' '}]

    attrname

    The identifier name of the attribute that defines the object references of the navigation control (the attribute of type MM_Object).

    attrName:'system'

    background

    The fill color of the navigation control icon, in RGB coding. Pure black ( {R:0, G:0, B:0} ) is not possible.

    background:{B:255, G:231, R:174}

    fillOpacity

    The fill color transparency of the navigation control icon. Possible values: 1 .. 256 (1 = 0% = transparent, 256 =100% = no transparency).

    fillOpacity:256

    foreground

    The line color of the navigation control icon, in RGB coding.

    foreground:{B:0, G:0, R:0}

    lineOpacity

    The line transparency of the navigation control icon. Possible values: 1 .. 256 (1 = 0% = transparent, 256 =100% = no transparency).

    lineOpacity:256

    lineWidth

    The line width of the navigation control icon. Possible values: 1 .. N (-1 means no line).

    linewidth:15

    symbol

    The icon used to represent the navigation control. A list of icons that can be used is available via the Shape option in the Change Graphic Shape function, accessible via the context menu of an object.

    symbol:application-icon

    title

    The name that is shown after the custom navigation control is clicked to select a reference object. If you do not want to use a title, leave the property as follows: title:''. Instead, the value of property 'attrname' is used.

    title:'Related system'

    typeName

    The type of the object reference(s). The type name consists of the metamodel name followed by a colon and the name of the object type.  The type names of object types can be found in the metamodel package, in the Default concepts folder of the metamodel. Another way to find type names is via the Metamodel Browser, accessible via the Metamodel button in the Query tool window.

    typeName:'ArchiMate:ApplicationComponent'


    hidden : Set to true if the attribute should not be shown on the Profiles tab of the Properties pane once the control is used.


The navigation control is now ready and can be validated and previewed in a test model package to see if it is available in the correct place and displayed correctly.

Adding object references

Once the navigation control is available on the object in your model, you can start adding one or more object references to it.

  1. Select the object in the diagram or view, and click the navigation control.



  2. Click the plus next to the control title, select the object you want to refer to, and click OK.



  3. Optional: If the control supports adding multiple object references, the plus control is still available. Click it again to add another reference object, and repeat this until you have linked all objects you want to refer to.

Setting a preferred reference for use in HoriZZon

In HoriZZon, a custom navigation control can be used to directly navigate to the referred object. If the control only has only one referred object, clicking the control will open the properties panel of the linked object. In case a nagivation control has multiple object references attached, only one of them can be shown. Clicking the control will show the properties panel of the linked object that has been set in Enterprise Studio as the preferred reference. If no preferred reference is set, the properties panel of any of the referred objects will be opened after clicking the control.

To set a preferred reference for the navigation control, do as follows:

  • Click the navigation control on the object, and then set a checkmark next to the reference that must be the preferred reference.