# Shape Relationships

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

Shape Relationships let an administrator define **conditional styling for relationships** so specific links on the canvas stand out — a different color for a *Depends on* between a Business Application and its Database, for example. It's how you encode organizational conventions into the look of a diagram.

This page covers how the styling resolves, how to configure it, and how it fits with user-set styles.

## How Relationship Styling Resolves

YouDesign Models evaluates **three sources** of style when rendering a relationship, in order. Each subsequent source overrides the previous one where defined.

### 1. Global Relationship Style

The baseline style for all new visual relationships.

| Attribute      | Value                                             |
| -------------- | ------------------------------------------------- |
| **Defined in** | `sys_properties` table                            |
| **Setting**    | `x_inpi_yd.user.default_relationship_format`      |
| **Scope**      | Default for all users when no other style applies |
| **Affects**    | **Visual relationships only**                     |

Modify this in [Global Settings](/models/admin/global-settings.md).

### 2. User Preference Relationship Style

A user-specific override applied once the user has picked a style themselves.

| Attribute      | Value                                     |
| -------------- | ----------------------------------------- |
| **Defined in** | `sys_user_preference` table               |
| **Setting**    | `x_inpi_yd.user.last_relationship_format` |
| **Scope**      | Individual user's preference              |
| **Affects**    | **Visual relationships only**             |

This is set automatically when a user changes the style of a visual relationship in the editor. It affects subsequent new relationships the same user creates.

### 3. Shape Relationship (CI Relationship Style)

Conditional style for **CI relationships** between specific shape pairs. This is the admin-configured layer — where you bake rules like "relationships between Business Capability and Business Application use a green dashed line."

| Attribute      | Value                                                     |
| -------------- | --------------------------------------------------------- |
| **Defined in** | `x_inpi_yd_shape_relationship` table                      |
| **Scope**      | By shape pair + relationship type                         |
| **Affects**    | **CI relationships only** (not visual-only relationships) |

Because it's keyed by **Shape** (not just the underlying table), you can apply different styles for the same relationship type when the endpoints are different shapes — even if the shapes bind to the same table.

**Example:**

* *Business Application (Shape A)* → **Updates** → *Information Object (Shape B)* ⇒ Style Z
* *Business Application (Shape C)* → **Updates** → *Information Object (Shape B)* ⇒ Style X

## Configuring a Shape Relationship

1. Open the **Shape Relationships** list (`x_inpi_yd_shape_relationship`) from the YouDesign Models application menu.
2. Click **New**.

| Field                      | Description                                                                                               |
| -------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Shape**                  | The **from** (source) shape of the relationship                                                           |
| **Target Shape**           | The **to** (target) shape of the relationship                                                             |
| **Suggested Relationship** | The suggested relationship (from `cmdb_rel_type_suggest`) between the underlying tables of the two shapes |
| **Relationship**           | Auto-populated from the selected Suggested Relationship                                                   |
| **Style**                  | JSON style object (see below)                                                                             |

> **Both shapes must share the same underlying Data Hub table binding** for the suggested relationship to resolve correctly. If you can't find the Suggested Relationship you expect, check your metamodel first.

> **🖼 Screenshot needed:** \[Shape Relationship form with Shape, Target Shape, Suggested Relationship, Relationship, and Style fields populated] *Show: a Shape Relationship record showing From shape, To shape, a suggested relationship like "has target", and a JSON Style field with syntax-highlighted content.*

## Style JSON Reference

The **Style** field holds a JSON object describing the link's visual properties:

```json
{
  "fromArrow": "",
  "toArrow": "OpenTriangle",
  "linkRoute": "AvoidsNodes",
  "linkStroke": "line",
  "linkWidth": 4,
  "linkColor": "red",
  "horizontalTextAlignment": "0.5",
  "fontColor": "gray",
  "font": "normal 12px Arial",
  "textOrientation": "OnTheLine",
  "corner": 10,
  "verticalTextAlignment": 0
}
```

| Property                  | Description                                                                                                              |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `fromArrow`               | Arrow head at the source end (see [Relationships](/models/work-in-the-app/editor/relationships.md) for available values) |
| `toArrow`                 | Arrow head at the target end                                                                                             |
| `linkRoute`               | Routing style: `"Normal"`, `"AvoidsNodes"`, `"Orthogonal"`                                                               |
| `linkStroke`              | Stroke style: `"line"`, `"dashed"`, `"dotted"`                                                                           |
| `linkWidth`               | Line thickness (1–10)                                                                                                    |
| `linkColor`               | Line color — CSS name, hex, or RGB                                                                                       |
| `horizontalTextAlignment` | `"0"` (left), `"0.5"` (center), `"1"` (right) along the link                                                             |
| `verticalTextAlignment`   | Text offset relative to the line (-15 = top, 0 = middle, +15 = bottom)                                                   |
| `fontColor`               | Text color                                                                                                               |
| `font`                    | CSS font shorthand (e.g. `"normal 12px Arial"`)                                                                          |
| `textOrientation`         | `"OnTheLine"` (horizontal) or `"FollowsTheLine"` (rotates with link angle)                                               |
| `corner`                  | Corner radius for orthogonal/avoids-nodes routes                                                                         |

For the full set of arrow values and link behavior, see the [end-user Relationships documentation](/models/work-in-the-app/editor/relationships.md).

## Limits & Gotchas

* **Only CI relationships are styled by Shape Relationships.** Visual-only relationships (not backed by CMDB data) are controlled by the Global and User Preference styles.
* **Shape Relationships don't retroactively restyle existing links.** They apply as each link is rendered, so changes take effect on refresh.
* **Per-user overrides take priority over Global** — if a user has ever changed a relationship style in the editor, their User Preference will override the Global default for every new *visual* relationship they create.
* **Style precedence is not configurable.** The three-tier order (Global → User Preference → Shape Relationship) is fixed.
* **Migrate shape relationships via XML**, not Update Sets. See [Migrating Configuration](/models/get-the-app/migrating-configuration.md).

## Related

* [Relationships (end-user)](/models/work-in-the-app/editor/relationships.md) — the end-user view of styling
* [Shape Administration](/models/admin/shapes.md) — configuring the shapes themselves
* [Global Settings](/models/admin/global-settings.md) — where the global relationship format lives
* [Metamodel Prerequisites](/models/admin/metamodel.md) — suggested relationships must exist first
* [Migrating Configuration](/models/get-the-app/migrating-configuration.md) — moving styles between instances


---

# 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/shape-relationships.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.