Working With File Attachments

This chapter provides an overview of the file attachment functions and discusses:

• Developing applications that use file attachment functions.

• Application development considerations.

• Application deployment and system configuration considerations.

• Debugging file attachment problems.

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.

PeopleCode Built-in File Attachment Functions

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 machine to a specified storage location.

    See AddAttachment.

  • AddAttachment

    Use the MAddAttachment function to upload one or more files from an end-user machine 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.

The following diagram illustrates the operation of these 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.

See Also

Understanding File Attachment Storage Locations

Understanding URL Strings Versus URL Objects

Understanding the File Attachment Architecture

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. After the file is received at the web server, the file is streamed from the web server to the application server in one-megabyte chunks.

   Note. The one-megabyte transfer chunk size between web server and application server cannot be customized.

   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.

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.

See Also

Understanding Portal Templates

Understanding Template Types

Understanding File Attachment Storage Locations

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

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. 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 the PeopleTools 8.52: System and Server Administration PeopleBook.

See URL Maintenance.

Understanding URL Strings Versus URL Objects

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.

The PeopleTools 8.52: System and Server Administration PeopleBook 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

Developing Applications that Use File Attachment Functions

This section provides an overview of the application development process and discusses:

• Delivered record definitions.

• Managing entries in file reference tables.

• Using the PeopleTools Test Utilities page.

Application Development Process Overview

Follow these steps to develop an application that uses file attachments:

1. Create an application-specific, default storage location.

   Oracle recommends that you use a database table as the default storage location so that it is available to you during application development, and to customers as a default when the application is installed. You must include the FILE_ATTDET_SBR subrecord in the record definition associated with this target table; the record definition must have no other fields.

   Create a storage location that is unique to your application. (Specifically, to avoid potential file name conflicts and unintended file overwrites, do not share storage locations among applications.) For example, create a record definition named MYAPP_ATT_CNTNT and build the associated database table. If you need to store other information, store it as part of the file reference, as described in the step 3, or create another record and use it in the component.

2. Create a URL object that corresponds to your default storage location.

   See Understanding URL Strings Versus URL Objects.

3. Create an application-specific record definition to define the table that will store file reference information and any additional information about the file attachments. You must include the FILE_ATTACH_SBR subrecord in this new record definition.

   For example, create a new record called MYAPP_ATT_REF. Add fields for any other information related to the transaction you want to store. Your application must populate the fields in this file reference table with the system file name, user file name, and any information about the file that will be needed for later use.

   Note. Create a file reference record that is specific to your application. In addition, you should consider whether to create a separate file reference record for each storage location. Doing so can prevent file name conflicts, eliminates the need to store the URL string or URL identifier with each file reference, and can ease the use of the CopyAttachments function.

   See Considerations When Using CopyAttachments.

4. Clone the FILE_ATTACH_WRK record to create an application-specific derived/work record with a unique name. Save the PeopleCode with the new record.

   For example, create a record named MYAPP_ATT_WRK by cloning FILE_ATTACH_WRK. You can use this copy of the sample PeopleCode as the basis for your own application.

   Important! The FILE_ATTACH_WRK record is delivered as a sample only. It is not intended for direct use as part of an application running in production. Instead an application-specific clone of it must be used. Oracle can change the delivered sample PeopleCode in future releases. Any application that directly uses the FILE_ATTACH_WRK record might fail. Using application-specific PeopleCode makes it easier to manage during upgrades and your PeopleCode can be reused in other components that use file attachment functionality.
   
   You must also implement the PeopleCode to manage the data in your file reference table (or tables).

5. Use the records you created in the previous steps to create the file attachment component and page.

   The derived/work record has fields with FieldChange PeopleCode that you can use for Add, Delete, Detach, and View buttons.

   Add PeopleCode—probably at the component record field level—to invoke the underlying functions in the application-specific derived/work record when the user clicks on one of the buttons.

Delivered Record Definitions

The following table summarizes the delivered record definitions for use in a file attachment application:

FILE_ATTDET_SBR Subrecord

To use a database table as a storage location, you must create an application-specific record definition associated with the target table that will receive the attachments. You must include the FILE_ATTDET_SBR subrecord in your application-specific record, and it can contain no additional fields.

The FILE_ATTDET_SBR subrecord has the following fields:

PeopleTools maintains the values in this table. Therefore, do not reuse the fields in this table to store incomplete or nonstandard versions of the file name or other data.

FILE_ATTACH_SBR Subrecord

You must insert the FILE_ATTACH_SBR subrecord in the application-specific record definition to be associated with the table that will store references to the attached files. The fields in this subrecord store the system file name and the user file name.

The FILE_ATTACH_SBR subrecord contains the following fields:

Your application must populate these fields with the system file name, user file name, and any information about the file that will be needed for later use.

See Managing Entries in File Reference Tables.

FILE_ATTACH_WRK Derived/Work Record

The FILE_ATTACH_WRK derived/work record provides sample PeopleCode programs that demonstrate how to use the file attachment PeopleCode built-in functions. Clone this derived/work record so that you can customize the programs to suit your application's needs.

The FILE_ATTACH_WRK derived/work record contains the following fields:

The PeopleTools Test Utilities page demonstrates a sample application that makes use of the PeopleCode programs in the FILE_ATTACH_WRK derived/work record.

See Using the PeopleTools Test Utilities Page.

Managing Entries in File Reference Tables

When you create a file attachment application, you create an application-specific record to be associated with the table that will store file reference information and any additional information about the file attachments. You must include the FILE_ATTACH_SBR subrecord in this new record. For example, you might create a new record called MYAPP_ATT_REF. Then, you would add fields for any other information related to the transaction you want to store.

Your application must populate these fields with the system file name, user file name, and any information about the file that will be needed for later use. Your application should use the fields in file reference tables as follows:

• When your application is uploading files (for example, with AddAttachment):

  • ATTACHSYSFILENAME – Save the system file name in the ATTACHSYSFILENAME field. This is the name of the file as it exists at the storage location and is also a key field of your file reference table.

  • ATTACHUSERFILE – Save the user file name, which is the value returned by AddAttachment in its UserFile parameter. This is essentially the base name of file selected by the end user for uploading and would be used to allow end users to identify the file in other file attachment operations (such as viewing, downloading, or deleting).

• When your application is downloading or deleting files (for example, with ViewAttachment, DetachAttachment, or DeleteAttachment):

  • ATTACHUSERFILE – Use the ATTACHUSERFILE field to present a list of available files for end user selection. This field is also passed as a parameter to some of the built-in PeopleCode functions.

  • ATTACHSYSFILENAME – Use the ATTACHSYSFILENAME field (along with the ATTACHUSERFILE field, for some of the built-in PeopleCode functions) to construct the parameters to be passed to the built-in PeopleCode functions.

See Also

FILE_ATTACH_SBR Subrecord

Using the PeopleTools Test Utilities Page

Access the PeopleTools Test Utilities page (PeopleTools, Utilities, Debug, PeopleTools Test Utilities).

The PeopleTools Test Utilities page contains a sample file attachment application that allows you to upload (Attach button), save (Detach button), delete (Delete button), and open (View button) a file attachment. The page allows you to specify a storage location as a URL identifier or as an ad hoc string. After clicking the Attach button, you are prompted to select a file to upload to the storage location. Once the selected file has been successfully uploaded, buttons appear that allow you to open, save, or delete that file from its storage location.

Note. This demonstration application permits the user to enter a URL of up to 120 characters only.

The actual page definition involved, PSTESTUTIL, contains buttons that execute FieldChange PeopleCode programs in the FILE_ATTACH_WRK derived/work record definition. These programs are provided as working examples of how to use the following file attachment functions: AddAttachment, DeleteAttachment, DetachAttachment, and ViewAttachment. If you are developing a file attachment application, you can clone the FILE_ATTACH_WRK derived/work record definition and modify the copied programs to fit your application’s file processing requirements.

Important! Do not modify the delivered FILE_ATTACH_WRK record definition or the PeopleCode programs it contains. In addition, do not directly call these PeopleCode programs from any PeopleCode programs you implement. Oracle might modify these sample programs in a future release of PeopleTools.

See FILE_ATTACH_WRK Derived/Work Record.

The FILE_ATTACH_WRK derived/work record definition also demonstrates a programmatic methodology for restricting file types. The IsLegalAttachmentType function compares a given file to an internally defined array of illegal file extensions. This programmatic methodology can be contrasted with restricting file types through the use of file extension lists. File extension lists can be provide an easier, more flexible, and more manageable approach to restricting file types than a programmatic method.

Important! Do not combine these two methodologies in the same application.

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

Application Development Considerations

This section discusses:

• File name considerations.

• Restrictions on invoking functions in certain PeopleCode events.

• Converting file names for files uploaded by PutAttachment.

• Considerations when using CopyAttachments.

File Name Considerations

If the source file name specified using one of the file attachment. contains any of the following characters, the invoking function will be stopped and an error (%Attachment_Failed) is returned. The actual error message can be found in the logs.

• * (asterisk)

• : (colon)

• " (quotation mark)

• < (less than symbol)

• > (greater than symbol)

• ? (question mark)

When the file is uploaded to or downloaded from a storage location, the following characters are replaced with an underscore:

• (space)

• @ (at sign)

• ; (semicolon)

• + (plus sign)

• % (percent sign)

• & (ampersand)

• ' (apostrophe)

• ! (exclamation point)

• # (pound sign)

• $ (dollar sign)

Note. In general, you should exercise caution when using an @ or : character in the name of a file selected for uploading. In FTP URLs, the : character must to be used as a delimiter between the FTP user ID and the FTP password or just before the FTP port number (if one is specified). In addition, in FTP URLs, the @ character must be used as a delimiter between the FTP password and the FTP server address.

Restrictions on Invoking Functions in Certain PeopleCode Events

Because AddAttachment, DetachAttachment, MAddAttachment, and ViewAttachment are interactive, they are known as “think-time” functions. This means that these functions should not be used in any of the following PeopleCode events:

• SavePreChange

• SavePostChange

• Workflow

• RowSelect

• Any PeopleCode event that initiates as a result of a Select or SelectNew method, or any of the ScrollSelect functions.

If you want to transfer files in a non-interactive mode with functions that aren't think-time functions, see GetAttachment and PutAttachment.

See Also

Select

SelectNew

Think-Time Functions

Converting File Names for Files Uploaded by PutAttachment

Generally, a PeopleCode program that calls PutAttachment will also need to save (for later use) the name of each uploaded file as it ended up actually being named at the specified storage location. However, the destination file name (which may have been converted as described in “File Name Considerations”) is not passed back to the PutAttachment function. So, the only way for your PeopleCode program to ensure that it is saving the correct name is to either avoid using special characters in the destination file name or to simulate the conversion process in something like the following example:

&ATTACHUSERFILE = Substitute(&ATTACHUSERFILE, " ", "_"); 
&ATTACHUSERFILE = Substitute(&ATTACHUSERFILE, ";", "_"); 
&ATTACHUSERFILE = Substitute(&ATTACHUSERFILE, "+", "_"); 
&ATTACHUSERFILE = Substitute(&ATTACHUSERFILE, "%", "_"); 
&ATTACHUSERFILE = Substitute(&ATTACHUSERFILE, "&", "_"); 
&ATTACHUSERFILE = Substitute(&ATTACHUSERFILE, "'", "_"); 
&ATTACHUSERFILE = Substitute(&ATTACHUSERFILE, "!", "_"); 
&ATTACHUSERFILE = Substitute(&ATTACHUSERFILE, "@", "_"); 
&ATTACHUSERFILE = Substitute(&ATTACHUSERFILE, "#", "_"); 
&ATTACHUSERFILE = Substitute(&ATTACHUSERFILE, "$", "_");

Note. Unlike the PutAttachment function, the AddAttachment function automatically returns the converted file name for reference and later use. For example, the file name My Resume.doc is returned through the AddAttachment function as My_Resume.doc, with the space converted to an underscore.

See Also

File Name Considerations

Considerations When Using CopyAttachments

CopyAttachments does not modify the contents of any of the associated file reference tables. You must design your application in such a way that using CopyAttachments does not, by itself, require any subsequent changes to the contents of any of the associated file reference tables.

Application Deployment and System Configuration Considerations

This section discusses:

• File attachment functions in an environment with multiple application server domains.

• Configuring the web server to support additional MIME types.

• Restricting the file types that can be uploaded or downloaded.

• Setting up virus scanning.

• Considerations when attaching text files.

• File attachment chunk size.

• Using the Copy File Attachments page.

The topics in this section are of interest primarily to customers deploying file processing applications, and secondarily to application developers.

File Attachment Functions in an Environment with Multiple Application Server Domains

In an environment involving multiple application server domains, a call to one of the PeopleCode file attachment functions must not be passed a parameter designating a file that is located on the file system of a particular application server domain. The problem is that at the time of the call, the application server domain currently in use (as a consequence of load-balancing) might not be the application server domain that has the file in question. In this case, a file-not-found error would result. For example, this may be an issue for a call to PutAttachment, or this might cause a call to GetAttachment to result in the file being downloaded to an unexpected location (the file system of the wrong application server domain) or to fail entirely if the specified destination directory does not exist on the application server domain currently in use. Therefore, the path to the local file must be specified with this in mind by creating directories that can be comparably accessed regardless of which application server domain actually services the request at runtime.

Configuring the Web Server to Support Additional MIME Types

When a browser attempts to open a file attachment, the browser invokes a viewer based on the MIME (Multipurpose Internet Mail Extensions) type sent in the response header from the web server. For example, if the user tried to view an MP3 file, the response header sent to the browser by the web server would indicate the audio/MPEG content type:

HTTP/1.1 200 OK 
Server: Microsoft-IIS/5.0 
Date: Mon, 01 Oct 2001 21:25:51 GMT 
​Content-Type: audio/mpeg 
​Accept-Ranges: bytes 
Last-Modified: Mon, 01 Oct 2001 21:00:26 GMT 
ETag: "78e21918bc4ac11:cc8" 
Content-Length: 60

Notice that the content-type is audio/mpeg. The browser uses this MIME type to determine that the viewer for audio/MPEG is the appropriate application to open this attachment. If the web server did not send this content-type header, the browser would not be able to determine the nature of the file being transmitted, and it would be unable to invoke the correct viewer application. The browser would try to display the file as text/plain, which is often the wrong behavior.

The web server maps file extensions to MIME types through entries in a web.xml configuration file. A copy of web.xml is deployed to each web server instance when it is installed. After a web server instance is created, edit its deployed copy to add any additional MIME types.

The location of the deployment copies varies depending on the web server:

See your web server documentation for the name and location of the master copy of this configuration file.

This file contains definitions similar to the following:

  <mime-mapping> 
    <extension> 
      doc 
    </extension> 
    <mime-type> 
       application/msword 
    </mime-type> 
  </mime-mapping> 
  <mime-mapping> 
    <extension> 
      xls 
    </extension> 
    <mime-type> 
       application/vnd.ms-excel 
    </mime-type> 
  </mime-mapping>

Let's say you want to add a mapping that causes .log files to be interpreted as regular text files. To determine the correct MIME type, check RFC (Request for Comments) documents 2045, 2046, 2047, 2048, and 2077, which discuss internet media types and the internet media type registry.

After checking the RFCs, you determine that the correct MIME type is text/plain. The following is an example of code you would add to the previous section of the configuration file:

  <mime-mapping> 
    <extension> 
      log 
    </extension> 
    <mime-type> 
       text/plain 
    </mime-type> 
  </mime-mapping> 
​

Once you save the file, the .log extension is associated with the content type of text/plain.

Note. You must restart your web server before these changes are recognized.

Note. When trying to view the objects, the extension must exactly match what is set up in the web.xml file. This value is case-sensitive. Therefore, if the PreserveCase parameter has been used when uploading files, it will be necessary to add a MIME type entry for each case-permutation of the file extension in question. If the object view appears garbled, chances are that either the extension is not set up in the web.xml file or there is a case mismatch.

See Also

Documentation for your web server

Restricting the File Types That Can Be Uploaded or Downloaded

You can restrict the file types that can be uploaded to or downloaded from your PeopleSoft system. The file type restrictions apply to the AddAttachment, DetachAttachment, MAddAttachment, and ViewAttachment functions. Allowable or disallowed file extensions are managed through a file extension list and through the FILE_EXT_LIST property of the URL object.

Note. File extension lists cannot be applied to ad hoc URL strings.

The PeopleTools 8.52: System and Server Administration PeopleBook contains detailed information on creating and maintaining file extension lists.

See File Extension List.

Setting Up Virus Scanning

This section discusses:

• Enabling virus scanning.

• Configuring VirusScan.xml.

• Logging virus scans.

• Virus scan errors and return codes.

Virus scanning can be performed on all files uploaded with the AddAttachment function only.

Warning! Virus scanning cannot currently be performed on files uploaded with the MAddAttachment function.

Enabling Virus Scanning

To enable virus scanning, open the file VirusScan.xml and set the value of disableAll to "False". By default, disableAll is "True".

<Providers disableAll="False" logFile="./servers/PIA/logs/VirusScan%u.log">

The location of VirusScan.xml on your system depends on which web server you use.

Oracle WebLogic Server:

PS_HOME/webserv/web_server/applications/peoplesoft/PORTAL.war/WEB-INF/classes/⇒
psft/pt8/virusscan

IBM WebSphere:

PS_HOME/webserv/profile_name/installedApps/app_nameNodeCell/⇒
​app_name.ear/PORTAL.war/WEB-INF/classes/psft/pt8/virusscan

Configuring VirusScan.xml

These tags are mandatory in VirusScan.xml:

psft.pt8.virusscan.provider.
GenericVirusScanProviderImpl

psft.pt8.virusscan.provider.
GenericVirusScanProviderImpl

See PeopleTools 8.52: MultiChannel Framework PeopleBook for complete details on configuring VirusScan.xml.

See Enabling Virus Scanning.

Logging Virus Scans

Detailed logging is configured in the logging.properties file on the web server.

Oracle WebLogic:

PS_HOME/webserv/web_server/applications/peoplesoft/logging.properties

IBM WebSphere:

PS_HOME/webserv/profile_name/installedApps/app_nameNodeCell/app_name.ear/⇒
logging.properties

Set the location of the log file in VirusScan.xml.

<Providers disableAll="False" logFile="./servers/PIA/logs/VirusScan%u.log"> 

The following results are logged with the date and the file name that was scanned:

• CLEAN, INFECTED, and SCANERROR

  The results for these statuses is logged in this form:

  filename = ​result
  ​

  For example:

  finance.xls = INFECTED

• CONNECTERROR and CONFIGERROR

  The results for these statuses is logged in this form:

  Unable to connect to the Scan engine: REASON = ​result
  ​

  For example:

  Unable to connect to the Scan engine: REASON = CONFIGERROR

Virus Scan Errors and Return Codes

If the file is uploaded successfully and no problems are found in the virus scan, AddAttachment returns %Attachment_Succeeded.

If a problem is found, AddAttachment returns one the following return codes:

Considerations When Attaching Text Files

The PeopleCode file attachment functions do not provide text file conversions when files are attached or viewed. In fact, when any file is uploaded, it is always copied to the specified destination byte-for-byte.

Warning! You may encounter problems when a text file is uploaded from one operating system or environment and then later viewed on another. For instance, suppose a text file on a DB2 system is encoded in EBCDIC. A user viewing that file in a Windows environment might see garbled content because the text file viewer is expecting ANSI encoding.

Similar issues can occur when two file systems have different character sets, such as Japanese JIS and Unicode, or different line endings.

It is the developer's responsibility to manage this issue in their environments. A number of text file conversion utilities are available for various platforms.

Some steps you can take to avoid conversion problems include:

• Educate your users.

• Standardize on file formats and encodings.

• Make sure that the user's environment supports the files being transferred.

• Restrict attachments to file types that are known to be compatible across user platforms.

File Attachment Chunk Size

When using a database table as the storage location, the file is automatically “chunked,” or stored, in multiple rows of the database table. The size of each chunk is determined by the Maximum Attachment Chunk Size field on the PeopleTools Options page.

Because each file is chunked, you cannot pull whole files directly from the database. You must use the PeopleCode file attachment functions, which automatically put the data back together into one file for you. Because the chunk size is stored with the file, if you change the system chunk size, you can still retrieve files with different chunk sizes.

See Also

PeopleTools Options

Using the Copy File Attachments Page

The Copy File Attachments page is provided as a way to launch a CopyAttachments operation (select PeopleTools, Utilities, Administration, Copy File Attachments). The CleanAttachments function is also available from this page.

Note. The copying functionality available on this page does not fully exploit the capabilities of the CopyAttachments built-in PeopleCode function. In particular, the page does not permit the end user to specify values for CopyAttachments’ optional parameters. If you want to enable the use of these optional parameters, you must clone and then modify the existing PeopleCode or implement your own PeopleCode to do this.

See Also

CopyAttachments

CleanAttachments

Copy File Attachments

Debugging File Attachment Problems

This debugging section discusses the following:

• Enabling tracing on the web server or application server.

• Problems with transfers to and from FTP sites.

• Attachments with non-ASCII file names.

• Problems uploading files.

• Passing error messages to the end user.

The topics in this section are of interest primarily to customers deploying file processing applications, and secondarily to application developers.

Enabling Tracing on the Web Server or Application Server

This section discusses how to:

• Enable tracing on the web server.

• Enable PeopleCode tracing on the application server.

Enabling Tracing on the Web Server

To enable web server tracing of file attachment processes:

1. Select PeopleTools, Web Profile, Web Profile Configuration, and open the current web profile.

2. Select the Custom Properties page.

3. Add a new row, and enter these values:

   Column	Value
   Property Name	IDDA
   Validation Type	Number
   Property Value	32 (File processing)

4. Set the .level property of the logging.properties file to ALL.

5. Restart the web server.

The log files are written to a directory that depends on the java.util.logging.FileHandler.pattern property of the logging.properties file.

More information on IDDA logging is available in the PeopleTools PeopleBooks.

See Enabling IDDA Logging.

Enabling PeopleCode Tracing on the Application Server

For tracing file attachment issues, set the PeopleCode trace level to 2048 (Statement Tracing, which shows each statement as it's executed). In addition, higher PeopleCode trace settings are recommended whenever CopyAttachments is run. You can enable PeopleCode tracing on the application server in several ways:

• For all client sessions by setting TracePC in Configuration Manager.

• For a specific client session through the Trace PeopleCode page (select PeopleTools, Utilities, Debug, Trace PeopleCode.

Because PeopleCode tracing can generate a lot of output, setting tracing for a specific client session only is recommended.

Application server log files can be found in the PS_CFG_HOME/appserv/domain/LOGS directory.

• The application server log files have names in the form APPSRV_MMDD.LOG (in which MMDD represents the month and date).

• The file transfer log file has a name in the form of FILETRANSFERpid.LOG.

• The PeopleCode trace file has a name of the form, *.tracesql.

See Specifying Trace Settings.

Problems with Transfers to and from FTP Sites

A common reason that a transfer fails is that the FTP server is not accessible from the application server. This error could be due to:

• An incorrect password.

• An incorrect account name.

• An inability of the application server to resolve the FTP server's host name.

• The FTP server is down.

Try to ping the FTP server machine from the application server system, and then try to manually transfer a file to the FTP server machine from the application server.

If the FTP site is on Microsoft Windows, the host name for the system might not be associated with a fixed IP address and might not be resolvable using DNS (Domain Name System). If the application server is on a UNIX machine, the application server can resolve the host name using DNS only—or perhaps using NIS (Network Information System) or an /etc/hosts file. However, the application server will be unable to use Windows mechanisms such as WinBeui or WINS. Therefore, the application server will not be able to convert the host name indicated for the Microsoft Windows file server into an IP address and route to it.

If the file transfer fails, you must resolve the problem by either specifying the numeric IP address in the FTP URL or by putting the host name for the FTP site into DNS, NIS, or the hosts file on your application server so that the name can be resolved.

Typically, the URL used for file attachments has the following format:

ftp://user:pwd@system_name/dir1/subdir

However, if the domain name cannot be resolved with DNS, then use the numeric IP address. The following example assumes system_name has the IP address of 123.123.123.123:

ftp://user:pwd@123.123.123.123/dir1/subdir

Note. Use numeric IP addresses only when absolutely necessary.

Attachments with non-ASCII File Names

To successfully upload an attachment with a file name containing non-ASCII characters (such as Japanese), Oracle recommends running the application server with the locale that supports those specific non-ASCII characters—for example, ja_JP.utf-8.

If the storage location for the attachment is an FTP site or an HTTP repository, Oracle recommends that the storage location also be running in an environment that supports the same language or locale as the file names used. The web server (which serves as an intermediary in the transfer of the file from the browser to the application server and then on to the storage location) can be running either an English environment or a non-ASCII character language environment.

See Also

URL Maintenance

Problems Uploading Files

You cannot use a relative path to specify the file that is to be uploaded; you must use a full path. If users experiences problems in uploading files, ensure that they browse to the file they wish to upload rather than attempting to manually enter the full path name of the file.

This problem can manifest itself differently depending on the browser used. For example, with some browser versions, the PeopleSoft page appears to be in an infinite “Processing” state.

See Also

My Oracle Support, “Troubleshooting Browser Limitations”

Passing Error Messages to the End User

When working with the attachment functions, if you want the end user to be able to view error messages (such as that the file is too large, that the file was not found, that there is no disk space at the storage location, and so on), then you need to write or clone PeopleCode to interpret function return codes and pass error messages back to the user.

As an example, each of the programs in the FILE_ATTACH_WRK derived/work record includes a parameter that sets the message level, but does not translate these into user terminology. The message levels that can be set are:

• 0 – Suppress all messages including errors.

• 1 – Display all messages.

• 2 – Suppress success messages only, but display error messages.

By default, the message level is 0 for each of these programs. The programs are demonstrated on the PeopleTools Test Utilities page.

See Also

FILE_ATTACH_WRK Derived/Work Record

Using the PeopleTools Test Utilities Page