Installation Checklist

Quick steps to follow in order to get Supporting Document Autoloader up and running.

In order to successfully install the Supporting Document Auto-loader (SDA) application, the following steps need to be carefully followed.

  1. Pre-Installation Checklist:
    1. SDA must be installed on a system that has the 64-bit Caseware Working Papers installed and configured.
    2. SDA is a small service that does not require any other dependencies other than .NET 4.5 Framework.
    3. SDA is a 64-bit service, therefore it needs to be installed on a 64-bit operating system.
    4. The Caseware Working Papers client file needs to be accessible from this host either as a local file or via a network share.
    5. The spool directory to monitor needs to be accessible from this host either as local folder or as a network share.
  2. Installation:
    1. To install the service just run the installer and follow the prompts as an administrative user.
  3. Configuration:
    1. By default the service is installed in Manual start mode.  Configure it first by editing the autoloader-config.xml file as per below instructions, then change the startup type to Automatic and start the service.  If you use network shares, ensure that the account that has access to those shares is configured as the start account for the service.
    2. The configuration is contained in one XML file located in the installation directory, usually %PROGRAMFILES%\F. H. Black & Company Incorporated\SDA\, called autoloader-config.xml.  
    3. These bits of information are required to configure the SDA file:
      1. Is mail notifications to be used?  
        1. If Yes – then the SMTP server address and port, as well as From address to use is needed.  Configure the mail-settings and email-notifications elements.
        2. Email notifications will be sent for the following events:
          1. Failure in starting the application
          2. Failure in importing a file into Caseware
      2. The file types to import is required as a filter, and specified as a list of extensions, such as .pdf, .xls etc.  Configure the file-import-types element.
      3. An arbitrary amount of watched folders can be configured.  Each watched folder corresponds to one Caseware Working Papers Client file.  For each watched folder:
        1. The spool (Source) directory to monitor for incoming files need to be created then specified in here. SDA needs full filesystem permission to this directory as it will create subdirectories inside this folder, and move files around as they are imported.
        2. The target Caseware document folder (Destination) name needs to be specified – this is the name of the folder in Caseware to which these files will be imported.
        3. The target Caseware file (.ac) to import into needs to be specified.
        4. The physical path to where this Caseware file resides, needs to be specified.
        5. If Caseware compression is needed, this option should be turned on.
        6. The Caseware username/password to access this file (if required) must be documented.
        7. If email notifications have been turned on, the recipient email address(es) are needed.
    4. Ensure that if you are editing the XML file on a Windows Vista or newer or Windows 2008 or newer system, you use Notepad and not any other editor as folder virtualisation would interfere with saving to the correct file location.
  4. Startup:
    1. Once configured, start the service.  Any errors will be logged in the Application EventLog.  Open Event Viewer, expand the Windows Logs node then review the Application log for errors related to Source SupportingDocAutoloaderService. 

The following table contains a brief overview of the XML attributes and their meanings:

Element Attribute Mandatory? Description
mail-settings   Yes Contains mail server details to submit emails on errors (loading of application and importing of files).
  smtp-server Yes IP/Host name of SMTP server for submission of emails. If not to be used, leave this field blank.
  smtp-port No Optional port for mail server. Defaults to 25.
mail-settings/sender full-name Yes From name to use in email submissions
  email-address Yes From email address to use in email submissions
common-settings/email-notifications   No List of recipients for any email notifications unless overridden in a watched-folder.
common-settings/email-notifications/recipient full-name Yes Recipient full name for emails sent
  email-address Yes Recipient email address for emails sent
common-settings/file-import-types   No List of global file types that will be imported. This is the default list if not overridden in a watched-folder
common-settings/file-import-types/file-type extension Yes The extension of the file to import.  Must start with a period.  As an example, to import PDF files use .pdf
watched-folder   Yes At least one watched-folder needs to be specified. Each watched-folder correlates to one Caseware Working Papers file.
  group-name Yes A user defined name to identify this group.
  cw-import-folder-name Yes The Caseware folder name that SDA will create and use to import the documents in to, unless it is overwriting an existing document and the file contained a document number, and the auto-parse-documentnumbers attribute is set to true.
  cw-import-folder-name-superseded No If auto-parse-documentnumbers is set to true and an existing document number was found, the replaced document will be moved to the folder specified in this attribute, and the document name will be made unique by the prefixing of a unique sequence number. If this attribute is not specified or empty, the replaced document will be left in the same folder it was found in, but renamed to be unique.
  cw-username Yes The Caseware document user name to use to import the document as.
  cw-password Yes The Caseware password for the cw-username user above.
  target-folder Yes The physical path to the folder containing the Caseware Working Papers file. An example would be c:\Program Files\CaseWare\Data\Samp01\. UNC names are supported. Do not use mapped drives. For UNC names, ensure a dedicated Windows domain account exists with access to that network share, set to never expire password, then change the FHB Supporting Document Autoloader service in services.msc to Log On As this user account.
  source-folder Yes The physical path to the spool folder where documents will be copied to to be imported into Caseware Working Papers. Supports UNC paths. Do not use mapped drives.
The name of the file can include two additional pieces of information embedded in the name: the document ID and the user to sign off as. To use this feature, ensure the file adheres to this naming convention:
<Base file name> [document identifier] - <user to sign off as>.<file extension>
If the file name is BankRecon2018.xls, then to (optionally) have it created as document id 111.A and signed off as user jsmith, ensure the file is named as follow BEFORE uploading to this folder:
BankRecon2018 [111.A] - jsmith.xls
Also, make sure the attribute auto-parse-documentnumbers is set to true in order to parse document numbers, and ensure auto-parse-filenames is set to true to parse the user to sign off as.
  target-cw-file Yes The name of the Caseware Working Papers file to which files will be imported, usually with an .ac extension.
  save-compressed No true or false. If true, and if the Caseware file supports it, the document will be compressed.
  attr-roll-forward No true or false. If true, the roll forward flag will be set for the imported document.
  attr-roll-forward-as-placeholder No true or false. If true, the roll forward as placeholder flag will be set for the imported document. Requires Caseware Working Papers 2012 or newer.
  attr-retained-on-cleanup No true or false. If true, the retained on cleanup flag will be set for the imported document.
  attr-lockdown No true or false. If true, the lockdown flag will be set for the imported document.
  auto-parse-filenames No true or false. If true, the file name parsing explained under source-folder will take place automatically, and the signed off as user name will be extracted if provided. Otherwise (default), the file name will not be parsed for the signed off as value.
  auto-parse-documentnumbers No true or false. If true, the file name parsing explained under source-folder will take place automatically, and the document number will be extracted if provided. Otherwise (default), the file name will not be parsed fopr the document number.
  trim-imported-filename No true or false. If true, the files moved to the Imported folder will be stripped of any sign off as and document number annotations. If false, the files will be moved to the Imported folder unaltered.
watched-folder/tags   No Allows custom tags to be associated with the uploaded documents. All documents imported into this Caseware Working Papers file will be assigned the tags listed here.
watched-folder/tags/tag name Yes The name of the tag.
watched-folder/settings   No Settings specified here override the global settings. Same options are available as under common-settings.