Shape Libraries

You are here:
< Back

Designer contains a rich set of pre-defined shape libraries including thousands of shapes, which can be extended and sorted as required. 

Shape libraries and shapes are supporting domain separation.

Shape Library

A – Select Shape Libraries application menu to see the shape library list.

B – Click New to create a new shape library.

C – The Image column contains a static preview of some shapes contained by the shape library. The image is not updated automatically. 

D – Only Active shape libraries are visible within the Designer canvas. 

Shape Libraries Form

The shape library form contains the relevant field to configure the shape library, including the references to the individual shapes within the library.

Shape Library Form

A – Categorize shape libraries to logically group them. The category is not used within the Designer canvas.

B – The Name of the shape library is visible in the Designer canvas and should be unique.

C – Select a ServiceNow group to make the shape library available only for a selected group of people. If the Global (G) is active, the Group (C) settings will be overwritten.

D – Short description of the content of the shape library. 

E – Static image of the shape library for preview purposes.

F – Active shape libraries are shown within the Designer canvas. Deactivate to hide it from all users. 

G – Global shape libraries are visible for all users. This option overwrites the Group (C) option. Uncheck and set a Group (C) to make the library available for a selected group of people. 

H – The order number positions the shape library amongst the other shape libraries. 

I – The related list shows all shapes as part of the library. 

Shapes Form

The shapes form is accessible via the shapes libraries form and contains the specification of an individual shape. 

Shape Form

A – The Shape Library indicated to which library the shape belongs to. 

B – The shape Name is used for display/tooltip and search within the Designer canvas. 

C – Setting the default table will associate the shape with a table while creating future state elements (CTRL+M in Designer).

D – The order number positions the shape within the shape library.  

E – Only Active shapes are visible within the shape library. 

F – The Label contains the text to be displayed within the shape. HTML code can be used for extended formatting (see table shapes).

G – Defines the default width of the shape. 

H – Defines the default height of the shape. 

I – The styling of the shape, which can be defined through formatting in Designer (CTRL+E in Designer to copy the style of a shape).

J – Check the Relationship box to indicate, that the shape is a relationship.  

K – Extended and custom SVG styling of shapes can be entered here (See Editing Stencils). 

Editing Stencils

The following nomenclature can be used to draw custom shapes. 


The outer element is <shape>, that has the following attributes:

  • name
    • string, required.
    • The stencil name that identifies the shape.
  • w” and “h
    • are optional decimal view bounds.
    • This defines your co-ordinate system for the graphics operations in the shape.
    • The default is 100,100.
  • aspect
    • optional string. Either “variable”, the default, or “fixed”.
    • Fixed means always render the shape with the aspect ratio defined by the ratio w/h.
    • Variable causes the ratio to match that of the geometry of the current vertex.
  • strokewidth
    • optional string.
    • Either an integer or the string “inherit”.
    • “inherit” indicates that the strokeWidth of the cell is only changed on scaling, not on resizing.
    • If numeric values are used, the strokeWidth of the cell is changed on both scaling and resizing and the value defines the multiple that is applied to the width.
    • Default is “1”.


If you want to define specific fixed connection points on the shape use the <connections> element. Each <constraint> element within connections defines a fixed connection point on the shape. Constraints have attributes:

  • perimeter
    • required. 1 or 0.
    • 0 sets the connection point where specified by x,y.
    • 1 Causes the position of the connection point to be extrapolated from the center of the shape, through x,y to the point of intersection with the perimeter of the shape.
  • x” and “y
    • are the position of the fixed point relative to the bounds of the shape.
    • They can be automatically adjusted if perimeter=1.
    • So, (0,0) is top left, (0.5,0.5) the center, (1,0.5) the center of the right hand edge of the bounds, etc.
    • Values may be less than 0 or greater than 1 to be positioned outside of the shape.
  • name
    • optional string. A unique identifier for the port on the shape.

<background> and <foreground>

The path of the graphics drawing is split into two elements, <foreground> and <background>. The split is to define which part any shadow applied to the shape is derived from (the background). This, generally, means the background is the line tracing of the outside of the shape, but not always.

Any stroke, fill or fillstroke of a background must be the first element of the foreground element, they must not be used within <background>. If the background is empty, this is not required.

Because the background cannot have any fill or stroke, it can contain only one <path>, <rect>, <roundrect> or <ellipse> element (or none). It can also not include <image>, <text> or <include-shape>.

Note that the state, styling and drawing in Designer stencils is very close in design to that of HTML 5 canvas. 


Rendering within the foreground and background elements has the concept of state. There are two types of operations other than state save/load, styling and drawing. The styling operations change the current state, so you can save the current state with <save/> and pull the last saved state from the state stack using <restore/>.


The elements that change colors within the current state all take a hash prefixed hex color code (“#FFEA80”).

  • <strokecolor>, this sets the color that drawing paths will be rendered in when a stroke or fillstroke command is issued. 
  • <fillcolor>, this sets the color that the inside of closed paths will be rendered in when a fill or fillstroke command is issued.
  • <fontcolor>, this sets the color that fonts are rendered in when text is drawn.
  • <alpha> defines the degree of transparency used between 1.0 for fully opaque and 0.0 for fully transparent.
  • <strokewidth> defines the integer thickness of drawing elements rendered by stroking. Use fixed=”1″ to apply the value as-is, without scaling.
  • <dashed> is “1” for dashing enabled and “0” for disabled.

When <dashed> is enabled the current dash pattern, defined by <dashpattern>, is used on strokes. dashpattern is a sequence of space separated “on, off” lengths that define what distance to paint the stroke for, then what distance to paint nothing for, repeat… The default is “3 3”. You could define a more complex pattern with “5 3 2 6”, for example. Generally, it makes sense to have an even number of elements in the dashpattern, but that’s not required.

<linejoin>, <linecap> and <miterlimit> are best explained by the Mozilla page on Canvas styling (about halfway down). The values are all the same except we use “flat” for linecap, instead of Canvas’ “butt”.

For font styling there are:

  • <fontsize>, an integer,
  • <fontstyle>, an ORed bit pattern of bold (1), italic (2) and underline (4), i.e bold underline is “5”,
  • <fontfamily>, is a string defining the typeface to be used.


Most drawing is contained within a <path> element. Again, the graphic primitives are very similar to that of HTML 5 canvas.

  • <move> to attributes required decimals (x,y).
  • <line> to attributes required decimals (x,y).
  • <quad> to required decimals (x2,y2) via control point required decimals (x1,y1).
  • <curve> to required decimals (x3,y3), via control points required decimals (x1,y1) and (x2,y2).
  • <arc>, this doesn’t follow the HTML Canvas signatures, instead it’s a copy of the SVG arc command. The SVG specification documentation gives the best description of its behaviours. The attributes are named identically, they are decimals and all required.
  • <close> ends the current subpath and causes an automatic straight line to be drawn from the current point to the initial point of the current subpath.

Complex drawing

In addition to the graphics primitive operations there are non-primitive operations. These provide an easy method to draw some basic shapes:

  • <rect>, attributes “x”, “y”, “w”, “h”, all required decimals
  • <roundrect>, attributes “x”, “y”, “w”, “h”, all required decimals. Also “arcsize” an optional decimal attribute defining how large, the corner curves are.
  • <ellipse>, attributes “x”, “y”, “w”, “h”, all required decimals.

Note that these 3 shapes and all paths must be followed by either a fill, stroke, or fillstroke.


<text> elements have the following attributes:

  • str“, the text string to display, required.
  • x” and “y“, the decimal location (x,y) of the text element, required.
  • align“, the horizontal alignment of the text element, either “left”, “center” or “right”. Optional, default is “left”.
  • valign“, the vertical alignment of the text element, either “top”, “middle” or “bottom”. Optional, default is “top”.
  • localized“, 0 or 1, if 1 then the “str” actually contains a key to use to fetch the value out of mxResources. Optional, default is 0, unused in Designer for now.
  • vertical“, 0 or 1, if 1 the label is rendered vertically (rotated by 90 degrees). Optional, default is 0.
  • rotation“, angle in degrees (0 to 360). The angle to rotate the text by. Optional, default is 0.
  • align-shape“, 0 or 1, if 0 ignore the rotation of the shape when setting the text rotation. Optional, default is 1.
  • placeholders“, 0 or 1, if 1 placeholders of the form %name% will be replaced with their values. Optional, default is 0.


<image> elements should be uploaded to ServiceNow and linked with the relative link, without using the instance name. This ensures that diagrams can be transferred between different instances. 

Attributes are:

  • src“, required string. Either a data URI or URL.
  • x“, “y“, required decimals. The (x,y) position of the image.
  • w“, “h“, required decimals. The width and height of the image.
  • flipH” and “flipV“, optional 0 or 1. Whether to flip the image along the horizontal/vertical axis. Default is 0 for both.

Sub-shapes (only supported for built-in shapes in Designer)

<include-shape> allow stencils to be rendered within the current stencil by referencing the sub-stencil by name. Attributes are:

  • name“, required string. The unique shape name of the stencil.
  • x“, “y“, “w“, “h“, required decimals. The (x,y) position of the sub-shape and its width and height.