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 entities…………………………………………………………………14

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 foreign–key 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. Define a document category
3. Assign document category to various entities types: Form, Report or Function
4. Define a document of type Standard or Template in the Documents form
5. Create Attachment Addition Rules
6. 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 haven’t 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.

5
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 Management’s
default reports in this field. Only text documents can print on reports.

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

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

8
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

9
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 one-
time. 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 one-
time 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