Page tree
Skip to end of metadata
Go to start of metadata


Standard upgrade

0 - Before you start

It is HIGHLY recommended that you perform a backup of the schema where the extension is running as well as a copy of the current web app (a zip of the web app in the tomcat folder) in order to migrate the old config.yml file to a new one. This is all it takes to roll back the installation if anything goes wrong, you just have to restore the database backup and unzip the webapp. 

1 - Backing up config.yml and default.yml

Before proceeding, you have to save your current configuration files to migrate them to the new version.

  1. These files can be found in the installation path of Write-Back under apache-tomcat/webapps/twbe/WEB-INF/classes/config.yml and apache-tomcat/webapps/twbe/WEB-INF/classes/sites/default.yml. If you have more sites configured besides default you will have to save those as well.
  2. Please save these files to a location that you can access later.

2 - Backing up database driver

Besides configuration files, you'll also have to backup the driver for the database you are currently using; save it to a place that you'll be able to reach later.

  1. It can be found under apache-tomcat/webapps/twbe/WEB-INF/lib. The PostgreSQL driver, for example, is postgresql-42.2.5.jar.
  2. Please save these files to a location that you can access later.

3 - Install the new version and remove the old one

Now after backing up everything you do the installation.

  1. Stop Write-Back Server service
  2. To download the new version simply go to our Support & Resources page and in there you can find the war to download (not the installer) and you should rename it to twbe.war
  3. Go to <installation_path>\apache-tomcat\webapps\
  4. Delete twbe from webapps
  5. Now copy the new twbe.war to the webapps folder

When you download the twbe.war it comes with a version in the file name. We recommend removing the version from the file name, so this way you don't need to update your trex files to the new war name.

5 - Apply your existing configuration and Start Write-Back

Finally you need to restore your existing settings. 

  1. Start Write-Back Server
    1. Notice that a new twbe folder is created
  2. Copy your config.yml and default.yml to the new twbe\WEB-INF\classes and twbe\WEB-INF\classes\sites, respectively.
  3. Copy the database driver to twbe\WEB-INF\lib
  4. Restart Write-Back Server

Upgrading from Release 2.1.x to Release 2.2

Please follow the Standard upgrade instructions.


Upgrading from Release 2.1.2 to Release 2.1.3


Version 2.1.3, contains an important fix for using Active Directory (AD) LDAP. You can check the Release Notes.

With this release we have changed the authentication configuration properties as you can see Manual Installation#2.4-ConfigureAuthenticationMethods

Worth noticing:

  • We removed the method - activedirectory from the available options to configure
  • We enabled ldap configuration to also work with AD.

To upgrade your previous config.yml file that used - activedirectory as an option, in addition to the current properties, you will need to provide a user to bind to the AD. Take a look at the following table:

Release 2.1.2 Release 2.1.3 config.yml
config.ymlsite.ymlconfig.ymlsite.yml
authentication:
  methods:
    - activedirectory
    (...)
 
  active-directory:
    ad-domain: MYCOMPANY.COM
    ad-server: ldap://kerberos-server.mycompany.com:389/
authenticationOptions:
  activeDirectory:
    ldapSearchBase: cn=Users,dc=mycompany,dc=com
    ldapSearchFilter: (userPrincipalName={0})
authentication:
  methods:
    - ldap
    (...)
 
  ldap:
    server-url: ldap://kerberos-server.mycompany.com:389/
authenticationOptions:
  ldap:
    searchBase: cn=Users,dc=mycompany,dc=com
    searchFilter: (userPrincipalName={0})
    principalDn: uid=bindUser,ou=system
    principalPassword: secret

Upgrading from Release 2.0.X to Release 2.1


Version 2.1 brings improvements and new features to 2.0. These include new customization options, optional selection of marks to add data, support for boolean types from Tableau as well as an improved way to deal with Tableau source fields that is much more intuitive and secure. You can find all about this in our Release Notes.

0 - Before you start

It is HIGHLY recommended that you perform a backup of the schema where the extension is running as well as a copy of the current web app (a zip of the web app in the tomcat folder) in order to migrate the old config.yml file to a new one. This is all it takes to roll back the installation if anything goes wrong, you just have to restore the database backup and unzip the webapp. 

1 - Backing up config.yml and default.yml

Before proceeding, you have to save your current configuration files to migrate them to the new version. These files can be found in the installation path of Write-Back under apache-tomcat/webapps/twbe/WEB-INF/classes/config.yml and apache-tomcat/webapps/twbe/WEB-INF/classes/sites/default.yml. If you have more sites configured besides default you will have to save those as well. Please save these files to a location that you can access later.

2 - Backing up database driver

Besides configuration files, you'll also have to backup the driver for the database you are currently using; save it to a place that you'll be able to reach later. It can be found under apache-tomcat/webapps/twbe/WEB-INF/lib. The PostgreSQL driver, for example, is postgresql-42.2.5.jar.

3 - Download the new version and remove the old one

Now, after backing up everything, you can delete the twbe folder and/or twbe.war from apache-tomcat/webapps. 

To download the new version simply go to our Support & Resources page and in there you can find the war download for the version 2.1 (twbe.war). 

4 - Installing the new version

After removing the older version and downloading the new one, you can copy the new war to apache-tomcat/webapps. After that, please restart the server or the service if you installed with the installer (the service is TableauWritebackServer). When the server starts up a folder with the same name as the war should show up. Then, please follow the following steps:

  1. Go inside apache-tomcat/webapps/twbe/WEB-INF/lib and place the database driver here
  2. Go inside apache-tomcat/webapps/twbe/WEB-INF/classes/sites and open the default.yml that is there
    1. Notice that a few new options are there, named themeProperties: dashboardButtonProperties: and look like this:
      1.  
      2. These options are now mandatory and you should add them to the default.yml you currently have or just paste your current settings above these ones. The file should look somewhat similar to this:
      3. default.yml
        themeProperties:
          dashboardButtonProperties:
            colorOptions:
              - colorOption: '#00A2AA'
              - colorOption: '#00373A'
              - colorOption: '#00DCE8'
              - colorOption: '#302B2B'
              - colorOption: '#707070'
              - colorOption: '#8E8C89'
      4. You can copy from here as well. Please pay attention to the indentation of the file.

    2. After performing these changes, save the file in the apache-tomcat/webapps/twbe/WEB-INF/classes/sites/ folder
    3. Then, simply paste your previous config.yml in apache-tomcat/webapps/twbe/WEB-INF/classes/. This file does not require changing.
    4. Finally, just restart the server or service (TableauWritebackServer, if installed with the installer) and you should be up and running again.

If any of these steps fails or you can't get the extension working, please reach us over on our Service Desk.

5 - Upgrade on boolean source fields

If you already have a configuration made with a previous version of Write-Back that contains boolean fields, when upgrading to the new one you will notice that these fields will appear in red on the configuration screen. This is because Write-Back now supports explicitly this type of field, meaning for new configurations they will actually be boolean fields on the database. The side impact is that on previous configurations the type is considered not to match what comes from Tableau. You have 2 options:

  1. Leave it as is, if you just want to add data.
    1. They show up in red in configuration panel, but the functionality of adding data will keep working. However, if you want to edit the dataset configuration, it won't be possible unless you do what is described next.
  2. Manually fix update to Boolean and take advantage of the new feature
    1. You can manually update these values on the database by changing the type of the boolean fields' columns from TEXT to BOOLEAN, on the dataset table, and on widget_field_config table update the value of the FIELDTYPE column to BOOLEAN.


Upgrading from Release 1.2.X to Release 2.0


With the new 2.0 release of our Write-Back extension, we bring you lots of new interesting features that will allow you to further enhance your writing data capabilities and it is aimed to increase your ability to come up with new and creative use cases for when you need to insert data.

Along with the new features, you may see some changes on your datasets tables and metadata to account for the new features to allow for backward compatibility with the previous version. You can find all about this in our Release Notes.

0 - Before you start

It is HIGHLY recommended that you perform a backup of the schema where the extension is running as well as a copy of the current web app (a zip of the web app in the tomcat folder) in order to migrate the old config.yml file to a new one. This is all it takes to roll back the installation if anything goes wrong, you just have to restore the database backup and unzip the webapp. 

1 - Deploy the new war

After you backed up all your data you can now head to the Support & Resources page and download the new version of the extension. To update the war in the tomcat folder please follow the following section Manual Installation#2.8-DeployWarFile.

Update existing version

If you want to take advantage of Write-Back 2.0 and you have previously installed a version 1.2.5 or lower of Write-Back, using our quick installer, and do not intend to proceed with a new installation, you have to do the update manually.

Note

You need to unzip the new war file by yourself and replace the older version in the %INSTALL_PATH%/apache-tomcat-8.5.45/webapps/ folder.

2 - Configuration Changes

Regarding configuration, there are a few changes to consider when upgrading releases. With Release 2.0 we inserted a new configuration option which is the Extension Sites.  The Extension Sites are a tool to further segregate your options regarding persistence and authentication options. 

This changed the content of the WEB-INF/classes folder, in your web app. The content of the configuration file - config.yml - now contains fewer configuration properties since these will be moved to the new site files in the sites folder (which is also in the WEB-INF/classes). You can find detailed information about it in the Manual Installation - Configure Different Sites. The goal with sites is to make available the possibility to configure different options if you'll need to use different resources, which means, you can configure different persistence and authentication options for your widgets.

How to migrate your config.yml file (mandatory)

Here we are providing the before and after configuration files if you do not intend to use multiple sites and wish to maintain everything as it was before the upgrade. This means upgrading a single config.yml file to two files, the config.yml and a default.yml file that will be stored under the sites folder.

Release 1.2.XRelease 2.0
config.ymlconfig.ymlsites/default.yml
persistence:
  type: jdbc
  database:
    driver: driver
    url: url
    username: username
    password: password
    schema: schema

authentication:
  methods:
    - inmemory
    - tableauserver

  tableau-server:
    api-url: https://tableauserver/api/3.5
	site: customSite

  in-memory:
    users:
      - username: user1
        password: user1
      - username: user2
        password: user2
      - username: user3
        password: user3

jwt:
  server-host: yourhotstname.com
  secret-key: SecretKeyToGenerateJWTs
  algorithm: HS512
  expiration-time: 60

security:
  cors:
    enabled: false
    allowed-origins:

license:
  license-key:
authentication:
  methods:
    - inmemory
    - tableauserver

  tableau-server:
    api-url: https://tableauserver/api/3.5

jwt:
  server-host: yourhotstname.com
  secret-key: SecretKeyToGenerateJWTs
  algorithm: HS512
  expiration-time: 60

security:
  cors:
    enabled: false
    allowed-origins:

license:
  license-key:
persistence:
  type: JDBC
  database:
    driver: driver
    url: url
    username: username
    password: password
    schema: schema

authenticationOptions:
  tableauServer:
    site: customSite

  inMemory:
    users:
      - username: user1
        password: user1
      - username: user2
        password: user2
      - username: user3
        password: user3


These changes make you use a "default" site which is the same behavior as when we did not provide this option. To find more about what properties stay on each file, go through our manuals, namely Manual Installation#2.2-ConfigureDifferentSitesManual Installation#2.3-ConfigurePersistenceConnections, and Manual Installation#2.4-ConfigureAuthenticationMethods

3 - Database Changes

With the new release, it also came the need to save some additional metadata in order for everything to work properly. However, we focused on maintaining the same structure and only include new columns and tables. This way we aimed to eliminate the probability of losing data if you end up choosing the same database schema for the new version.

The main functional changes are in the metadata tables widget_config and widget_field_config to the FIELDS_ORDER column. Prior to release 2.0, it would store the New Fields order in a string in the FIELDS_ORDER column on the widget_config table. With the new release and the addition of a Tabular View we also made available the option to order the New Fields as well as the Source Fields. As such, we moved the order to another table, the widget_field_config. 

In widget_field_config table, you will find a column FIELDORDER, which will contain a number indication of where they should be placed, its order. If you deploy the new application under the same schema, at the first run it will populate this new column with the number indication of 1. However, you can manually change this by taking into account the FIELDS_ORDER column that is on the widget_config table.

For instance, consider that we have the following widget configured (in the table below, some columns were omitted for clarity), before 2.0 version. The column FIELDS_ORDER stored a string value containing the name of the columns in an order separated by a semicolon. With the upgrade, you would find the New Fields order close to the fields metadata in the widget_field_config.


Release 1.2.X

after upgrade
Release 2.0


However, the conversion between the two is not automatic. As you can notice the new column is populated with a value of 1 for every field. This means that with the upgrade the order of the fields, from old configurations, needs to be fixed manually if you intend to. When configuring new widgets the FIELDORDER column will be correctly populated with the order you provided. 

How to migrate the field order (not mandatory)

You can manually map the FIELDS_ORDER column in the widget_config table to the new FIELDORDER column in the widget_field_config table through the power of SQL. For instance, for MySQL the following query would do the job:

MySQL Query Example
UPDATE widget_field_config wfc JOIN (
select
	widgetConfigID,
  	fieldOrder,
  	SUBSTRING_INDEX(SUBSTRING_INDEX(oldOrder.fields, ';', fieldOrders.fieldOrder), ';', -1) fieldName
from
 (select 1 fieldOrder union all
   select 2 union all
   select 3 union all
   select 4 union all
   select 5 union all
   select 6 union all
   select 7 union all
   select 8 union all
   select 9 union all
   select 10
) fieldOrders
INNER JOIN (SELECT `FIELDS_ORDER` widgetFieldsOrder, `ID` widgetConfigID FROM widget_config wc) as oldOrder
ON CHAR_LENGTH(oldOrder.widgetFieldsOrder) - CHAR_LENGTH(REPLACE(oldOrder.widgetFieldsOrder, ';', '')) >= fieldOrders.fieldOrder
 ) mapTable
     ON wfc.`WIDGETCONFIGURATION_ID` = mapTable.widgetConfigID AND wfc.`DISPLAYFIELDNAME` = mapTable.fieldName
    SET wfc.`FIELDORDER` = mapTable.fieldOrder WHERE wfc.`WIDGETCONFIGURATION_ID` = mapTable.widgetConfigID AND wfc.`DISPLAYFIELDNAME` = mapTable.fieldName;


This query should map all the old FIELDS_ORDER column values to the corresponding FIELDORDER if the configurations do not have more than 10 New Fields. If they do have more than that, the relevant part of the query to alter is the "union" part, where it should have as many unions as the maximum amount of New Fields existent for any widget.



  • No labels