理解文件附件函数

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:

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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

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

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.

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.

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