Insights Connector API contract

This contract is currently in the Proof-of-concept stage and is still subject to change

Introduction

Our product can integrate with a variety of business intelligence (commonly called BI) tools. By configuring new Module Plugins with the category “Business Intelligence”, MediaHaven will produce a list of reports by combining all reports across all plugins of this category.

Methods

A connector of the category “Business Intelligence” must implement the following methods

GET /reports

Returns a list of embeddable report URLs. This means those URLs can be safely embedded into a 3rd party website, specifically the MediaHaven frontend. If the BI tool wants to protect itself against tampering of the URL by the end-user (e.g. changing a parameter), then the connector should produce a signed URL which is inherently tamper-proof.

Optional parameters

Depending on the application and the authorizations of the user the following parameters can provided with this GET request.

Parameter	Usage	Example
collection	When the installation contains multiple applications, then the collection parameter specifies which application it concerns such that a different list of reports can be returned.	Seriesregister, e-Depot
filter.organisation_long_name filter.organisation_short_name filter.organisation_id	When the user has no access across all organisations, then these parameters restrict the results that should be displayed in the report to this organisation. Specifically, if the user has the function `ADMIN_VIEW_ALL_ORGANISATIONS`then they can see installation-wide reports.	The organisation of the user

Expected headers

x-api-key: <reporting engine api key>

Output

Example

[
  {
    "EmbedUrl": "https://mh-dev.mediahaven.com/reporting/embed/dashboard/ABC#bordered=true&titled=true",
    "Id": 123,
    "Label": "My report A",
    "Collection": "Collection",
    "Params": [
      {
        "Id": 123,
        "Label": "label",
        "Type": "Type"
      }
    ]
  },
  {
    "EmbedUrl": "https://mh-dev.mediahaven.com/reporting/embed/dashboard/XYZ#bordered=true&titled=true",
    "Id": 124,
    "Label": "My report B",
    "Collection": "Collection",
    "Params": [
      {
        "Id": 124,
        "Label": "label",
        "Type": "Type"
      }
    ]
  }
]

GET /reports/:id

Returns a specific report with the ID

Optional parameters

Same as the general GET method.

Expected headers

x-api-key: <reporting engine api key>

Output

Example

{
  "EmbedUrl": "https://mh-dev.mediahaven.com/reporting/embed/dashboard/ABC#bordered=true&titled=true",
  "Id": 123,
  "Label": "My report A",
  "Collection": "Collection",
  "Params": [
    {
      "Id": 123,
      "Label": "label",
      "Type": "Type"
    }
  ]
}