EmbedManager Methods

Describes the supported eventManager JavaScript methods

The following EmbedManager methods can be used to manage embedded Self-Service Analytics components. Sample code showing the use of these methods in an application are provided. See Embedded JavaScript Examples for a complete example of how these methods might be coded in JavaScript.

Method	Description
createComponent()	Creates a Self-Service Analytics component in your application. This method is asynchronous and returns a promise that resolves the created component. The parameters input to this method include: a string that identifies the type of component you want created (the component types currently supported are dashboard and visual-builder). An error occurs if an invalid component type is specified. the configuration of the component, which includes the properties described in Embedded Dashboard Properties and Objects and Embedded Visual Authoring Properties and Objects. Use a standard render method (for example, dashboard.render or visualBuilder.render) to render the component in your application after it has been created. Examples are provided in Embedded JavaScript Examples. The following example embeds a dashboard: const dashboard = await embedManager.createComponent('dashboard', { dashboardId: <id>, theme: 'composer', interactivityProfileName: '<interactivity-profile-name>', interactivity { settings:{ CHANGE_LAYOUT: "true", }, visualSettings:{ FILTER: "false", overrideVisualInteractivity: "true", }, } editor: { placement: 'dockRight' // use eve sidepanel }, header: { visible: true, showTitle: true, showActions: false, // will hide actions bar title: "Static custom title" } });
getComponentById()	Returns an instance of a Self-Service Analytics component, based on its component instance ID. The parameter input to this method is a string representing the component instance ID. async function getComponent(<componentInstanceId>) { const embedManager = await createOrGetEmbedManager(); return embedManager.getComponentById(<componentInstanceId>); }
refresh()	Refreshes all embedded components. This is useful when the token is expired. No parameters are passed to this method. async function refreshComponent(<newToken>) { const embedManager = await createOrGetEmbedManager(); embedManager.updateToken(<newToken>).then(() => { embedManager.refresh(); }); }
refreshComponent()	Refreshes a particular component. The parameter used with this method is a string representing the component instance ID. The following example refreshes a specific dashboard: async function refreshDashboard(<newToken>, <componentInstanceId>) { const embedManager = await createOrGetEmbedManager(); embedManager.updateToken(<newToken>).then(() => { embedManager.refreshComponent(<componentInstanceId>); }); }
refreshWithToken()	Combines an update token and refresh request for all components. The parameter input to this method is a string representing the new token. async function refreshComponent(<newToken>) { const embedManager = await createOrGetEmbedManager(); embedManager.refreshWithToken(<newToken>); }
removeComponent()	Removes an embedded component from your application. This method returns the value true when the removal is successful and false when it fails. When a component is removed, its watchers are also removed. The parameter input to this method is a string representing the component instance ID. async function clearComponent(id) { const embedManager = await createOrGetEmbedManager(); embedManager.removeComponent(<componentInstanceId>); }
updateToken()	Refreshes the authorization token for an embedded component. This method is asynchronous and should be called prior to a refresh. The parameter input to this method is either a string representing the new token or a function requesting a new token. async function refreshDashboard(<newToken>) { const embedManager = await createOrGetEmbedManager(); embedManager.updateToken(<newToken>).then(() => { embedManager.refresh(); }); }

Embedded Dashboard Properties and Objects

Properties can be passed as parameters to the createComponent method when embedding dashboards.

Here is a sample embedding "componentInstanceId":"<id>":

embedManager.createComponent('dashboard',
	const componentConfig = {
		"dashboardId": "<dashboard-ID>",
		"componentInstanceId":"<component-instance-ID>",
	}
);

The following table describes available options for these properties and objects.

See: dashboardId, componentInstanceId.

Property/Object	Default	Description
"dashboardId":"<dashboard-ID>"	none	The dashboard ID. If no dashboard ID is specified, an empty dashboard is embedded. Type: string
"componentInstanceId":"<component-instance-ID>"	none	The instance ID for the dashboard is generated when the dashboard is created. Type: string

Here is a sample embedding "type":

embedManager.createComponent('dashboard',
	const componentConfig = {
		"dashboardId": "<dashboard-ID>",
		"componentInstanceId":"<component-instance-ID>",
		"type":"dashboard",
	}
);

The following table describes available options for these properties and objects.

See: type.

Property/Object	Default	Description
"type":"dashboard"		The type of embedded component.

Here is a sample embedding "application":

embedManager.createComponent('dashboard',
	const componentConfig = {
		"dashboardId": "<dashboard-ID>",
		"componentInstanceId":"<component-instance-ID>",
		"type":"dashboard",
		"application":{
			"banner":false,
			"logo":true
		}
	}
);

The following table describes available options for these properties and objects.

See: application.banner, application.logo.

Property/Object	Default	Description
"application.banner": true	false	Indicates whether the top-level navigation banner should be shown with the embedded dashboard. Valid values are true or false. Type: boolean This property is deprecated and will be removed in a future release.
"application.logo": true	false	Indicates whether the logo should be shown with the embedded dashboard. Valid values are true or false. Type: boolean This property is deprecated and will be removed in a future release.

Here is a sample embedding "interactivityProfileName":

embedManager.createComponent('dashboard',
	const componentConfig = {
		"dashboardId": "<dashboard-ID>",
		"componentInstanceId":"<component-instance-ID>",
		"type":"dashboard",
		"application":{
			"banner":false,
			"logo":true
		}
		"interactivityProfileName":"interactive",
	}
);

The following table describes available options for these properties and objects.

See: interactivityProfileName.

Property/Object	Default	Description
"interactivityProfileName":"interactive"	interactive	Determines the way in which your users will be able to work with the embedded dashboard. Valid values are readonly and interactive. If you do not want the user of your application to change anything and only be able to view the dashboard, specify readonly. If you want your users to be able to make changes to the dashboard, specify interactive. When the mode is readonly, the dashboard cannot be changed. This setting is backward-compatible with the interactive option for public shared link embeds. If you are migrating to Self-Service Analytics’s JavaScript embed technology, specify interactive for this setting to ease the migration. Type: string

Here is a sample embedding "interactivityOverrides":

embedManager.createComponent('dashboard',
	const componentConfig = {
		"dashboardId": "<dashboard-ID>",
		"componentInstanceId":"<component-instance-ID>",
		"type":"dashboard",
		"application":{
			"banner":false,
			"logo":true
		}
		"interactivityProfileName":"interactive",
		"interactivityOverrides":"<interactivity-overrides-ID>",
	}
);

The following table describes available options for these properties and objects.

See: interactivityOverrides.

Property/Object	Default	Description
"interactivityOverrides":"<interactivity-overrides-ID>"	none	Specifies specific dashboard and visual interactivity settings for an embedded dashboard. The visual interactivity settings specified in this object will override any interactivity settings specified for the individual visuals. These settings will also override the dashboard interactivity profile linked to the dashboard (the one saved with the dashboard) and the dashboard interactivity profile passed by the interactivityProfileName property. Type: object

Here is a sample embedding "mode":

embedManager.createComponent('dashboard',
	const componentConfig = {
		"dashboardId": "<dashboard-ID>",
		"componentInstanceId":"<component-instance-ID>",
		"type":"dashboard",
		"application":{
			"banner":false,
			"logo":true
		}
		"interactivityProfileName":"interactive",
		"interactivityOverrides":"<interactivity-overrides-ID>",
		"mode":"interactive",
	}
);

The following table describes available options for these properties and objects.

See: mode.

Property/Object	Default	Description
"mode":"interactive"	interactive	When a dashboard interactivity profile is specified (using the interactivityOverrides object or the interactivityProfileName parameter), the mode parameter is ignored. The mode parameter is also deprecated in Self-Service Analytics and will be removed in a future release. Type: string

Here is a sample embedding "theme":

embedManager.createComponent('dashboard',
	const componentConfig = {
		"dashboardId": "<dashboard-ID>",
		"componentInstanceId":"<component-instance-ID>",
		"type":"dashboard",
		"application":{
			"banner":false,
			"logo":true
		}
		"interactivityProfileName":"interactive",
		"interactivityOverrides":"<interactivity-overrides-ID>",
		"mode":"interactive",
		"theme":"modern",
	}
);

The following table describes available options for these properties and objects.

See: theme.

Property/Object	Default	Description
"theme":"dark"	composer	The theme for the embedded visual. Valid values are d+a_light, __platform__, composer, modern, dark. The initial default theme, composer, is the same as the modern theme. However, if you add your own themes to the application, more options are available in this list and you may have introduced a different default. Type: string

Here is a sample embedding "editor":

embedManager.createComponent('dashboard',
	const componentConfig = {
		"dashboardId": "<dashboard-ID>",
		"componentInstanceId":"<component-instance-ID>",
		"type":"dashboard",
		"application":{
			"banner":false,
			"logo":true
		}
		"interactivityProfileName":"interactive",
		"interactivityOverrides":"<interactivity-overrides-ID>",
		"mode":"interactive",
		"theme":"modern",
		"editor":{
			"placement": "docRight"
		}
	}
);

The following table describes available options for these properties and objects.

See: editor.placement.

Property/Object	Default	Description
"editor.placement":"docRight"	modals	Indicates where the dashboard editor appears. Valid editor placements are dockRight and modals. Type: string

Here is a sample embedding "header":

embedManager.createComponent('dashboard',
	const componentConfig = {
		"dashboardId": "<dashboard-ID>",
		"componentInstanceId":"<component-instance-ID>",
		"type":"dashboard",
		"application":{
			"banner":false,
			"logo":true
		}
		"interactivityProfileName":"interactive",
		"interactivityOverrides":"<interactivity-overrides-ID>",
		"mode":"interactive",
		"theme":"modern",
		"editor":{
			"placement": "docRight"
		}
		"header": {
			"title": "My Dash"
			"showActions": false,
			"showTitle": false,
			"visible": false
		}
	}
);

The following table describes available options for these properties and objects.

See: header.title, header.showActions, header.showTitle, header.visible.

Property/Object	Default	Description
"header.title":"<newtitle>"	none	Allows you to overwrite the title of the embedded dashboard. The embedded dashboard title is read only; it cannot be changed while the dashboard is embedded. Type: string
"header.showActions": false	true	Indicates whether dashboard actions should be visible for the embedded dashboard. Valid values are true or false. Type: boolean
"header.showTitle": false	true	Indicates whether the dashboard title should be shown for the embedded dashboard. Valid values are true or false. Type: Boolean
"header.visible": false	true	Indicates whether the dashboard header should be shown for the embedded dashboard. Valid values are true or false.

Here is a sample embedding "intialFilters":

intialFilters: {
	sourceId: "<source-id>"
	timeFilter: {
		from: "+$start_of_data",
		to: "+$end_of_data",
		timeField: "_saledate",
		},
	filters: [{
		"operation": "BETWEEN"
		"paths": "returns",
		"value": [ 1, 25 ]
	}]
}

The following table describes available options for these properties and objects.

See: initialFilters, applyFiltersStrategy.

Property/Object	Default	Description
initialFilters	none	Allows you to pass initial filters to the specified dashboard. Pass parameters for filters, sourceId, timeFilter, and applyFiltersStrategy. Type: string
applyFiltersStrategy	overrideSamePath	Use overrideSamePath to overwrite filters using the same path. Use replaceExisting to remove all filters and use only defined initialFilters.

You can also refresh your data in the dashboard as needed.

Method	Description
component.refreshData()	Refreshes data in the dashboard when called.

Embedded Library Properties and Objects

The library embed feature also includes pre-defined actions for adding a dashboard and opening a dashboard.

Here’s what you can do with pre-defined actions:

• Specify an action for embed action
• Specify an action for navigate to link
• Change a cursor if a column has onClick action specified
• Pass an item id to the link (“https://dashboards.company.com/edit/\${inventoryitemId}”)
• Filter dashboards by dashboard tags (See Embed Components Using JavaScript and Trusted Access)

The following Actions are supported:

Action
Embed
Open

Below is a code sample for using the onClick property:

Type	Example
FunctionClickHandler	(data?: InventoryItem) => console.log(data)
EmbedClickHandler	{ type: "embed", parentElement: "#editor-container", // OR document.querySelector("#editor-container") replaceComponent: true, componentParams: { ... } }
LinkClickHandler	{ type: "link", href: "https://dashboards.com/edit/${inventoryItemId}", target: "_blank" }

Embedded Source Inventory Properties and Objects

The source inventory embed feature allows you to define the look and feel of the Sources page for your embedded users.

When you embed a list of sources, you can define which columns to include, order them in your preferred layout, and define what controls are available by enabling and disabling interactivity settings. Your users can filter sources, search for sources, and add sources to favorites.

Use the InteractivityValue property to specify interactivity parameters for the sources inventory.

Parameter	Description
"ADD_NEW": true	When set to true, users can create a new data source configuration. When set to false, the button to create a new data source is hidden. Type: boolean
"FILTER": true	When set to true, users can filter sources using the quick filter icons to the left of the Search field on the sources page. When set to false, they cannot filter sources. Type: boolean
"DELETE": true	When set to true, users can delete data source configurations not currently in use by a visual. When set to false, they cannot delete data source configurations, and the delete icon is not visible in the UI. Type: boolean
"DESCRIPTION": true	When set to true, users can view and search for items (sources, visual gallery visuals, dashboard or self-service report in the library) by the contents of an item’s description. When set to false, description options are not available to users. Type: boolean
"EXPORT": true	When set to true, users can export data source configurations. When set to false, users cannot export data source configurations, and the option is not visible in the UI. Type: boolean
"PERMISSIONS": false	When set to true, users can manage user and group permissions for data sources. When set to false, they cannot manage permissions for data sources, and the related icons are not visible in the UI. Type: boolean
"FAVORITES": true	When set to true, users can mark the data source as a favorite. When set to false, they cannot mark data source favorites and the favorites icons are not visible in the UI. Type: boolean
"ROW_SECURITY": false	When set to true, users can define row security for data sources. When set to false, they cannot define row security for data sources, and the related icons are not visible in the UI. Type: boolean
"COLUMN_SECURITY": false	When set to true, users can define column security for data sources. When set to false, they cannot define column security for data sources, and the related icons are not visible in the UI. Type: boolean
"CLEAR_CACHE": true	When set to true, users can clear the cache for a data source. When set to false, users cannot clear the cache for a data source and the related icons are not visible in the UI. Type: boolean
"AVAILABLE_VISUAL_TYPES": true	When set to true, users invoke the Available Visual Types work area to enable and disable available visual types for a source. When set to false, they cannot affect available visual types, or see related icons are not visible in the UI. Type: boolean

Embedded Visual Authoring Properties and Objects

The following properties can be passed as parameters to the createComponent method when embedding visual authoring components.

Here is a sample.

This example assumes that the EmbedManager has already been initialized, and the ID of a visual template is passed.

const getToken = async () => { const response = await fetch('<playground-uri-and-username-token>', { method: 'GET', credentials: 'same-origin' }); return response.json().then((result) => { return { access_token: result.token, expires_in: result.expiresIn, }; }); }; const embedManagerPromise = window.initComposerEmbedManager({ getToken: getToken }); const componentConfig = { "theme":"modern", "header": { "showTitle": false, "visible": false, "showActions": false, "title": "<title-text>", } } const createEmbedComponent = (embedManager, config, containerElementId = 'widget-holder') => { embedManager.createComponent("visual-builder", config).then(component => { component.render(document.getElementById(containerElementId), { width:"100%", height: "100%" }); }) } embedManagerPromise.then(embedManager => { createEmbedComponent(embedManager, componentConfig, 'widget-holder'); });

The following table describes the available properties for componentConfig.

See: theme.

Property/Object	Default	Description
"theme":"dark"	composer	The theme for the embedded visual. Valid values are d+a_light, __platform__, composer, modern, dark. The initial default theme, composer, is the same as the modern theme. However, if you add your own themes to the application, more options are available in this list and you may have introduced a different default. Type: string

The following table describes the available header properties.

See: showTitle, visible, showActions, title.

Property/Object	Default	Description
"showTitle": true	true	Indicates whether the visual header title should be shown for the embedded visual. Valid values are true or false. Type: boolean
"visible": false	true	Indicates whether the visual header should be visible for the embedded visual. Valid values are true or false. Type: boolean
"showActions": false	true	Indicates whether the visual header actions should be shown for the embedded visual. Valid values are true or false. Type: boolean
"title": <text>	none	Specifies a static title for the visual. Type: string

The following table describes the available breadcrumb properties.

See: breadcrumbs.onClick, breadcrumbs.target, breadcrumbs.title.

Property/Object	Default	Description
<optional breadcrumb properties>		Optional breadcrumb properties are described in Optional Embedded Visual Authoring Breadcrumb Properties.
"breadcrumbs.onClick"	none	The click action handler for the breadcrumb title. Type: function
"breadcrumbs.target":"_blank"	none	The link target parameter. Use "_blank" to open in a new tab. A valid link target should be specified in quotes ("<target>"). Type: string
"breadcrumbs.title":"<title>"	none	The first item breadcrumbs title. A valid title should be specified in quotes ("<title>"). Type: string

The following table describes the available properties for source visualID.

See: source.visualId, interactivityOverrides, visualId.

Property/Object	Default	Description
"source.visualId":"<id>"	null	The source ID of a visual template, used for creating a new visual in visual authoring. This represents a predefined visual template. A valid source ID should be specified in quotes ("<source-visual-ID>"). If neither visualId or source.visualId is specified, an empty visual authoring instance will be opened. If both are provided, visualId is used. Type: string
"interactivityOverrides"	none	Specifies interactivity override settings for visual authoring. The interactivity settings specified in this object will override any interactivity settings specified for the individual visuals. For a list of visual interactivity settings you can specify, see Control How Users Interact With a Visual. Type: object
"visualId":"<id>"	null	The visual ID for an existing visual for visual authoring. A valid visual ID should be specified in quotes ("<visual-ID>"). If neither visualId or source.visualId is specified, an empty visual authoring instance will be opened. If both are provided, visualId is used. Type: string

The following table describes all of the available properties.

Property/Object	Default	Description
<optional breadcrumb properties>	Optional breadcrumb properties are described in Optional Embedded Visual Authoring Breadcrumb Properties.
"breadcrumbs.onClick"	none	The click action handler for the breadcrumb title. Type: function
"breadcrumbs.target":"_blank"	none	The link target parameter. Use "_blank" to open in a new tab. A valid link target should be specified in quotes ("<target>"). Type: string
"breadcrumbs.title":"<title>"	none	The first item breadcrumbs title. A valid title should be specified in quotes ("<title>"). Type: string
"header.showActions": false	true	Indicates whether the visual header actions should be shown for the embedded visual. Valid values are true or false. Type: boolean
"header.showTitle": false	true	Indicates whether the visual header title should be shown for the embedded visual. Valid values are true or false. Type: boolean
"header.title": <text>	none	Specifies a static title for the visual. Type: string
"header.visible": false	true	Indicates whether the visual header should be visible for the embedded visual. Valid values are true or false. Type: boolean
"interactivityOverrides"	none	Specifies interactivity override settings for visual authoring. The interactivity settings specified in this object will override any interactivity settings specified for the individual visuals. For a list of visual interactivity settings you can specify, see Control How Users Interact With a Visual. Type: object
"source.visualId":"<id>"	null	The source ID of a visual template, used for creating a new visual in visual authoring. This represents a predefined visual template. A valid source ID should be specified in quotes ("<source-visual-ID>"). If neither visualId or source.visualId is specified, an empty visual authoring instance will be opened. If both are provided, visualId is used. Type: string
"theme":"dark"	composer	The theme for the embedded visual. Valid values are d+a_light, __platform__, composer, modern, dark. The initial default theme, composer, is the same as the modern theme. However, if you add your own themes to the application, more options are available in this list and you may have introduced a different default. Type: string
"visualId":"<id>"	null	The visual ID for an existing visual for visual authoring. A valid visual ID should be specified in quotes ("<visual-ID>"). If neither visualId or source.visualId is specified, an empty visual authoring instance will be opened. If both are provided, visualId is used. Type: string

You can include several controls for embedded visuals, allowing users to select and deselect favorite visuals, as well as filter the list of visuals in the embedded Visual Gallery by favorite status. See Use the Visual Gallery.

Optional Embedded Visual Authoring Breadcrumb Properties

Optionally, you can pass breadcrumb properties as parameters to the createComponent method when embedding Self-Service Analytics visual authoring components.

Here is a sample:

			"breadcrumbs": {
			"title": "<title>",
			"onClick": () => {console.log('clicked')},
			"href": "<uri-or-fqdn>",
			"target": "_blank"
		}

The following table describes the optional breadcrumb properties.

See: title, onClick, href, target.

Property/Object	Default	Description
"title":"<title>"	none	The first item breadcrumbs title. A valid title should be specified in quotes ("<title>"). Type: string
"onClick"	none	The click action handler for the breadcrumb title. Type: function
"href":"<uri-or-fqdn>"	none	The link address of the breadcrumb title. A valid link address, such as a URI or Fully Qualified Domain Name should be specified in quotes ("<uri-or-fqdn>"). Type: string
"target":"_blank"	none	The link target parameter. Use "_blank" to open in a new tab. A valid link target should be specified in quotes ("<uri-or-fqdn>"). Type: string

Token-Related Configuration Properties

The initComposerEmbedManager window function supports the following token-related configuration properties.

See: getToken.

Property	Description
getToken	This method returns a token using Trusted Access. This is the same as the window.composerGetToken method. There is no default. getToken: () => { return Promise.resolve({ // this is an example function. server side should be called in production "access_token": "60a26b4f-c5d7-49af-a90b-1da4e6eb12b8", "expires_in": "6000" }); }