Deploying the On-Premise Agent

This guide describes how PMS Sync reaches a law firm's on-premise Aderant database, and the repeatable process for standing up that connection at a new client site. It is written for whoever runs the deployment — an Alterspective engineer working with the client's IT team. The process below was rehearsed end to end on an isolated Azure environment before first client use.

1. How the Connection Works

The cloud components (the portal and the proxy) never connect to the client's database directly. Instead, a small on-premise agent runs on a Windows host inside the client's network, next to their Aderant SQL Server. The agent exposes a read-only query API and reaches the cloud over an outboundtunnel — so the client opens no inbound firewall ports and exposes no database to the internet.

The recommended tunnel is an Azure Relay Hybrid Connection: a Microsoft-operated rendezvous point. The agent dials out and listens on the relay; the proxy sends requests to the relay, signed with a shared-access key. Neither side needs a public IP. The request path is:

Staff browser
   │  (Keystone SSO)
   ▼
PMS Sync Portal  ──►  Proxy  ──►  Azure Relay  ──►  On-prem Agent  ──►  Aderant SQL Server
  (cloud)              (cloud)     (Microsoft)       (client network)     (client network)

Each client environment carries its own connection details and its own relay key — nothing is shared between tenants. A second client is simply another configured environment.

2. What You Provision (per client)

Secrets (agent API key, relay keys, SQL password) live in Azure Key Vault. The on-prem host can read its own secrets at runtime via a managed identity — they need not be typed onto the box in plaintext.

3. Set Up the Azure Relay

In the Alterspective Azure subscription (example uses the Azure CLI):

# Resource group + relay namespace (choose a region near the client)
az group create -n rg-<client>-pms -l australiaeast
az relay namespace create -g rg-<client>-pms -n <client>-pms-relay -l australiaeast

# Hybrid connection — REQUIRE client authorization
az relay hyco create -g rg-<client>-pms \
  --namespace-name <client>-pms-relay -n aderant-agent \
  --requires-client-authorization true

# Two least-privilege rules: agent listens, proxy sends
az relay hyco authorization-rule create -g rg-<client>-pms \
  --namespace-name <client>-pms-relay --hybrid-connection-name aderant-agent \
  -n agent-listen --rights Listen
az relay hyco authorization-rule create -g rg-<client>-pms \
  --namespace-name <client>-pms-relay --hybrid-connection-name aderant-agent \
  -n proxy-send --rights Send

The agent's relay endpoint is https://<namespace>.servicebus.windows.net/aderant-agent. Keep the Listen key for the agent's .env and the Send key for the portal's environment settings.

4. Install the Agent (client host)

The agent ships as a single Windows MSI that bundles its own Node runtime and installs a supervised Windows service — no system Node, IIS, or inbound firewall rules required. The full IT-facing steps are in the installer README shipped with the MSI; the shape is:

1. Install (elevated): msiexec /i AderantAgentSetup-<version>.msi /qn /l*v install.log. The service is registered for automatic start but deliberately not started yet — it needs its configuration first.
2. Configure .env in the install folder: the read-only SQL connection, the agent API_KEY, and the Azure Relay values (namespace, path aderant-agent, the Listen rule name and key). Leave ALLOWED_ORIGINS unset — the only caller is the proxy, server-to-server.
3. Preflight: aderant-agent.cmd --check validates configuration, the SQL connection, the port, and the relay setup. Exit code 0 means ready.
4. Start: Start-Service AlterspectiveAderantAgent, then confirm GET /api/health returns ok and /api/health/ready returns 200 once the database is reachable.

Because the service runs in production mode, the agent refuses to start with a missing, too-short, or placeholder API key, and its API documentation (/docs) requires the key. These are intentional safety defaults for an internet-reachable on-prem component.

5. Connect the Environment (Settings)

In the PMS Sync portal, an administrator adds an environment for the client under Settings and fills in:

• Alterspective Proxy URL — the agent's relay endpoint (https://<namespace>.servicebus.windows.net/aderant-agent).
• Alterspective Proxy API Key — the agent API_KEY.
• Azure Relay SAS Key and SAS Rule Name — the Send rule key and its name (e.g. proxy-send). These are only needed when the Proxy URL is an Azure Relay endpoint; for a direct URL, leave them blank.
• Clio Operate connection — identity URL, API URL, client ID/secret, instance, scope.
• Optionally the default security teams, work-type mapping, and a SIEM webhook.

Leave Import writes disabled until the read-only validation week is done. All secret fields are stored server-side and never shown again — leave them blank on a later save to keep the current value.

6. Verify End to End

1. Search for a known matter on the dashboard — this proves the full read path (portal → proxy → relay → agent → SQL).
2. Preview the matter and confirm parties, roles, work type, and dates look right.
3. Enable import writes, import one low-risk matter, and confirm it in Clio Operate via the result link.
4. Re-import the same matter — it must return the existing work item, not a duplicate.

7. Troubleshooting

For the component architecture and security model, see the Technical Overview. For the staff import workflow, see the User Guide. During the pilot, your Alterspective contact is the escalation path for anything this guide doesn't cover.