19 Implement Attachments

The attachment views component can display more detail from the Oracle WebCenter Content repository. Enabling this functionality, however, requires additional configuration of the repository. Since the attachment views component is not dependent on this configuration, you can do it when required.

The Model project must be set up correctly before you can add attachments to your page.

Part of the Model setup involves creating an attachment view link between the business object view object and the attachments view object. When defining this attachment view link, you must select Primary Key values and enter an Attachment Entity Name. This unique name is used to identify all attachments for your business object.

The first time you create an attachment view link for your business object, the unique attachment entity name is stored in the database. If you need to link the same set of attachments to another view object on a different page, reselect the existing attachment entity name when creating the attachment view link.

After creating the attachment view link, you will need to assign a set of categories to your attachment entity. When creating the attachment view link, you can choose to show all of the categories assigned to your entity in your UI, or a subset of these categories. If you do not need to reduce the list of categories that will be displayed in your UI, you can select to "Show All Categories" on the Categories step in the Attachment View Link Wizard. This will make all categories that are assigned to your attachment entity available in your UI. For more information, see How to Create Attachment View Links.

After you have finished setting up your Model project, you must decide how you would like to display the attachments in your page: As an attachment field, as a table of attachments, an attachment column in an applications table, or as an attachment carousel. This design-time setup is performed in your ViewController project. For more information about setting up your ViewController project for attachments, see How to Create an Attachments Field_ Attachments Table_ Attachments Carousel_ or Attachment Views, How to Create an Attachments Column in an Applications Table, and About Displaying Attachments for Multiple Entities in the Same Table.

After adding attachments to your UI page, you must complete the required steps to ensure that the attachments functionality works correctly at runtime. For more information about these setup steps, see What Happens When You Implement Attachments and What Happens at Runtime.

After you have completed all the steps in the wizard by clicking Finish to create your Attachment view link:

• The Attachment view link is created, including generating the Accessor in the source view object.

• All new or changed category information is stored to the FND_DOCUMENT_CATEGORIES and FND_DOCUMENT_CATEGORIES_TL tables.

• A custom property (OAF_ATTACHMENT_CATEGORY) is created on the Attachments view link, which is a list of all the categories that you select in Step 4 of the wizard.

  The custom property stores an empty list when you select the Display All Available Categories checkbox. When this checkbox is not selected, the custom property stores a comma-separated list of categories (using the CATEGORY_NAME from the FND_DOCUMENT_CATEGORIES table) that you manually selected from the list of available categories.

• The AttachmentEntityName transient attribute is created on the Entity view object. Its value is the entity name that you entered in Step 3 of the wizard.

  Note:

  This transient attribute should not be included in your UI.

• New Attachment Entity information is stored to the FND_DOCUMENT_ENTITIES and FND_DOCUMENT_ENTITIES_TL tables.

The WHERE clause that links the Entity view object to the Attachments view object is derived based on the selected entity primary key columns. For example, if the entity primary key for the PO_INVOICES entity is made up of the columns INVOICE_HEADER_ID and INVOICE_LINE_ID then the view link query would be as follows:

where PO_INVOICES is the value that you entered in the Entity Name field in Step 3 of the wizard.

(:Bind_InvoiceHeaderId = PK1_VALUE) AND
(:Bind_InvoiceLineId = PK2_VALUE) AND
(:Bind_AttachmentEntityName = ENTITY_NAME)

(:Bind_Pk1Value = PoInvoiceLines.INVOICE_HEADER_ID) AND
(:Bind_Pk2Value = PoInvoiceLines.INVOICE_LINE_ID) AND
(:Bind_EntityName = PO_INVOICES)

Deleting the business object from the database does not automatically apply to any of its Attachments. Subsequently, if your business functionality calls for the deletion of the business object (as opposed to a programmatic deletion, where the record is flagged as deleted but is kept around for auditing purposes), you also must delete all of its Attachments. Otherwise, these records will continue to persist in the Attachments tables. If another business object for your entity is created with the same primary key values, these Attachments will immediately be attached to the new record.

What you do depends on the method or methods you used to delete the business object in your own functionality. The programmatic method to delete the attachments will be the same. Typically, overriding the remove() method of the business object view object will allow you to programmatically access the Attachments detail collection via the View Link Accessor. When you have access to this collection, you can loop through calling the remove() method of the collection, shown in Example 19-4.

public void remove() {
      Row currRow = this.getCurrentRow();
      RowSet attachedItems = (RowSet) currRow.getAttribute("Attachments1");
      while (attachedItems.hasNext()) {  
        Row currAttachment = attachedItems.next();
        currAttachment.remove();
      }
      super.remove();
 }  

It is necessary to assign one or more attachment categories to your attachment entity.

The "Manage Attachment Categories" setup UI can be used to create and update the relationships between your categories and entities. You can search for a particular attachment category, then search and select the attachment entities to assign to the category. For more information, see About Integrating Attachments Task Flows into . Relationships between categories and entities can also be maintained using the Manage Attachment Entities setup UI.

The Entity-Category relationships are stored in the FND_DOC_CATEGORIES_TO_ENTITIES table. There is a many-to-many relationship between Entities and Categories, allowing one category to be assigned to multiple Entities.

The relationships stored in this table are striped by MODULE_ID for seeding purposes, and the seed data loader can be used to seed this data for your product.

See the " Available Seed Data Loaders" table in Chapter 65 for information about Attachments Seed Data Loaders.

1. Create a page, page segment, or an applications panel that is bound to the attachments-enabled Master Data Collection (your business object data collection).
2. Drag the Detail Data Collection (the Attachments data collection) onto a databound drop target. The Create context menu appears.
3. Select Applications > Attachments to display the Create Attachments dialog, as shown in Figure 19-25.

   Figure 19-25 Create Attachments

   

   Choose Attachments Field, Attachments Table, Attachments Carousel, or Attachment Views. Click OK to display the Edit Taskflow Binding dialog.

   The ConnectionName parameter is automatically set to #(AttachmentsTaskflowListener.connectionName) on the attachmentRepositoryBrowseTaskFow1 taskflow in the page bindings for your page. This parameter is used to derive the connection name of the content server connection to be used when the Document Picker taskflow is used in the Attachments UI at runtime.

4. Click OK. Do not make any changes on the Edit Taskflow Binding dialog.

   Selecting Attachments Field or Attachments Table will add the Attachments component to the page. The mode will be set automatically to link or table. Selecting Attachments Carousel will add the Attachments Carousel component to the page. Selecting Attachment Views will add the Attachment Views component to the page. The selected component will be bound to the Detail Data Collection.

<af:panelLabelAndMessage label="Attachment"
      partialTriggers="btnNext btnPrevious">
  <fnd:attachment mode="link" repositoryMode="true"
    attachmentModel="#{bindings.Attachments1}/>
</af:panelLabelAndMessage>

The following are examples of the generated source code:

<fnd:attachment mode="link" id="a1"
   attachmentModel="#{bindings.AttachmentsIterator}"/>

<fnd:attachment mode="table" id="a1"
   attachmentModel="#{bindings.AttachmentsIterator}"/>

<fnd:AttachmentsCarousel id="ac1"
   attachmentModel="#{bindings.AttachmentsIterator}"/>

<fnd:attachmentView id="aView"
   attachmentModel="#{bindings.AttachmentsIterator}"/>

1. Drag your Master Data Collection (your business object data collection) onto your drop target (Page, Page Segment, or Applications Panel). The Create Context Menu is displayed.
2. Select Create, Applications Table to open the Applications Table wizard, Configure Table Patterns dialog.
3. Select the Attachments option.
4. Click OK. Do not make any changes on the Edit Taskflow Binding dialog.

   An Applications Table is created with an Attachments column located in the rightmost position.

5. Manually add the columnLinkTableModel attribute to the attachments component. This attribute must be set to the value that identifies the Master Data Collection Model and must match the value set for the value property of the af:table component that contains the Attachment column. For example:

   columnLinkTableModel="#{bindings.AuEmployee1.collectionModel}"
   

1. Drag your Detail Data Collection (the Attachments data collection) onto your drop target (af:table within the table facet of the Applications table). The Create Context Menu is displayed.
2. Select Create, Applications, Attachments Column. The Edit Taskflow Binding dialog is displayed.
3. Click OK. Do not make any changes on the Edit Taskflow Binding dialog.
4. Manually add the columnLinkTableModel attribute to the attachments component. This attribute must be set to the value that identifies the Master Data Collection Model and must match the value set for the value property of the af:table component that contains the Attachment column. For example:

   columnLinkTableModel="#{bindings.AuEmployee1.collectionModel}"
   

<af:column sortable="false"
   headerText="#{applcoreBundle.ATTACHMENTS_COLUMN_HEADER}"
   width="200">
<fnd:attachment mode="columnLink"
   attachmentModel="#{bindings['Attachments1']}"
   columnModel="#{row.attachments}"/>
   columnLinkTableModel="#{bindings.AuEmployee1.collectionModel}"/>
</af:column>

To implement your attachments successfully you must set the following required properties:

• usesUpload for a standard JSPX page

• usesUpload on the UI Shell

  Note:

  usesUpload must be set using either of the above methods when uptaking either a taskflow or component that contains the attachments component. Ensure that your uptake document includes this instruction.

  This property serves as a reminder for anyone including Attachments as part of an "object" being provided that the destination JSPX page or UIShell must have the same settings so that the users can upload.

• RefreshCondition for the task flow

Users have the ability to associate a URL, desktop file, repository file or folder, or text with a business object, such as an expense report, contract, or purchase order.

When a user chooses to attach a repository file or folder, they are presented with the Document Picker dialog from which they can select one or more repository files or folders. After a repository file or folder has been attached, the type is displayed as either File or Folder.

The ability for a user to add, update, view, or delete an attachment is programmatically controlled using the addAllowed, updateAllowed, viewAllowed, deleteAllowed, and ReadOnly attributes on the Attachment component.

The ability to control what type of attachments can be added in the Attachments UI is controlled by the following attributes on the Attachment component: fileTypeEnabled, textTypeEnabled, urlTypeEnabled, and attachFolderAllowed.

The type of attachment that is used determines how the attachment is displayed when the user clicks the attachment link. The browser and client configuration determines what desktop application is used to display the attachment. When clicking on the link to access the content of a File or Text type Attachment, the user will be prompted to save the file. For their protection, users should be encouraged not to open files inside the browser.

Repository files are viewed in the same way as desktop files. However, if you click the link in the File Name/URL column in the Attachments table for an attached folder, a browser window/tab opens and displays the list of files and folders within the attached folder.

Page bindings must be manually created to include AttachmentsExtraAttributes and AttachmentsRendition. They are not required for the operation of any of the Attachment components. However, in order to display the "More Information" and "Renditions" sections in the Details pane of the Attachments View component, page bindings are required.

To update page bindings, do the following:

1. Open up the page that contains the Attachment Views component.

2. In the Data Controls section of Oracle JDeveloper, find the Attachments Data Control entry that was used to create the Attachment Views component.

3. Expand the Attachments entry, drag the AttachmentsExtraAttribute child onto the page, and select a read-only table with all columns.

4. Remove the af:table just created from the page.

5. In the Data Controls section, drag the AttachmentsRendition child onto the page and choose a Read-Only table with all columns.

6. Remove the af:table just created from the page.

7. In the Data Controls, drag the AttachedDocumentsDFF child onto the page and choose Applications > Oracle Descriptive Flexfield.

8. Remove the fnd:descriptiveFlexfield just created from the page.

9. Open the page definition of the page and go to the source. Add the following source inside the tree node for the Attachments definition:

   <Properties>
     <CustomProperties>
       <Property Name="ExtraAttributes" Value="<ExtraAttributesId>" />
       <Property Name="Renditions" Value="RenditionTreeId" />
       <Property Name="DFF" Value="<DffIteratorId>" />
     </CustomProperties>
   </Properties>
   

10. Replace ExtraAttributesId with the Id of the tree node for the Attachments extra attribute that was created in Step 3.

11. Replace RenditionTreeId with the Id of the tree node for the Attachments Rendition that was created in Step 5.

12. Replace <DffIteratorId> with the Id of the iterator node for the Attachments DFF that was created in step 7.

13. Save the page definition.

The Attachments View component will detect that these properties have been configured and will start using them.

This section provides details on how to configure your data model to display attachments for two or more business objects. These instructions assume that you have already created the Attachments view link between one business object view object and the Attachments view object, as described in How to Create Attachment View Links.

Support has been included for using Attachments in pages built for Oracle Fusion Applications User Simplified Experience (FUSE). When using Attachments in a FUSE page, you will need to adhere to the following rules in order to implement a FUSE compliant design:

The following properties are not used when in FUSE mode:

• ApprovalEnabled

• DeleteMessage

• UpdateAllowed

• UpdateEnabled

• InsertMultiple

• ShowCategory

• SecondaryToolbarRendered

• AddAllowed

• AddEnabled

• ActionEntity

• DeleteAllowed

• DeleteEnabled

• UpdateCategoryList

The following is example source code for a FUSE Attachment:

<fnd:attachment mode="link" 
   fuse="true" id="a1Fuse"
   AttachmentModel="#{bindings.Attachments1}
   textTypeEnabled="false"
   confirmDelete="false"
   DefaultCategory="MISC"/>

Methods have been provided for programmatically creating the File, Text and URL types. There is also an additional type, ManagedURL.

A managed URL attachment is intended for use with pages that are hosted on internal servers that are administered by Topology Manager. Since changes made by the Topology Manager might invalidate the scheme://domain:port portion of a URL resulting in a dead link, support for this variation of the URL type was created. To the end-user, this link will still appear as a URL. Internally, however, this Attachment will be created with a different Attachment type, TMURI.

Methods for attaching files that have been uploaded from a third-party application are also available. In this case, the developer has gotten the required information returned from uploading the file to complete the attachment. Where the file is already attached to another record, using the copyAttachments method to attach the file to the require record is recommended.

Table 19-2 summarizes the available methods for Attachments APIs.

When end-user ordering has been enabled in the view for the attachment component, any programmatically created rows for the entity must have their sequence value set as well. Calling the method setAttachmentSequence, passing in the newly created row, will set the correct sequence value.

All methods are overloaded, providing two options for creating a new Attachment. The first option creates the new Attachment row from the Attachment collection linked to the parent view object. This is illustrated in Example 19-16.

The second option is to allow the method to create the Attachment row at the same time, as shown in Example 19-17.

If you use the second option, it is essential for the Entity and Primary Key values to be set programmatically as well. Getting any of these values wrong may result in the Attachment being lost or assigned to the wrong record. While the second type looks like less work it would be a better practice to use the first approach for creating new Attachments.

It will also be necessary to set the Category value for the new row before committing the transaction as shown in both examples. The value expected is the CATEGORY_NAME from the FND_DOCUMENT_CATEGORIES table. Since the value is not validated, use the following method to ensure that you are providing a category value that is mapped to your Document Entity Name:

newAttachment.setCategoryName("MISC");    

// Retrieve the department for adding the new Attachment row to
ViewObject vo = am.findViewObject("FndDemoDept1");
vo.setWhereClause("DEPT_NUM = :deptNum");
vo.defineNamedWhereClauseParam("deptNum", null, null);
vo.setNamedWhereClauseParam("deptNum", departmentNumber);
vo.executeQuery();                                                                  
Row currDepartment = vo.next();
// Retrieve the Attachments Collection  
RowSet attachments = (RowSet) currDepartment.getAttribute("Attachments");       
// Create new Attachment Row
AttachmentsVORowImpl newAttachment = (AttachmentsVORowImpl) 
  attachments.createRow(); 
// Add Managed Link        
attachmentServiceAMImpl.attachManagedUrl(newAttachment, 
  textEntAppShortName, textURI);
// Set the Category Value
newAttachment.setCategoryName("MISC");    

// Add Managed Link        
newAttachment = attachmentServiceAMImpl.attachTopologyManagedUrl(textEntAppShortName, textURI);
newAttachment.setEntityName("FND_DEMO_DEPT");
newAttachment.setPk1Value(departmentNumber);         
// Set the Category Value
newAttachment.setCategoryName("MISC");    

The InputStream and OutputStream methods have been supplied for retrieving Attachment types of FILE or TEXT. The URL or TMURI types are not stored on the content server. Their URL values can be retrieved with the getAttachmentUrl() method, which is described in Table 19-3.

Two utility methods are provided enable a list of Attachments to be copied to another record as identified by the unique combination of the Document Entity Name and Primary Key values. The list is constructed of the Attachment rows from one or more other records.

The copyAttachments utility does not duplicate the files on the content server. When the method is complete, the destination record will point to the same files in the content server as the source record.

The duplicateAttachments utility does duplicate the files on the content server. When the method is complete, the destination record will point to the new content on the content server.

When constructing the list of Attachments, consider whether Category Data Security has been implemented (see About Attachment Category Data Security). If implemented, the list of Attachments available may not be the full list depending on the permissions granted to the current user. If the full list is required it will be necessary to bypass Category Data Security by setting the dataSecurityDisabled flag on AttachmentsVOImpl to true, as shown in Example 19-18.

AttachmentsVOImpl attachmentVO = attachmentServiceAMImpl.getAttachments1();
attachmentVO.setDataSecurityDisabled(true);
// assign where clause conditions
attachmentVO.executeQuery;

Generally, the Attachments component handles resources effectively; there is normally no need to manage resources programatically. However, if the Attachments component is holding a large number of HTTP sessions open for a long time, you might need to dispose of the unnecessary sessions. You can do this by calling the dispose method, which is described in Table 19-5.

By default, the Attachment files on the Content Server are locked down. When a request is made using the Attachments functionality, it includes additional parameters that are processed on the Content Server. The user's privileges are temporarily elevated so that the request can be performed.

Methods that support attaching files to business-object records using third-party applications are described in the table that follows.

The process to create an Attachment using a third-party application is the following:

1. The third-party application makes a request to the business object to retrieve a signature for uploading a file with a provided title to a record in the business object.

2. The business object evaluates whether the requesting user is allowed to attach a file to the record.

3. The business object makes a call to the signUpload method, which returns an array of name value pairs that make up the signature.

4. The business object returns the array to the third-party application.

5. The third-party application creates the request to create the new file. The request includes the array of name value pairs returned from the business object.

6. The third-party application sends the request to the Content Server.

7. The response from the Content Server includes the document ID and version number of the new document.

8. The third-party application makes a request to the business object to create a new Attachment for the record using the new document ID and version number.

9. The business object calls the attachRepositoryFile method for its record to create the new Attachment record.

Since the attachRepositoryFile method validates that the user making the request to create the attachment is the same user that created the file on the Content Server, all of the steps in this process must be performed by the same user.

The service call made to create the file on the Content Server (Step 5) is the CHECKIN_UNIVERSAL service. For more information, see the Services Reference for Oracle WebCenter Content.

When setting parameters, you must use the guidelines described in the table that follows.

PL/SQL equivalents exist for some of the Java methods described in About Creating New Attachment Types and About Using Attachment Utilities. These PL/SQL operations appear in the following table.

PROCEDURE ATTACH_MANAGED_URL (
  X_ENTITY_NAME in VARCHAR2,
  X_PK1_VALUE in VARCHAR2, 
  X_PK2_VALUE in VARCHAR2 DEFAULT NULL,
  X_PK3_VALUE in VARCHAR2 DEFAULT NULL,
  X_PK4_VALUE in VARCHAR2 DEFAULT NULL,
  X_PK5_VALUE in VARCHAR2 DEFAULT NULL,
  X_CATEGORY_NAME in VARCHAR2,
  X_ENT_APP_SHORT_NAME in VARCHAR2,
  X_URI in VARCHAR2,
  X_TITLE in VARCHAR2 DEFAULT NULL,
  X_DESCRIPTION in VARCHAR2 DEFAULT NULL );

PROCEDURE ATTACH_URL (
  X_ENTITY_NAME in VARCHAR2, 
  X_PK1_VALUE in VARCHAR2, 
  X_PK2_VALUE in VARCHAR2 DEFAULT NULL, 
  X_PK3_VALUE in VARCHAR2 DEFAULT NULL, 
  X_PK4_VALUE in VARCHAR2 DEFAULT NULL, 
  X_PK5_VALUE in VARCHAR2 DEFAULT NULL, 
  X_CATEGORY_NAME in VARCHAR2, 
  X_URL in VARCHAR2,
  X_TITLE in VARCHAR2 DEFAULT NULL,
  X_DESCRIPTION in VARCHAR2 DEFAULT NULL );

PROCEDURE COPY_ATTACHMENTS (
  X_SRC_ENTITY_NAME in VARCHAR2, 
  X_SRC_PK1_VALUE in VARCHAR2, 
  X_SRC_PK2_VALUE in VARCHAR2 DEFAULT NULL, 
  X_SRC_PK3_VALUE in VARCHAR2 DEFAULT NULL, 
  X_SRC_PK4_VALUE in VARCHAR2 DEFAULT NULL, 
  X_SRC_PK5_VALUE in VARCHAR2 DEFAULT NULL, 
  X_SRC_CATEGORY_NAME in VARCHAR2 DEFAULT NULL,
  X_DST_ENTITY_NAME in VARCHAR2, 
  X_DST_PK1_VALUE in VARCHAR2, 
  X_DST_PK2_VALUE in VARCHAR2 DEFAULT NULL, 
  X_DST_PK3_VALUE in VARCHAR2 DEFAULT NULL, 
  X_DST_PK4_VALUE in VARCHAR2 DEFAULT NULL, 
  X_DST_PK5_VALUE in VARCHAR2 DEFAULT NULL,
  X_DST_CATEGORY_NAME in VARCHAR2 DEFAULT NULL );

PROCEDURE COPY_ATTACHMENT (
  X_ATTACHED_DOCUMENT_ID in VARCHAR2, 
  X_ENTITY_NAME in VARCHAR2, 
  X_PK1_VALUE in VARCHAR2, 
  X_PK2_VALUE in VARCHAR2 DEFAULT NULL, 
  X_PK3_VALUE in VARCHAR2 DEFAULT NULL, 
  X_PK4_VALUE in VARCHAR2 DEFAULT NULL, 
  X_PK5_VALUE in VARCHAR2 DEFAULT NULL, 
  X_CATEGORY_NAME in VARCHAR2 DEFAULT NULL );

PROCEDURE DELETE_ATTACHMENT (
  X_ATTACHED_DOCUMENT_ID in FND_ATTACHED_DOCUMENTS.ATTACHED_DOCUMENT_ID%TYPE );

PROCEDURE DELETE_ATTACHMENTS (
   X_ENTITY_NAME in FND_ATTACHED_DOCUMENTS.ENTITY_NAME%TYPE,
   X_PK1_VALUE in FND_ATTACHED_DOCUMENTS.PK1_VALUE%TYPE,
   X_PK2_VALUE in FND_ATTACHED_DOCUMENTS.PK2_VALUE%TYPE DEFAULT NULL,
   X_PK3_VALUE in FND_ATTACHED_DOCUMENTS.PK3_VALUE%TYPE DEFAULT NULL,
   X_PK4_VALUE in FND_ATTACHED_DOCUMENTS.PK4_VALUE%TYPE DEFAULT NULL,
   X_PK5_VALUE in FND_ATTACHED_DOCUMENTS.PK5_VALUE%TYPE DEFAULT NULL );

A debugging utility is also included. When enabled, messages are written to the console. This feature is not enabled by default. At runtime the same messages will be written as log messages if logging is set to FINEST for the applcore.db.plsql.attachments.FND_ATTACHMENTS module.

To begin writing log messages to the console, use the PROCEDURE START_DEBUG command.

To stop writing log messages to the console, use the PROCEDURE STOP_DEBUG command.

Example 19-19 displays sample code for implementing Attachments with PL/SQL with debugging enabled.

SET SERVEROUTPUT ON;
DECLARE
  BAD_ENTITY_NAME_EXCEPTION EXCEPTION;
  PRAGMA EXCEPTION_INIT(BAD_ENTITY_NAME_EXCEPTION, -20001);
  P_ENTITY_NAME VARCHAR2(40)  := 'FND_DEMO_DEPT1';
  P_PK1_VALUE   VARCHAR2(150) := '10';
BEGIN
  BEGIN
  FND_ATTACHMENTS.START_DEBUG;
  FND_ATTACHMENTS.ATTACH_URL (P_ENTITY_NAME,
             P_PK1_VALUE, NULL, NULL, NULL, NULL,
             'MISC',
             'http://www.oracle.com', 'Oracle Corportation',
             NULL);
  FND_ATTACHMENTS.END_DEBUG;
  EXCEPTION
    WHEN BAD_ENTITY_NAME_EXCEPTION THEN   
        DBMS_OUTPUT.PUT_LINE ('The entity name supplied, ' || P_ENTITY_NAME || ', is not a registered document entity.');      
  END;
END;

Four facets (placeholders) are provided on the attachments component for product teams to add toolbar buttons to the toolbar and actions to the Action menu of the attachments table.

The facet tableAppsTableSecondaryToolbar is provided to add toolbar buttons to the Attachments Table toolbar.

The facet linkAppsTableSecondaryToolbar is provided for Link mode.

The facet tableAdditionalActionItems is provided to add action items to the Action menu in the attachments table menus.

The facet linkAdditionalActionItems is provided for Link mode.

Facets are provided on the Attachment Views component to add custom actions.

The following facets are provided:

• appsTableSecondaryToolbar: adds toolbar buttons to the Attachment Views toolbar. Three buttons, Sel, All, and One, are shown in the following figure.

• additionalActionItems : adds action items to the Action menu in the Attachment Views menu. Five menu options, Show Selected Items, Show All Items, Show One Item, Selected Row Count, and All Row Count, are shown in the following figure.

Figure 19-26 Custom Actions and Facets

You can also use facets inline for adding icons or action items. These facets are incorporated into the actions section of the attachment, as shown in the previous figure. There is no central facet for the inline facets. As Oracle Application Development Framework rules do not allow this type of sharing, you must add each icon and item that must be identical for each view. This provides the flexibility for icons or actions to change from view to view for any implementation.

The rendering of the facets are controlled with properties. By default, the facets are not rendered.

Approval functions are added to the Attachments component using the Custom Actions feature, which is documented in the previous section of this chapter.

The approvalEnabled property on the Attachments component can be used to control whether the Status column (from the FND_DOCUMENTS_TL table) is displayed in the Attachments Table. This column indicates the status of the attachment relationship between the business object and the file, not the status of the file in the content repository.

Product teams are responsible for programmatically setting the status as necessary, but are required to set this value using a lookup code provided in the FND_ATTACHMENT_STATUSES lookup. The following table has the full list of valid values found in this lookup table. (Null is also a valid value):

Redlining is a function that shows the changes to an attachment from one version of the parent record to another. It gets its name from the format applied to the attachments that were deleted between the versions.

Redlining requires the following:

• Your business object must be tracking different versions of the same record

• There can be only one current record. All previous versions of the record are no longer editable.

At runtime, attachment views compare the attachments of the current record with that of its nominated predecessor.

• New attachments have their line prefixed with the word "Added". The Title, Description, and Category fields are formatted in green.

• Modified attachments have their line prefixed with the word "Edited". The Title, Description, and Category fields are formatted in blue. Previous values are formatted in red with a strikethrough.

• Deleted attachments have their line prefixed with the word "Removed". The Title, Description, and Category fields are formatted in red with a strikethrough. Deleted Attachments cannot be modified.

• Attachments that are unchanged have no prefix. The Title field displays in blue text.

The following figure shows an example of redlining.

Figure 19-27 Attachment Redlining

Many product teams define data security on their business objects. This data security controls which instances of that business object each user can access. Oracle Fusion attachments reuses this data security when users try to access documents directly, either via a URL or via the Content Server user interface, to ensure that users can only access files that are attached to the business object instances that they have permission to access. This security is important for controlling access to attached files when accessed directly.

Attachments can be secured using attachments categories. This security determines which attachments a user has access to, and what actions they can perform on that attachment, based on the Category that is assigned to it. Uptaking this security is not a mandatory requirement for product teams.

Before uptaking category data security, ensure you have assigned one or more categories to the attachment entity defined for your business object. For more information, see About Assigning Categories to the Attachment Entity.

To incorporate category data security, you need to seed data security for your attachment categories to control which roles have access to each of the categories.

The following seed data has been provided and must be used when you set up category data security:

• "FND_DOCUMENT_CATEGORIES": The seeded database resource for attachment categories data security

• Three actions (form functions) seeded for attachments. These are listed in Table 19-13.

  Table 19-13 Actions Seeded for Attachments

  Action	FUNCTION_NAME	USER_FUNCTION_NAME
  Seeded Read Action	FND_READ_APPLICATION_ATTACHMENT_DATA	Read Application Attachment
  Seeded Update Action	FND_UPDATE_APPLICATION_ATTACHMENT_DATA	Update Application Attachment
  Seeded Delete Action	FND_DELETE_APPLICATION_ATTACHMENT_DATA	Delete Application Attachment

File sharing impacts the way in which your files are secured. Files are stored on the Content Server as either Shared or Not Shared. Users can choose which option to use when they attach files to their business objects. For more, see About Using Attachments File-Level Security.

Shared files are files that are stored in virtual folders within the Content Server and are available to all attachments users. An attachments user is any user who has been assigned the "AttachmentsUser" role. Shared files are exempt from data security.

Unshared files are only available to those users who have access to the file via data security. Therefore, if an Oracle Fusion Applications user has privileges to access to an attachment through a business object instance and they have privileges to access attachments with a particular category, then they have access to the file in the Content Server.

Users are defined on a single Lightweight Directory Access Protocol (LDAP) server. Each of these users can log in to both Oracle Fusion Applications and Oracle Content Server using the same username and password. Users will be given appropriate privileges to each system based on their assigned roles.

Most complex file formats include scripting support to assist users with automating common tasks. This has led to the rise of Cross Site Scripting (XSS attacks, where attackers gain access by including scripts in a file that an unsuspecting user then opens. The challenge, then, is how to recognize and balance the need for users to be able to include automation within their files with the need to prevent malicious scripts inflicting damage to the site.

When opening a file, the default Attachments behavior is to prompt the user to download. This removes native-browser file types from being opened in the session context. It also gives the user more control over when to open the file and, in the case of where the file is suspect, which viewer to use.

The new "Manage Attachment File Formats" page provides a site with additional options for managing the behavior of Attachments based on the file format. Since all file formats are downloaded by default, no file formats are shipped. Sites can use the management page to add file formats, identified by their mime type, either by entering their mime-type directly or by using the option to supply a sample file to source the mime-type. See About Integrating Attachments Task Flows into for more information about task flows.

File formats are set to have a state of either Deny, Download, or Open. If you do not want a file format in use on your site, you would add and set a file format to the Deny state using the management page. Subsequently, any attempt to upload a file of that type will be rejected. Any existing files of that file type will still appear in the Attachments UI, but they cannot be downloaded. Instead, an explanatory message will appear when clicking on the file link.

Setting the state to Open will open any file of a specific format when a link is clicked. Clicking on the link for these files will open based on the browser's settings.

If a file format is in a state of flux, setting the state of that file format to Download will revert it to its default behavior. This eliminates the need of having to delete the file format and re-add at a later time.

Files whose file types are not on the Open state list can still be treated individually as Open when uploaded by users who have been granted the FND_Attachment_File_Trusted_Status (ADFMethodResourceType) permission with the Invoke action. A user with this permission is able to verify that the contents of the file can be opened safely.

Software as a Service (SaaS) support has been added for Oracle Fusion attachments to ensure that the attachments belonging to organizations using the same environment are all kept completely separate to each other.

With Oracle Fusion Applications attachments, users have the ability to set attachments to be either Shared or Not Shared using the Shared option, as shown in Figure 19-28.

Figure 19-28 Attachment Table with Shared Column

The Shared column is only shown in the Attachments table when the repositoryMode property is set to true. The default state for this option is Not Shared for both Text and File type attachments.

All repository File or Folder attachments are shared by default. This is because only shared files are visible in the Document Picker, which is used to select the Repository Files or Folders.

If the user hovers the mouse pointer over the Shared check box, the following hint displays: Checking this box will make this file available to other users.

If the user attempts to change a File type attachment from Shared to Not Shared, the system checks to see if the file is attached to any other business object instances. If the file is attached to other business object instances, the following message is displayed and the file attachment remains shared: This change cannot be made as this file is attached to other business objects.

Users have the ability to update attachments within the Attachments table or popup.

As well as being able to update the category, title, and description of an attachment, users can update existing URL and Text attachments and replace the file of existing File attachments with a new version of the file.

Icon	Function	File	Property
	Check Out	versioncheckout_ena.png	repositoryMode = true
	Check In	versioncheckin_ena.png	repositoryMode = true
	Cancel Check Out	versionrollback_ena.png	repositoryMode = true

The updateAllowed and repositoryMode properties on the Attachments component, and the Checked Out status of the Content Repository files, control how the update functionality works for a particular user.

1. Highlight the File attachment in the Attachments table. Click the Check Out button located on the toolbar.

   The file is immediately checked out in the Content Repository. The Checked Out By column is updated to show your user name.

   Tip:

   Clicking the Cancel Check Out button cancels the check out without making any updates to the file. The check out is cancelled immediately in the Content Repository.

2. Go to your local file system and make the necessary updates to this file.
3. Return to the Attachments table and highlight the checked out file. Click the Check In button located on the toolbar to open the Check In File dialog, as shown in Figure 19-31.

   Figure 19-31 Check In File Dialog

   
4. Click Browse to browse your local file system. Select the updated file that you want to upload.
5. Click OK to save your changes and close the dialog.

   The selected file is uploaded to the content server. The Checked Out By column is cleared.

6. Click Save on the Attachments Table page to commit your transaction.

   Tip:

   If you cancel the entire transaction, the checked out status returns to the state that it was in before the transaction took place.