File Storage API

File Storage API

File storage for imports: You can use the file storage API to:

• upload files for import

• obtain a list of files that have been uploaded, or that are in error

• download a file, such as an error file (does not automatically delete the file)

• delete files

Note:

Use of the file storage API is required for new installations of Order Administration 17.x and later.

File storage for exports: Use the file storage API to:

• obtain a list of export files that have been generated

• download an export file

• delete files

Use of the FILE_STORAGE table: The FILE_STORAGE table stores data on import files and export files, as well as errors that occur during import or export processing. The web service requests files from, deletes files in, and puts files in this table.

Import processing example: To import Catalog Requests through the file storage API:

1. Create or obtain the Catalog Request file named IXCRIN.txt. See the Sample Catalog Requests Upload Data for sample contents.

2. Use the putFile web service request to place the IXCRIN.txt file data in the OMS-IMPORTS container of the FILE_STORAGE table.

3. Run the UPCATRQ Upload Catalog Request File (Program name PFR0134, Parameter IXCRIN) periodic function to use the contents of the FILE_STORAGE record to populate the Catalog Request Interface table (IXCRIN).

4. This deletes the record from the FILE_STORAGE table. Also, the system creates a file upload record, viewable at the Work with File Upload Screen.

5. Use the Work with Catalog Request Interface (WCRU) menu option to process the records in the Catalog Request Interface table; see Working with the Catalog Request Interface (WCRU).

When the uploaded file record is processed by the related import function, the record is deleted. It is not archived in the FILE_STORAGE folder.

Export processing example: To export marketing download data through the file storage API:

1. The system creates records in the Marketing Download Trigger table as a result of certain actions in Order Administration.

2. Run the MDEXTR Marketing Download Order and Customer Extract (CSX1041) periodic function to extract order and customer-related records in the Marketing Download Trigger table to the appropriate Marketing Download table.

3. Run the MDEXPRT Marketing Download Export (PFR0130) periodic function to extract the data in the Marketing Download tables to a pipe delimited text file that is included in a zip file, which is placed in the OMS-MARKETING container of the FILE_STORAGE table. The zip file has the same name as the text file, except for the .zip extension.

4. Use the getFiles web service request to determine the names of the zip files that are in the OMS-MARKETING container.

5. Use the getFile web service request to download one or more marketing download files from the FILE_STORAGE table.

6. Use the deleteFile web service request to delete the files from the FILE_STORAGE table once they are downloaded.

Web service requests: Requests supported by the file storage API and their purposes are:

• getFile: Download an error or export file that has been generated by Order Administration.

• deleteFile: Delete a file record, such as an error file or export file that has already been downloaded.

• putFile: Upload an import file to Order Administration. The file format can be text (.TXT file extension) or compressed (.zip file extension, or the .MOMZIP file extension for the Oracle Retail Merchandising Foundation Cloud Service (RMFCS) and Oracle Retail Pricing Cloud Service (RPCS) Integration). If the file is compressed, Order Administration extracts the information from the zip file when processing the import. No other file extensions are supported.

  Note:

  If you are uploading a zip file, then it must contain a text file of the same name as the zip file, which be in the base level of the zip file, with no subfolders. For example, the EXAMPLE123.ZIP file contains a single EXAMPLE123.TXT file.

  The file storage API returns an error if there is already an existing file in the table with the same name, regardless of whether the suffix is different. For example, the API returns an error if you attempt to upload a file named VENDORS.ZIP if there is currently a FILE_STORAGE record named VENDORS.TXT.

• getFiles: Request a list of file records in the FILE_STORAGE table.

URL: The URL is  http://server:port/oms/sxrs/SerenadeREST/FileStorage, where server:port identifies the application server where the RESTful service is located.

Every web service request needs to specify a container. The types of containers are:

• OMS-IMPORTS: Contains import file records from the integrating system that can be processed by the appropriate Order Administration function. For example, use the putFile request to create an OMS-IMPORTS record so that Order Administration can import the data.

• OMS-ERRORS: Contains error file records that resulted from a process through the file storage API. For example, use the getFiles request to retrieve a list of error files that have been created.

• OMS-MARKETING: Contains zip file records, each containing a single text file of marketing download data. See Working with the Marketing Download Extract.

• OMS-ECOMMERCE: Contains zip file records, each including a single text file of ecommerce-related data. The following options create records in this container:

  • Downloading E-Commerce Offer Files (EOFR): Contains the E-Commerce Product Web XML File (ProductWeb).

  • Working with Merge/Purge Sold-to Names (MMCS): Contains the E-Commerce Customer Merge Web XML File (CustomerMergeWeb).

  • E-Commerce Availability Web Request XML Message (AvailabilityWebRequest).

  For more information see the Order Administration Web Services Guide on My Oracle Support (ID 2953017.1).

• OMS-POSLOG: Contains zip file records, each containing a single text file of POSLog data for Xlink generated through the POSLOGX periodic function.

• OMS-SALES-AUDIT: Contains RTLOG zip file records that the SNDRTLG periodic function copied to file storage after sending the files to the Sales Audit module of Oracle Retail Merchandising Foundation Cloud Service. These files are retained in the FILE_STORAGE table in case you need to resend a file through the RCVRLG periodic function. See Data Flow from Order Administration to Sales Audit Module for an overview of the data flow, and see Transmitting the RTLOG File to Object Storage for information on how the records are written to the FILE_STORAGE table and used.

Web authorization required: All request messages also need to use a valid Storage web service user ID with a valid password. See Working with Web Service Authentication (WWSA).

File cleanup:

• Import file records: The import process removes records from the OMS-IMPORTS container when populating the staging or destination database table.

• Error records: The integrating system is responsible for deleting error records.

• Export records: The integrating system is responsible for deleting export records, including the OMS-MARKETING, OMS-ECOMMERCE, OMS-POSLOG, and OMS-SALES-AUDIT containers.

Summary of file storage API responses: The response codes that might be returned to file storage requests include:

• 200 = The getFile or getFiles request was successful.

• 204 = The putFile or deleteFile request was successful.

• 401 = The request failed because the web service user and password were not correct.

• 403 = The putFile request included a file that exceeded the FILE_STORAGE_MAX_SIZE property, or that was empty.

• 404 = The request failed for other reasons.

• 409 = A putFile failed because a file with the same name already exists in the FILE_STORAGE table.

• 500 = Server error.

Maximum file size for uploads: The FILE_STORAGE_MAX_SIZE property defines the maximum file size that you can upload through the file storage API. This property should not be set larger than 1G.

Uploading multiple files: If the amount of data for a particular upload exceeds the maximum size defined in the FILE_STORAGE_MAX_SIZE property, you can break the data out into multiple files. To upload multiple files of the same type, append a unique sequence number, such as a date/time suffix, to the file name, preceded by an underscore. The date/time suffix indicates the sequence in which to upload the contents of each file.

Example: To upload more than one file containing vendor data, you can create and upload a file named VNDUPL_20180702010203.ZIP and another named VNDUPL_20180702010204.ZIP. When the vendor upload program runs, the contents of both files will be extracted and loaded into the Vendor Upload table. Each zip file must include a single file using the same name, but with the TXT extension.

Note:

When an upload uses multiple files, the file names MUST include a unique sequence number suffix, such as a date/time stamp, preceded by an underscore. If the file names do not follow this convention, the upload will fail, and no subsequent uploads for the same file type will succeed until the incorrectly named files are removed from the CWDIRECTCP_UPLOAD_ DIRECTORY.

Upload directories: If the file storage API is enabled for imports, files that are placed in the CWDIRECTCP_UPLOAD_ DIRECTORY, or the other directories that are used for the are not processed by the related function; however, you can still upload a file for processing through the Work with File Uploads (WUPL) option.

Even though the system does not retrieve import files from the upload directories such as the CWDIRECTCP_UPLOAD_ DIRECTORY, import functions still use these directories for certain processing steps.