GUI Extensions

What Are GUI Extensions?

GUI extensions let you embed custom content and actions directly into the Omnium backoffice UI. Each extension is a configuration entry in tenant settings that can:

• Display an iframe — embed an external application, dashboard, or tool inside an Omnium page
• Trigger a webhook — add a button that sends contextual data to an external endpoint when clicked
• Show information — display text, descriptions, or custom properties alongside Omnium data

Extensions are configured per tenant and appear in specific extension areas throughout the UI — on order pages, product pages, customer views, store pages, and more. No code changes to Omnium are required.

How Extensions Work

  CONFIGURATION                    RUNTIME

  Admin configures                 Omnium UI renders
  extension in       ──────────▶   extension in the
  Tenant Settings                  assigned area
                                       │
                              ┌────────┴────────┐
                              ▼                 ▼
                        Iframe loads      Button click
                        with context      sends webhook
                        data (URL         with event
                        templates)        data

1. An admin creates an extension in Tenant Settings > GUI Settings
2. The extension is assigned to an extension area (e.g., the order sidebar, product edit page, or a context menu)
3. At runtime, Omnium renders the extension in that area and passes context data (the current order, product, customer, etc.)
4. If the extension has an iframe URL, it loads the external page with context values injected into the URL
5. If the extension has a webhook URL, clicking the button sends the context data to the external endpoint

Extension Areas

Each extension is assigned to an area that determines where it appears in the UI and how it's displayed. Areas are grouped by the page or feature they belong to.

Orders

Carts

Products

Customers

Stores

Purchase Orders

Deliveries

Other

Extension Model

Each extension is a JSON object in TenantSettings.GuiSettings.GuiExtensions:

Minimal example

An extension that embeds an external dashboard on the order edit page:

{
  "Name": "Order Dashboard",
  "GuiExtensionArea": "EditOrderInline",
  "Header": "External Dashboard",
  "IframeUrl": "https://dashboard.example.com/order?id={{dataObject.orderId}}"
}

Full example

An extension with both an iframe and a webhook action:

{
  "Name": "Fraud Check",
  "GuiExtensionArea": "editorderSidebarLeft",
  "Header": "Fraud Analysis",
  "Description": "Review fraud risk score for this order",
  "ButtonText": "Run Fraud Check",
  "IconCssClass": "fa fa-shield",
  "IframeUrl": "https://fraud.example.com/check?order={{dataObject.orderId}}&market={{dataObject.marketId}}",
  "WebhookUrl": "https://api.example.com/webhooks/fraud-check",
  "WebhookHttpVerb": "POST",
  "WebhookRequestHeaders": [
    { "Key": "Authorization", "Value": "Bearer your-api-key" },
    { "Key": "X-Source", "Value": "omnium" }
  ],
  "Tags": ["requires-review"]
}

Iframe Extensions

When an extension has an IframeUrl, Omnium renders an iframe in the designated area. The iframe receives context data in two ways:

URL templates

The IframeUrl supports dynamic placeholders that are replaced with actual values at render time. Placeholders use double curly braces:

Example URLs:

https://app.example.com/order/{{dataObject.orderId}}
https://erp.example.com/customer?id={{dataObject.customerId}}&lang={{language}}
https://dashboard.example.com/?stores={{selectedStoreIds}}&user={{user.email}}

postMessage API

After the iframe loads, Omnium also sends the full context data to the iframe via the browser's postMessage API. Your iframe application can listen for this message to receive the complete object data:

window.addEventListener('message', function(event) {
  // Verify origin for security
  if (event.origin !== 'https://your-omnium-instance.omnium.no') return;
 
  const data = event.data;
  // data contains the full context object (order, product, etc.)
  console.log('Received from Omnium:', data);
});

Webhook Extensions

When an extension has a WebhookUrl and ButtonText, Omnium displays an action button. Clicking the button sends the current context data to the webhook URL.

Request format

The webhook receives a JSON payload containing the extension configuration and the event data:

{
  "guiExtension": {
    "name": "Fraud Check",
    "guiExtensionArea": "editorderSidebarLeft",
    "webhookUrl": "https://api.example.com/webhooks/fraud-check"
  },
  "eventData": {
    "objectId": "ORD-12345",
    "className": "Order",
    "dataObject": { /* full order object */ }
  }
}

Custom headers configured in WebhookRequestHeaders are included in the request, allowing you to pass API keys or other authentication tokens.

Response format

Your webhook endpoint can return a validation result that Omnium displays to the user:

{
  "isValid": true,
  "validationMessages": ["Fraud check passed — low risk score"],
  "validationWarnings": ["Customer is from a new region"]
}

Retry policy

Webhook requests are retried automatically on failure, with increasing delays between attempts (1, 5, and 15 seconds).

Event logging

Every webhook trigger is logged in the Omnium event system with operation ID 200001 (GuiExtensionTriggered). You can subscribe to this event via the standard Events system for monitoring or auditing.

Tag-Based Filtering

Extensions can be conditionally displayed based on tags. When an extension has Tags configured, it only appears if the current context object's tags include all of the extension's tags.

This lets you show different extensions for different types of objects. For example:

[
  {
    "Name": "B2B Credit Check",
    "GuiExtensionArea": "orderInfo",
    "Tags": ["B2B"],
    "IframeUrl": "https://credit.example.com/check?order={{dataObject.orderId}}"
  },
  {
    "Name": "Gift Wrapping Options",
    "GuiExtensionArea": "orderInfo",
    "Tags": ["gift-order"],
    "IframeUrl": "https://gifts.example.com/wrap?order={{dataObject.orderId}}"
  }
]

The "B2B Credit Check" extension only appears on orders tagged with "B2B". The "Gift Wrapping Options" extension only appears on orders tagged with "gift-order".

Custom Properties

Extensions can include custom key-value properties that are displayed in the extension panel. These are useful for showing static configuration or reference information:

{
  "Name": "Support Info",
  "GuiExtensionArea": "orderInfo",
  "Header": "Support Details",
  "Properties": [
    { "Key": "SLA", "Value": "24 hours" },
    { "Key": "Escalation Email", "Value": "escalation@company.com" },
    { "Key": "Documentation", "Value": "https://wiki.company.com/support" }
  ]
}

Help Menu Items

In addition to page-level extensions, you can add custom items to the help menu in the Omnium UI. Help menu items are configured in TenantSettings.GuiSettings.GuiHelpMenuItems:

{
  "GuiHelpMenuItems": [
    {
      "Name": "Company Wiki",
      "Url": "https://wiki.company.com/omnium",
      "Routes": ["orders", "products"]
    },
    {
      "Name": "Training Videos",
      "Url": "https://training.company.com",
      "Routes": []
    }
  ]
}

When Routes is empty, the help item appears on all pages. When specific routes are listed, it only appears on matching pages.

Common Patterns

External dashboard on order page

Embed an analytics dashboard that shows order-specific insights:

{
  "Name": "Order Analytics",
  "GuiExtensionArea": "editorderSidebarLeft",
  "Header": "Analytics",
  "IframeUrl": "https://analytics.example.com/order/{{dataObject.orderId}}?lang={{language}}"
}

ERP sync button

Add a button that triggers an order sync to your ERP system:

{
  "Name": "Sync to ERP",
  "GuiExtensionArea": "orderEditManage",
  "ButtonText": "Send to ERP",
  "IconCssClass": "fa fa-sync",
  "WebhookUrl": "https://erp-integration.example.com/sync",
  "WebhookHttpVerb": "POST",
  "WebhookRequestHeaders": [
    { "Key": "Authorization", "Value": "Bearer erp-api-key" }
  ]
}

Store-specific information panel

Show store-specific tools on the store edit page:

{
  "Name": "Store Performance",
  "GuiExtensionArea": "storeTab",
  "Header": "Performance Dashboard",
  "IframeUrl": "https://dashboard.example.com/store/{{dataObject.id}}?stores={{selectedStoreIds}}"
}

Customer lookup in external CRM

Embed a CRM view on the customer page:

{
  "Name": "CRM Profile",
  "GuiExtensionArea": "privateCustomerEdit",
  "Header": "CRM",
  "IframeUrl": "https://crm.example.com/customer?email={{dataObject.email}}"
}

Configuring in the UI

Extensions are managed in the Omnium backoffice under Administration > Tenant Settings > GUI Settings.

The admin panel provides:

1. Extensions tab — add, edit, reorder, and remove extensions
   • Settings: name, header, description, button text, area assignment, tags, icon
   • Properties: custom key-value pairs
   • IFrame: iframe URL configuration
   • Webhook: webhook URL, HTTP method, custom request headers
2. Help menu tab — configure custom help menu items

Extensions can be reordered by dragging them in the list. The order determines the display order within each extension area.

Related Documentation