Skip to main content

FAS 8.3 Upgrade Notes

Ernst Vorndran
  • Updated

    Introduction

    FAS 8.3 stays compatible with the previous release in terms of all APIs. The major changes are:

    • Business Manager users now manage personal information and their passwords themselves. A user must also provide and validate their email address before starting work on the Business Manager.
    • Ranking cocktails became scoped entities. They are automatically migrated from business.xml to the shadow configuration copy when the new version of FAS starts the first time.  

    Ranking cocktails

    FAS 8.3 introduces the concept of 'ranking attributes', which are algorithms (or strategies) defined as a special attribute. The first thing represented by this concept is the well-known ranking cocktail. It is a strategy that allows sorting by combining values of a set of attributes. A ranking cocktail can be used in rankings, other rules, and query language and get referenced as a special attribute. Before, ranking cocktails were managed on a dedicated page in the system settings and stored in business.xml. Now they are managed on the 'Ranking attributes' page (under the 'Rankings' tab) and stored in the shadow configuration copy.

    Migration from previous FAS 8 versions

    Migration of ranking cocktails happens automatically when FAS 8.3 starts the first time. The steps are:

    • The previous version of business.xml gets stored in the config/old.<timestamp> directory, so it can be manually restored should anything go wrong.
    • Ranking cocktails are read from business.xml and stored in the config/scopes/shadow/entities/ranking-attributes directory (every ranking cocktail in a separate file).
    • Ranking cocktail's head versions get created in the config/scopes/shadow/history/ranking-attributes directory.
    • Ranking cocktails get published in config/backup/<timestamp>/scopes/xml, so live nodes would be able to read them at the start.
    • Old ranking cocktails get deleted from the business.xml file. All changes in ranking cocktails will be saved in the shadow copy.
    • Please note that ranking cocktails will not be restored if the system settings published before an upgrade get restored after the upgrade.

    Migration from FAS 7 versions

    When any FAS 7 version gets upgraded directly to FAS 8.3, entities migration happens in 2 steps:

    • First, all the entities except ranking cocktails get migrated
    • Then ranking cocktails get migrated. Please note that ranking cocktails that reference invalid attributes will not be migrated.

    Business Manager

    FAS 8.3 takes a major step towards GDPR compliance. Before, users' personal details (display name) and passwords were managed by administrators. Now only users themselves can define their display names and passwords. Every user should also have a validated email address to work with the system.

    Email validation for existing users

    So, after any customer gets upgraded to FAS 8.3.0, every existing user will need to enter and validate their email before starting to work with the Business Manager:

    • When users log into Business Manager the first time after the upgrade, they must enter their email address. This email must be unique (i.e. two users with the same email are not permitted) and valid.
    • After that, the user receives a validation email with the account validation link in the form of a button. When clicked on, the user's email address is considered valid, and the user gets redirected to the Business Manager. If the account is validated within 15 minutes after the email has been sent, the user does not need to log into the system again.
    • Please note that the user's password stays unchanged and can be altered via the user's preferences page.
    • When entering an email address, the user can initiate sending an account validation email a few times. In this case, only the link from the last email will work (all the others will be considered invalid). 

    Creating a new user

    • When an administrator creates a new user, they must enter the user's email and define the role and some preferences (the preferences are the same as in previous FAS versions).
    • After, the invited user receives an invitation email with the account validation link in the form of a button.
    • When the user clicks the button, they get redirected to a special page where they register in the system (by entering their display name, login name and password).
    • After the registration is successful, the user gets redirected to the Business Manager login page and can work with the Business Manager.
    • Note: an admin can re-send the user's invitation. In this case, only the link from the last email will work (all the others will be considered invalid).

    Corner case: the user forgets their password

    Because an administrator cannot manage passwords anymore, and the user cannot enter the system, the account should be deleted by the administrator. Then the administrator invites the user into the system, as described in the previous section. 

    The 'reset password from the login' screen feature is introduced in the release FAS 8.3.1.

    Corner case: sending an email does not work

    In the unlikely case of not working email system, users without validated email addresses may not be able to work with the Business Manager. In this case, the support team can assist. Namely, the user's email should be registered in the BMDB manually.

    Exact steps:

    • Disable configuration sync.
    • ssh to the indexer machine.
    • Stop qserver.
    • Connect to BMDB (there is a great guide about the procedure). In most cases, the following sequence of commands should help: 
      cd /tmp
java -cp '/mnt/deployment-data/installations/fas-assembly-<version>/lib/*' org.apache.derby.tools.ij
connect 'jdbc:derby://localhost:9191//mnt/deployment-data/instances/indexer/data/bizman/db/default;user=admin;password=admin;create=false';
    • figure out the id of a user by their login name and fill in their email 
      update fh_user set email='<user-email>' where name='user-login-name';
1 row inserted/updated/deleted

quit;
    • start qserver
    • enable configuration sync

    Other limitations

    • In FAS 8.3.X, there are no restrictions regarding a user's password
    • In FAS 8.3.0, an account validation link in the email which is sent last never expires. 
      On the contrary, in FAS 8.3.1, an invitation link expires within 24 hours, and a password reset link - in 1 hour.

    Setting up email sending for on-premise customers

    FAS 8.3.1 can send emails through an SMTP server. The configuration to access the SMTP server is stored on a properties file. FAS uses a specific lookup procedure to support the needs of cloud and on-premise customers. The procedure is documented below:

    • If the system property FAS_SMTP_CONFIG_FILE is defined, load the properties file specified by its value.
    • If the environment variable FAS_SMTP_CONFIG_FILE is defined, load the properties file specified by its value.
    • If the config/smtp.properties file exists, load it.
    • If any FH_S3_LDAP_CONFIG_BUCKET_URI or FH_LDAP_CONFIG_LOCAL system properties or environment variables exist, then use the fredhopper-support-access extension to load the LDAP properties file and get the SMTP properties from there. The LDAP properties file is loaded as follows:
    • if the system property or environment variable FH_LDAP_CONFIG_LOCAL is true, load the properties file located at config/$FH_LDAP_CONFIG_FILE, where $FH_LDAP_CONFIG_FILE is the value of the system property or environment variable, or from config/fredhopper-ldap-access.properties by default.
    • otherwise, fall back to loading properties from the Fredhopper cloud, which is not the case for on-premise.

    The following properties are used to configure access to an SMTP server:

    • smtp.hostname = <SMTP server hostname or ip address>
    • smtp.port = <SMTP server port>
    • smtp.username = <SMTP server authentication user name>
    • smtp.password = <SMTP server authentication password>
    • smtp.useTls = true/false/

    Changing the 'from' address

    By default, emails will be sent from no-reply@fredhopper.com. This must be changed for on-premise installations by setting the /com/fredhopper/bm/email@from-address property in system.xml.

    Possibility of not sending emails when working locally

    setting up the extension and email sending could be troublesome when one works with FAS locally. Since FAS 8.3.1, there is a setting which makes FAS log an email validation URL in fredhopper.log instead of sending email: /com/fredhopper/bm/email@suspend-email-sending   false -> true

    The login extension and whole email setup can be omitted if the setting is on.

    Extensions

    fredhopper-support-access 1.3

    This extension is used to provide access to the Business Manager to Fredhopper support staff. Now it is also used to orchestrate sending emails. Without it, users won't be able to start working with the Business Manager. Version 1.3 must be installed for any customer upgrading to FAS 8.3. The details about the extention can be found here.

    Default settings

    Some default settings have changed values or were renamed. It might impact the system's behaviour after the upgrade. Please check the list below.

    Setting: com/fredhopper/query/RankingCocktail@support-match-rate

    Change: false -> true

    Impact: By default, the match rate field is now available in ranking cocktails.

    Action: none

    Related articles

    Comments

    0 comments

    Please sign in to leave a comment.