DataProviders

BiExcellence.OpenBi.Api.DataProviders is the client for the reporting engine. A dataprovider is not a stored object but state in the caller's session on the server: it is opened from a connection template, changed, executed and read, and its id is the name it has in that session.

DataProviderView holds an open dataprovider together with its definition, so most work goes through it:

using BiExcellence.OpenBi.Api.ConnectionTemplates;
using BiExcellence.OpenBi.Api.DataProviders;

// 1. validate a connection template - this puts a dataprovider into the session
var validated = await client.ValidateConnectionTemplateAsync(templateId, cancellationToken: cancellationToken);
var name = validated.DataproviderName!;

// 2. open the cube, query or stored view to read
var opened = await client.OpenDataProviderAsync(name, new OpenDataProviderRequest { InfoCube = "SALES" }, cancellationToken);

// every further connection it turned out to need has to be validated too
foreach (var used in opened.UsedConnections)
{
    await client.ValidateConnectionTemplateAsync(
        used.ConnectionTemplateId!, new() { DataproviderId = used.DataProviderName }, cancellationToken);
}

// 3. read the definition
await using var view = await client.GetDataProviderViewAsync(name, cancellationToken);

// 4. change it in memory
view.Dimensions["COUNTRY"]!.Axis = DataProviderAxis.Rows;
view.Dimensions["COUNTRY"]!.Filters.Add(new DataProviderFilter("DE"));
view.KeyFigures["REVENUE"]!.Visible = false;

// 5. execute, then read
var result = await view.ExecuteAsync(cancellationToken);
var grid = await view.GetGridDataAsync(withTuples: true, cancellationToken: cancellationToken);

Disposing the view closes the dataprovider on the server.

The definition

Unlike every other resource type of this client, the definition (DataProviderDefinition) is mutable: it is read, edited and sent back.

• ExecuteAsync sends the whole definition. What is left out of it is removed from the dataprovider.
• Where executing changed the definition on the server, the view reads it again before ExecuteAsync returns, so it never works on an outdated definition.
• Dimensions, KeyFigures, Variables and a dimension's Attributes are lists that can also be indexed by id. The indexer returns null where there is no element with that id.
• Positions are 1-based per axis and are applied as sent, so setting one dimension's Position alone leaves two dimensions on the same position. DataProviderElementExtensions has Move and Swap, which renumber the others.

Reading the result

Call	Returns
GetGridDataAsync, GetGridDataSliceAsync	The grid, cell by cell - see DataProviderGridCell for what each cell holds
GetChartDataAsync	The data as series and categories for a chart
GetF4ValuesAsync	The values a dimension or variable can take (value help)
ExportAsync	The grid as an Excel or CSV document (DataProviderExportFormat)
SaveAsync	Stores the current state as a view that can be opened again later