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:

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
AdminProcess

List Storage Prefixes

Business Overview

This service is used for retrieving Object Storage prefixes.

Service Type

Get

ReST URL

/FTSWrapper/listprefixes

Headers

Key	Value
Accept-Language	String (Ex: en-US)

Output

The output metadata contains the prefix details of the request including validation error, if any.

For Success:

[
 		 "downloaded",
  		 "incoming",
]

For Failure:

{
 		 "error_message": "string"
}

Register a New Storage Prefix

Business Overview

This service is used to register a new storage prefix.

Service Type

Put

ReST URL

/FTSWrapper/register/{prefix}

{prefix} - The Storage prefix to use

Headers

Key	Value
Accept-Language	String (Ex: en-US)

Responses

Code	Description
200	Successfully registered.
500	Failed registration.

Unregister a Storage Prefix

Business Overview

This service unregisters a storage prefix.

Service Type

Delete

ReST URL

/FTSWrapper/unregister/{prefix}

{prefix} - The storage prefix to be unregistered.

Headers

Key	Value
Accept-Language	String (Ex: en-US)

Responses

Code	Description
200	Successfully unregistered.
500	Failed unregistering.

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.

Service Type

Post

ReST URL

/FTSWrapper/upload

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.

Service Type

Post

ReST URL

/FTSWrapper/download

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.

Service Type

Delete

ReST URL

/FTSWrapper/delete

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.

Service Type

Get

ReST URL

/FTSWrapper/listfiles

Headers

Key	Value
Accept-Language	String (Ex: en-US)

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

Business Overview

This service is used to move files from one location to other in Object Storage.

Service Type

Post

ReST URL

/FTSWrapper/movefiles

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"
}

FTS Health Check

Business Overview

This service checks the status of the File Transfer Service (FTS).

Service Type

Get

ReST URL

/FTSWrapper/ping

Headers

Key	Value
Accept-Language	String (Ex: en-US)

Output

The output metadata contains output of the FTS service for Health check which shows the status. Validation error will be output, if any.

For Success:

{
    "appStatus": 200
}

For Failure:

{
    "error_message": "string"
}