For 8.3.0

This upgrade includes instructions to add a pepper string and alias to the keystore. See:

• Adding Data to a Keystore for the keystore command syntax and how the keystore works
• Understanding Password Encryption for information about the pepper key and how to ensure user security information is migrated to use the most secure encryption
• Considerations for Pepper Strings for whether or not to use different pepper keys for different instances.

Run the PhixFlow upgrade script

Running the upgrade script makes essential security improvements to passwords.

After upgrading your database in Step 10 of Upgrading PhixFlow, make sure you have sufficient disc space, memory and time to run the PhixFlow upgrade script.  There is advice in the special upgrade instructions for 8.2.0.

Run the PhixFlow upgrade script from the installation directory .../phixflow-version-date/install. To see information about all the options, run the upgrade script with the -help option.

java -jar bin/upgrader.jar -help

The command returns:

[Boot] INFO:  loading properties from one-jar.properties
2021-02-09 10:52:19,475 [main] INFO  phixflow.upgrader.main.UpgraderMain - PhixFlow Upgrade starting
Option              Description
------              -----------
--skip-superceded   Skip upgrading the superceded_dtm column on stream data tables
                      (Oracle only; only use if advised by PhixFlow support)
--help              Print this message
--match-streams     Only streams matching this regexp are upgraded (Oracle only)
--pass              The database password
--test              Test the database connection properties
--upgrade           Upgrade the PhixFlow database schema
--url               The database url, e.g. jdbc:mysql://hostname/database
--user              The database username

To upgrade PhixFlow, run the upgrade script with the -upgrade option, for example.

java -jar bin/upgrader.jar -url="jdbc:mysql://localhost/phixflow" -user=<myuser> -pass=<mypass> -upgrade

After the upgrade script completes, continue with the following configuration steps.

Add a pepper string to the keystore 

PhixFlow now requires a pepper string to be added to the keystore. When a local user sets their password, the pepper string is added to it and the combined string is encrypted. This means user passwords are tied to a PhixFlow instance. 

1. Run the -importpass command, specifying the alias: pepperkey
The alias is case-sensitive. If you use a different alias, update phixflow-instance.xml to use the same alias.

2. When prompted, enter the keystore password.
3. When prompted for the password, enter the pepper string you want to add to user passwords. 
   We recommend this string has the same characteristics as a password. For example it should be a random string containing at least 6 letters, numbers and special characters. 
   Keep a secure record of the pepper sting. 

"%JAVA_HOME%\bin\keytool" -importpass -alias pepperkey -keystore C:\secure\hidden.jks -storetype PKCS12

&"$env:JAVA_HOME\bin\keytool.exe" -importpass -alias pepperkey -keystore C:\secure\hidden.jks -storetype PKCS12

$JAVA_HOME/bin/keytool -importpass -alias pepperkey -keystore /opt/secure/hidden.jks -storetype PKCS12

Merge changes in configuration files

You must create new versions of the following configuration files in $webapp/WEB-INF/classes:

 - phixflow-instance.xml
 - phixflow-datasource.xml
 - phixflow-login.xml
 - phixflow-secret.xml

To do this we recommend you:

1. Rename your existing configuration file, for example by adding a .bak suffix.
2. Follow the Install the PhixFlow Webapp instructions for creating a new file from the.example file provided. 
3. Copy the individual values from your existing configuration file and paste them into the new file.
   Avoid copying entire XML blocks into your new configuration files, as you may overwrite a section of the configuration file that PhixFlow needs.

If you choose to merge the changes from the new .example file into your existing configuration file, the following notes indicate where there are changes.

phixflow-instance.xml

The new section for configuring the pepper alias is required.

<!-- The pepper key is instance specific so extra caution has to be taken when changing the pepper key value in keystore, changing the value in keystore will cause login issue for user's migrated to new password encryption -->

   <util:properties id="instanceProperties">
      <prop key="pepperkey">pepperkey</prop>
   </util:properties>

The default value is pepperkey. If you have multiple PhixFlow instances, each instance must have a pepper string and alias; see Considerations for Pepper Strings.

phixflow-datasource.xml

1. You can no longer specify the database username and password directly in phixflow-datasource.xml.
If you have not already done so, you must add the database username and password to the keystore.
Specify the keys for the username and password in the new bean <bean id="externalCredential" by replacing demo.

<bean id="externalCredential" class="com.accipia.centerview.util.ExternalCredentialProvider">

   <property name="secretService">
      <ref bean="secretService"/>
   </property>
   <property name="usernameKey">
      <value>demo</value>
   </property>
   <property name="passwordKey">
      <value>demo</value>
   </property>

</bean>

2. In <bean id="dataSource" 

• the class name has changed from class="com.accipia.centerview.util.PhixFlowDataSource">
  to class="org.apache.commons.dbcp2.PhixFlowDataSource">
• property name and ref bean have changed from secretService to credentialProvider and externalCredential respectively
• the following lines have been removed, because they are now in the <bean id="externalCredential":
  <property name="username">
   <value>demo</value>
</property>
<property name="password">
   <value>demo</value>
</property>

phixflow-login.xml

1. New <bean id="passwordEncoder" specifies the encryption method for passwords; see Understanding Password Encryption.

2. New <bean id="securityQuestionEncoder" specifies the encryption method for security question.

3. New <bean id="sameSiteCookieFilter". If you use SAML for login, uncomment this.

4. <bean id="exampleAuthenticationOnlySamlAttributeMap" has an additional property: <property name="globalLogout" value="false" />

5. <bean id="idpFileMetadataProvider" has additional property: <property name="requireLogoutResponseSigned" value="true" />

phixflow-secret.xml

1. The new <bean id="keyStoreSecretService" is required.
2. <bean id="secretService" has changed.

After restart, configure datasources and email accounts

After the upgrade is complete and PhixFlow has been restarted, review each datasource instance and email account. For those that require a username and password, we recommend these are stored securely; see the release note on Secure Credentials for Datasource and Email Account.

1. Save the username and password with their alias to the keystore; see Adding Data to a Keystore.
2. In the properties for the datasource instance or email account:
   1. Set Authorisation Type External.
   2. Add the aliases to the Username Key and Password Key fields.

For 8.3.13

Update LibreOffice

If you are generating PDF documents, upgrade LibreOffice to version 7.2.5.

For 8.3.17

New Privilege

There is a new privilege Release Exclusion Groups which controls access to the Administration Menu action Release Exclusion Group. This privilege will need to be added to the user(s) and/or groups who require access to the Release Exclusion Group administration menu option. 

For 9.0.0

Create new PhixFlow configuration files:

1. You must create new versions of the following configuration files in your ../webapp/WEB-INF/classes directory:

   1. logback.xml

   2. phixflow-datasource.xml

   3. phixflow-instance.xml

   4. phixflow-logging.xml

   5. phixflow-login.xml

   6. phixflow-secret.xml

2. To do this:

   1. Rename your existing configuration files, for example by adding a .bak suffix.

   2. Follow the Install the PhixFlow Webapp instructions for creating a new file from the ".example" files provided. 

   3. Copy the individual values from your existing configuration files and paste them into the new files.

      1. Avoid copying entire XML blocks into your new configuration files, as you may overwrite a section of the configuration file that PhixFlow requires.

For 9.0.1

If you are upgrading from 9.0.0 please check that the migration script from 8.3.20 to 8.3.21 has been run. If it has been run there will be a column export_file_formats_enum in table stream_view. If this column does not exist you must run the 8.3.20 to 8.3.21 migration script before running the 9.0.0 to 9.0.1 migration script.

For 10.0+

Create new PhixFlow configuration files

You must create a new version of the following configuration file in your <tomcat>/webapps/phixflow/WEB-INF/classes directory:

1. phixflow-instance.xml

 To do this:

1. Rename your existing configuration file, for example by adding a .bak suffix.

2. Follow the Install the PhixFlow Webapp instructions for creating a new file from the ".example" files provided. 

3. Copy the individual values from your existing configuration files and paste them into the new files.

   1. Avoid copying entire XML blocks into your new configuration files, as you may overwrite a section of the configuration file that PhixFlow requires.

Database Upgrader

Run the upgrader from the command line once you have run the migration scripts and taken a suitable backup of your PhixFlow Database:

1. Open the command line tool as an administrator.
2. Within the Version 10 installation directory navigate to the directory holding upgrader.jar.
   1. For example, \desktop\PhixFlow10\install\bin
3.   Run the following command:
   1. java -jar upgrader.jar --upgrade --path=<tomcat>\webapps\phixflow\WEB-INF\classes
      1. Where <tomcat> is the location where tomcat is installed. 

JWT Token for API Authentication (Optional)

PhixFlow Version 10 supports incoming API access, this can be either anonymous or authenticated.  To use Authentication for an API coming into PhixFlow, a signing key is used to generate the PhixFlow API key and this is stored on the server to ensure secure access.

Using the page Configure a Keystore and Aliases, configure phixflow-api-key to be used as the signing key for PhixFlow API Keys in the same way as pepperKey is configured. This secret string must be a minimum of 32 bytes length. Full API details can be found on PhixFlow Incoming API.

Application Template Package (Optional)

To be able to use the new features in Version 10 it is recommended that you install the Serene Grey Template Package. See Installing Template Packages.

For 11.0+

File Table Upload Location

To use the new File Display component which facilitates the uploading of files by dragging and dropping files onto a PhixFlow screen, the following setup is required:

1. On your PhixFlow server, create a directory where the files can be stored. This should be created alongside the other System Directories and be accessible to the application. See Minimum Setup for configuring System Directories.
   1. For example,  /opt/phixflow/data/file
2. In PhixFlow, from the  Administration menu, open System →  Configuration
   1. In the System Directories section → File Table Upload Location field, add the address of the directory setup in the first step, e.g. /opt/phixflow/data/file
   2.  save your changes
3. All uploaded files will now be placed in this directory. The directory should be backed up in line with your local policy.

For 11.1.1

(DEV-16708) HTTP Headers on HTTP actions have been updated to ensure correct capitalisation e.g. contenttype will become Content-Type. Due to this amendment existing Actionflows should be reviewed and any access to returned HTTP Header values should be adjusted to use the correct capitalisation if they do not currently use standard header capitalisation.

(DEV-17452) As part of the upgrade, all Actionflows that previously were configured as API Endpoints have been converted to the new API Endpoint type Actionflow. For the endpoint to return data, the response body needs to be mapped to the output body attribute in the new API Endpoint.

For 11.3.0

DEV-18280 File Record Gallery

Ensure the default field in 'Application Properties' → 'Styles' tab → 'Default Components' → 'Default File Display Gallery Component' is set. Or if you usually set this via the System Configuration, set this in 'System Configuration' → 'Styles' tab → 'Default Components' → 'Default File Display Component'.