Oracle® Fusion Applications Developer's Guide 11g Release 6 (11.1.6) Part Number E15524-11 |
|
|
PDF · Mobi · ePub |
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:
Section 18.3, "Displaying Attachments for Multiple Entities in the Same Table"
Section 18.6, "Setting Up Miscellaneous Attachments Features"
Section 18.7, "Integrating Attachments Task Flows into Oracle Fusion Functional Setup Manager"
For general information about Oracle Fusion Middleware user interface (UI) components, see:
"Introduction to Oracle ADF Applications" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition)
"Introduction to ADF Faces Rich Client" chapter in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition)
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 18-1 shows an example of an attachment field in a page or page segment with attachments.
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.
Figure 18-2 shows an example of an attachment column in a table.
Attachment table:
The Attachment table can be shown in:
A page or page segment
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 18-3 is an example of an Attachments table with the repositoryMode
attribute set to false.
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:
Add the Applications Core (Attachments Model) library to your Model project:
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.
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 information about how to create a Content Repository connection in JDeveloper, see Section 54.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 Portal (Oracle Fusion Applications Edition).
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 (Oracle Fusion Applications Edition).
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.6, "How to Create an Attachments Field or an Attachments Table," Section 18.2.8, "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.7, "What Happens When You Implement Attachments" and Section 18.2.10, "What Happens at Runtime."
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 18-4.
Click OK to access Step 1 of the Create Attachment View Link wizard, as shown in Figure 18-5.
Complete the following information:
Select the name of the application that your view object belongs to.
Select the package where the attachment view link will reside.
Enter a unique name for the attachment view link.
Click Next to access Step 2. The View Object dialog appears, as shown in Figure 18-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.
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.
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.
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.5, "How to Assign Categories to the Attachment Entity."
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.8.1, "Attachment Category Data Security."
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.
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.
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.
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.
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 18-4.
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.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.
See the "Available Seed Data Loaders" table in Chapter 56 for information about Attachments Seed Data Loaders.
This section describes how to create an Attachments field or table.
To create an Attachments field or an Attachments table:
Create a page, page segment, or an applications panel that is bound to the attachments-enabled Master Data Collection (your business object data collection).
Drag the Detail Data Collection (the Attachments data collection) onto a databound drop target. The Create context menu appears.
Select Applications > Attachments to display the Create Attachments dialog, as shown in Figure 18-11.
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:
The following are examples of the generated source code:
Example 18-6 Source Code for an Attachment Field
<fnd:attachment mode="link" attachmentModel="#{bindings.AttachmentsIterator}"/>
Example 18-7 Source Code for an Attachment Table
<fnd:attachment mode="table" attachmentModel="#{bindings.AttachmentsIterator}"/>
Example 18-8 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.
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:
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.
Select Create, Applications Table to open the Applications Table wizard, Configure Table Patterns dialog.
Select the Attachments option.
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:
columnLinkTableModel="#{bindings.AuEmployee1.collectionModel}"
To create an attachments column in an existing applications table:
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.
Select Create, Applications, Attachments Column. The Edit Taskflow Binding dialog is displayed.
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}"
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.
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.
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.
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:
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 18-9 and Example 18-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 18-11. (The added items are in bold).
Example 18-11 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>
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.
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:
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 18-1 Attachment Component Properties
Property | Description | Default Value |
---|---|---|
Mode |
String. Acceptable values are link, columnLink, and table. |
The |
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 |
ReadOnly |
Boolean: true / false. True disables all creation/update/delete functions in the Attachment component at runtime. |
False |
To support headless or automated processing of Attachments, methods have been provided in the oracle.apps.fnd.applcore.attachments.attachmentService.applicationModule.AttachmentServiceAM
class.
Before you begin:
If the Application or Project has not already been configured to use Attachments, follow the instructions in "Before you begin:" in Section 18.2, "Creating Attachments."
Find or create an instance of the AttachmentServiceAM
:
Example 18-12 AttachmentServiceAM
// Enable the Attachments Service AM AttachmentServiceAMImpl attachmentServiceAMImpl = (AttachmentServiceAMImpl) am.findApplicationModule("attachmentsServiceAM"); if (attachmentServiceAMImpl == null) { attachmentServiceAMImpl = (AttachmentServiceAMImpl)am.createApplicationModule("attachmentsServiceAM", "oracle.apps.fnd.applcore.attachments.attachmentService.applicationModule. AttachmentServiceAM"); }
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 18-2 summarizes the available methods for Attachments APIs.
Table 18-2 Method Summary for Attachment APIs
Class | Method |
---|---|
|
Updates the supplied attachments row with the information to attach a file. |
|
Creates a new row from the internal attachments view object and populates the attributes to attach a file. |
|
For the given attachment row, it populates the attributes for the attachment type |
|
Creates a new row from the internal attachments view object and calls |
|
Updates the supplied attachments row with the information to attach text. |
|
Creates a new row from the internal attachments view object and populates the attributes to attach text. |
|
Updates the supplied attachments row with the information to attach a static 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 18-13.
Example 18-13 Code for Creating a New Attachment Row: Option 1
// Retrieve the department for adding the new Attachment row to ViewObject vo = am.findViewObject("FndDemoDept1"); vo.setWhereClause("DEPT_NUM = :deptNum"); vo.defineNamedWhereClauseParam("deptNum", null, null); vo.setNamedWhereClauseParam("deptNum", departmentNumber); vo.executeQuery(); Row currDepartment = vo.next(); // Retrieve the Attachments Collection RowSet attachments = (RowSet) currDepartment.getAttribute("Attachments"); // Create new Attachment Row AttachmentsVORowImpl newAttachment = (AttachmentsVORowImpl) attachments.createRow(); // Add Managed Link attachmentServiceAMImpl.attachManagedUrl(newAttachment, textEntAppShortName, textURI); // Set the Category Value newAttachment.setCategoryName("MISC");
The second option is to allow the method to create the Attachment row at the same time, as shown in Example 18-14.
Example 18-14 Code for Creating a New Attachment Row: Option 2
// Add Managed Link newAttachment = attachmentServiceAMImpl.attachTopologyManagedUrl(textEntAppShortName, textURI); newAttachment.setEntityName("FND_DEMO_DEPT"); newAttachment.setPk1Value(departmentNumber); // Set the Category Value newAttachment.setCategoryName("MISC");
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");
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 18-3.
Table 18-3 getAttachmentUrl() Method
Class | Method |
---|---|
|
Retrieve the attachment content for the supplied attachment row as a stream. |
|
Retrieve the attachment content for the supplied attachment row as a stream. |
|
Retrieve URL for the attachment content for the supplied attachment. |
Two utility methods are provided enable a list of Attachments to be copied to another record as identified by the unique combination of the Document Entity Name and Primary Key values. The list is constructed of the Attachment rows from one or more other records.
The copyAttachments utility does not duplicate the files on the content server. When the method is complete, the destination record will point to the same files in the content server as the source record.
The duplicateAttachments utility does duplicate the files on the content server. When the method is complete, the destination record will point to the new content on the content server.
When constructing the list of Attachments, consider whether Category Data Security has been implemented (see Section 18.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 it will be necessary to bypass Category Data Security by setting the dataSecurityDisabled
flag on AttachmentsVOImpl
to true, as shown in Example 18-15.
Example 18-15 AttachmentsVOImpl
AttachmentsVOImpl attachmentVO = attachmentServiceAMImpl.getAttachments1(); attachmentVO.setDataSecurityDisabled(true); // assign where clause conditions attachmentVO.executeQuery;
Note:
If order is important, the list is processed in the order it is received. Based on the default ordering the UI, this would place the first attachment in the list last when viewed.
Table 18-4 AttachmentsVORowImpl
Class | Method |
---|---|
|
Creates copies of the supplied attachment rows assigning them to the entity values as provided. |
|
Creates copies of the supplied attachment rows assigning them to the entity values as provided. Content on the content server is also copied. |
PL/SQL equivalents exist for some of the Java methods described in Section 18.5.1 and Section 18.5.3. These PL/SQL operations appear in Table 18-6.
Table 18-5 PL/SQL Attachments Implementation
Method | PL/SQL Implementation |
---|---|
attachManagedURL |
PROCEDURE ATTACH_MANAGED_URL ( X_ENTITY_NAME in VARCHAR2, X_PK1_VALUE in VARCHAR2, X_PK2_VALUE in VARCHAR2 DEFAULT NULL, X_PK3_VALUE in VARCHAR2 DEFAULT NULL, X_PK4_VALUE in VARCHAR2 DEFAULT NULL, X_PK5_VALUE in VARCHAR2 DEFAULT NULL, X_CATEGORY_NAME in VARCHAR2, X_ENT_APP_SHORT_NAME in VARCHAR2, X_URI in VARCHAR2, X_TITLE in VARCHAR2 DEFAULT NULL, X_DESCRIPTION in VARCHAR2 DEFAULT NULL ); |
attachURL |
PROCEDURE ATTACH_URL ( X_ENTITY_NAME in VARCHAR2, X_PK1_VALUE in VARCHAR2, X_PK2_VALUE in VARCHAR2 DEFAULT NULL, X_PK3_VALUE in VARCHAR2 DEFAULT NULL, X_PK4_VALUE in VARCHAR2 DEFAULT NULL, X_PK5_VALUE in VARCHAR2 DEFAULT NULL, X_CATEGORY_NAME in VARCHAR2, X_URL in VARCHAR2, X_TITLE in VARCHAR2 DEFAULT NULL, X_DESCRIPTION in VARCHAR2 DEFAULT NULL ); Updates the supplied attachments row with the information to attach a static URL. |
copyAttachments |
PROCEDURE COPY_ATTACHMENTS ( X_SRC_ENTITY_NAME in VARCHAR2, X_SRC_PK1_VALUE in VARCHAR2, X_SRC_PK2_VALUE in VARCHAR2 DEFAULT NULL, X_SRC_PK3_VALUE in VARCHAR2 DEFAULT NULL, X_SRC_PK4_VALUE in VARCHAR2 DEFAULT NULL, X_SRC_PK5_VALUE in VARCHAR2 DEFAULT NULL, X_SRC_CATEGORY_NAME in VARCHAR2 DEFAULT NULL, X_DST_ENTITY_NAME in VARCHAR2, X_DST_PK1_VALUE in VARCHAR2, X_DST_PK2_VALUE in VARCHAR2 DEFAULT NULL, X_DST_PK3_VALUE in VARCHAR2 DEFAULT NULL, X_DST_PK4_VALUE in VARCHAR2 DEFAULT NULL, X_DST_PK5_VALUE in VARCHAR2 DEFAULT NULL, X_DST_CATEGORY_NAME in VARCHAR2 DEFAULT NULL ); Creates copies of the supplied attachment rows assigning them to the entity values as provided. This utility does not copy the content on the server; it creates a copy of the reference to the content. |
copyAttachment |
PROCEDURE COPY_ATTACHMENT ( X_ATTACHED_DOCUMENT_ID in VARCHAR2, X_ENTITY_NAME in VARCHAR2, X_PK1_VALUE in VARCHAR2, X_PK2_VALUE in VARCHAR2 DEFAULT NULL, X_PK3_VALUE in VARCHAR2 DEFAULT NULL, X_PK4_VALUE in VARCHAR2 DEFAULT NULL, X_PK5_VALUE in VARCHAR2 DEFAULT NULL, X_CATEGORY_NAME in VARCHAR2 DEFAULT NULL ); Creates a copy of the supplied attachment row. This utility does not copy the content on the server; it creates a copy of the reference to the content. |
Note:
The Attachments procedures listed in Section 18.5.1 and Section 18.5.3, but not listed in Table 18-5, cannot be implemented in PL/SQL.
A debugging utility is also included. When enabled, messages are written to the console. This feature is not enabled by default. At runtime the same messages will be written as log messages if logging is set to FINEST for the applcore.db.plsql.attachments.FND_ATTACHMENTS
module.
To begin writing log messages to the console, use the PROCEDURE
START_DEBUG
command.
To stop writing log messages to the console, use the PROCEDURE
STOP_DEBUG
command.
Example 18-16 displays sample code for implementing Attachments with PL/SQL with debugging enabled.
Example 18-16 Implementing Attachments with PL/SQL
SET SERVEROUTPUT ON; DECLARE BAD_ENTITY_NAME_EXCEPTION EXCEPTION; PRAGMA EXCEPTION_INIT(BAD_ENTITY_NAME_EXCEPTION, -20001); P_ENTITY_NAME VARCHAR2(40) := 'FND_DEMO_DEPT1'; P_PK1_VALUE VARCHAR2(150) := '10'; BEGIN BEGIN FND_ATTACHMENTS.START_DEBUG; FND_ATTACHMENTS.ATTACH_URL (P_ENTITY_NAME, P_PK1_VALUE, NULL, NULL, NULL, NULL, 'MISC', 'http://www.oracle.com', 'Oracle Corportation', NULL); FND_ATTACHMENTS.END_DEBUG; EXCEPTION WHEN BAD_ENTITY_NAME_EXCEPTION THEN DBMS_OUTPUT.PUT_LINE ('The entity name supplied, ' || P_ENTITY_NAME || ', is not a registered document entity.'); END; END;
When the repositoryMode
property is set to true, the following features become available:
Custom Actions
Approvals
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.
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."
Table 18-6 lists the task flows and their parameters.
Table 18-6 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.
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 18.8.2, "File Sharing."
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.5, "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-7.
Table 18-7 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 |
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 18-7) 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:
INSTANCE_SET_NAME: FNDDOCUMENTCATEGORIESFND214
PREDICATE: category_name = 'MISC'
Using the Manage Attachment Entities Setup UI, "switch on" category data security for your attachment entity.
For more information, see Chapter 49, "Implementing Oracle Fusion Data Security."
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.9.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.
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.
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.
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.
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.
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.
If repositoryMode
= false:
The Check In, Check Out, and Cancel Check Out buttons are not rendered in the Attachments table toolbar.
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.
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.
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.
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 18-15.
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.