CTS DirectConnect

CTS DirectConnect is designed for Capture in the Cloud.

CTS DirectConnect allows you to connect network based scanners to your Capture in the Cloud instance by scanning to folders that are continuously monitored. The ingestion of documents from these folders can be set up to run automatically using a Windows service or executed on demand. Built-in reliability features include automatic retries, error handling with dedicated error folders, and optional file backup for added protection. Advanced functionality such as encrypted credential management, recovery of failed files, and detailed logging ensures both security and transparency.

Click here for CTS DirectConnect Legacy Documentation.

Preparation

Before you begin, make sure you have the following:

The CTS DirectConnect package. Download it here: GlobalCapture_DirectConnect.zip .
The URL of your GlobalCapture CTS instance: capture-mycompany.mysquare9.com.
A privileged user and password to authenticate to GlobalCapture CTS. This user should have a scan license. For more information on licensing in GlobalCapture, refer to our knowledge base article, “License Management”
An internet connected workstation capable of running CTS DirectConnect, see our hardware requirements for more information.

It is best practice to install CTS DirectConnect on your server as to not rely on any one persons PC to be the destination of all scans.

Configuring CTS DirectConnect

Setup

Download and Extract the contents of the package.

While this folder can be placed anywhere, it must remain in place and accessible at all times, as it contains required components that the system relies on for proper operation. Deleting, moving, or restricting access to this folder may cause errors or prevent the service from running correctly.

Best practice is to create a folder on the root called S9Media and adding the extracted folder here.

Create a copy of the appsettings.template.json to the same location and rename the copied file appsettings.json.

Open the appsettings.json and add your Capture API endpoint to the BasePath. All other settings are optional. See appsettings.json Details below.

The BasePath should look like:

https://<your_instance>.mysquare9.com/square9captureapi

CODE

{
  "AppSettings": {
    "BasePath": "https://<your_instance>.mysquare9.com/square9captureapi",
    "VerboseLogging": false,
    "DefaultWatchPath": "C:\\Watch",
    "DefaultBackupPath": "C:\\Backup",
    "HttpTimeoutMinutes": 2,
    "MaxRetryAttempts": 3,
    "RetryDelaySeconds": 30,
    "FailedRetryHours": 24,
    "MaxConcurrentUploads": 2,
    "UploadDelayMs": 0,
    "WatchFolders": []
  }
}

Create a Secure Credentials file. Make sure this user is a GlobalCapture Administrator.
1. Open a CMD prompt. Make sure to run the CMD prompt as an Administrator.
2. Change the directory to the location of your unzipped file.
3. Run the command:

CODE

FileUploader.exe --encrypt-creds “<your_username>” “<your_password>”

Generate the Workflow Config File. This will pull all the workflows from GlobalCapture that have the CTS DirectConnect node, and update the appsettings.json file.
1. From an Administrator CMD prompt, change the directory to the location of your unzipped file.
2. Run the command:

CODE

FileUploader.exe --build-config

If you run --build-config where it has previously been run, the application will attempt to merge the existing with the new.

Create the watch folders by running FileUploader.exe. This will create all the watch folders.

CODE

FileUploader.exe

If you configure the service to run automatically, watch folders will be automatically created.

Press CTRL+C to quit when prompted.

Executing Workflows

Ingestion of documents from the watch folders can be executed multiple ways.

Uploading a Single Document from ANY Location on Demand

Individual documents can be upload to a GlobalCapture workflow from ANY location on demand. This is handy when dealing with a one off document.

Open a CMD prompt as an Administrator.
Change the directory to the location of you GlobalCapture_DirectConnect extracted file.
Run FileUploader.exe with the file path to the watch folder.

CODE

FileUploader.exe "<fully qualified path to file>"

You will be prompted to select the workflow to process the document. Enter the number of the workflow and press Enter.

The document will enter the selected workflow and appear in the GlobalCapture Batch Manager. The file is NOT deleted from the source location.

Uploading Documents From ALL Watch Folders on Demand

Open a CMD prompt as an Administrator.
Change the directory to the location of you GlobalCapture_DirectConnect extracted file.
Run FileUploader.exe.

CODE

FileUploader.exe

Uploaded documents are removed from the Watch folders.

Automated Ingestion from ALL Watch Folders

Create a Service that runs in the background and automatically ingests files are deposited into the watch folders.

Open a CMD prompt as an Administrator.
Run: sc create "GlobalCapture DirectConnect" binPath="<pathtoyourfile>\FileUploader.exe --service" start=auto

CODE

sc create "GlobalCapture DirectConnect" binPath="<pathtoyourfile>\FileUploader.exe --service" start=auto

Start the service: sc start “GlobalCapture DirectConnect”

CODE

sc start “GlobalCapture DirectConnect”

Updating Workflows

When new workflows are constructed, the appsettings.json needs to be updated. This will add the new workflow(s) to the WatchFolders array and create the watch folder in the designed location.

Generate the Workflow Config File. This will pull all the workflows from GlobalCapture that have the CTS DirectConnect node, and update the appsettings.json file.
1. Open a CMD prompt. Make sure to run the CMD prompt as an Administrator.
2. Change the directory to the location of your unzipped file.
3. Run the command:

CODE

FileUploader.exe --build-config

If you run --build-config where a it has previously been run, the application will attempt to merge the existing with the new.

Create the watch folders by running FileUploader.exe. This will create all the watch folders.

CODE

FileUploader.exe

If you have configured the service to run automatically, watch folders will be automatically created.

Update Command

You can create a simple batch file that executes the above commands with a click.

Create a file with the following code.

Update the file path on line 2 to reflect the location of your GlobalCapture_DirectConnect folder.

CODE

@echo off
cd /d "C:\S9Media\GlobalCapture_DirectConnect"

:: Run first command and wait
FileUploader.exe --build-config

:: Start second command, wait 2 seconds, then kill it
start "" FileUploader.exe
timeout /t 2 >nul
taskkill /im FileUploader.exe /f

exit

Save the file with a .bat extension.

Run this each time a new workflow is created to add the workflow to the appsettings.json and create the watch folder.

Failed File Recovery

If a document fails to be uploaded to the GlobalCapture workflow, it is moved to a failed files folder located within the watch folder for that particular workflow.

Navigate to the failed folder.
Remove the timestamp and _FAILED suffix from the file name.
Move the file back to the watch folder.
Delete the corresponding .error.txt file.

appsettings.json Details

Available configurable parameters for the ingestion of documents using DirectConnect.

Parameter	Description	Default	Required
`BasePath`	Base URL of the workflow API	-	Yes
`VerboseLogging`	Enable detailed error logging	false	No
`TargetId`	Default workflow ID (used for interactive mode)	-	No
`DefaultWatchPath`	Default path for auto-generated watch folders	`C:\Watch`	No
`DefaultBackupPath`	Default path for auto-generated backup folders^	`C:\Backup`	No
`HttpTimeoutMinutes`	HTTP request timeout in minutes	2	No
`MaxConcurrentUploads`	Maximum simultaneous file uploads	2	No
`MaxRetryAttempts`	Number of retry attempts for failed uploads	3	No
`RetryDelaySeconds`	Base delay between retries (with exponential backoff)	30	No
`FailedRetryHours`	Hours to wait before retrying failed files	24	No
`UploadDelayMs`	Delay in milliseconds before processing each file	0	No

^The Backup folder is only created when if BackupFiles is configured true for one or more watch folders in the WatchFolders array.

WatchFolders Array Configuration

These will automatically be populated and only appear in the WatchFolder array only after the setup is complete.

Each watch folder in the WatchFolders array supports:

Parameter	Description	Required
`Path`	Full path to the folder to monitor	Yes
`TargetId`	Workflow ID for files in this folder	Yes
`Name`	Descriptive name for the workflow	No
`BackupFiles`	Whether to backup processed files	No
`BackupLocation`	Path to backup processed files	No*

*Required if BackupFiles is true

Sample appsettings.json File

CODE

{
  "AppSettings": {
    "BasePath": "https://capture-educationtest.mysquare9.com/square9captureapi",
    "VerboseLogging": false,
    "DefaultWatchPath": "C:\\Watch",
    "DefaultBackupPath": "C:\\Backup",
    "HttpTimeoutMinutes": 2,
    "MaxRetryAttempts": 3,
    "RetryDelaySeconds": 30,
    "FailedRetryHours": 24,
    "MaxConcurrentUploads": 2,
    "UploadDelayMs": 0,
    "WatchFolders": [
      {
        "Path": "C:\\Watch\\SCAR_Delivery_Receipts",
        "TargetId": "62177a76d104a460d9aa9568",
        "Name": "SCAR Delivery Receipts",
        "BackupFiles": false,
        "BackupLocation": "C:\\Backup\\SCAR_Delivery_Receipts"
      },
      {
        "Path": "C:\\Watch\\Auto_Deal_Processing",
        "TargetId": "634eb6bcf70728df5bb015f4",
        "Name": "Auto Deal Processing",
        "BackupFiles": false,
        "BackupLocation": "C:\\Backup\\Auto_Deal_Processing"
      },
      {
        "Path": "C:\\Watch\\Process_AR_Delivery_Receipts_with_Rapid_Adapt",
        "TargetId": "650346b13c24c36c4ddd702a",
        "Name": "Process AR Delivery Receipts with Rapid Adapt",
        "BackupFiles": false,
        "BackupLocation": "C:\\Backup\\Process_AR_Delivery_Receipts_with_Rapid_Adapt"
      },
    ]
  }
}

Troubleshooting

Log File

Log files are automatically generated to record system activity, including processed files, errors, and status updates. CTS DirectConnect processes are monitored and logged in a log file located within the GlobalCapture_DirectConnect folder. A folder called logs will be created once the process begins. These logs provide valuable insight for troubleshooting and performance monitoring.

"FileUploader Service starting..." - Service startup
"Started monitoring folder: {FolderPath}" - Folder monitoring active
"Successfully processed file: {FilePath}" - File processing success
"Moved failed file to: {FailedPath}" - File processing failure

Log files are kept for 30 days.

Diagnostic Commands

Service	Command
Check Service Status	CODE `sc query "GlobalCapture Direct Connect"`
View Service Configuration	CODE `sc qc "GlobalCapture Direct Connect"`
View Logs	CODE `type "logs\fileuploader-*.log"`

Common Issues

Files Not Being Processed

Symptom: Files added to watch folders are not being ingested.

Check:

Check if the service is running: sc query "GlobalCapture Direct Connect".
Folder permissions: Service account has read/write access.
File locks: Files are not in use by another application.
Configuration: Watch folder path is correct.
Logs: Check for error messages.

Authentication Failures

Symptom: HTTP 401/403 errors in logs.

Check:

Verify credentials are correct.
Re-encrypt credentials: FileUploader.exe --encrypt-creds username password.
Test API access manually.

Connection Issues

Symptom: HTTP timeout or connection errors.

Check:

Network connectivity to API server.
Firewall settings.
Proxy configuration (if applicable).
API server status.
Increase HttpTimeoutMinutes in configuration.

File Process Failures

Symptom: Files moved to failed folder.

Check:

Error details in .error.txt files.
File format compatibility.
Workflow configuration on server.
API server logs.

Service Won’t Start

Symptom: Windows service fails to start.

Check:

.NET 8 Runtime is installed
Configuration file exists and is valid JSON
Service account permissions
Windows Event Log for service errors