Embedding ITAM Content

ITAM

ITAM web pages and elements thereof can be embedded in external web pages using an Inline Frame, or “iframe”. This allows you to wrap ITAM content within a page design that is consistent with your organization's web site. Navigation within the embedded frame will remain on the ITAM pages, while navigation outside the frame is controlled by the embedding page.

It is also possible to embed individual Dashboard widgets on an external web page. Because Dashboard widgets are not stand-alone pages within ITAM the mechanism for embedding them is slightly different. Furthermore, each embedded widget requires certain parameters in order to control display and behavior.

Required Security Settings

In order to embed our web content successfully on 3rd party sites with modern browser and server security, you will need to add a CSP entry into your instance's Settings. Navigate to Settings -> Network and scroll down to the CSP settings at the bottom. Under the hosts that are allowed to embed portion, put in the DNS name for the server that will embed the content from ITAM. Note you can use a wildcard to cover your domain such as *.mydomain.com

Additionally, in order to embed 3rd party content into our widgets (i.e. using an iframe in the generic html widget) you need to specify hosts from which embedded content are allowed.

Embedding Basics

To embed a page or element you add an iframe to your external web site page using HTML markup like this:

<iframe
	src="//keyserver.sample.net/frame-body/public/maps.html"
	seamless="seamless"
	height="500px"
	width="100%"
	frameborder="0"
	>
</iframe>

You can use any iframe attributes and style that you need, but three attributes are important to understand. The seamless="seamless" attribute makes the frame look more like part of the page, and is generally recommended. The height="500px" attribute can have any value, but should be large enough to accommodate the content. If the content does not fit in the iframe height, the browser will show a scroll bar. It is also possible to use JavaScript to size the iframe dynamically depending on the browser window size. Any such JavaScript would exist in the embedding page, and is left up to you to implement.

The third and most important attribute is the URL of the page or content you want to embed. For example, let's say you want to embed the Availability Maps main (list) page, That page has a URL similar to:

//keyserver.sample.net/maps.html

Embedding with page content only

All ITAM pages have top and side navigation elements. It's common to want to remove those when you're embedding the content. There are two options for this.

To embed a page without the main navigation elements you would need to add /frame-body to the URL, as shown in bold here:.

//keyserver.sample.net/frame-body/maps.html

This pattern can be applied to any page, and that page's title and content will appear within the iframe on your external page.

To embed this page with only the content you would need to add /frame-core to the URL as shown here:

//keyserver.sample.net/frame-core/maps.html

This pattern can be applied to any page, and that page's content will appear within the iframe on your external page.

Note how there is no longer the toolbar in this case. Depending on the page or element you embed, the nature of the ribbon/tool bar that shows in the frame-body but not the frame-core will differ.

Tips on the src attribute

In the examples above you might have noticed we left out the “scheme” — the http: or https: — in the iframe src attribute URLs. When the scheme is not present in a URL, the browser will use the scheme of the page containing that URL. So if your external page is accessed using http:, the embedded page will also be accessed using http:. Normally it is good practice to leave out the scheme so that the embedding and embedded pages are accessed in a consistent manner. However, sometimes this is not desirable. For instance, if you only run ITAM on HTTPS (a best practice these days), but your external pages can be accessed over HTTP, you should include https: in the iframe src attribute.

If ITAM is running on non-standard ports (on prem only), the src attribute URL must include the proper port. For example, if you run ITAM on port 8080 you must specify that in the iframe src attribute:

http://keyserver.sample.net:8080/frame-body/maps.html

Or similarly if SSL is configured for a non-standard port, let's say 8443:

https://keyserver.sample.net:8443/frame-body/maps.html

In both of these cases we are required to include the URL scheme so the browser knows whether or not to initiate a secure connection on the non-standard port. As explained above, when the URL scheme is included, the embedded page will be accessed in that manner regardless of the scheme used to access the embedding page.

Embedding individual Floorplans

Above we talk about embedding the entire Maps page in another webpage, but you may want to embed individual Floorplans only. The process is the same, you just need to navigate down to the individual Floorplan to get its ID URL. For example, if you go to a floorplan and see it has a URL like this:

https://keyserver.sample.net/maps/std/8f8aa9b7cbbda744bb3cd65b43613f78

Then to embed that floorplan you insert the frame-core into the URL like this:

https://keyserver.sample.net/frame-core/maps/std/8f8aa9b7cbbda744bb3cd65b43613f78

Which will result in the floorplan with any enabled legend, forecast, and map, but without the ribbon, navigation, toolbar, etc.

You can also use the frame-body option thus:

https://keyserver.sample.net/frame-body/maps/std/8f8aa9b7cbbda744bb3cd65b43613f78

Which will add the Ribbon that has the options for heat maps, software search, etc.

Another option is to append /embed.html on the end of the URL thus:

https://keyserver.sample.net/maps/std/8f8aa9b7cbbda744bb3cd65b43613f78/embed.html

This will result in the Floorplan only, with no legend, forecast, or map. Clicking on the floorplan will take you to the full website page for that floorplan.

Finally, you can also embed a floorplan in list view instead of floorplan view by appending ?list=1 on the end of the map url (combining with either frame example above, but not embed.html) for something like this:

https://keyserver.sample.net/frame-core/maps/std/8f8aa9b7cbbda744bb3cd65b43613f78?list=1

There are other options you can append as well, most with multiple variables:

auto=1 - turn on auto refresh
status=free|used|down|gone - show only a certain status. multiple values can be specified as in stat=freedown
sort=stat|name|osys - to set sort order by name, status, or OS
plat=mosx|wind|unix - show only a given OS type. multiple values can be specified as in plat=mosxwind
heat=pd|pw|pm - turn on display of heatmaps for the previous day, week, or month

You can string these together with & like ?list=1&auto=1&status=free to have a list of only available machines that auto refreshes.

Embedding Other Pages

The above methods of adding frame-body and frame-core to a url for maps also works for other page types in. Note these parameters are always added between the server name and the rest of the URL, i.e. before /maps or /software etc.

Software List

You can embed the Software list with the above methods. This gives you a clean list with (frame-body) or without (frame-core) the Publisher and Category tabs at the top.
In addition, it's possible to embed a scoped software list, but getting the URL is a bit more challenging due to how the scope is applied. With a scope (e.g. for a Division) in place, open the inspector/developer tools of the browser to view the page code and find the data-link-scope url. You can then add the body or core parameter as needed.
In Chrome for example:

With the Software page scoped as desired, go to the "Tools" drop down (dot menu at the far end of the bar) to More Tools -> Developer Tools
Make sure the Elements tab is selected at the top and you see the html code.
Right click in the code and Copy Element
Paste into a text editor and scroll to the top
You should see something like this in the body tag that you can copy the url from:

data-link-scope="http://localhost/software?setscope=eyJpZCI6IjM4YTQwODllYWY0Mjg5YjNlOGQwYmU0NmVmZTE0ZjgzIiwidHlwZSI6Im1hcCIsIm5hbWUiOiJBRFJJIiwiZGVzYyI6IkRpdmlzaW9ucyAvIEFEUkkiLCJzZXRpZCI6InN0ZCIsInNldCI6IkRpdmlzaW9ucyIsImNzdCI6ImRpdm4iLCJwaWQiOiIweDAwMDBGRkUxIiwicG5hbWUiOiJBRFJJIn0"

Saved Reports

It's also possible to embed a saved report using the body and core methods. When you run a report you will see it has a very long URL that is the report parameters. If the report is saved to run on a Schedule (so data gets refreshed daily/weekly/as desired) in a folder that has permission to Viewers (of which the "KeyReporter Guest" should be a member, see Accounts and Report Builder for more details) then it will self update on the schedule and be visible to guest view. At that point, adding the frame-core to the report URL and embedding it will give you a display of the report results.

Embedding individual Dashboard widgets

There are two ways to embed widgets on a web page. This first method is the simplest to set up and is the most compatible since it isolates each widget from your main page, but is inefficient if you plan to load more than one widget on a particular page. Behind the scenes, this method will create an Inline Frame, or “iframe” into which the widget will be loaded. The first requirement is that your page load some JavaScript files from the ITAM host. These scripts are loaded within the element as follows:

<body>
<script type="text/javascript" src="//keyserver.sample.net/include/js/jquery.min.js"></script>
<script type="text/javascript" src="//keyserver.sample.net/include/js/krf-embed.js"></script>

Note that if your page already loads any version of jQuery you do not have to load that file from the host.

The script loaded in the krf-embed.js file will scan your page for widgets to embed, and create an iframe for each. First, the script needs to know where the host is located. You indicate the host by adding the following HTML element anywhere on your page:

<div id="kr-info" data-kr-host="//keyserver.sample.net" />

Each widget you want to load is described in a separate <div> element. The div element should be empty initially, but can be contained within any other HTML markup you require in order to place it on the page.

The embedding element for any widget can be copied from the widget's Settings window. First add the widget to a dashboard in ITAM and set the size as desired for the final display. Click the Gear icon to configure it how you want (scope, theme, etc), then click the Embed tab (the < > tab on the far right). Copy the text that appears and use it to embed the widget in an external page, as described above. You can remove the widget from the dashboard without affecting the embedded widget.

There are three important parts to the embedding element. First, the element must have the kr-embed class. This class is used by the embed script to find the widgets to be embedded. Second, the widget's internal ID must be provided in the data-krw-id attribute. This ID is different for each widget, and can be found in this list of Widgets. Third, the display dimensions for the widgets must be specified. In this example the dimensions are given in the style attribute, but they can also come from a CSS rule or other source.

The example also has two optional attributes: data-krw-title for the widget title, and data-krw-theme for the widget theme. The title is used in case the widget is not available from ITAM, and otherwise is ignored. The theme is used to change the colors of the widget, as can be done on the main Dashboard.

Embedding multiple widgets on the same page

When you are embedding multiple widgets in the same page, it is most efficient for page rendering if those widgets can share the various scripts and style sheets that are loaded from ITAM. The information below differs from that above in a couple places to improve that page performance. One potential pitfall is that these resources might conflict with the scripts that are loaded by your external web page. This method will load jQuery, which is a widely used JavaScript library that you might already use on your page. Also, the Bootstrap CSS framework is loaded. If neither of these will conflict with your external page, this is the best method to use for embedding (otherwise you can use the iframe-based method described above to embed multiple widgets on a single page).

The first requirement is that your ITAM instance must be configured to support Cross-Origin Resource Sharing (CORS). To do this, again navigate to Settings -> Network and at the bottom you'll find the hosts from which these resources are allowed section. In the Scripts box once again enter the server DNS name that will be accessing these jquery scripts. In this case, it is highly advised you enter a specific DNS name, not a wild card entry.

Next, you can configure your external page. The page must load a style sheet from the ITAM host. The style sheet is loaded within the <head> element as follows:

<head>
<link href="//keyserver.sample.net/include/css/kr-embed.css" rel="stylesheet">

Your page must also load some JavaScript files from the ITAM host. These scripts are loaded within the <body> element as follows:

<body>
<script type="text/javascript" src="//keyserver.sample.net/include/lang/kr.dash-en.min.js"></script>
<script type="text/javascript" src="//keyserver.sample.net/include/js/kr.embed.min.js"></script>

The script loaded in the kr-embed.js file will scan your page for widgets to embed. First, the script needs to know where the ITAM host is located. You indicate the host by adding the following HTML element anywhere on your page:

<div id="kr-info" data-kr-host="//keyserver.sample.net" />

The embedding element for any widget can be copied from the widget's Settings window. First add the widget to a dashboard in ITAM, configure it how you want it to appear, then click the Embed tab in the Settings window. Copy the text that appears and use it to embed the widget in an external page, as described above. You can remove the widget from the dashboard without affecting the embedded widget.

Embedding in TDx Work Management

TD Work Management has the ability to embed content in Dashboards and portal pages as well. This allows you to embed maps, software lists, widgets, and other elements in your TDx WM Dashboard or portal pages.

For more information on embedding in Work Management , see this article.

Briefly, you can navigate to TDAdmin -> Organization Settings -> HTML Content Allowlists -> Iframe Sources and enter the address of your ITAM server.

Then to make an embed, navigate to TDAdmin -> Dashboard Templates -> HTML Modules -> New and click the Source button and put in something like:

Then navigate to TDNext -> Desktop, and click "edit blah Desktop" near the top, and your new embed would be a choice in possible content.

Using the KML Feed

ITAM also has a KML feed for use in mobile apps like Modo or other mapping technologies like Google Maps. The syntax for the map feed is simply kml.xml at the end of the individual Map Set url. For example, the default map set is always std (standard) so the kml feed is at https://myserver.com/maps/std/kml.xml. Other map sets will have their name in the url.

0 reviews

Print Article

Updating...