---
title: DocumentBannerInstructions
summary: Selects a document's envelope destination and assembles the fixed-order banner-page text.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-09-24
library: SAIF.SAIFCode.Core
reference_type: package
operation_id: OP-CORE-01
trigger: Banner creation or parse for a document
---

# DocumentBannerInstructions

`DocumentBannerInstructions` decides which physical envelope a document is routed to and assembles (or later parses back apart) the printed banner-page text that accompanies the document batch.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-CORE-01 |
| **Trigger** | Document banner creation or banner-string parse |
| **Inputs** | Document metadata, the six ordered inserts, and a language marker |
| **Outputs** | Selected envelope type; assembled or re-extracted banner string |
| **Primary components** | `DocumentBannerInstructions.WhichEnvelope`, `DocumentBannerInstructions.CreateBannerPageText`, `DocumentBannerInstructions.GetFreeformText` |
| **Entry point** | `Core/SAIF.Core/Contracts/Documents/DocumentBannerInstructions.cs` |

## Steps

1. `WhichEnvelope` inspects the document's routing attributes and selects one of three envelope destinations: Left window, Right window, or DCBS batch ([CORE-BR-001](../business-rules.md#core-br-001-documents-are-routed-to-a-left-window-right-window-or-dcbs-batch-envelope)).
2. `CreateBannerPageText` assembles the banner-page text from six ordered inserts (selected via the nested `IncludeInserts` flags container), followed by a language marker and the `"; "` delimiter ([CORE-BR-002](../business-rules.md#core-br-002-banner-text-order-of-six-inserts-plus-language-marker-and-delimiter-matters-for-parsing)).
   - The insert order is fixed; downstream OCR/print processes rely on this exact ordering to parse the banner back apart*.
3. `GetFreeformText` and related helper methods extract free-form segments back out of an already-assembled banner string, relying on the same six-insert order established in step 2 ([CORE-BR-002](../business-rules.md#core-br-002-banner-text-order-of-six-inserts-plus-language-marker-and-delimiter-matters-for-parsing)).
   - If the insert order was not preserved when the banner was created, extraction can silently misalign*.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Document ready for banner processing]) --> Which["WhichEnvelope selects<br>Left-window Right-window or DCBS-batch"]
	Which --> Create["CreateBannerPageText assembles<br>six ordered inserts plus language marker"]
	Create --> Parse{"Banner string later<br>needs re-parsing?"}
	Parse -->|Yes| Extract["GetFreeformText extracts<br>free-form segments"]
	Parse -->|No| EndOk([Banner ready for print])
	Extract --> EndOk2([Segments returned to caller])
```

## Failure and edge-case behavior
- If the six-insert order is violated when the banner is created, `GetFreeformText` extraction can misalign and silently return the wrong segment*.

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

## Sources
- Core/SAIF.Core/Contracts/Documents/DocumentBannerInstructions.cs