Interface

The Recommendation Engine (abbreviated as Gravity Reco) offers the possibility to generate recommendations for off-line usage, such as a newsletter sent out periodically. The image below offers a quick glance at how the system works:

The FTP Server is operated by gravity and our clients get access by ordering our batch processing API. This is the place where the customer will upload his recommendation requests and from where he may download the results for those.
For communicating with the Reco servers tab-delimited and XML files are used. These will be transferred over the network by using the FTP or SFTP protocol.

The following sections contain information on the exact usage details, like the work flow of transferring the files and file formats to use.

Batch recommender workflow

Customer	Gravity
1/ Uploading the recommendation request 1. Create a marker file named RecommendationRequests-YYYYMMDD_HHMMSS.upload 2. Upload the recommendation request file named RecommendationRequests-YYYYMMDD_HHMMSS.tsv the file format is described below. 3. Rename the marker file from RecommendationRequests-YYYYMMDD_HHMMSS.upload toRecommendationRequests-YYYYMMDD_HHMMSS.go 4. No further modifications are allowed to the marker and tab-delimited file after step 3.	1/ Waiting for the recommendation request 1. Check every 5 minute or so (configurable on request) for the presence of go marker files.
2/ Waiting for the recommendation result 1. Check for a marker file with finished extension.	2/ Processing the recommendation request 1. For every found marker file (RecommendationRequests-YYYYMMDD_HHMMSS.go) it will rename it to a processing extension (RecommendationRequests-YYYYMMDD_HHMMSS.processing) and start creating the answer XML files. 2. Once done the XML file will be uploaded to the ItemRecommendations folder besides the marker file. The name of the answer file is ItemRecommendations-YYYYMMDD_HHMMSS.xml 3. Move the tab-delimited file RecommendationRequests-YYYYMMDD_HHMMSS.tsv to the processed folder besides the marker file. 4. Create a report file inside the processed folder containing the statistics and errors found during the Reco serving the customers batch recommendation request. Its name is the marker name with log extension:RecommendationRequests-YYYYMMDD_HHMMSS.log 5. Rename the marker file to have a finished extension. RecommendationRequests-YYYYMMDD_HHMMSS.finished
3/ Download the recommendations 1. For every found marker file RecommendationRequests-YYYYMMDD_HHMMSS.finished there is an ItemRecommendations-YYYYMMDD_HHMMSS.xml file in the ItemRecommendations folder which should be downloaded. Format is specified below.

📘
NOTE:
Depending on the size of the customers item and user database the second phase may turn out to be quite lengthy (one to three hours). Take this into consideration when you are planning just how often do you want to request batch recommendations.

📘
NOTE:
To avoid long and single burst data transfer we recommend splitting the recommendation requests into 5,000-10,000 request chunks. The above process is valid for one single chunk. The customer needs to go through the work flow for each and every batch. To differentiate between two recommendation requests (batches) we use a date based naming convention. The batch interface of the Reco communicates with the FTP server through the existence and name of the files on the FTP server. The process is guided by the presence and the name of a special file, also refereed to as the marker file.

Recommendation request file

The recommendation engine accepts batch recommendation requests in tab-delimited format. For the description of this format, see the Tab-delimited item example page.

In addition:

In this case each line contains a recommendation request.
The userId and scenarioId columns are mandatory. The others are optional.

For example, to get NEWSLETTER scenario recommendations for users 1 and 2, a valid request file specifies in its first row the name of the columns and then follows it up with enumerating the values corresponding to those:

userId	scenarioId
1	NEWSLETTER
2	NEWSLETTER

If the recommendation request has another parameters, you can add them as columns. Column name considers the key (name of the attribute), column values are the attribute values. Example:

userId	scenarioId	categories_to_exclude	numberLimit	Gender
1	NEWSLETTER	fashion,electronics	10	Male
2	NEWSLETTER	fashion	10	Female

NOTE: These additional parameters only have an influence on the recommendation result if the usage of the parameter is built in the scenario logic.

If the result should contain additional item properties beside the item ID-s (like in the example below) please add the name of those properties in additional columns:

userId	scenarioId	categories_to_exclude	numberLimit	Gender	resultName	resultName	resultName
1	NEWSLETTER	fashion,electronics	10	Male	imgUrl	price	category
2	NEWSLETTER	fashion	10	Female	imgUrl	price	category

Recommendation answer file

The answer file for a recommendation request is an XML file (ItemRecommendations 1 0.xsd).

The file contains recommendations for every requested user. For example, in case of the upper request file a valid answer may be:

<recommendations xmlns="http://schemas.gravityrd.com/receng/itemRecommendations_1_0.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"                
xsi:schemaLocation="http://schemas.gravityrd.com/receng/itemRecommendations_1_0.xsd itemRecommendations_1_0.xsd">
    <!-- One recommendation item for each recommendation -->
    <recommendation recommendationId="j4edn6m1-59pj6p0lreu-S.NEWSLETTER.C.c91_a92-1eomy5w">
        <!-- The original recommendation request can be included -->
        <request>
            <userId></userId>
            <cookieId></cookieId>
            <scenarioId></scenarioId>
            <numberLimit>1</numberLimit>
            <properties>
                <property name="filter.category" value="100"/>
            </properties>        
        </request>
        <items>
            <!-- The list of recommended items -->
            <item itemId="1" predictionValue="0.4" modifiedPredictionValue="1.2">
                <itemProperties>
                    <property name="title" value="Example Item Title 1"/>
                    <property name="product" value="Product"/>
                    <property name="imgUrl" value="http://webshop.example.com/img1.jpg"/>
                    <property name="price" value="10.0"/>
                    <property name="category" value="100"/>
                </itemProperties>
            </item>
            <item itemId="2" predictionValue="0.5">
                <itemProperties>
                    <property name="title" value="Example Item Title 2"/>
                    <property name="product" value="Product"/>
                    <property name="imgUrl" value="http://webshop.example.com/img2.jpg"/>
                    <property name="price" value="20.0"/>
                    <property name="category" value="100"/>
                </itemProperties>
            </item>
        </items>     
    </recommendation>
</recommendations>

FTP interface set up and configuration

This is done solely on request by the Gravity R&D staff. May the customer wish to use this feature he will need to contact the Gravity R&D personal [email protected].

Batch

Interface

Batch recommender workflow

📘
NOTE:

📘
NOTE:

Recommendation request file

Recommendation answer file

FTP interface set up and configuration

Interface

Batch recommender workflow

📘NOTE:

📘NOTE:

Recommendation request file

Recommendation answer file

FTP interface set up and configuration

📘
NOTE:

📘
NOTE: