The manager should not need to understand an API to get her Friday file. Your application can offer the request and progress messages, while PBRS handles the workbook preparation and delivery behind them.
On the server, check that she is allowed to request North’s data and select the approved PBRS job. Keep credentials there as well. The button starts that job; it does not receive an Excel file directly from the execution request.
API example: request and monitor North’s saved workbook job
Begin with an existing single-report schedule that already produces the correct workbook in PBRS. The visual-data Excel guide explains the export settings. Use a valid access token and replace the example schedule ID 101 and connection values with your own.
POST {pbrsBaseUrl}/api/Schedule/ExecuteScheduleAsync
Authorization: bearer {pbrsAccessToken}
Content-Type: application/json
{"ScheduleType":"report","uniqueid":101,"RunBy":"North workbook requested"}
GET {pbrsBaseUrl}/api/Schedule/GetExecutionStatus?ExecutionId={ExecutionId}
Authorization: bearer {pbrsAccessToken}
Retain the returned ExecutionId and use it for status checks. Follow the execution guide to inspect the result and confirm delivery before telling the manager the workbook is ready.
If the portal offers a download link, your application must also provide authorised access to the completed file at its destination. PBRS’s execution response is a job reference, not XLSX bytes.
Keep each request tied to its approved regional configuration. Do not let a second user change shared settings while North’s job is running. If monitoring times out, check the existing execution before submitting another request so the manager does not receive duplicate files.
If you chose the direct-download experience inside Power BI, the separate example below shows that route. It builds a workbook from the custom visual’s own data and does not use the PBRS request above.
Alternative code example: download XLSX from a custom visual
For the custom visual, bind OrderId, Region and Amount in that order. Keep OrderId as a unique text key and Amount numeric, and configure aggregation to preserve the intended order-level detail. The button reads its own table data view, not a neighbouring visual’s rows.
Our illustrative data contains O-001 in North for 1,200, O-002 in North for 800 and O-003 in South for 900. Selecting North should supply two distinct IDs totalling 2,000. Confirm that the slicer and report interactions affect the custom visual itself.
The file download API has an administrator-controlled permission and user consent separate from ordinary export controls. Declare ExportContent in the visual’s capabilities and have the visual’s data use approved. The extended download method requires API 5.3 or later and supports Service and Desktop, with a 30 MB file limit.
The bounded example below uses a smaller 29,000,000-byte ceiling and refuses segmented or 1,000-row data views. Those checks reduce the chance of accepting an obviously limited view; they do not prove that every source record reached the visual. Model security, filters and aggregation still determine its input.
Inspect the generated workbook’s protection separately. Do not assume that a custom-created file automatically inherits every sensitivity label or protection attached to the report.
Build the custom visual
Create the project using Microsoft’s development tutorial, preserving its generated licence notices and configuration. Select a compatible API version of at least 5.3 in pbiviz.json and install an approved XLSX serialization dependency using SheetJS’s installation guidance and your version policy.
The following capabilities bind one table of export fields and request up to 1,000 rows. The implementation refuses a view at that boundary rather than treating it as proof of completeness. Review the capabilities and data-view mapping guidance when adapting it.
{
"privileges": [{"name": "ExportContent", "essential": true}],
"dataRoles": [{"name": "fields", "displayName": "Export fields", "kind": "GroupingOrMeasure"}],
"dataViewMappings": [{"table": {"rows": {"for": {"in": "fields"}, "dataReductionAlgorithm": {"top": {"count": 1000}}}}}],
"objects": {}
}
Place this Visual class in src/visual.ts, retaining the generated licence notice. It copies the current rows before awaiting permission, validates the agreed types and keys, creates a real workbook, and reports the host’s completion result.
import powerbi from "powerbi-visuals-api";
import * as XLSX from "xlsx";
import IVisual = powerbi.extensibility.visual.IVisual;
import VisualConstructorOptions = powerbi.extensibility.visual.VisualConstructorOptions;
import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
// Illustrative bounded export. This exports this visual's bound data view.
// It does not certify that the data view contains every source record.
export class Visual implements IVisual {
private service: powerbi.extensibility.IDownloadService;
private button: HTMLButtonElement;
private message: HTMLParagraphElement;
private view?: powerbi.DataView;
private busy = false;
constructor(options: VisualConstructorOptions) {
this.service = options.host.downloadService;
this.button = document.createElement("button");
this.message = document.createElement("p");
this.message.setAttribute("role", "status");
this.button.textContent = "Export current rows to Excel";
this.button.disabled = true;
this.button.addEventListener("click", () => { void this.download(); });
options.element.append(this.button, this.message);
}
public update(options: VisualUpdateOptions): void {
this.view = options.dataViews?.[0];
this.button.disabled = this.busy || !this.view?.table?.rows?.length;
if (!this.busy) {
this.message.textContent = `${this.view?.table?.rows?.length ?? 0} current visual rows. Validate the scope before exporting.`;
}
}
private async download(): Promise<void> {
if (this.busy) return;
this.busy = true;
this.button.disabled = true;
try {
// Freeze the click-time data before awaiting permission or consent.
const view = this.view;
const table = view?.table;
if (!table?.rows?.length) throw new Error("No current rows to export.");
if (view?.metadata.segment || table.rows!.length >= 1000) {
throw new Error("This bounded example refuses segmented or 1,000-row data views.");
}
const headers = table.columns.map(c => c.displayName);
if (headers.join("|") !== "OrderId|Region|Amount") {
throw new Error("Bind OrderId, Region and Amount in that order.");
}
const rows = table.rows!.map(row => [...row]);
const keys = new Set<string>();
for (const row of rows) {
if (row.length !== 3 || typeof row[0] !== "string" || !row[0] ||
typeof row[1] !== "string" || typeof row[2] !== "number" ||
!Number.isFinite(row[2]) || keys.has(row[0])) {
throw new Error("Check the required types and unique OrderId values.");
}
keys.add(row[0]);
}
const status = await this.service.exportStatus();
if (status !== powerbi.PrivilegeStatus.Allowed) {
throw new Error("Custom-visual download permission is unavailable.");
}
const workbook = XLSX.utils.book_new();
const sheet = XLSX.utils.aoa_to_sheet([headers, ...rows]);
XLSX.utils.book_append_sheet(workbook, sheet, "CurrentRows");
const content = XLSX.write(workbook, {bookType: "xlsx", type: "base64"});
// A conservative 29,000,000-byte ceiling below the host's 30 MB limit.
const padding = content.endsWith("==") ? 2 : content.endsWith("=") ? 1 : 0;
if (content.length * 3 / 4 - padding > 29000000) {
throw new Error("Workbook exceeds this example's size ceiling.");
}
const result = await this.service.exportVisualsContentExtended(
content, "Current-Visual-Rows.xlsx", "base64", "Current visual rows"
);
this.message.textContent = result.downloadCompleted
? `Download completed for ${rows.length} click-time rows. Validate the workbook before use.`
: "Download was not completed. No successful export is recorded.";
} catch (error) {
this.message.textContent = error instanceof Error ? error.message : "Export failed.";
} finally {
this.busy = false;
this.button.disabled = !this.view?.table?.rows?.length;
}
}
}
Test denied permission, cancellation, empty or segmented data, the row boundary, duplicate or non-text keys and host errors. Also test a delayed permission response while another click or filter change occurs. The retained click-time rows should be the ones written to the workbook. Compare them with an independent source baseline even when the view is below the example’s ceiling.
