How to upload and trigger Suggest Blacklist & Whitelist Data

Scope

Suggestions can be added to the Suggest index by including a whitelist.csv to the input data for Suggest. Similarly, suggestions can be removed by including these in the blacklist.csv. 

The following guide contains details on how to upload and trigger Suggest Blacklist & Whitelist data using the REST API. 

Note: If this is your first time uploading Suggest Blacklist and Whitelist data, please get in touch with your Technical Consultant to integrate this feature initially. Your Technical Consultant can initially provide the files in the correct format, which you can then use to update with new data using the below steps.

 

Finding your existing data

You can download your existing data.zip file containing the two files using the following endpoints:

https://my.{region}.fredhopperservices.com/{clound_account}/input/suggest/{service_instance}/dummy/ Note: The data.zip should be uploaded inside /dummy/ and the data-id=dummy used.

 

Steps

The Blacklist and Whitelist files should be compressed with the original zip specification (application/zip) before uploading and a MD5 checksum of the ZIP file need to be generated to verify the file after its uploaded.

1. Compress all .csv files (e.g. blacklist.csv, whitelist.csv) into one data.zip file. 

2. Create MD5 checksum of data.zip file to validate that upload file is not corrupt, e.g.

    md5sum data.zip

    The output should be similar to:

   DB211B14E25CFBXXX92C3B3697CD0394 data.zip

3. Upload data.zip file and MD5 checksum to environment

   REST URL:

   https://my.{region}.fredhopperservices.com/suggest:{service_instance}/data/input/data.zip?checksum={checksum}

   cURL example:

   curl -D - -u "{cloud_username}":"{cloud_password}" -X PUT -H "Content-Type: application/zip" --data-binary @data.zip https://my.eu1.fredhopperservices.com/suggest:{service_instance}/data/input/data.zip?checksum={checksum}

4. Save data-id value from the response body for tracking purposes:

   HTTP/1.1 100 Continue HTTP/1.1 201 Created Date: Wed, 07 Nov 2018 10:39:30 GMT Server: Jetty(9.3.6.v20151106) Location: https://my.{region}.fredhopperservices.com/suggest:{service_instance}/data/input/{data-id}/ Content-Type: text/plain Content-Length: 28 Via: 1.1 my.eu1.fredhopperservices.com Vary: Accept-Encoding Connection: close

5. Before the new data-id can be used for triggering a checksum has to be uploaded using the same approach. This checksum file must be named "data.zip.md5", utf-8 encoded, and have the following content:

   <md5sum><space><space>data.zip
   

   An example could be:

   6456235eec7095cc0dcd32ee2308cc4b  data.zip
   

   The checksum file can be generated using the md5sum(1) tool from the GNU CoreUtils package, which should be installed on most Linux systems. A Windows version of the package is available at http://gnuwin32.sourceforge.net/packages/coreutils.htm .

6. Trigger the processing of uploaded Suggest (Blacklist & Whitelist) data by creating a trigger including the data-id of the corresponding upload.

   REST URL:

   https://my.{region}.fredhopperservices.com/suggest:{service_instance}/trigger/generate

   cURL example:

   curl -D - -u "{cloud_username}":"{cloud_password}" -X PUT -H "Content-Type: text/plain" --data-binary "data-id={data-id}" https://my.eu1.fredhopperservices.com/suggest:{service_instance}/trigger/generate

   Example response:

   HTTP/1.1 201 Created Date: Wed, 07 Nov 2018 10:44:17 GMT Server: Jetty(9.3.6.v20151106) Location: https://my.eu1.fredhopperservices.com/suggest:{service_instance}/trigger/generate/{trigger-id} Content-Length: 0 Via: 1.1 my.eu1.fredhopperservices.com Vary: Accept-Encoding Connection: close

7. Monitor the execution following the 'Location' URL and by tracking the newly-created status-file until the status is either SUCCESS or FAILURE.

   REST URL:

   https://my.{region}.fredhopperservices.com/suggest:{service_instance}/trigger/generate/{trigger-id}/status

   cURL example:

   curl -s -D - -u "{cloud_username}":"{cloud_password}" https://my.eu1.fredhopperservices.com/suggest:{service_instance}/trigger/generate/{trigger-id}/status

   Example response:

   HTTP/1.1 200 OK Date: Wed, 07 Nov 2018 10:47:38 GMT Server: Jetty(9.3.6.v20151106) Content-Type: text/plain Content-Length: 227 Via: 1.1 my.eu1.fredhopperservices.com Vary: Accept-Encoding Connection: close SUCCESS