Configure Filters, Parameters, Bookmarks, and Rendering

Control report content and presentation through Power BI filters, report parameters, bookmarks, and rendering settings.

These settings belong to the source-specific schedule definition. Include them when creating a schedule or preparing a complete update.

Before you begin

You need:

• An authenticated connection to the PBRS REST API.
• Access to the selected report.
• The report's field, parameter, and visual information.
• A schedule definition appropriate to the report source.
• A controlled destination for verifying the output.

Complete Create and Update Single Schedules before applying these settings.

The JSON examples below are sections of a schedule definition, not complete API requests. Merge the relevant sections into the request for your selected create or update operation.

Choose settings for the report source

Do not copy fields between source models unless the target operation supports them.

Report filters are separate from the schedule keywords used to search for schedules. Changing Keywords does not filter report content.

1. Configure basic Power BI filters

Basic filters include or exclude a list of values from a report field.

Add them to the top-level BasicFilters array:

{
  "BasicFilters": [
    {
      "TargetField": "Sales.Region",
      "FieldDataType": "String",
      "FilterLevel": 0,
      "Operator": "In",
      "BasicValues": [
        "West",
        "Central"
      ],
      "IgnoreBlankDataDrivenInserts": false
    }
  ],
  "AdvancedFilters": []
}

Replace Sales.Region with a field in your report's data model.

BasicValues contains strings even when the target field represents another datatype. Match the field datatype and the value representation expected by the report.

Use actual model field names, not a chart title or display label. Preserve a working target expression when updating an existing filter, particularly where names contain special characters.

Blank and empty values

These values are not interchangeable:

• An omitted filter.
• An empty filter collection.
• An empty BasicValues array.
• An empty string within BasicValues.
• A blank value in the report's data model.

Do not assume that an empty value list means “select everything.”

Use an appropriate blank comparison when the intention is to select blank report values, and verify the resulting output.

Do not rely on IgnoreBlankDataDrivenInserts as a general null-handling rule or a substitute for validating recipient-specific filter values.

2. Configure advanced Power BI filters

Advanced filters use comparison conditions and a logical operator.

The outer Operator combines the conditions. Each condition has a comparison Key and a string Value.

{
  "AdvancedFilters": [
    {
      "TargetField": "Customer.Name",
      "FieldDataType": "String",
      "FilterLevel": 0,
      "Operator": "Or",
      "FirstCondition": {
        "Key": "StartsWith",
        "Value": "A"
      },
      "SecondCondition": {
        "Key": "StartsWith",
        "Value": "B"
      },
      "IgnoreBlankDataDrivenInserts": false
    }
  ]
}

This example selects values beginning with A or B.

Logical operators

Comparison operators

Choose comparisons appropriate to the field datatype and reporting engine.

For a single-condition filter, supply FirstCondition and omit SecondCondition rather than inventing a second comparison.

Each supplied condition requires both Key and Value. For a blank comparison, an empty string can supply the condition's string-valued operand; do not substitute JSON null for a required string.

Keep logical operators in the outer Operator field. Do not place And or Or in a condition's Key.

3. Target a slicer

Use FilterLevel: 1 when configuring a supported slicer filter.

Selector values are:

For title-based selection, use the exact title of the intended slicer in SlicerSelectorValue.

Retain the field target and other selector information required by the working report configuration. A visual title identifies a visual; it is not a replacement for every target-field setting.

If titles are duplicated, blank, or changed, verify that the selector still identifies the intended slicer. Do not assume every visual supports slicer operations.

Use Discover Folders, Reports, and Reporting Resources to inspect available report visuals.

4. Set Power BI paginated report parameters

Add parameter objects to the top-level Parameters array:

{
  "Parameters": [
    {
      "ParameterName": "Region",
      "ParameterValue": "West",
      "ParameterType": 0,
      "IsNull": false
    },
    {
      "ParameterName": "MinimumSales",
      "ParameterValue": "1000",
      "ParameterType": 1,
      "IsNull": false
    }
  ]
}

Use the parameter names defined by the report.

Parameter types

ParameterValue remains a string for all these types. For example, a numeric value is "1000", not a JSON number.

Use a value format accepted by the selected report. Do not infer date or boolean formatting solely from the numeric type selector.

Null and multivalue parameters

Use IsNull when the report accepts null. An empty string and a null parameter are different values.

Do not substitute a JSON array for ParameterValue. This field is a string. For multivalue requirements, use the representation supported by the specific operation and report rather than assuming comma-separated text or repeated parameters will work.

For parameter-only changes, use Update Paginated Report Parameters instead of preparing a full schedule update unnecessarily.

5. Set SSRS parameters

SSRS schedule parameters use a different structure:

{
  "Parameters": [
    {
      "ParameterName": "Region",
      "ParameterValues": {
        "West": "West"
      },
      "IsMultiValue": false,
      "IsNull": false
    }
  ]
}

ParameterValues is a string-to-string dictionary. It is not the paginated report's singular ParameterValue field.

Use report metadata to establish the valid values and their mapping. Do not assume display labels and underlying values are always identical.

Set IsMultiValue according to the report parameter, and use IsNull only when the parameter accepts null.

Dependent parameters

For cascading parameters:

1. Retrieve the report's parameter definitions.
2. Select valid values for the upstream parameters.
3. Request updated metadata using GetReportParametersWithValues and CurrentValues.
4. Choose downstream values from the resulting metadata.
5. Include the intended parameter configuration in the schedule.

CurrentValues belongs to the metadata request. It is not a replacement for the schedule's Parameters array.

Power BI Report Server uses its own schedule parameter model. Do not automatically reuse the SSRS dictionary structure in a PBIRS request.

6. Apply a Power BI bookmark

Power BI schedule definitions expose two bookmark representations:

Both companion values are strings.

Bookmark JSON

Set ApplyBookmark to true and supply valid bookmark JSON encoded as a string in BookmarkJson.

Do not insert the bookmark as a nested object. Let your JSON serializer escape the string when serializing the complete schedule.

For example, when preparing a PowerShell schedule hashtable:

$PbrsBookmarkFile = Read-Host "Path to the report's bookmark JSON file"
$PbrsBookmarkJson = Get-Content -LiteralPath $PbrsBookmarkFile -Raw

if ([string]::IsNullOrWhiteSpace($PbrsBookmarkJson)) {
    throw "The bookmark JSON file is empty."
}

$null = $PbrsBookmarkJson | ConvertFrom-Json -ErrorAction Stop

$PbrsDefinition.ApplyBookmark = $true
$PbrsDefinition.BookmarkJson = $PbrsBookmarkJson
$PbrsDefinition.ApplyBookmarkState = $false
$PbrsDefinition.BookmarkState = ""

The file must contain a bookmark representation compatible with the selected report and PBRS workflow. Valid JSON syntax alone does not establish that the bookmark is usable.

Bookmark state

Set ApplyBookmarkState to true only when BookmarkState contains a valid, nonempty state for the selected report.

Do not replace the state with a bookmark display name, report URL, or arbitrary JSON.

Use one bookmark representation at a time. Do not depend on an order of precedence when both representations are enabled.

Disable bookmark application

When no bookmark should be applied:

{
  "ApplyBookmark": false,
  "BookmarkJson": "",
  "ApplyBookmarkState": false,
  "BookmarkState": ""
}

When combining bookmarks and filters, verify the final output. Do not assume a bookmark and separately supplied filters will resolve conflicting selections in a particular order.

7. Configure rendering

For supported Power BI and PBIRS schedule operations, use the top-level RenderingSettings object.

{
  "RenderingSettings": {
    "MinLoadingTime": 10,
    "MaxLoadingTime": 60,
    "PageWidth": 1300,
    "PageHeight": 800,
    "PagesToRender": "",
    "PageOrientation": 1,
    "MarginLeft": 0,
    "MarginRight": 0,
    "ViewStyle": 1,
    "RenderingMethod": 1,
    "TransparentBackground": true,
    "MinReportSize": -1,
    "CropPdf": false,
    "PDFCompression": 1,
    "CropLeft": 0,
    "CropRight": 0,
    "CropTop": 0,
    "CropBottom": 0
  }
}

This example selects all report pages, landscape orientation, fit-to-page display, Chromium rendering, and low PDF compression.

Choose settings appropriate to the report and output format. Not every rendering option applies to every source, renderer, or output.

Loading and dimensions

Loading waits are separate from request timeouts, execution timeouts, and your application's polling deadline.

Increasing a loading wait does not resolve invalid credentials, missing report access, or an unavailable reporting service.

Page selection

PagesToRender uses one-based page numbers:

Visual-data exports use a separate zero-based PageNumber. Do not use visual page indexes directly in PagesToRender.

Orientation

Fit style

Set the intended value explicitly. A read response can supply fallback rendering settings when no stored settings exist; do not treat fallback values as proof of a previously saved configuration.

Rendering method

Use a rendering method supported by the selected report and deployment.

RenderingMethod is separate from a paginated schedule's UseNativeAPIForRendering option. They are not interchangeable.

PDF settings

Compression values are:

Inspect the resulting PDF for layout and image quality after changing cropping or compression.

Minimum report size

MinReportSize is an output-size threshold used to detect potentially incomplete rendering and request another rendering attempt.

It is not an API request-size limit or an execution-concurrency setting. The default value is -1. Preserve the existing value unless you have established an appropriate threshold for the report.

8. Submit changes without losing configuration

Use the applicable source-specific create or update operation.

For updates:

• Include the existing uniqueid.
• Preserve recurrence and enabled state.
• Include complete EmailDestinations and DiskDestinations arrays.
• Preserve each retained destination's DestinationId.
• Include all filters and parameters that should remain.
• Preserve the intended bookmark and rendering configuration.

Power BI updates rebuild filter collections. Sending empty filter arrays removes those filter definitions; it is not an instruction to leave them unchanged.

Existing destinations absent from the supplied destination arrays are removed.

Use RenderingSettings for writes. Do not replace it with ClientRenderingSettings or assume a read response contains every setting required for a lossless update.

Keep schedule-authoring models separate from import models. A similarly named field in an import definition does not automatically belong in a create or update request.

9. Verify the resulting report

After saving:

1. Retrieve the schedule through its source-specific read operation.
2. Confirm the intended configuration.
3. Execute a controlled test.
4. Inspect the execution result.
5. Open the generated report.
6. Verify content, layout, and delivery.

Check both included and excluded data. For example, a regional filter test should establish that the intended region appears and that unrelated regions do not.

Repeat testing after report-model changes, renamed fields, changed slicers, republished bookmarks, or altered page order.

Report personalization is not a substitute for access controls. Keep reporting-account permissions and recipient selection appropriate to the data being delivered.

Use data-driver values in report filters

For a data-driven package schedule, a report filter can use a value from the current data-driver record.

Use this insert syntax in the filter value:

<[r]fieldname>

Replace fieldname with the name of the field in your data-driver records.

Example

Suppose the current data-driver record contains:

{
  "recipient_id": 101,
  "agent_name": "Alex"
}

This object illustrates one data-driver record, not a complete schedule request.

To filter a report by this record's agent name, configure the report's agent-name filter with the following value:

<[r]agent_name>

When PBRS processes this record, the insert supplies Alex as the filter value. The next record supplies its own agent_name value.

The data-driver field name identifies the value to insert. Configure the report's target table, column or slicer separately.

See Create and Manage Report Packages for the package definition and data-driver configuration.

Verify the filtered output

Before enabling the schedule:

1. Test with records containing different agent names.
2. Check that each generated report contains the expected agent's data and excludes unrelated agents' data.
3. Check records with missing or blank filter values.
4. Verify the destination and recipient separately from the report filter.

Filtering controls the report's data. It does not determine who receives the output.

This example applies to report filter values. Do not assume the same insert syntax is supported in every API field, including email subjects, filenames, paths or recipient addresses.

Troubleshooting

Next steps

Continue with Export Power BI Visual Data to Excel for visual selection, workbook formatting, and template placement.

Use Update Paginated Report Parameters for parameter-only changes, or Manage Destinations and Output Settings to configure report delivery.