How do I use the 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. 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. 

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.

Get Token

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
}

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
}

GetExecutionQueue

Returns an array of schedules that have been executed in the past 12 hours as well those waiting to be executed and currently executing.

 GET api/schedule/GetExecutionQueue

[
{
string ExecutionId 
int UniqueId
int ProcessId
string Status
int EntryDateEpoch
int CompletionDateEpoch
string RunBy
string ResultJson 
string ServerName
string ScheduleType
string ScheduleName
}
]

Folder Endpoint

The Folder endpoint allows you to traverse the entire PBRS folder hierarchy including schedules.

Get Folder

Retrieves the details about a Folder based on the provided ID. To get the topmost folder, provide folder ID.

 GET api/folder/get/{id}

{
int FolderId
string folderName
int FolderParent
}

GET api/folder/getsubfolders/{id}

[
{
int FolderId
string folderName
int FolderParent
}
]

GET api/folder/getschedules/{id}

[
 {
 int UniqueId
 string Name
 string ScheduleType
 bool IsDataDriven
 bool IsEnabled
 }
]

POST api/folder/getuniqueidfrompath

string Path
string ScheduleName
string ScheduleType

{
int UniqueId
}

POST api/folder/getfolderfrompath

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 Power BI reports in a given workspace.

GET api/powerbiaccount/getreports

GET Body

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 Power BI dashboards in a given workspace.

GET api/powerbiaccount/getdashboards

GET Body

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=..."
    }
]

GetVisualsForReport

Returns a collection of all the visuals in a given report and their respective Power BI page index.

GET api/powerbiaccount/getvisualsforreport

POST Body

GetPaginatedReports

Returns a collection of Paginated Reports in a given workspace.

GET api/powerbiaccount/getpaginatedreports

GET Body

SingleSchedule Endpoint

The SingleSchedule endpoint allows you to carry out CRUD operations related to PBRS single schedules.

GetAll

Retrieves all Power BI Single Schedules in PBRS regardless of folder location based on the Schedules' Keywords. If the body is not provided, the request will return an empty array.

GET api/singleschedule/getall

GET Body

GetAllPaginated

Retrieves all Power BI Paginated Report Single Schedules in PBRS regardless of folder location based on the Schedules' Keywords. If the body is not provided, the request will return an empty array.

GET api/singleschedule/getallpaginated 

GET Body

Get Single Schedule

Returns the full Power BI 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"
}

GetPaginated

Returns the object representing a Paginated Single schedule.

GET api/singleschedule/getpaginated/{id}

CreateForPowerBI

This is to create Power BI Single Schedules. 

POST api/singleschedule/createforpowerbi

POST Body

CreatePaginated

This is to create Power BI Paginated Single Schedules. 

POST api/singleschedule/createpaginated

POST Body

UpdateForPowerBI

This method updates a Power BI Single schedule and uses the same POST body as the CreateForPowerBI method.

POST api/singleschedule/updateforpowerbi

AddEmailDestination (EmailDestinationModel)

Adds an email destination to an existing Power BI single schedule.

POST api/singleschedule/addemaildestination

POST Body

PackageSchedule Endpoint

The PackageSchedule endpoint allows you to carry out CRUD operations related to PBRS Package schedules.

GetAll

Retrieves all Power BI Packaged in PBRS regardless of folder location based on the Schedules' Keywords. If the body is not provided, the request will return an empty array.

GET api/packageschedule/getall

GET Body

Get Package

Returns the full Package Schedule model for a specific package.

GET api/packageschedule/get/{id}

Create

This is to create Power BI packages.

POST api/packageschedule/create

Dependent Models

PowerBIDataOnlyExportModel

RenderingSettingsModel

PowerBiFilterBaseModel

PowerBiBasicFilterModel

This model inherits from the PowerBiFilterBaseModel.

PowerBiAdvancedFilterModel

This model inherits from the PowerBiFilterBaseModel.

TimeScheduleBaseModel

PackagedPowerBIReportModel

DataDriverModel

PaginatedParameterModel