Skip to content

On-Prem Agent Connectors

Use this guide when the target system has no internet-facing API: a SQL database on a local server, a localhost HTTP service, or other data behind a firewall. The connector still uses the SDK and CLI, but connector code runs on the customer's machine through the App Xchange Agent instead of in App Xchange cloud infrastructure.

Cloud connectors and on-prem connectors share the same project structure, data objects, data readers, and actions. The difference is where the connector executable runs and how it is deployed.

Prerequisites

  • App Xchange Agent installed on the machine that can reach the target system.
  • Connector SDK and CLI with on-prem connection support (isOnPrem on ConnectionDefinition) in SDK version 1.5.8 or later and Trimble.Xchange.Connector.CLI 1.4.14 or later.
  • The same connector development setup described in Getting Started.

When to use an on-prem connection

Mark a connection definition as on-prem when:

  • The integrator must reach a database or service on their own network.
  • The target URL is localhost or a private hostname.
  • There is no route from App Xchange cloud to the data source.

Keep the default (cloud) connection when App Xchange can call your public API directly. A single connector can include both cloud and on-prem connection definitions.

How on-prem deployment works

  1. You add a connection definition class with isOnPrem: true on the ConnectionDefinition attribute.
  2. xchange extract includes isOnPrem: true for that definition in connector metadata.
  3. On connector publish, the deployment pipeline detects an on-prem definition and uploads a connector package to the on-prem agent registry (in addition to normal cloud deployment).
  4. The agent downloads that package and runs connector code when App Xchange schedules cache writes or actions against an on-prem connection.

Non-on-prem connection definitions in the same connector continue to deploy and run in the cloud only.

Mark a connection definition as on-prem

On the connection definition class, set isOnPrem: true. Only do this for definitions that must run on the agent. Define properties, auth handlers, and clients as described in Auth Types and Creating an API Client.

On-prem connection definition 
[ConnectionDefinition(
    title: "Local Database",
    description: "Connection to a SQL database on the agent machine",
    isOnPrem: true)]
public class LocalDatabase : ICustomAuth
{
    [ConnectionProperty(title: "Connection String", description: "", isRequired: true, isSensitive: true)]
    public string ConnectionString { get; init; } = string.Empty;
}

isOnPrem defaults to false. Leave it unset for cloud connections.

A connector can define multiple connection definitions—for example, a cloud BasicAuth definition for a public API and an on-prem ICustomAuth definition for a local SQL source.

Building the connector

Follow the standard connector guides. The on-prem-specific parts are isOnPrem: true on the connection definition and where the connector runs after deploy.

Step Guide
Connection definition and auth Auth Types
API client (HTTP or non-HTTP) Creating an API Client
Data objects and data readers Reading Data
Local testing before submit Local Testing
Submit and deploy Connector Submission

For a localhost HTTP API, use a normal HTTP client and auth type with BaseUrl pointing at the local URL; set isOnPrem: true on the definition.

Example: read from a local SQL database

This pattern applies when the agent machine can open a connection to an offline SQL database (for example a customer-hosted system with no public API).

Define the on-prem connection definition using the pattern above, with the properties your integrator needs (for example a connection string).

Read data in the API client

Implement database access in your ApiClient (or a dedicated client class registered alongside it). Use the connection definition injected at runtime, not hard-coded credentials.

The SDK still expects an ITargetSystemApiClient implementation; use that class for whatever protocol or library reaches your data. You are not required to use HTTP.

Example SQL read (simplified) 
public async Task<ApiResponse<IReadOnlyList<Employee>>> GetEmployeesPage(
    int page,
    int pageSize,
    CancellationToken cancellationToken = default)
{
    await using var connection = new SqlConnection(_localDatabase.ConnectionString);
    await connection.OpenAsync(cancellationToken);

    var sql = @"
        SELECT Id, Name, Email
        FROM Employees
        ORDER BY Id
        OFFSET @offset ROWS FETCH NEXT @pageSize ROWS ONLY";

    // Execute query and map rows to your data object type.
    // Return ApiResponse with IsSuccessful set from query success.
}

Wire the client into a data reader per Reading Data.

Connections on App Xchange

Create and manage connections using the Connections help topic.

On-prem differences:

  • The agent must be installed and registered under Connectivity → On-Prem Agents before the connection can run.
  • The integrator selects the on-prem connection definition for the connector (not a cloud definition from the same connector).
  • Connection property values are used on the agent machine at runtime, not in App Xchange cloud infrastructure.

If test connection fails after deploy, verify agent services on the host. See the App Xchange Agent help topic.

Verify extraction metadata

After adding isOnPrem: true, run extract and confirm the definition in connector metadata:

xchange extract

In the extracted connector interface JSON, the on-prem definition should include "isOnPrem": true. Cloud definitions should show "isOnPrem": false or omit the flag.