Deploying the On-Premise Agent

This guide describes the standard procedure for deploying the PMS Sync on-premises SQL agent and connecting it to the Alterspective Cloud and Clio Operate tenant. It is written for deployment engineers collaborating with client IT administrators.

1. How the Connection Works

The cloud components (the Portal on port 3060 and the Proxy on port 3050) never connect directly to the client database. Instead, a lightweight on-premises agent (port 4102) runs on a Windows host inside the client network, adjacent to the Aderant SQL Server. The agent connects outbound over TLS (port 443) to anAzure Relay Hybrid Connection — opening zero inbound firewall ports.

Staff Browser / Widget
   │  HTTPS (Port 443 -> Container 3060)
   ▼
PMS Sync Portal (Port 3060)  ──►  API Proxy (Port 3050)  ──►  Azure Relay (Port 443)  ──►  SQL Agent (Port 4102)  ──►  Aderant SQL (Port 1433)
  (Alterspective Cloud)             (Orchestrator)              (Microsoft Rendezvous)        (Client Host / LAN)          (db_datareader)

2. Provisioning Summary (per client environment)

3. Provision the Azure Relay

In the Alterspective Azure subscription (using Azure CLI):

# 1. Resource group & relay namespace (select geographic region close to the client host)
az group create -n rg-<client>-pms -l australiaeast
az relay namespace create -g rg-<client>-pms -n <client>-pms-relay -l australiaeast

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

# 3. Create least-privilege SAS rules
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 endpoint resolves to https://<namespace>.servicebus.windows.net/aderant-agent. The agent-listen key is installed into the agent host configuration; the proxy-sendkey is stored in the portal environment settings.

4. Install and Verify the Agent (Client Host)

The agent ships as a standalone Windows MSI that packages a self-contained Node runtime and installs as an automatically recovering Windows service:

1. Install MSI (Elevated PowerShell):

   msiexec /i AderantAgentSetup-<version>.msi /qn /l*v install.log

   The service is registered with automatic startup but remains stopped until configuration is applied.
2. Configure Environment: Populate the .env file in the service installation directory:

   PORT=4102
   SQL_SERVER=192.168.1.50
   SQL_DATABASE=AderantExpert
   SQL_USER=pms_sync_reader
   SQL_PASSWORD=<StrongSecretPassword>
   API_KEY=<SecureRandom32CharString>
   AZURE_RELAY_NAMESPACE=<client>-pms-relay
   AZURE_RELAY_PATH=aderant-agent
   AZURE_RELAY_RULE_NAME=agent-listen
   AZURE_RELAY_KEY=<ListenSasKey>

3. Preflight Diagnostic Verification: Run the preflight checker before starting the service:

   aderant-agent.cmd --check

   This command validates port 4102 availability, SQL credentials, network latency to the database, and Azure Relay socket binding. Exit code 0 confirms all prerequisites are met.
4. Start Service:

   Start-Service AlterspectiveAderantAgent

   Confirm that GET http://localhost:4102/api/health returns 200 OK andGET http://localhost:4102/api/health/ready confirms active SQL connectivity.

5. Connect Environment & Role Cardinality Configuration

In the PMS Sync Portal, navigate to Settings → Environments and supply the connection details:

• Alterspective Proxy URL: Hosted proxy endpoint (e.g. https://aderant-proxy.alterspective.com.au).
• Azure Relay Endpoint: https://<namespace>.servicebus.windows.net/aderant-agent.
• Azure Relay SAS Key & Rule Name: The proxy-send key and rule name.
• Clio Operate Connection: Identity URL, API URL, client ID, client secret, and scope.
• Role Cardinality Mapping: Configure work-type participant rules. Designate single-allocation roles (Claim Handler, Responsible Partner) vs multi-allocation roles (Counsel, Expert Witnesses), ensuring pre-import validation catches conflicts before writes execute.
• Default Security Teams: Configure mandatory matter access groups to stamp on import.

6. End-to-End Verification Checklist

1. Search Verification: Query a known matter code on the dashboard to test the read path (Portal → Proxy → Relay → Agent → SQL).
2. Preview & Cardinality: Open the matter preview to confirm client details, parties, and role badges resolve with zero cardinality warnings.
3. Pilot Import: Enable import writes, import one test matter, and verify the work item and ODS party links in Clio Operate.
4. Idempotency Verification: Re-import the same matter to verify it detects the existing record and prevents duplicate creation.

7. Troubleshooting Matrix

For component boundaries and security specifications, see the Technical Overview. For staff import procedures, see the User Guide.