Polimorfizm Źródeł Danych Raportów (struktura dataSources)

Opis mechanizmu

Kluczową przewagą sPrint API jest możliwość dynamicznego podmieniania definicji połączeń bazodanowych oraz zapytań wewnątrz spakowanego szablonu .sp bezpośrednio podczas wywołania operacji. Umożliwia to projektowanie szablonu na bazie środowiska testowego, a drukowanie na rzeczywistych danych produkcyjnych konkretnego klienta ERP lub dynamiczną edycję zapytania z użyciem dodatkowych kryteriów wdrożeniowych.

W tablicy obiektów dataSources przekazywane są struktury polimorficzne. O zestawie wymaganych pól oraz regułach walidacji technicznej decyduje wartość nadrzędna zadeklarowana w polu type. Komponent ten pozwala na całkowitą zmianę dostawcy danych w locie – od relacyjnych baz SQL po strukturalne pliki obiektowe.

Zasada nadpisywania danych (Scope Replacement)

Globalny Zasięg: Jeśli tablica reportIds jest pusta ([]), sPrint podmieni konfigurację połączenia bazodanowego we wszystkich raportach i subreportach (podraportach) zagnieżdżonych w pakiecie, natomiast samo zapytanie (query) zostanie nadpisane wyłącznie w raporcie głównym.
Precyzyjny Zasięg: Jeśli dodasz konkretne identyfikatory (GUID) do tablicy reportIds, zarówno nowe parametry połączenia, jak i treść zapytania (query) zostaną zaaplikowane tylko i wyłącznie w tych szablonach lub subreportach, które pasują do wskazanych identyfikatorów. Identyfikatory raportów można pobrać za pomocą dedykowanego endpointu opisanego w artykule POST /api/v0/Info.

Specyfikacja typów źródeł danych (Warianty polimorficzne)

Każdy element kolekcji dataSources bazuje na wspólnym kontrakcie. W zależności od wybranego dostawcy danych, struktura JSON przyjmuje jedną z poniższych form:

1. Wariant: Db (Relacyjne bazy danych)

Najczęściej stosowany model integracji. Obsługuje bezpośrednie, natywne sterowniki dla systemów bazodanowych: Microsoft SQL Server (w tym uwierzytelnianie Windows), PostgreSQL oraz Oracle.

{
  "type": "Db",
  "reportIds": [],
  "server": "sql-prod-server",
  "port": 1433,
  "connectionType": "MsSql",
  "databaseName": "SYSTEM_ERP_PROD",
  "query": "SELECT * FROM cdn.Faktury WHERE FakID = @id",
  "credentials": {
    "login": "db_reader",
    "password": "Password123!"
  }
}

type (string): Wartość stała "Db" wymuszająca walidację połączenia relacyjnego.
server (string): Nazwa instancji lub adres IP serwera bazy danych.
connectionType (string): Silnik bazy danych. Dopuszczalne wartości: "MsSql", "MsSqlWindows", "PostgresSql", "Oracle"
databaseName (string): Nazwa docelowej bazy danych.
query (string): Nowa definicja zapytania wyciągającego dane (obsługuje parametry szablonów, np. @id).
credentials (object): Kontener przechowujący jawne dane uwierzytelniające (właściwości login, passwordW przypadkutrybu MsSqlWindows sekcja ta może przyjmować wartość null

2. Wariant: Json (Strukturalny plik)

Wybierany w architekturach, gdzie system nadrzędny nie udostępnia bezpośredniego wglądu do bazy SQL, lecz przekazuje gotowy zestaw danych sformatowany do struktur JSON (np. stanowiska sprzedaży rozproszonej Comarch POS).

{
  "type": "Json",
  "reportIds": [],
  "jsonSource": {
    "dataFormat": "Bytes",
    "source": "W3siSWQiOjEsIk5hbWUiOiJQcm9kdWt0In1d..."
  }
}

type (string): Wartość stała "Json" wymuszająca walidację źródła obiektowego.
jsonSource (object): Polimorficzny kontener dostarczenia danych bazujący na modelu FormattedSourceBaseViewModel. Może dostarczyć strukturę JSON jako ścieżkę pliku (Path), ciąg Base64 (Bytes) lub zasób chmurowy (S3). Szczegółowy opis tego mechanizmu znajdziesz w artykule poświęconym obiektom report i output w sekcji struktura obiektu „report”

3. Wariant: Odbc

Stosowany przy specyficznych integracjach z systemami zewnętrznymi. Konfiguracja opiera się na uniwersalnym ciągu połączenia (Connection String) lub systemowej nazwie źródła danych (DSN).

{
  "type": "Odbc",
  "reportIds": [],
  "connectionString": "Driver={MySQL ODBC 8.0 ANSI Driver};Server=db_legacy;Database=archive_2026;Uid=user;Pwd=pass;",
  "query": "SELECT * FROM old_invoices WHERE id = @id"
}

type (string): Wartość stała "Odbc"
connectionString (string): Pełny, sformatowany ciąg połączenia ODBC zawierający wskazanie sterownika, adresu i poświadczeń.
query (string): Nowa treść zapytania dopasowana do dialektu bazy docelowej, z którą łączymy się przez ODBC.

Realne Kompleksowe Przykłady (JSON Payload dla /api/v0/Print)

Poniższe przykłady obrazują, jak poprawnie osadzić i skonfigurować kolekcję dataSources w pełnych strukturach żądań biznesowych.

Przykład 1: Nadpisanie bazy SQL globalnie z użyciem parametru wejściowego

W tym scenariuszu podmieniamy połączenie bazodanowe globalnie (pusta tablica reportIds). Silnik zaktualizuje źródło i wywoła zdefiniowane zapytanie, podstawiając pod parametr @Category_name wartość wstrzykniętą w sekcji parameters.

{
  "printFormat": "Pdf",
  "report": {
    "dataFormat": "Path",
    "path": "C:\\sPrint\\Templates\\CounterSprintDbMain.sp"
  },
  "output": {
    "dataFormat": "Bytes"
  },
  "dataSources": [
    {
      "type": "Db",
      "reportIds": [],
      "server": "sql-prod-server",
      "port": 1433,
      "connectionTimeout": 500,
      "commandTimeout": 50,
      "connectionType": "MsSql",
      "databaseName": "NORTHWND",
      "query": "SELECT * FROM Categories WHERE CategoryName = @Category_name",
      "credentials": {
        "login": "erp_reader",
        "password": "SecurePassword123!"
      }
    }
  ],
  "parameters": [
    {
      "name": "Category_name",
      "value": "Confections"
    }
  ]
}

Przykład 2: Różne zapytania i źródła dla Raportu Głównego oraz Subraportu (Zaawansowany)

Scenariusz hybrydowy. Szablon pobiera nagłówek dokumentu ze struktury Microsoft SQL Server (zaaplikowane dla konkretnego GUID raportu głównego), natomiast powiązane pozycje szczegółowe w subreportacie są dynamicznie zasilane z rozproszonej bazy danych PostgreSQL.

{
  "printFormat": "Pdf",
  "report": {
    "dataFormat": "Path",
    "path": "C:\\sPrint\\Templates\\MainWithSubreport.sp"
  },
  "output": {
    "dataFormat": "Bytes"
  },
  "dataSources": [
    {
      "type": "Db",
      "reportIds": ["fb7bba1c-e799-4ee5-a6f4-992ca1c473ce"],
      "server": "mssql-cluster",
      "connectionType": "MsSql",
      "databaseName": "NORTHWND",
      "query": "SELECT * FROM Invoices WHERE InvoiceID = @inv_id",
      "credentials": {
        "login": "sa_reader",
        "password": "Password1!"
      }
    },
    {
      "type": "Db",
      "reportIds": ["72ce2314-76e1-4948-b186-99698ec5d206"],
      "server": "postgres-node",
      "port": 5432,
      "connectionType": "PostgresSql",
      "databaseName": "Sprint",
      "query": "SELECT * FROM Reports WHERE MainInvoiceGUID = @inv_guid",
      "credentials": {
        "login": "postgres",
        "password": "postgres"
      }
    }
  ],
  "parameters": [
    {
      "name": "inv_id",
      "value": "10244"
    }
  ]
}

Przykład 4: Podmiana źródła danych na generyczne połączenie ODBC

Scenariusz, w którym silnik sPrint API zostaje zmuszony do porzucenia domyślnego połączenia MS SQL i pobrania danych z zewnętrznej, starszej bazy danych (np. systemu zewnętrznego archiwum) za pośrednictwem zainstalowanego na serwerze sterownika ODBC.

{
  "printFormat": "Pdf",
  "report": {
    "dataFormat": "Path",
    "path": "C:\\sPrint\\Templates\\LegacyArchiveReport.sp"
  },
  "output": {
    "dataFormat": "Bytes"
  },
  "dataSources": [
    {
      "type": "Odbc",
      "reportIds": [],
      "connectionString": "Driver={MySQL ODBC 8.0 ANSI Driver};Server=db_legacy_node;Database=archive_2026;Uid=erp_archive_user;Pwd=HardToGuessPassword2026!;",
      "query": "SELECT * FROM historical_orders WHERE customer_id = @cust_id"
    }
  ],
  "parameters": [
    {
      "name": "cust_id",
      "value": "CUST-99281"
    }
  ]
}

Jak możemy ci pomóc?