Embedding via iframe
Txture allows reports to be shared with external individuals via URL or to be embedded in existing portal applications or wikis, i.e. via HTML iframes.
Authentication
To access the shared information the user needs to be authenticated. Depending on the type of access, multiple options can be used:
-
Option 1: Shared via URL: For this type of sharing, any authentication method can be used (OAuth, SSO or API-Token in the URL). In the first two cases users will be automatically authenticated if they reach an embedded report. Keep in mind that the report still has to be shared with the correct roles or users within Txture. Make sure you set the correct redirect URLs at your OAuth provider.
-
Option 2: Embedding in an iframe: Due to the design of OAuth it is not possible to embed reports in an iframe. Therefore it is best to use an API-Token in the URL for this kind of report sharing.
Sharing Reports
Accessing a Report's URL
Regardless of the option you choose, you have to obtain the URL of the report by navigating to Main Menu / Reports → Manage Reports and search for the report to be embedded.
You can then click on the share nodes to bring up the report sharing dialog.
This menu shows the report URL and optionally also generates the embed URL (with or without API token authentication).
Alternatively, you can also click on the menu in the upper right corner of the report and choose to open the report in a new tab, which will show the URL in the browser's address bar.
Format of a URL with an API-Token
If option 2 was chosen, you can either manually modify the URL to include the API token or do so directly in Txture by selecting an API token. Without an API token, your URL should look something like this:
https://txture-server-url/embed.html#/report/d:<report_id>/master/
If it includes an API token, it will show the part ?access_token=API_TOKEN in the URL:
https://txture-server-url/embed.html?access_token=API_TOKEN#/report/d:<report_id>/master/
You can also simply replace place holder API_TOKEN with your actually API Token. Make sure you only replace the exact words "API_TOKEN" with your actual token!
The resulting URL allows accessing the report with the permissions of the role assigned to the API Token. Make sure these are sufficient to access the report while ensuring only absolutely necessary permissions are assigned.
Sharing Report Templates
A special case arises if the report in question is a Report Template. In this case the variables used in the report template also have to be given when embedding the report template. This is done in a similar way as the API Token above:
https://txture-server-url/embed.html#/report/d:<report_id>/master?variable_name_1=value&variable_name_2=value
All variables and their value are encoded in the form variable=value and appended to the URL separated by &.
Note that this also applies to the API token (in case it is required):
https://txture-server-url/embed.html#/report/d:<report_id>/master?access_token=API_TOKEN&variable_name_1=value&variable_name_2=value
Depending on the variable type the following formats are expected:
| Variable type | Example value | Description |
|---|---|---|
| Asset | t:83c6b447-c455-4e32-a508-04eb3740cb55 | For assets, the txtureID is required. You can display txtureIDs of assets in a column in the table report. |
| Date | 2019-08-13 | Date in ISO 8601 format. Example is the 13th of August 2019 |
Sharing Assets and Links
The detail pages of a single asset or link can also be embedded via the following URLs:
// the current state of an asset or link:
https://txture-server-url/embed.html#/asset/<id>?access_token=API_TOKEN
https://txture-server-url/embed.html#/link/<id>?access_token=API_TOKEN
// the asset or link at a certain time (in the past)
https://txture-server-url/embed.html#/asset/<id>/master/<timestamp>?access_token=API_TOKEN
https://txture-server-url/embed.html#/link/<id>/master/<timestamp>?access_token=API_TOKEN
The individual URLs can be accessed via open in new window feature in the Asset Detail Sidebar .
Sharing Structure
For documentation purposes the current Structure can be embedded as well:
https://txture-server-url/embed.html#/structure?access_token=API_TOKEN