It is advised that you have some experience with creating SGV files.

Custom symbols are defined in the configuration of Enterprise Studio. Introducing custom symbols means that you have to perform a manual migration of your model packages once in order to make the custom symbols available.

Once added to the configuration, custom symbols will be there permanently.


The shapes and icons used for the appearance of objects and relations in Enterprise Studio are defined in *.symbol files, called symbol definitions . The definition files are located in the configuration of Enterprise Studio. You can add custom symbols to Enterprise Studio by creating *.symbol files and then adding them to your tool configuration. After that, you need to migrate the model packages to the new configuration.


On this page:


Symbol definitions

The symbol definitions are images in the Scalable Vector Graphics (SVG) format. There is lots of information on the Web on scalable vector graphics and on how to create images in SVG. See for example https://www.w3schools.com/graphics/svg_intro.asp .

Please be aware that Enterprise Studio does not support the complete SVG standard. Please check out the overview of SVG tags, presentation attributes, and transform functions that are supported.

When creating custom symbols, try to keep your symbol definitions as simple as possible. As shapes, they need to scale well, preferably reserve space for the object name, and obey to the styling and coloring defined by Enterprise Studio or HoriZZon. As icons or relation ends, they are generally quite small on a view. So, make sure their features are still discernable on a small scale.

Naming your custom symbols

When you create custom symbols, choose their names wisely. The file name (without the .symbol extension) is directly used in Enterprise Studio to refer to the symbol. In the Change Graphic Shape window, for example, the selection list to pick a shape is populated with the symbol file names in alphabetical order. With the introduction of the Amazon Web Services (AWS) symbols in Enterprise Studio, BiZZdesign has started to employ the following naming convention for symbols:

<Collection>_<Category>_<SymbolName>.symbol

where

  • <Collection> is the name of the collection the symbol belongs to. You could use your company name or an abbreviation of it, for example.
  • <Category> is the name of the category the symbol belongs to within the collection. This is not required but may be helpful to organize your symbols if there are many.
  • <SymbolName> speaks for itself.


A few examples of file names:

AWS_Database_DynamoDB.symbol
AWS_Machine-Learning_SageMaker.symbol
AWS_Networking_NAT-Gateway.symbol


The different parts of the symbol name are separated by underscore characters _. Please note that spaces are not allowed in any part of the file name. Use dash characters instead. When you adhere to this naming scheme, it will be easier to find the symbol you are looking for when changing the graphic shape of an object, or to search for it when changing the icon in the Metamodeler.

Recommendations for shapes

When you create a symbol definition that you want to use as a shape for an object, adhere to the following recommendations.

In Enterprise Studio it is possible to change several graphical properties of object shapes, such as the fill and line colors, fill transparency, line weight and line style. When you generate a color view, Enterprise Studio also changes the fill color. To enable this for your custom symbols:

  • Do not specify a fill color for the main shape.
  • Do not specify a stroke color for the main shape.
  • Do not specify a fill-opacity for the main shape.
  • Do not specify a stroke-weight for the main shape.
  • Do not specify a stroke-dasharray for the main shape.

Some additional recommendations:

  • If possible, leave sufficient white space in the middle of your shape for Enterprise Studio to place a name label.
  • When your shape contains a large white or transparent area, place a transparent rectangle (<rect width="xxx" height="yyy" fill-opacity="0"/>) behind your shape or use an explicit white fill (fill="white" or fill="#ffffff") rather than a transparent fill (fill="none"). Otherwise, your shape is more difficult to select.
    If your symbol is meant to be used as an icon and you want the main object’s shape color to shine through, you can additionally set fill-opacity="0", so the white fill will be transparent.
  • Do not count on squares being squares and circle being circles, as the size of your shape is determined by the editor. It is likely these symmetric shapes will be stretched out.
  • Enterprise Studio will automatically reduce the width and height of your shape to the bounding box of the visible graphics. Therefore, there is no point in offsetting the x and y positions or to define a group with a larger size than its child graphics. This is also the reason why the outer <svg>…</svg> tags may be omitted.
  • Keep in mind that the default shape size is (400, 160). Design your shapes to scale well to that ratio between width and height. If that is not possible, make sure to change the default object size in your custom viewpoint definitions.
  • Tab characters are not allowed. Use spaces to format the symbol file.

Recommendations for icon symbols

When you create a symbol definition that you want to use as an icon in custom viewpoint definitions, please take note of the following:

  • Icons can be more colorful than shapes. They do not necessarily have to change color with the shape if a color view is applied. However, when omitted, Enterprise Studio will choose fitting default colors. Therefore, you are advised to stick to the above recommendations for shapes as much as possible when defining new icon symbols.
  • If the stroke color is not defined, the editor will use the object’s font color. If the fill color is not defined, the editor will make the icon transparent. So, if you do rely on a visible fill, you must explicitly set the fill attribute for symbols that are going to be used as icons. If you want to use a symbol as both icon and shape, you may need to define two separate symbols, one without a fill and one with an explicit fill color. In that case append -icon to the end of the symbol name to make clear it was designed as an icon.
  • Keep the icon symbols as simple as possible without much detail. Icons are usually quite small, so any detail will be difficult to discern.
  • The default icon size is (40, 40). Design your icons to scale well to a more or less equal ratio between width and height. If that is not possible, make sure to change the icon size in your custom viewpoint definitions. If you want to use a symbol as both icon and shape, you may need to define two separate symbols with different size ratios. In that case append -icon to the end of the symbol name to make clear it was designed as an icon.

When you have defined custom icons and you want to use them in Enterprise Studio, you need to define a custom viewpoint definition in which you set the icon for all objects of a certain type.

Examples of symbol definitions and tools for creating them

For a few examples of SVG symbol definitions that can be used for custom symbols in Enterprise Studio, please refer to Examples of SVG symbol definitions for creating custom symbols.

For creating custom symbols it can be useful to have a graphical editor or an SVG editor with visual feedback. For more information, please refer to Tools for creating symbol definitions.

Conversion of existing SVG images

Often you will start with an existing SVG image that needs to be converted to a symbol definition. In this case, you will have to apply the following conversions and simplifications:

  • Remove or replace tab characters.
  • Remove or replace gradient colors.
  • Remove explicitly set fill and stroke colors.
  • Remove or replace <text>s with explicit <path>s.
  • Remove inner paths of filled areas to reduce the image to a line drawing.
  • Insert a transparent <rect> behind a largely transparent symbol to facilitate selection.

Taking custom symbols into use

Before taking your custom symbols into use in your production environment, test the results in a test environment to make sure they are as expected.

Once you have created custom symbols, you need to add the symbol definition files to the SymbolDefinitions folder of the Enterprise Studio configuration. Do not make any changes to your default configuration. If you do not have a custom configuration yet, first make a copy of the configuration and add the files to that copy if you are working with the on-premise solution. If you are working with the hosted solution, you can contact BiZZdesign Support to get a copy of the default configuration. After you have included the symbol definition files, migrate your model packages to the new tool tool configuration once. After that the new symbols will be in the configuration permanently.

For detailed instructions, please refer to Manually upgrading the tool configuration and migrating model packages to the new configuration.