File Transfer Services (FTS)
Business Overview
File Transfer Services (FTS) provide an endpoint for the customer to be used when working with files that are uploaded to and downloaded from the Merchandising Cloud Service Suite. These services are used by Merchandising and Sales Audit (RMFCS), Pricing (RPCS), Invoice Matching (ReIMCS), Allocation (RACS) and the Data Conversion tool. They allow you to manage uploading and downloading files to Oracle Cloud Infrastructure Object Storage, which is an internet-scale, high-performance storage platform that offers reliable and cost-efficient data durability.
For each customer environment, buckets, which are logical containers for storing objects, will be created in Object Storage. Any type of data, regardless of content type, is stored as an object. An object is composed of the object itself and metadata about the object.
The services use OAUTH 2.0 client credential authentication. Once authentication passes, the internal file transfer services that retrieve a pre-authenticated request (PAR) are called to upload and download files to Object Storage. The primary role of these services is to ensure that only valid external users can call the service by enforcing authorization policies.
List of services:
- List Storage Prefixes
- Register a New Storage Prefix
- Unregister a Storage Prefix
- Retrieve PAR for Uploading Files
- Retrieve PAR for Downloading Files
- Delete Files
- List Files
- Move Files
- FTS Health Check
URL Prefix: https://rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace>/RmsPlatformServices/services/private
The final URL will be the URL Prefix followed by the ReST URL path mentioned in each service description below.
To start uploading or downloading the files to/from Object Storage, storage prefixes should be registered first.
The table below shows the prefixes used by each of the solutions when calling the above listed services. By default, all the storage prefixes below will be registered automatically.
RMFCS | RPCS | ReIMCS | RACS | Data Conversion | |
---|---|---|---|---|---|
Incoming |
/incoming |
/incoming/reim |
/incoming/alloc |
/dataconversion/incoming |
|
Outgoing |
/outgoing |
/dataconversion/outgoing |
|||
Reject |
/reject |
n/a |
n/a |
||
Downloaded |
/downloaded |
/downloaded/reim |
/downloaded/alloc |
n/a |
|
Archive |
n/a |
n/a |
n/a |
n/a |
Table 5-1 Administrative Processes
Storage Prefix | Service | File Name |
---|---|---|
AdminProcess |
Dynamic Hierarchy |
dynamic_hierarchy/dynamic_hierarchy_mapping_tl.csv |
Retrieve PAR for Uploading Files
Business Overview
This service is used for retrieving an Object Storage pre-authenticated request (PAR) for uploading files. The response from the service is then used to upload the files in the user specified prefix from Object Storage using curl. The specified prefix is the staging location for input file that is processed by one of the Merchandising cloud service upload batches.
Headers
Key | Value |
---|---|
Accept-Language |
String (Ex: en-US) |
Request body
{
"listOfFiles": [
{
"storagePrefix": "string",
"fileName": "string"
}
]
}
Output
Parameter Name | Data Type |
---|---|
id |
String |
name |
String |
accessUri |
String |
objectNames |
<List> String |
access |
String |
timeExpires |
Timestamp |
timeCreated |
Timestamp |
The output metadata contains the PAR details of the request including validation error, if any
For Success:
{
"id": "string",
"name": "string",
"accessUri": "string",
"objectNames": [
"string"
],
"accessType": "string",
"timeExpires": "timestamp",
"timeCreated": "timestamp"
}
For Failure:
{
"error_message": "string"
}
Uploading the Batch Incoming File
To upload the file, use a curl
command as shown below in the example, including the accessUri
returned from the ReST service call. Provide the location of the file to be uploaded. The file must be uploaded before the
expiration time. Below is an format of the curl
command structure. The specified prefix is the staging location
for input files that is processed by one of the Merchandising cloud service upload batches.
Example
curl https://<objectstorage_hostname/p/<pre authenticated request>/n/<namespace>/b/<bucketname>/o/<prefixname>/<filename> --upload-file <filename>
Retrieve PAR for Downloading Files
Business Overview
This service is used for retrieving an Object Storage pre-authenticated request (PAR) for downloading files. The response
from the service is then used to download the files in the user specified prefix from Object Storage using curl
. The specified prefix is the staging location for file that is processed by one of the Merchandising cloud service batches.
Headers
Key | Value |
---|---|
Accept-Language |
String (Ex: en-US) |
Request Body
{
"listOfFiles": [
{
"storagePrefix": "string",
"fileName": "string"
}
]
}
Output
Parameter Name | Data Type |
---|---|
id |
String |
name |
String |
accessUri |
String |
objectNames |
<List> String |
access |
String |
timeExpires |
Timestamp |
timeCreated |
Timestamp |
The output metadata contains the PAR details of the request including validation error, if any.
For Success:
{
"id": "string",
"name": "string",
"accessUri": "string",
"objectNames": [
"string"
],
"accessType": "string",
"timeExpires": "timestamp",
"timeCreated": "timestamp"
}
For Failure:
{
"error_message": "string"
}
Downloading the File
To download the file, use the curl
command to the accessUri
returned from the output
metadata. You can download the file before the expiration time. The specified prefix is the staging location for file that
is processed by one of the Merchandising cloud service batches.
Example
curl https://<objectstorage_hostname>/p/<pre authenticated request>/n/<namespace>/b/<bucketname>/o/<prefixname>/<filename> -O
Delete Files
Business Overview
This service is used for deleting files in Object Storage based on the provided prefix.
Headers
Key | Value |
---|---|
Accept-Language |
String (Ex: en-US) |
Request body
{
"listOfFiles": [
{
"storagePrefix": "string",
"fileName": "string"
}
]
}
Output
The output metadata contains the output of the FTS service for deletion. Validation error will be output, if any.
For Success:
{
"filesDeleted": [
{
"filePath": {
"storagePrefix": "incoming",
"fileName": "testFile.txt"
},
"responseMessage": "File successfully deleted incoming/testFile.txt"
}
],
"filesFailedDeletion": []
}
For Failure:
{
"error_message": "string"
}
List Files
Business Overview
This service provides a list of Object Storage files under the specified directory/prefix.
Input Parameters
Parameter Name | Data Type |
---|---|
prefix |
String |
contains |
String |
scanStatus |
String |
Limit |
String |
Offset |
String |
Sort |
String |
Output
Parameter Name | Data Type |
---|---|
name |
String |
size |
String |
md5 |
String |
version |
String |
etag |
String |
createdDate |
Timestamp |
modifiedDate |
Timestamp |
scanStatus |
String |
scanDate |
Timestamp |
scanMessage |
String |
The output metadata contains the file detail of the request.
For Success:
{
"name": "string",
"size": "string",
"md5": "string",
"version":”string",
"etag": "string",
"createdDate": "timestamp",
"modifiedDate": "timestamp",
"scanStatus": "string",
"scanDate": "timestamp",
"scanMessage": "string",
}
Move Files
Headers
Key | Value |
---|---|
Accept-Language |
String (Ex: en-US) |
Request body
{
"listOfFiles": [
{
"currentPath": {
"storagePrefix": "string",
"fileName": "string"
},
"newPath": {
"storagePrefix": "string",
"fileName": "string"
}
}
]
}
Output
The output metadata contains the output of the FTS service for file movement. Validation error will be output, if any.
For Success:
{
"failedMove": [],
"successfulMove": [
{
"moveFile": {
"currentPath: {
"storagePrefix": "downloaded",
"fileName": "RTLOG_STOREXXX_20210405122426384.DAT"
},
"newPath: {
"storagePrefix": "incoming",
"fileName": "RTLOG_STOREXXX_20210405122426384.DAT"
},
"responseMessage": "Successfully moved"
}
}
]
}
For Failure:
{
"error_message": "string"
}