Automatic Attachments in Order Management

An Oracle Whitepaper March 2009

Summary........2 Concepts.........2 Setup and demo......4 Code and functionality changes........12 Security issues......14 Operations with attachments....14 Attachment across entities14

Summary
This paper addresses the Automatic Attachments functionality in Order Management application, version 11.5.10 and release 12. Attachments feature in Order Management allows to: Include attachments with orders and order lines Include attachments with order returns and order return lines Add free form text to the Sales Order Acknowledgement Report Quote header and lines include attachments The attachment documents can be viewed in the following forms: Order Organizer, Sales Orders, Blanket Sales Agreement Organizer, Blanket Sales Agreement, Quick Sales Orders, Quick Order Organizer, Quote, and Quick Quote windows.

Concepts
The attachments feature enables users to link unstructured data, such as images, word processing documents, spreadsheets, or text to their application data.

Attachment
A document associated with an entity is called an attachment.

Attachment function
A form or form function in your application cannot use attachments until the attachments feature is set up for that form or function; that is, it must be defined as an attachment function in the Attachment Functions window.

Document
A document is any object that provides information to support another object or action. Examples include images, word processing documents, spreadsheets, or text.

Document Category
A document category is a label that users apply to individual attachments and documents. Document categories provide security by restricting the documents that can be viewed or added via a specific form or form function. When you set up the attachments feature, you assign document categories to particular forms or form functions. When a user defines a document, the user assigns a category to the document. The attachments form can query only those documents that are assigned to a 2

category to which the calling form or form function is associated. A Miscellaneous category is seeded to provide easy visibility of a document across forms.

Document Usage Type

Indicates how the document may be used. There are three usage types: Template - the document is meant to be modified/edited before use. When you select a Template usage document in the Document Catalog, a copy of the document is created and the document usage of the copy is set to One-Time. The copy is also updateable. If you delete an attachment that has a usage type of Template, the document content, as well as the association of the document to the record is deleted. Documents that appear in the Document Catalog with a usage type Template, are created from the Documents Window screen in Oracle Applications. See the Oracle Applications User's Guide for additional information. One-time - the document is meant to be used only once. If you delete an attachment that has a usage type of One-time, the document content, as well as the association of the document to the record is deleted. The One-Time documents are created using the Attachment form (FNDATTACH.fmb). Standard - the document is a standard document that can only be referenced. When you select a Standard usage document in the Document Catalog, a copy of the document is not made. As a result, the document is not updateable. If you delete an attachment that has a usage type of Standard, the document content is not deleted, only the association of the document to the record is deleted. Documents that appear in the Document Catalog with a usage type of Standard, are created from the Documents Window screen in Oracle Applications. See the Oracle Applications User's Guide for additional information. Note: The Documents form ( FNDATDOC.fmb ) only allows you to create Template and Standard types and not One-Time documents.

Entity
An entity is an object within Oracle Applications data, such as an item, an order, or an order line. The attachments feature must be enabled for an entity before users can link attachments to the entity. In the context of attachments, an entity can be considered either a base entity or a related entity. A base entity is the main entity of the block. A related entity is an entity that is usually related to the block by a foreignkey relationship.

Setup and Demo

Pre-requisites:
In order to use Automatic Attachments in Order Management, it is necessary to: - set the profile option: OM: Apply Automatic Attachments to Yes - define attachment addition rules for the attachment document ( in Attachment Addition Rules window)

Automatic attachments in six steps

1. Enable the profile OM: Apply Automatic Attachments, at user level 3

2. 3. 4. 5. 6.

Define a document category Assign document category to various entities types: Form, Report or Function Define a document of type Standard or Template in the Documents form Create Attachment Addition Rules Create a Sales Order and check if the attachment document is applied automatically

Demonstration
1. Set the profile OM: Apply Automatic Attachments (OE_APPLY_AUTOMATIC_ATCHMT) to Yes. 2. Define a document category if you havent already defined one and choose a default data type (Figure 1). Go to Order Management > Setup > Orders >Attachments > Document Categories

Figure 1 Defining Document Categories

The Category defines the purpose of an attachment and controls which forms can access it. Select the Default Data Type from the list of values (Long Text, Short Text, File or Web page). The default Datatype can be overridden when you create documents. - Text (short text or long text)Enter text that is less than 2000 characters. If the text you want to attach is more than 2000 characters, upload it in a file. - File - Launch the Upload a File window in your browser. Select the Browse button to locate the file in your file system, or enter the file location in the File field. File documents are external files such as Microsoft Word files, Microsoft Excel files, image files such as .JPG files, or other types of files. When File type documents are attached, they are loaded into the database in the location set be the profile option Attachment File Directory (ATTACHMENT_FILE_DIRECTORY). When a 4

File document is selected, the lower half of the Attachments window displays an Open Document button that invokes a web browser and passes the file to the browser. The web browser handles displaying the file as appropriate based on its filename extension. The documents having Data Type: File cannot be saved as Template because they cannot be edited.

Figure 2 Defining Documents having data type as File

- Web Page - Web Page documents are attached as URLs in the format http://www.oracle.com (or the format www.oracle.com if your browsers can use that format). When a user selects a Web Page document to view, the lower half of the Attachments window displays an Open Document button that invokes a web browser and passes the URL to the browser. Your cursor advances to the File or URL field on the Source tab of the window. Enter the URL for the Web page. Optionally, enter an effective date range for your attachment category. Save the chages.

Figure 3 Defining Documents having data type as Web Page

3. Assign document category to various entities types: Form, Report or Function using the Assignments button (Figure 4).

Figure 4 Assigning Document Category

Order Management enables Oracle Application Attachment functionality for the following entities: The Sales Order and Order Organizer Window (form) The Sales Order Acknowledgement Report If you choose to include an Attachment for printing on the Sales Order Acknowledgement Report, you are currently limited to selecting a data type of Short or Long Text. Additionally, order-level attachments print only at the order header or order footer within the output, and order line-level attachments print only in the report body (within the body of each record displayed). You can associate as many reports as you need with a single category. If you customize your own reports to include documents, you can specify your own as well as Order Managements default reports in this field. Only text documents can print on reports.

Oracle Shipping Execution enables Oracle Application Attachment functionality for entities such as: Bill of Lading, Commercial Invoice, Pack Slip, and Pick Slip. Oracle Pricing enables Oracle Application Attachment functionality for entities such as Agreements and Price Lists. For entity type: Report, select a Format: Header, Body or Footer. The Format value determines where documents in this category will appear on the report. You can add your own formats for selection within the CategoryAssignment window by adding values to the Order Management QuickCode NOTE_FORMAT type. However, standard reports support only the seeded format of Header, Body, and Footer. In standard reports, order-level notes print only at the header and footer levels; line-level notes print only in the report body. 4. Also, define a document of type Standard or Template in the Documents form. Go to Order Management > Setup > Orders >Attachments > Documents Attach the document to the document category previously defined (Figure 5).

Figure 5 Defining a document having Data Type as Long text

Starting with Oracle Applications Technology 11i.ATG_PF.H Rollup 4 (RUP4) patchset : 4676589 and with Release 12, there is no longer the 'One Time' radio button on Usage region in the Attachments form. 5. Create Attachment Addition Rules The Addition Rules button opens the Attachment Addition Rules window (Figure 6).

Figure 6 Creating an Attachment Addition Rule for the new created Document

These rules are used for automatically attaching of all types of documents to order headers and order lines. For Order Management, attachment addition rules can be defined at the header level for the following attributes for orders, quotes, or returns: Customer Customer PO Invoice To Order Category Order Type Ship To At the order line level, you can specify your attachment addition rules by specifying values for the following attributes on the order, order line, quote line, or return line: Customer Inventory Item Invoice To Line Category Line Type Purchase Order Ship To Note: Blanket Sales Agreement does not support rule-based attachments. 6. When creating a Sales Order having an entity matching with the rule attribute defined in the addition rule defined previously, the attachment is applied automatically (Figure 7). (Order Management > Order, Returns > Sales Orders form)

Figure 7 Creating a new Sales Order elligible for automatic attachment

When accessing Attachments icon, the Attachment window is opened and the text is displayed. The Attachments icon invokes the Attachments window. If attachments already exist, the icon appears as a paperclip holding paper (Figure 8). Note: In Order Organizer, for line level attachments, the paper clip icon will only be highlighted in the "Lines TAB" of the Order Organizer form. The paper clip icon in the "Summary TAB" of the Order Organizer form will only be highlighted when there are header level attachments.

Figure 8 Viewing the attchment document

A "Publish to Catalog" button has been added to the Attachments form, to allow one-time attachments to be easily published to the catalog as either Standard or Template documents. The "Publish to Catalog" button is conditionally enabled, based on the current row status and usage type (one-time, standard, etc). The button is also secured by Function Security, to allow it to be globally disabled.

Row Status: The button is only enabled for queried rows, not for new rows. Before publishing to the catalog, a new attachment row must first be saved to the database. Usage Type: The button is only enabled if the Usage Type of the current row is onetime. Standard documents are already published to the catalog, the button is disabled. Function Security: The Publish to Catalog button is controlled by function security. The function is named FND_FNDATTCH_PUBTOCAT of type SUBFUNCTION. The Attachments form will call fnd_function.test() to test if the function has been granted to the current user - if not, the button will not be displayed. By default, the function will be seeded as granted to GLOBAL user. System Administrators can delete or alter this grant if they want to restrict access.

Publish to Catalog Button Behavior - When pressed, the "Publish to Catalog" button opens a dialog window. The options available in this window will vary based on Document type. - For Long Text and Short Text, the dialog will ask Which kind of document would you like this published as?. Choices are Standard, Template, or Cancel (Figure 9). If the user picks Standard then the current record will simply be changed to Standard and this will of course be published to the catalog by default. If the user picks Template then a copy of the current record is made and set as a template and will thus show up in the Catalog. The option Cancel would do nothing and close the dialog. When choosing Standard or Template, the current record is marked as Changed in Forms. The user will be asked to Save changes when leaving the attachments form, data published to catalog will be committed or rolled back along with the rest of the transaction. If a One-time document is of any other type (File, URL, OFO), the dialog will pop up with 2 buttons: and ask Would you like to publish as a Standard?. Choices are 'Publish' or 'Cancel'. If the user picks Publish then the current record will simply be changed to standard and this will of course be published to the catalog by default. Cancel would do nothing and close the dialog.

Creating a One-time document

This can be done using the Attachments window (Figure 10). In FNDATTCH (Attachment) window, if adding a one time document: Sequence: 20, Category: MS_INVOICE, with a specified text : see also attached documents when accessing Publish to Catalog, the system allows that this document to be published as Template or Standard document. The new document saved as Template or Standard can be viewed using Document Catalog button and querying after Category and Usage fields.

10

Figure 9 Creating a one-time document in Attachment window

Figure 10 Saving the one-time document as template in Attachment window

The 'May Be Changed' checkbox is always disabled for documents having Usage Type as Standard and users will not be able to update the attachment. For attachment documents with Template as usage type the May be changed check box is always enabled.

The Standard and Template documents can be queried using Document Catalog window (Figure 11).

11

Figure 11 Querying the Template documents from Document Catalog window

Also, the document can be previewed using Preview button (Figure 12):

Figure 12 Viewing the documents with Preview button in Document Catalog window

Code and functionality changes

1. There was a change in ATG.RUP4: 4676589 and release 12. It was determined that onetime documents were never meant to show up in the catalog and this was causing many problems with maintaining and using documents. The fix for bug 4566172 has obsoleted the one-time functionality and introduced the following changes: The application now has a button (Publish To Catalog) on the Attachments (FNDATTCH) form that will allow the user to create an attachment/document, select it, and save the document to the catalog as a template or standard document so that it can be used again from the catalog. All template and standard documents can be controlled and maintained in the Documents form (FNDATDOC). This is the way the documents were meant to be used in the Oracle Application. 12

One-time documents were meant to be used only once (not re-used), created only by the user on the Attachments (FNDATTCH) form. Whenever reusing a document from the catalog it should be a template or a standard document. If you re-use a one-time document over and over it used to show up in the catalog for each time - sometimes up to a thousand instances. This left room for error in picking one of the thousand documents that may look the same in the description field but were different in the content field. A template and standard document can be controlled and maintained whereas a one-time cannot. When a template is selected and attached from the catalog it becomes a one-time. A standard document also resides in the catalog and when is selected to be attached from the catalog, the same document can be shared across many entities (orders or WIP jobs). The changes of this Patch in this area are as follows: It adds a "Publish To Catalog" button on the FNDATTCH form (Attachments Form), with a dialog box containing buttons for "Standard" and "Template" that pops up after the "Publish To Catalog" button is pressed. The attachment record will need to be committed before the "Publish To Catalog" button would be enabled (in view). You also will have the Publish to Catalog button controlled by function security. Changed the FNDATDOC form (Documents form) so the Documents form only shows Template and Standard. The Documents form only allows you to create Template and Standard types, not one-time attachments. Only change is that we're giving the end user control of whether their document is visible to everyone else, where they had no choice before.

2. The FND patch 6843372 - resolves the issue of display of one-time document with template region greyed out in FNDATDOC form (Documents form) for the new records. In order to correct the old records, datafix bug 7375991 is already logged for the same and provides a datafix for correcting the old records.

3. The bug 6814730 fixed the attachment issue wherein change of attachment attribute was not deleting the attachment for old attribute value and attaching the attachment for new attribute value. Because of the above fix when any attribute (with no addition rules defined) is changed, then also it was triggering attachments which has been partially fixed in bug 7449257. Since bug 7449257 does not fix the complete issue (it is not feasible to fix it with current framework), a new Enhancement Request 7649341 has been raised with Develoment team

13

Security issues with Attachments in Order Management

When viewing the sales order and returns, you should be able to specify who has the ability to apply and update the attachment and who can only view the attachment. This will be setup via Attachment Functions. For Order Management, two attachment functions will be seeded: 1. Query_only sales order form function (ONT_OEXOEORD_VW): the attachment function will be setup such that only viewing of attachments is allowed. Users cannot create, update or delete the attachments if accessing the form via this function. 2. Sales Order form (OEXOEORD): from any function other than the above query_only function that accesses the sales order form, the user will be able to query, update, insert or delete attachments. The system administrator can thus restrict who can only view or who can view & edit attachments by setting up the associated menu to access the query_only function or any other sales order form function respectively.

Operations with attachments

Copy an attachment You can copy an attachment when using copy sales order functions. In Copy window, the tabs Copy Headers and Copy Lines, there is a checkbox Attachments that allows you to specify if you want to copy attachments from the source sales order. Update an attachment You can update an attachments of type: One-Time and Templates. The attachment documents of type Standard cannot be updated. When a Template is attached and modified in the Attachments form the template itself is not updated instead another document is created with usage type = One-Time and that document is attached to the entity. Delete an attachment If you delete an attachment that has a usage type of Template or One-Time, the document content, as well as the association of the document to the record is deleted. If you delete an attachment that has a usage type of Standard, the document content is not deleted, only the association of the document to the record is deleted.

Attachments across entities

In many cases, there is a need to have the attachment from one form visible on another form. In the example below, we will address the requirement that attachment defined at Item Master level for a particular item to be visible on the Sales Order line level. The setup mentioned below is needed to achieve this functionality:

14

1) Under Application Developer responsibility > Attachments> Attachment Functions (Figure 13). 2) In the field Name, query for "INVIDITM" which is the fmb file name for "Master Item" form (Figure 14).

Figure 13 Attachment Functions form 3) Go to (B) Blocks-> then go to (B) Entities-> Entity "Item" -> Primary Key fields (Figure 15). The primary key values should be: Key 1: MTL_SYSTEM_ITEMS.ORGANIZATION_ID Key 2: MTL_SYSTEM_ITEMS.INVENTORY_ITEM_ID

Figure 14 Block Declaration window for INVIDITM

15

Figure 15 Entity Declaration form and Primary Key Fields tab 4) Go to attachment function again. 5) Select name as OEXOEORD, which is the fmb file name for 'Sales Orders' form. 6) Click on Blocks button (Figure 16).

Figure 16 Attachment Functions for OEXOEORD 7) Select block name 'LINE'.

16

Figure 17 Block Declaration form for OEXOEORD 8) Click on Entities button (Figure 17). 9) Add a new entity 'Item' having Display Method as 'Main Entity'.

Figure 18 Entity Declaration form with the Item entity defined and setup of Priviledges 10) In the Privileges tab make query as 'Always' and rest privileges as 'Never' (Figure 18). 11) In the Primary Key Fields tab put the following values (Figure 19): Key1 field: LINE.SHIP_FROM_ORG_ID which is mapped with MTL_SYSTEM_ITEMS.ORGANIZATION_ID of "Master Item" form. Key2 field: LINE.INVENTORY_ITEM_ID which is mapped with

17

MTL_SYSTEM_ITEMS.INVENTORY_ITEM_ID of "Master Item" form.

Figure 19 Entity Declaration form with the Item entity defined and setup of Primary Key 12) Define an attachment in the master items form for an item (Organization Item).

Figure 20 Access Attachment icon in order to define an attachment for the selected item In the Attachment window, select a valid Category. In this case: Miscellaneous(Figure 21)

Figure 21 Create an attachment for the selected item

18

13) Check if the category: Miscellaneous (as selected in Figure 21 above) has the Sales Order form assigned to it. Go to Application Developer responsibility > go to Attachments> Document Categories. Query for category: Miscellaneous(Figure 22)

Figure 22 Document Category form for Miscellaneous category Go to Assignments button and in Category Assignments, query for Sales Orders.

Figure 22 Check if Sales Order is present and enabled in Category Assignments window 14) Create a sales order having a sales order line for this item and save it (Figure 23).

Figure 23 Check if the attachment icon is enabled on Sales Order line

19

See the Attachment icon is enabled on Sales Order form and the attachment text is visible when opening the attachment (Figure 24).

Figure 24 Open the attchment icon and check if the correct attachment is visible Note: The ship_from_org_id/warehouse and the organization in which document is defined in the master item should be same.

20

Automatic Attachments in Order Management Author: Marian Stan Senior Technical Support Engineer Global Product Support Special thanks to Aditya Mallik, Manager of OM Development team and Chidananda Pati, Senior Applications Engineer in OM Development team for their great help in reviewing and providing valuable suggestions for improving this whitepaper.

Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065 U.S.A.

Worldwide Inquiries: Phone: +1.650.506.7000 Fax: +1.650.506.7200 oracle.com

Copyright 2008, Oracle and/or its affiliates. All rights reserved. This document is provided for information purposes only and the contents hereof are subject to change without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. We specifically disclaim any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. This document may not be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without our prior written permission. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

21