Build a Scheduling Portal Integration

Use the PBRS REST API to add report scheduling to your application. Users can select approved reports, configure delivery, manage schedules, and monitor execution through your portal.

Your application backend authenticates to PBRS, validates user requests, and translates them into supported API operations.

Architecture

Keep PBRS integration logic on the server.

The browser should communicate with your application backend. Keep PBRS client secrets, access tokens, connection details, and privileged responses out of browser code and storage.

Do not expose a generic proxy that accepts arbitrary PBRS paths or request bodies.

Before you begin

Configure:

• The PBRS API service and its network access.
• HTTPS for the connection used by your backend.
• An API client or other supported authentication flow.
• The required PBRS permissions.
• Reporting accounts and access to the intended reports.
• Destination folders, mail settings, and execution dependencies.
• Portal authentication and resource authorization.

Start with a defined workflow, such as creating daily PDF email schedules for an approved set of Power BI reports.

Add other report sources, package schedules, and output formats as separate supported workflows.

Define what users can configure

Expose business choices rather than the entire PBRS request model.

The backend must revalidate submitted choices. A value being present in the frontend does not make it authorized.

For customer-specific reporting, enforce the required data scope independently of optional user filters. Do not allow a user to remove a mandatory filter or select another customer’s data.

Authenticate to PBRS

For API client credentials, request a token from:

POST /oauth2/token

This route does not include /api.

Send the returned access_token with protected requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

Tokens expire after 60 minutes. Cache and renew them on the backend using the returned expiration information.

Keep portal user authentication separate from PBRS authentication. A shared PBRS API client does not identify the individual portal user.

Record the portal actor in your application’s audit records.

Maintain resource ownership in your application

Store a mapping between each portal schedule and its PBRS resource.

Recommended fields include:

Before every read, update, execution, sharing, or deletion request, resolve the portal ID and authorize the caller against the stored mapping.

Apply the same check when returning execution status. Knowing an ExecutionId must not be enough to view another user’s activity.

Do not use schedule names, keywords, folder paths, or RunBy as substitutes for authorization.

PBRS permissions remain relevant, but a shared API client and naming convention do not establish tenant isolation.

Discover approved reports

An administrator supplies the configured reporting account identifiers. Your backend uses those accounts to discover the reporting objects needed by the portal.

List Power BI workspaces

GET /api/PowerBiAccount/GetWorkspaces?Id=CONFIGURED_ACCOUNT_ID

Id identifies the configured Power BI account.

List Power BI reports

GET /api/PowerBiAccount/GetReports

Send a JSON body:

{
  "AccountId": "7f320302-7ccb-4aba-a052-56197424ab36",
  "WorkspaceId": "24a89913-81fe-4815-a822-8d49cxxxfec1"
}

Replace the illustrative identifiers with values from your environment.

Related discovery operations include:

Report and dashboard discovery use AccountId and WorkspaceId. Visual discovery uses AccountId and ReportUrl.

These operations bind JSON bodies to GET requests. Use a backend client that supports GET bodies and verify that intermediaries preserve them.

Return a portal catalogue

Filter discovery results against the portal user’s permitted reports before returning them.

Expose portal catalogue IDs and display names. Resolve those IDs to PBRS account identifiers and report URLs on the backend.

Do not return every report visible to a broadly privileged integration account.

Create a schedule

Select the creation endpoint for the report source.

Construct the PBRS request from validated portal choices and server-controlled configuration.

Example: daily Power BI PDF email

The following request creates a disabled schedule so the backend can inspect the result before enabling recurring delivery.

POST /api/SingleSchedule/CreateForPowerBI

{
  "ScheduleName": "Daily sales",
  "FolderPath": "/API Reports",
  "Description": "Daily sales reporting",
  "Keywords": "portal,sales",
  "Schedule": {
    "Frequency": "Daily",
    "StartDate": "2026-10-01",
    "ExecutionTime": "09:00",
    "HasEndDate": false,
    "Repeat": false,
    "Enabled": false,
    "DailyRepeatInterval": 1
  },
  "EmailDestinations": [
    {
      "DestinationName": "Sales email",
      "DestinationType": "Email",
      "Enabled": true,
      "OutputFormat": "Acrobat Format (*.pdf)",
      "To": [
        "[email protected]"
      ],
      "Cc": [],
      "Bcc": [],
      "Subject": "Daily sales report",
      "Body": "Attached is the daily sales report.",
      "BodyFormat": "TEXT"
    }
  ],
  "DiskDestinations": [],
  "DataDriven": false,
  "PowerBiAccountId": "7f320302-7ccb-4aba-a052-56197424ab36",
  "ObjectType": "REPORT",
  "ReportUrl": "https://app.powerbi.com/reportEmbed?reportId=64e25062-4786-43be-bfea-56ec8b9aaeca",
  "PowerBiReportName": "Sales overview",
  "WorkspaceName": "Sales",
  "ApplyBookmark": false,
  "ApplyBookmarkState": false,
  "RenderingSettings": {
    "MinLoadingTime": 10,
    "MaxLoadingTime": 60,
    "PageWidth": 1300,
    "PageHeight": 800,
    "PagesToRender": "",
    "RenderingMethod": 1
  },
  "BasicFilters": [],
  "AdvancedFilters": []
}

Replace the example report, account, path, date, and recipient values. Add any mandatory report filters before submitting.

ExecutionTime is local PBRS schedule time. If your portal accepts times in another timezone, define how the backend converts them and handles daylight-saving changes.

An empty PagesToRender selects all pages.

A successful creation returns:

{
  "uniqueid": 101
}

Persist the returned ID and the authoritative request definition.

Then retrieve the schedule:

GET /api/SingleSchedule/Get?Id=101

Confirm the report, recurrence, destinations, and intended enabled state before completing the portal workflow.

Manage edits

Present users with the supported editable fields for the selected report source.

Use a dedicated operation when it matches the requested change. Otherwise, construct the complete source-specific update request.

Complete schedule updates

For a full update:

1. Authorize the portal user.
2. Retrieve the current PBRS resource.
3. Compare it with the stored definition and expected version.
4. Preserve settings unrelated to the requested edit.
5. Include the complete report and destination collections required by the operation.
6. Preserve retained destination IDs.
7. Submit the update.
8. Retrieve and verify the saved result.

Read responses can omit settings. Do not build every update by blindly returning the latest GET response.

Serialize competing portal edits or use application-level version checks. Account for changes made directly in PBRS so that a portal update does not silently overwrite them.

Email-only changes

For supported single schedules, the dedicated email update endpoint can change recipients and message fields:

PUT /api/SingleSchedule/UpdateEmailDestination

Use explicit null values to preserve Cc, Bcc, and BodyFormat when those fields are not being changed. Omitted values can reset them.

Verify that the destination belongs to the authorized schedule before submitting its ID.

See Manage Destinations and Output Settings for the complete field behavior.

Pause and resume scheduling

For a Power BI single schedule, enable recurring execution with:

POST /api/Schedule/EnableSchedule

{
  "ScheduleType": "report",
  "uniqueid": 101,
  "RunBy": "Portal"
}

Disable future scheduled execution using the same body with:

POST /api/Schedule/DisableSchedule

Both operations return HTTP 200 with an empty body.

Disabling a schedule does not guarantee cancellation of an execution already running. Display schedule enabled state separately from execution state.

RunBy is descriptive information. It does not replace the portal’s authorization or audit record.

Run a schedule on demand

After authorizing the request, submit:

POST /api/Schedule/ExecuteScheduleAsync

{
  "ScheduleType": "report",
  "uniqueid": 101,
  "RunBy": "Portal"
}

For a package, use ScheduleType: "package" and the package’s ID.

Store the returned ExecutionId against the portal operation and schedule.

Do not substitute ExecuteScheduleOnTimeAsync for a normal on-demand run when preserving the next scheduled run matters. The scheduled-time mode advances NextRun after completion.

Prevent accidental duplicate submissions

Create an application operation record before submitting work. Use it to control repeated button clicks and concurrent submissions.

If the response is lost, mark the operation as unresolved and reconcile it with PBRS activity before resubmitting.

An application operation ID does not create an idempotency guarantee inside PBRS.

Monitor execution

Have the backend poll:

GET /api/Schedule/GetExecutionStatus?ExecutionId=RETURNED_EXECUTION_ID

Return a filtered status response to the authorized portal user.

Suggested portal states include:

Parse ResultJson separately when populated. Completed can contain a failed result.

Do not label an execution “Delivered” solely because it completed. Use delivery evidence appropriate to the destination.

Keep durable portal records because the API queue is not a long-term archive.

Share schedules with existing PBRS users

When the workflow requires PBRS-level sharing, the backend can call:

POST /api/UserManager/ShareSchedulesToUsers

{
  "Id": 101,
  "Type": "report",
  "Users": [
    "report.viewer"
  ]
}

A successful response is HTTP 200 with an empty body.

Resolve the intended PBRS usernames from an authorized mapping. Do not accept an arbitrary list of usernames from the browser.

This operation shares a schedule with existing PBRS users. It does not create users, assign roles, transfer ownership, or establish a portal tenant boundary.

Provision users and permissions through the appropriate administrative process, then verify access using the intended identities.

Administrative catalogues

The public API also provides:

• GET /api/UserGroups/Get.
• GET /api/UserGroups/GetCustomTaskTypes.
• GET /api/UserGroups/GetDestinationTypes.

These operations require User Manager permission. An authenticated caller without that permission receives HTTP 403.

Use these catalogues only where the portal’s administrative workflow needs them. A listed task or destination category does not establish a public creation endpoint for that category.

Handle failures without losing state

Record each requested change and its outcome.

Do not expose raw PBRS exceptions, connection strings, or secrets in user-facing messages.

See Errors, Execution States, and Limits for response and retry behavior.

Control portal workload

Apply application-level limits to:

• Schedule creation frequency.
• Minimum recurrence intervals.
• Run-now submissions.
• Recipient counts.
• Concurrent operations.
• Execution-status polling.

PBRS does not impose API request throttling, but execution capacity and upstream services remain constrained.

A free-capacity response is a snapshot, not a reservation.

For larger workloads, queue portal requests and monitor execution pressure instead of allowing repeated browser actions to create uncontrolled submissions.

Validate before launch

Verify the complete workflow with representative users and reports:

1. Users see only their approved report catalogue.
2. Changing a portal resource ID does not expose another user’s schedule.
3. Destination and execution IDs cannot bypass authorization.
4. Mandatory data filters remain enforced.
5. Creation preserves the intended recurrence and recipients.
6. Edits retain unrelated settings and destinations.
7. Pause, resume, and run-now actions behave distinctly.
8. Repeated submissions do not cause automatic duplicate creation or delivery.
9. Failed and unresolved executions are displayed accurately.
10. PBRS sharing matches the intended user access.
11. Generated reports contain the correct data.
12. Recipients receive only their intended output.

Keep these checks in your integration validation process when changing portal permissions, PBRS configuration, or supported report workflows.