Introduction
This is a technical blog post to describe the inner workings of SuperOffice Web Tools. The intended audience is technicians, developers and other special interested.
By understanding how SuperOffice Web Tools works, it is easier to troubleshoot issues and to have a common ground when reporting and discussing wishes and issues.
SuperOffice Web Tools have basically four features:
- Download, edit and upload documents
- Alarm notifications
- Quick-login to SuperOffice by menu or double-clicking on the icon in the notification area
- Bridge between user-initiated actions in SuperOffice CRM Web and SuperOffice Mail Link
Prerequisites
Web Tools is currently using .NET framework 4.5, which will be installed by the installer if it is not already installed on the system.
Small recap on the road behind us
SuperOffice Web Tools bridges document editing in SuperOffice CRM Web with the associated applications on the user's desktop. In previous versions, this was possible by using a protocol handler. The Web client executed URIs in order to make Web Tools download a document. Web Tools would start the associated editor and when the user was finished editing the document, would upload the document. After a while, using protocol handlers became unreliable on some browsers. For instance, issuing the same protocol multiple times within a small time-frame would stop executing the commands entirely.
Our response to that was to create a browser plugin which worked on the most popular browsers, but of course, shortly after some browsers decided to drop support for NPAPI-based plugins. This leads us to the current implementation where we use SignalR-technology to communicate between SuperOffice in the web browser and Web Tools running on the user's desktop. As you may realize by now, the interaction between SuperOffice Web Tools and SuperOffice Web is heavily dependent on the capabilities in the browser used.
Installation
Per user
When you download Web Tools from a SuperOffice installation, you might have noticed that the downloaded file has a name in form of "SuperOffice.Web.Tools--u=https%3a%2f%2fsuperoffice%3a443%2fSuperOffice%2f&cn=SuperOffice&un=souser--.exe". The contents after "--" is the configuration directive. The Web Tools installer executes the command: SuperOffice.TrayApp.Client.exe /autoconfig:[installer_name] (without brackets). This example configures the Web Tool installation to connect to https://superoffice/superoffice/. The full command given to SuperOffice.TrayApp.Client.exe in this example is:
SuperOffice.TrayApp.Client.exe /autoconfig:"SuperOffice.Web.Tools--u=https%3a%2f%2fsuperoffice%3a443%2fSuperOffice%2f&cn=SuperOffice&un=souser--.exe"
Configuration after installation
If Web Tools are already installed, or if you for other reasons wish to configure it, it is possible to use SoConfig files for the initial setup. A SoConfig variant is given below. When deploying through GPO or other alternatives, executing the SoConfig file during the logon process will setup Web Tools for the user. The site will not be added again if it has already been added.
Upgrading
When the user logs in to an updated Web installation, Web Tools will detect there is an updated version available and prompt the user for upgrade. Versioning in SuperOffice is defined as "MAJOR.MINOR.BUILD.REVISION". The user will be "forced" to upgrade if the MAJOR component is higher than the current web tools major version. Other changes are optional upgrades.
The prompt for upgrade can be disabled in scenarios where you don’t want to push a new version of Web Tools. The configuration setting SuperOffice\Downloads\WebToolVersion in the web.config file can be set to a previous version. The user will still be able to upgrade to the latest version by pressing Download in the web client.
Configuration
Configuration in SuperOffice Web Tools can be segmented into configuration stored per site in the SiteInfo files and configuration stored in the Windows Registry.
The SiteInfo files, which are encrypted, contain all connectivity information such as the endpoint URL and the credentials used for authentication. Additionally, the settings from the Preferences-dialog in Web Tools are included here.
Versions prior to 8.0 stored SiteInfo files in the IsolatedFileStorage provided by .NET in local application data. Versions from 8.x store the SiteInfo files in %AppData%\SuperOffice\TrayApp (Roaming Profiles).
There are no command-line utilities for creating/modifiying/viewing the SiteInfo files directly. All manipulation must be performed through the user interface in SuperOffice Web Tools.
Settings which are not site-specific are usually found in the registry. "Normal" installations should not require any tweaking in the registry.
The following list of registry entries in HKCU\Software\SuperOffice\DocLink is available (complete list of released version at the time of writing):
|
Name |
Type |
Description |
|
SupressExitWarning |
REG_DWORD |
Set to 1 to disable the exit warning when closing Web Tools |
|
ClientId |
REG_SZ |
The identifier which uniquely identifies the user and machine when multiple Web Tools from the same user are connecting to one installations. Incorrect values of ClientId result in loss of functionality. |
|
ProtocolLogFile |
REG_SZ |
The path incl filename where data sent and received through the SignalR-connection are logged. Empty or missing value results in no logging. |
|
LogFile |
REG_SZ |
Path incl. Filename where general logging is stored. Empty or missing value results in no logging. |
|
NetworkTimeoutPeriod |
REG_DWORD |
The default timeout-period before network-invocations are considered unresponsive. (SignalR) |
|
ConnectTimeoutRatio |
REG_DWORD |
The default factor which NetworkTimeoutPeriod is scaled by between connection timeouts. A lower value will give more immediate reconnect attempts on connection failures, but will also lead to new connections to more quickly be deemed unsuccessful. |
|
QueueLength |
REG_DWORD |
The default queue-length for the responsiveness-checker. |
|
EnableTracing |
REG_DWORD |
1 to enable. Enables SignalR connection level tracing. Files are stored to %TEMP% with prefix trace_. |
|
DisableHttpExpect100Header |
REG_DWORD |
1 to disable. Disables the Expect: 100-continue HTTP header in violation of HTTP-spec when working with proxies. Required when working against squid-proxies. |
|
ProxyUsesDefaultCredentials |
REG_DWORD |
1 to enable. Use the logged-in user's Windows credentials for authenticating towards the proxy. |
|
DisableTls10 |
REG_DWORD |
1 to disable. Disable TLS 1.0. (Only support TLS 1.1 and 1.2) |
|
ProxyCredentialType |
REG_SZ |
Set the credential type when authenticating towards a proxy. Valid values: Windows, Ntlm, Digest and Basic. ProxyUsesDefaultCredentials must be set to 1 for this setting to have effect. |
Interactions between SuperOffice Web Tools and SuperOffice Sales and Marketing
Web Tools consists of three components: the installed component on the user’s computer, TrayApp2.svc (WCF) and the SignalR endpoint. The two latter are installed server-side along with SuperOffice Sales and Marketing, and access the SuperOffice database through NetServer APIs. (Yes, the same APIs which are available to partners).
Starting up Web Tools
After Web Tools have finished starting up, it will resuming incompleted tasks. The tasks files are stored in %localappdata%\SuperOffice\SuperOffice 7 Web Extensions\Tasks. One task consists of a task file and a directory with the same name. This directory will contain the document during editing/reading.
Document editing
Authentication
Web Tools supports authenticating to two different layers to SuperOffice. The first layer is authenticating towards the Web Server (IIS) using Negotiate (Windows Authentication), NTLM, Digest or Basic. The second layer is authenticating towards the SuperOffice installation. Authenticating towards the SuperOffice installation can be handled by SuperOffice, Active Directory or delegated to a third-party such as Google or Office 365 (only available in Online). Single-sign on is achieved when both authentication layers are compatible – for instance Windows Authentication in IIS and Active Directory on the SuperOffice installation.
SSO requires configuration changes in IIS and web.config file. Users must being configured to use Active Directory for authentication. The link describes how to configure this (https://community.superoffice.com/en/technical/documentation/prepare/IIS_Authentication/).
General tips for troubleshooting Web Tools
I'm running single sign-on, but the credential window pops up many times.
Using Single-Sign On delegates the authentication to your domain controller (or the component that acts as the authentication server). Authentication will fail if the password on the local machine is different than the password stored centrally (hint: NTLM password hashes). It will also fail if the account has been locked.
The document dialog pops up instead of Web Tools when I double-click a document in the archive.
This is often caused by Web Tools not being properly configured. Note that earlier versions of 8.0 had stability issues. The web page WebToolsDiagnostics.aspx can give indicators on which clients are registered with the logged-in user.
Which types of debugging utilities are available for Web Tools diagnostics?
WebToolsDiagnostics.aspx is, as the name suggests, a tool to give hints on the current connectivity state between SuperOffice Web Tools and the Web browser. Information such as the version and the machine name of Web Tools are displayed along with which signalr clients are connected.
The registry keys LogFile and ProtocolLogFile enable logging of the main actions and the SignalR-protocol respectively. Please note a restart of web tools is often necessary for applying the registry settings.
Further work
There are still missing gaps in this blog post and it will be updated continously.
Hi Frode,
We are using the 7.5 version, perhaps the issue you mentioned was also in this version.
Perhaps we should open a support ticket on this.
Thank you.