Chapter 10 - Files, attachments and images

These nine commands work with files: resize pictures, download or inspect file attachments, read, list, save and delete files on the network, and render the form as a PDF or as plain text. Chapter 1 explains the command syntax, dynamic parameter values and where results go; this chapter assumes you know it.

Network file commands. DeleteFile, GetNetworkFile, ListDirectory, SaveToNetwork and SubmitToNetwork work with files and folders that the FormsViewer server can reach (for example \\fileserver\share\folder or D:\Forms\Out). The server does the work, so paths are resolved on the server, not on the user's computer, and the server's account needs access to them. These commands are only available on FormsViewer deployments that have local network file access enabled, typically an on-premises installation. On other deployments they fail with the error message the server returns.

The examples use this main data source:

my:myFields
  my:Photo                  (picture control, base64 image)
  my:Thumbnail              (picture control, base64 image)
  my:Receipt                (file attachment)
  my:Attachments
    my:Attachment           (repeating)
      my:File               (file attachment; attributes my:qRulesFilename, my:qRulesLink)
      my:FileName
  my:Directory
    my:Entry                (repeating; attributes my:FullPath, my:Modified)
  my:PdfCopy                (file attachment)
  my:PdfLink
  my:FileName

10.1 AlterImage

Resizes a base64 image and can change its format and quality. Use it to shrink photos before they are saved or submitted, for example after a user adds a large picture from a phone camera.

Syntax

AlterImage /image=<base64> | /imagexpath=<XPath> [/imageds=<data source>] [/width=<n> | /maxwidth=<n>] [/height=<n> | /maxheight=<n>] [/maintainproportions=true] [/quality=<1-100>] [/format=png|jpg|<type>]

Result: with /image, the altered image as base64. With /imagexpath, the number of images changed.

Examples

AlterImage /imagexpath=/my:myFields/my:Photo /maxwidth=800 /maxheight=800 /maintainproportions=true /format=jpg /quality=80
AlterImage /image-xpath=/my:myFields/my:Photo /width=200 /maintainproportions=true /resultxpath=/my:myFields/my:Thumbnail

The first fits the photo inside 800 x 800 pixels, keeping its shape, and stores it as a jpg. The second leaves the photo as it is and writes a 200-pixel-wide copy into another field.

Notes

• The output is png unless you give /format. Resizing a jpg photo without /format=jpg converts it to png, which is usually much larger.
• With /maxwidth and /maxheight together and /maintainproportions=true, the image is scaled to fit inside both limits. Without /maintainproportions, each side is limited on its own, which can distort the image.
• The value must be a plain base64 image, such as a picture control stores when the picture is included in the form. A value that cannot be loaded as an image fails with Encountered an error while loading the image. It may be an invalid or unsupported value.
• With /imagexpath, an image that fails does not stop the others. Success is false, Result is the number of images that were changed, and Error lists the problems after Encountered errors while processing images:. If the XPath selects nothing, the command fails with Error: No nodes were found using the specified XPath.
• Parameter errors: /image cannot be used at the same time as /imagexpath or /imageds, Either /image or /imagexpath must be specified., Can't use /width with /maxwidth or /height with /maxheight, Can't use /width with /maxheight or /height with /maxwidth if /maintainproportions is true, /quality must be greater than 0 and less than or equal to 100., and Value 'abc' for parameter 'width' is not a valid number. for a non-numeric size or quality.
• Zero or negative sizes fail with /width, /maxwidth, /height, and maxheight, when specified, must be greater than 0.
• The command description in the Command Builder says /maxheight is ignored when the actual width is already smaller; the engine compares the height, as described above.

Related: DownloadAttachment, GetAttachmentAttribute.

10.2 DownloadAttachment

Downloads a file stored in a form field (a file attachment, or a picture stored as base64) to the user's computer, or opens it in a new browser tab. Use it on a button next to an attachment, for example "Open receipt".

Syntax

DownloadAttachment /xpath=<XPath> [/dsname=<data source>] [/filename=<name>] [/open=true]

Result: empty on success.

Examples

DownloadAttachment /xpath=/my:myFields/my:Receipt
DownloadAttachment /xpath=/my:myFields/my:Attachments/my:Attachment[2]/my:File /open=true
DownloadAttachment /xpath=/my:myFields/my:Photo /filename=Site photo.jpg

The first downloads the receipt with its original name; the second opens the second attachment in a new tab; the third downloads the photo under a chosen name.

Notes

• With /open=true, /filename does not change the name of the opened file, but its extension is used to decide how the browser handles the file.
• Errors: Could not locate attachment field., Attachment field is empty., Failed to initiate file download.
• Opening a new tab can be blocked by the browser's pop-up blocker. Run the command from a button so the browser treats it as a user action.

Related: GetAttachmentAttribute, GetNetworkFile.

10.3 GetAttachmentAttribute

Reads one property of a file attachment: its file name, extension, size, or the file content without the attachment header. Use it to show the name of an attached file, to check its type before submitting, or to pass the bare file content to a web service.

Syntax

GetAttachmentAttribute /xpath=<XPath> /attr=name|ext|size|file [/dsname=<data source>]

Result: the requested value.

Examples

GetAttachmentAttribute /xpath=/my:myFields/my:Receipt /attr=name /resultxpath=/my:myFields/my:Attachments/my:Attachment[1]/my:FileName
GetAttachmentAttribute /xpath=/my:myFields/my:Receipt /attr=ext

The first copies the receipt's file name into a field; the second returns, for example, pdf, which a following rule can check before the form is submitted.

Notes

• A file attachment field stores a header (with the file name) in front of the file content. /attr=file returns the content only, which is what most web services and APIs expect.
• Errors: An invalid attribute was specified., Failed to select the attachment node., The attachment node is blank.

Related: DownloadAttachment, SaveToNetwork.

10.4 DeleteFile

Deletes a file on the network. Requires a FormsViewer deployment with local network file access (see the start of this chapter).

Syntax

DeleteFile /path=<file path>

Result: empty on success.

Example

DeleteFile /path-xpath=/my:myFields/my:Directory/my:Entry[1]/@my:FullPath

Deletes the first file listed by ListDirectory, using the full path that ListDirectory stored in the row.

Notes

• The file is deleted at once; it is not moved to a recycle bin. Ask the user to confirm first.
• If the server cannot delete the file, Success is false and Error holds the server's message, or Unspecified error when the server gives none.

Related: ListDirectory, SaveToNetwork.

10.5 GetNetworkFile

Gets a file from the network. It can start a download of the file, return a link to it, or load an XML file into one of the form's data sources. Requires a FormsViewer deployment with local network file access (see the start of this chapter).

Syntax

GetNetworkFile /path=<file path> [/action=download|link|load] [/dsname=<data source>]

Result: with /action=link, the download address; otherwise empty.

Examples

GetNetworkFile /path=\\fileserver\forms\Templates\Instructions.pdf
GetNetworkFile /path-xpath=/my:myFields/my:Directory/my:Entry[1]/@my:FullPath /action=link /resultxpath=/my:myFields/my:PdfLink
GetNetworkFile /path=\\fileserver\forms\Saved\Order-1001.xml /action=load

The first downloads a file; the second stores a download link in a field, which a hyperlink control can show; the third replaces the current form data with a saved XML file.

Notes

• Before any action, the server checks that the path may be accessed. If not, Success is false and Error holds the server's message (or Unexpected error).
• The download address points to this FormsViewer server's file proxy (/LocalProxy/File). It keeps the current page's query parameters, such as the SharePoint host, but not the template, document or form-token parameters, so it can be stored in the form and used later.
• download opens a new window. If the browser blocks it, the command fails with Unable to initiate download. Please ensure that your browser is not blocking popups from this page.
• load keeps the data source's root element and replaces everything inside it with the contents of the file's root element. Attributes on the root are copied only where the root already has them. The file must therefore match the data source's structure; loading a file into the main data source replaces the form's data.
• An unknown action fails with Unknown /action value: value.

Related: ListDirectory, SubmitToNetwork, DownloadAttachment.

10.6 ListDirectory

Lists the files, or the subfolders, of a network folder and writes one row per item into a repeating group. Use it to let users pick a file, or to show what has already been saved. Requires a FormsViewer deployment with local network file access (see the start of this chapter).

Syntax

ListDirectory /path=<folder path> /parent=<XPath> /child=<element name> [/dsname=<data source>] [/mode=file|directory] [/clear=true|false] [/fullpathattributename=<attribute>] [/lastmodifiedlocalattributename=<attribute>]

Result: the number of items listed.

Example

ListDirectory /path=\\fileserver\forms\Saved /parent=/my:myFields/my:Directory /child=my:Entry /fullpathattributename=my:FullPath /lastmodifiedlocalattributename=my:Modified

Fills Directory with one Entry row per file, each with its full path and last-modified time in attributes.

Notes

• /clear=true removes every child of /parent, not only earlier rows. Keep the rows alone in their group.
• The rows are created with the given names; define the row element and the attributes in the data source's schema so the data stays valid.
• A prefix in /child or in an attribute name (such as my:) must be declared on /parent or one of its ancestors, or the command fails with Cannot find namespace for prefix my. A name with more than one colon fails with Invalid child node name: name.
• /parent is only changed after the folder has been read successfully. If the folder cannot be read, Success is false and Error holds the server's message (or Unexpected error).
• Other errors: Unable to find destination node., Invalid mode value: value. Allowed values are 'file' and 'directory'.

Related: GetNetworkFile, DeleteFile.

10.7 SaveToNetwork

Saves the files in one or more file attachment fields to a network folder, one file per field. By default it then clears each field and records the saved file's name and link in attributes of the field, so the form keeps a reference to the file instead of the file itself. Requires a FormsViewer deployment with local network file access (see the start of this chapter).

Syntax

SaveToNetwork /path=<folder path> /xpath=<XPath> [/dsname=<data source>] [/name=<file name> | /namexpath=<relative XPath>] [/uniquename=true|false] [/overwrite=true] [/clear=true|false] [/createdirectory=true|false]

Result: the number of files saved.

Example

SaveToNetwork /path=\\fileserver\forms\Receipts /xpath=/my:myFields/my:Attachments/my:Attachment/my:File[. != ''] /namexpath=../my:FileName

Saves every filled attachment row under the name in that row's FileName field, then clears each File field and fills its my:qRulesFilename and my:qRulesLink attributes.

Notes

• Each file field needs two attributes whose names start with qRulesFilename and qRulesLink (for example my:qRulesFilename and my:qRulesLink). Without them the command fails with Error: The required attributes are missing: 'qRulesFilename' and 'qRulesLink'. After saving, the first receives the file name used and the second the link returned by the server. They are filled even with /clear=false.
• Select only filled fields. If none of the selected fields has a file, the command succeeds with Result 0 and the warning Warning: No attachments were found at the specified path. But if the selection mixes filled and empty fields, the empty ones are processed too and the command stops with Failed to upload, invalid file found. Add a filter such as [. != ''], as in the example.
• The attachment's extension is added when the chosen name has none or a different one: Receipt becomes Receipt.pdf, and Receipt.txt for a PDF file becomes Receipt.txt.pdf.
• With /name, every selected file gets the same name. When saving several files, use /namexpath or the default unique names.
• An empty name (for example an empty /namexpath field) fails with Filename is required to upload file. A /namexpath that finds no field fails with Invalid file name node XPath. A name with characters not allowed in file names is rejected.
• Files are saved one after the other. If one fails, the command stops with the server's message (or Unspecified error while uploading the file); files saved before it stay saved and their fields are already cleared.

Related: SubmitToNetwork, GetAttachmentAttribute, DeleteFile.

10.8 SubmitToNetwork

Saves the XML of the form, or of any data source, as a file in a network folder. Use it to keep a copy of each submitted form on a file share. Requires a FormsViewer deployment with local network file access (see the start of this chapter).

Syntax

SubmitToNetwork /path=<full file path> | /path=<folder path> /filename=<name> [/dsname=<data source>] [/createdirectory=true] [/overwrite=true]

Result: empty on success.

Examples

SubmitToNetwork /path=\\fileserver\forms\Saved\Order-1001.xml
SubmitToNetwork /path=\\fileserver\forms\Saved /filename-xpath=/my:myFields/my:FileName /createdirectory=true /overwrite=true

The first saves the form under a fixed name; the second takes the name from a field, creates the folder if needed and replaces an earlier version.

Notes

• The data source is saved as UTF-8 XML. File attachments in the form are saved inside the XML, as they are stored in the form.
• Note the defaults: unlike SaveToNetwork, /createdirectory is false here.
• Errors: Could not determine folder path to save to., Could not determine file name., or the server's message (There was an error while uploading file when it gives none). A name with characters not allowed in file names is rejected.
• To read the file back into the form, use GetNetworkFile with /action=load.

Related: SaveToNetwork, GetNetworkFile.

10.9 RenderForm

Renders the form's data through one or more views and returns the result as a PDF or as plain text. Use it to attach a PDF copy of the form to an e-mail, to store it in a file attachment field before submitting, or to open it for printing. PDFs are generated by the FormsViewer server.

Syntax

RenderForm /format=pdf|text [/views=<view>[&<view>...]] [/output=base64|base64raw|text] [/filename=<name>] [/open=browser|download|none] [/templatename=<template> [/dsname=<data source>]] [/useactualview=true] [/includebuttons=true] [/attachmentsxpath=<XPath> /attachmentsmode=inline] [/headertext=<text>] [/headerfontfamily=<font>] [/headerfontsize=<points>] [/headeralignment=<alignment>] [/footertext=<text>] [/footerfontfamily=<font>] [/footerfontsize=<points>] [/footeralignment=<alignment>]

Result: the PDF (as a file attachment value or plain base64), or the view's text.

Examples

RenderForm /format=pdf /open=none /filename=Expense report.pdf /resultxpath=/my:myFields/my:PdfCopy
RenderForm /format=pdf /views=Summary&Details /footertext=Page {CrtPage} of {PageCount} /footeralignment=center /open=download
RenderForm /format=pdf /attachmentsxpath=/my:myFields/my:Attachments/my:Attachment/my:File /attachmentsmode=inline /open=browser
RenderForm /format=text /views=Summary

The first stores a PDF of the current view in a file attachment field without showing it, for example before a submit. The second merges two views with page numbers and downloads the result. The third opens a PDF that includes the attached files. The fourth returns the Summary view as plain text, for example for an e-mail body.

Notes

• /open defaults to browser. A RenderForm step that only needs the PDF in a field (before a submit or an e-mail) should use /open=none, or the PDF opens every time the rule runs.
• /format, /output and /attachmentsmode values are case-sensitive: /format=PDF fails with Unsupported /format value: PDF.
• View names are checked against the current template: Invalid view name(s): 'name'. With /templatename, they are not checked locally, but /views is required: /views must be specified when using /templatename.
• /useactualview=true captures what the user sees, including the current state of the page. It fails with Cannot specify multiple views when using /useactualview=true or Cannot specify a different view when using /useactualview=true. It has no effect with /format=text.
• Text format reads the rendered view: field values and labels are kept, table cells are separated by tabs and rows by line breaks. Hidden sections, pictures and attachments, "Insert item" links and (unless /includebuttons=true) buttons are left out. Render one view at a time with text.
• Attachments: empty fields are skipped; two files with the same name are renamed, for example Picture.png and Picture_2.png. If the server cannot include an attachment, the PDF is still created, Success is true, and Error holds a warning such as Attachment 'name': reason (up to ten, separated by |).
• Other errors: Unsupported /output value: value., Unsupported /format value: text with /output value: base64., Cannot use /templatename with /format=text, Cannot use /attachmentsxpath with /format=text, /attachmentsmode is required when /attachmentsxpath is specified, Cannot use /attachmentsmode without /attachmentsxpath, Invalid /attachmentsmode value: value. Supported values are: inline, Invalid /open value: value, and An unknown error occurred trying to generate the PDF. when the server reports a failure without a message.
• The command description in the Command Builder says /filename only applies with /output=base64; the engine also uses it as the name of the opened or downloaded file.

Related: GetAttachmentAttribute, SaveToNetwork, DownloadAttachment. To send the PDF by e-mail, see SendEmail; to save it to SharePoint, see SaveToSharePoint.

Back to the Command Index.