After document generation (Commands)

---

Commands can be called after the actual document generation. Certain Commands can only be used in the event of success (OnSuccess).

Breaking Change

Version 4.0.30043.0 introduced various changes — among others, attribute names were renamed or configurations were extended/altered. In the event of an error, check whether the configuration matches the current version.

Access to the result

There are two types of document generation results::

• <Document />: This Document-element is the actual result after document generation, which contains the Word, PowerPoint, Excel or external file.
  This element is only available in the event of success, i.e. in OnSuccess!
• <Report />: The Report is an “image” of the status of the document generation or the status of the processing of the commands.
  If generation is aborted or in the event of an error, the report can be used to pass on the error information to the calling system.

Commands must explicitly specify the result, i.e. either Document or Report must be configured.

Document

The Document contains the actual result of the document generation and can only be used in the OnSuccess case.

Conversion to PDF

In order to convert the document into a PDF, there is an extra attribute::

<Document Conversion="..." />

warning

Conversion is currently only supported for Word templates!

A document can be converted with Microsoft Office:

<Document Conversion="PdfViaOffice" />

… or via the PDF converter integrated in primedocs:

<Document Conversion="Pdf" />

Report

The Report is particularly suitable for errors or manual termination of generation.

However, the Report is available in all cases (OnSuccess, OnError, OnCancel, OnExit).

Important: Initially, the report is given the status of document generation. Each defined Command is then processed in sequence and each command then influences the report.

The Report itself is an XML file with the following structure:

<primedocsConnectReport>
  <Status>Error</Status>
  <Input>
    <File>C:\Temp\ConnectFile.pdck</File>
  </Input>
  <CreatedOnUtc>...</CreatedOnUtc>
  <Message><![CDATA[Something failed due to ....

Overview
========
  --> [exception #1] System.ExampleException1: An error occurred while ...
    --> [exception #2] System.ExampleException2: Unable to ...]]>
    </Message>
</primedocsConnectReport>

• Status: The Status can contain the following values:
  • OK: No errors, the document generation or all Commands up to this point ran successfully.
  • Cancelled: This status occurs when the user cancels the document generation.
  • Error: Error during document generation or if a previous Command failed.
• Input & File: If primedocs is called via a primedocs Connect file, this element contains the file path of this file.
• CreatedOnUtc: Time when the report was created.
• Message: Contains messages from the report.

Dynamic Parameter

Connect commands can be assigned values via their respective attributes or elements, e.g. you can specify the save path for SaveFile:

<SaveFile FileName="\\MyServer\share\organisation\...\Letter.docx" ...

However, if you want to assemble the path or file name dynamically, you can access the document generation fields (“User”, “Forms”, ‘Field’, “Data” etc.) via the field-attribute.

<SaveFile field-FileName="SavePath" ...

The use here is only exemplary. Not every attribute or element supports access to fields.

Basically:

• Attributes that support access to fields are named in the style:
  • Attribute="static value" or field-Attribute="FieldName"
• Elements that support access to fields are named in this style:
  • <element>static value</element> or <element field-Content="FieldName" />

warning

Access to the fields only works in the OnSuccess case.

Commands

The following table lists all available commands and indicates whether they are only available on the client or server side and whether they can only be used if successful.

Overview

Command	Description	Client
OpenFile	Opens Office files with the standard process that is registered in Windows for the file type.	✓
SaveFile	Saves the document at the specified destination in the specified format.	✓
InvokeProcess	Calls an external application. For security reasons, the process must be configured beforehand.	✓
InvokeUrl	Sends the file or report to an HTTP/HTTPS endpoint. For security reasons, the target URL must be configured beforehand.	✓

Description

SaveFile (client-only)

The SaveFile-Command saves the document at the specified destination.

Attributes:

• FileName: Absolute path with file extension
• field-FileName: Alternative to FileName to enable dynamic paths via the fields.
• Overwrite: True/False; specifies whether an existing file should be overwritten.
• CreateFolder: True/False; specifies whether folders specified in the filename should be created.

Elements:

• Document or Report: See section “Accessing the result”

<primedocsConnect>
  ...
  <Commands>
    <OnSuccess>
      <SaveFile FileName="\\MyServer\share\organisation\...\Letter.docx"
                Overwrite="true"
                CreateFolder="true">
        <Document />          
      </SaveFile>
    </OnSuccess>
  </Commands>
</primedocsConnect>

OpenFile (client-only)

The OpenFile-Ccommand opens Office files with the standard process that is registered in Windows for the file type. For example, the generated file is saved in a specific file location and is to be edited in Word afterwards.

Attributes:

• FileName: Absolute path with target file extension
• field-FileName: Alternative to FileName to enable dynamic paths via the fields.

<primedocsConnect>
  ...
  <Commands>
    <OnSuccess>
      <SaveFile FileName="\\MyServer\share\organization\...\Letter.docx"
                Overwrite="true"
                CreateFolder="true">
          <Document />
      </SaveFile>
      <OpenFile FileName="\\MyServer\share\organization\...\ShortLetter.docx"/>      
    </OnSuccess>
  </Commands>
</primedocsConnect>

InvokeProcess (client-only)

The InvokeProcess-Command calls an external application. For security reasons, the permitted applications must first be whitelisted in the dashboard. The configuration for this can be found under Settings → Connect Settings → InvokeProcess - Configuration and looks something like this:

<CommandConfig>
    <Process name="OurSystemNotepad" executablePath="%systemroot%/notepad.exe" />
    <Process name="..." executablePath="..." />
</CommandConfig>

The call in the connect file must match the name of an application previously released in the dashboard.

Attributes:

• Name: Configured process name

Elements:

• Arguments: Arguments for the process call
• Arguments with field-Content: Alternative to Arguments. Allows access to field values.

The call can optionally contain arguments and looks like this:

<primedocsConnect>
  ...
  <Commands>
    <OnSuccess>
      <InvokeProcess Name="OurSystemNotepad">
          <Arguments>...</Arguments>
          <!-- or -->
          <Arguments field-Content="FieldName" />
      </InvokeProcess>    
    </OnSuccess>
  </Commands>
</primedocsConnect>

OpenDocumentInOffice (client-only)

The OpenDocumentInOffice command opens the generated document directly in the Office application without having to save it first.

<primedocsConnect>
  ...
  <Commands>
    <OnSuccess>
      <OpenDocumentInOffice />      
    </OnSuccess>
  </Commands>
</primedocsConnect>

InvokeUrl (client-only)

The InvokeUrl-Command sends the file or report to an HTTP/HTTPS endpoint. For security reasons, the permitted applications must first be whitelisted in the dashboard. The configuration for this can be found under Settings → Connect Settings → InvokeUrl - Configuration and looks something like this:

<CommandConfig>
    <Url startsWith="https://example1.com" />
    <Url startsWith="https://example2.com/subfolder" />
</CommandConfig> 

Basic structure:

HTTP requests can be defined as steps (Step) in InvokeUrl.
A Step consists of a Request or MultipartFormDataRequest and optionally a Response.

The structure is similar to HttpDataProvider but the Document or Report can be sent to an endpoint via the MultipartFormDataRequest.

The Command processes all Step-elements in the defined sequence. A Step has no further attributes.

Request-Element:

• Attributes:
  • Method: Specification of the HTTP method (POST, GET, etc.)
• Elements:
  • Url: Specification of the target URL, which must be configured in the dashboard for security reasons.
  • Url with field-Content: Alternative to Url. Allows you to access field values.
  • Body: Specification of the HTTP body.
  • Body with field-Content: Alternative to Body. Allows you to access field values.
  • Header: List of HTTP headers from Key and Value or field-Value.

MultipartFormDataRequest-Element:

• Elements:
  • Url: Specification of the target URL, which must be configured in the dashboard for security reasons.
  • Url with field-Content: Alternative to Url. Allows you to access field values.
  • Header: List of HTTP headers from Key and Value or field-Value.
  • FormData: List of FormData elements from Key and Value or field-Value.
  • File: Transfer of the actual file as a multipart/form-data request.
    • Attributes:
      • Name: Optionale name - depending on the server endpoint. The binary data is serialized as multipart/form-data under this name in the request.
      • FileName: Optionale file name.
      • field-FileName: Alternative to FileName to enable dynamic names for the fields.
    • Elements:
      • Document or Report: See section “Accessing the result”

Response-Element:

• Elements:
  • Property: Retrieve specific data from the result of the HTTP request.
    • Attributes:
      • Name: Name of the property. This value can be accessed in a subsequent request via the {PropertyName} syntax.
      • JsonPath: The value of the property is determined via the JsonPath. The HTTP response must be a valid JSON.
      • XPath: The value of the property is determined via the XPath. The HTTP response must be a valid XML.

Example:

<primedocsConnect>
  ...
  <Commands>
    <OnSuccess>
        <InvokeUrl>
          <Step>
            <Request Method="Post">
              <Header Name="FieldHeader" field-Value="Forms.TestFoobar" />
              <Url field-Content="Forms.Url" />
              <Body field-Content="Forms.Body" />
            </Request>
            <Response>
              <Property Name="AccessToken" JsonPath="$.AccessToken" />
            </Response>
          </Step>
          <Step>
            <MultipartFormDataRequest>
              <File Name="Foobar" field-FileName="Forms.FileName">
                <Document Conversion="PDF" />
              </File>
              <Url field-Content="Forms.DataUrl" />
              <Header Name="AccessToken" Value="{AccessToken}" />
              <Header Name="AnotherHeader" field-Value="Forms.Header" />
              <FormData Name="SomethingOne" field-Value="Forms.FormData" />
              <FormData Name="SomethingTwo" Value="SomeValue2" />
            </MultipartFormDataRequest>
          </Step>
        </InvokeUrl>  
    </OnSuccess>
  </Commands>
</primedocsConnect>