ViewAttachment function

Syntax

ViewAttachment(URLSource, DirAndSysFileName, UserFileName [, NewWindow[, PreserveCase]])

Description

Use the ViewAttachment function to download a file from its source storage location and open it locally on the end-user machine.

By using the UserFileName parameter, the copy of the file to be viewed may be given a different name than the file at the storage location.

Additional information that is important to the use of ViewAttachment can be found in the PeopleTools: PeopleCode Developer's Guide:

• PeopleTools supports multiple types of storage locations.

  See PeopleCode Developer’s Guide: Understanding File Attachment Storage Locations.

• Certain characters are illegal in file names; other characters in file names are converted during file transfer.

  See PeopleCode Developer’s Guide: File Name Considerations.

• Non-ASCII file names are supported by the PeopleCode file attachment functions.

  See PeopleCode Developer’s Guide: Attachments with non-ASCII File Names.

• The PeopleCode file attachment functions do not provide text file conversions when files are attached or viewed.

  See PeopleCode Developer’s Guide: Considerations When Attaching Text Files.

• Because ViewAttachment is interactive, it is known as a “think-time” function, and is restricted from use in certain PeopleCode events.

  See PeopleCode Developer’s Guide: Restrictions on Invoking Functions in Certain PeopleCode Events.

You can use a file extension list to identify file types to accept or reject when using this function.

See System and Server Administration: Using Administration Utilities.

Parameters

Parameter	Description
URLSource	A reference to a URL. This can be either a URL identifier in the form URL.URL_ID, or a string. This, along with the DirAndSysFileName parameter, indicates the file's source location. Note: When the URLSource parameter is specified as a string value, forward slashes (/) are required. Backward slashes (\) are not supported for a string value. See PeopleCode Developer’s Guide: Understanding URL Strings Versus URL Objects.
DirAndSysFileName	The relative path and file name of the file on the file server. This is appended to URLSource to make up the full URL where the file is transferred from. This parameter takes a string value Note: Because the DirAndSysFileName parameter is appended to the URL, it also requires forward slashes (“/”). Backward slashes (“\”) are not supported for this parameter.
UserFileName	The name associated with the copy of the file to be viewed (may be different than the name of the file at the storage location). Note: The file name for the user-selected file cannot be greater than 64 characters.
NewWindow	Specify if the browser should try to use a new window to display the attachment. This parameter takes a Boolean value. The default is True.
PreserveCase	Specify a Boolean value to indicate whether when searching for the file specified by the DirAndSysFileName parameter, its file name extension is preserved or not; True, preserve the case of the file name extension, False, convert the file name extension to all lowercase letters. The default value is False. Warning! If you use the PreserveCase parameter, it is important that you use it in a consistent manner with all the relevant file-processing functions or you may encounter unexpected file-not-found errors.

Returns

You can check for either an integer or a constant value:

Numeric Value	Constant Value	Description
0	%Attachment_Success	File was transferred successfully. Important: If file type restrictions are changed so that access to a previously uploaded file is now blocked, a call to ViewAttachment will return %Attachment_Success, even though the file and its contents are not displayed.
1	%Attachment_Failed	File transfer failed due to unspecified error. The following are some possible situations where %Attachment_Failed could be returned: Failed to initialize the process due to some internal error. Failed due to unexpected/bad reply from server. Failed to allocate memory due to some internal error. Failed due to timeout. Failed due to non-availability of space on FTP server. Failed to close SSL connection. Failed due to an unspecified error on the HTTP repository. If the HTTP repository resides on a PeopleSoft web server, then you can configure tracing on the web server to report additional error details. See PeopleCode Developer’s Guide: Enabling Tracing on the Web Server or Application Server.
2	%Attachment_Cancelled	File transfer didn't complete because the operation was canceled by the end user.
3	%Attachment_FileTransferFailed	File transfer failed due to unspecified error during FTP attempt. The following are some possible situations where %Attachment_FileTransferFailed could be returned: Failed due to mismatch in file sizes. Failed to write to local file. Failed to store the file on remote server. Failed to read local file to be uploaded No response from server. Failed to overwrite the file on remote server.
7	%Attachment_DestSystNotFound	Cannot locate destination system for FTP. The following are some possible situations where %Attachment_DestSystNotFound could be returned: Improper URL format. Failed to connect to the server specified.
8	%Attachment_DestSysFailedLogin	Unable to login to destination system for FTP. The following are some possible situations where %Attachment_DestSysFailedLogin could be returned: Unsupported protocol specified. Access denied to server. Failed to connect using SSL Failed to verify the certificates. Failed due to problem in certificates used. Could not authenticate the peer certificate. Failed to login with specified SSL level. Remote server denied logon. Problem reading SSL certificate.
9	%Attachment_FileNotFound	Cannot locate file. The following are some possible situations where %Attachment_FileNotFound could be returned: Remote file not found. Failed to read remote file.

Example

&retcode = ViewAttachment(URL.MYFTP, ATTACHSYSFILENAME, ATTACHUSERFILE); 
 

An example of the ViewAttachment function is provided in the demonstration application delivered in the FILE_ATTACH_WRK derived/work record. This demonstration application is shown on the PeopleTools Test Utilities page.

See PeopleCode Developer’s Guide: Using the PeopleTools Test Utilities Page.

Security Considerations

PeopleTools includes an X-Content-Type-Options: nosniff response header with content retrieved using the ViewAttachment built-in function.

Viewing a file involves requesting that it be opened. The result of the open action depends upon the extension of the file name and the application associated with that extension. Keep in mind that the act of opening a file with certain extensions (for example, .exe or .bat) results in the file being executed when it is opened. If you do not want specific file type to be handled this way, you must prevent the end user from viewing the requested file.

When the end user views attachments using the ViewAttachment function, some browsers treat documents as HTML regardless of file extension, and thus execute embedded JavaScript. You may want to write a PeopleCode program to allow only specific file extensions to be viewed.

Alternatively, you can use a file extension list to restrict the file types that can be uploaded to or downloaded from your PeopleSoft system.

See PeopleCode Developer’s Guide: Restricting the File Types That Can Be Uploaded or Downloaded.

Problems Downloading Files

The combination of the attachmentExtraWindow web profile property and settings of a browser can silently interfere with downloading and opening of files with the ViewAttachment function. For more information, see the documentation on the attachmentExtraWindow web profile property.

See Portal Technology: Configuring Custom Properties.

In addition, if you need to use the SetLanguage built-in function to change languages, invoke SetLanguage prior to invoking ViewAttachment or DetachAttachment. You must place the call to SetLanguage in a different PeopleCode program and event from the PeopleCode program and event that invokes ViewAttachment or DetachAttachment.