X

An Oracle blog about Oracle Integration Cloud(OIC)

  • January 11, 2017

Oracle ERP Cloud Object Attachment Service

Important Note: Please visit Oracle's Application Customer Connect for latest and more information on ERP Integration Services including for this post

Introduction

The ERP Object Attachment Service supports the automatic upload of attachments for Oracle ERP Cloud business applications.  An attachment represents a collection of meaningful business information that is commonly captured as a separate file, text, or Internet URL.  Attachments are used to supplement and provide key additional information to enhance daily business operations and better track financials activities or events. 

Business enterprises often require the capability to efficiently associate specific attachments with a particular business entity or collection of business entities. For example:

  • Payables invoices may need to be associated with supporting documents such as duplicate invoices, payments, etc.
  • Account receivables transactions may need to be linked to customer-centric documents
  • Purchase orders may need supplementary files attached to indicate additional details related to specific goods or services procured or the nature of the overall purchase.

The ERP Object Attachment Service delivers this real-time automated capability starting in Oracle ERP Cloud Release 11 Patch Bundle 13.

Security Considerations

The ERP Object Attachment Service is secured through Oracle Web Service Manager (OWSM) using the following policy:

oracle/wss11_saml_or_username_token_with_message_protection_service_policy.

The client must satisfy the message protection policy to ensure that the payload is encrypted or sent over the SSL transport layer.

A client policy that can be used to meet this requirement is:  “oracle/wss11_username_token_with_message_protection_client_policy”

The user must have the duty role "ORA_FUN_FSCM_LOAD_INTERFACE_ADMIN_DUTY".

Design and Implementation

Constructing the Oracle ERP Object Attachment Service End Point URL

For illustration, to obtain the physical end point of any specific instance as a basis for the end point URL:

  1. Launch the ATK home page and sign in as a functional user.
  2. Navigate to a dashboard or work area associated with the Payables Service.
  3. In the Payables Invoice workbench, you can see a URL in the browser similar to https://<hostname>.<domainname>/payables/faces/InvoiceWorkbench.

The “<hostname>.<domainname>” may be “https://<pod-name>.<lba>.***.oraclecloud.com”.
In this example “<pod-name>.<lba>” is the hostname and “***.oraclecloud.com” is the domain name.

  1. In this URL, capture “https://<hostname>.<domainname>".
  1. Append the static context root: "/publicFinancialCommonErpIntegration/ ErpObjectAttachmentService".

“https://<hostname>.<domainname>/publicFinancialCommonErpIntegration/ ErpObjectAttachmentService” is the WSDL URL for the Oracle ERP Object Attachment Service.

Operation: uploadAttachment

The uploadAttachment operation uploads a file to the Oracle WebCenter Content (UCM) server based on the document details specified and submits an ESS job to load and import the uploaded files to an application table.

The following table lists the parameters for this operation:

Parameter

Name

Description

Parameter

(In/Out)

Mandatory

Type

Entity Name

Entity Name of the attachment

Navigate to “Setup & Maintenance UI > Set up Tasks > Manage Attachment Entities or Manage Attachment Categories” to get valid entity names. For example, AP_INVOICES_ALL, AR_BATCHES_ALL, PO_CONFIG_COMPONENTS, etc. are possible entity names.

IN

Yes

java.lang.String

Category Name

Category Name of the attachment

Navigate to “Setup & Maintenance UI > Set up Tasks > Manage Attachment Entities or Manage Attachment Categories” to get valid category names. For example, AP_SUPPORTING_DOC, PAYMENT_SUPPORTING_DOC, SCANNED_INVOICE_IMAGE, etc. are possible category names.

IN

Yes

java.lang.String

Allow Duplicate

Option to allow duplicate attachments

Values: Yes or No

IN

Yes

java.lang.String

Attachment Rows

The details of the attachment are:

User Keys: UserKeyA, UserKeyB, UserKeyC, UserKeyD, and UserKeyE. Please see below for more information.

Attachment Type: URL, File,  or Text

Title: Title of the document

Content

File -  This attachment type represents base64 encoding for file content being uploaded

URL - This attachment type represents an Internet URL of your document

Text - This attachment type represents actual text such as “Invoice requires further approval”

IN

Yes

java.lang.String

Response Code

The response code in JSON format

OUT

java.lang.String

User Keys

The ERP Object Attachment Service supports up to five user keys as UserKeyA, UserKeyB, UserKeyC, UserKeyD, and UserKeyE. These keys could provide different qualifying business contexts for a chosen entity such as business units, legal entities, ledgers, etc.

Sample Payload

The following example illustrates the sample payload to upload an attachment to a payables invoice:

<soap:Body>

                <ns1:uploadAttachment xmlns:ns1="http://xmlns.oracle.com/apps/financials/commonModules/shared/model/erpIntegrationService/types/">

                        <ns1:entityName>AP_INVOICES_ALL</ns1:entityName>

                        <ns1:categoryName>AP_SUPPORTING_DOC</ns1:categoryName>

                        <ns1:allowDuplicate>yes</ns1:allowDuplicate>

                        <ns1:attachmentRows xmlns:ns2="http://xmlns.oracle.com/apps/financials/commonModules/shared/model/erpIntegrationService/">

                                <ns2:UserKeyA>Vision Operations</ns2:UserKeyA>

                                <ns2:UserKeyB>SBP26</ns2:UserKeyB>

                                <ns2:UserKeyC>1377245736</ns2:UserKeyC>

                                <ns2:UserKeyD>#NULL</ns2:UserKeyD>

                                <ns2:UserKeyE>#NULL</ns2:UserKeyE>

                                <ns2:AttachmentType>TEXT</ns2:AttachmentType>

                                <ns2:Title>Sample</ns2:Title>

                                <ns2:Content>Testing Text</ns2:Content>

            </ns1:attachmentRows>

                        <ns1:attachmentRows xmlns:ns2="http://xmlns.oracle.com/apps/financials/commonModules/shared/model/erpIntegrationService/">

                                <ns2:UserKeyA>Vision Operations</ns2:UserKeyA>

                                <ns2:UserKeyB>SBP26</ns2:UserKeyB>

                                <ns2:UserKeyC>1377245736</ns2:UserKeyC>

                                <ns2:UserKeyD>#NULL</ns2:UserKeyD>

                                <ns2:UserKeyE>#NULL</ns2:UserKeyE>

                                <ns2:AttachmentType>FILE</ns2:AttachmentType>

                                <ns2:Title>SampleFILE.txt</ns2:Title>

                                <ns2:Content>VGhpcyBpcyBhIHNhbXBsZSBmaWxlIHRvIHRlbWVudCBvcGVyJTEUuDQo=</ns2:Content>

            </ns1:attachmentRows>

        </ns1:uploadAttachment>

    </soap:Body>

Figure 1:  Sample request payload for the Payables Invoices attachment

Sample Response

<env:Body xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="Body-7Us3sWti6wcgpuLGJ1ixLw22">

        <ns0:uploadAttachmentResponse xmlns:ns0="http://xmlns.oracle.com/apps/financials/commonModules/shared/model/erpIntegrationService/types/">

            <result xmlns="http://xmlns.oracle.com/apps/financials/commonModules/shared/model/erpIntegrationService/types/">"Attachment1":"SUCCEEDED","Attachment2":"SUCCEEDED"</result>

        </ns0:uploadAttachmentResponse>

</env:Body>

Figure 2:  Sample response payload for the Payables Invoices attachment

Conclusion

This summary highlights how to implement the ERP Object Attachment Service. It illustrates the programmatic approach of uploading documents into the ERP Cloud from external systems. It can be invoked through any integration platform.

Join the discussion

Comments ( 7 )
  • Arun Saturday, September 23, 2017
    Hi,

    Is there a documentation to refer what UserKeyA..UserKeyB..etc for a particular entity. Even for the example given AP_INVOICES_ALL, I could see that you are using BU as the UserKeyA. Not able to guess what others are.. Please help
  • Muniyasamy K Wednesday, May 16, 2018
    hi, I want sample payload for the Account object.
  • Vivek Monday, May 21, 2018
    Hi,
    Is there anyway to pass attachment filename in the request.
    As of now only placeholder is of attachmentTitle which is taken as the filename as well.
  • Jacob Monday, May 28, 2018
    Same question as Arun

    Is there a documentation to refer what UserKeyA..UserKeyB..etc for a particular entity.
  • Olivier Wednesday, April 3, 2019
    Hi

    Same question here. What should we use in the "keys"?

    Regards
    Olivier
  • Olivier Wednesday, April 3, 2019
    Hi

    More details can be found here: https://cloudcustomerconnect.oracle.com/posts/1ac9da3f2f

    This post also explain how to find the meaning of the userKeys.

    Kind Regards
    Olivier
  • Desh Deepak Friday, February 14, 2020
    Is there any service to extract all invoice attachments for invoices between a start date and end date of invoices?
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.