Wonderware Intelligence Dashboard Licensing Guide 3/22/13
All rights reserved. No part of this documentation shall be reproduced, stored in a retrieval system, or transmitted by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of Invensys Systems, Inc. No copyright or patent liability is assumed with respect to the use of the information contained herein. Although every precaution has been taken in the preparation of this documentation, the publisher and the author assume no responsibility for errors or omissions. Neither is any liability assumed for damages resulting from the use of the information contained herein. The information in this documentation is subject to change without notice and does not represent a commitment on the part of Invensys Systems, Inc. The software described in this documentation is furnished under a license or nondisclosure agreement. This software may be used or copied only in accordance with the terms of these agreements. 2013 by Invensys Systems, Inc. All rights reserved. Invensys Systems, Inc. 26561 Rancho Parkway South Lake Forest, CA 92630 U.S.A. (949) 727-3200 http://www.wonderware.com For comments or suggestions about the product documentation, send an e-mail message to ProductDocumentationComments@invensys.com. All terms mentioned in this documentation that are known to be trademarks or service marks have been appropriately capitalized. Invensys Systems, Inc. cannot attest to the accuracy of this information. Use of a term in this documentation should not be regarded as affecting the validity of any trademark or service mark. Alarm Logger, ActiveFactory, ArchestrA, Avantis, DBDump, DBLoad, DT Analyst, Factelligence, FactoryFocus, FactoryOffice, FactorySuite, FactorySuite A 2, InBatch, InControl, IndustrialRAD, IndustrialSQL Server, InTouch, MaintenanceSuite, MuniSuite, QI Analyst, SCADAlarm, SCADASuite, SuiteLink, SuiteVoyager, WindowMaker, WindowViewer, Wonderware, Wonderware Factelligence, and Wonderware Logger are trademarks of Invensys plc, its subsidiaries and affiliates. All other brands may be trademarks of their respective owners.
Wonderware Intelligence Dashboard Licensing Purpose The Wonderware Intelligence Dashboard Licensing software is an add-on to the Wonderware Intelligence software that enables concurrent use of the Dashboard Server. By default, the Dashboard Server is licensed based on a number of named users. With this add-on software, the Dashboard Server effectively becomes driven by a concurrent licensing model. This add-on may only be used with a valid Wonderware Intelligence license for concurrent-users. This document describes the installation, configuration and use of the Wonderware Intelligence Dashboard Concurrent Licensing software. Prerequisites A valid Wonderware Intelligence license for concurrent users (paper license) Tableau Server 7.0.13 or greater installed locally Tableau Server configured to use active directory Active directory users must be imported in Tableau Server Licenses are configured in Tableau Server.NET 4.0 (full version; Client Profile is not sufficient) is installed on the computer Installation The following steps are required to install and configure the Dashboard Licensing tool. Copying the Concurrent Licensing Files Copy the following files to a folder of your choice (for example, C:\ConcurrentLicensing): IntelligenceDashboardLicensingConfigurator.exe IntelligenceDashboardLicensingServer.exe IntelligenceDashboardLicensingServer.exe.config
Newtonsoft.Json.dll System.Net.Http.dll System.Net.Http.Formatting.dll System.Net.Http.WebRequest.dll System.Web.Http.dll System.Web.Http.SelfHost.dll Registering the Service The IntelligenceDashboardLicensingServer.exe application from the install directory needs to be registered as a Windows Service. The service must run using a Windows account that has Administrator privileges on the local computer. For this step and the steps to follow, make sure to login to the computer using this account. To register the service, open a command prompt as an Administrator. Run the following commands: sc.exe create "Wonderware Intelligence Dashboard Licensing" binpath= "C:\ConcurrentLicensing\IntelligenceDashboardLicensingServer.exe" DisplayName= "Wonderware Intelligence Dashboard Licensing" start= auto obj= "MyDomain\MyAdminUser" password= "AdminUserPassword" sc.exe description "Wonderware Intelligence Dashboard Licensing" "Provides concurrent licensing support for the Wonderware Intelligence dashboard server." Notes: Please replace the highlighted text above with the values applicable to your environment. The path to the executable must be the fully qualified path. A relative path cannot be used. A space character must be present after the = sign when assigning values in the command. After the service is registered, the user account that is used to run the service needs to be granted the Log on as a service right. To do so, follow the steps described in http://technet.microsoft.com/en-us/library/cc794944(v=ws.10).aspx
The Local Security Policy shown below highlights where the change needs to be made: Editing the Configuration Open the IntelligenceDashboardLicensingServer.exe.config file found in the install directory using a text editor. Set the following settings to proper values: Setting TableauTabCmdPath TableauServer TableauAdministratorUserName ConcurrentLicensingToolPort VerboseLog Description Path to the location of the Tableau TabCmd.exe application. By default, this is: C:\Program Files (x86)\tableau\tableau Server\7.0\bin\tabcmd.exe. Server name (including port number) of the Tableau Server in the form server:port. User name (without domain) of an active directory user that is configured as a Tableau Server administrator. Port used by the Dashboard Licensing tool (for example, 50123). When set to True, enables the logging of the TabCmd.exe command line, its arguments and the output to the Windows event log. Opening a Firewall Port If required, the process IntelligenceDashboardLicensingServer.exe on the configured port (e.g. 50123) must be allowed to receive incoming HTTP requests. Refer to your firewall documentation. For example, if you are using Windows Firewall, you can go to the Windows Firewall control panel screen and then to the Allowed Programs section to add the Dashboard Licensing Server executable.
Configuring the Tableau Administrator User Password Make sure you are logged in to the computer as the user that is running the service (as specified in the command that was executed to register the service). The user that is running the service is also visible in the Windows Services management console. Run the IntelligenceDashboardLicensingConfigurator.exe application from the install directory. At the prompt, type in the password for the Tableau administrator user that was configured previously in the IntelligenceDashboardLicensingServer.exe.config file and press Enter. Please note the characters typed for the password are not echoed on the screen. Note: If the password is changed using the IntelligenceDashboardLicensingConfigurator.exe application after the system is configured and running, it will be necessary to restart the Wonderware Intelligence Dashboard Licensing service. Starting the Service Using the Windows Services management console, start the Wonderware Intelligence Dashboard Licensing service that was registered previously. The service should start successfully. If it does not, use the Windows Event log to get more information about the error.
Using the Dashboard Licensing Tool The following operations can be executed against the Dashboard Licensing tool. In all cases, the server:port used below must be replaced with the configured values: Server: Name of the computer that is hosting the Dashboard Licensing tool. Port: port that was configured previously (for example, 50123). The operations can be executed using several mechanisms. For example, simply accessing the URL using Internet Explorer will perform the operation. In addition, scripts can be written to automate the process. For more information, see the Automating the Use of the Tool section. Acquiring a License To acquire a license, a call to the following WebAPI method must be made: http://server:port/wwintelligence/dashboardlicensing/requestlicense Releasing a License To release a license, a call to the following WebAPI method must be made: http://server:port/wwintelligence/dashboardlicensing/releaselicense Managing Users A file used by the Dashboard Licensing tool must be regenerated each time any of the following changes are made to Tableau users: Adding a user to Tableau Removing a user from Tableau Changing the Administrator privileges of a Tableau user (adding or removing the privilege) To regenerate the file used by the Dashboard Licensing tool, perform the following: 1. Make sure you are logged in to the computer as the user that is running the service. 2. Locate the Intelligence folder found in the local app data folder of the user that is running the service. Typically, this folder will be C:\Users\[UserName]\AppData\Local\Intelligence. 3. In this folder, you should see a file named: DashboardServerUsers.xml. 4. Delete this file. 5. Restart the Wonderware Intelligence Dashboard Licensing service. Alternatively, the file will automatically be regenerated once a new request to acquire or release a license is made.
Troubleshooting The following sections provide troubleshooting information. Common Troubleshooting Steps The following steps can be used to identify potential issues when the application is not behaving as expected: Review the Windows event log for any warning or error under the Application category. The Source used to log the message is Wonderware Intelligence Dashboard Licensing. Review the configuration settings (see the Editing the Configuration section). Reconfigure the Tableau administrator password (see the Configuring the Tableau Administrator User Password section). Enable the VerboseLog so that all TabCmd.exe output is logged in the Windows event log (see the Editing the Configuration section). Make sure that the configured Tableau administrator has Administrator privileges in Tableau. Delete the DashboardServerUsers.xml used by the Dashboard Licensing tool (see the Managing Users section). Make sure that the user that is used to run the service has administrator privileges on the computer. Restart the service. Service Startup Timeout If the service takes a long time to start, the following can be done: 1. Run the following command: "C:\Program Files (x86)\tableau\tableau Server\7.0\bin\tabcmd.exe" get "/users.xml" --filename c:\dashboardserverusers.xml --server http://localhost:8000 --u TableauAdministratorUser --password MyPassword Note: Please replace the highlighted text above with the values applicable to your environment. The TableauAdministratorUser and the MyPassword values need to be updated to reflect the tableau administrator user that is used on the system. 2. Locate the file that was generated (for example, C:\DashboardServerUsers.xml). 3. Move the file to the Intelligence folder found in the local app data folder of the user that is running the service. Typically, this folder will be C:\Users\[UserName]\AppData\Local\Intelligence 4. Start the service.
Uninstall Perform the following to uninstall the Dashboard Licensing tool. 1. Using the Windows Services management console, stop the Wonderware Intelligence Dashboard Licensing service. 2. Open a command prompt as an Administrator. Run the following command to unregister the service: sc.exe delete "Wonderware Intelligence Dashboard Licensing" 3. Delete the files that were copied to the installation directory. 4. Locate and delete the Intelligence folder that was created in the Local application data folder for the user that was used to run the service. 5. For example, on Windows Server 2008R2, this folder is located at: C:\Users\[UserName]\AppData\Local\Intelligence
Automating the Use of the Tool The following Windows powershell scripts are examples of scripted use of the Dashboard Licensing tool. Requesting a License Function which makes a call to the supplied Web API URL. Uses the current users credentials function LicenseHttpCommand() { param( [string] $target = $null ) $webrequest = [System.Net.WebRequest]::Create($target) $webrequest.contenttype = "text/html" $webrequest.usedefaultcredentials = $true $webrequest.preauthenticate = $true $webrequest.method = "GET" try { [System.Net.WebResponse] $resp = $webrequest.getresponse(); catch [System.Net.WebException] { Write-Host $_.Exception.Response.StatusCode.ToString() Write-Host $_.Exception.Response.StatusDescription.ToString() return; Write-Host $resp.statuscode.tostring() Write-Host $resp.statusdescription.tostring() MAIN CODE $URL = "http://server:port/wwintelligence/dashboardlicensing/requestlicense" LicenseHttpCommand $URL
Releasing a License Function which makes a call to the supplied Web API URL. Uses the current users credentials function LicenseHttpCommand() { param( [string] $target = $null ) $webrequest = [System.Net.WebRequest]::Create($target) $webrequest.contenttype = "text/html" $webrequest.usedefaultcredentials = $true $webrequest.preauthenticate = $true $webrequest.method = "GET" try { [System.Net.WebResponse] $resp = $webrequest.getresponse(); catch [System.Net.WebException] { Write-Host $_.Exception.Response.StatusCode.ToString() Write-Host $_.Exception.Response.StatusDescription.ToString() return; Write-Host $resp.statuscode.tostring() Write-Host $resp.statusdescription.tostring() MAIN CODE $URL = "http://server:port/wwintelligence/dashboardlicensing/releaselicense" LicenseHttpCommand $URL