Purpose

This guideline explains how to include widgets from PERF to external applications.

Overview

PERF Board allows its widgets being included into other applications. This can be useful while building custom dashboards, for example to expose key KPIs of your project with additional notes or a summary to your Client. To achieve this, one should embed a snippet of HTML code into their application and specify a few required parameters so that PERF could render required charts.

Integration Principle

Iframe

In case if you can't insert HTML-code into your page (for example in Cloud Confluence) you can embed this widget using iframe with a special URL.

Use this URL template for "src" attribute for iframe:

1. SERVER_URL: https://delivery.epam.com

2. Query Parameters:

   1. unitId - (required) PERF node ID to take data from

      widgetName - (required) (old name metricName) name of a widget (you can find names in the section List of Available KPIs below)

Set height in iframe properties to 450 for better view experience. Set width according to your needs.

Examples of URLs:

Examples of iframe's code:

To get URLs:

1. Open Delivery Metrics dashboard and click "Get Embed Code"

Open

2. Copy widget metrics code and paste into your place

Open

Example - How to embed a widget into a Confluence page

In order to make the iframe tag work on the Confluence page the following steps should be performed:

1 Click "Insert more content" option on the top of the page.

2 Choose "Other macros" option from the list.

3 In the "Select macro" modal window choose either "HTML" (recommended), or "Iframe".

4a. HTML: Click "Insert" and then insert your iframe tag into the "HTML" field.

4b. Iframe: Fill in URL, Width & Height fields and insert a macro.

Migration Guide: JavaScript → iframe

Here is an example of JavaScript implementation:

In order to migrate it to iframe you would need to:

1. Prepare URLs for "src" attributes in iframe tags based on the template: <HOST>/perf/widget/host.html?unitId=<projectId>&widgetName=<metricName>.

In the example above:

HOST = https://delivery.epam.com

projectId (1,2) = 162919

metricName (1) = QUALITY_QUALITY_DEBT_PESSIMISTIC

metricName (2) = QUALITY_QUALITY_DEBT_OPTIMISTIC

1. Remove all script tags.

2. Replace all div tags with id attributes with iframe tags. Please feel free to copy values of style attributes. Don't forget to add height/width values, if they are absent.

As a result we will have:

Embedding EPAM DC widgets on non-EPAM KB

If you would like to embed widgets from EPAM DC (https://delivery.epam.com ) to customer's confluence, please keep in mind that due to security restrictions you would need to be authorized to http://delivery.epam.com first. In order to ease this process, please feel free to place this peace of code in HTML section on your confluence page with widgets:

List of Available Metrics

Here is an explanation of a way how to obtain an up-to-date list of available metrics.

Go to the Swagger UI, find the endpoint GET /api/v2/views/metric/default/config/category/catalogue -

Make sure fullMode == false.

Invoke the endpoint.

Take the output and grab a required metric ID based on its reader-friendly name.

Full JSON with a list of metric categories as well as metric names / IDs is available below (but can be outdated!!!)