---
title: Distribute report
summary: Ensures report XML exists, then submits the report for distribution through clsPrint's synchronous or asynchronous transport.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-30
library: SAIF.Services.Printing
reference_type: package
operation_id: OP-PRT-06
trigger: Caller invokes ReportBase.Distribute(overwrite)
---

# Distribute report

`ReportBase.Distribute` is the consumer-facing distribution entry point on the `IReport` workflow. Unlike `Print`, it does not call `Render` — it calls `Create` directly to (re)generate report XML, then hands the XML and package name to `clsPrint.distributeDocument`, which independently decides between the synchronous and asynchronous transport paths.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-PRT-06 |
| **Trigger** | Caller invokes `ReportBase.Distribute(overwrite)` |
| **Inputs** | Optional `overwrite` flag; the report's `ReportPackage` and report XML |
| **Outputs** | Boolean success; an `ErrorDetail` entry in `Errors` on failure |
| **Primary components** | `Reporting.ReportBase.Distribute`, `Reporting.ReportBase.Create`, `clsPrint.distributeDocument` |
| **Entry point** | `Services\SAIF.Services.Printing\Reporting\ReportBase.vb` |

## Steps

1. `Distribute` checks whether rendered bytes are missing or `overwrite` is `True`.
   - If so: it calls `Create(overwrite)` to (re)generate report XML. Note that this step calls `Create` directly rather than `Render`, so it does not resolve a default printer or call the preview service the way [Render report](render-report.md) does.*
2. `Distribute` checks that `m_reportXml` is not `Nothing` and `m_ReportPackage` has a non-zero length.
   - If either condition fails: distribution is skipped and `Distribute` returns `False` (via the unset `result` variable).
3. When ready, `Distribute` calls `xPrint.distributeDocument(ReportPackage, ReportXml.ToString)` — the [Distribute document (synchronous or asynchronous)](distribute-document.md) operation, which internally branches on `Asynchronous` ([BR-001](../business-rules.md#br-001-distribution-mode-follows-the-asynchronous-flag)).
   - Note: this call serializes the report XML using `ReportXml.ToString` rather than the `ToXpression()` xPression-specific serialization used by `Render` in step 6 of [Render report](render-report.md); the two workflows format the XML payload differently.*
4. On success, `result` is set to `True`.
5. **On exception:** any exception raised during steps 1–3 is caught, wrapped in an `ErrorDetail("An error occurred distributing the report.", ex)`, and appended to `Errors`; `Distribute` returns `False`.

## Process flow

The following diagram visualizes the create-then-distribute sequence.

```mermaid
flowchart TD
	Start([Distribute called with overwrite]) --> NeedCreate{Bytes missing<br>or overwrite = True?}
	NeedCreate -->|Yes| Create[Call Create overwrite]
	NeedCreate -->|No| Valid
	Create --> Valid{XML present and<br>ReportPackage set?}
	Valid -->|No| Fail([Return False])
	Valid -->|Yes| Call[Call xPrint.distributeDocument<br>ReportXml.ToString]
	Call --> End([Return True])
	Create -.->|Exception| Err[Add ErrorDetail, return False]
	Call -.->|Exception| Err
```

## Failure and edge-case behavior

- `Distribute` skips validation of whether the XML was successfully created before proceeding, relying only on the null/length check in step 2; a `Create` override that silently fails without throwing produces the same `False` result path as a missing package.*
- Distribution uses `ReportXml.ToString()` rather than `ReportXml.ToXpression()`, so the payload format sent to `clsPrint.distributeDocument` differs from the payload format `Render` sends to the preview service; whether this discrepancy is intentional could not be confirmed from source.**
- Exceptions from either XML creation or the underlying distribute call are caught and converted into a single generic `ErrorDetail` message that does not distinguish the two failure sources.

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

## Sources
- `Services\SAIF.Services.Printing\Reporting\ReportBase.vb`
- `Services\SAIF.Services.Printing\clsPrint.vb`