September 4, 2018September 4, 2018| Stan YorkStan York|
Categories:

ATC: ATTACH UPDATE  options

This command modified existing matching attachments on a document.

  • options are optional.  There are several options that can be used singularly or together, separated by spaces.  Clearly, you will use at least one!
    • FILTER filter; requires a semicolon (;) after it. This option specifies a filter for limiting the scope to those attachments that match.  Use .NET Data Expression syntax (for more information see the Data Dictionary and .NET data expression syntax). If the filter option is omitted, all document attachments will be processed. The filter can also be assigned to a variable using ATC: SET; the semicolon goes after the variable name—not in the ATC: SET command.
    • INCLUDE how specifies a new route include mode for the file and causes routed content to be recalculated. How must be one of the following:
      • M to include the file assembled in routed content;
      • P to include the PDF version of the file in routed content
      • 1 to include the native file in routed content
      • 0 to exclude the file from routed content (i.e, not sent)
    • FOLDER $FolderName is optional.  $Foldername is any variable name into which has been placed a folder path.
    • NAME newname; is optional but requires a semicolon (;) after it. It specifies the new name for the file; bookmarks are expanded.  Do not include the file type (extension) because the extension will be added automatically.  If the name would be a duplicate, a (n) is added before the extension.  Avoid periods inside the file name; do not include a file extension.  The name can also be assigned to a variable using ATC: SET; in which case the semicolon goes after the variable name—not in the ATC: SET command.
    • REFRESH refreshes matching attachments that have bookmark replacement enabled, creating a new file version if necessary.  The file will automatically be unlocked if necessary (but a checkout by another user will block the action).  If the file was unlocked for the REFRESH, it is automatically re-locked unless it is included as assembled content. Note: if the file already has bookmarks frozen it cannot be processed by this command.
    • FREEZE turns off future bookmark updates/refreshing by setting the Bookmarks Locked option on (checkmark).  Manual editing remains possible unless the file is also locked.
    • LOCK marks the attachment as LOCKED to prevent additional changes.  If a refreshable file is locked, it is also automatically frozen.
    • SYSLOCK marks the attachment as LOCKED to prevent changes by end users.    An admin can unlock the file.
    • UI how is optional. It specifies whether the file should be shown on the Attachments tab.  How must be either Hidden or Visible. The default is Visible.
    • UNFREEZE turns on future bookmark updates/refreshing by setting the Bookmarks Locked option off (unchecked), as long as the file itself is unlocked.
    • APPLY template name;  is only applicable for Excel attachments. The option copies all worksheets and defined names from the specified Excel template onto the specified attachment. The option can support CSV files and change the CSV file to an XLSX file (with the same name). See example below.
    • [V23+] ERASE {VALUES} ranges; Empties the cells of one or more ranges in an Excel attachment. Separate multiple ranges with a comma; the semicolon terminator is required. The cell contents are removed but formatting, merged cells and the rest of the worksheet are left alone.
      Hints:

      • Include the optional VALUES for ranges in which you want constants cleared but formulas left in place.
      • You can combine ERASE ranges and ERASE VALUES ranges in the same command.
      • Valid range formats:
        • A rectangle range such as SheetName!A2:B20
        • A whole column by letter such as Sheet1!E:E
        • A whole row by number, or a range of rows such as Sheet1!2:20
        • The “defined name” of a range
        • A $workflowvariablename that has been assigned the above using ATC: SET
      • Include Sheet Names!  If the sheet name is omitted, the workbook’s active sheet *when the file was last saved* would be assumed.
      • Enclose a sheet name containing spaces in single quotes (‘Bid Detail’!A2:B20).
      • Use a variable assigned via ATC: SET to enhance readability.
      • Erasing takes place after APPLY, so a range cleared here stays cleared even if the applied template supplied content for it.
      • Each updated attachment is saved as a new file version.
      • Non-Excel attachments are skipped with a workflow warning;
      • If no range could be matched the script logs a warning.
    • SOURCE contact specifies the source contact to be associated with the file attachment. The contact can be indicated by an email, user key, or user login.
    • TYPE doctype specifies the Spitfire Document type to be associated with the file attachment. This doctype can be indicated by DocTypeKey or by [name] in square brackets.
    • NOTE text; specifies the note to be associated with the file attachment. This free-form text must be ended by a semicolon. If the text includes a semicolon, use the ATC: SET $NoteVar = command prior to the ATC: ATTACH UPDATE command.

Examples:

ATC: ATTACH UPDATE FILTER FileName LIKE '.csv'; APPLY [CVS to XL];

The above example means “update attached files that end in .csv by changing those CVS files to Excel XLSX files.”

ATC: SET $Ranges = Sheet1!A2:B20, Sheet1!E2:E99
ATC: ATTACH UPDATE FILTER FileName LIKE '*.xlsx' AND FileName LIKE 'Bid*'; ERASE $Ranges;

The above example means “place the two cell ranges into the variable $Ranges, then empty cells A2 through B20 and cells E2 through E99 on Sheet1 of every attached file whose name starts with Bid and ends in .xlsx.”

ATC: ATTACH UPDATE FILTER FileName LIKE '*.xlsx'; APPLY [Bid Worksheet]; ERASE 'Bid Detail'!A5:H200;

The above example means “add the worksheets from the Bid Worksheet template to every attached Excel file, then clear the sample rows the template supplied in cells A5 through H200 of the Bid Detail sheet.”

ATC: SET $TargetFolder = /Contracts
ATC: SET $Filter = FileName LIKE '*.docx'
ATC: SET $NewName = Updated for [DocHeader_SourceDocNo]
ATC: ATTACH UPDATE FILTER $Filter; NAME $NewName; FOLDER $TargetFolder INCLUDE P

The above example means “place the string /Contracts into the variable name $TargetFolder and place files ending with .docx into the variable name $Filter then change all attachments with names matching $Filter so that they are in the $Targetfolder and include them in routed content as PDF.  Change the file name too.”

ATC: SET $NewName = [DocHeader_Project] - [DocHeader_Title]
ATC: SET $FILTER = RefreshBookmarks AND FileName LIKE '*.docx'
ATC: ATTACH UPDATE FILTER $Filter; NAME $NewName; INCLUDE P

The above example means “Set the variable $NewName to contain the Project and Document Header, then set the variable $Filter to a .NET expression that selects only files that have the Refresh Bookmarks option checked and that end in docx, and finally update the attached files that match the filter with the new name and set the Include option to PDF.”

Last updated: September 10, 2026 at 14:54 pm; green text = new

Tags: , ,

Related Post