Portal Widgets Reference

This page describes the widgets included in the initial catalog. Core widgets have visual controls and, where applicable, advanced JSON properties; native User View types are configured entirely through guided controls.

Common Properties

Property	Type	Usage
title	string	Optional title for the widget.
hidden	boolean	Hides the widget when set to true.
placement.x, placement.y	integer	Position in the grid, starting from 1.
placement.w, placement.h	integer	Width and height in cells.
style	object	CSS properties, states, and breakpoint of the instance.
style.rawCss	string	Advanced scoped CSS rules.

In the Inspector, the Title field and the JSON property title are synchronised in both directions. A string entered in one of the two is also reflected in the other. To remove the heading, delete title from the JSON or clear Title; the guided control automatically saves the change.

Guided controls are automatically saved and show a confirmation toaster. For JSON Properties, JSON Style, and Scoped CSS, use Save Advanced Changes instead.

Section (layout.section)

Groups related content. title controls the visible heading. It is also useful as a destination structure for custom components.

Text (content.text)

The text property contains plain text; line breaks are preserved.

{"title": "Avviso", "text": "Intervento programmato\nDalle 18:00 alle 19:00"}

To change only the content, use .portal-text in scoped CSS.

Hero (content.hero)

Opening block with eyebrow, title, subtitle, image (assetPath) and optional button (buttonLabel, routeId). routeId accepts only an internal route. Use only one main Hero per page and fill imageAlt when an image is present. Image layout can place the image as the background, at the top, in the middle, or at the bottom without distortion.

Card (content.card)

Combines title, text, image and internal link. In grids use uniform dimensions; Image layout can use the image as the Card background or place it at the top, in the middle, or at the bottom while preserving its proportions.

Divider (content.divider)

orientation can be horizontal or vertical; title is an optional label. A vertical divider requires adequate grid height.

Link (navigation.link)

• label: button label;
• routeId: identifier of an internal route declared in portal.json.

The widget does not open external URLs.

{"label": "Apri ordini", "routeId": "orders"}

Menu (navigation.menu)

items is an array of {label, routeId} selected from existing routes. orientation can be horizontal or vertical; collapseOnMobile enables compact mode on small screens.

Navigation Tabs (navigation.tabs)

Shows related routes as tabs. items preserves order, while stretch distributes tabs across available width. On mobile, tabs scroll horizontally.

Breadcrumb (navigation.breadcrumb)

items describes the hierarchical path; the last item may not have routeId. separator accepts short text. The Breadcrumb does not replace the main menu.

Image (media.image)

• assetPath: image path in the repository;
• alt: accessible alternative description.

Load the file from Explorer first and then use the same path:

{"title": "Marchio", "assetPath": "assets/logo.png", "alt": "Logo aziendale"}

PNG, JPEG, GIF and WebP files can be loaded up to the limit indicated by the editor. Height placement.h also sizes the image, which uses all available space without distortion. To change the crop, use, for example, .portal-image { object-fit: cover; } in scoped CSS.

Read-only Form (form.readonly)

fields is an array of objects with key, label and value:

{
  "title": "Ordine",
  "fields": [
    {"key": "number", "label": "Numero", "value": "SO-1001"},
    {"key": "status", "label": "Stato", "value": "Aperto"}
  ]
}

Collapsible panel (layout.collapsible)

title is always visible, content contains the text and openByDefault selects the initial state. Do not hide mandatory errors or confirmations in a closed panel.

Sidebar (layout.sidebar)

Side area confined within the widget. side is left or right; collapsible and collapsedByDefault govern compact control. For complete navigation, a vertical menu is preferably used.

Drawer (layout.drawer)

Overlaid Panel opened by buttonLabel. side selects the side and closeOnScrim enables closing on background. The runtime handles Escape and focus return; do not use the Drawer for blocking messages.

Data table (data.table)

• columns: ordered list of keys to display;
• bindings.data.resourceKey: Data Resource declared in the data folder.

{
  "props": {"title": "Ordini", "columns": ["number", "status"]},
  "bindings": {"data": {"resourceKey": "orders"}}
}

The Data Resource can query authorized objects, data sources, or Semantic Models. The browser does not access the source directly.

The Data command creates and modifies resources with visual selection of connection, schema, table, dimensions, measures, and aggregations, or of a published Semantic Model, fields, and measures. Open JSON enables advanced configurations after the first save.

Data form (form.write)

Collects typed fields and starts an authorised Workflow. Define fields opens a dedicated dialog for key, label, type, default value, required state, minimum and maximum; at least one field is required, and limits are enabled only for numbers, dates and date/time values. The Workflow selector is mandatory and lists only executable Project Workflows that receive input data. Workflow defaults and fixed values must be associated with a form field; in Preview they override its default and are displayed directly in the disabled input, without an additional text row. The Data form does not require a Data Resource, so that section is not shown in the Inspector; editing an older configuration automatically removes any obsolete data binding.

The Value list type uses the options configured in the Workflow and is rendered as a dropdown. It has no default, minimum or maximum, does not accept a fixed value and can only be mapped to a Workflow parameter of the same type. Option labels and values remain distinct, and the selected value is validated before execution.

Bar chart (data.chart)

Displays server-calculated metrics as accessible horizontal bars. series lists the key, label and optional colour for each metric; the binding must reference an aggregate Data Resource.

Upload File (form.upload)

Portal readers can drop a document onto the upload area or select it from their device. The widget updates its status without reloading the page and then shows the file name, size and remove action. The Download button is available only when it is enabled in the Inspector.

The configuration accepts PDF, PNG, JPG/JPEG, DOCX, TXT, CSV and XLSX, a maximum size from 1 to 256 MB, and the Encrypt file on server option. Sybot validates the actual file content before storing it and rejects disguised executables, scripts and files that do not match their extension. Each reader can download or remove only files they uploaded.

Data export (data.export)

The Inspector checkboxes can expose CSV, XLSX, or both; at least one format must remain selected. No export command needs to be enabled in the Data Resource: queryable Connections, Semantic Models, and Working Datasets are supported. The widget binding, Portal access, and source permissions are still checked. The generated file is temporary and neutralises values that may be unsafe in spreadsheets.

User View (user-view.embed)

• viewId: User View ID;
• versionId: Published version ID to block in the release.

Both values are mandatory. In Visual mode, the dropdown displays only published User Views belonging to the Portal Project and automatically populates both IDs. The version pin prevents a subsequent modification of the View from changing an already approved Portal release.

In Preview and the Published Portal, the View is displayed directly in the widget, without requiring a second access. If the session or permissions are no longer valid, the widget displays diagnostics instead of the View.

In the Portal, the extended header of the View does not occupy space: updates, filters, and view options are gathered in a floating icon-only toolbar.

User View Widget (user-view.widget)

Incorpora un singolo widget standard o personalizzato di una Vista pubblicata. La palette e l'Inspector mostrano solo i widget delle Viste accessibili nel Progetto e registrano viewId, versionId e widgetKey. Sono supportati anche grafici, KPI, tabelle, mappe e widget provenienti dal catalogo personalizzato delle Viste.

The runtime loads only the portion of the View and the data source required for the selected widget; it is not possible to change widgetKey to access a different data source.

Native Types Shared with User Views

The Portal can create new instances of every type available in the User View editor. The palette shows the type rather than instances already configured in individual Views. New instances belong to the Portal and use the shared properties, guidance, and renderer.

Available families include charts, maps, KPIs, record details, content, layouts, navigation and filter controls, Workflow actions, diagnostics, and Data Table. Data types require a Portal Data Resource, while types that start a Workflow require the corresponding binding.

The Inspector groups properties into sections and provides visual controls for columns, linked widgets, thresholds, ranges, and mappings, so editing JSON is not required. Sections keep their open or closed state during autosave. Types that share a name with a core Portal widget remain separate: the native User View entry does not replace or change the core implementation.

Workflow Action (workflow.action)

• workflowId: Associated workflow;
• buttonLabel: button text;
• confirmationText: optional confirmation;
• fields: parameters collected before startup;
• bindings.workflow.workflowId: must match props.workflowId.

In Visual mode, the dropdown displays only the executable Workflows of the Portal Project. For each parameter, the Inspector generates a choice between a default value (default), a user-provided value (prompt), and a fixed value (literal). Sensitive parameters do not allow fixed values; Workflows with file parameters are not selectable.

In Preview, the action performs a dry-run. In the active Portal, it starts the Workflow only if the user, Portal, and release are authorised.

BPMN diagram (bpmn.viewer)

• templateId: BPMN object belonging to the Project;
• versionId: deployed, pinned version.

The selector fills both values and shows accessible diagrams only. Preview and runtime use a read-only viewer and revalidate the reader's permissions.

Report Power BI (bi.powerbi)

The widget supports both Secure URL, with the viewer's Microsoft session, and App owns data, with a Project-governed profile and binding. Publish to web URLs and values containing tokens or credentials are rejected. See Power BI: Secure URL and App owns data for the complete configuration of both modes.

Dashboard Qlik (bi.qlik)

• embedMode: secure_url or oauth_impersonation;
• embedUrl: Qlik HTTPS URL, only for Secure URL;
• bindingKey: Project logical binding, only for OAuth impersonation;
• allowFullscreen: enables fullscreen.

Governed mode stores the App ID and content type in the binding and uses a short-lived token generated by Sybot. Profile and endpoint must pass Diagnostics, and the release retains the binding revision. See Governed integrations.

Custom widget sandbox (custom.sandbox)

A custom component uses this structure:

components/my-widget/
├── component.json
├── template.html
├── styles.css
└── index.js

component.json declares files and capabilities:

{
  "schemaVersion": 1,
  "name": "My widget",
  "executionMode": "sandboxed",
  "template": "template.html",
  "styles": "styles.css",
  "entry": "index.js",
  "capabilities": ["data:query", "events:emit"]
}

JavaScript can modify the DOM inside its own iframe. For data and actions, use PortalWidgetSDK; direct network calls, access to the parent document, cookies and session storage are not allowed.

The Inspector exposes Open component code, which automatically switches to Code and opens manifest, template, CSS and JavaScript. The Project Catalogue can also copy a component from another Portal; the component becomes a versionable copy in the current repository.

export async function mount(sdk) {
  const result = await sdk.query('orders', {status: 'open'});
  document.querySelector('[data-count]').textContent = result.rows.length;
}

For live updates, register sdk.onDataInvalidated(listener) and repeat the query when the event includes the resource used by the widget. After a mutation, call sdk.invalidateData(resourceKey). setContext() and getContext() manage shared context without accessing the parent document.

Enable Allow the widget to start Workflows in the Inspector to manage the workflow:start capability without editing JSON. No bindings.workflow entry is required for a custom widget. Use sdk.runWorkflow(nameOrId, parameters) or its sdk.startWorkflow() alias to start any executable Workflow in the current Project; runtime checks still enforce Project scope and user permissions.

Styles, states and breakpoints

CSS properties use kebab-case names. The states and breakpoints sections apply local variations:

{
  "background-color": "#ffffff",
  "padding": "1rem",
  "border-radius": "8px",
  "states": {
    "hover": {"box-shadow": "0 8px 24px rgba(15, 23, 42, .18)"}
  },
  "breakpoints": {
    "md": {"padding": "1.5rem"}
  }
}

Supported states are hover, focus, active and disabled; breakpoints are sm, md, lg and xl. Always verify Desktop, Tablet, Mobile and Preview.

Power BI: Secure URL and App owns data

The bi.powerbi widget provides two modes:

• Secure URL uses a reportEmbed link and the viewer's Microsoft session. The sign-in page is expected when the viewer is not already authenticated.
• App owns data uses a project Power BI binding. Sybot obtains a short-lived token on the server; credentials and tokens are never stored in the widget.

For App owns data, a Super Admin first creates the secret in the Control Center's Credential Vault tab. The project owner then opens Manage profiles and reports in the Portal Editor and creates a profile, a binding and at least the Authoring endpoint. The selectors load workspaces and reports available to that profile. Run Diagnostics before Preview.

Each Project can use multiple profiles, including different Power BI tenants or users, and select a profile for each endpoint. Microsoft public cloud, US Government GCC and Power BI China are available. The Vault supports installation or Project scope, expiration, rotation, disabling and permanent revocation. RLS is configured with a Sybot identity, a static value and roles; advanced SDK settings remain optional.

Property	Purpose
embedMode	secure_url or app_owns_data.
embedUrl	reportEmbed URL, only for Secure URL.
reportBindingKey	Project logical binding, only for App owns data.
variantKey	Endpoint variant, normally default.
pageName	Optional initial page.
showFilters	Shows or hides the filter pane.
showPageNavigation	Shows or hides page navigation.

A binding can resolve different reports and identities for Authoring, Development, Staging, Production or a specific target. Rotating a Vault secret does not require changing the widget. The embed token is refreshed automatically before expiry.

Before deployment, every App owns data binding and variant in the release must have a diagnosed endpoint for the target or its environment fallback. If it is missing, preflight blocks deployment and identifies the configuration to fix; Secure URL does not require this check.