Dashboard widget API fails to load custom data source, returns 404 Not Found

IoT Cumulocity IoT
, , , , , , , ,
1

I’m developing a custom dashboard widget that needs to fetch data from a custom microservice endpoint. The widget API consistently returns 404 Not Found when attempting to load the data source, even though the microservice endpoint works fine when tested directly.

The widget configuration references the data source using the Widget API endpoint pattern, but I’m unsure if the path is correct. We’ve registered the data source in the widget manifest with type ‘c8y_CustomDataSource’ and specified the microservice path.

Direct curl test to the microservice returns data successfully:


GET /service/custom-analytics/api/metrics

But the widget’s data fetch fails with 404. Is there a specific data source registration process required beyond the manifest declaration? The widget API path correctness is unclear from the documentation - should it be relative or absolute, and does it need a specific prefix for custom microservices?

2

That clears up a lot. So the workflow is: 1) Define data source type in widget manifest, 2) Register actual endpoint via application options API, 3) Reference by relative path in widget code. I’ll update our registration and test. One more question - does the data source registration need to happen before the dashboard loads the widget, or can it be lazy-loaded?

3

Widget API requires data sources to be registered via the application options API, not just in the manifest. You need to POST to /application/applications/{appId}/options with your data source configuration. The 404 suggests the widget runtime can’t resolve your custom data source reference.

4

I’ve debugged similar issues. The path correctness problem usually comes from mixing absolute and relative paths. In your widget TypeScript code, when you reference the data source, use just the relative path like ‘metrics’ not ‘/service/custom-analytics/api/metrics’. The widget framework automatically prepends the microservice context based on your application options registration.

5

Excellent question - here’s the complete solution covering all three focus areas:

Widget API Endpoint: The widget framework uses a multi-layer resolution system:

  1. Widget code references data source by key (e.g., ‘customMetrics’)
  2. Framework looks up key in application options to get actual endpoint
  3. Endpoint is resolved relative to application context (UI app or microservice)

For custom microservices, the endpoint path in your widget should be relative to the microservice base:

// In widget component
this.dataService.fetch('customMetrics', {params: {...}})
// NOT: this.http.get('/service/custom-analytics/api/metrics')

Data Source Registration: Register via application options API during app deployment:


POST /application/applications/{yourAppId}/options
{
  "category": "dataSource",
  "key": "customMetrics",
  "value": "/service/custom-analytics/api/metrics"
}

This must happen BEFORE dashboard loads widgets. Include this in your application’s deployment script or initialization hook.

Widget manifest (cumulocity.json) declares capability:

{
  "dataSources": [
    {"name": "customMetrics", "type": "c8y_CustomDataSource"}
  ]
}

API Path Correctness: Common mistakes causing 404:

  • Using absolute paths in widget code (wrong)
  • Forgetting /service/ prefix in options registration (wrong)
  • Mismatched key names between manifest and options (wrong)
  • Missing microservice context path (wrong)

Correct pattern:

  • Manifest: declares “customMetrics” data source
  • Options: maps “customMetrics” → “/service/custom-analytics/api/metrics”
  • Widget: references “customMetrics” (framework resolves full path)

Microservice Configuration: Ensure your microservice manifest includes:

{
  "contextPath": "custom-analytics",
  "requiredRoles": ["ROLE_APPLICATION_MANAGEMENT_READ"],
  "resources": {
    "memory": "256M"
  }
}

Debugging Steps:

  1. Verify microservice is subscribed: Administration → Applications → custom-analytics (should show ‘Subscribed’)
  2. Test direct access: GET /service/custom-analytics/api/metrics (should return 200)
  3. Check application options: GET /application/applications/{appId}/options (should list your customMetrics entry)
  4. Verify widget manifest syntax: ensure dataSource name matches options key exactly
  5. Clear browser cache and reload dashboard

Your 404 error is caused by missing application options registration. The widget framework can’t resolve ‘customMetrics’ to the actual microservice endpoint without the options API mapping. Register the data source as shown above and ensure the key names match across manifest, options, and widget code.

6

It’s a one-time setup during app deployment or configuration. The widget manifest tells the UI framework what data sources the widget supports, but the application options API actually registers where those data sources point to. For custom microservices, your path in the widget needs to match the registered option key exactly, and it should be relative to the microservice base path, not absolute.