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 records, 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 a file from an end user machine to a specified storage location.

    See AddAttachment.

  • 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 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 records 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 records.

    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. The actual value of the URL is maintained on the URL Maintenance page.

See Also

Understanding File Attachment Storage Locations

Understanding Storage Location URLs

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 browser-to-web server transfer is performed using a standard HTML form construct.

   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 or if the file is 0 bytes.

2. After the file is received at the web server, the file is transferred from the web server to the application server in one-megabyte chunks.

   Note. The one-megabyte transfer size 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 gets re-chunked (as specified by the value of the Maximum Attachment Chunk Size field on the PeopleTools Options page) and then is temporarily stored in a PeopleTools table in the database.

4. Once the entire file is transferred, the application server reassembles the file as a temporary file on the application server's file system and deletes the temporary copy from the PeopleTools table in the database.

5. Then, the application server transfers the file to its ultimate storage location.

   Note. If the storage location is a database record, then the file gets re-chunked (as specified by the value of the Maximum Attachment Chunk Size field) when the file is transferred from the application server to the database.

   See File Attachment Chunk Size.

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 records, FTP sites, and HTTP repositories. Except for the CleanAttachments function, all PeopleCode file attachment functions support all three storage locations. The CleanAttachments function supports only database records 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 record to store the attachments themselves. This target record must include the FILE_ATTDET_SBR subrecord and no other fields.

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

See Application Development Process Overview.

When the storage location is a database record, the URL can be defined in one of two ways:

• A string in the form of:

  record://MYRECORD

  In this case, MYRECORD is the target record.

• A URL identifier in the form of:

  URL.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! Only the FTP protocol supports a URL string in this form. FTPS and SFTP require that a URL identifier be used.

• A URL identifier in the form of:

  URL.URL_ID

When specifying an FTP URL as a string or as a URL identifier, 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://user01:password@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

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.

When the storage location is an HTTP repository, the URL must be defined as a URL identifier in the form of:

URL.URL_ID

Understanding Storage Location URLs

Storage location URLs define both the protocol to be used and the address for a storage location. These URLs can be defined and maintained as URL identifiers, and in limited cases, they can also be specified as a string at run time. Oracle recommends that you always use URL identifiers 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. In addition, by using a URL identifier and the GetUrl function to get the underlying FTP URL, you can mask the FTP user ID and password when necessary.

URL identifiers 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 information in addition to the URL itself. This additional information is defined as URL properties on the associated URL Properties page.

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

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

The PeopleTools 8.51 PeopleBook: System and Server Administration contains detailed information on creating and maintaining URL identifiers.

See URL Maintenance.

Developing Applications that Use File Attachment Functions

This section discusses:

• Application development process overview.

• 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 record 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 this target record; the target record must have no other fields.

   Create a storage location that is unique to your application (that is, do not share storage locations among several 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 identifier that corresponds to your default storage location.

   See Understanding Storage Location URLs.

3. Create a custom record to 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, 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 these fields 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 and to the storage location. Doing so eliminates the need to store the URL string or URL identifier with each file reference.

4. Clone the FILE_ATTACH_WRK record to create a custom 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 use as part of an application running in production unless it has been customized. It is important to create your own PeopleCode programs. Oracle can change the delivered sample PeopleCode in future releases. Any application that directly uses the FILE_ATTACH_WRK record might fail. Customizing your application makes it easier to manage during upgrades and your PeopleCode can be reused in other components that use file attachment functionality.

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

   The custom 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 custom 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 record as a storage location, you must create a custom record to receive the attachments. You must include the FILE_ATTDET_SBR subrecord in your custom 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 custom record that will store references to the attached files. The fields in this subrecord store the system file name and the user file name. No PeopleCode is associated with this subrecord.

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 the 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 a custom record to 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 by 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 the built-in PeopleCode functions.

  • ATTACHSYSFILENAME – Use the ATTACHSYSFILENAME field (along with the ATTACHUSERFILE field) 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), download (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 interactively as a string. By clicking the Attach button, the file is uploaded to the storage location. Once the selected file has been successfully uploaded, buttons appear that allow you to open, download, 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 customize the copied programs to fit your 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.

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, 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.

• 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.

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. 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

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.

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.51 PeopleBook: MultiChannel Framework 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 record 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.

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

PeopleCode trace level 2048 (show each statement as it's executed) is the appropriate level for tracing file attachment issues. 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 from the application server system, and then try to transfer a file to the FTP server 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 you are using a UNIX system and 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 from a locale with a file name in a language that uses a non-ASCII characters, such as Japanese, Oracle recommends running your application server in an environment that supports non-ASCII character languages.

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 on either an English environment or a non-ASCII character language environment.

If your environment does not fully support non-ASCII characters, then the file-processing system will convert file names into names that are fully ASCII strings. At upload time, the new file names will be passed back to the calling PeopleCode program rather than the original names of the files as selected by the end users. This means that it may be more difficult for an end user to later identify the renamed file for further processing, such as selecting and viewing the file.

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 specify the full path to the file to be uploaded.

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 code 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. 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