How to Schedule Dashboards with Parameters Using an API

Published:

Overview

Scheduling a dashboard with parameters through an API allows for automated reporting tailored to specific criteria. This guide outlines the steps to schedule a dashboard that filters data based on parameters, such as department.

Step 1: Ensure Dashboard is Parameterized

Before scheduling, confirm that the dashboard is set up to pull data based on parameters. For example, if the dashboard displays employee details by department, ensure it can filter data for specific departments like Sales and Marketing.

In this scenario, if the goal is to send an email to external recipients in the Sales department, the parameter to pass will be:

Department=Sales

Step 2: Generate Access Token

To interact with the API, an access token is required. Follow these steps to generate the token:

API URL: Use the following endpoint to obtain the token:
```
http://localhost:8085/bi/api/site/site1/token
```
Request Format: Set the Content-Type to application/json and include the following JSON body in your request:
```
{
  "username": "testuser@boldbi.com",
  "password": "Admin@123",
  "grant_type": "password"
}
```
Authentication: This request will return an access token that will be used in subsequent API calls.

Step 3: Use Add Schedule API

Once the access token is obtained, you can schedule the dashboard using the Add Schedule API.

Request Format

The API endpoint for creating a new schedule is as follows:

http://localhost:8085/bi/api/site/site1/v5.0/dashboards/schedules

Authorization

You must include a token in the Authorization header to authenticate your request. The format is:

Authorization: Bearer <token>

Request Body

The body of the request should be in JSON format and include the following parameters:

{
  "Name": "TestingScheduleWithParameter",
  "ItemId": "5f9b220a-f9ff-44e7-90b2-882bc7d928d4",
  "ExportType": "Image",
  "StartTime": "2025-08-04T15:20:40Z",
  "Parameter": "Department=Sales",
  "NeverEnd": true,
  "EndAfterOccurrence": 0,
  "EndDate": "2025-08-11T15:04:40Z",
  "UserList": ["testuser@boldbi.com"],
  "ExternalRecipientsList": ["testuser@boldbi.com"],
  "ScheduleType": "Hourly",
  "IsEnabled": true,
  "FailureNotificationToOwner": true,
  "FailureNotificationToRecipient": true,
  "FailureOccurrence": 0,
  "ExportFormatInfo": {
    "ExportType": "Image",
    "Extension": "jpg",
    "Resolution": 96
  },
  "Email": {
    "Subject": "Organization Name: Your scheduled dashboard",
    "Body": "Hello Username,\n\nPlease find attached, the dashboard that you had requested.\n\nSchedule- ScheduleName has exported the dashboard [DashboardName](DashboardLink).\n\nRegards,\n\nOrganization Name"
  },
  "HourlySchedule": {
    "ScheduleInterval": "0:15"
  }
}

Parameter Descriptions

Name: The name of the schedule.
ItemId: The unique identifier of the dashboard to be scheduled.
ExportType: The type of export (e.g., Image).
StartTime: The start time for the schedule in UTC format.
Parameter: Any parameters to be passed to the dashboard (e.g., filters).
NeverEnd: A boolean indicating if the schedule should never end.
EndAfterOccurrence: The number of occurrences after which the schedule should end (0 means it will not end based on occurrences).
EndDate: The date when the schedule should end.
UserList: A list of users who will receive the scheduled report.
ExternalRecipientsList: A list of external recipients for the scheduled report.
ScheduleType: The type of schedule (e.g., Hourly).
IsEnabled: A boolean indicating if the schedule is enabled.
FailureNotificationToOwner: A boolean indicating if the owner should be notified on failure.
FailureNotificationToRecipient: A boolean indicating if recipients should be notified on failure.
FailureOccurrence: The number of failures after which notifications should be sent.
ExportFormatInfo: Information about the export format, including type, extension, and resolution.
Email: The email subject and body to be sent with the scheduled report.
HourlySchedule: Details about the hourly schedule, including the interval.

Email Delivery: The scheduled email will be sent to the specified recipients, ensuring that only the data related to the Sales department is visible in the shared mailbox.

Conclusion

By following these steps, you can successfully schedule a dashboard with parameters via API, ensuring that the right data reaches the intended recipients.

Additional References

Was this article useful?

Dislike

Written by Mahendran Maragatha Patchai

Updated:

Comments (0)