Viz dashboard API SDK: Custom widget loads blank after API data fetch

IoT Oracle IoT Cloud
, , , , , , , ,
1

Our custom dashboard widget intermittently loads blank even though the API SDK successfully fetches data. Looking at browser console, the API response is valid JSON with all expected fields, but the widget UI doesn’t render. This happens about 30% of the time - refreshing the page eventually makes it work.

Widget data binding code:

vizAPI.getData().then(data => {
  widget.bind(data.metrics);
  widget.render();
});

API response validation shows 200 status and correct data structure. The dashboard UI refresh seems to have timing issues. We’re using oiot-pm (latest production maintenance release). Has anyone dealt with custom widget rendering reliability in the viz dashboard module?

2

Check if your API response contains any null values in the metrics array. The viz dashboard SDK’s data binding engine doesn’t handle nulls gracefully - it just silently fails to render without throwing an error. You need to sanitize your data before binding. Also, make sure you’re calling widget.render() AFTER the binding completes, not in the same tick. The binding operation is asynchronous even though the API doesn’t make that clear in the documentation.

3

Look at the widget’s CSS loading. In oiot-pm, custom widgets load their stylesheets asynchronously, and if the render() method executes before CSS is fully loaded, you get a blank display because elements have zero dimensions. The widget is technically rendered but invisible. Add a CSS load listener before calling render().

4

Your intermittent blank widget issue is caused by improper handling of the widget lifecycle and data binding validation. Here’s a complete solution addressing all three focus areas:

Widget Data Binding: The problem is that you’re calling bind() and render() synchronously, but the viz SDK’s bind operation is asynchronous and doesn’t return a promise. You need to wait for the binding to complete:

vizAPI.getData().then(data => {
  widget.bind(data.metrics, {
    onBindComplete: () => {
      widget.render();
    },
    onBindError: (err) => {
      console.error('Binding failed:', err);
      widget.showError();
    }
  });
});

The bind() method in oiot-pm accepts an options object with lifecycle callbacks that you must use to ensure proper sequencing.

API Response Validation: Even though your API returns 200 status, the viz dashboard SDK performs additional validation on the data structure. The blank widget occurs when validation fails silently. Implement explicit validation:

vizAPI.getData().then(data => {
  // Validate required fields
  if (!data.metrics || !Array.isArray(data.metrics)) {
    throw new Error('Invalid metrics structure');
  }

  // Sanitize null values
  const cleanData = data.metrics.filter(m => m !== null)
    .map(m => ({
      ...m,
      value: m.value ?? 0
    }));

  widget.bind(cleanData, {
    onBindComplete: () => widget.render()
  });
}).catch(err => {
  widget.showError(err.message);
});

The SDK’s bind method fails silently when encountering null values or missing required properties. Always filter and sanitize your data before binding.

Dashboard UI Refresh: The intermittent nature (30% failure rate) indicates a race condition with the dashboard framework initialization. The viz dashboard loads widgets in parallel, and your custom widget might be trying to render before the framework’s CSS and layout engine are ready.

Use the dashboard’s ready event:

dashboard.onReady(() => {
  vizAPI.getData().then(data => {
    const cleanData = sanitizeMetrics(data.metrics);
    widget.bind(cleanData, {
      onBindComplete: () => {
        // Force layout recalculation
        widget.container.style.display = 'none';
        widget.container.offsetHeight; // Trigger reflow
        widget.container.style.display = '';
        widget.render();
      }
    });
  });
});

The forced reflow ensures the widget container has proper dimensions before rendering. This eliminates the blank display issue caused by CSS loading delays.

Additionally, clear the widget cache by adding a cache-busting parameter to your widget definition:

widget.configure({
  cacheKey: Date.now()
});

This combination of proper lifecycle management, data validation, and framework synchronization should eliminate your blank widget issues entirely.