ui5-best-practices-integration-cards

Best practices for UI Integration Cards development

Rules an agent must follow when creating, modifying, validating, or previewing a UI Integration Card. Adherence is critical for working cards.

When to load each reference

Trigger	Load
Working on or planning an Analytical card	references/analytical_chart_types.md
dt/Configuration.js exists, is being created, or is being modified	references/configuration_editor_example.md

If the trigger applies, load before producing any output. Do not work from memory.

1. Core rules

Rule	Detail
Prefer declarative cards	Types: List, Table, Calendar, Timeline, Object, Analytical. Create an Extension only in exceptional cases.
Use create_integration_card MCP tool	When creating a new declarative card.
Parameter binding syntax	{parameters>/parameterKey/value} — single braces, > separator, value suffix.
Destination binding syntax	{{destinations.destinationName}} — double braces, dot. Configure under sap.card/configuration/destinations/. Reference by name; never replace with raw URL.
Use destinations for service URLs	Wrap every external service URL in a destination under sap.card/configuration/destinations/ and reference it as {{destinations.name}}.
i18n binding	Bind every non-data, user-visible string to the i18n model.
Links	Use the actions property; never inline <a> or hand-rolled URL handlers.
Validate before declaring done	See 3. Validation.
Show preview when requested	See 4. Preview.
Don't modify provided data	Use it as supplied.
JSON responses only	The endpoint behind sap.card/data/request must return JSON. For OData services, append $format=json to the request URL or parameters.

2. Data placement

sap.card/data/ is the only correct top-level location for the data request.

Path	Purpose
sap.card/data/path	Primary data path
sap.card/content/data/path	Content-specific path; overrides the primary path if set
sap.card/header/data/path	Header-specific path; overrides the primary path if set

Forbidden: putting the request itself under sap.card/content/data/ or sap.card/header/data/.

Symptom — "No data to display": typically caused by a content/data block that overrides the primary data path. Verify 2. Data placement before debugging anything else.

3. Validation

Rule	Detail
Valid JSON	manifest.json must parse.
sap.app/type	Must be "card".
Schema validation	Use run_manifest_validation MCP tool.
No deprecated properties	In manifest.json or elsewhere.
Not a UI5 project	Except for Component-type cards.

4. Preview

If asked to preview, first check the card folder for an existing preview entry point — package.json start script, README.md, or an existing HTML file. Reuse it if present. Otherwise create an HTML page with a <ui-integration-card> element pointing at the manifest, and serve via an http server.

5. Configuration Editor

The editor lets the Administrator, Page/Content Administrator, and Translator personas customize a card without editing manifest.json directly.

Two pieces:

1. dt/Configuration.js — exports a function that returns new Designtime({ form: {...} }).
2. manifest.json — references the file at sap.card/configuration/editor.

Design as the Administrator persona.

Rule	Detail
Mirror the manifest	Editor reflects the current structure and parameters of manifest.json exactly. manifestpath can target any existing path — a configuration/parameters/*/value for parameterized fields, or a direct path like /sap.card/header/icon/shape for static manifest properties.
All existing fields editable	Title, subtitle, header icon, parameters — make them configurable.
Ask the user	Before deciding which fields to expose, ask: "Make all manifest fields editable? Anything else to add?"
No invented fields	Never add an editor field that does not exist in manifest.json.
Keep in sync	Add to or remove from the editor when adding to or removing from manifest.json.

Load references/configuration_editor_example.md for the canonical paired example.

6. Analytical cards

Load references/analytical_chart_types.md for the full chart-type catalog (UIDs and per-type examples).

Rule	Detail
Set chartType	sap.card/content/chartType is required.
Match feeds to chart type	measures, dimensions, and feeds must match the UIDs the chart type expects. The reference file lists them per chart.
Each feed needs three keys	type (Dimension|Measure), uid, values.
chartProperties	Use it for labels, colors, legend, etc. Do not invent keys. Omit entirely if defaults are fine.

Minimal feeds example (donut/pie):

"feeds": [
  { "type": "Dimension", "uid": "color", "values": ["Store Name"] },
  { "type": "Measure", "uid": "size", "values": ["Revenue"] }
]

7. Card Explorer (reference)

• Schema docs and live samples: https://ui5.sap.com/test-resources/sap/ui/integration/demokit/cardExplorer/webapp/index.html
• Sample sources: https://github.com/UI5/openui5/tree/master/src/sap.ui.integration/test/sap/ui/integration/demokit/cardExplorer/webapp/samples