Upgrading the Webtrends SharePoint Tag Installers

Products

SharePoint 2013+ (all versions)
SharePoint Online (aka Office 365)

Cause

Webtrends provides multiple products in order to install analytics tracking code into your SharePoint environment. Due to new feature enhancements and fixes, upgrading the products from time to time is advised. Depending on the version and ?view? of SharePoint you are using, you may need to upgrade more than one product in your environment.

Classic
The Webtrends SharePoint Classic View Tag Installer, also known as the Webtrends SharePoint App, is a ?Classic View? app or Add-in that provides a User Interface to configure and insert the Webtrends tracking JavaScript into Classic Pages using User Custom Actions.

This app/add-in is available for, and the same file for SP2013, SP2016, SP2019, and SPO.

The app/add-in is scoped to the site collection. You should not install the app/add-in on sub sites.

Modern
The Webtrends SharePoint Modern View Tag Installer, also known as the Webtrends SharePoint App Extension, is a SharePoint Framework application customizer ?app extension? that inserts Webtrends tracking JavaScript into Modern View pages. The new Modern View available in both SP2019 and SPO. The Modern experience does not use User Custom Actions, and as such the Classic App described above is unable to track these pages. The app extension provides the ability to track these pages in addition to the Classic pages.

Due to differing support of the SharePoint Framework in SP2019 vs. SPO, two separate app extension products are available from Webtrends. Both implement the same underlying tracking JavaScript, which is also the same as the Classic app.
App extensions do not provide a User Interface to facilitate configuration of the tracking code. Therefore, the app extension products currently rely on the parallel installation of the Webtrends SharePoint Classic View Tag Installer in order to provide the configuration lists. You must currently install both the classic and modern apps on a modern site collection in order to enable tracking.

App extensions are scoped to the web scope by default. As a result, you must install app extensions on both the site collection root and any sub sites.

The constantly evolving nature of Modern View in SharePoint Online means that upgrading the extension is more frequently needed that On Premise versions of SharePoint.

Resolution

Upgrading the Classic App
With most apps/add-ins, you can update the package in the app catalog, and then use the Update link on each site collection to upgrade the app/add-ins. Unfortunately, we have found that this process does not properly update the configuration list schema of the Webtrends app. As such, it is recommended to
perform a complete uninstallation and reinstallation of the app/add-in on the site collection in order to ensure that the configuration lists contain the latest available features.

Note:

If you are not using Modern sites, you may alternatively use the Webtrends SharePoint Tag Administrator tool available on our website to perform these same actions against one or more site collections.

If you are using Modern sites, this tool does not currently communicate with Modern site collections and can only be used for Classic sites.

A replacement tool that supports Modern sites is currently being developed.

1. Download the latest Webtrends SharePoint Classic Tag Installer from www.webtrends.com/support/downloads.
2. Extract the .zip to a desired location.
3. Open a browser to the app-catalog site collection for your tenancy.
4. Replace the Webtrends SharePoint Tag Installer.app with the new version found in the extracted zip.
5. Visit a site collection where the Classic App has been installed.
6. Open the Site Contents page.
7. Click on the Webtrends SharePoint Tag Installer text link.
8. Note the current configuration settings, in particular the DCSID and Desired Extension CDN Path, as all settings be replaced with the defaults during reinstallation.
9. On the General tab, click Retract Webtrends SharePoint Tag Installer.
   1. This will remove the following from the site collection:
      1. The User Custom Action
      2. The WebtrendsAssets document library folder and tracking JS.
         1. If this is a SPO Modern site where custom JS has been disabled, the User Custom Action and folder may not exist.
10. Return to the Site Contents page.
11. Remove the Webtrends SharePoint Tag Installer app.
    1. You will need to switch to Classic experience if you are currently viewing the Modern Site Contents page.
12. Click Add an app.
13. Reinstall the latest Webtrends SharePoint Tag Installer app found within the app-catalog.
14. After installation, click on the Webtrends SharePoint Tag Installer text link to open the configuration.
15. Reset the configuration settings to the values as noted in step 8.
16. Check Enable tracking.
17. Click Save.
    1. This will re-add the following to the site collection:
       1. The User Custom Action
       2. The WebtrendsAssets document library folder and tracking JS.
          1. If this is a SPO Modern site where custom JS has been disabled, the User Custom Action and folder may not be created.
             1. You will also see an error regarding Permissions that can be ignored.
18. Repeat for each Site Collection

Upgrading the Modern App Extension
Upgrading the App Extension does not officially require that the Classic App is also upgrading. It is possible to simply replace the app extension deploy files (see below) and immediately update Modern pages. However, to obtain the latest features and bug fixes for all views of SharePoint, it is recommended to also upgrade the Classic App on each site collection, so that the configuration lists are properly upgraded.

We are currently developing a replacement product that will make installation and upgrading an easier process.

Locating the CDN Path
When initially installing the SPO app extension, you will have set up a ?CDN? location to host the various ?Deploy Files?. This path may be a generic document library on a site collection somewhere, or even a public or private CDN path. For SP2019 you will have similarly chosen a location for the ?WebtrendsAssets?.

If you are unsure where this path is, you should be able to find it within the Classic Tag Installer User Interface, where it will have needed to be specified to enable tracking originally.

1. Open a site collection where the Webtrends SharePoint Tag Installer is installed.
2. Open the Site Contents page.
3. Click on the Webtrends SharePoint Tag Installer link text.
4. On the General tab, note the ?Desired Extension CDN Path? field value.
   1. For SharePoint Online, instructions are to have created this path ending with a /WebtrendsSharePointAppExtension/ folder, but it?s possible that you chose to use an alternative name.
   2. For SharePoint 2019, instructions will have specified to use a path leading to a /WebtrendsAssets/ folder, either a shared location or on the local site collection.

SharePoint Online
The SPO app extension has a ?Deploy Files? folder that must be manually uploaded to a desired location. Specifying this location this requires editing an XML file prior to uploading the .sppkg. See Locating the CDN Path instructions above to determine the currently used CDN path.

1. Download the latest Webtrends SharePoint Modern View Tag Installer from www.webtrends.com/support/downloads.
2. Extract the .zip to a desired location.
3. Follow the Installing the Webtrends SharePoint App Extension section of the Webtrends SharePoint App Extension_V#.docx file found within to replace the .sppkg package and Deploy Files.

After replacing the version in the app-catalog, you will see that a new version of the file is available in the Site Contents page or Add-an-app page of each site. It is not technically required to do anything further, as you have already replaced all the related files, but you may wish to Upgrade the app-extension on each site so that SharePoint recognizes that the latest version is in use on that particular site.

SharePoint 2019
The SharePoint 2019 app extension was more recently released and takes advantage of a newer ?includeClientAssets? flag within the SharePointFramework. This flag tells SharePoint to host the extensions main ?Deploy Files? within a public CDN in SharePoint Online automatically. However, the WebtrendsAssets tracking JS files are still currently separate, and must be hosted manually. See Locating the CDN Path instructions above to determine where you may have placed the /WebtrendsAssets/ folder.

1. Download the latest Webtrends SharePoint 2019 Modern View Tag Installer from www.webtrends.com/support/downloads.
2. Extract the .zip to a desired location.
3. Follow the Installing the Webtrends SharePoint 2019 App Extension section of the Webtrends SharePoint 2019 App Extension_V#.docx file to replace .sppkg package and the /WebtrendsAssets/ JS files.

Note: If you opted not to use a shared location for the /WebtrendsAssets/ contents, and instead chose to use the files generated by the Classic App on each site collection, you must upgrade the Classic App on each site collection to ensure that the latest tracking JS files are available for the extension.

More Information

You can also download a PDF of this article from the following link: