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

Attachment field in a page or page segment:

The following elements are rendered on the page or page segment:

A link to the most recently attached document or URL. Hovering your mouse on a link supplies a detail window with attachment information. The detail window contains the following information about the most recent attachment:

Type - File/URL

Last Updated By

Last Updated Date

When clicked, the link opens the attachment in a new browser tab or window depending on the browser settings.

If there are no attachments the value of this field will be None.

When there are more attachments, a link will be displayed in the format "<# of additional attachments> more...". Clicking this link opens the Attachments window, which displays the full list of attachments in a table.

Hovering over this link will display a small dialog with a list of up to the next three most recent attachments. When clicked, these links opens the attachment in a new browser tab or window depending on the browser settings. If there are more than four attachments the last bullet is a link with the format " <# of remaining attachments> more...". The number of attachments shown in the small dialog list is configurable. Clicking this link opens the Attachments window, which displays the full list of attachments in a table.

The Manage Attachments icon. When clicked, the Attachments window is launched showing any existing attachments as well as a new empty row at the top of the list to allow the user to add new attachments.

The Delete Attachments icon. Only shown when there is only one attachment added. Allows the one attachment to be deleted without having to launch the Attachment window.

Figure 19-1 shows an example of an attachment field in a page or page segment with attachments.

Figure 19-1 Attachment Field in a Page or Page Segment

Note:

The Attachment label originates from outside the Attachment component to allow the Attachment component to correctly align with the other components in the page layout.

Attachment column in a table:

The following elements are rendered in the table:

A column header titled Attachments

A link to the most recently attached document or URL. Hovering your mouse on a link supplies a detail window with attachment information. The detail window contains the following information about the most recent attachment:

Type - File/URL

Last Updated By

Last Updated Date

When clicked, the link opens the attachment in a new browser tab or window depending on the browser settings.

If there are no attachments the value of this field will be None.

When there are more attachments, a link will be displayed in the format "<# of additional attachments> more...". Clicking this link opens the Attachments window, which displays the full list of attachments in a table.

Hovering over this link will display a small dialog with a list of up to the next three most recent attachments. When clicked, these links opens the attachment in a new browser tab or window depending on the browser settings. If there are more than four attachments the last bullet is a link with the format " <# of remaining attachments> more...". The number of attachments shown in the small dialog list is configurable. Clicking this link opens the Attachments window, which displays the full list of attachments in a table.

The Manage Attachments icon. When clicked, the Attachments window is launched showing any existing attachments as well as a new empty row at the top of the list to allow the user to add new attachments.

The Delete Attachments icon. Only shown when there is only one attachment added. Allows the one attachment to be deleted without having to launch the Attachment window.

This occurs when you choose to display all attachments for the current record in a table.

A dialog

This occurs when the user clicks the Manage Attachments icon associated with an attachment field either on a page or page segment, or an attachment column in a table.

The following elements are rendered in the Attachment table:

Table Toolbar

Add button, which adds a new row at the top of the table

Delete button, which deletes the selected rows from the table

Type (required field that determines the type of Attachment)

File (default)

Text

URL

Repository File/Folder

Category

Category values are defined at implementation time. Make sure to use functionally relevant category names. If two or more categories are defined, the category column is displayed. If only one category is defined, the column is not displayed.

File Name or URL (required field)

If the value is an existing attachment, a link is shown that opens the attachment when selected. The link opens in a new browser tab or window depending on the browser settings. For new rows:

If Type is File, will show a file upload field

If Type is Text, will show a text field

If Type is URL, will show a text field

If Type is Repository File/Folder, will show a text field and browse button. Clicking on Browse will launch a document picker for finding files in the repository.

Title

The user name for the attachment, as the file name or URL may not adequately convey the contents of the attachment. If users do not enter a title, it defaults to the value in the File Name or URL field.

Description

The field to include additional information on the attachment.

Last Updated By

Shows the name of the user that last updated the attachment relationship.

Last Updated Date

Shows the date on which the attachment relationship was updated.

Figure 19-3 is an example of an Attachments table with the repositoryMode attribute set to false.

Figure 19-3 Attachments Table

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

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

Create the view object representation of the business object that requires attachments in your model project.

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 Propagation for Authentication.

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

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 "Security Groups, Roles and Permissions" in Oracle WebCenter Content System Administrator's Guide for Content Server.

Also, be aware that there is an enforced maximum size for the files you can upload. You can modify the default setting, but doing so will affect any application deployed to the server that uses a multi-part form to upload from the desktop to Oracle WebLogic Server. For more information, see "Setting Parameters to Upload Files to Content Repositories" in Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal.

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

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

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

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

Click Next to access Step 2. The View Object dialog appears, as shown in Figure 19-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 19-6 Create Attachment View Link Wizard — View Object (Step 2)

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

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.

Click Next to access Step 4. The Categories dialog appears, as shown in Figure 19-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.

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 19.8.1, "Attachment Category Data Security."

Click Next to access the Application Module page. The Application Module dialog appears, as shown in Figure 19-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 19-9 Create Attachment View Link — Application Module (Step 5)

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

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

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:

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

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

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.

Save your changes.

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

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

19.2.4 How to Delete the Business Object

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. Once you have access to this collection, you can loop through calling the remove() method of the collection, shown in Example 19-4.

19.2.5 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 19.7, "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.

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.

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:

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.

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:

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

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

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

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

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

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

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.

Go to the Bindings tab for that page.

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

Select the attachmentRepositoryBrowseTaskFlow1 task flow from the list of Executables.

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

Save your changes.

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

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

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

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

Open the view object for your business object.

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.

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

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.

Open the attachment view link.

Link your secondary business object to the Attachments view object.

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

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.

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.

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

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 19-9 and Example 19-10.

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 19-11. (The added items are in bold).

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.

Save all your changes.

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

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

Select the Attachment component.

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.

19.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 19-1 for basic descriptions of why and how each property is used.

The most important properties to take note of are:

mode - This property drives the UI that is rendered. It is automatically set when you add attachments to your page and should not be changed. Mode values include link, table, and columnLink.

repositoryMode - This property indicates whether or not a user is aware of the content repository. A more advanced UI is displayed to users who are aware of the content repository (repositoryMode=true) allowing them to perform advanced functions such as selecting repository files and folders to attach to the business object, and checking in and checking out attached files.

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

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.

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.

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.

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

19.5 Working with Attachments Programmatically

To support headless or automated processing of Attachments, methods have been provided in the oracle.apps.fnd.applcore.attachments.attachmentService.applicationModule.AttachmentServiceAM class.

19.5.1 Creating New Attachment Types

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.

There currently are no methods for attaching files that are already uploaded to the content server (Repository File or Folder). How a required file would be located and then added still needs to be determined. If the required file is already attached to another record, use the copyAttachments method to attach the file to the required record. Table 19-2 summarizes the available methods for Attachments APIs.

For the given attachment row, it populates the attributes for the attachment type AttachmentsConstants.TMURI_TYPE.

AttachmentsVORowImpl

attachManagedUrl(java.lang.String entAppShortName, java.net.URI uri)

Creates a new row from the internal attachments view object and calls attachManagedUrl(AttachmentsVORowImpl row, String entAppShortName, URI uri) to populate.

void

attachText(AttachmentsVORowImpl row, java.lang.String text)

Updates the supplied attachments row with the information to attach text.

AttachmentsVORowImpl

attachText(java.lang.String text)

Creates a new row from the internal attachments view object and populates the attributes to attach text.

void

attachUrl(AttachmentsVORowImpl row, java.lang.String url)

Updates the supplied attachments row with the information to attach a static URL.

AttachmentsVORowImpl

attachUrl(java.lang.String url)

Creates a new row from the internal attachments view object and populates the attributes to attach URL.

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

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.

Warning:

Assigning an Attachment to the wrong record could allow an end-user to view a document they would not normally be able to view.

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");

19.5.2 Retrieving Attachments

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.

Table 19-3 getAttachmentUrl() Method

Class

Method

java.io.InputStream

getAttachmentInputStream(AttachmentsVORowImpl row)

Retrieve the attachment content for the supplied attachment row as a stream.

java.io.OutputStream

getAttachmentStream(AttachmentsVORowImpl row)

Retrieve the attachment content for the supplied attachment row as a stream.

java.lang.String

getAttachmentUrl(AttachmentsVORowImpl row)

Retrieve URL for the attachment content for the supplied attachment.

19.5.3 Using Attachment Utilities

One utility method that is provided enables 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.

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

When constructing the list of Attachments to copy, consider whether Category Data Security has been implemented (see Section 19.8.1, "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 for the copy it will be necessary to bypass Category Data Security by setting the dataSecurityDisabled flag on AttachmentsVOImpl to true, as shown in Example 19-15.

Create copies of the supplied attachment rows assigning them to the entity values as provided.

19.6 Setting Up Miscellaneous Attachments Features

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

Custom Actions

Approvals

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

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

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 50, "Implementing Function Security."

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

Attachment Category data 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 19.8.2, "File Sharing."

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

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

Table 19-6 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

19.8.1.1 How to Set Up Category Data Security

Do the following to set up category data security:

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.

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

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 19-6) 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.

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

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.

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

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

19.9.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 19-12.

Figure 19-12 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.

Note:

The option is not available for all URL and Folder type attachments, as shown in Figure 19-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.

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

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.

19.9.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 19-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 19-13 Attachment Table with 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 19-14 Attachment Table with 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.

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

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

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

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.

Go to your local file system and make the necessary updates to this file.

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

Figure 19-15 Check In File Dialog

Click Browse to browse your local file system. Select the updated file that you want to upload.

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.

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.