Recommendations Application (EXPERIMENTAL)

Last modified by Yann Flory on 2021/03/17 21:10

cogProvides a list of recommended pages based on the users' histories
TypeXAR
CategoryApplication
Developed by

Yann Flory

Rating
1 Votes
LicenseGNU Lesser General Public License 2.1

Installable with the Extension Manager

Description

https://raw.githubusercontent.com/xwiki-labs/xwiki-labs-logo/master/projects/xwikilabs/xwikilabsproject.png

The extension requires an "easyrec" server to work. easyrec is an open-source recommendation engine.

This is an experimental extension, performance and pertinence issues may appear. Data collected by the recommendation engine may not be compatible with future versions of the extension.

Recommendations types

The Recommendations Application add the ability to recommend content to XWiki users, by listing pages that could be interesting for them in a panel.
There are 2 types of recommendations : 

  • User-based recommendations : Create links between pages based on the users' histories. Recommendations will then depend on what other users have visited or edited in the wiki.
  • Content-based recommendations : The engine needs to know the page the user is currently reading and it will recommend pages with a similar content or metadata (most frequent words of the page, title, tags, author and space).

User-based recommendations are provided in this application.
Content-based recommendations can also be added if you install the content-based recommendations extension upgrade.

Configuration of the external recommendation engine

Install easyrec

To use the Recommendations application, you have to install an easyrec server (the recommendation engine). easyrec can be downloaded here, and it is recommended to follow the easyrec installation guide.

Once the server is set up, you can enter the management section of the web interface of easyrec and create a new Tenant for your XWiki installation. You have to choose a tenant id ("xwiki" for example) and enter the xwiki server address in the URL field.

Configuration of the extension in XWiki

Once you have install the extension with the Extension Manager, you can go to the wiki administration (XWiki.XWikiPreferences), section Applications/Recommendation Engine.
Here you have to link your XWiki server to your easyrec server. You just have to specify :

  • the easyrec server address
  • the tenant id you have just created in easyrec
  • the easyrec API key (available in the easyrec web interface / management section)
    You can also choose to disable the recommendations. If you do so, you won't receive recommendations in the panel and easyrec won't receive data about the users' histories anymore.

You now just have to install the panel and choose the maximum number of pages recommended in that panel and if everything has been done properly, the recommendation engine should start receiving data each time a user visits a page.

Recommendations are computed every day at 2.00 a.m. by default so you won't receive recommendations instantly. If you don't want to wait, you can trigger the recommendations plugins manually in the easyrec administration (at the top of the page in easyrec web interface) : go to the "Tenants" page and click on the "start plugin" icon in your tenant line.

Recommendations in a wiki farm

If you are using a wiki farm and you want to be able to receive recommendations across all the wikis, you can simply install the extension on the whole farm with the extension manager, and configure it only in the main wiki :

  • make sure "Allow subwikis to use this configuration" is enable
  • add the Panel in all wikis with a single click

If you want one of your subwikis to have its own recommendations (not shared with the other subwikis), you can also go to the wiki administration of that subwiki, section Application/Recommendation Engine and :

  • Disable "Use the main wiki configuration (in case of a wiki farm)"
  • Specify the easyrec server to use, the API key and the tenant. You can just create a new tenant for that wiki in the easyrec management and the recommendations will be separated. You don't need a new server.

Configure easyrec to have better user recommendations (optionnal)

Without modification, the extension is able to make personalized recommendations based only on the pages visited by the user. However, the extension is also able to deal with edited pages and, to do so, in the easyrec management you have to :

  • add an "EDIT" action type
  • add a "CREATE" action type
  • and an "EDITED_TOGETHER" association type.
    You can do it in easyrec web interface, by clicking on your tenant id and going in the "Type manager" part.

Then, you have to configure your tenant to tell it what is an association "EDITED_TOGETHER" between two items. Go to the "Administration" part on top of the page and then on the "Tenant" tab and click on the "configure tenant" icon in your tenant line :

easyrecTenantConfig.png

Here you can select the ARM plugin for the EDITED_TOGETHER association type, and change its settings to link it with the "EDIT" action. You can also change the "minimum absolute support", which represents the number of differents users who have to edit the 2 same pages before easyrec considers the pages as "EDITED TOGETHER" and starts using that link to make recommendations. You can also change the "minimum absolute support" for the "VIEWED_TOGETHER" association type.

easyrecEditSimilaritiesConfig.png

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki
Tags:
    

Get Connected