Electronic Delivery Utility (.NET) Administrator Guide

This guide is for ILLiad system administrators who install, configure, and maintain the Electronic Delivery Utility. It covers the .NET implementation that ships with ILLiad 10 — what's new, how EDU works, and the full configuration and troubleshooting reference.

What's new in the .NET EDU

In ILLiad 10 the Electronic Delivery Utility's underlying components were updated from Delphi to .NET. EDU still does the same job — it takes scanned PDF/TIFF documents from staff and delivers them to borrowing libraries over Odyssey, or over OCLC Article Exchange when a lender has no reachable Odyssey address. What changed is how it connects and runs:

• Talks to ILLiad through the Web API instead of a direct database connection — no database credentials live on the workstation anymore.
• Guided first-run setup — a wizard captures your ILLiad Web API URL (with a Test Connection button), then you sign in.
• Modern authentication — username/password with automatic token refresh, or single sign-on (SSO).
• Multiple watch directories — monitor several folders at once, including subfolders.
• Built-in .sent marker workflow — close a transaction for a document you shipped out-of-band, without an Odyssey send.
• Backup folder cleanup — a built-in tool to clear out old delivered files.
• Billing moved to Odyssey Manager — EDU no longer bills on send; billing is handled centrally by Odyssey Manager.

What stays the same

• Still a per-workstation desktop application (not a background service).
• Still the watch-directory model: scan into a folder, EDU picks it up.
• Same Odyssey peer protocol on the wire and the same Odyssey port (7968) — legacy and .NET EDU can deliver to the same borrowers.
• Article Exchange is still the fallback when a lender has no reachable Odyssey address.

Where to go next

• Updating an existing ILLiad site to ILLiad 10? See Upgrading the EDU for the migration steps.
• Installing ILLiad or setting up EDU for the first time? See Setting up the EDU for the first-run walkthrough.
• The rest of this guide is the full reference — configuration, authentication, file processing, routing, troubleshooting.

How EDU works

The Electronic Delivery Utility (EDU) runs on a staff workstation on the lending side. Staff scan articles or book chapters (or hand EDU files that are already scanned as PDF or TIFF), and EDU delivers them to the borrowing library — over Odyssey when possible, or through OCLC Article Exchange when the library has no Odyssey address.

Here's the path a document takes:

1. Staff scan a document and save it into a folder EDU is watching, naming the file after the ILLiad transaction number.
2. EDU matches the file to that transaction.
3. EDU checks the file and the transaction, decides whether to send it over Odyssey or Article Exchange, and sends it.
4. Just before sending, EDU moves the request to an Awaiting Scanning status, so nothing is lost if the send is interrupted. After a successful send it leaves the request there for your routing rules (or Odyssey Manager) to move it along, adds a history note showing how it was delivered, and files the original into a Backup folder.
5. If a send fails, EDU puts the request back to where it was before pickup and adds a note explaining what went wrong. The file stays where it is — it is not moved to Backup.

EDU is a regular Windows desktop program: someone has to be signed in with EDU open for it to process files — it does not run in the background as a service. EDU does not handle billing; that happens in Odyssey Manager.

No direct database connection

The .NET EDU talks to ILLiad only through the ILLiad Web API (over HTTPS). It no longer connects straight to the SQL database the way the old Delphi EDU did — there's no database login on the workstation. This means each EDU workstation needs to reach your ILLiad Web API, not the database server.

Installation and setup

Follow the task guide for the actual steps

• Updating an existing site to ILLiad 10? Use Upgrading the EDU.
• Fresh install? Use Setting up the EDU.

The rest of this section is deployment reference — file layout, settings paths, and startup gates.

Prerequisites

• Windows desktop OS.
• .NET 10 desktop runtime installed on the workstation (part of the ILLiad 10 install).
• Network connectivity from the workstation to the ILLiad Web API (HTTPS), the destination libraries' Odyssey listeners (TCP), and/or OCLC Article Exchange (via the local Odyssey Manager relay) if Article Exchange will be used.
• A staff user account with credentials to the ILLiad Web API, or a configured SSO identity provider. EDU authenticates as a staff user, not as a service principal.

Deployment layout

The deployed install directory contains:

File	Purpose
ElectronicDeliveryUtility.exe	Main executable
appsettings.json	Machine-wide default settings
log4net.config	Log output configuration

User-modifiable settings (per logged-in Windows user) are persisted separately to:

%LOCALAPPDATA%\Atlas Systems\Electronic Delivery Utility\usersettings.json

Settings path changed — a one-time migration handles it

The per-user settings file moved to %LOCALAPPDATA%\Atlas Systems\Electronic Delivery Utility\usersettings.json. On first launch, if that file doesn't yet exist, EDU performs a one-time migration that copies the earlier file forward from %LOCALAPPDATA%\ILLiad\ElectronicDeliveryUtility\usersettings.json. No action required.

Logs did not move. They remain under %APPDATA%\ILLiad\ElectronicDeliveryUtility\Logs\.

Logs are written to:

%APPDATA%\ILLiad\ElectronicDeliveryUtility\Logs\

First run

EDU ships a guided first-run flow — an API URL wizard, then sign-in, then watch-directory setup. For the full step-by-step walkthrough, see Setting up the EDU. Two things worth knowing at the reference level:

• What triggers the wizard. The shipped API base URL is blank on purpose; a blank value is what opens the first-run API URL setup window. Enter your real API URL there rather than hand-editing appsettings.json.
• Startup gates. After sign-in, two hard-stop checks run before file watching begins — a version check (VersionElectronicDeliveryUtility) and a server-address (ILLiadServerIP) presence check — either of which shows a dialog and exits if the server is misconfigured. An Article Exchange availability diagnostic is also logged (non-fatal).

No installer, no auto-start, no tray icon

EDU is a foreground application — no tray-icon mode, no Windows service registration, no auto-start logic. If unattended operation is desired, schedule the executable through Windows Task Scheduler at user logon. There is also no single-instance check; running two copies against the same watch directory will cause both to try to process each file.

Configuration

EDU layers configuration in two tiers:

1. Machine-wide defaults from appsettings.json (sections ApiSettings, FileWatcherSettings, ProcessingSettings, OdysseySettings).
2. Per-user overrides from usersettings.json (under %LOCALAPPDATA%\Atlas Systems\Electronic Delivery Utility\).

When both exist, the per-user values win.

appsettings.json

You normally don't edit this file by hand — the first-run wizard and the Settings window manage it for you, and every property is documented in the tables below.

note

BaseUrl ships blank on purpose

The shipped appsettings.json sets BaseUrl to "" — which is exactly what triggers the first-run API URL wizard. Enter your real API URL in that wizard rather than hand-editing the file.

note

Two keys are user-only, not in appsettings.json

ApiSettings.ValidateSSL (default true) and ProcessingSettings.Cleanup.FileAgeThresholdDays (default 30) exist in the settings model but are not in the shipped appsettings.json. They only appear once a user saves settings from the UI.

Full settings reference

ApiSettings

Property	Default	Range	Purpose
BaseUrl	(blank; set via wizard)	—	Root URL of the ILLiad Web API. Blank triggers the first-run wizard.
TimeoutSeconds	30	1–300	Per-attempt HTTP timeout budget
ValidateSSL	true	—	Enforce TLS certificate validation. Persisted to usersettings.json.

FileWatcherSettings

Property	Default	Purpose
DefaultWatchDirectory	(blank)	One or more directories to monitor, separated by comma, semicolon, or newline
ScanIntervalSeconds	30	Periodic re-scan interval (see note)
ProcessingDelaySeconds	5	Carried into processing configuration (see note)
SupportedExtensions	[".pdf", ".tif", ".tiff"]	Document types (see note)

note

Two FileWatcherSettings values don't do what their names suggest

ScanIntervalSeconds — the file-processing orchestrator uses a fixed 30-second monitor sweep regardless of this key.

ProcessingDelaySeconds — this value is carried into processing configuration but is not the mechanism that waits for a scanner to finish writing. File readiness is governed independently by a minimum age plus stability/lock checks (see File readiness).

SupportedExtensions — the runtime scanner set also includes .sent so the marker workflow works. Recursive watching is forced on and is not configurable.

ProcessingSettings

Property	Default	Range	Purpose
MaxRetryAttempts	3	0–10	Odyssey send retry count for transient errors
RetryDelaySeconds	5	—	Base delay seeding the retry backoff
MaxConcurrentFiles	5	1–20	Maximum files sent concurrently
DefaultProcessType	"Lending"	—	Lending / DocDel / Both
WatchLending	true	—	Process Lending transactions
WatchDocDel	false	—	Also process Document Delivery transactions
AutoMode	false	—	When true, files process automatically as they arrive; when false, staff trigger with Send Selected Files
Cleanup.FileAgeThresholdDays	30	1–365	Age threshold for Backup folder cleanup

OdysseySettings

Property	Default	Purpose
DefaultServerAddress	localhost	Fallback Odyssey/Odyssey Manager server address for this workstation
DefaultServerPort	7968	Odyssey TCP port (see note)
ConnectionTimeoutSeconds	10	Timeout for opening an Odyssey peer connection
SendTimeoutSeconds	30	Timeout per send operation

note

DefaultServerPort is 7968, the real Odyssey port

This value is used only as a fallback when a system-ID customization key can't be parsed as a full Odyssey URL. Outbound connections to lenders use the address from the lender's OdysseyIP, which already includes the destination port.

UserSettings (persisted per-user)

Property	Purpose
LastApiUrl, LastWatchDirectory, LastProcessType, LastAutoMode	Remembered selections (including the persisted Auto Mode toggle)
RememberSettings	Toggle for whether to persist the above
Theme	Theme selection (default Office2019Colorful)
MainWindow (Width/Height/Left/Top/IsMaximized)	Window layout
RememberUsername / SavedUsername	Login convenience

Editing settings

Most settings can be edited from the in-app Settings window (four tabs):

• File Processing — Process Lending / Process Document Delivery checkboxes, a multi-line Watch Directories box with an Add… folder picker, and an Enable Auto Mode checkbox.
• API Settings — API Base URL, Timeout (1–300), and Validate SSL Certificates (default checked).
• Appearance — theme combo.
• Advanced — Max Retry Attempts (0–10), Max Concurrent Files (1–20), and Backup Cleanup → File Age Threshold (1–365).

The footer has Test Connection, OK, and Cancel. When opened as part of first-run setup, the title becomes "Initial Setup - Configure Required Settings."

Hand-edited values are clamped on read-back

When EDU reads usersettings.json, it clamps integers to the same ranges the Settings dialog enforces — Timeout [1,300], Max Retry Attempts [0,10], Max Concurrent Files [1,20] — so a hand-edited file can't push an out-of-range value past UI validation.

log4net.config

The shipped logger writes to three rolling files under %APPDATA%\ILLiad\ElectronicDeliveryUtility\Logs\:

File	Levels	Rolling	Backups
EDU_yyyy-MM-dd.log	Information+	Daily	30
EDU_errors_yyyy-MM-dd.log	Warning+	Daily	90
EDU_debug.log	Debug+	50 MB size-based	5

Web API URL configuration

The API base URL is the only required setting before EDU can authenticate. On first run it's captured by the API URL setup wizard, which:

• Normalizes and corrects the entered URL — prepends https://, strips trailing slashes, removes accidental endpoint suffixes (/auth, /login, /transactions, and similar), and appends /illiad/api or /api when appropriate.
• Tests connectivity with its own probe: a GET against the entered base URL (and a /api variant), treating HTTP 2xx or 401 Unauthorized as reachable. The probe honors the Validate SSL setting. Next enables only after a successful test.

Correcting the URL later — the Change button

The Login window has a small Change button ("Change the API URL and start over"). Clicking it reopens the wizard, persists the corrected URL, and returns to the login screen — no restart required. The API URL can also be edited later on the API Settings tab.

HTTP/1.1 is forced to avoid issues with some IIS / HTTP/2 configurations. If the URL is wrong or the API is unreachable at login, the login attempt fails with a UI error and the user stays on the login dialog.

Authentication and SSO

Staff sign in to EDU with their ILLiad username and password, or through your library's single sign-on (SSO). EDU keeps them signed in during the session, and on a shared server it works in the site the staff member picked at login. See EDU Authentication and SSO.

Directory configuration

Watch directories are set on the Settings File Processing tab; for the step-by-step (including the Add… folder picker and separator rules), see Setting up the EDU. This section covers the reference behavior.

How watching works

EDU watches each configured directory plus runs a periodic sweep. Recursive watching is forced on, so subfolders under each watch root are monitored too. Files under any Backup folder or any dot-prefixed ancestor directory are excluded from pickup. There is no per-NVTGC routing — every watched directory is global to this EDU instance.

Server image-path keys seed the first-run default only

On first run, when no watch directory is configured, EDU reads ElectronicDeliveryUtilityImagesPathLending and ElectronicDeliveryUtilityImagesPathDocDel to default the watch directory — but only for a value that resolves on this workstation. A seeded-but-missing path is ignored, and the user is prompted to configure one. After first-run seeding, the effective watch list is the local setting; the keys aren't re-read on every start.

Required pre-existing folders

EDU does not create watch directories on startup. Saving a watch directory requires it to already exist, and if a watched directory later disappears the monitor raises an error. When multiple directories are configured, a non-existent one is skipped with a warning rather than aborting the whole monitor.

Backup subfolder

When a file is delivered successfully, EDU moves it to a Backup subfolder created in the same directory as the source file (so a file dropped in a nested subfolder gets a nested Backup). The recursive-watch exclusion of Backup folders keeps the scanner from re-picking-up retained files.

File processing

Detecting files

EDU watches each folder two ways: it reacts to file changes as they happen (new, changed, or renamed files) and also re-scans every folder about every 30 seconds to catch anything it missed. Only files with an allowed extension are picked up — .pdf, .tif, .tiff, and the .sent marker — and EDU remembers what it has already seen so a re-scan doesn't process the same file twice.

Making sure a file is finished

A scanner may still be writing a file when EDU first notices it, so before opening one EDU confirms it's fully written: the file isn't empty (non-zero size), it's at least ~2 seconds old, EDU can open it exclusively (nothing else has it locked), and its size and timestamp have held steady across three checks half a second apart. This — not the ProcessingDelaySeconds setting — is what actually waits for the scan to finish.

Validation

• File check: the file exists, has an allowed extension, is finished writing, and its name contains a transaction number. EDU reads the transaction number from the filename — leading digits, a TN/Transaction prefix, or any run of 5 or more digits. There's no size limit on the file.
• Transaction check: EDU must be signed in, then it looks up the transaction and confirms it's the type this workstation handles and is at the expected pre-send status — "In Stacks Searching" for Lending/Borrowing, or "In DD Stacks Searching" for Document Delivery.

Validation failures are not moved to Backup

A file that fails file or transaction validation is added to an invalid-file cache and skipped. It's not routed to a failed status and not moved to Backup. Only a send failure produces a status revert and a note.

Retry behavior

Transient Odyssey send errors trigger up to MaxRetryAttempts (default 3) retries with exponential backoff (30 / 60 / 120 s). Non-retryable conditions fail immediately. There is no automatic cross-method fallback — a failed Odyssey send does not silently retry via Article Exchange, and vice versa.

Post-processing file move

On a successful send the source file is moved to a Backup subfolder beside it; on a name collision a timestamp suffix preserves both files; a move failure is a warning, not a failure of the delivery. On a send failure there is no Backup move — the file stays in place.

Delivery method routing

For each document, EDU decides how to deliver it: straight to the borrowing library over Odyssey, or through OCLC Article Exchange when that library has no Odyssey address (or you've set it to prefer Article Exchange). See Delivery Method Routing.

Transaction integration

Status transitions

• Before sending: EDU moves the request to "Awaiting Lending Scanning" (or "Awaiting Doc Del Scanning" for Document Delivery). The change is recorded as System, so if EDU is interrupted mid-send the request can be picked up again.
• On success: EDU leaves the request at that Awaiting …Scanning status for your routing rules (or Odyssey Manager) to move it forward. It no longer sets a "sent" status — the old Electronic Delivery - Sent / Failed statuses were removed.
• On failure: EDU puts the request back to the searching status it had before pickup (again recorded as System).

History entries & notes

On success a history entry names the delivery method. The .sent workflow records "Manually shipped (.sent marker processed by EDU)." On failure a note is added containing the error message, recorded as a System-type note but added by the signed-in user.

Web API endpoints used (transaction side)

Method	Endpoint	Purpose
GET	transactions/{tn}	Fetch transaction details
PUT	transactions/{tn}/route	Status transition (with asSystem flag)
(history POST)	—	Add a history entry
(notes POST)	—	Add a note
GET	customization/key/{key}	Read customization values

What EDU does not do

• Billing: EDU writes no billing tables. Billing is handled centrally by Odyssey Manager. If you previously relied on legacy EDU send-side billing, configure the corresponding billing customization keys in Odyssey Manager instead.
• Aggregate statistics: EDU maintains no per-session counters; logs are the source of truth for activity and errors.

.sent marker workflow

Sometimes a document is sent to the borrowing library outside of ILLiad — by email or fax, for example. To close out the request in that case, staff drop a small marker file into a watched folder (named with the transaction number and ending in .sent). EDU sees it and marks the request finished without trying to send anything over Odyssey. See The .sent Marker Workflow.

Monitoring and troubleshooting

EDU keeps activity logs (with passwords and tokens hidden), shows its current status right in the window, and lists the errors you're most likely to run into. See Monitoring and Troubleshooting.

Backup folder cleanup

After a document is delivered, EDU keeps a copy in a Backup folder. A built-in cleanup tool lets you review and remove copies older than a number of days you choose. See Backup Folder Cleanup.

Customization keys

EDU reads customization keys through the Web API; keys are NVTGC-scoped by the current site. EDU consumes the server address / startup-gate keys and the two image-path keys at config/first-run time; the rest drive Article Exchange availability, Odyssey identity/symbol resolution, version gating, and multi-tenant mode.

Key	Purpose
ILLiadServerIP	Odyssey/Odyssey Manager server address for the local site; also a post-login startup gate. Defaults to localhost if unset.
VersionElectronicDeliveryUtility	Version this ILLiad server expects; startup gate that can terminate EDU on mismatch.
VersionClient	User-Agent suffix the server expects.
OCLCILLAuthorization, OCLCILLPassword, OCLCWebServiceV2APISecret, OCLCWebServiceV2APIKey, ILLiadWebPlatformConfig	The five keys that must all be set for Article Exchange to be available.
OdysseySystemID, OdysseySystemIDAlt	Odyssey system identity used to build this workstation's sender URL.
OdysseyLocalReceiverIDs, OdysseyLocalSenderIDs	Local Odyssey receiver/sender identifiers.
OdysseyReceive, OdysseySend	Odyssey receive/send enablement.
SystemIDOCLCSymbol, SystemIDDOCSymbol, SystemIDRAPIDSymbol, SystemIDISOSymbol	Symbol resolution for OCLC / DOCLINE / RAPID / ISO.
SharedServerSupport	Multi-tenant / shared-server mode flag.
ElectronicDeliveryUtilityImagesPathDocDel, ElectronicDeliveryUtilityImagesPathLending	Seed the first-run watch-directory default (only a value that resolves on this workstation is adopted).

EDU consumes these keys; it does not define them

Customization keys live in the existing ILLiad Customization table and are read via the Web API. EDU introduces no schema changes.

What changed from the Delphi EDU

This table maps the old Delphi EDU to the .NET implementation for reference. For the step-by-step migration procedure, see Upgrading the EDU.

Area	Delphi EDU	.NET EDU
ILLiad access	Direct SQL connection	ILLiad Web API over HTTPS — no database credentials on the workstation
First-run setup	Manual config	Guided API URL wizard (with Test Connection); watch directory seeded from server image-path keys when they resolve, else a post-login prompt
Authentication	DB-level auth	JWT bearer token; username/password with automatic refresh, or SSO discovered at runtime
Configuration	INI/registry	appsettings.json (machine) and usersettings.json (per user)
Logging	Built-in	log4net with token/password masking
Status on success	Electronic Delivery - Sent	Left at Awaiting …Scanning for routing rules / Odyssey Manager to advance
Billing	Send-side billing in EDU	Handled centrally by Odyssey Manager
.sent markers	(Not present)	Update-only workflow that closes a transaction without an Odyssey send
Backup cleanup	(Not present)	Built-in preview + recursive discovery + confirmation dialog
Multi-directory monitoring	Single watch path	Comma-, semicolon-, or newline-separated list; recursive watch