Automatic Attachments in Order Management

An Oracle Whitepaper

March 2009

2

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

3

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

4

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

5

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.

6

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.

7

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

8

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)

9

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

10

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.

11

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

12

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.

13

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

14

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:

15

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

16

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

17

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

18

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

19

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

20

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.

21

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.