Skip Headers
Oracle® Fusion Applications Developer's Guide
11g Release 1 (11.1.1.5)
Part Number E15524-01
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
View PDF

18 Implementing Attachments

This chapter provides guidelines for implementing attachments at design time in a quick and simple manner using Oracle Fusion Middleware components.

This chapter includes the following sections:

For general information about Fusion Middleware user interface (UI) components, see:

18.1 Introduction to Attachments

The Attachment component provides a declarative programming mechanism for you to add attachments to the user interface (UI) pages that you create for Fusion web applications. Once added to a UI page, the component gives users 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. The component can be displayed in a UI page in any of the following ways:

18.2 Creating Attachments

This section provides information about creating attachments and describes how to set up your model project for attachments, how to create an attachment field or an attachments table, and an attachments column in an Applications table. Also included is how to set up required properties, as well as information about what happens when you implement attachments and what happens at runtime.

Before you begin:

  1. Add the Applications Core (Attachments Model) library to your Model project:

  2. After adding the library to your model, navigate to Application Navigator >Application Resources >Descriptors >META-INF and add the following xml snippet to your jazn-data.xml file:

    Example 18-1 Snippet for jazn-data.xml File

    <grant>
   <grantee>
      <codesource>
       <url>file:${atgpf.oracle.home}/atgpf/modules/oracle.applcore.attachments_
       11.1.1/Attachments-Model.jar</url>
      </codesource>
   </grantee>
   <permissions>
     <permission>
       <class>oracle.security.jps.service.credstore
         .CredentialAccessPermission</class>
       <name>context=SYSTEM,mapName=oracle.wsm.security,
         keyName=keystore-csf-key</name>
       <actions>read</actions>
     </permission>
     <permission>
       <class>oracle.security.jps.service.credstore
         .CredentialAccessPermission</class>
       <name>context=SYSTEM,mapName=oracle.wsm.security,
             keyName=enc-csf-key</name>
         <actions>read</actions>
      </permission>
   </permissions>
</grant>

    Note:

    Be aware that the URLs and <class> entries cannot contain any spaces or line breaks.

  3. Create a Content Repository connection in JDeveloper.

    Notes:

    Attachments can support multiple Content servers.

    Attachments stores the name of the Content Repository connection used when creating a new attachment. This value is then used when retrieving the attachments. It is important to co-ordinate the naming and registration of Content Repository connections. So that the Attachments code can connect to the correct server to retrieve the requested file.

    Developers need to create a Content Repository connection with the name "FusionAppsContentRepository". This connection should used jaxws as the socket type and Identity Propgagtion for Authentication.

    For information about how to create a Content Repository connection in JDeveloper, see Section 53.1, "Creating a Content Repository Connection".

    For additional information see the "Integrating Content" chapter of the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter.

  4. Log onto the Content Repository and confirm that the following has been created:

    • Attachments folder under the Contribution Folders folder

    • Attachments security group used for unshared attachments

    • SharedAttachments security group used for shared attachments

    • AttachmentsUser role with no permissions set

    • AttachmentsRead user role with read (R) permission to the Attachments security group for unshared attachments

    • AttachmentsWrite user role with write (W) permission to the Attachments security group for unshared attachments

    • AttachmentsDelete user role with delete (D) permission to the Attachments security group for unshared attachments

    • AttachmentsAdmin user role with read, write, delete, and admin (RWDA) permissions to the Attachments security group for unshared attachments

    • SharedAttachmentsWrite user role with write (W) permission to the SharedAttachments security group - for shared attachments

    • SharedAttachmentsDelete user role with delete (D) permission to the SharedAttachments security group - for shared attachments

    • SharedAttachmentsAdmin user role with read, write, delete, and admin (RWDA) permissions to the SharedAttachments security group - for shared attachments.

    Note:

    This setup is required for Attachments to function correctly. You must log in to the Content Server as a user with System Administrator privileges in order to see the above information. If you cannot see these details in your Content Server, please contact your system administrator to ensure that they have enabled the FusionAppsAttachments component in the Content Server. For more information, see "Internal Security: Security Groups, Roles, and Permissions " in Oracle Universal Content Management: Managing Security and User Access, 10g Release 3 (10.1.3.3.1).

18.2.1 How to Set Up Your Model Project for Attachments

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 Section 18.2.2, "How to Create Attachment View Links."

Once 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, or as an attachment column in an applications table. This design-time setup is performed in your ViewController project. For more information about setting up your ViewController project for attachments, see Section 18.2.5, "How to Create an Attachments Field or an Attachments Table," Section 18.2.7, "How to Create an Attachments Column in an Applications Table," and Section 18.3, "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 Section 18.2.6, "What Happens When You Implement Attachments" and Section 18.2.9, "What Happens at Runtime."

18.2.2 How to Create Attachment View Links

Attachment view links are used to establish master-detail relationships between your view objects and the attachments view object. Attachment view links are created using the Attachment View Link wizard.

To create an attachment view link:

  1. In JDeveloper, choose Application Navigator > Model Project. Right-click and choose New from the menu to open the New Gallery.

  2. Choose the Business Tier > ADF Business Components category. Select the Attachment View Link item, as shown in Figure 18-4.

    Figure 18-4 New Gallery Dialog

    New Gallery dialog

  3. Click OK to access Step 1 of the Create Attachment View Link wizard, as shown in Figure 18-5.

  4. Complete the following information:

    1. Select the name of the application that your view object belongs to.

    2. Select the package where the attachment view link will reside.

    3. Enter a unique name for the attachment view link.

    Figure 18-5 Create Attachment View Link Wizard — Name (Step 1)

    Create Attachment View Link - Step 1

  5. Click Next to access Step 2. The View Object dialog appears, as shown in Figure 18-6.

  6. Enter the name for the view link accessor that will be added to the data control of selected view object. Then, from the Available column, select the view object that you want to create attachments for.

    Tip:

    There is no need for you to select a destination view object because the Attachment view link always uses the Attachments view object as the destination view object.

    Figure 18-6 Create Attachment View Link Wizard — View Object (Step 2)

    Create Attachment View Link - Step 2

  7. Click Next to access Step 3. The Attachment Entity dialog appears, as shown in Figure 18-7. The Attachment Entity is used to uniquely identify your business object.

    Figure 18-7 Create Attachment View Link Wizard — Attachment Entity (Step 3)

    Create Attachment View Link - Attachment Entity.

  8. Complete the following information:

    Use Existing Attachment Entity: When checked, the Available / Selected columns are automatically populated with the stored primary key values for the selected entity. When unchecked, the new entity is created in the FND_DOCUMENT_ENTITIES and FND_DOCUMENT_ENTITIES_TL tables.

    Entity Name: Enter a unique name for the entity you are adding attachments to.

    Note:

    The entity name is used to map a business object to its attachments.

    Available / Selected: Select only those columns that make up the primary key of the entity object by shuttling them from the Available column to the Selected column.

  9. Click Next to access Step 4. The Categories dialog appears, as shown in Figure 18-8. (The Display All Available Categories checkbox is not selected when you first enter this page.)

    Choose the categories that will be made available to the user in the Attachments runtime UI. The categories you select here must be assigned to your attachment entity. If they are not, they will not be visible in your UI.

    Categories that you create using this wizard are inserted into the FND_DOCUMENT_CATEGORIES and FND_DOCUMENT_CATEGORIES_TL tables against the Application that you selected in Step 1 of the Attachment View Link wizard. Categories that you edit are updated in the FND_DOCUMENT_CATEGORIES and FND_DOCUMENT_CATEGORIES_TL tables.

    Notes:

    • You can only add, edit or delete categories for the Application that you selected in Step 1 of the Attachment View Link wizard.

    • The categories that you create here are not assigned automatically to their attachment entity. You must ensure that all categories you select in Step 9 are assigned to their Attachment Entity. For more information, see Section 18.2.4, "How to Assign Categories to the Attachment Entity."

    Figure 18-8 Create Attachment View Link — Categories (Step 4)

    Create Attachment View Link - Categories

    Select the categories to be made available for this entity in the runtime UI.

    Note:

    Use the Add, Edit, and Delete buttons to add, edit, or delete existing categories for the Application that you selected in Step 1. You are not able to edit or delete the seeded Miscellaneous FND category.

    Tip:

    The end-user display name for the Category (USER_NAME from the FND_DOCUMENT_CATEGORIES_TL table) is shown in the shuttle.

    Select Display All Available Categories to show all categories that are assigned to your attachment entity.

    When you select Display All Available Categories, all other fields are automatically removed from the dialog. You will no longer see a list of categories and therefore, you will not be able to add, edit, or delete them. This selection, however, does not override the document category to entity mapping.

    You should select this option if you want Categories, assigned to your attachment entity in the future, to appear in the Categories dropdown list at runtime. Selecting this option will ensure that customers can create and use their own Categories in your UI with minimal effort.

    Deselect the Display All Available Categories checkbox to select a subset of categories that are used to further restrict the list of Attachments returned in the UI. Only the Attachments that are assigned to the selected categories will be retrieved in the UI. To select the required categories, highlight them in the Available column and shuttle them over to the Selected column.

    Note:

    If you did not select the Display All Available Categories checkbox, you must select at least one category before proceeding to the final step in the wizard.

    The selected list of categories will be stored as a custom property on the newly created attachment view link. The value will consist of a concatenated string of values. All the selected categories are concatenated in a comma-separated list.

    Note:

    It is recommended that you choose the Display All Available Categories option to allow for customization of the Category list without code changes. Additionally, please be aware that the list of available categories, and the list of Attachments displayed can be further controlled using Category data security. For more information, see Section 18.7.1, "Attachment Category Data Security."

  10. Click Next to access the Application Module page. The Application Module dialog appears, as shown in Figure 18-9. Select Application Module to create a new instance of the view object that you selected on the View Object page, and create an instance of the attachments view object as a child of the new instance.

    Figure 18-9 Create Attachment View Link — Application Module (Step 5)

    Create Attachment View Link — Application Module (Step 5)

  11. Click Next to access the Summary page, which is shown in Figure 18-10. Review your selections and click Finish to create your attachment view link.

    Figure 18-10 Create Attachment View Link — Summary (Step 6)

    Create Attachment View Link — Summary (Step 6)

  12. If you chose to keep the Application Module option unselected in Step 10, you need to add your newly created attachments view link to your application module data model as follows:

    1. Choose Application Navigator > AM name. Right-click and choose to open the application module in the editor.

    2. Choose Data Model from the list of categories to open the Data Model Components dialog.

    3. Select the newly created Attachment View Link located in the left column and select the view object that you created the view link for in the right column. Shuttle the Attachment View Link over to the right column.

    4. Save your changes.

18.2.3 What Happens When You Create an Attachment View Link

Once 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:

Example 18-2 Source WHERE Clause

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

Example 18-3 Destination WHERE Clause

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

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

18.2.4 How to Assign Categories to the Attachment Entity

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 Section 18.6, "Integrating Attachments Task Flows into Oracle Fusion Functional Setup Manager." 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.

Note:

It is important to ensure that you seed your attachment entities and attachment categories before you seed the data in the FND_DOC_CATEGORIES_TO_ENTITIES table when extracting and uploading the data.

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

18.2.5 How to Create an Attachments Field or an Attachments Table

This section describes how to create an Attachments field or table.

To create an Attachments field or an Attachments table:

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

    Figure 18-11 Create Attachments

    Create Attachments

    Choose either Attachment Field or Attachment Table. 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.

    Based on the selection that you made in Step 3, either an Attachment Field or an Attachment Table is created and bound to the Detail Data Collection. The mode attribute is automatically set to link or table on the Attachment Component.

When using attachments in link mode, the Attachment component must be displayed inside a panelLabelAndMessage component and a partialTrigger needs to be added as an attribute. You must then add the IDs for the appropriate events on the page to the partialTriggers that cause the underlying business object record to change, which in turn requires the Attachments data to change. For example, the navigation buttons Next and Previous as shown here:

Example 18-4 Adding Event IDs to the PartialTriggers

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

18.2.6 What Happens When You Implement Attachments

The following are examples of the generated source code:

Example 18-5 Source Code for an Attachment Field

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

Example 18-6 Source Code for an Attachment Table

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

Example 18-7 Source Code for an Attachment Column

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

Note:

The bindings, as shown above, only show when the Attachments are bound to a data control.

18.2.7 How to Create an Attachments Column in an Applications Table

You can create an attachments column in an applications table by dragging a Master Data Collection (your business object data collection) onto your drop target.

You can create an attachments column in an existing applications table by dragging a Detail Master Collection (the Attachments data collection) onto your drop target.

Note:

The mode attribute is automatically set to columnLink on the Attachment component when creating an attachment column.

To create an attachments column when creating your applications table:

  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}"

To create an attachments column in an existing applications table:

  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}"

18.2.8 How to Set Up Required Properties

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

  • usesUpload for a standard JSPX page

  • usesUpload on the UI Shell

  • RefreshCondition for the task flow

To set the usesUpload property for a standard JSPX page:

To be able to upload files from the desktop to the Content Server, you must set the usesUpload property to true.

For a standard JSPX page, you must set the usesUpload property on the af:form that contains your attachment component. For example:

<af:form usesUpload="true">

To set the usesUpload property on the UI Shell:

To set the usesUpload property value on the UI Shell's af:form, you need to set the Form Uses Upload property on the itemNode that represents the JSPX in the appropriate menu XML file.

  1. Go to the Application Navigator and select the menu XML file.

  2. Go to the Structure pane and select the item node representing the JSPX page.

  3. Go to the Property Inspector > Advanced Properties > Page tab and set the Form Uses Upload property to true.

  4. Save your changes.

To set the RefreshCondition property for the taskflow:

Setting the RefreshCondition property is only required when the repositoryMode property is set to true on the Attachment component. Setting this property for the taskflow allows the Document Picker to be used more than once within the Attachments table or popup in the same session.

  1. Go to the Bindings tab for that page.

  2. Click on the link to the Page Definition File, which is located at the top of the page.

  3. Select the attachmentRepositoryBrowseTaskFlow1 task flow from the list of Executables.

  4. Go to the Property Inspector and set the RefreshCondition property to #{AttachmentsTaskflowListener.refreshTaskflow}.

  5. Save your changes.

18.2.9 What Happens at Runtime

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.

Note:

The ability to associate repository files or folders is available when the repositoryMode property is set to true.

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. Once 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, and deleteAllowed 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.

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.

18.3 Displaying Attachments for Multiple Entities in the Same Table

For a user interface that shows information for more than one business object, the Attachments component can be configured to display the attachments for two or more of these business objects.

For example, when opening up the Attachments from the Department section of your UI page, you might want to display attachments for all Employees that exist in that Department. This example will be used throughout this section to help clarify the instructions.

This configuration is only possible when the underlying view object for your page contains the primary keys for each of the business objects whose attachments you want to show in your page. For example, the DeptEmpVO would need to include attributes for both the Department primary key and the Employee foreign key. In this example, the Department is considered to be the primary business object and the Employee is the secondary business object. The example uses only two business objects, but it is possible to display the attachments for more than two business objects using this feature.

Your primary business object is the one that you linked to the AttachmentsVO at design time, when you created your Attachment view link. Attachments can only be added to the primary business object when using this feature.

The actionEntity property can be used to set the primary business object and controls which attachments can be updated and deleted. When set, any document attached to a different entity is displayed for reference purposes only. It cannot be updated or deleted.

18.3.1 How to Configure the Attachments Component to Display Attachments for Multiple Entities

The following steps provide 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 Section 18.2.2, "How to Create Attachment View Links."

To configure your data model to display attachments for two or more business objects:

  1. Open the view object for your business object.

  2. Navigate to the Attributes tab. Add a new transient attribute for the secondary business object for which you want to display attachments. Use the existing AttachmentEntityName attribute as an example, naming the new attribute AttachmentEntityName1.

  3. Change the Expression value in the View Attribute screen to be the Attachment ENTITY_NAME as defined for your business object in the FND_DOCUMENT_ENTITIES and FND_DOCUMENT_ENTITIES_TL tables

  4. Repeat Steps 2 and 3 for any subsequent business objects for which you want to show attachments. Make sure that you modify the attribute name and expression value for each.

    Close the view object.

  5. Open the attachment view link.

  6. Link your secondary business object to the Attachments view object.

    1. Navigate to the Relationship tab and click the Attributes Edit icon.

    2. Select the foreign key reference column in your view object from the Source Attribute list and then select the corresponding PknValue column in the Attachments view object (starting with Pk1Vlaue) from the Destination Attribute list. Click Add to add this pair.

      Repeat this for each column that makes up the foreign key, which identifies your secondary business object.

    3. Select the EntityName attribute (created in Step 2) in the Attachments view object from the Destination Attribute list. Click Add to add this pair.

      Repeat this for each of the AttachmentEntityName transient attributes.

    4. Navigate to the Query tab, and click the Source Edit icon.

    5. Modify the auto-generated Source and Destination queries to match the appropriate Entity Names and Primary Key values Put parentheses around the criteria that pertain to one business object and change the AND to an OR in between each business object. Make sure your parentheses are matched correctly, as shown in examples Example 18-8 and Example 18-9.

      Example 18-8 Source Query

      ((:Bind_EmployeeId = PK1_VALUE) AND (:Bind_AttachmentEntityName = ENTITY_NAME)) 
OR 
((:Bind_DeptNum = PK1_VALUE) AND (:Bind_AttachmentEntityName1 = ENTITY_NAME))

      Example 18-9 Destination Query

      ((:Bind_Pk1Value = FndDemoDeptEmpEO.EMPLOYEE_ID) AND (:Bind_EntityName = 'FND_DEMO_EMP')) 
OR 
((:Bind_Pk1Value = FndDemoDeptEmpEO.DEPT_NUM) AND (:Bind_EntityName = 'FND_DEMO_DEPT'))

  7. Navigate to the Source view for the view link and edit the source XML to include the extra attributes in the Destination array. Make sure you include attributes for each additional business object for which you want to display attachments.

    The AttrArray for the destEnd ViewLinkDefEnd must map to the AttrArray for the sourceEnd ViewLinkDefEnd.

    The design time code inserts an array of unique items where the runtime code needs a matching item list, as shown in Example 18-10. (The added items are in bold).

    Example 18-10 Source and Destination Attribute Arrays

    <ViewLinkDefEnd
  Name="sourceEnd"
  Cardinality="1"
  Owner="oracle.apps.model.FndDemoDeptEmpVO"
  Source="true">
  <AttrArray Name="Attributes">
    <Item Value="oracle.apps.model.FndDemoDeptEmpVO.DeptNum"/>
    <Item Value="oracle.apps.model.FndDemoDeptEmpVO.AttachmentEntityName"/>
    <Item Value="oracle.apps.model.FndDemoDeptEmpVO.AttachmentEntityName1"/>
    <Item Value="oracle.apps.model.FndDemoDeptEmpVO.EmployeeId"/>
  </AttrArray>
</ViewLinkDefEnd>
<ViewLinkDefEnd
  Name="destEnd"
  Cardinality="-1"
  Owner="oracle.apps.fnd.applcore.attachments.uiModel.view.AttachmentsVO">
  <AttrArray Name="Attributes">
    <Item Value="oracle.apps.fnd.applcore.attachments.uiModel.view.AttachmentsVO.Pk1Value"/>
    <Item Value="oracle.apps.fnd.applcore.attachments.uiModel.view.AttachmentsVO.EntityName"/>
    <Item  Value="oracle.apps.fnd.applcore.attachments.uiModel.view.AttachmentsVO.EntityName"/>
    <Item Value="oracle.apps.fnd.applcore.attachments.uiModel.view.AttachmentsVO.Pk1Value"/>
  </AttrArray>

  8. Navigate back to the General tab and expand the Custom Properties section. Modify the value of the OAF_ATTACHMENT_CATEGORY custom property to control the attachments that are displayed in your page, based on category and to control the Category droplist values.

    Note:

    This can be further controlled using data security.

  9. Save all your changes.

To configure your Attachments component to display attachments for two or more business objects:

  1. Open the page that contains the Attachment component that is bound to the ViewLink modified above.

  2. Select the Attachment component.

  3. Set the actionEntity property to the ENTITY_NAME of the primary business object. By setting this property, you are allowing users to update and delete attachments belonging to the primary business object whilst disabling the ability for users to update and delete attachments for the secondary and all subsequent business objects.

18.4 Configuring the Attachments Component UI

The default behavior of the Attachments component can be changed by setting the properties on the component using the Property Inspector.

Following is a list of some of the properties that are supported by the Attachment component. Refer to Table 18-1 for basic descriptions of why and how each property is used.

The most important properties to take note of are:

Table 18-1 Attachment Component Properties

Property Description Default Value

Mode

String. Acceptable values are link, columnLink, and table.

The mode property is set automatically at the time the component is created.

RepositoryMode

Boolean: true / false.

True: Repository related functionality is enabled, including: the ability to select and attach a document/folder from the Content Server, and version control.

False

AttachFolderAllowed

Not used.

N/A

AttachLatestVersion

Not used.

N/A

ApprovalEnabled

Boolean: true / false. True: Adds the Status column to the Attachments table.

False

DeleteMessage

String. Message to be displayed on Delete Attachment confirmation page.

Are you sure you want to delete the selected attachment(s)?

Rows

Number. Maximum number of rows to display in a single range of rows in attachment table. Some ranges may have fewer than the number specified here, i.e. the last range when there is an insufficient number of rows. To display all rows at once, set this attribute value to 0.

10

FileTypeEnabled

Boolean: true / false. True: Display attachment type of "File" in the Type choice list.

False: the component is hidden.

True

TextTypeEnabled

Boolean: true / false. True: Display attachment type of "Text" in the Type choice list.

True

UrlTypeEnabled

Boolean: true / false. True: Display attachment type of "URL" in the Type choice list.

True

NumAttachmentsDisplayed

Number. Maximum number of attachments displayed as links in the hover popup when mode is set to link or columnLink.

3

AddAllowed

Boolean: true / false. Enables/disables the "Add" icon in the attachments table toolbar.

True: enables the icon in the toolbar.

False: disables the icon in the toolbar.

True

AddEnabled

Boolean: true / false.

True: shows the icon in the toolbar.

False: hides the icon in the toolbar.

True

ActionEntity

String. This must be an Attachment Entity Name. For use when showing the attachments for multiple entities in the Attachments table/popup. Setting this property indicates that update and delete actions will only be possible on this entity.

  

UpdateAllowed

Boolean: true / false. Enables/disables the update icons in the attachments table toolbar. These include the "Check In", "Check Out" and "Cancel Check Out" icons. This property also enables/disables the users' ability to update the Category, Title and Description of the Attachments.

True: enables the icons and makes the Category, Title and Description columns editable for existing attachments.

False: disables the update icons and makes the Category, Title and Description columns read-only for existing attachments.

True

UpdateEnabled

Boolean: true / false. Controls show/hide of the update icons in the attachments table toolbar. These include the"Check In", "Check Out" and "Cancel Check Out" icons.

True: shows the update icons in the toolbar.

False: hides the update icons in the toolbar.

True

InsertMultiple

Boolean: true / false. Determines whether more than one attachment can be assigned.

False: User can only add a one attachment.

True

DeleteAllowed

Boolean: true / false. Enables/disables the "Delete" icon in the attachments toolbar and inline for link and columnLink modes. True: Deleting attachments is allowed.

True: enables the icon.

False: disables the icon.

True

DeleteEnabled

Boolean: true / false. Controls show/hide of the "Delete" icon in the attachments table toolbar.

True: shows the icon in the toolbar.

False: hides the icon in the toolbar preventing users from deleting attachments.

True

ViewAllowed

Boolean: true / false. True: Viewing attachments is allowed.

False: Links for viewing documents in Attachments tables are disabled.

True

DefaultCategory

String. Value selected as the default in the Category poplist when adding new attachments.

  

Rendered

Boolean: true / false. True: Component is rendered in the page.

False: the component is not rendered.

True

Id

String. The identifier of the component.

Auto-generated

Visible

Boolean: true / false.

True: the component is displayed in the page.

False: the component is hidden.

True

ShortDesc

String. The short description of the component. This text is commonly used by user agents to display tooltip help text.

  

Label

String. Specifies the title for the Attachment popup.

Attachment

AutoHeightRows

Number. Sets the maximum number of rows that the table height will automatically adjust to depending on the amount of data in the table.

10

ContentDelivery

String. This property is only used in conjunction with the AutoHeightRows property. If AutoHeightRows is not set, this property should be not be set either.

Immediate

RowBandingInterval

Number. The interval between which the row banding occurs. This value controls the display of the row banding in the table. For example, rowBandingInterval=1 would display alternately banded rows in the grid.

  

ColumnBandingInterval

Number. The interval between which the column banding occurs. This value controls the display of the column banding in the table. For example, columnBandingInterval=1 would display alternately banded columns in the grid.

  

ShowCategory

Boolean: true / false. Controls show/hide of the Category column in the Attachments table.

True

UpdateCategoryList

String. Stores a comma-separated list of Category Names that will be used at run time to populate Category LOV when a user adds new attachments or attempts to update the Category of an existing attachment. This list must be a subset of the Categories that are assigned to your Entity.

  

SecondaryToolbarRendered

Boolean: true / false.

True: shows the secondary toolbar.

False: hides the icon in the toolbar.

False

18.5 Setting Up Miscellaneous Attachments Features

When the repositoryMode property is set to true, the following features become available:

18.5.1 Custom Actions

Four facets (placeholders) are provided on the Attachment 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.

Note:

When using the tableAppsTableSecondaryToolbar or linkAppsTableSecondaryToolbar facets, you must also set the SecondaryToolbarRendered property on the attachments component to true to expose this facet in the Attachments table.

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.

18.5.2 Approvals

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):

Lookup Code Meaning
APPROVED Approved
REJECTED Rejected
REVIEWED Reviewed
SUBMITTED_FOR_APPROVAL Submitted for Approval
SUBMITTED_FOR_REVIEW Submitted for Review
UNAPPROVED Unapproved

Note:

The Status column is a read-only column when displayed in the Attachments Table.

18.6 Integrating Attachments Task Flows into Oracle Fusion Functional Setup Manager

Every application registers task flows with a product called Oracle Fusion Functional Setup Manager. The Functional Setup Manager provides a single, unified user interface that allows customers and implementers to configure all Oracle Fusion applications by defining custom configuration templates or tasks based on their business needs.

The Functional Setup Manager UI enables customers and implementers to select the business processes or products that they want to implement.

Function Security controls your privileges to a specific task flow, and users who do not have the required privilege cannot view the task flow. For more information about how to implement function security privileges and roles, see Chapter 49, "Implementing Function Security."

Table 18-2 lists the task flows and their parameters.

Table 18-2 Attachments Task Flows and Parameters

Task Flow Name Task Flow XML Parameters Passed Behavior Comments

Manage Attachment Entities

/WEB-INF/oracle/apps/fnd/applcore/attachments/publicUi/flow/ManageAttachmentEntities.xml#ManageAttachmentEntities

[moduleType] [moduleKey] [pageTitle]

Search and edit Attachment entities.

NA

Manage Attachment Categories

/WEB-INF/oracle/apps/fnd/applcore/attachments/publicUi/flow/ManageAttachmentCategories.xml#ManageAttachmentCategories

[moduleType] [moduleKey] [pageTitle]

Search and edit Attachment categories.

NA

For more information about task flows, see Oracle Fusion Applications Common Implementation Guide.

18.7 Securing Attachments

All attachments users must be assigned the "AttachmentsUser" role in order to use attachments. This role gives users read access to all shared file attachments. Depending on the security defined for attachments, further access privileges will be assigned to users on a per-file basis at the time of accessing the attachments.

Attachments can be secured using the following two types of security:

A user can choose whether to Share a file when creating a file attachment. File sharing impacts the way in which files are secured. For more information, see Section 18.7.2, "File Sharing."

18.7.1 Attachment Category Data Security

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 Section 18.2.4, "How to Assign 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 18-3.

    Table 18-3 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

18.7.1.1 How to Set Up Category Data Security

Do the following to set up category data security:

  1. Define the conditions (object instance sets) that identify the category or set of categories you are securing. The CATEGORY_ID, CATEGORY_NAME, or USER_NAME condition items can be used in your condition definitions.

  2. Ensure the Roles to which you want to assign data security have been created in Oracle Platform Security Services (OPSS).

  3. Grant the actions that you will allow a user to perform on the set of Categories identified by your condition in Step 2. You can grant one or more of the seeded actions: read, update, and delete (see Table 18-3) to a role, but a role must be assigned the read action in order to view attachments from the Attachments UI.

    The "Manage Database Resources and Policies" setup UI in the FndSetup application can be used to create these grants once you have defined your conditions in the database.

  4. (Optional) The "Applications Common Reference Data Review Duty" role (GUID: 7BC1484030A9EE43499AB0EBBE17B104) provides users with read, update, and delete actions for all attachments that are assigned the "Miscellaneous" category.

    To setup your own category data security for the "Miscellaneous" category, you will need to follow Steps 1 to 4.

    The following condition (object instance set) is seeded with Oracle Fusion attachments and can be reused by using the "Miscellaneous" category for your product:

    • INSTANCE_SET_NAME: FNDDOCUMENTCATEGORIESFND214

    • PREDICATE: category_name = 'MISC'

  5. Using the Manage Attachment Entities Setup UI, "switch on" category data security for your attachment entity.

For more information, see Chapter 47, "Implementing Oracle Fusion Data Security."

18.7.2 File Sharing

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 Section 18.8.1, "How to Use 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.

18.7.3 Attachments SaaS

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.

18.8 Using Attachments (Runtime)

This section discusses how to use Attachments file-level security, update attachments, use the Attachments update functions, and how to check file attachments out and in.

18.8.1 How to Use Attachments File-Level Security

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

Figure 18-12 Attachment Table with Shared Column

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

Note:

The option is not available for all URL and Folder type attachments, as shown in Figure 18-12. By default, all Folder type attachments are shared, and all URL type attachments are not shared. Therefore, the check box is hidden because these default values cannot be changed by the user.

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.

18.8.2 How to Update Attachments

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.

Note:

Only one attachment can be updated at any one time.
Icon Function File Property
Check Out Check Out versioncheckout_ena.png repositoryMode = true
Check In Check In versioncheckin_ena.png repositoryMode = true
Cancel Check Out 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.

18.8.2.1 Attachments Update Functions

The Attachments update functions are available in the Attachments table toolbar and Actions menu.

The rendering of the update buttons in the Attachments table toolbar and the corresponding actions in the Actions menu are controlled in the following way using the updateAllowed property on the Attachments component:

updateAllowed = true:

  • The Category, Title, and Description columns in the Attachments table are updateable.

    The title and description values are kept in sync with the corresponding values stored in the Content Server. When a user updates the title or description, the values are updated in the Content server when the changes are saved.

  • If repositoryMode = true:

    • The Check In, Check Out, and Cancel Check Out buttons are rendered in the Attachments table toolbar, as shown in Figure 18-13.

      These buttons are enabled or disabled based on the type of attachment and the checked out status of File and Text type attachments.

      Figure 18-13 Attachment Table with Update Functions set to True

      Update Functions set to True

  • If repositoryMode = false:

    • The Check In, Check Out, and Cancel Check Out buttons are not rendered in the Attachments table toolbar.

      Figure 18-14 Attachment Table with Update Functions set to False

      Update Functions set to False

updateAllowed = false:

  • None of the fields in the table are updateable when this property is set to false.

  • If repositoryMode = true:

    • The Check In, Check Out, and Cancel Check Out buttons are rendered and disabled in the Attachments Table toolbar.

  • If repositoryMode = false:

    • The Check In, Check Out, and Cancel Check Out buttons are not rendered in the Attachments table toolbar.

18.8.2.2 Determining the Checked Out Status of File and Text-Type Attachments

The Checked Out By column indicates the checked-out status in the Attachments table. this column is only rendered when the repositoryMode is set to true.

This column is always empty for URL and Folder type attachments.

For File and Text attachments, this column is either:

  • Empty, indicating that the file is not checked out.

  • Displays the Oracle Fusion Applications username of the user who currently has the file checked out.

    The user name is derived from the Checked Out By value that is stored against the file in the Content server. The stored Content Server username is mapped to the appropriate Oracle Fusion Applications username. If the value cannot be mapped, the Content server username is displayed in the column. This value is never stored in the Attachments Table.

18.8.2.3 Enabling or Disabling Attachments Update Functions

The update functions apply to a single selected row in the Attachments table. If no rows are selected or more than one row is selected in the Attachments table, all of the update buttons and the corresponding actions in the Actions menu are disabled.

When a single row is selected in the Attachments table, the enabling or disabling of the update buttons in the Attachments table toolbar and the corresponding actions in the Actions menu are controlled using the following rules when the updateAllowed property is set to true:

URL attachments

The following rules apply regardless of the repositoryMode value:

  • The Category, Title, and Description fields are updateable.

  • The Check Out, Check In, and Cancel Check Out functions are always disabled.

Folder attachments

If repostoryMode = true:

  • The Category, Title, and Description fields are updateable.

  • All of the update functions are disabled.

Text and File attachments

If repositoryMode = true:

  • The Category, Title, and Description fields are updateable.

  • All of the update functions are disabled when the file is checked out by a user other than the current user.

  • The Check Out function is disabled, and the Check In, and Cancel Check Out functions are enabled when the file is checked out by the current user.

  • The Check Out function is enabled, and the Check In and Cancel Check Out functions are disabled when the file is not checked out.

18.8.3 How to Check Out and Check In File Attachments

This section describes how to check out and check in file attachments.

To check out and check in file attachments:

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

    Figure 18-15 Check In File Dialog

    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.
Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Feedback page
Contact Us