Bosch IoT Insights

PM Service API: Embedding Dashboards

Dashboards in Bosch IoT Insights can be embedded in an external page using an iFrame.

A dashboard can also be embedded via the UI, refer to Embedding a dashboard.

Prerequisites

To embed a dashboard, you need:

  • a project name

  • a technical name of an existing dashboard

  • a URL of the target page where the iFrame will be embedded

Creating the embedding

An embedding can be created via the Project Management Service APIs.

Proceed as follows

  1. Open the Project Management Service APIs.

  2. Open Embeddings: Embedding Management Controller.
    → A list of request is displayed.

  3. Open the POST /v1/{project}/embeddings request.

    1. In the Parameters pane, enter the project name in the project field.

    2. In the embedding field, paste the following code block:

      {
      "active": true,
      "dashboard": "home",
      "allowedOrigins": [
      "https://mywebsite.example.com",
      "https://test.example.com"
      ],
      "authMethod": "USER_SESSION_GRACEFUL"
      }

      → This request creates an embedding for the dashboard with the name 'home' in your project.

The dashboard is allowed to be embedded on the URLs: https://mywebsite.example.com and https://test.example.com.

{
"id": "609a6a07ea4ce82548dcf501",
"dashboard": "home",
"authMethod": "USER_SESSION_GRACEFUL",
"allowedOrigins": [
"https://mywebsite.example.com",
"https://test.example.com"
],
"active": true,
"createdAt": "2021-05-11T11:27:03.038Z",
"createdBy": {
"userId": "27b60000-0000-0000-0000-0000407c0000",
"userName": "user@example.com"
},
"updatedAt": "2021-05-11T11:27:03.038Z",
"updatedBy": {
"userId": "27b60000-0000-0000-0000-0000407c0000",
"userName": "user@example.com"
}
}

The response contains the embedding Id '609a6a07ea4ce82548dcf501'.

This Id is required to build the embedding URL, which follows this structure: https://bosch-iot-insights.com/embed/{project}/{id}.html.

https://bosch-iot-insights.com/embed/p123456/609a6a07ea4ce82548dcf501.html

If you want to initialize the view in a specific language, you can specifiy the language with the query paramater initialLang. Currently supported values are de and en. Furthermore, you can specify to load Bosch IoT Insights in full-screen mode using the query parameter fullscreen.

https://bosch-iot-insights.com/embed/p123456/609a6a07ea4ce82548dcf501.html?initialLang=en&fullscreen=true

If you want the hyperlinks to consider your outer Frame URL use the prefixUrl parameter. It will prevent dashboard links to open outside of the outer Frame, by passing the URL of your frame server.

For instance, by passing

https://bosch-iot-insights.com/embed/p123456/609a6a07ea4ce82548dcf501.html?prefixUrl=https://my-frame-server.com/app/ 

hyperlinks which forward to another dashboard, will be converted from

https://bosch-iot-insights.com/ui/project/<projectName>/views/dashboards/<dashboardName> 

to

https://my-frame-server.com/app/<dashboardName> 

Embedding an iFrame

The embedding URL can be used to embed the dashboard within an iFrame on one of the allowed origins.

<script type="text/javascript" src="https://bosch-iot-insights.com/ui/assets/iframe-resizer/iframeResizer.js"></script>
<iframe id="insightsFrame" src="https://bosch-iot-insights.com/embed/p123456/609a6a07ea4ce82548dcf501.html" width="100%" height="100%"></iframe>
<script type="text/javascript">
iFrameResize({ heightCalculationMethod: 'bodyScroll', checkOrigin: false }, '#insightsFrame');
</script>

Depending on how you want the iFrame to be displayed on your website, you can use the iFrameResizer as seen in the example to automatically adjust the height of the iFrame based on its content to avoid a scrollbar within the iFrame.

Advanced embedding example

If you want to pass query parameters between your website and the dashboard or want to navigate between different dashboards, you can use the embedding-api.js as displayed in the following example:

<script type="text/javascript" src="https://bosch-iot-insights.com/ui/assets/iframe-resizer/iframeResizer.js"></script>
<script type="text/javascript" src="https://bosch-iot-insights.com/ui/assets/embedding/embedding-api.js"></script>
<iframe id="insightsFrame" src="https://bosch-iot-insights.com/embed/p123456/609a6a07ea4ce82548dcf501.html" width="100%" height="100%"></iframe>
<script type="text/javascript">
iFrameResize({ heightCalculationMethod: 'bodyScroll', checkOrigin: false }, '#insightsFrame');
insightsFrameApi = initInsightsEmbedding('#insightsFrame');
</script>
<a href="javascript: insightsFrameApi.navigate('https://bosch-iot-insights.com/embed/p123456/609a6a07ea4ce82548dcf501.html?device=otherDevice')">Dashboard 2</a>

The insightsFrameApi.navigate() JavaScript function can be used to navigate to another dashboard or pass in query parameters.

Insights embedding API

The initInsightsEmbedding function has several arguments that can be used to realize different use cases.

initInsightsEmbedding(iFrameRef, baseLocation = window.location.pathname, debug = false, handlers = {})
  • iFrameRef can be an iFrame DOM element or a string with a css selector to an iFrame element.

  • baseLocation is the base path that will be extended with the history push state API to add path and query parameters of the Bosch IoT Insights dashboard, when parameters are changed. If set to null, no url manipulation will be done.

  • debug, set to true, to get logging information on the console.

  • handlers is an object that can have an action name as key and a function as value, that receives events from Bosch IoT Insights.

insightsFrameApi = initInsightsEmbedding('#insightsFrame', window.location.pathname, true, {
paramsChange: (data) => console.log('Parameters have been changed', data),
ready: () => console.log('Frame has been loaded'),
userInfo: (data) => console.log('Logged in in IoT Insights with', data)
});

Troubleshooting

iFrame shows a connection error

  • Firefox: The connection was reset

  • Chrome: bosch-iot-insights.com refused to connect

If you see such an error, it usually means that the allowedOrigins of the embedding do not match the current website and the iFrame embedding is not allowed for this website.

You can solve this issue by using the REST API to modify the embedding with a list of allowedOrigins that contains the current website.