Architecture of FOS Recommendation Engine

To provide a recommendation to a customer, certain data is required based on which the recommendations are predicted. The data needs to be fed to the Data-Processing unit.

Following are the various layers of the Data-Processing unit:

Data-Mapper Engine

The first layer of the data processing unit is Data-Mapper Engine. Data such as customer information, purchase history is provided through ERP system or REST APIs to this engine in CSV or JSON format.

The following components are part of the Data-Mapper Engine.

  • Data Mapper: Submit the customer’s transactional data such as product Id, customer Id, transaction Id, or sample data to do the mapping.

  • Data Publisher: Publish the customer’s transactional data by providing the data mapper details created through the Data Mapper API.

Data Mapper APIs

Method: HTTP POST

Endpoint: http://<host_address>:<port_address>/v1/jsonDataMapper or
http://<host_address>:<port_address>/v1/csvDataMapper

Data Mapper Parameters
Parameter Cardinality Description
productIdMapper Mandatory The product Id of the mapper.
customerIdMapper Mandatory The customer Id of the mapper.
transactionIdMapper Mandatory The transaction Id of the mapper.
dataMapperName Mandatory This is the name of the data mapper that is created once the API is executed. You can provide a desired name here.
Request body Mandatory Provide a sample data here.

Sample:

{
	"id": "PO_TV",
	"href": "https://host:port/productInventoryManagement/v4/product/g265-tf85",
	"description": "product description",
	"isBundle": false,
	"isCustomerVisible": true,
	"name": "Voice Over IP Basic instance for Jean",
	"productSerialNumber": "N/A",
	"orderDate": "2017-11-01T09:37:29.961Z",
	"startDate": "2017-11-01T09:37:29.961Z",
	"status": "active",
	"@baseType": "Product",
	"@type": "Product",
	"@schemaLocation": "https://host:port/standardProduct.json",
	"relatedParty": [
		{
			"id": "Cust_01",
			"href": "https...",
			"name": "Jean",
			"role": "User",
			"@referredType": "Individual"
		}
	]
}

Data Publisher APIs

Method: HTTP POST

Endpoint: http://<host_address>:<port_address>/v1/publishJsonData or
http://<host_address>:<port_address>/v1/publishCsvData

Data Publisher Parameters
Parameter Cardinality Description
dataMapperName Mandatory Name of the data mapper that you have created through Data Mapper API.
dataMapperVersion Mandatory Version of the data mapper that you have created through Data Mapper API.
Request body Mandatory Provide a sample data here.

Sample:

Sample as below:

{
	"id": "PO_TV",
	"href": "https://host:port/productInventoryManagement/v4/product/g265-tf85",
	"description": "product description",
	"isBundle": false,
	"isCustomerVisible": true,
	"name": "Voice Over IP Basic instance for Jean",
	"productSerialNumber": "N/A",
	"orderDate": "2017-11-01T09:37:29.961Z",
	"startDate": "2017-11-01T09:37:29.961Z",
	"status": "active",
	"@baseType": "Product",
	"@type": "Product",
	"@schemaLocation": "https://host:port/standardProduct.json",
	"relatedParty": [
		{
			"id": "Cust_01",
			"href": "https...",
			"name": "Jean",
			"role": "User",
			"@referredType": "Individual"
		}
	]
}

Datastore Engine

Data store mainly has GraphQL APIs to perform data operations in Redis. All other services' Data Mapper, Recommendation Engine Core, and Recommendation Engine APIs call Data Store Engine to save, retrieve, or delete different data.

Example: Recommendation Data Mapper calls Data Store Engine to save data mapper and also saves sanitized customer's transactional data. Recommendation Engine Core calls GraphQL APIs to fetch customer data and saves calculated association rules in Redis.

Apart from GraphQL APIs for CRUD operations on data, Data Store Engine has REST APIs to perform CRUD operations on PMML.

Predictive Model Markup Language (PMML) Model

This functions in a similar to the algorithms that work in python. The PMML 4.4 version is supported and the Naive Bayes and k-Nearest Neighbors classifications are used as of now. You need to create and train PMML model by using data science tool. For more information on PMML, see https://dmg.org/pmml/v4-4-1/GeneralStructure.html

Note: If PMML is present in your system, then it has the priority over core algorithms. If PMML is note present, then only the core algorithms are applied.
Data Store Engine PMML Controller APIs
Make specific version of PMML Model file active

Method: HTTP PUT

Endpoint: http://<host_address>:<port_address>/v1/pmml/{version}

 
Parameter Cardinality Description
Version Mandatory Version of the pmml file.

Delete specific version of PMML Model file

Method: HTTP DELETE

Endpoint: http://<host_address>:<port_address>/v1/pmml/{version}

 
Parameter Cardinality Description
Version Mandatory Version of the pmml file.

Download All PMML Model Files for Tenant ID

Method: HTTP GET

Endpoint: http://<host_address>:<port_address>/v1/pmml

Upload PMML file

Method: HTTP POST

Endpoint: http://<host_address>:<port_address>/v1/pmml

Request body: Browse the pmml file that you want to upload.

Get metadata of All PMML Model Files for Tenant ID

Method: HTTP GET

Endpoint: http://<host_address>:<port_address>/v1/pmml/metadata

Download Active PMML Model Files for Tenant ID

Method: HTTP GET

Endpoint: http://<host_address>:<port_address>/v1/pmml/active

Core Engine

This is a python based micro service. By default, Recommendation Core Engine has Apriori and Cosine Similarity algorithms. The core engine applies these two algorithms if there is no active PMML present in the system.

The Apriori algorithm runs on the customers' transactions and generates association rules for the products. In contrast, the Cosine Similarity algorithm runs on the customers’ catalog and generates similar products.

If active PMML is present in the system, core engine processes PMML and generates customer predictions for customers’ transactions.

Recommendation Engine API generates recommendations based on association rules, similar products, and customer predictions.

This service has the following rule APIs:

Note: The Find Association Rule and Calculate Product's Similarity APIs run in the background asynchronously at the schedule time created by the user.

Find Association Rules

Method: HTTP GET

Endpoint: http://<host_address>:<port_address>/v1/findAssociationRules/sync

The tenantid field is mandatory.

Calculate Product's Similarity

Method: HTTP GET

Endpoint: http://<host_address>:<port_address>/v1/calculateProductsSimilarity/sync

The tenantid field is mandatory.

Note: The responses from these sync APIs are not stored in a data store, this is just for viewing.

Schedule Job

The actual customer's data is huge, where the algorithms are applied to provide the recommendations. Hence this action cannot be synchronous. A specific time window has to be provided for the recommendation system to work on. A start job and stop job can determine the required time window.

Schedule Job Start

You can schedule the job start time for each tenant.

Method: HTTP POST

Endpoint: http://<host_address>:<port_address>/v1/schedule/job/start

The tenantid and cron_schedule fields are mandatory.

The tenantid is the ID of the tenant for which job needs to be scheduled.

The cron_schedule is a Linux command used for scheduling tasks to be executed sometime in the future. This is normally used to schedule a job that is executed periodically. Example: to send out a notice every morning

This is used for updating jobs that are already scheduled.

For example, if a Job for tenant TIBCO is scheduled to run at 1 PM daily and later the user wants to change the schedule to run it at 2 PM daily, then POST API is called. Here, you have to add the same tenant ID and different cron_schedule for the tenant.

Schedule Job Stop

When you want to stop the cron job of the already scheduled tenant, then use this API.

Method: HTTP POST

Endpoint: http://<host_address>:<port_address>/v1/schedule/job/stop

The tenantid field is mandatory.

Recommendation Engine API

List or find query product recommendation objects

Method: HTTP GET

Endpoint: http://<host_address>:<port_address>/v1/queryProductRecommendation

 
Parameter Cardinality Description
recommendationPageNo Mandatory Recommendation page number
numberOfRecommendationsPerPage Mandatory Number of recommendations per page

Create query product recommendation

Method: HTTP POST

Endpoint: http://<host_address>:<port_address>/v1/queryProductRecommendation

 
Parameter Cardinality Description
noOfSimilarProducts Mandatory Number of similar products
Request body Mandatory Provide a sample data here

Note: If the instantSyncRecommenation flag is true, the recommendation is saved and also added in the response. If it is false, recommendation is only saved.
List or find query product recommendation objects

Method: HTTP GET

Endpoint: http://<host_address>:<port_address>/v1/queryProductRecommendation/{Id}

 
Parameter Cardinality Description
id Mandatory Id of the query product recommendation