Version: 9.2

Dashboard

When embedded in an application, this widget enables complete dashboard management for tenant end-users.

⚡ Quick Embeddable Sample (For Testing Only)

⚠️ Important: This example is for testing purposes only.

In production, you must use a qvToken instead of exposing an apiKey in the UI.
The apiKey is private and should only be used for backend-to-backend communication.
For testing, clientId can match the userId. In production, clientId must be a unique identifier for each tenant end user.

<!-- Tag -->
<qrvey-dashboard settings="dashboardConfig"></qrvey-dashboard>

<!-- Config -->
<script>
var dashboardConfig = {   
   "apiKey": "<YOUR_PRIVATE_API_KEY>",   // Testing only. Do not use in production UI.
   "domain": "<DOMAIN>",   
   "appId":  "<APP_ID>", 
   "userId": "<USER_ID>",
   "dashboardId": "<DASHBOARD_ID>",
   "clientId": "<CLIENT_ID>",            // Optional, for testing, this can match userId.
   "orgId": "org:0"                      // Optional, for testing, use org:0 (base organization)
};  
</script>

<!-- Launcher -->
<script type="module" src="https://<DOMAIN>/qrvey-dashboard/qrvey-dashboard/qrvey-dashboard.esm.js"></script>

Production Deployment

Use qvToken instead of apiKey.
Pass sensitive values (appId, userId, clientId, orgId) via qvToken, not in plain config.
In production, configure roles, orgs, filters, i18n, and theme as needed.

Configuration Object

Property	Type	Required	QVToken Support	Description
domain	`String`	Required	No	Qrvey instance URL.
qvToken	`String`	Optional	No	Encrypted string securing the widget config. Required if no `apiKey` is provided. Cannot be used with `apiKey`.
apiKey	`String`	Required, if `qvToken` is not provided	No	Secret identification token for accessing the application. Required if `qvToken` is not provided. Cannot be used with `qvToken`.
appId	`String`	Required	Yes	ID of the Qrvey application. Must be passed via `qvToken` in production.
userId	`String`	Optional	Yes	User ID of the application owner. Must be passed via `qvToken` in production.
dashboardId	`String`	Optional	Yes	ID of a specific dashboard to embed. If omitted, the widget will present the "browse dashboards" page.
clientId	`String`	Optional	Yes, and must be passed via `qvToken` during production.	Unique identifier for the tenant end user. For testing, this can match the `userId`. In production, should be unique per tenant end user and passed via qvToken. If omitted, the widget will assume `anonymous`.
roles	`Array<string>`	Optional	Only	Used for Column Level Security.
orgId	`String`	Optional	Yes	The Organization ID for the end user. Used for asset ownership. If omitted, widget will use the clientId's orgId (if set in orgs object) otherwise use `anonymous`.
orgs	`Array(Object)`	Optional	Only	The orgs object to list users, defined per organization, in the Subscribe modal. Note: The orgs object is ignored when the widget's orgId is set to"org:0".
userFilters	`Object`	Optional	Yes	Collection of custom filters that the system will apply to the visualized data. For more information, see Working With Filters in Embedded Scenarios.
timezone	`String`	Optional	Yes	Timezone offset applied to dates. For more information, see Configuring Time Zone Settings.
i18n	`Object`	Optional	No	Defines language and localization. For details, please see The i18n Object.
themeId	`String`	Optional	No	Theme ID to use in the component. For more details, please see Accessing a Theme Programmatically.
styles	`JSON`	Optional	No	Key-value JSON with style variables. See the Dashboard Styles documentation.
defaultMode	`"design"` or `"interact"`	Optional	No	Sets the dashboard's default mode, so it opens in either `design` or `interact` mode. Defaults to `interact` mode. Only applies to a single dashboard.
customTokens	`Custom Tokens`	Optional	No	Sets custom tokens. For more information, see Using Custom Tokens.
permissions	`JSON`	Optional	Only	Record-level security permissions object.
asset_permissions	`Asset Permissions`	Optional	Only	The asset permissions object.
email	`String`	Optional, but Required in order to enable scheduling and subscriptions.	Only	Email of the `clientId` user. When passed in the qvToken, enables scheduling of exports and subscriptions.
customization	`JSON`	Optional	No	The Dashboard customization object.

Orgs

For full details on how orgs work, please see Ownership, Orgs, & Subscriptions.

Property	Type	Description
orgId	String	The ID of the organization to which the roles and users will be defined next. Should correspond to the user in session's `orgId` if you want the roles and users to be listed in subscribe.
users	Array	An object/array of users to be listed in the subscribe modal. This is not for the current user. Adjust `clientId` and `email` accordingly.
users.clientId	String	`clientId` of the user.
users.email	String	Email address of the user.

Example:

const orgs = [
  {
      orgId: 'ORG_ID',
      users: [
        {
          clientId: 'CLIENT_ID',
          email: 'EMAIL'
        },
        {
          clientId: 'CLIENT_ID2',
          email: 'EMAIL2'
        }
      ]
  }
]

i18n

For more information, please see Internationalization, Step by Step.

Property	Type	Required	Value
lang	String	Required	The language to use for the UI. Example: `"es"`.
locale	String	Optional	The locale code to use for date and number formatting. Example: `"es-ES"`.

Styles

The Dashboard Widget supports customization through CSS variables, allowing you to adapt the look and feel of dashboards to match your application’s design system. This includes control over fonts, colors, spacing, and other UI elements.

By overriding the available style variables, you can achieve a fully branded experience for end users without altering functionality. This is the recommended way to ensure consistency across embedded dashboards.

👉 For the complete list of available style variables and examples of how to use them, please refer to the Styles documentation.

Methods and Events

The Dashboard widget supports two main interaction patterns: Direct Method Calls using the executeAction method and Event-Based Communication using custom events with promise-based responses; both approaches provide the same functionality with different implementation styles, allowing developers to programmatically control dashboard behavior (such as applying filters, switching versions, or triggering downloads) from their host application and integrate dashboard actions into their own UI workflows or automation scripts.

setUserFilters Method

Applies a set of filters to the widget’s current view. Useful for programmatically controlling the data display.

Syntax:

// Enables changes to the userFilters property.
const dashboardComponent = document.querySelector("qrvey-dashboard");
dashboardComponent.setUserFilters(filters);

Note: For parameter type filters please see Working With Filters in Embedded Scenarios.

executeAction Method

The executeAction method provides direct access to dashboard functionality through method calls on the dashboard element.

Syntax:

dashboard.executeAction(actionName, parameters)
  .then(response => {
    // Handle success
  })
  .catch(error => {
    // Handle error
  });

executeAction("atApplyUserFilters")

Applies user-defined filters to the dashboard data. This allows you to programmatically filter dashboard content based on specific criteria.

Applicable Views: Preview, Design and Interact

Property	Type	Required
filters	IFBUserFilters. For details about the filter object please see Working With Filters in Embedded Scenarios.	Required

const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('atApplyUserFilters', {
  filters: [
    {
      operator: 'AND',
      expressions: [
        {
          qrveyid: 'syqssyvbr',
          questionid: 'f4koA2I1b',
          validationType: 'EQUAL',
          value: ['0 - 1 Solar Resource Assessment']
        }
      ]
    }
  ]
})
.then(result => console.log('Filters applied successfully:', result))
.catch(error => console.error('Failed to apply filters:', error));

executeAction("qvDSHRestoreDashboard")

Switches between different versions of the dashboard, allowing users to restore original, personalized, or handle non-existent versions.

Applicable Views: Interact

Property	Type	Required
version	String. One of `ORIGINAL`, `PERSONALIZED` or `NO-VERSION-EXISTS`	Required

const dashboard = document.querySelector('qrvey-dashboard');

// Restore original version
dashboard.executeAction('qvDSHRestoreDashboard', { version: 'ORIGINAL' })
  .then(result => console.log('Original version restored'))
  .catch(error => console.error('Failed to restore version:', error));

// Restore personalized version
dashboard.executeAction('qvDSHRestoreDashboard', { version: 'PERSONALIZED' })
  .then(result => console.log('Personalized version restored'))
  .catch(error => console.error('Failed to restore version:', error));

// Handle non-existent version
dashboard.executeAction('qvDSHRestoreDashboard', { version: 'NO-VERSION-EXISTS' })
  .then(result => console.log('Version handling completed'))
  .catch(error => console.error('Version does not exist:', error));

executeAction("qvDSHSaveDashboard")

Saves(interact mode) or publishes(design mode) the current state of the dashboard, persisting any changes made by the user.

Applicable Views: Design and Interact

const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('qvDSHSaveDashboard')
  .then(result => console.log('Dashboard saved successfully:', result))
  .catch(error => console.error('Failed to save dashboard:', error));

executeAction("qvDSHDownloadDashboard")

Triggers a download of the dashboard, opening the modal to configure the download or schedule a report/export file. The format attribute is required for the download.

Applicable Views: Design and Interact

Property	Type	Required
format	String. One of `PDF`, `CSV`, `EXCEL` or `DATASET`	Required

const dashboard = document.querySelector('qrvey-dashboard');

// Download as PDF
dashboard.executeAction('qvDSHDownloadDashboard', { format: 'PDF' })
  .then(result => console.log('PDF download initiated'))
  .catch(error => console.error('PDF download failed:', error));

// Download as CSV
dashboard.executeAction('qvDSHDownloadDashboard', { format: 'CSV' })
  .then(result => console.log('CSV download initiated'))
  .catch(error => console.error('CSV download failed:', error));

// Download as Excel
dashboard.executeAction('qvDSHDownloadDashboard', { format: 'EXCEL' })
  .then(result => console.log('Excel download initiated'))
  .catch(error => console.error('Excel download failed:', error));

// Download as Dataset
dashboard.executeAction('qvDSHDownloadDashboard', { format: 'DATASET' })
  .then(result => console.log('Dataset download initiated'))
  .catch(error => console.error('Dataset download failed:', error));

executeAction("qvDSHUndo")

Reverts the last action performed on the dashboard, allowing users to step back through their changes.

Applicable Views: Design and Interact

const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('qvDSHUndo')
  .then(result => console.log('Last action undone:', result))
  .catch(error => console.error('Undo failed:', error));

executeAction("qvDSHRedo")

Reapplies a previously undone action, allowing users to step forward through their change history.

Applicable Views: Design and Interact

const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('qvDSHRedo')
  .then(result => console.log('Action redone:', result))
  .catch(error => console.error('Redo failed:', error));

executeAction("qvDSHDiscardChanges")

Discards all unsaved changes made to the dashboard, reverting it to its last saved state.

Applicable Views: Design and Interact

const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('qvDSHDiscardChanges')
  .then(result => console.log('Changes discarded:', result))
  .catch(error => console.error('Failed to discard changes:', error));

executeAction("qvDSHHiddenItems")

Opens the hidden items panel, allowing users to view and potentially restore previously hidden dashboard elements.

Applicable Views: Interact

const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('qvDSHHiddenItems')
  .then(result => console.log('Hidden items panel opened:', result))
  .catch(error => console.error('Failed to open hidden items:', error));

The dashboard supports event-based communication using custom events. You can dispatch events directly and handle them however you prefer. However, if you need a response from the dashboard, you can listen for a result event with the same name plus "Result" suffix (e.g., dispatching qvDSHSaveDashboard and listening for qvDSHSaveDashboardResult). The helper function below demonstrates this pattern with promise-based handling, but you're free to implement your own event handling approach.

Helper Function:

function dispatchWithResponse(eventName, detail) {
  return new Promise((resolve, reject) => {
    const resultEvent = `${eventName}Result`;
    const onResult = (event) => {
      event.detail.success 
        ? resolve(event.detail.data) 
        : reject(new Error(event.detail.error));
      document.removeEventListener(resultEvent, onResult);
    };
    document.addEventListener(resultEvent, onResult);
    document.dispatchEvent(new CustomEvent(eventName, { detail }));
  });
}

// Usage wrapper
function callDispatch(eventName, detail={}) {
  dispatchWithResponse(eventName, detail)
    .then(res => console.log(`[Event] ${eventName} SUCCESS`, detail, res))
    .catch(err => console.log(`[Event] ${eventName} ERROR`, detail, err.message));
}

atApplyUserFilters

Triggers the process of applying user filters to the dashboard, similar to method “apply-user-filters”

Applicable Views: Preview, Design and Interact

Property	Type	Required
filters	IFBUserFilters. For details about the filter object please see Working With Filters in Embedded Scenarios.	Required

dispatchWithResponse('atApplyUserFilters', {
  filters: [
    {
      operator: 'AND',
      expressions: [
        {
          qrveyid: 'syqssyvbr',
          questionid: 'f4koA2I1b',
          validationType: 'EQUAL',
          value: ['0 - 1 Solar Resource Assessment']
        }
      ]
    }
  ]
})
.then(result => console.log('Filters applied via event:', result))
.catch(error => console.error('Event-based filter application failed:', error));

qvDSHRestoreDashboard

Requests the restoration of the dashboard to a previous saved state. Only the valid versions (ORIGINAL or PERSONALIZED) are allowed.

Applicable Views: Interact

Property	Type	Required
version	String. Either 'ORIGINAL'	'PERSONALIZED'

// Restore original version
dispatchWithResponse('qvDSHRestoreDashboard', { version: 'ORIGINAL' })
  .then(result => console.log('Original version restored via event'))
  .catch(error => console.error('Event-based restore failed:', error));

// Restore personalized version
dispatchWithResponse('qvDSHRestoreDashboard', { version: 'PERSONALIZED' })
  .then(result => console.log('Personalized version restored via event'))
  .catch(error => console.error('Event-based restore failed:', error));

qvDSHSaveDashboard

Initiates the dashboard save operation, persisting all current modifications.

Applicable Views: Design and Interact

dispatchWithResponse('qvDSHSaveDashboard')
  .then(result => console.log('Dashboard saved via event:', result))
  .catch(error => console.error('Event-based save failed:', error));

qvDSHDownloadDashboard

Triggers a download of the dashboard, opening the modal to configure the download/schedule, usually as a report or export file. The format attribute is required for the download.

Applicable Views: Design and Interact

Property	Type	Required
format	String. One of `PDF`, `CSV`, `EXCEL`. `DATASET` or `JSON`	Required

// Download as PDF via event
dispatchWithResponse('qvDSHDownloadDashboard', { format: 'PDF' })
  .then(result => console.log('PDF download initiated via event'))
  .catch(error => console.error('Event-based PDF download failed:', error));

// Download as CSV via event
dispatchWithResponse('qvDSHDownloadDashboard', { format: 'CSV' })
  .then(result => console.log('CSV download initiated via event'))
  .catch(error => console.error('Event-based CSV download failed:', error));

qvDSHUndo

Triggers the undo operation for the most recent dashboard action.

Applicable Views: Design and Interact

dispatchWithResponse('qvDSHUndo')
  .then(result => console.log('Last action undone via event:', result))
  .catch(error => console.error('Event-based undo failed:', error));

qvDSHRedo

Triggers the redo operation for the most recently undone action.

Applicable Views: Design and Interact

dispatchWithResponse('qvDSHRedo')
  .then(result => console.log('Action redone via event:', result))
  .catch(error => console.error('Event-based redo failed:', error));

qvDSHDiscardChanges

Requests to discard all pending modifications to the dashboard.

Applicable Views: Design and Interact

dispatchWithResponse('qvDSHDiscardChanges')
  .then(result => console.log('Changes discarded via event:', result))
  .catch(error => console.error('Event-based discard failed:', error));

qvDSHHiddenItems

Opens the hidden elements modal, where deleted dashboard items can be reviewed or restored.

Applicable Views: Interact

dispatchWithResponse('qvDSHHiddenItems')
  .then(result => console.log('Hidden items panel opened via event:', result))
  .catch(error => console.error('Event-based hidden items failed:', error));

This section describes the custom DOM events emitted by the dashboard widget. These events notify your host application about important actions or state changes within the dashboard, such as when a page loads, filters are applied, or a download completes. Listen for these events to react to dashboard activity, update your UI, or trigger additional logic in your application.

qvDSHPageLoaded

Emitted when the dashboard page has fully loaded and is ready for interaction.

Applicable Views: Preview, Design and Interact

document.addEventListener('qvDSHPageLoaded', (event) => {
  console.log('Dashboard page loaded and ready');
  // Initialize any dashboard-dependent functionality here
});

qvDSHItemsLoaded

Emitted once all visible dashboard items (panels) have been successfully loaded.

Applicable Views: Preview, Design and Interact

document.addEventListener('qvDSHItemsLoaded', (event) => {
  console.log('Dashboard items loaded successfully');
  // Perform actions that depend on dashboard items being available
});

atApplyUserFiltersResult

Emitted after user filters have been applied, containing the resulting filtered data or status.

Applicable Views: Preview, Design and Interact

document.addEventListener('atApplyUserFiltersResult', (event) => {
  console.log('Apply filters result:', event.detail);
  if (event.detail.success) {
    console.log('Filters applied successfully');
  } else {
    console.error('Error applying filters:', event.detail.error);
  }
});

qvDSHRestoreDashboardResult

Emitted after the restore operation completes, providing the outcome (success/failure) and details.

Applicable Views: Interact

document.addEventListener('qvDSHRestoreDashboardResult', (event) => {
  console.log('Restore result:', event.detail);
  if (event.detail.success) {
    console.log('Dashboard restored successfully');
  } else {
    console.error('Error restoring dashboard:', event.detail.error);
  }
});

qvDSHSaveDashboardResult

Emitted after a save operation finishes, with information about success and any validation messages.

Applicable Views: Design and Interact

document.addEventListener('qvDSHSaveDashboardResult', (event) => {
  console.log('Save result:', event.detail);
  if (event.detail.success) {
    console.log('Dashboard saved successfully');
  } else {
    console.error('Error saving dashboard:', event.detail.error);
  }
});

qvDSHDownloadDashboardResult

Emitted when the download process has completed or failed, containing the download status or file info.

Applicable Views: Design and Interact

document.addEventListener('qvDSHDownloadDashboardResult', (event) => {
  console.log('Download result:', event.detail);
  if (event.detail.success) {
    console.log('Dashboard downloaded successfully');
  } else {
    console.error('Error downloading dashboard:', event.detail.error);
  }
});

qvDSHUndoResult

Emitted once the undo operation has finished, reporting the current state after reverting changes.

document.addEventListener('qvDSHUndoResult', (event) => {
  console.log('Undo result:', event.detail);
  if (event.detail.success) {
    console.log('Undo executed successfully');
  } else {
    console.error('Error executing undo:', event.detail.error);
  }
});

qvDSHRedoResult

Emitted once the redo operation has finished, reporting the current state after reapplying changes.

Applicable Views: Design and Interact

document.addEventListener('qvDSHRedoResult', (event) => {
  console.log('Redo result:', event.detail);
  if (event.detail.success) {
    console.log('Redo executed successfully');
  } else {
    console.error('Error executing redo:', event.detail.error);
  }
});

qvDSHDiscardChangesResult

Emitted after all unsaved dashboard changes have been discarded.

Applicable Views: Design and Interact

document.addEventListener('qvDSHDiscardChangesResult', (event) => {
  console.log('Discard result:', event.detail);
  if (event.detail.success) {
    console.log('Changes discarded successfully');
  } else {
    console.error('Error discarding changes:', event.detail.error);
  }
});

qvDSHHiddenItemsResult

Emitted when the hidden items modal has been opened

Applicable Views: Interact

document.addEventListener('qvDSHHiddenItemsResult', (event) => {
  console.log('Hidden items result:', event.detail);
  if (event.detail.success) {
    console.log('Hidden items accessed successfully');
  } else {
    console.error('Error accessing hidden items:', event.detail.error);
  }
});

Error Handling

Both direct method calls and event-based communication provide comprehensive error handling:

Success responses contain the operation result data
Error responses include detailed error information
Network or system errors are caught and can be handled appropriately

Always implement proper error handling to ensure a robust user experience:

// Example with comprehensive error handling
dashboard.executeAction('download', { format: 'PDF' })
  .then(result => {
    console.log('Download successful:', result);
    // Handle successful download
  })
  .catch(error => {
    if (error.response) {
      console.error('Server error:', error.response);
      // Handle server-side errors
    } else {
      console.error('Client error:', error.message);
      // Handle client-side errors
    }
  });

Event Modes

Some events are only fired in specific widget modes (Design, Interaction, Preview). Refer to the event documentation for mode-specific details.

Dashboard

⚡ Quick Embeddable Sample (For Testing Only)

Production Deployment

Configuration Object

Orgs

i18n

Styles

Methods and Events

setUserFilters Method

executeAction Method

executeAction("atApplyUserFilters")

executeAction("qvDSHRestoreDashboard")

executeAction("qvDSHSaveDashboard")

executeAction("qvDSHDownloadDashboard")

executeAction("qvDSHUndo")

executeAction("qvDSHRedo")

executeAction("qvDSHDiscardChanges")

executeAction("qvDSHHiddenItems")

Incoming Events (Custom Events Listened By Widget)

atApplyUserFilters

qvDSHRestoreDashboard

qvDSHSaveDashboard

qvDSHDownloadDashboard

qvDSHUndo

qvDSHRedo

qvDSHDiscardChanges

qvDSHHiddenItems

Outgoing Events (Custom Events Emitted By Widget)

qvDSHPageLoaded

qvDSHItemsLoaded

atApplyUserFiltersResult

qvDSHRestoreDashboardResult

qvDSHSaveDashboardResult

qvDSHDownloadDashboardResult

qvDSHUndoResult

qvDSHRedoResult

qvDSHDiscardChangesResult

qvDSHHiddenItemsResult

Error Handling

Event Modes

⚡ Quick Embeddable Sample (For Testing Only)​

Production Deployment​

Configuration Object​

Orgs​

i18n​

Styles​

Methods and Events​

setUserFilters Method​

executeAction Method​

executeAction("atApplyUserFilters")​

executeAction("qvDSHRestoreDashboard")​

executeAction("qvDSHSaveDashboard")​

executeAction("qvDSHDownloadDashboard")​

executeAction("qvDSHUndo")​

executeAction("qvDSHRedo")​

executeAction("qvDSHDiscardChanges")​

executeAction("qvDSHHiddenItems")​

Incoming Events (Custom Events Listened By Widget)​

atApplyUserFilters​

qvDSHRestoreDashboard​

qvDSHSaveDashboard​

qvDSHDownloadDashboard​

qvDSHUndo​

qvDSHRedo​

qvDSHDiscardChanges​

qvDSHHiddenItems​

Outgoing Events (Custom Events Emitted By Widget)​

qvDSHPageLoaded​

qvDSHItemsLoaded​

atApplyUserFiltersResult​

qvDSHRestoreDashboardResult​

qvDSHSaveDashboardResult​

qvDSHDownloadDashboardResult​

qvDSHUndoResult​

qvDSHRedoResult​

qvDSHDiscardChangesResult​

qvDSHHiddenItemsResult​

Error Handling​

Event Modes​

⚡ Quick Embeddable Sample (For Testing Only)

Production Deployment

Configuration Object

Orgs

i18n

Styles

Methods and Events

setUserFilters Method

executeAction Method

executeAction("atApplyUserFilters")

executeAction("qvDSHRestoreDashboard")

executeAction("qvDSHSaveDashboard")

executeAction("qvDSHDownloadDashboard")

executeAction("qvDSHUndo")

executeAction("qvDSHRedo")

executeAction("qvDSHDiscardChanges")

executeAction("qvDSHHiddenItems")

Incoming Events (Custom Events Listened By Widget)

atApplyUserFilters

qvDSHRestoreDashboard

qvDSHSaveDashboard

qvDSHDownloadDashboard

qvDSHUndo

qvDSHRedo

qvDSHDiscardChanges

qvDSHHiddenItems

Outgoing Events (Custom Events Emitted By Widget)

qvDSHPageLoaded

qvDSHItemsLoaded

atApplyUserFiltersResult

qvDSHRestoreDashboardResult

qvDSHSaveDashboardResult

qvDSHDownloadDashboardResult

qvDSHUndoResult

qvDSHRedoResult

qvDSHDiscardChangesResult

qvDSHHiddenItemsResult

Error Handling

Event Modes