Output Management

---

Purpose and use

This document function can be used to transfer the generated file to one or more configurable endpoints.
This function can also be used to configure form letters or the serial creation of multiple documents based on a list of recipients, for example.

The individual actions are defined using primedocs Connect Commands.

Basic structure

<OutputConfiguration>
  <DesktopOutput Name="Test Output 1">
    <Fields>
      <Text Name="Guid">
        <Code>
          function main() { return $.util.generateGuid(); }
        </Code>
      </Text>
      <Text Name="GeneratedFileName">
        <Code>
          function main() { 
             var RecipientName = $("RecipientName");
             return "X:\\documents\\Document_" + $("Guid") + "_" + RecipientName + ".docx"; }
        </Code>
      </Text>
    </Fields>
    <Commands>
      <SaveFile field-FileName="GeneratedFileName" Overwrite="false" CreateFolder="false">
        <Document />
      </SaveFile>
    </Commands>
  </DesktopOutput>
  <DesktopOutput Name="Test Output 2">
    <Commands>
      <SaveFile field-FileName="Forms.FullPath" Overwrite="false" CreateFolder="false">
        <Document />
      </SaveFile>
    </Commands>
  </DesktopOutput>  
  <DesktopSeriesOutput Name="Series Output">
    <ForEach>
      <SeriesTextReplacer Name="Default">
        <Current Text="$current" />
        <Total Text="$total" />
      </SeriesTextReplacer>
      <Commands>
        <SaveFile FileName="C:\temp\sample_$current_of_$total.docx" Overwrite="true" replacer-FileName="Default">
          <Document />
        </SaveFile>
      </Commands>
    </ForEach>
    <ForSeries>
      <MergeAsPdf>
        <Commands>
          <SaveFile FileName="C:\temp\sample.pdf" Overwrite="true">
            <Document />
          </SaveFile>
          <OpenFile FileName="C:\temp\sample.pdf" />
        </Commands>
      </MergeAsPdf>
    </ForSeries>
  </DesktopSeriesOutput>
</OutputConfiguration>

If the SelectecObjectId attribute is configured in an ObjectCollection within the Forms configuration, a DesktopSeriesOutput configuration is implicitly generated and a corresponding button is displayed in the Forms dialogue.

The optional DisableDefaultSeriesOutput attribute can be used to suppress this behaviour.

---

DesktopOutput

The resulting document can be sent to a specific endpoint using the DesktopOutput-elements.

A DesktopOutput can be run either directly during creation via the Forms dialog or manually afterwards via the primedocs ribbon (COM add-in).

Attributes:

Attribute	Required	Description
Name	yes	Label of the additional button in the Forms dialog and the add-in ribbon.
Tooltip	optional	Tooltip of the button.
Icon	optional	Base64-encoded icon (e.g. PNG) for the button.
HideInForms	optional	When true, the output is not shown in the Forms dialog.
HideInAddIn	optional	When true, the output is not shown in the add-in ribbon.
HideSuccessMessageInForms	optional	When true, the success message after execution is suppressed in the Forms dialog.
HideSuccessMessageInAddIn	optional	When true, the success message after execution is suppressed in the add-in.

Elements:

• Fields: To define dynamic data for an "output," fields can be defined in a similar way to the normal Fields function.
• Commands: The commands determine which actions are performed. All commands from primedocs Connect are available.

Fields in Outputs

Fields in the output are calculated as soon as the corresponding output is activated.

The Output Fields allow a subset of the normal field function in combination with certain API calls.

<Fields>
    <Text Name="Guid">
        <Code>
          function main() { return $.util.generateGuid(); }
        </Code>
    </Text>
    <Text Name="StaticValue" Value="Test" />
    <Text Name="StaticTranslatedValue" translate-Value="Fields.Key.StaticValue" />
    <Text Name="GeneratedFileName">
        <Code>
          function main() { 
             var RecipientName = $("RecipientName");
             return "X:\\documents\\Document_" + $("Guid") + "_" + RecipientName + ".docx"; 
          }
        </Code>
    </Text>
</Fields>

Elements:

Text: Allows you to create a Text element. A Name must be set as the identifier.
The value can be set in the following ways:

• Static via Value
• Static, but with translation via translate-Value
• Dynamic via Code

The Code element uses the same logic as the Fields, but with a simplified JavaScript API:

note

Only Text types can be retrieved and returned in this API. Access to fields with other types is not permitted.

Function	Return type
$("…")	Returns a text field.
$.get("…")	Returns a text field.
$.getText("…")	Returns a text field.
$.util.generateGuid()	Generates a unique GUID.

The generated fields can then be used for the Commands via the field-FileName (etc.) syntax.

---

DesktopSeriesOutput

Serial generation can be started using the DesktopSeriesOutput-elements.

info

This option can only be executed in combination with a configured ObjectCollection including SelectedObjectId, as a defined list must be iterated.

Like a DesktopOutput, a DesktopSeriesOutput can be run directly during creation via the Forms dialog or manually afterwards via the primedocs ribbon (COM add-in).

DesktopSeriesOutput is not supported for Excel templates. PowerPoint supports series output without PDF merging. ForSeries with MergeAsPdf is available for Word only.

Attributes: the same attributes as for DesktopOutput apply (Name, Tooltip, Icon, HideInForms, HideInAddIn, HideSuccessMessageInForms, HideSuccessMessageInAddIn).

Elements:

• ForEach: This element can be used to define actions for each serial document.
  • Example: A document should be saved for each recipient.
• ForSeries: This element can be used to create a merged PDF for the entire series.
  • Example: A merged PDF is required for all recipients.

Series output from an open Word document

When started from the Word COM add-in, the open document is the basis for each document in the series. Manual changes are preserved. Only parts bound to fields are updated. The field values stored in the document provide the initial values. Values from the current series object override them by name. Object collections with the same name are replaced as a whole, while nested objects are merged field by field.

If the open document has no stored primedocs field values, output stops with a message. It does not automatically fall back to the template.

Object collection during the series

Each document in the series has access to the complete object collection, not only to the current series object. Fields that iterate over the collection, for example a distribution list using WordTableRows with $.getObjectCollection("Forms.Recipients"), therefore show the same entries in the series document as in the document itself. In each run, the current series object is the only selected one and is available through the SelectedObjectId, for example $("Forms.Recipient.Name"). The selection in the open document is not affected.

note

Office document properties that refer to fields of the series object are not updated through this route. They retain the value from the open document. Applying a MIP sensitivity label is not supported for series output from an open Word document.

PowerPoint series output without PDF merging continues to be generated from the template. Series generation when creating a document and web series output are unaffected by this change to the open Word document.

Configuration checks

The configuration preview opened manually in the template editor reports DesktopSeriesOutput for Excel and ForSeries with MergeAsPdf for template types other than Word as errors. This additional configuration diagnostic runs only in the manually opened preview, not when saving or generating. Independently of that diagnostic, series output itself rejects unsupported combinations with an error message. The COM add-in hides the affected outputs.

ForEach

• This element can be used to define actions for each serial document.

Elements:

• SeriesTextReplacer: This element can be used to map placeholders for the current element and the total number of documents to be generated. This makes it possible to create Document_26_of_87.docx. Only this element has access to the current "iterator" and the "total number".
  • <Current Text="$current" /> means that the current number is expressed by the placeholder $current.
  • <Total Text="$total" /> means that the total number is expressed by the placeholder $total.
  • Multiple SeriesTextReplacer-s can be defined. Each must have a unique Name attribute.
• Commands: Similar to DesktopOutput, the commands are defined here (see: primedocs Connect)
  • In addition, you can access the replacer-FileName="Default" here.

info

Similar to dynamic access via field-FileName, these attributes can be iterated through again in the ForEach element using the replacer-[ATTRIBUTE].

"ForSeries"

This element allows you to map all documents as a single PDF using the MergeAsPdf element.

Commands can be defined within MergeAsPdf and the result is processed as a "PDF" document.

---

WebOutput

WebOutput is the counterpart to DesktopOutput for primedocs Web and the Office Web Add-ins. Each WebOutput appears in the web as an additional button during generation. Only the web-supported commands InvokeUrl, ShowDialog, and DownloadFile are available.

<OutputConfiguration>
  <WebOutput Name="Download as PDF" Tooltip="Creates a PDF" HideSuccessMessage="false">
    <Commands>
      <DownloadFile FileName="Letter.pdf">
        <Document Conversion="Pdf" />
      </DownloadFile>
    </Commands>
  </WebOutput>
</OutputConfiguration>

Attributes:

Attribute	Required	Description
Name	yes	Label of the button in the web.
Tooltip	optional	Tooltip of the button.
HideSuccessMessage	optional	When true, the success message after execution is suppressed.

Elements:

• Fields (optional): Fields for this output, namely Text and GlobalFields (analogous to Fields in outputs, but limited to these two types).
• Commands: The actions to run. Only InvokeUrl, ShowDialog, and DownloadFile are allowed.

---

WebSeriesOutput

WebSeriesOutput is the counterpart to DesktopSeriesOutput for series generation in the web. As with DesktopSeriesOutput, an ObjectCollection with SelectedObjectId is required (see DesktopSeriesOutput).

<OutputConfiguration>
  <WebSeriesOutput Name="Series as PDF" Tooltip="Merge all recipients">
    <ForEach>
      <SeriesTextReplacer Name="Default">
        <Current Text="$current" />
        <Total Text="$total" />
      </SeriesTextReplacer>
      <Commands>
        <DownloadFile FileName="Document_$current_of_$total.docx">
          <Document />
        </DownloadFile>
      </Commands>
    </ForEach>
    <ForSeries>
      <MergeAsPdf>
        <Commands>
          <DownloadFile FileName="Series.pdf">
            <Document />
          </DownloadFile>
        </Commands>
      </MergeAsPdf>
    </ForSeries>
  </WebSeriesOutput>
</OutputConfiguration>

Attributes: Name (required), Tooltip (optional), and HideSuccessMessage (optional), analogous to WebOutput.

Elements:

• Fields (optional): Text and GlobalFields.
• ForEach: Actions per series document, consisting of SeriesTextReplacer (placeholders $current/$total, optionally with Format) and Commands.
• ForSeries: Merge all documents into a single PDF via MergeAsPdf › Commands.

Here too, only the web-supported commands (InvokeUrl, ShowDialog, DownloadFile) are available in all Commands.

Background processing & transient storage

Unlike the other outputs, series generation via WebSeriesOutput runs in a server-side background service, because it iterates over an entire list and processing can take longer. Progress is shown in the web app, and the result is then available for download.

This is the only place where primedocs temporarily persists generated document data on the server, deliberately transient and encrypted only:

• The result file (e.g. the series ZIP) is stored on disk AES-256 encrypted only.
• The key is derived per file from the user session (bearer token), so the download is bound to the signed-in user.
• Results are automatically deleted after at most one hour (periodic cleanup), so no un-downloaded files remain on the server.

---

GlobalOutputs

GlobalOutputs references a centrally stored set of output definitions instead of repeating the DesktopOutput / DesktopSeriesOutput elements in every template. The referenced outputs are added to the locally defined ones (they do not replace them).

<OutputConfiguration>
  <GlobalOutputs Key="StandardProjectOutputs" />
  <DesktopOutput Name="Save to project folder">
    <Commands>
      <SaveFile FileName="result.docx" Overwrite="true">
        <Document />
      </SaveFile>
    </Commands>
  </DesktopOutput>
</OutputConfiguration>

The referenced global configuration entry is of type OutputGlobalOutputs and may contain DesktopOutput, DesktopSeriesOutput, WebOutput, and WebSeriesOutput.

Attribute	Required	Description
Key	yes	Key of the referenced global output entry.

The validation of the output configuration first resolves the referenced global outputs and checks them together with the local ones against the same rules. A missing or invalid global entry is reported as well.

warning

PdfViaOffice only in Word templates

<Document Conversion="PdfViaOffice" /> converts through Word and is therefore only allowed in Word templates. In a PowerPoint or Excel template the validation reports an error and names Conversion="Pdf" as the alternative, also when the output comes from a global entry. Document creation fails with the same message in this case.