Understanding the File Attachment Functions

This section provides an overview of:

  • PeopleCode built-in file attachment functions.

  • File attachment architecture.

  • File attachment storage locations.

  • Storage location URLs.

All file attachments are performed using PeopleCode built-in functions, such as AddAttachment, ViewAttachment, GetAttachment, and so on. These functions operate on and transfer files to and from supported storage locations: database tables, FTP sites, and HTTP repositories.

PeopleCode provides eight built-in file attachment functions that are organized into three categories:

  • End user upload/download:

    • AddAttachment

      Use the AddAttachment function to upload one file from an end user specified location (local storage or cloud storage) to a specified storage location.

      See AddAttachment.

    • MAddAttachment

      Use the MAddAttachment function to upload one or more files from an end user specified location (local storage or cloud storage) to a specified storage location.

      See MAddAttachment.

    • DetachAttachment

      Use the DetachAttachment function to download a file from its source storage location and save it locally on the end user machine. The file is sent to the browser with appropriate HTTP headers to cause the browser to display a save as dialog box to the user.

      See DetachAttachment.

    • ViewAttachment

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

      See ViewAttachment.

  • Application server upload/download:

    • PutAttachment

      Use the PutAttachment function to upload a file from the file system of the application server to the specified storage location.

      See PutAttachment.

    • GetAttachment

      Use the GetAttachment function to download a file from its source storage location to the file system of the application server.

      See GetAttachment.

  • Storage location maintenance:

    • CleanAttachments

      Use the CleanAttachments function to remove orphan files (files with no corresponding file reference) from specified tables used as storage locations in the current database.

      See CleanAttachments.

    • CopyAttachments

      Use the CopyAttachments function to copy all files with file references from one storage location to another. The files to be copied can be limited to those referenced in specific file reference tables.

      See CopyAttachments.

    • DeleteAttachment

      Use the DeleteAttachment function to delete a file from the specified storage location.

      See DeleteAttachment.

Image: PeopleCode file attachment functions

The following diagram illustrates the operation of the PeopleCode file attachment functions:

PeopleCode file attachment functions

Because these functions abstract the storage of the attachments, you can use any defined storage location. The location to be used is determined by the URL passed as the first parameter to the invoked attachment function.

File attachments are supported by using PeopleCode built-in functions that implement the transfer of a file to or from a storage location. Using the PeopleCode functions, files can be transferred back and forth from the end user machine to the storage location (by way of the web server and application server) or transferred back and forth from the application server file system to the storage location.

The following steps depict the process of transferring a file with the AddAttachment function:

  1. The file is streamed from the browser to the servlet on the web server using a standard HTML form construct.

    Optionally, if virus scan is enabled, the stream in the HTTP servlet request is scanned by the virus scan engine.

    See Setting Up Virus Scanning.

    Note: This transfer can be performed securely in an encrypted fashion if the web server uses Secure Sockets Layer (SSL) to communicate to the browser.

    Note: When the user selects a file for uploading, file size is not checked until after the file is transferred to the web server. Once the file gets to the web server the file size is compared to the value of the AddAttachment function's MaxSize parameter. The transfer is terminated if the file size exceeds this parameter.

  2. As the file stream is received by the web server, the file is streamed from the web server to the application server in one-megabyte chunks until there is no streamed data available on the web server.

    Note: The one-megabyte transfer chunk size between web server and application server is fixed and cannot be changed.

    Note: The web server-to-application server transfer is performed by using Oracle Jolt, which is securely encrypted. Because this transfer is done using the standard Oracle Jolt mechanism, no additional settings to the firewall are required (you do not need to open additional ports).

  3. The file chunks from the web server are transferred by the application server to a temporary table in the database. The chunk size for this temporary storage depends on the ultimate storage location.

    For database tables, the chunk size is governed by the value of the Maximum Attachment Chunk Size field on the PeopleTools Options page. The chunk size in temporary storage can vary, but it never exceeds this maximum attachment chunk size limit. For all other storage locations, the chunk size in the temporary storage table is 16 KB.

  4. Then, the application server transfers the file in chunks from the temporary database table to its ultimate storage location.

    Once the entire file is transferred, the application server deletes the temporary copy from the PeopleTools table in the database.

    Note: If the storage location is a database table, then the chunk size is exactly as specified by the value of the Maximum Attachment Chunk Size field (except for the last chunk written, which can be smaller than the maximum).

    See File Attachment Chunk Size.

    Note: If the storage location is an FTP site or an HTTP repository, the file is reassembled into a whole file at the destination.

Note: The file transfer process for MAddAttachment is, in general, similar to the process for AddAttachment. With a call to MAddAttachment, the files are streamed from the browser to the web server in bulk but from the web server through to the storage location one file at a time. Moreover, virus scanning cannot currently be performed on files uploaded with MAddAttachment.

Image: AddAttachment file transfer process

The following diagram depicts this process of transferring a file with the AddAttachment function:

AddAttachment file transfer process

The file attachment architecture is designed for use in the frame template or the iframe template only. It is not supported in a pagelet or an HTML template. When content is rendered in a pagelet or HTML template, the user interaction is managed through the PeopleSoft portal servlet. For the file attachment architecture to work, the browser must communicate directly with the PeopleSoft content servlet, which requires the use of the frame or iframe template.

PeopleTools supports three types of storage locations: database tables, FTP sites, and HTTP repositories. Except for the CleanAttachments function, all PeopleCode file attachment functions support all three storage locations. The CleanAttachments function operates only on database tables as storage locations.

This section provides an overview of the following:

  • Database storage considerations

  • FTP site considerations

  • HTTP repository considerations

Important! The following applies to FTP sites and HTTP repositories on Windows only:

When uploading to a Windows file system or downloading files from a Windows file system, remember that Windows processes file names in a case-insensitive manner. So, for example, if a file called FILE1.TXT already exists at a particular location on a Windows file system:

Attempting to download a file called file1.txt from that same location will have the effect of downloading the file FILE1.TXT that is there.

Attempting to upload a file called file1.txt to that same location will have the effect of overwriting the file FILE1.TXT that is there.

Database Storage Considerations

To store file attachments in the database, you must create a target table to store the attachments themselves. The record definition associated with this target table must include the FILE_ATTDET_SBR subrecord and no other fields.

This chapter contains additional information on how to create the target table.

See Application Development Process Overview.

When the storage location is a database table, the URL parameter of the invoked file attachment function can be specified in one of two ways:

  • A URL string in the form of: 

    record://MYRECORD

    In this case, MYRECORD is the record definition associated with the target table.

  • A URL identifier in the form of: 

    URL.URL_ID

    In this case, the URL identifier refers to the URL object named URL_ID.

FTP Site Considerations

When the storage location is an FTP site, the URL can be defined in one of two ways:

  • A URL string in the form of: 

    ftp://FTP_user:FTP_pwd@FTP_site/path

    Important! FTPS and SFTP require that a URL object be used and do not support URL strings. This form of URL string is for use with the FTP protocol only.

  • A URL identifier in the form of: 

    URL.URL_ID

    In this case, the URL identifier refers to the URL object named URL_ID.

When specifying a URL for an FTP site, specify the FTP server's name or its IP address. Specify a path on the FTP server relative to the directory specified as the FTP server's home directory.

Note: For many FTP servers, the FTP server's home directory is specifiable on a per-FTP-user basis. Therefore, if an application will be using multiple FTP user accounts, then care must be take to ensure that files are being stored and accessed in a consistent manner with respect to their absolute location on the FTP server.

The default FTP port is 21. If you want to use a different port, you must specify it in the URL, as part of the FTP server address. For example:

ftp://ftpserver.peoplesoft.com:6000/

Note: If the specified subdirectories do not exist the PeopleCode function tries to create them.

The following limitations apply to FTP URLs:

  • The FTP user name to is limited to 30 characters.

  • The FTP password to is limited to 16 characters.

HTTP Repository Considerations

When the storage location is an HTTP repository, the URL parameter of the invoked file attachment function must be specified as a URL identifier in the form of:

URL.URL_ID

In this case, the URL identifier refers to the URL object named URL_ID.

An HTTP repository can reside on a PeopleSoft web server, or on a different web server environment. If the HTTP repository resides on a PeopleSoft web server, then the psfiletransfer servlet has been provided to manage the file transfers to and from the storage location. If the HTTP repository resides on a non-PeopleSoft web server, then you need to ensure that the web server can handle file transfer security and requests.

Additional configuration is required to set up a PeopleSoft web server as an HTTP repository. See the “Working with HTTP/HTTPS” section in PeopleTools: System and Server Administration.

See URL Maintenance

The URL parameter of the invoked file attachment function includes both the protocol to be used and the address for a storage location. These URLs can be specified as ad hoc strings at run time in certain limited cases. Alternatively, they can be defined and maintained as URL objects, which include an identifier, the URL itself, and additional URL properties. Oracle recommends that you always use URL objects since that approach gives you the flexibility of later changing the storage location of your files without having to modify your PeopleCode or the contents of any file reference tables used. Moreover, the FILE_EXT_LIST property of a URL object allows you to specify a file extension list, which is the most straightforward way to restrict the file types that can be uploaded to or downloaded from your PeopleSoft system. File extension lists cannot be applied to ad hoc URL strings.

See Restricting the File Types That Can Be Uploaded or Downloaded.

URL objects are created and maintained using the URL Maintenance page (PeopleTools, Administration, Utilities, URLs). The length of the full URL is limited to 254 characters. Certain protocols—specifically, FTPS, SFTP, HTTP, and HTTPS—require the use of URL objects because other information in addition to the URL itself are required. This additional information is defined as URL properties on the associated URL Properties page.

Note: For database tables and the FTP protocol only, the storage location can be specified as an ad hoc string at run time because these file transfer methods do not require additional URL properties.

PeopleTools: System and Server Administration contains detailed information on creating and maintaining URL objects.

See URL Maintenance

The following are examples of some valid storage location URLs:

record://MYAPP_ATT_CNTNT
ftp://user01:password@ftpserver.peoplesoft.com/myfiles
ftps://ftp_user:usr_pwd@ftps.oracle.com:6000/images
sftp://usr10:pwd@ftp.mycompany.com/attachments
http://www.peoplesoft.com:8080/psfiletransfer/ps/docs
https://www.peoplesoft.com:8090/psfiletransfer/empl/docs