Reveal + SQL Server E2E for PoC Kickoff

You'll find everything you need to learn and implement a Reveal SDK application (both client and server) in this organization. This documents includes the general over of Reveal, links to source code for getting started samples, links to product documentation, support and video training.

Find the server (Node, .NET Core, Java) in the corresponding /server folders in this repo.

---

Versions

This repo targets Reveal SDK 2.2. Every server and the HTML client are pinned to the versions below.

Platform	Package	Version
ASP.NET Core	Reveal.Sdk.AspNetCore	2.2.1
ASP.NET Core	Reveal.Sdk.Data.Microsoft.SqlServer	2.2.1
ASP.NET Core / Blazor	Reveal.Sdk.Dom	0.1.672-beta
Blazor Server	IgniteUI.Blazor.Trial	26.1.98
Java (Spring Boot)	io.revealbi:reveal-sdk-servlet	2.2.0
Node.js / TypeScript	reveal-sdk-node	2.2.1
Node.js / TypeScript	@revealbi/dom	0.3.0
HTML client	reveal-sdk (jsDelivr)	2.2.1

Supporting stacks: .NET 8 (the Reveal 2.2.1 NuGet packages ship net8.0 only), Java 17+ with Spring Boot 3.5.x, and Node.js 20.19+ with Express 5.

Upgrade notes (2.0 → 2.2)

Things that changed in the SDK and are already reflected in this repo:

• newTooltip beta flag removed. The redesigned hover tooltips are the default in 2.2. RevealSdkSettings.betaFeatures.enable("newTooltip") is gone.
• hoverTooltipsEnabled renamed to showTooltips on RevealView. The old name still works but is deprecated. RevealSdkSettings.enableActionsOnHoverTooltip is not an API at all - assigning it silently did nothing.
• New DataGrid is the default grid visualization. Disable the newDataGrid feature flag to fall back to the legacy grid.
• RVDashboard gained public serialization: loadFromJson(), toJson() and toJsonString(). Reaching into the private _dashboardModel is no longer necessary.
• RVDashboardThumbnailView was replaced by RVThumbnail (2.0).
• Legacy $.ig and RevealApi globals were removed (2.1). The client no longer needs jQuery.
• @revealbi/dom 0.3.0 changed its packaging. The browser bundle is now index.iife.js (the old index.umd.min.js is gone) and the global is RevealDom. The package is also ESM-only, so CommonJS servers must load it with a dynamic import() rather than require().
• SQL Server connectors require trusted TLS certificates by default (2.0). These samples set TrustServerCertificate = true for local development - turn it off in production.

---

Running the samples

Every server listens on http://localhost:5111, which is the base URL the HTML client in /client expects. Run one server at a time.

Sample	Location	Configure	Run
ASP.NET Core	server/aspnet/RevealSdk.Server	appsettings.json → SqlServer section	dotnet run
Blazor Server	server/blazor-server	appsettings.json → SqlServer section	dotnet run
Java (Spring Boot)	server/java	copy src/main/resources/application.properties.example to application.properties	./mvnw spring-boot:run
Node.js	server/node-js	copy .env.example to .env	npm install && npm start
TypeScript	server/node-ts	copy .env.example to .env	npm install && npm start

The TypeScript sample runs through tsx (npm start watches and restarts on change; npm run build && npm run start:prod compiles to dist/ and runs plain Node). It previously used ts-node, which is not compatible with TypeScript 7.

The HTML client is static - open client/index.html through any web server, or let the Java sample serve it (it maps / to the client folder).

---

Reveal Overview & Important Notes for a PoC Kickoff

Dependencies

The essential dependencies for a .NET Core application using Reveal are the Reveal NuGet package and the SQL Server dependency.

Integrating Reveal

Reveal is integrated into a .NET Core or NodeJS application via NuGet packages for .NET or an NPM package for NodeJS. Dependency injection is configured to include Reveal services. Here’s the setup in Program.cs:

builder.Services.AddControllers().AddReveal(builder =>
{
    builder
        .AddAuthenticationProvider<AuthenticationProvider>()
        .AddDataSourceProvider<DataSourceProvider>()
        .AddUserContextProvider<UserContextProvider>()
        .AddObjectFilter<ObjectFilterProvider>()
        .DataSources.RegisterMicrosoftSqlServer();
});

or in TypeScript / JavaScript in your app.ts / main.js:

const revealOptions: RevealOptions = {
	userContextProvider: userContextProvider,
	authenticationProvider: authenticationProvider,
	dataSourceProvider: dataSourceProvider,
	dataSourceItemProvider: dataSourceItemProvider,
	dataSourceItemFilter: dataSourceItemFilter,
	dashboardProvider: dashboardProvider,
	dashboardStorageProvider: dashboardStorageProvider
}
app.use('/', reveal(revealOptions));

In this setup:

• AddReveal Configuration: Registers essential services like AuthenticationProvider and DataSourceProvider, while including optional configurations such as UserContextProvider, ObjectFilterProvider, and DashboardProvider as needed.
• Data Sources: Registers the Microsoft SQL Server connector, which is necessary for SQL Server integrations in .NET Core. For NodeJS, you are not required to install / register the SQL Server connector separately.

Core Server Functions

Authentication

Authentication is handled by implementing the IRVAuthenticationProvider. A username and password credential are created, and the connection details are stored in the data source provider. The example utilizes an Azure SQL instance.

• Authentication: Detailed documentation on setting up authentication.

Data Source Provider

The DataSourceProvider specifies the location of the database, including host, database name, schema, and port. This information can be retrieved from various sources, such as app settings, Azure Key Vault, or configuration files. The example uses app settings to store these details.

• Data Source / Data Source Items: Guidance on setting up and managing data sources.

Data Source Items

Custom data source items can be created, such as parameterized queries and stored procedures. These items are defined in the DataSourceProvider and are made accessible to users through a dialog.

• Custom Queries: Steps for adding custom queries to data sources.

Custom Queries: always parameterize

Never concatenate a value from the request (user id, order id, a header, a filter) into CustomQuery. Put a named placeholder in the SQL text and pass the value alongside it, so the driver binds the value instead of the database parsing it as SQL. SQL Server uses @name placeholders.

ASP.NET Core / Blazor

sqlDsi.CustomQuery = "SELECT * FROM [Orders] WHERE [OrderId] = @orderId";
sqlDsi.CustomQueryParameters = new Dictionary<string, object>
{
    ["@orderId"] = orderId
};

Java

sqlDsi.setCustomQuery("SELECT * FROM [Orders] WHERE [OrderId] = @orderId");
HashMap<String, Object> parameters = new HashMap<>();
parameters.put("@orderId", orderId);
sqlDsi.setCustomQueryParameters(parameters);

Node.js / TypeScript

dataSourceItem.customQuery = "SELECT * FROM [Orders] WHERE [OrderId] = @orderId";
dataSourceItem.customQueryParameters = { "@orderId": orderId };

A table or column name is an identifier and cannot be bound as a parameter. When the query shape itself depends on the request, validate the name against a server-side allow list first - that is what the FilterTables property on the user context does in these samples - and never interpolate a name straight from the request.

Parameterized custom queries are supported on SQL Server, Azure SQL, Azure Synapse, MySQL, MariaDB, PostgreSQL, Snowflake, BigQuery, Redshift, Athena, Databricks, ClickHouse and Elasticsearch. DuckDB, SQLite and Oracle support custom queries but not parameters.

Optional, but Important Server Functions

Object Filter

The ObjectFilter controls the data access permissions for users. It has a Filter function that can be customized to restrict data visibility based on user roles or other criteria. The example demonstrates a scenario where users with the "user" role can only access "All Orders" and "Invoices" data.

• Object Filter: Examples of filtering data objects.

User Context

The UserContext provides information about the logged-in user. It can be used to store default properties like UserID or other custom properties defined in the UserContextProvider. The GetUserContext method is used to retrieve the user context.

• User Context: Explanation of how to utilize the user context.

Dashboard Provider

The DashboardProvider enables customization of dashboard saving behavior. It can be used to determine the save location based on the user's context, like saving to different folders or databases.

Setting up the Client

HTML Client Setup

The HTML client needs one dependency: the Reveal JavaScript library, loaded locally or from a CDN. jQuery is no longer required - the legacy $.ig and RevealApi globals were removed in 2.1. The client code specifies the server URL and a callback function that handles user interaction.

The pages in /client import the ES module build and pin the version:

<script type="module">
    import { RevealView, RevealSdkSettings, RVDashboard }
        from "https://cdn.jsdelivr.net/npm/reveal-sdk@2.2.1/dist/reveal-sdk.esm.js";

    RevealSdkSettings.setBaseUrl("http://localhost:5111/");
</script>

Pinning the version matters: an unpinned npm/reveal-sdk/dist/... URL silently follows the latest release and will pick up breaking changes on its own.

Loading Dashboards

Dashboards are loaded using the LoadDashboard function, which takes the name of the dashboard file as a parameter. In HTML clients, a selector is used to specify where the dashboard should be rendered.

Additional Headers Provider

The SetAdditionalHeadersProvider API allows passing custom headers to the server. These headers can contain information like customer ID or other relevant details.

• SetAdditionalHeadersProvider: Documentation on using this API for custom headers.

Adding Custom Menu Items to Visualizations

In Reveal, you can customize the menu that appears on specific visualizations using the onMenuOpening event. This can be especially useful for adding custom actions directly accessible to users from visualizations.

• Custom Menu Items: Instructions for adding custom menu items to visualizations.

Using the Reveal SDK DOM

The Reveal.SDK.DOM library, currently in beta, provides a typed view of dashboards. It allows easy access to dashboard properties, such as file name and title. It ships as Reveal.Sdk.Dom on NuGet and @revealbi/dom on npm, and every server in this repo uses it to expose /dashboards/names and /dashboards/visualizations.

Two things to know about @revealbi/dom 0.3.0:

• In the browser, the bundle is index.iife.js and the global is RevealDom. The old index.umd.min.js path no longer exists and returns a 404.

• On the server, the package is ESM-only ("type": "module"), so a CommonJS project cannot require() it. Load it with a dynamic import() instead:

  let _domPromise;
  const getDom = () => (_domPromise ??= import('@revealbi/dom'));
  
  // ...inside an async handler
  const { RdashDocument } = await getDom();

  In TypeScript this needs "module": "node16" in tsconfig.json, otherwise the compiler downlevels the import() back into a require() and it fails at runtime.

• Reveal SDK DOM: Library for accessing dashboard properties.

Dashboard Titles vs. File Names

The dashboard title displayed to the user can differ from the underlying file name. The DashboardsThumbnail and DashboardsNames APIs are used to retrieve both the title and file name, ensuring consistency in user experience.

Video Training

Explore these video resources to help you set up and configure Reveal BI for .NET and SQL Server:

• Setting Up a .NET Core Server with Reveal BI: Quick & Easy Guide
• Configuring SQL Server in a .NET Core Server in Reveal BI
• Leveraging SQL Server Stored Procedures and Parameters in Reveal BI
• Configuring Row Level Security with UserContext in Reveal BI

For a comprehensive learning path, check out the .NET & SQL Server Track Playlist:
https://youtube.com/playlist?list=PLprTqzVaLDG8TSd0nIwgmAkwIF0xkJRI7&si=-TvFdEN4vNzeFfRP

Licensing

A trial license key is valid for 30 days and can be extended upon request. When a license is purchased, the key is valid for the duration of the contract. It's important to keep track of the license expiry date to avoid disruptions. The license key can be set in code, configuration files, or the home directory.

Resources

The following resources are available to help with the PoC:

• Documentation: Comprehensive documentation covering installation, licensing, and various features.
• GitHub: The Reveal BI GitHub repository contains SDK samples, issue tracking for bug reports and feature requests, and discussions for community support.
• Support via Discord Channel: A Discord channel dedicated to Reveal provides direct interaction with the product team.
• Support via GitHub Discussions: A GitHub channel dedicated to Reveal provides direct interaction with the product team. Usually, you'd use this if you can't access Discord due to corporate policy.
• YouTube Channel: Webinars and videos covering various aspects of Reveal are available on the YouTube channel.
• JavaScript API: Reveal offers a comprehensive JavaScript API that allows customization of almost every aspect of the dashboard, including visualization chooser, editing modes, and adding custom elements.
• Developer Playground: An interactive playground to experiment with Reveal BI's features.
• Add Feature Requests, Bug Reports, or Review Open Issues: Reveal's GitHub repository where you can review, add, or comment on new or existing issues.

PoC Requirements

Check-in Calls

Weekly check-in calls lasting 10-15 minutes will be scheduled to provide updates and address any challenges during the PoC.