implementation and install guide - webtrends€¦ · web viewthe configuration page appears. modify...

IWebtrends

Implementation and Install Guide

Webtrends SharePoint Tag Administrator

Version 3.0, August 2017

Table of ContentsWhat is the Webtrends SharePoint Tag Administrator?..............................................................................4

System Requirements..................................................................................................................................4

Installing the Webtrends SharePoint Tag Administrator.............................................................................5

Webtrends SharePoint Tag Administrator UI..............................................................................................7

Login Page...............................................................................................................................................7

Home Layout...........................................................................................................................................8

Tools bar..................................................................................................................................................9

Status information...............................................................................................................................9

Batch Status.......................................................................................................................................10

File Download....................................................................................................................................10

APP Packages.....................................................................................................................................11

Setup.................................................................................................................................................12

Actions Bar............................................................................................................................................13

Search....................................................................................................................................................14

Filters.................................................................................................................................................14

Site List Table.........................................................................................................................................15

More......................................................................................................................................................16

Using the Webtrends SharePoint Tag Administrator:................................................................................17

Uploading an App Package....................................................................................................................17

Deploying an App Package to a Single Site Collection...........................................................................17

Deploying an App Package to Multiple Site Collections.........................................................................19

Viewing the batch result/state..............................................................................................................19

Enabling and Configuring the App on a Single Site Collection...............................................................19

Enabling and Configuring the App on Multiple Site Collection..............................................................20

Switch to turn on/off “Enable Tracking”................................................................................................21

Switch to turn on/off “Collect User Profile Information?”.....................................................................21

Undeploying an App..............................................................................................................................21

Upgrading an App..................................................................................................................................22

Configuring the Webtrends SharePoint Tag Administrator.......................................................................24

Application Structure.............................................................................................................................24

Configuration file location.....................................................................................................................24


Web.config............................................................................................................................................24

Radio Button......................................................................................................................................24

Log file configuration.........................................................................................................................25

Log file location..................................................................................................................................25

System.properties.................................................................................................................................26

SMTP certification setup....................................................................................................................26

Directory for the app files..................................................................................................................26

Directory for the audit log files..........................................................................................................27

Timeout settings for app deployment and undeployment................................................................27

Upgrading the Webtrends SharePoint Tag Administrator.........................................................................27


What is the Webtrends SharePoint Tag Administrator?

The Webtrends SharePoint Tag Administrator, previously known as the Webtrends SharePoint Enterprise Administration Tool or SPEAT, was built to fill a need generated by deficiencies in SharePoint application deployment features. In particular SharePoint has no built-in facilities to manage applications deployed across thousands of site collections or reconfigure those applications without the use of scripting. Webtrends has created this tool to deploy and manage the Webtrends Tag Installer for SharePoint app (now referred to as add-ins) for SharePoint. By using this tool, you can batch deploy/undeploy the add-in, save and upload configurations across site collections, track versions of deployed apps, and upgrade deployed copies of the add-in as needed.

To use the Webtrends SharePoint Tag Administrator, you will need to have a Windows 2012 Server with IIS installed and running. You will need to create a new website in IIS to host the tool, and make that URL available to any SharePoint administrators that are going to use it to manage the app on your SharePoint site collections. While there is no login for the tool specifically, you must be able to provide a SharePoint administrator account for the tool to use to authenticate against your SharePoint Online (O365) instance, or your local SharePoint farm. The tool uses standard web ports 80 and 443 to communicate with your SharePoint instance, and you may need to create and install a certificate as a result.

System Requirements Windows 2012 R2 with IIS running Intel® Xeon® CPU E5-2660 v3 @ 2.60GHz or better recommended 16GB RAM or better 100GB free for system drive recommended (maintain at least 2x as much free space as

available RAM)


Installing the Webtrends SharePoint Tag AdministratorThese steps will walk you through installing the tool. Before beginning, you will need a Windows

2012 server with IIS running, and the ability to create and modify new sites on that server.

1. Make sure the IIS installation on your server has the following components enabled:

2. Make sure the IIS_IUSRS account has List, Write, and Read & execute permissions.

3. Create a new site within IIS to host the Webtrends SharePoint Tag Administrator. Be sure the domain is descriptive and appropriate to deliver to your SharePoint administrators, for example “spadmin.mydomain.corp”. The picture below shows example bindings on the default ports.


4. Once the site is created, extract the files for the Webtrends SharePoint Tag Administrator zip available from my.webtrends.com/downloads.

5. Copy the files within the extracted folder into the new site’s web root directory.

6. Create an Application Pool with a name that matches the site name you created in step 1. The picture below shows the required settings for the application pool.

7. Start the Website and Application pool you created if they are stopped.

8. In a web browser, verify you can access the Webtrends SharePoint Tag Administrator.

If the site is properly installed, when you call up the domain in a browser you should be prompted with a login window for your SharePoint install.


Note: You may need to create a security certificate for your site through your IT department, depending on how internal sites are setup on your network. Check with your IT department for more information.

Webtrends SharePoint Tag Administrator UIThe Webtrends SharePoint Tag Administrator uses the specified credentials entered into the

login screen to attempt to connect to the specified SharePoint instance and pull basic information about site collections and the status of deployed Webtrends applications. The credentials you provide must have the ability to modify every site collection, as well as the application library within your SharePoint instance. For this reason, it is recommended that you use a global administrator account when utilizing this tool. If the account does not have appropriate credentials, you may not be able to obtain a full list of all site collections in your SharePoint instance, upload and deploy new versions of the Webtrends application, or perform other functions from within the tool.

Login Page

UI elements Radio buttons - Select the appropriate SharePoint installation type. Choose SharePoint Online

when accessing SharePoint Online. Choose SharePoint Server when accessing SharePoint 2013 or SharePoint 2016 farms.

Admin Domain – Enter the appropriate URL or Admin URL (SPO) for your SharePoint installation, including the protocol and port number if utilizing a non-standard port. When connecting to SharePoint Online, the “-admin” URL is required to access the Central Administration and obtain a list of site collections.


o For example, if the URL for your SharePoint instance is: https://webtrendsQA.sharepoint.com

o Enter the following instead: https://webtrendsQA -admin .sharepoint.com

Account – Enter the appropriate User Account Name that you would use when accessing the SharePoint site directly.

o SharePoint Online - this is typically a [email protected] formatted login.

o SharePoint On-Premise - this is typically a domain\username formatted login. Password – Enter the proper Password for the user account in use. Login – Click the Login button to authenticate with SharePoint and procced.

Note: Login information will be verified and remembered on the client machine once the user certification is passed.

Home LayoutAfter authenticating, the system will retrieve information for all available site collections in the

SharePoint web application, and display them in a data grid. The Home screen shows you at a glance which sites already have the Webtrends app installed, as well as provide several options for interacting with the site collections in your SharePoint instance.

Note: It may several minutes for the first list of site collections to appear, depending on how many site collections are present in your instance, how fast your connection is, and the load on your SharePoint instance. Additional site collections will be retrieved as a background process.

UI elements Tools bar – Options for managing the Tag Administrator. Actions bar – Options to perform on selected site collections.


https://webtrendsQA-admin.sharepoint.com/

https://webtrendsQA.sharepoint.com/

Search/Filters – Options to narrow the visible list of site collections. Site List Table – The list of site collections available in the web application. More – Displays additional site collections that may have been collected in the background.

Tools barThe Tools bar provides links to management functions of the Webtrends SharePoint Tag

Administrator which allow you to view status messages, upload app packages, and more.

Status informationThis screen provides a running list of application status messages from the Webtrends

SharePoint Tag Administrator. Messages indicating errors or failures, as well as general application status information, will appear here.

Click on the tools bar to open the System Status window.

UI elements Status – The list of overall status messages. Version – The Version of the installed Webtrends SharePoint Tag Administrator. Sync – Clears and refreshes all cached site collection data in the system. Clear – Clears the list of status messages. Close – Close the Status window.


Batch StatusThis screen provides an interactive display to review the results of current and previous batch

jobs. You may use the arrows at the bottom to iterate through the status messages from previous runs. The tool utilizes many batch processes, such as saving configuration in batch, deploy app in batch, and undeploy app in batch.

Click on the tools bar to open the Batch Status window.

UI elements Batch Status – The list of details for a single batch job including the:

a. Batch No – An identifier for the batch job.b. Batch Type – The action being performed by the batch job.c. Start Time – The time the job was started.d. End Time – The time the job finished.e. Status – The status of the batch job.f. Detail – The status of individual jobs within the batch job.g. Delete – Deletes the current batch job status.

Prev – Loads the previous batch job details. Next – Loads the next batch job details. Refresh – Refreshes the current batch job status. Close – Closes the Batch Status window.

File DownloadThis screen allows you to download batch job status reports or audit logs from the

administration tool directly, rather than locating them on the server itself. These files are simple text files that you can search for desired information.

Click on the tools bar to open the file download window.


UI elements Batch Log List – The list of batch job logs to download. Click an item to download. Audit Log List – The list of audit logs. Click an item to download. Close – Closes the File Download window.

APP PackagesThis screen displays the list of app versions that you have uploaded to the administration tool.

Uploaded packages are stored in a directory (configurable) on the IIS server. These versions are available to deploy to new or existing site collections in your SharePoint infrastructure.

Click on the tools bar to open the APP Packages window.


UI elements APP Packages – The list of uploaded .app files and their version numbers.

o Delete – Deletes the .app file from the system. Upload – Uploads the selected .app to the system.

o Choose File – Opens a window to select the desired .app file.

SetupThis screen allows users to configure the location of the SharePoint App Catalog in the event

that the default App Catalog is not used. You may also opt to receive e-mail notifications of the start or stop of batch jobs at a specified e-mail address. This same information can be found in the batch status files available for download.

Click on the tools bar to open the Setup window.


UI elements AppCatalog Site Address – The URL to the App Catalog, if not using a standard location. Receive Email Notification – Enables the email notification of batch job statuses. Email – The email address to send the notification to.

Note: the SMTP server settings must be configured to send notifications. See SMTP certification setup

Actions BarThe actions bar provides various functions that can affect single or multiple site collections,

depending on whether a single or multiple rows are selected within the Site list table.

UI elements Configuration – Opens the configuration page for the app used on the currently selected site

collection(s). See official app documentation for details on configuring the app.o Save – Applies the current configuration to the site collections(s)o Retract Webtrends Advanced Analytics – Removes the User Custom Action and

deletes the WebtrendsAssets folder from the selected site collection(s), disabling tracking.

This option only appears if the Enable Tracking is active. o Export – Exports the current configuration settings to an XML file into the browser’s

default Downloads folder.o Import – Imports a previously exported XML file with configurations, to copy the

settings into the currently selected site collection(s).


Deploy – Opens the APP Packages window with a list of add-ins that can be installed using the “Install It” button.

Undeploy – Removes the add-in from the currently selected site collections. Upgrade – Opens the APP Packages window with a list of add-ins that can replace the

current version using the “Upgrade To This Version” button. Refresh – Refreshes the cache of site information and status for the selected site collections. Log Version – Opens a popup that allows logging a version number for the selected site

collections in cases where the app version cannot be determined do to different installation methods or older product versions.

SearchThe search bar will let you limit the visibility of sites displayed in the Site list table based on the

Site Path column.

UI elements Input box – A text field to search for. Search – Initiates the search for the desired string.

Note: the search utilizes a substring match. Searches for “dev” would match both “/sites/Dev/” and “/sites/dev2/”. The search function only queries against the Site Path column.

FiltersFilter the list of site collections based on various criteria. The filters work in conjunction with the

Search outlined above and are not applied until the Search button is clicked. The Search Input box can be empty when performing this action.

UI elements App – Filter the site list table to show site collections with the add-in deployed or not

deployed. Tracking – Filter the site list table to show site collections with the app’s Enable Tracking

button enabled or disabled. User Profile Service – Filter the site list table to show site collections where the User Profile

Service plugin is enabled or disabled.


DCSID Format – Filter the site list table to show site collections where the DCSID is formatted with a valid or invalid syntax.

Note: changes made to filter selections are not immediately applied. After making a filter selection, click the Search button to apply the new set of filters.

Site List TableThe Site List Table displays the list of successfully retrieved sites with columns containing site

and status information for each record.

UI elements Checkbox – Select a single or multiple site collections to perform an action against. Site ID – The GUID of the site collection retrieved from SharePoint. Site Path – The site collection root URL retrieved from SharePoint. Site Title – The site collection title retrieved from SharePoint. Deployment – The deployment status of this site.

o When the add-in is not deployed, a “Click to Deploy” link is present. o When the add-in has previously been deployed or is an older app, a “Deployed”

button is visible, which can open the current add-in configuration. o When the add-in has been deployed in this session and is new enough, the add-in

version is displayed on the same button. Tracking – An indicator of whether the add-in’s “Enable Tracking” button is enabled.

o When enabled, the WebtrendsAssets document library will appear in the site collection site contents and the User Custom Action responsible for enabling tracking is added to the site collection.

UPS – An indicator of whether the User Profile Service plugin is enabled for tracking of user information.

Status – An indicator of the status of a current action or previous action within the same session.

Note: hovering over an icon in the Status column will display text about the status.


MoreIn order to improve on perceived performance, the system will attempt retrieve and display a

limited number of site collections for you as soon as possible, and continue to collect information about additional site collections in the background. To refresh the Site List Table to show the additional site collections, click the “More” button at the bottom of the screen.

UI elements Left section:

o The number of apps deployed across all site collections in the web application.o How many site collections in the web application this user was authorized to access.o The number of site collections visible in the Site List Table out of the number of site

collections the cache has in storage. More – Adds any additional site collections found in cache that are not already displayed in

the Site List Table.


Using the Webtrends SharePoint Tag Administrator:Main features of the tool include the ability to deploy/undeploy apps, update app

configurations, and upgrade the installed apps to a newer version. Most of these features support batch process, which means user can select more than one site collection in the Site Table List and apply the changes in one process. Batch jobs will launch a multi-thread process in backend, and log the result into the batch log file, then send the Email notification to the logged in user if enabled.

Note: avoid starting many batch jobs processes in the same time, as this may require too many threads and impact the server performance.

Note: the UI will display a progress bar in each Site Table List row to monitor the progress of the action. If there are more than 30 site collections selected in the batch job, the UI will stop querying for individual job status to reduce the load on server. Users can receive the Email notification and check the results later by themselves.

Uploading an App Package1. Click the App Package link in the Tools bar.2. The APP Packages window appears.3. Click “Choose File” to open an Explorer window.4. Select the desired .app file from your computer.5. Click “Open” to close the Explorer window.6. Click “Upload” to upload the file to the server.

Note: uploaded apps are stored on the Tag Administrator server. The location for storage is configurable. See Directory for the app files.

Deploying an App Package to a Single Site Collection1. Choose a site collection to deploy to.2. View the column “Deployment” ion the Site List Table.

a. “Click to Deploy” means an app is currently not deployed on that site. 3. Click the “Click to Deploy” link.4. The APP Packages window appears.


5. Choose the desired app from the list of available apps and click “Install it”.6. The system will start the process of deployment and show the progress bar on status

column.

7. After completion, the system will refresh the state of the row.

8. When complete, you’ll see indicators in the UI indicating the success or failure of the job on a per site basis.

a. A green checkmark indicates job success. b. A red X indicates an issue with the job.

Note: hovering over the status icon will display a text message with the most recent message.


Note: some successful deployments may show a red X simply due to taking too long. Refreshing the site information will reveal if the “Click to Deploy” button has been replaced by the Deployed or App Version button, indicating a successful installation.

Deploying an App Package to Multiple Site CollectionsDeploying to more than one site collection will create a batch job that iterates through each

selected site collection and deploys the app package.

1. Select one or more site collections using the checkboxes on the left of the Site List Table.2. Click the “Deploy” button in the Actions bar.3. The remaining steps are identical to Deploying an App Package to a Single Site Collection.

Viewing the batch result/state The current status can be viewed by opening the System Status window and viewing the

updated messages. The final status can be viewed by opening the Batch Status window and viewing the updated

messages. The final status can sent to the current user’s email using the Receive Email Notification

option.

Enabling and Configuring the App on a Single Site CollectionDeploying an app does not enable the tracking of the site collection automatically. It only adds

the app to the site collection, making it available for use. In order to turn on tracking, you must enter a valid DCSID in the Configuration page, check the Enable Tracking box, then Save the changes. This adds the User Custom Action and the WebtrendsAssets folder to the site collection, and begins tracking user


interactions. Alternatively, you can enable tracking using the switch icon in the Site Table List’s Tracking column, provided that the configuration already has a valid DCSID input.

Note: please consult the official Webtrends Tag Installer guide for more details about the app configuration tabs and options.

1. Choose a site collection to configure.2. Click the button in “Deployment” column for the desired row.

a. This button will state the currently installed app version, or “Deployed” if the app version was unable to be retrieved.

3. The Configuration page appears.

4. Modify the settings of the app as needed, or Import the desired configuration to copy settings from a previously configuration site collection.

5. Click the “Save” button to apply the changes.

Enabling and Configuring the App on Multiple Site Collection1. Select the site collections you wish to update using the checkboxes.2. Click the “Configuration” button in the Action bar.3. The Configuration window appears.4. Modify the settings of the app as needed, or Import the desired configuration to copy

settings from a previously configuration site collection. 5. Click the “Save” button to apply the changes.


Switch to turn on/off “Enable Tracking”You can easily enable/disable tracking of a single site collection by utilizing the switch icon in the

Tracking column of the Site List Table. This allows you to avoid opening the configuration page if you wish to perform simple testing of the tracking.

1. - Tracking is currently disabled. Click it to turn on “Enable Tracking” directly from site list table.

2. - Tracking is currently enabled. Click it to turn off “Enable Tracking” directly from site list table.

Switch to turn on/off “Collect User Profile Information?”You can easily enable/disable the User Profile Service API call from the app for a single site

collection by utilizing the switch icon in the Tracking column of the Site List Table. This allows you to avoid opening the configuration page if you wish to perform simple testing of the tracking.

1. - User Profile Service API is currently disabled. Click it to turn on “Collect User Profile Information” directly from site list table.

2. - User Profile Service API is currently ensabled. Click it to turn on “Collect User Profile Information” directly from site list table.

Note: User data from the UPS API is stored in sessionStorage of a browser tab, and is not shared across tabs. It may be necessary to close and re-open your test page tab in the browser to see changes such as disabling the UPS API.

Undeploying an App1. Select the desired site collection(s) using the checkboxes on the left of the Site List Table.2. Click the “Undeploy” button in the Action bar.3. A confirmation prompt will appear.

4. Click OK.5. A warning that all configurations for this site collection will be deleted appears.

a. If you wish to save the configurations, Export them from the Configuration window prior to undeploying.


6. Click OK.7. The system will undeploy the app, and you can watch the progress in the Site Table List’s

Status column.

Note: undeploying through the Tag Administrator will first retract the app, removing the User Custom Action and WebtrendsAssets folder, then it will remove app from site. This is different than if the app has been deployed via the App Catalog, where you will need to manually retract the app first, then remove it from the Site Contents page of the site collection.

Upgrading an AppThe Upgrade option is essentially the same as the Deploy option. The App Packages dialog box

appears and provides you a list of app versions to install. If the desired version is not in the list, you can Upload the .app file from a local directory.

1. Select the desired site collection(s) by using the checkboxes on the lift of the Site List Table.2. Click the “Upgrade” button in the Action bar.3. Click “Upgrade to This Version” next to the app version you wish to upgrade to.


4. The system will deploy the new version of the app, and you can watch the progress in the Site Table List’s Status column.


Configuring the Webtrends SharePoint Tag Administrator

Application StructureThe Webtrends SharePoint Tag Administrator is a solution based on a stand-alone web

application hosted within IIS. Below is a screenshot of the application structure at the root level.

Configuration file locationThere are two user configurable files used by the Webtrends SharePoint Tag Administrator.

These are the Web.config and the System.properties files. The Web.config is the common configuration file for the web application, and System.properties provides configuration options for properties such as the Email SMTP, Batch size, WorkerThreads, Storage locations of files, and more. Both of these two files are visible under the root folder of the application. Most configuration options will not need customization. Below are some options you may wish to configure.

Note: the application must be restarted after modifications in order to reflect the changes.

Web.config

Radio ButtonThe availability of the two radio buttons for SharePoint routes are configurable by editing the

<appSettings> section. Possible values for the “Route” key are: “Both”, “Online”, or “Server”.


Log file configurationThe system uses the 3rd party “log4net” library to generate the logging information. The default

logging level is set to “INFO”. This setting can be modified by editing the level value within the <root> section.

Please see documentation for log4net and logging levels here:

https://stackify.com/log4net-guide-dotnet-logging/

Log file locationThe <appender> section named LogFileAppender defines where the log files are to be stored,

configured within the <file> property. The default location is a “logs” folder within the parent folder of the web application.


https://stackify.com/log4net-guide-dotnet-logging/

System.propertiesSystem configurations are available within the System.properties file. The System.properties file

is a plain text file containing a collection of key=value pairs. Each data row is a single configuration. For example:

#Directory for the batch data filesPath.batchesFolder=C:\SP_EAT\EAT_Batches

a. The line starting with the # character is a “comment” and will not be read by the properties reader. Lines without the preceding # character will be read as properties.

b. The text on the left of the equal sign is called a “key”.c. On the right side of the equal sign is the “value”.

SMTP certification setupThe Administration tool provides an Email notification function for batch configurations and

other processes. Users will need to initially configure the SMTP server and appropriate credentials in below properties, if they would like to have email notifications.

#Email SetupMailHost=MailLoginUser=MailLoginPWD=

Directory for the app filesUsers can upload the app files to the system for storage. These uploaded files will be kept on the

server in the specified location here:

#Directory for the app filesPath.appPackagesFolder=C:\SP_EAT\EAT_Packages


Directory for the audit log filesThe location of the audit logs is defined below. Users can also download the files from the UI

directly.

#Audit file storage path Audit.logPath=c:\SP_EAT\EAT_Audit

Timeout settings for app deployment and undeploymentAfter clicking deploy/undeploy app for a site collection, the system will repeatedly check on the

status of the process until complete, or a timeout has been reached. The timeout in milliseconds is configurable below.

#Timeout(ms) for checking the app status after deployTimeout.checkApp.afterDeploy=240000

#Timeout(ms) for checking the app status after undeployTimeout.checkApp.afterUndeploy=240000

Upgrading the Webtrends SharePoint Tag Administrator

1. Log in to the server hosting the Tag Administrator.2. Back up the existing Web.config and System.properties configuration files from the root

directory of the Tag Administrator site if you have made any customizations.3. Visit my.webtrends.com4. Sign in using the link in the upper left.5. Go to my.webtrends.com/downloads6. Click the SharePoint tab7. Click the Download link for the WebtrendsSharePoint Tag Administrator.8. Save the file.9. Open IIS on the server.10. Open the root directory for the SPEAT site.11. Extract the contents within the downloaded zip into the root directory, replacing all files.12. Edit the new Web.config and System.properties to restore any customizations as needed.13. Restart the web application in IIS to reflect the changes.


implementation and install guide - webtrends€¦ · web viewthe configuration page appears. modify...

Documents