Release 6.1: Troubleshooting Tips

iDatix and iSynergy transitioned to DocuPhase

File locations have moved from iSynergy and iDatix references.

On the servers, during the upgrade, the C:\ProgramData\iDatix folder and its contents are moved to C:\ProgramData\DocuPhase.
For individual client products, this action takes place when they are started.
To avoid any data issues, existing database names are unaltered.

Release 6.0 and Earlier

Release 6.1 and After

*Note: DocuPhase Analytics will reside in its own folder.

32-bit vs. 64-bit Transition

Email Integration


Upload Email

Docuphase server web.config

Program Files/docuphase/docuphase server/web.config
Email URL is the mail server web service:

HTML5 Viewer Email

Dataservice web.config

Program Files/docuphase/dataservice/web.config
Finding the mail server’s url:
Use a Microsoft Outlook client that connects to the same Exchange server.
  • Hold the Ctrl key and right click on the Outlook Icon in the system tray
  • Select “Test E-mail Auto Configuration” from the menu

  • Type in an email address located on the desired Exchange server and the password for that account

  • Click Test
  • The URL is listed as 'Availability Service URL'

Exchange Server settings:

  • The service account running the Data Service needs to have full control over the mailboxes in that exchange server.

    • **The web says that you should be able to get it work by giving it SendAs permissions, but it did not work for me. This could be server specific.

  • The web server needs to be given permission to relay messages. This is done from the admin side of the exchange server

  • Verify that you can log into that exchange server with that user’s email that is noted in the docuphase user profile (you can do this by adding OWA to the end of the URL. Example: https://mail.mailservice.com/owa). Some times we may need to have the “fully qualified email”. For example, a client uses emails like [email protected] and if you send an email to that address the user will get it. However, if you try to log in to the outlook portal (OWA) with that address, it does not work. It will work with [email protected]. Once I updated the user’s profile to reflect that, I was able to send emails.

Document Caching

Use Viewer Console to view status of cache

Configuration Settings displayed in the Viewer Console (Administration\System\Viewer Console)
DocuPhase Viewer Cache.Directory – location where the cache is stored
DocuPhase Viewer Cache.Disable Browser Cache –
True – this is the default value; this forces the system to use the server cache, protecting the documents from security breaches            
False – Does allow the local browser to capture the documents in a local cache; although this would allow faster display of documents, it would provide a security hole to the documents stored in DocuPhase
PDF Render Use Datalogics –
True – allows the system to use the Datalogics toolkit, which is more specifically focused on PDF rendering.
False – this is the default value; instruct the system to have all PDF documents rendered by the Leadtools toolkit. This will have an impact in performance, the Leadtools rendering is a bit faster than the Datalogics one; we have not observed an impact on quality but the Datalogics toolkit is what we use for all other PDF need across our product suite.
DocuPhase Viewer Cache.Cache Check Interval – this setting controls how often the system will check for documents that have met the criteria to be removed from cache; see the following settings to determine what those settings are
DocuPhase Viewer Cache.Access Timeout – Determines how long to wait between file access errors before an exception is thrown. A small period will disable re-tries to access a file and force the Dataservice to trigger an error.
DocuPhase Viewer Cache.Sliding Expiration – this setting indicates the window of time within which a document must be accessed to be considered current and not eligible for cache clearing
DocuPhase Viewer Cache.CacheMaxSizeGB – this setting indicates the max size (in Gigabytes) the cache is allowed to grow to on the server. A small size may cause excessive evaluations of the cache for compliance, which will affect performance; further, may cause frequent re-rendering (and therefore re-caching) of document pages. If a value is specified here, the mentioned tasks are performed by the Dataservice instance so the recommendation is to set this to no-limit (Zero or empty) and configure the DocuPhase Service Viewer Cache plugin to perform this job outside of the Dataservice context.
Max Size Cache Threshold Percentage – this setting indicates to the system when cache cleanup will occur, when the cache size reaches this percentage of the max cache (DocuPhase Viewer Cache.CacheMaxSizeGB), the Dataservice must go through the process of clearing eligible documents from the cache in a FIFO order. This setting is NOT exposed through the web.config file so the administrator has no way no change this behavior.
There are two relevant configuration files for the HTML 5 Viewer Cache Service.

First configuration file location

C:\ProgramData\DocuPhase\DocuPhase Service\ViewerCacheServiceConfig.xml

This configuration file contains default values for the service.  These default values are used in the event that the data service goes down but the DocuPhase service is still up and running.
Configuration values are as follows:
DocuPhaseViewerCache.Directory – Directory to be used to temporarily store cached data in the event that a data service is inaccessible
DocuPhaseViewerCache.AccessTimeout – Timeout timespan for read/write access to the file cache directory
DocuPhaseViewerCache.CacheMaxSizeGB – Maximum size in GB for the file cache before purge activities begin
DocuPhaseViewerCache.SecurityUri – URI to the Security service.
DocuPhaseViewerCache.SecurityUsername – User Name for security service authentication
DocuPhaseViewerCache.SecurityPassword – Password for security service authentication

Second configuration file location

C:\Program Files\DocuPhase\Data Service\Web.config

This file contains identical settings; however, these settings take precedence over settings in the ViewerCacheServiceConfig.xml
The settings that are used from the data service web config are as follows:
DocuPhaseViewerCache.Directory – This is the directory that the data service uses to cache data, also the value that is returned to the HTML 5 Viewer Cache service when the configuration is requested from the data service
DocuPhaseViewerCache.AccessTimeout – Timeout timespan for read/write access to the file cache directory
DocuPhaseViewerCache.SlidingExpiration – This setting is used by the data service when adding items to the file cache.  It sets all new items added to the cache with this sliding expiration timeout so that when the item is no longer accessed, it can be cleaned up by the HTML 5 Viewer cache service
DocuPhaseViewerCache.CacheCheckInterval – This is no longer used and should be removed
DocuPhaseViewerCache.CacheMaxSizeGB – Maximum size of the file cache in GB - this is returned to the HTML 5 Viewer Cache service when the configuration is requested.

Use the web.config file located in the DataService installation folder to make adjustments that affects the DataService instance

To perform changes to the settings mentioned above and exposed by the Viewer console the administrator should adjust the following entries:

<appSettings>
    …
    <!-- Caching Start-->
    …
    <add key="DocuPhaseViewerCache.AccessTimeout" value="" />
    <add key="DocuPhaseViewerCache.SlidingExpiration" value="48:00:00" />
    <add key="DocuPhaseViewerCache.CacheCheckInterval" value="23:00:00" />
    <add key="DocuPhaseViewerCache.CacheMaxSizeGB" value="" />
    <add key="DocuPhaseViewerCache.DisableBrowserCache" value="true" />
    <!-- Caching End-->
    …
    <add key="PDFRenderUseDatalogics" value="false" />
    …
  </appSettings>

Use the ViewerCacheServiceConfig.xml file(s) located in the DocuPhase Service installation folder to make adjustments to the HTML5 Viewer Cache plugin

As mentioned earlier, it is recommended that the ability to validate and perform cache adjustment be disabled in the DataService by setting  the “DocuPhase Viewer Cache.CacheMaxSizeGB“ entry in the web.config to zero or an empty string.

Plugin documentation and how to perform the adjustments.

  1. Service is started under the DocuPhase Service as a service plugin

  2. When the service starts up it attempts to load a configuration file for the service plugin

  3. The configuration file is typically located at C:\ProgramData\DocuPhase\DocuPhase Service\ViewerCacheServiceConfig.xml

(different Windows O/S versions may store the file in a different location)

  1. If the service cannot find the configuration file, it generates one with default settings'

  2. When the configuration is loaded the service "goes to sleep" until it is activated by the DocuPhase service to perform its work

  3. On a timer interval (default is 7200 seconds) the service activates and performs the following activities:

    1. Loads the default configuration - in case there were changes to the configuration file settings since last run

    2. Creates a connection to the Security service to get a security token which is used to make subsequent secured service calls

    3. Loops through up to 10 data services performing the following:

      1. Calls the data service and retrieves the cache configuration values

        1. If the call to the data service fails for some reason, default configuration values are used

      2. Checks to make sure the data service is up

        1. If data service is up

          1. Gets a cache snapshot from the data service instance

          2. Loads cache snapshot into service local memory

        2. If data service is not up

          1. Loads cache from the database into service local memory for the data service instance

      1. Creates a new instance of LeadTools FileCache and points the FileCache to the cache directory (either from the data service or from the default configuration)

      2. Checks cache max size configuration setting and if this is set, computes the maximum allowable size of the cache in bytes

      3. Checks the Cache and reconciles cache on disk if required by:

        1. enumerates through cache directory and gets a listing of cached items

        2. Gets the size of the cache directory

        3. Checks the cache policies on the individual cached items to determine if any should be removed - this is performed by LeadTools.FileCache

        4. Gets the size of the cache directory again

        5. Compares the size of the cache directory before and after the LeadTools cache policy check

        6. If the size is different - meaning that LeadTools pruned the cache, then:

          1. compares current list of cached items to original list (created in step a) - and removes items from original list that were removed

          2. if the data service is up performs a DataService cache sync operation

          3. if the data service is not up, adds to an in memory list tracking which documents have been purged or deleted

        7. If the cache max size configuration setting is > 0

          1. Checks to see if the cache on disk is within the CacheSizeThresholdPercentage

          2. If cache on disk is larger than the threshold Purge the cache by:

            1. Get the sub directories in the disk cache directory order by the creation time (this puts oldest first)

            2. For each document delete from the cache until the cache threshold is met

          3. Compares current list of cached items to original list (created in step a) - and removes items from original list that were removed

          4. if the data service is up performs a DataService cache sync operation

          5. if the data service is not up, adds to an in memory list tracking which documents have been purged or deleted

      1. If the cache was reconciled and the data service instance is down, the cache is saved to the database for this instance

(this does not save the actual cached content, just a URI, document ID, and security info)

    1. After all data services have been processed, service goes to sleep

              
Note: code has been implemented in this service such that if a service shutdown is requested, this plugin should stop performing work so that the service can shut down in a timely manner.                  
Limitations - (i.e. not supported if the user configures the system to run with these settings):

  1. If the system administrator configures the service to run at an interval of less than 2 hours, warning messages will be logged.  Changing the settings to run at a shorter time interval has the potential to cause contention between the HTML 5 Viewer and the HTML 5 Viewer Cache Service.  Caution must be exercised when changing the service interval to less than 2 hours.

  2. If the system administrator configures the data service to use a cache directory that is inaccessible (security or network inaccessible), by the HTML 5 Viewer Cache Service then the HTML 5 Viewer Cache service will not be able to clean up the cache.

HTML5 Viewer vs Legacy Viewer

There are obviously significant technical differences between the HTML5 and Legacy Viewer. This section, however, will just focus on the main components and troubleshooting requirements.

Local vs Server

  • The Legacy Viewer is a client side install program, while the HTML5 Viewer is only installed on the server itself

  • The Legacy Viewer is only available with the IE browser, while the HTML5 Viewer is available in all browsers

  • The HTML5 Viewer installation itself, as well as how it appears on the server when installed, is actually under the name “DocuPhase Viewer”

How to change viewers

By Default, during installation, all users will be set to use the HTML5 Viewer. This can be changed for an individual user by going to a given users preferences. The system administration can perform this action, or each individual user may change it as well.
If a user switches their preference to the Legacy Viewer, only the IE browser will support it. All other browsers will continue to use the HTML5 Viewer.

What processes document requests and where to find Viewer errors

Legacy Viewer

  • The Document Server continues to act as the sole processor for all document requests via the Legacy Viewer

    • Should issues occur, we need to health check its application pool

    • The ImageService is no longer utilized as the associated LightWeight Viewer has been replaced with the HTML5 Viewer

  • Legacy Viewer errors continue to be reported in one of two places:

    • DocumentServer.log, available on the server under C:\ProgramData\DocuPhase\Tracelogs

    • ViewerLogFile.log, available via accessing the configuration icon in the Viewer itself
HTML5 Viewer

  • The new DataServices is the sole processer for all HTML5 Viewer requests

    • Should issues occur, we need to health check its application pool

  • HTMLViewer errors are reported in one of two places:

    • DataServerice.log, available on the server under C:\ProgramData\DocuPhase\Tracelogs

      • All document related activity is reported through this log

    • DocuPhaseViewer.log

      • This would be specific issues with the viewer itself, separate from document actions
Send to ScanDox
The HTML5 Viewer supports the Send to ScanDox feature, like the Legacy viewer. However, the mechanism is perform the operation different from it. Because the HTML5 Viewer is a web component, it’s not able interact and launch local client programs. To get around this:

  • We communicate with the DocuPhase Server to obtain the connected ScanDox workstations

  • We evaluate the connection information against the requesting machine to ensure it is a valid ScanDox station

  • We then communicate with the local Upload Service, via SignalR – also used by Progression for communication – to send a request to launch ScanDox and load the selected document.

  • When the document is modified and sent back to the server from ScanDox, a request is set to the viewer to reload the current document.

  • The DocuPhaseServer.log on the server will contain the list of machines connected to ScanDox

    • It will also list if there are problems connecting to a given machine

  • The Local ScanDox workstation will report issues in the UploadService.log

Analytics

  • Analytics is now a 64bit install like other DocuPhase products.

    • There is now a ProgramData\DocuPhase Analytics folder with the pertinent a Analytics information stored there.

    • This means uninstalls and re-installs no longer overwrite this data.

  • There is a new pre-shared key that must exist in the DocuPhase Server web.config

    • This file is in the ProgramData\DocuPhase Analytics folder

    • If you uninstall/change analytics, you will need to regenerate and ensure the new key is in the DocuPhase Server web.config

    • Doing so will also force a reset of the system

Additional Changes / Information

  • Annotation controls in the HTML Viewer are now toggle controlled

    • Click once to use

    • Click again to turn off

  • The Toggle is maintained as you move from page to page within a document as well as when you move from one document to the next.

    • This allows a user to apply the same annotation, much like you could with Rubber stamps, from one document to the next

  • The ObjectID and ApplicationID are available in the Document info (properties) feature

  • For Forms customers where a DB connector is used, remember to manually move it from the C:\ProgramData\idatix\DBConnector (typical name) folder to a new C:\ProgramData\DocuPhase\DBConnector folder.