# Shape Administration

> This task requires the **Shape Editor** (`x_inpi_yd.shape_editor`) or **YouDesign Admin** (`x_inpi_yd.admin`) role.

Shapes are the building blocks end users drop onto boards. Admins define each shape's look, the ServiceNow table it binds to, which fields the [Data Panel](/models/work-in-the-app/editor/data-inspector.md) exposes, and how it's grouped with other shapes in the library.

This page covers the admin side of shape configuration. For the end-user reference of what's bundled, see [Shape Libraries](/models/work-in-the-app/editor/shape-libraries.md). For end-user shape handling on the canvas, see [Shapes](/models/work-in-the-app/editor/shapes.md).

## Getting to Shape Administration

In the ServiceNow navigator, open the **YouDesign Models** application menu:

* **Configuration → Shapes** — the Shape list
* **Configuration → Shape Categories** — the category hierarchy
* **Configuration → Shape Relationships** — relationship styling rules ([see dedicated page](/models/admin/shape-relationships.md))

## Shape Categories

Categories are how shapes are grouped in the Diagramming panel. A category can be top-level or nested under a parent category.

### Creating a Category

Open the **Shape Category** list (`x_inpi_yd_shape_category`) and click **New**.

| Field           | Description                                                                                                   |
| --------------- | ------------------------------------------------------------------------------------------------------------- |
| **Name**        | Display name shown in the diagramming panel                                                                   |
| **Description** | Optional short description                                                                                    |
| **Parent**      | Leave empty for a top-level category. Otherwise, reference an existing category to create a nested structure. |
| **Order**       | Display order. Same-order entries are sorted alphanumerically.                                                |
| **Active**      | Unchecking hides the whole category (and its shapes) from the diagramming panel without deleting anything.    |

A category record shows two related lists:

* **Shapes** — every shape assigned to this category
* **Shape Categories** — every direct child category

> **🖼 Screenshot needed:** \[Shape Category form in ServiceNow with Name, Parent, Order fields visible, plus related list of child categories and shapes] *Show: Shape Category record for "ServiceNow", Parent empty, Order 500, Shapes related list showing CMDB/Digital/Foundation/ITSM children.*

### Reorganizing

* Move a shape to a different category by editing the shape's **Category** field.
* Renest a category by changing its **Parent**.
* Changes are reflected immediately in the diagramming panel after the user refreshes.

## Individual Shapes

Each shape record (`x_inpi_yd_shape`) has **general**, **data association**, and **preview** sections.

### General

| Field           | Description                                                                        |
| --------------- | ---------------------------------------------------------------------------------- |
| **Category**    | Which shape category this shape belongs to                                         |
| **Name**        | Display name shown in the UI                                                       |
| **Description** | Longer description shown on hover / in admin contexts                              |
| **Active**      | Unchecking hides the shape from the library without deleting its configuration     |
| **Is group**    | Defines the shape as a container (can contain other shapes as group members)       |
| **Order**       | Display order within the category. Same-order entries are sorted alphanumerically. |

### Data Association

Binds the shape to a ServiceNow table so records of that type can be dropped onto the canvas via the [Data Hub](/models/work-in-the-app/editor/data-hub.md).

| Field             | Description                                                                                        |
| ----------------- | -------------------------------------------------------------------------------------------------- |
| **Data Hub**      | Check to make this a Data Hub shape (bindable to records). Leave unchecked for visual-only shapes. |
| **Table**         | The ServiceNow table the shape binds to                                                            |
| **Display Field** | The field used as the shape's label (typically `Name`)                                             |

> **Define only one shape per table as the Data Hub shape.** Multiple Data Hub shapes on the same table confuse the Data Hub's search and drag-drop behavior. Visual variants of the same concept should use different tables or be non-Data-Hub shapes.

### Preview

| Field                    | Description                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------ |
| **Preview (attachment)** | The preview image shown in the shape library. Upload as an attachment on the record. |
| **Update Preview**       | Check after changing the stencil definition to regenerate the preview                |

### Classification (not in use yet)

The **Classification** and **Classification Value** fields are reserved for future use. Leave them at their defaults.

## Stencils: How a Shape Looks

A shape's visual form is defined by a **stencil** — a JSON definition that uses diagramming classes (Panel, Spot, Picture, TextBlock, IndicatorWrapper, etc.) to describe the layout.

A minimal stencil for a simple image shape looks like this:

```json
{
  "ctr": "Panel.Auto",
  "properties": {
    "desiredSize": { "use": "Size", "toParse": "160 160" },
    "locationSpot": { "use": "Spot.Center" },
    "resizable": false,
    "rotationSpot": { "use": "Spot.Center" },
    "rotatable": true
  },
  "children": [
    {
      "ctr": "Picture",
      "properties": {
        "source": "data:image/svg+xml;base64,..."
      }
    }
  ]
}
```

More complex shapes use additional classes:

| Class                | Purpose                                              |
| -------------------- | ---------------------------------------------------- |
| **Panel**            | Container for arranging child elements               |
| **Panel.Auto**       | Panel that sizes to its children                     |
| **Panel.Spot**       | Panel that positions children using spots            |
| **Picture**          | Embedded image (typically base64-encoded PNG or SVG) |
| **TextBlock**        | Editable or static text                              |
| **Shape**            | Geometric shape (rectangle, diamond, circle, etc.)   |
| **IndicatorWrapper** | Enables Realtime Indicator rendering on the shape    |
| **GraphObject**      | Generic stretch/alignment controls                   |

### Embedding a Custom Image

Convert the image (PNG or SVG) to **base64**, then embed it as the `source` property of a `Picture`:

```json
{
  "ctr": "Picture",
  "properties": {
    "source": "data:image/png;base64,iVBORw0KGgoAAAANSUh..."
  }
}
```

SVG sources are preferred where possible — they scale cleanly at any zoom level.

### When to Get Help

Stencils can grow complex quickly — particularly shapes with multiple ports for relationships, embedded RTI indicators, or dynamic labels. If you need help creating shapes or an entire custom shape library, contact your ins-pi representative. Custom shape development is part of the professional services offering — see [Support Process](/models/reference/support.md).

## Shape Fields

A shape's **fields** control which ServiceNow record fields appear in the [Data Panel](/models/work-in-the-app/editor/data-inspector.md) when that shape is selected. See [Shape Fields](/models/admin/shape-fields.md) for the full configuration.

## Limits & Gotchas

* **Shape changes migrate via XML**, not Update Sets. See [Migrating Configuration](/models/get-the-app/migrating-configuration.md).
* **"Active" toggles hide but don't delete.** Users won't see an inactive shape, but existing boards still render it.
* **Tables must exist.** A shape pointing at a table that hasn't been created (or migrated) appears in the library but fails to bind when dropped. See [Metamodel Prerequisites](/models/admin/metamodel.md).
* **Preview image has to be regenerated manually** after stencil changes — check **Update Preview** on the shape record.

## Related

* [Shape Libraries](/models/work-in-the-app/editor/shape-libraries.md) — what's bundled
* [Shapes (end-user)](/models/work-in-the-app/editor/shapes.md) — canvas behavior
* [Shape Fields](/models/admin/shape-fields.md) — field-level configuration
* [Shape Relationships](/models/admin/shape-relationships.md) — relationship styling
* [Metamodel Prerequisites](/models/admin/metamodel.md) — tables must exist first
* [Migrating Configuration](/models/get-the-app/migrating-configuration.md) — how to move shapes between instances
* [Support Process](/models/reference/support.md) — custom shape assistance


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ins-pi.com/models/admin/shapes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.