Teamstudio Adviser consists of two Lotus Notes Applications that manage scanning and aggregation of data about your IBM Notes environment and generate reports, along with a supporting executable application that collects the raw usage activity logging data from servers.
The user interface for Adviser is a web application, and is hosted on a Domino server with HTTP enabled. The primary application, TSAdviser.nsf, contains the web application, and is deployed by creating an NSF on the desired server, and configuring it via web browser.
All data collection, including catalog, usage and complexity data, is designed to be run on a separate workstation. The secondary application, TSAdviserWS.nsf, is deployed on a workstation installation of IBM Notes. This application is responsible for scheduling and performing scans, and can be deployed automatically by executing actions in the server application from the chosen workstation. Scans are resource intensive processes; running them from a separate workstation and Notes client limits the impact of Adviser on server performance, and allows easier access to multiple domains.
The web interface for Teamstudio Adviser can be hosted on any Domino server version 8.5.3 or above.
- For Domino 8.5.3, the server must have a minimum of Fix Pack 3 installed, and must have Upgrade Pack 1 installed (or equivalent version of the Xpages Extension Library).
- The required components are included in Domino 9.0 and greater; no additional components are required.
The Teamstudio Adviser workstation is supported on Notes version 8.5.3 and higher (32-bit) running on supported versions of Microsoft Windows.
Upgrading an Existing Installation
If you are upgrading an existing installation of Adviser 6.0 or above, you can skip directly to the Upgrading section. Otherwise continue to follow the instructions below.
Prerequisites for Usage Data Collection
The Usage module of Teamstudio Adviser aggregates and reports on data collected by the IBM Domino server’s Activity Logging task.
In order to use Usage Auditor, Activity Logging must be enabled on all servers you wish to include.
Activity Logging can be enabled on the Server Configuration document in the Domino Directory database. Teamstudio Adviser tracks the following activity streams:
By default, Activity is logged to the Log.nsf database on the server, and the default 2 week retention period for Log.nsf applies to activity as well. By default, Teamstudio Adviser will collect usage data every night and will import any new data. If collection fails, no data will be lost as long as the problem is resolved within the 2 week retention period.
Installing and Configuring Teamstudio Adviser Server
To install the main server component, sign the TSAdviser.ntf template with an ID appropriate to execute code and access servers to be scanned, and create an NSF from the template on the desired server.
To configure Teamstudio Adviser, connect to the application via web-browser, using an address in the form http(s)://<server>/<path>/index.html, where <server> is the host name or IP address of the Domino server, and <path> is the file path of the NSF. For convenience, the NSF displays this URL when opened in a Notes Client.
If installation is successful, you should see the application home screen.
Teamstudio Adviser server requires that the ACL entry "anonymous" be defined as "No Access" and given the privilege "Read Public Documents" – this setting allows the Adviser workstation to trigger server-side job processing when client-side jobs have completed. Anonymous access cannot be used to create jobs or access data. Anonymous should not be set to a higher level of access, as authentication is required by the Adviser services that support the web browser application. Allowing anonymous higher levels of access will prevent the server from requiring authentication.
In general, other ACL settings in Adviser are applied to the browser application in the same manor they are applied in traditional Notes applications.
The "-Default-" access can be used to assign any level of access desired in place of anonymous access.
The final step in configuring the Teamstudio Adviser server is to select the servers to scan. You can do this from the Settings page in the web application, accessed via the gear icon on the right of the Adviser navigation bar. See Servers for more details.
Installing the Adviser data collection application on workstations
The Adviser data collection application is a Notes application based on the template TSAdviserWS.ntf.
This application is intended to run scans from a client workstation. Scanning for and reporting on activity is a resource intensive activity that may access multiple servers and works with file system files as part of the process.
Usage activity data from the scan are written to the server application, and available via the web browser interface.
The Adviser workstation requires locally scheduled agents to be run, in order to monitor the server application for pending jobs, and to run data collection for those jobs.
The application must be installed and run by ID that has a least Reader access to the Log.nsf files on the servers to be scanned, as well as any applications for which Complexity data is desired. If the servers exist in multiple domains, the ID and local workstation must be properly cross-certified to all servers.
The ID must also have Editor level ACL access (with delete rights) to the Adviser Server application.
Installing the Adviser Workstation Notes application
- On the workstation where the Adviser workstation will run, log in to the IBM Notes client with the ID that will be used to collect data.
- Ensure that the Notes client setting "Enable scheduled local agents" is checked (File > Preferences > Basic Notes Client Configuration).
- Ensure that the Notes client setting "Don't prompt for password from other Notes-based programs" is checked (File > Security > User Security). This step is required to allow the executable to run.
- Open the Adviser server application in the Notes client, and click on the link Enable Workstation Processing:
Running the Enable Workstation Action creates the local workstation application, signs it with the current ID, and enables a local agent to monitor the Adviser Server and respond to pending jobs. It typically take about 5 minutes for the local agent to begin running.
Installing the executable
Adviser uses an executable utility, logscan.exe, to collect raw activity data from Domino servers.
If a scan is initiated and this utility is not yet installed in the Notes program directory, Adviser will automatically install it, assuming the current user has appropriate OS rights to allow the install.
In the event that Administrator access is necessary to save this executable to the Notes program directory, the utility is located in the database’s Help > About document, and can be manually detached and saved to the Notes executable directory if needed.
Once saved, the user account running Usage Auditor in Notes must have read and execute rights in order to run the executable.
Workstation JVM Memory Settings
Adviser workstation runs scan jobs written in Java, and which rely on a sufficient memory to process large design notes during complexity scan, and occasionally large data caches (for example, to make importing usage from a prior copy of Usage Auditor more performant).
The default JVM Heap limit on a Notes installation is 64MB, which is often insufficient to manage large design notes (for example, forms with large attachments).
This limit can be changed by setting the workstation Notes.ini parameter JavaMaxHeapSize=<desired byte size>.
Teamstudio recommends setting a minimum of 128MB; a setting of 256MB should be ample in most cases.
To enable a 256MB heap limit, add or modify the line to read: JavaMaxHeapSize=268435456
If Out of Memory errors occur during workstation job processing, increase the limit as needed.
Workstation - Server Connectivity
Adviser workstation requires connectivity to the Adviser server via HTTP.
Most workstation processing, including scanning servers and databases, and writing data to the Adviser server, is handled through the Notes client and NRPC.
In order to trigger server processing once client side jobs have completed, Adviser invokes a REST service endpoint via HTTP to ensure that the server application is running to process the updated data.
The default workstation configuration attempts to connect to the server based on the fully-qualified host name specified first in the server document in the server's address book. The connection is attempted without SSL on port 80.
For servers requiring SSL connections, or connectivity on an alternate port, the configuration can be modified by editing the HTTP Host Name field in the Workstation Configuration document in the workstation database. By default this field contains only the host name; a protocol and optional port name can be specified (for example,specifies SSL on port 499). The Notes client acting as the Adviser workstation must be exited completely and restarted for this setting to take effect. For help configuring these settings, contact Teamstudio support.
Due to limitations with the Java 6 JVM currently embedded in Notes, SSL that uses large key sizes may not work correctly.
To upgrade from a previous version of Adviser 6.0 or greater, follow the steps below.
- Sign the new template with the appropriate ID to execute code on the target server.
- Refresh the design of the server Adviser database from the new template.
- Restart the HTTP task on the server using the command "restart task http" (this is equivalent to "quit http" followed by "load http" - note that "tell http restart" will not fully release the JVM and update the new code).
- Exit the Notes client acting as the workstation completely (this can be confirmed using task manager) and re-launch Notes. This will allow the Adviser workstation database to pick up the design changes to the server template.
- Within about 5 minutes the workstation agent should restart.
- In the browser UI, schedule a new scan. This will update the data as needed for the new version, and enable any new features. It is safe to schedule a scan while waiting for the workstation to restart; the scan will begin once the workstation is active.
Adviser does not currently support using "Saved Passwords" in browsers. Previously saved passwords can be removed via the browser's settings page.
Scheduling Daily Scans
Since Adviser extracts activity data from the server's log.nsf, which by default keeps 10 days of data, it's important to run Usage Scans on a regular basis to insure the data is up-to-date and without gaps.
To enable nightly scanning, open the Adviser server application in Domino Designer, navigate to Agents, and enable the agent Schedule Nightly Scan. When prompted for the server to run on, choose the server on which the server application resides. Check that the agent is signed with an ID capable of running scheduled agents on that server.
By default, this agent will run once daily, at 1:00 AM. The run time can be modified to another time if desired.
The Schedule Nightly Scan agent initiates the same process as triggering a manual scan using the Scan Now button in the application. The scan will update Catalog information, import Usage since the last scan, and recalculate any affected metrics. Workstation processing must be enabled for the scan request to be processed.
Importing Usage data from Usage Auditor
Usage data from Teamstudio Usage Auditor can be imported if the setting Save Supporting Data was enabled during the period of usage collection. Click here for information on importing from Usage Auditor.