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

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 shows in which environments they are available: the Desktop client, primedocs Web (including the Office Web Add-ins, Connect Sessions, and WebOutput), and the API — pure server-side generation via the Connect/Document API.

Overview

Command	Description	Desktop	Web	API
SaveFile	Saves the document at the specified destination in the specified format.	✓	–	–
OpenFile	Opens Office files with the standard process that is registered in Windows for the file type.	✓	–	–
OpenDocumentInOffice	Opens the generated document directly in the Office application.	✓	–	–
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.	✓	✓	✓
ShowDialog	Shows the user a dialog with a title, message, and optional button/link.	✓	✓	–
DownloadFile	Provides the document or report as a file download.	–	✓	–

Availability

• Desktop only: SaveFile, OpenFile, OpenDocumentInOffice, and InvokeProcess access the local system and are only available in the desktop client.
• Desktop & Web: ShowDialog shows the user a dialog — in the desktop client and in primedocs Web. DownloadFile is limited to primedocs Web.
• API (server-side generation): the Connect/Document API returns the document directly to the caller. Of the commands, only InvokeUrl (a server-side HTTP call) is available there; interactive or client-/web-specific commands such as ShowDialog, DownloadFile, or SaveFile have no effect in server-side generation.
• Web also covers the execution of Connect Sessions (/{sessionId}/Execute of the Connect Session API) and the WebOutput / WebSeriesOutput output.
• Commands can be used in all handler groups (OnSuccess, OnExit, OnError, OnCancel) — but commands with <Document /> only in OnSuccess.

Description

SaveFile

Desktop

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

Desktop

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

Desktop

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

Desktop

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

Desktop Web API

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.

Authentication via a Connected Service:

The optional ConnectedServiceKey attribute on the InvokeUrl element authenticates the HTTP call via a Connected Service (OAuth 2.0 access token). If the key is set and the user is not yet signed in to the service in primedocs Web, the web app shows a sign-in prompt before execution.

note

ConnectedServiceKey is not available via the Connect/Document API (pure server-side generation), because that runs without a signed-in user context (client credentials). For scenarios requiring connected-service authentication, use the Connect Session (/Execute), which runs in the context of the signed-in user.

<InvokeUrl ConnectedServiceKey="MSGraph">
  <Step>
    ...
  </Step>
</InvokeUrl>

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>

ShowDialog

Desktop Web

The ShowDialog command shows the user a dialog — for example a success or error message with an optional button that points to a URL. It is available in the desktop client, in primedocs Web, and via the Connect Session API.

Attributes (each also available as a field- variant to use field values):

• Title / field-Title: Dialog title.
• Message / field-Message: Message text.
• ButtonLabel / field-ButtonLabel: Label of the optional button.
• ButtonUri / field-ButtonUri: Target URL of the button.

<primedocsConnect>
  ...
  <Commands>
    <OnSuccess>
      <ShowDialog Title="Done"
                  Message="The document was created."
                  ButtonLabel="Open in CRM"
                  ButtonUri="https://crm.example.com/doc/42" />
    </OnSuccess>
  </Commands>
</primedocsConnect>

DownloadFile

Web

The DownloadFile command provides the generated document or report as a file download in the web app (Connect Session, WebOutput, WebSeriesOutput). If multiple DownloadFile commands are defined, the files are packaged into a ZIP archive.

Attributes:

• FileName / field-FileName / replacer-FileName: File name of the download.

Elements:

• Document or Report: See the "Accessing the result" section. Document is only valid in OnSuccess.

<primedocsConnect>
  ...
  <Commands>
    <OnSuccess>
      <DownloadFile FileName="Offer">
        <Document />
      </DownloadFile>
    </OnSuccess>
  </Commands>
</primedocsConnect>