The PBRS API is used for collaboration and other system functions. PBRS API allows you to run schedules as well as control the scheduling services. Here is how to install and configure it if needed.
Options - PBRS API
The PBRS API is used for collaboration and other system functions. PBRS API allows you to run schedules as well as control the scheduling services. You can use any programming language of your choice to query the API. Here is how to install and configure it if needed.
How to Install the PBRS API?
- Go to Options.
- Go to REST API.
API Settings
- The API Settings section is used for collaboration and other system functions.
- Click Install API.
- Enter your windows credentials to install API.
- Click OK.
- Click Yes.
- Click OK.
- PBRS API is installed.
- Click Start to start the PBRS API Service.
- The PBRS API is configured and PBRS API Service is running.
API Clients
- API Clients section is used to give another application access to the PBRS API.
- Click Add.
- You only need to provide the Client name as the Client ID and Secret are automatically generated by PBRS.
- Once the Client name is added, click Save & Close.
How do I use the PBRS API?
Getting Started
PBRS’s API allows you to run schedules as well as control the scheduling services. You can use any programming language of your choice to query the API.
The PBRS API is a RESTful API based on HTTP requests and JSON responses. The easiest way to start using the PBRS API is by using Postman, a free tool which helps developers run and debug API requests, and is the source of truth for this documentation.
Unless otherwise specified, all requests must be made with the Content-Type set to application/x-www-form-urlencoded in the request header.
Authentication and Authorization
The PBRS API can use OAuth2 Client Credentials or Username and Password authentication and authorization flow. All API endpoints except the /api/service/ping require a valid access token for authorization.
Username and Password Flow
To request an access token using the credentials of a PBRS user, make a POST request as follows:
http://[pbrsserver]:9000/api/login/token
POST http://[pbrsserver]:9000/api/login/token
POST Body
string username
string password
Example Result
{
"UserId": "jd",
"FirstName": "John",
"LastName": "Doe",
"role": "Administrator",
"ExpiryDateEpoch": 1617803400,
"token": "VEw+8f/9N1D8ZiJOmOses38Wad0RD/NU9jUDIVVK8CeUcmIjErSZDn965NVmSlEZJd3gfRbkUajd5dCNm87c295S1TO4RKbeJUho6t6XEJUdiJSs1T4WY2xEaR75RqufM3Xi3u55Pp3AsQX0jmN0wcOe/26k1y3feM8hZmnjffbDYZT7azIpiebLBPaXhY6dAA==",
"token_type": "custom"
}
Client Credentials Flow
In order to use obtain an access token, you must first add the Client application to PBRS. This is done under the Configuration/PBRS API screen.
You only need to provide the Client name as the Client ID and Secret are automatically generated by PBRS.
To request an access token, make a POST request as follows:
http://[pbrsserver]:9000/oauth2/token
POST http://[pbrsserver]:9000/oauth2/token
POST Body
string grant_type: client_credentials
string client_id
string client_secret
Result
{
string access_token
string token_type: bearer
int expires_in
}
Below is an example of what a successful authentication result looks like:
{
"access_token": "AQAAANCMnd8BFdERjHoAwE_...",
"token_type": "bearer",
"expires_in": 86399
}
PBRS API tokens expire in 24 hours.
Once the access token has been obtained, it must be included as part of your API request headers.
For the username and password flow, the request header must include:
Authorization: token {access_token}
For client credentials flow include:
Authorization: bearer {access_token}
EndPoints
The API is accessed by making HTTP requests to a specific URL endpoint, in which GET or POST variables contain information about what you wish to access. Every endpoint is accessed via the port and protocol configured in PBRS. The PBRS API Service must also be running on the PBRS server.
The default starting endpoint for the API is:
http://[pbrsserver]:9000/api
Service EndPoint
The Service Endpoint allows you to query and control the PBRS services.
Ping
To check if the API is up and running, you can use Ping. The call will return 1 when the API is running.
GET /api/service/ping
Result:
int i
IsSchedulerRunning
To check if the PBRS scheduler is running:
GET /api/service/isschedulerrunning
Result:
{
bool Result
}
GetConfigPath
To get the path to the PBRS config file:
GET /api/service/getconfigpath
Result:
{
string Result
}
UpdateCollaborationSettings
To update the collaboration settings for a server:
POST /api/service/updatecollaborationsettings
POST Body
bool IsCollaborationEnabled
int CollaborationId
string CollaborationLeader
string ConType
string ConString
string ConString2
Schedule Endpoint
The Schedule endpoint allows you to control PBRS schedules. Where a schedule type must be specified, the following are valid:
-
"report" or “single”: all Single and Data-Driven Schedules
-
"automation": all Automation schedules
-
"package": all Single and Data-Driven Package schedules
-
"event": all Event-Based schedules
-
“event-package" or “eventpackage”: all Event-Based Package schedules
The schedule’s unique Id can be obtained from the schedule’s properties screen in the application GUI.
ExecuteSchedule
Synchronously kicks off a schedule and waits for its completion.
POST api/schedule/executeschedule
POST Body
string ScheduleType
int UniqueId
string RunBy
Result
{
bool Result
string ErrorMessage
int ErrorNumber
}
ExecuteScheduleOnTimeAsync
Asynchronously kicks off the schedule as if it is being run by the scheduler. At completion, the schedule’s NextRun date will be incremented.
POST api/schedule/executescheduleontimeasync
POST Body
string ScheduleType
int UniqueId
string RunBy
Result
{
string ExecutionId
}
ExecuteScheduleAsync
Asynchronously kicks off a schedule and does not wait for its completion. The resulting ExecutionId can be used to query the execution status
POST api/schedule/executescheduleasync
POST Body
string ScheduleType
int UniqueId
string RunBy
Result
{
string ExecutionId
}
GetNumberOfFreeThreads
Gets the number of threads that are available for schedule execution based on the configured maximum thread count set in the application.
GET api/schedule/getnumberoffreethreads
Result
{
int Result
}
CancelExecution
Attempts to cancel an existing async execution:
GET api/schedule/cancelexecution?ExecutionId={ExecutionId}
Result
{
string Result
}
GetExecutionStatus
Retrieves the status of a schedule execution. The status can be one of:
-
Waiting
-
Executing
-
Completed
GET api/schedule/GetExecutionStatus?ExecutionId={ExecutionId}
Result
{
string ExecutionId
int UniqueId
int ProcessId
string Status
long EntryDateEpoch
long CompletionDateEpoch
string RunBy
string ResultJson*
string ServerName
}
*ResultJson Format
{
bool success
string errormessage
}
Folder Endpoint
The Folder endpoint allows you to traverse the entire PBRS folder hierarchy including schedules.
Get
Retrieves the details about a Folder based on the provided Id. To get the topmost folder, provide 0 as a the folder id.
GET api/folder/get/{id}
Result
{
int FolderId
string folderName
int FolderParent
}
GetSubFolders
Retrieves an array of folders for the given folder id.
GET api/folder/getsubfolders/{id}
Result
[
{
int FolderId
string folderName
int FolderParent
}
]
GetSchedules
Retrieves an array of schedules for the given folder id.
GET api/folder/getschedules/{id}
Result
[
{
int UniqueId
string Name
string ScheduleType
bool IsDataDriven
bool IsEnabled
}
]
GetUniqueIdFromPath
Returns the unique identifier of any schedule in a given folder path.
POST api/folder/getuniqueidfrompath
POST Body
string Path
string ScheduleName
string ScheduleType
Result
{
int UniqueId
}
GetFolderFromPath
Returns the folder object from the given path.
POST api/folder/getfolderfrompath
POST Body
string Path
Result
{
int FolderId
string folderName
int FolderParent
}
PowerBIAccount Endpoint
The PowerBIAccount endpoint allows you to interrogate the Power BI accounts in PBRS.
GetAll
Returns a collection of all the Power BI accounts in PBRS.
GET api/powerbiaccount/getall
Example Result
[
{
"AccountName": "Sales",
"AccountId": "16f471xb-87fb-4f74-8fea-0a5df5a8156b"
},
{
"AccountName": "Accounts",
"AccountId": "0247ef0a-1a50-427b-ac06-cfd711c54d16"
}
]
GetWorkspaces/{Id}
Returns a collection of all the workspaces in the specified Power BI account.
GET api/powerbiaccount/getworkspaces/{id}
Example Result
[
{
"Name": "My Workspace",
"Id": ""
},
{
"Name": "Tests",
"Id": "24a89913-81fe-4815-a822-8d49cxxxfec1"
},
{
"Name": "Dev",
"Id": "8b16abae-f65a-445d-b17d-2fbxxx4e59c7"
},
{
"Name": "Prod",
"Id": "23cb7428-af4d-4223-a445-7aa44cxxx45f"
},
{
"Name": "Paginated Reports",
"Id": "e4aa4920-d626-4ca3-9077-fb5250xxxf36"
},
{
"Name": "V2Workspace",
"Id": "1e83d0c8-1c2b-4b59-8093-7911xxx6b7e8"
}
]
GetReports
Returns a collection of reports in a given workspace.
POST api/powerbiaccount/getreports
POST Body
|
Field |
Type |
Desc |
|---|---|---|
|
AccountId |
string |
The Power BI account Id |
|
WorkspaceId |
string |
The Power BI Workspace Id |
Example Result
[
{
"Name": "Customer Profitability Sample",
"Url": "https://app.powerbi.com/reportEmbed?reportId=....&config=..."
},
{
"Name": "Queen City Dashboard",
"Url": "https://app.powerbi.com/reportEmbed?reportId=...&config=..."
}
]
GetDashboards
Returns a collection of reports in a given workspace.
POST api/powerbiaccount/getdashboards
|
Field |
Type |
Description |
|---|---|---|
|
AccountId |
string |
The Power BI account Id |
|
WorkspaceId |
string |
The Power BI Workspace Id |
Example Result
[
{
"Name": "Customer Map",
"Url": "https://app.powerbi.com/dashboardEmbed?dashboardId=...&config=..."
},
{
"Name": "Customer Profitability Sample",
"Url": "https://app.powerbi.com/dashboardEmbed?dashboardId=...&config=..."
}
]
SingleSchedule Endpoint
The SingleSchedule endpoint allows you to carry out CRUD operations related to PBRS single schedules.
CreateForPowerBI
POST api/singleschedule/createforpowerbi
POST Body
|
Field |
Type |
Description |
|---|---|---|
|
PowerBiAccountId |
string |
The Power BI account Id. |
|
ReportUrl |
string |
The embed url of the report |
|
PowerBiReportName |
string |
The name of the Power BI report. |
|
WorkspaceName |
string |
The name of the Power BI workspace. |
|
ApplyBookmark |
boolean |
Flag indicating if a Bookmark JSON will be provided for the report. |
|
BookmarkJson |
string |
The JSON string for the Bookmark. |
|
RenderingSettings |
renderingsettingsmodel |
The report rendering settings. (see below for fields) |
|
BasicFilters |
[powerbibasicfiltermodel] |
An array of zero or more basic filters. |
|
AdvancedFilters |
[powerbiadvancedfiltermodel] |
An array of zero or more advanced filters. |
|
ScheduleName |
string |
The name of the PBRS schedule. |
|
FolderPath |
string |
The path in PBRS to create the schedule. |
|
Description |
string |
The schedule description. |
|
Keywords |
string |
The schedule keywords. |
|
Schedule |
timeschedulebasemodel |
The definition for when the schedule will run. |
|
EmailDestinations |
[emaildestinationmodel] |
An array of 1 or more email destinations. |
Get
Returns the full single schedule model.
GET api/singleschedule/get/{id}
Result
{
"PowerBiAccountId": "16f471eb-87fb-4f74-8fea-0a5df5a8156b",
"ObjectType": "REPORT",
"ReportUrl": "https://app.powerbi.com/reportEmbed?reportId=017b23aa-ed0e-4ba1-a4fb-38908b16914f&config=eyJjbHVzdGVyVXJsIjoiaHR0cHM6Ly9XQUJJLVVTLUVBU1QyLXJlZGlyZWN0LmFuYWx5c2lzLndpbmRvd3MubmV0IiwiZW1iZWRGZWF0dXJlcyI6eyJtb2Rlcm5FbWJlZCI6dHJ1ZX19",
"PowerBiReportName": "Customer Profitability Sample",
"WorkspaceName": "My Workspace",
"ApplyBookmark": false,
"BookmarkJson": "",
"RenderingSettings": {
"OptionId": "5cb83ebd-a262-4732-a8b7-fad55526091f",
"ReportId": 670421871,
"MinLoadingTime": 10,
"MaxLoadingTime": 60,
"PageWidth": 1300,
"PageHeight": 800,
"PagesToRender": "1-3",
"PageOrientation": 0,
"MarginLeft": 0,
"MarginRight": 0,
"ViewStyle": 0,
"RenderingMethod": 2,
"TransparentBackground": true,
"MinReportSize": -1,
"CropPdf": false,
"PDFCompression": 0,
"CropLeft": 0,
"CropRight": 0,
"CropTop": 0,
"CropBottom": 0
},
"BasicFilters": [
{
"BasicValues": [
"Amezam",
"Sonic",
"QuestFP"
],
"Operator": "In",
"FilterId": "21d15577-17ab-4fec-bf9d-330bcae9cd55",
"TargetField": "Supplier.Name",
"FieldDataType": "String",
"FilterLevel": 0,
"SlicerSelectorType": 0,
"SlicerSelectorValue": "",
"SlicerSelectorRawValue": {
"name": null,
"title": null,
"type": null
},
"IgnoreBlankDataDrivenInserts": true
}
],
"AdvancedFilters": null,
"ScheduleName": "API Created Schedule",
"FolderPath": "Annual",
"UniqueId": 670421871,
"Description": "This is a sample schedule created via the API",
"Keywords": "API, PBRS, Testing",
"Schedule": {
"Frequency": "Daily",
"StartDate": "2021-03-30",
"HasEndDate": false,
"EndDate": "2030-03-31",
"ExecutionTime": "14:00:00",
"Repeat": false,
"RepeatInterval": 0.25,
"RepeatUnit": null,
"RepeatUntil": "00:00:00",
"Enabled": true,
"ScheduleId": 670421872,
"NextRunEpochUtc": 1617127200,
"ParentId": 670421871,
"Description": "This is a sample schedule created via the API",
"Keywords": "API, PBRS, Testing"
},
"EmailDestinations": [
{
"To": [
"user@company.com"
],
"Cc": [],
"Bcc": [],
"Subject": "API Created Schedule Email",
"Body": "Hello this is a test message",
"BodyFormat": "TEXT",
"EmbedReport": false,
"EmbedFormat": "IMAGE",
"CustomSenderName": "",
"CustomerSenderAddress": "",
"DestinationName": "Email Destination via API",
"DestinationId": 670421872,
"DestinationType": "Email",
"OutputFormat": "Acrobat Format (*.pdf)",
"CustomOutputFileName": "",
"CustomOutputExtension": "",
"Enabled": true,
"ParentId": 670421871
},
{
"To": [
"user@company.com",
"user2@company.com"
],
"Cc": [
"user3@company.com"
],
"Bcc": [],
"Subject": "API Created Schedule Email",
"Body": "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.0 Transitional//EN\">\r\n<HTML><HEAD>\r\n<META http-equiv=\"Content-Type\" content=\"text/html; charset=unicode\">\r\n<META name=\"GENERATOR\" content=\"MSHTML 11.00.10570.1001\"></HEAD>\r\n<BODY style=\"font-family: Verdana; font-size: 12px;\">\r\n<P>Hello this is a test message</P></BODY></HTML>\r\n",
"BodyFormat": "HTML",
"EmbedReport": false,
"EmbedFormat": "IMAGE",
"CustomSenderName": "",
"CustomerSenderAddress": "",
"DestinationName": "Email Destination via API",
"DestinationId": 670425094,
"DestinationType": "Email",
"OutputFormat": "Acrobat Format (*.pdf)",
"CustomOutputFileName": "",
"CustomOutputExtension": "",
"Enabled": true,
"ParentId": 670421871
}
],
"PackId": 0,
"Owner": "swa"
}
UpdateForPowerBI
This method updates a PowerBI single schedule and uses the same POST body as the CreateForPowerBI method.
POST api/singleschedule/updateforpowerbi
AddEmailDestination
Adds an email destination to an existing single schedule.
POST api/singleschedule/addemaildestination
POST Body
|
Field |
Type |
Description |
|---|---|---|
|
ParentId |
integer |
The unique Id of the parent schedule. |
|
DestinationName |
string |
The name of the destination. |
|
OutputFormat |
string |
The output format for the destination. Valid values are:
|
|
CustomOutputFileName |
string |
Optional custom output file name. |
|
CustomOutputExtension |
string |
Optional custom output file extension. |
|
Enabled |
boolean |
Specifies if the destination is enabled or not. |
|
To |
[string] |
An array of one or more email addresses to send the report to. |
|
Cc |
[string] |
An array or zero or more email addresses to send the report to. |
|
Bcc |
[string] |
An array or zero or more email addresses to send the report to. |
|
Subject |
string |
The email subject. |
|
Body |
string |
The email body as plain text or escaped HTML. |
|
BodyFormat |
string |
The format of the email body. Valid options are HTML or TEXT. |
|
EmbedReport |
boolean |
Indicates if the report should be embedded in the body of the email. |
|
EmbedFormat |
string |
The format that the embedded report will be. Valid options are IMAGE or HTML. |
|
CustomSenderName |
string |
The sender name that will appear when the email is sent. |
|
CustomerSenderAddress |
string |
The custom reply-to email address. |
Dependent Models
RenderingSettingsModel
|
Field |
Type |
Description |
|---|---|---|
|
MinLoadingTime |
int |
The minimum amount of time that PBRS will wait before proceeding to render a Power BI report to file. |
|
MaxLoadingTime |
int |
The maximum amount of time that PBRS will wait before proceeding to render a Power BI report to file. |
|
PageWidth |
int |
The width of the Power BI report. |
|
PageHeight |
int |
The height of the Power BI report. |
|
PageOrientation |
int |
The orientation of the Power BI report. Valid values are:
|
|
PagesToRender |
string |
The range of pages to render e.g. 1,2,3,5-10. Leave blank for all pages. |
|
MarginLeft |
int |
The page’s left side margin. |
|
MarginRight |
int |
The page’s right side margin. |
|
ViewStyle |
int |
The Power BI report fit style. Valid values are:
|
|
RenderingMethod |
int |
The method to use for rendering the Power BI report. Valid values are:
|
|
TransparentBackground |
boolean |
Indicates whether the rendered report should include the background image. |
|
MinReportSize |
int |
An optional size that PBRS will use to determine whether or not a report was rendered successfully. If the report output size is less than this value, then the report will be re-rendered. |
|
CropPdf |
boolean |
Indicates if PBRS should crop the PDF output. |
|
CropLeft |
int |
The mount of pixels to crop the PDF by from the left edge. |
|
CropRight |
int |
The mount of pixels to crop the PDF by from the right edge. |
|
CropTop |
int |
The mount of pixels to crop the PDF by from the top edge. |
|
CropBottom |
int |
The mount of pixels to crop the PDF by from the bottom edge. |
|
PDFCompression |
int |
How much compression to apply to the rendered PDF. Valid values are:
|
PowerBiFilterBaseModel
|
Field |
Type |
Description |
|---|---|---|
|
TargetField |
string |
The field that the filter will be applied to e.g. Sales.OrderId. |
|
FieldDataType |
string |
The target field’s data type. Valid values are:
|
|
FilterLevel |
int |
Indicates if the filter should be applied to a slicer or page. Valid values are:
|
|
SlicerSelectorType |
int |
For slicer filters, indicates if the selector is a Visual title or the field that your slicer is based on. Valid values are:
|
|
SlicerSelectorValue |
string |
Holds either the slicer’s visual title or the slicer’s target field depending on the SlicerSelectorType above. |
|
IgnoreBlankDataDrivenInserts |
boolean |
indicates if the filter should be ignored if its data-driven value is empty. |
|
BasicValues |
[string] |
An array of one or more values for the filter. |
|
Operator |
string |
The basic filter operator. Value can be either “In” or “NotIn”. |
PowerBiBasicFilterModel
This model inherits from the PowerBiFilterBaseModel.
|
Field |
Type |
Description |
|---|---|---|
|
BasicValues |
[string] |
An array of one or more values for the filter. |
|
Operator |
string |
The basic filter operator. Value can be either “In” or “NotIn”. |
PowerBiAdvancedFilterModel
This model inherits from the PowerBiFilterBaseModel.
|
Field |
Type |
Description |
|---|---|---|
|
Operator |
string |
The filter operator. Valid values are:
|
|
FirstCondition |
key-value pair of string and string |
A key-value pair of the operator and the value for the advanced filter condition. |
|
SecondCondition |
key-value pair of string and string |
A dictionary of the operator and the value for the advanced filter condition. |
TimeScheduleBaseModel
|
Field |
Type |
Description |
|---|---|---|
|
Description |
string |
The schedule’s description. |
|
Enabled |
boolean |
Indicates if the schedule should be enabled. |
|
EndDate |
string |
If applicable the schedule’s end date in the format yyyy-MM-dd. |
|
ExecutionTime |
string |
The schedule’s execution time in the format HH:mm e.g. 14:00 for 2PM. |
|
Frequency |
string |
The frequency of the schedule. Valid values are:
|
|
HasEndDate |
boolean |
Indicates if the schedule has an end date. |
|
Keywords |
string |
The schedule’s keywords. |
|
NextRunEpochUtc |
readonly int |
The schedule’s next run date represented as Unix date. |
|
Repeat |
bool |
Indicates if the schedule should repeat after the execution time. |
|
RepeatInterval |
double |
The repetition interval. |
|
RepeatUnit |
string |
The repeat interval. Valid values are:
|
|
RepeatUntil |
string |
When the schedule will repeat until in the format HH:mm. |
|
StartDate |
string |
The start date of the schedule in the format yyyy-MM-dd e.g. 2021-04-07 for April 7th 2021. |