Skip to main content

File API

Jess Garlick
  • Updated

    File API

     This page explains the Fredhopper Services File API.

    Background

    The Fredhopper Services API is the way to upload/download data to your Fredhopper Service, e.g. the latest sales data to be indexed by your FAS Service. You can also trigger and track commands, e.g. start a re-index with the latest data upload.

    URL

    The Fredhopper Services API is accessible via my.<region>.fredhopperservices.com.

    You can upload/download data and trigger commands by uploading files via FTP (passive mode) or via HTTPs.

    The following examples securely uploads a file with HTTPS using the open-source tool LFTP:

    lftp -u <CUSTOMER>,<PASS> https://my.eu1.fredhopperservices.com/<CUSTOMER>/
cd <FOLDER>
mkdir <FOLDER>
mput /path/to/file/to/upload
quit

    LFTP offers the same commands like FTP but is secure and can be easily scripted.

    Folder Structure

    The Fredhopper Services API offers the following folder structure:

      Folder Description
    Data Input input/<service>/<service instance>/<data-id>/ Folders in which you drop data for processing. You have to provide a unique data ID, e.g. the timestamp or a fixed name like current. For example: The input for your live Fredhopper instance is at input/fas/live1/2009-10-01_09-00-00/.

    When uploading data for incremental updates, it is recommended to add '_incremental' to the data-id. For example: input/fas/live1/2009-10-01_09-00-00_incremental/.
      input/<service>/<service instance>/<data-id>/data.zip

    For incrementals:
    input/<service>/<service instance>/<data-id>/data-incremental.zip    		 Data to be loaded. When the zip file represents a full data set, the file is called data.zip. For example: The full data for your live Fredhopper instance is at input/fas/live1/2009-10-01_09-00-00/data.zip.

    When the date represents an incremental update, the file name is data-incremental.zip.
      input/<service>/<service instance>/<data-id>/data.zip.md5

    For incrementals:
    input/<service>/<service instance>/<data-id>/data-incremental.zip.md5    		 MD5 checksum of the file data.zip or data-incremental.zip. For example: input/fas/live1/2009-10-01_09-00-00/data.zip.md5.
    Data Output output/<service>/<service instance>/<command-id>/ Folders in which Fredhopper drops data for you after triggering a certain command (may be also a scheduled command). 
      output/<service>/<service instance>/latest/ Points to the latest output folder, e.g. for your latest data
    Trigger Commands trigger/<service>/<service instance>/<command>/<command-id> Folders in which you trigger commands. You have to provide a unique command ID for each command that you trigger. This allows you to track the progress in the track folder. You may use a timestamp to ensure uniqueness. For example: To load data into Fredhopper you have to drop a file at trigger/fas/live1/load-data/2009-10-01_12-00-00.
    Track Commands track/<service>/<service instance>/<command>/<command-id>/ Read-only folders in which Fredhopper provides feedback on executed commands. For example: Fredhopper would provide feedback to your Fredhopper load-data request at track/fas/live1/load-data/2009-10-01_12-00-00.
      track/<service>/<service instance>/<command>/<command-id>/<command-id> Original command file dropped in the trigger folder. For example: Fredhopper provides a file track/fas/live1/load-data/2009-10-01_12-00-00/2009-10-01_12-00-00.
      track/<service>/<instance>/<command>/<command-id>/status Provides summary feedback on the outcome of your command. For example: Fredhopper provides a file track/fas/live1/load-data/2009-10-01_12-00-00/status with value SUCCESS.
      track/<service>/<instance>/<command>/<command-id>/logs/ Provides detailed feedback on the outcome of your command. For example: Fredhopper provides files in track/fas/live1/load-data/2009-10-01_12-00-00/logs/ stating each command that was executed.

    Commands

    This section explains all commands that Fredhopper Services API supports. You need to write a command file to trigger a command. The command parameters are passed within the command file in the .properties format.

    Supported commands:

    Load-data (was: reindex)

    Starts the data loading process

    Services

    This command is available for the fas service.

    Folder

    trigger/fas/<instance>/load-data/

    Parameters

    Parameter Description Examples
    data-id (required)
    • List of IDs pointing to the input data to be used.
    • IDs ending on _incremental refer to incremental data updates
    • Only one data ID can refer to a full data set.
    • The data sets from the data-id property are applied in the order they are given. A trigger that refers to both full and incremental data sets.
    		 2010-01-13_18-57-00, 2010-01-13_19-00-00_incremental, 2010-01-13_20-00-00_incremental

    If the trigger refers to a data ID that represents a full data set the current data will be wiped, and the full data and all increments will be used as XML. Otherwise the incremental data sets are applied to the currently loaded data.

    Response

    Fredhopper provides in the file track/<service>/<instance>/load-data/<command-id>/status information about the execution of the trigger. The file contains a status code in the first line, and the following lines can contain a detailed description of the status.

    All status codes are documented in the Trigger Status Reference, the more typical codes are listed here:

    Status Description
    SCHEDULED Command will start execution soon
    RUNNING Command is still executing
    SUCCESS Command was executed successfully
    FAILURE Command was not executed successfully

    FAS is only updated if and only if all data sets from the trigger have been successfully processed. A failure in processing of any data set will result in failure of the job.

    Usage example

    The following example assumes that you use timestamps as data-IDs.

    1. Upload yesterday's data: Upload a data dump to input/fas/live1/2009-09-30_01-00-00/
    2. Upload a full data set for today: Upload a data dump to input/fas/live1/2009-10-01_01-00-00/
    3. Upload an incremental data file for today: Upload a data dump to input/fas/live1/2009-10-01_01-00-00_incremental/
    4. Reindex today's data: Write a file trigger/fas/live1/load-data/2009-10-01_12-00-00 containing the data-ID of the input data 2009-10-01_01-00-00.
    5. trigger/fas/live1/load-data/2009-10-01_12-00-00
      data-id=2009-10-01_01-00-00
    6. Add incremental update: Write a file trigger/fas/live1/load-data/2009-10-01_12-01-00 containing the data-ID of the input data 2009-10-01_01-00-00_incremental.
      trigger/fas/live1/load-data/2009-10-01_12-01-00
      data-id=2009-10-01_01-00-00_incremental
    7. Rollback to yesterday's data: Write a file trigger/fas/live1/load-data/2009-10-01_12-05-00 containing the data-ID of the input data 2009-09-30_01-00-00.
      trigger/fas/live1/load-data/2009-10-01_12-05-00
      data-id=2009-09-30_01-00-00

       

    Related articles

    Comments

    0 comments

    Article is closed for comments.