Developing Applications that Use File Attachment Functions

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.

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

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.

    Note: ATTACHSYSFILENAME is a 128-character field.

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

    Note: ATTACHUSERFILE is a 64-character field.

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

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.

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.

See Delivered Record Definitions.

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.

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