ssrs powerbi library

A Python library for automating Power BI Report Server (PBIRS) and SQL Server Reporting Services (SSRS) via the REST API v2.0. Designed to replace PowerShell ReportingServicesTools in CI/CD pipelines.

Repository: ipierre1/ssrs-powerbi-library

Features

• Easy API — connect once, get resource handle objects, call methods on them
• NTLM authentication — native Windows/domain credentials via requests-ntlm
• Power BI reports — upload, delete, data sources, data model parameters, cache refresh plans, security
• Paginated (SSRS) reports — upload, delete, data sources, report parameters, cache refresh plans, security
• Folder management — create, list, delete, security policies
• Schedule helpers — build daily / weekly / monthly schedules with a fluent API
• Row-level security — manage RLS role assignments on Power BI reports
• Typed exceptions — PBIRSNotFound, PBIRSConflict, PBIRSAuthError
• CI/CD ready — works in GitLab, GitHub Actions, Azure Pipelines, etc.

Installation

pip install ssrs-powerbi-library

Or from source:

git clone https://github.com/ipierre1/ssrs-powerbi-library.git
cd ssrs-powerbi-library
pip install -e .

Requirements: Python 3.8+, network access to PBIRS, NTLM-capable credentials.

Quick start

from ssrs_library import PBIRSClient

client = PBIRSClient(
    base_url="http://pbirs.corp.local/reports",
    username="svc_deploy",
    password="secret",
    domain="CORP",
)

client.test_connection()   # raises PBIRSAuthError / PBIRSError on failure

# Upload a .pbix
report = client.upload_powerbi_report(
    folder_path="/Sales",
    file_path="/ci/artifacts/Revenue.pbix",
    name="Revenue",
    overwrite=True,
)
print(report)  # <PowerBIReport name='Revenue' path='/Sales/Revenue'>

API reference

PBIRSClient

PBIRSClient(base_url, username, password, domain="", verify_ssl=True, timeout=30)

PowerBIReport

Obtained from client.get_powerbi_report(path) or client.upload_powerbi_report(...).

Properties

Lifecycle

report.delete()

Data sources

sources = report.get_datasources()          # List[DataSource]
report.set_datasources([ds1, ds2])          # full replace

Data model parameters

params = report.get_data_model_parameters()
report.set_data_model_parameters([
    {"Name": "Environment", "Value": "Production"},
    {"Name": "MaxRows",     "Value": "10000"},
])

Cache refresh plans

plans = report.get_cache_refresh_plans()    # List[CacheRefreshPlan]

plan = report.create_cache_refresh_plan(
    description="Nightly refresh",
    schedule=Schedule.daily(hour=2),
)

Catalog security (who can view/edit the report)

policies = report.get_policies()
# {"InheritParentSecurity": False, "Policies": [...]}

report.set_policies(policies)               # full overwrite

report.add_user("CORP\\alice", ["Browser"])
report.add_user("CORP\\admins", ["Content Manager"])
report.remove_user("CORP\\alice")

Built-in role names: "Browser", "Content Manager", "Publisher", "Report Builder".

Row-level security (data model RLS)

roles = report.get_data_model_roles()       # model role definitions
assignments = report.get_data_model_role_assignments()

report.set_data_model_role_assignments([
    {"GroupUserName": "CORP\\alice", "Roles": ["Region_West"]},
    {"GroupUserName": "CORP\\bob",   "Roles": ["Region_East"]},
])

# Convenience helpers (read-modify-write):
report.add_rls_user("CORP\\alice", ["Region_West", "Region_North"])
report.remove_rls_user("CORP\\alice")

PaginatedReport

Obtained from client.get_paginated_report(path) or client.upload_paginated_report(...).

Same properties as PowerBIReport. Additional methods:

Folder

Obtained from client.get_folder(path) or client.create_folder(path).

DataSource

from ssrs_library import DataSource

# SQL, integrated auth (default)
ds = DataSource("SalesDB", "Server=sql01;Database=Sales;")

# Stored credentials
ds = DataSource(
    name="SalesDB",
    connection_string="Server=sql01;Database=Sales;",
    credential_retrieval="Store",
    username="svc_report",
    password="secret",
    windows_credentials=False,
)

report.set_datasources([ds])

Schedule

Helper for building cache-refresh plan schedules.

from ssrs_library import Schedule

# Daily at 02:00 (default)
Schedule.daily()

# Daily at 06:30
Schedule.daily(hour=6, minute=30)

# Every 3 days at 04:00
Schedule.daily(hour=4, interval=3)

# Every Monday and Friday at 08:30
Schedule.weekly(["Monday", "Friday"], hour=8, minute=30)

# Every two weeks on Wednesday
Schedule.weekly(["Wednesday"], interval=2)

# 1st of every month at 03:00 (default)
Schedule.monthly()

# 15th of January and July at 01:00
Schedule.monthly(day=15, months=["January", "July"], hour=1)

Pass a Schedule instance (or a raw {"Definition": {...}} dict) to create_cache_refresh_plan() or plan.update().

CacheRefreshPlan

Obtained from report.get_cache_refresh_plans() or report.create_cache_refresh_plan(...).

plan.update(
    description="Updated nightly refresh",
    schedule=Schedule.daily(hour=3),
)

plan.execute()
plan.delete()

Exceptions

from ssrs_library import PBIRSError, PBIRSNotFound, PBIRSConflict, PBIRSAuthError

Configuration patterns

Direct (script / notebook)

from ssrs_library import PBIRSClient

client = PBIRSClient(
    base_url="http://pbirs.corp.local/reports",
    username="alice",
    password="secret",
    domain="CORP",
)

Environment variables (CI/CD)

import os
from ssrs_library import PBIRSClient

client = PBIRSClient(
    base_url=os.environ["PBIRS_URL"],
    username=os.environ["PBIRS_USER"],
    password=os.environ["PBIRS_PASSWORD"],
    domain=os.environ.get("PBIRS_DOMAIN", ""),
)

.env file (local development)

from dotenv import load_dotenv
import os
from ssrs_library import PBIRSClient

load_dotenv()
client = PBIRSClient(
    base_url=os.environ["PBIRS_URL"],
    username=os.environ["PBIRS_USER"],
    password=os.environ["PBIRS_PASSWORD"],
    domain=os.environ.get("PBIRS_DOMAIN", ""),
)

CI/CD deploy example

from ssrs_library import PBIRSClient, DataSource, Schedule, PBIRSConflict
import os

client = PBIRSClient(
    base_url=os.environ["PBIRS_URL"],
    username=os.environ["PBIRS_USER"],
    password=os.environ["PBIRS_PASSWORD"],
    domain=os.environ.get("PBIRS_DOMAIN", ""),
)

# Ensure folder exists
try:
    folder = client.create_folder("/Sales")
except PBIRSConflict:
    folder = client.get_folder("/Sales")

# Deploy report
report = client.upload_powerbi_report(
    folder_path="/Sales",
    file_path="artifacts/Revenue.pbix",
    name="Revenue",
    overwrite=True,
)

# Point at production database
report.set_datasources([
    DataSource(
        "SalesDB",
        f"Server={os.environ['DB_HOST']};Database=Sales;",
        credential_retrieval="Store",
        username=os.environ["DB_USER"],
        password=os.environ["DB_PASSWORD"],
        windows_credentials=False,
    )
])

# Schedule nightly refresh at 02:00
for plan in report.get_cache_refresh_plans():
    plan.delete()

report.create_cache_refresh_plan(
    description="Nightly",
    schedule=Schedule.daily(hour=2),
)

# Grant read access
report.add_user("CORP\\Sales Team", ["Browser"])

Testing

pip install pytest
pytest tests/ -v

All tests use unittest.mock, no live server required.

License

MIT License