Table of Contents

Integration with an iframe can be used if the Graphlytic application should be directly embedded into another web application.

1. Prerequisites:

In order to enable iframe integration, please do the following:

  • Enable Cross-Origin Resource Sharing (CORS). For more information, refer to the Cross-Origin Resource Sharing (CORS) page.

  • Every request loaded inside the iframe must include an HTTP Referer header. Graphlytic's CORS filter rejects iframe requests without it, responding with 400 Bad Request – "Referer header not provided", so the page embedding the iframe must be served over HTTP/HTTPS. It cannot be opened directly from the local filesystem (file://), because browsers do not send a Referer header for file:// origins. The host page must also not suppress the referrer (e.g., <meta name="referrer" content="no-referrer"> or a Referrer-Policy: no-referrer header).

  • If a domain allowlist is configured in the CORS settings, the host (domain) of the request's Referer must match one of the allowed domains; otherwise, Graphlytic responds with 403 Forbidden –
    "Domain <domain> not supported". Make sure the domain of the page embedding the iframe is included in the allowlist. If the allowlist is left empty, requests from any domain are accepted
    (provided a Referer header is present).

  • Embed the iframe HTML code into the third-party web application (options are below)

Authenticating via username/password establishes a session stored in a cookie (JSESSIONID). Because the iframe is loaded from a different site than the host page, this is a third-party cookie. If the visitor's browser blocks third-party cookies, pages that load their data via background requests (e.g., the visualization list) may fail to load. To allow the cookie in a cross-site iframe, Graphlytic must be served over HTTPS (the cookie uses SameSite=None; Secure), and the browser must permit third-party cookies for the Graphlytic domain.

2. Iframe setup

Every time a new page should be displayed in the iframe, a new URL link should be created and used as the "src" attribute of the iframe HTML element. (example: <iframe id="graphlytic_frame" src="https://my.graphlytic.org/visualization?vis=1&p=1&username=read-only-user&password=userPassword123" width="1024" height="100%" title="description"></iframe>).
The sections below describe HTML tag attributes and the src URL parameters.

2.1. Iframe HTML tag attributes

Attribute

Example value

Description

id

graphlytic_frame

ID of the iframe HTML element. Can be used for later reference, e.g., for "src" changing (reloading the page in the iframe).

title

Optional title for the HTML element.

src

mandatory

https://my.graphlytic.org/

See URL parameters below.

width

1024, 100%

Width of the embedded frame.

height

1000, 80%

Height of the embedded frame.

2.2. URL parameters

For the iframe's source URL, use the URL of the Graphlytic instance that should be embedded. Always use the "HTTPS" protocol because "HTTP" is not allowed in some browsers, e.g., Chrome. 

When using a reverse proxy in the infrastructure, please ensure the HTTP/HTTPS scheme is correctly set in the request headers to avoid "mixed content" errors in browsers (e.g., Chrome).

There are several URL parameters that can be used to trigger different behavior of the embedded application:

  • username and password - authentication credentials used to automatically log in the user (skip the login page).

  • hide-header - if true, then the application header will be hidden.

  • suppress-before-unload-warning - if true, then the application will not show a browser-generated confirmation dialog that asks users to confirm if they really want to leave the page when they try to close or reload it, or navigate somewhere else.

  • other parameters to automatically load elements into the visualization - see Create a Visualization with URL Parameters for the list of all possible URL parameters.

Note that the "&username=admin&password=admin" part of the URL will automatically authenticate the user with 'username' and 'password'.

It is strongly advised to use credentials with read-only access rights.

2.3. Recommendations

To achieve a better user experience, it's recommended to configure the following:

  1. Turn off the display of the "first-time usage" hints on visualization load, because every iframe reload is treated as "first-time usage," and the hints are shown every time. To turn the hints off, add "showHintsOnInit":false to the global GENERAL setting.

  2. Turn off the info panel's initial display in Graphlytic. This will allow the visualization to be shown on the largest area possible. To turn it off, add "showInfoPanelOnInit":false to the global VISUALIZATION setting.

2.4. Examples

Example of the HTML code for iframe embedding

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
</head>
<body>
 <iframe id="graphlytic_frame" src="https://my.graphlytic.org/visualization?vis=1&p=1&username=read-only-user&password=userPassword123" width="1024" height="100%" title="description"></iframe>
</body>
</html>

Example of the "src" attribute change (resulting in frame page reload) using JavaScript

document.getElementById('graphlytic_frame').src = "https://my.graphlytic.org/visualization/?cq=MATCH%28n%3ALabel%29RETURN%20n%20LIMIT%2025";

3. Sample application

Here's an example of a simple HTML webpage that consists of:

  • Left panel with a list of a few nodes from our IT infrastructure knowledge graph.

  • Right panel, where a Graphlytic visualization will be dynamically created every time the user clicks on a node in the list.

3.1. Graphlytic iframe embedding example source code

<html>
<head>
<style>
body{ margin: 0; background-color: #ddd; }
.nodeSelector{ width: 19%; height: 100%; display: inline-block; font-family: Arial; }
.title{ font-size: 16px; font-weight: bold; margin: 15px; }
.nodeToClick{ padding: 15px; font-size: 12px; }
.nodeToClick:hover{ background-color: #eee; cursor: pointer; }
#graphlytic_frame{ border: none; float: right; width: 80%; height: 100%; display: none; }
</style>
<script>
function nodeClicked(uuid){
let cypher = encodeURI('MATCH p=(n)-[r*1..8]->(b) WHERE n.uuid="' + uuid + '" RETURN p');
let graphlytic = document.getElementById('graphlytic_frame');
graphlytic.style.display='block';
graphlytic.src = "https://your.graphlytic/visualization/?cq=" + cypher;
}
</script>
</head>
<body>
<div class="nodeSelector">
<div class="title">Visualize infrastructure for a selected node</div>
<div href="#" onClick="nodeClicked('7b30a949-5b15-4705-a92a-fa7e1538365f')" class="nodeToClick">
Application Component 9445
</div>
<div href="#" onClick="nodeClicked('3f1f3064-d79f-4307-865d-6971df81e6c9')" class="nodeToClick">
Database 55426
</div>
<div href="#" onClick="nodeClicked('a40214d4-277f-438a-8b53-48f92f95ba5a')" class="nodeToClick">
Failover Cluster 239540
</div>
<div href="#" onClick="nodeClicked('6cb9af3c-24ed-43d7-9da2-05eeec355cbf')" class="nodeToClick">
Security Device 94387
</div>
</div>
<iframe id="graphlytic_frame"
src="https://your.graphlytic/visualization?username=admin&password=admin">
</iframe>
</body>
</html>