Version: 9.2

Dashboard

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

⚡ 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.
For testing, orgId must be set to org:0 (the base organization).

<!-- 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>",            // For testing, this can match userId.
   "orgId": "org:0"                      // 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.
For testing, orgId should be set to org:0.
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. Required if no qvToken is provided. Cannot be used with qvToken.
appId	String	Required	Yes	ID of the Qrvey application. Must be passed via qvToken during production.
userId	String	Required	Yes	User ID of the application owner. Must be passed via qvToken during production.
dashboardId	String	Optional	Yes	ID of a specific dashboard to embed. If omitted, the widget presents the “browse dashboards” page.
clientId	String	Required	Yes	Unique identifier for the tenant end user. For testing, this can match the `userId`. In production, must be unique per tenant end user and passed via qvToken.
roles	Array(String)	Optional	Only	Used for Column Level Security and permissions when sharing.
orgId	String	Required	Yes	Organization ID for the end user. Required for widget access and sharing. For testing, use `org:0`.
orgs	Array(Object)	Optional	Only	The orgs object to list of users and roles per organization for Sharing. Ignored if `orgId = "org:0"`.
userFilters	Object	Optional	Yes	Collection of custom filters to apply to 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 apply. For more details, please see Accessing a Theme Programmatically.
defaultMode	"design" or "interact"	Optional	No	Sets default mode. Defaults to `interact`.
customTokens	Object	Optional	No	Sets custom tokens. For more information, see Using Custom Tokens.
permissions	JSON	Optional	Only	Record-level security permissions object.
asset_permissions	Object	Optional	Only	Asset permissions object.
email	String	Optional (required for scheduling/subscriptions)	Only	Email of the `clientId` user. Enables scheduling exports/subscriptions.
customization	JSON	Optional	No	The Dashboard customization object.

Orgs

For full details on how orgs work, please see Orgs, Sharing, & 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 sharing and subscribe.
orgRoles	Array	The roles available to share the dashboard with inside the organization defined with `orgId`.
users	Array	An object/array of users to be listed in the sharing and subscribe modals. 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',
      orgRoles: [ '<ROLE1>', '<ROLE2>' ],
      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 to suit your development preferences.

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
  });

apply-user-filters

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

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

dashboard.executeAction('apply-user-filters', {
  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));

swap-eup-versions

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

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

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

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

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

release-dashboard

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

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

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

download

Downloads dashboard data in various formats including PDF, CSV, Excel, Dataset, and JSON.

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

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

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

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

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

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

undo

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

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

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

redo

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

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

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

discard-changes-dashboard

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

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

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

open-trashcan

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

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

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

Event-Based Communication

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

Event-based version of applying user filters to the dashboard.

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

Event-based version of swapping dashboard versions.

// 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

Event-based version of saving(interact mode) or publushing(design mode) the dashboard.

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

qvDSHDownloadDashboard

Event-based version of downloading dashboard data in various formats.

// 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

Event-based version of undoing the last action.

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

qvDSHRedo

Event-based version of redoing a previously undone action.

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

qvDSHDiscardChanges

Event-based version of discarding dashboard changes.

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

qvDSHHiddenItems

Event-based version of opening the hidden items panel.

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

Dashboard Event Listeners

The dashboard emits certain events that you can listen for to respond to dashboard state changes.

qvDSHPageLoaded

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

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

qvDSHItemsLoaded

Fired when dashboard items have been loaded and are available for interaction.

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

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
    }
  });

⚡ Quick Embeddable Sample (For Testing Only)​

Production Deployment​

Configuration Object​

Orgs​

i18n​

Styles​

Methods and Events​

executeAction Method​

apply-user-filters​

swap-eup-versions​

release-dashboard​

download​

undo​

redo​

discard-changes-dashboard​

open-trashcan​

Event-Based Communication​

atApplyUserFilters​

qvDSHRestoreDashboard​

qvDSHSaveDashboard​

qvDSHDownloadDashboard​

qvDSHUndo​

qvDSHRedo​

qvDSHDiscardChanges​

qvDSHHiddenItems​

Dashboard Event Listeners​

qvDSHPageLoaded​

qvDSHItemsLoaded​

Error Handling​