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).

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.

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—all 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 — Text and GlobalFields (analogous to Fields in outputs, but limited to these two types).
• Commands: The actions to run — only InvokeUrl, ShowDialog, and DownloadFile.

---

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 — with 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.