Skip to content

Establish Project

Establish Your Codebase

Before you can start building your Connector you should go through Getting Started and ensure you have the CLI tool installed:

dotnet tool list --global

Generate Connector Scaffolding

Create a folder for your new connector named after your connector. In this case, the connector's name will be "ExampleConnector":

mkdir connector-ExampleConnector
cd connector-ExampleConnector/

The CLI offers an easy way to generate the initial code for your connector code base with the following command:

xchange connector new --name ExampleConnector

This will create a code base for the "ExampleConnector" connector, but you should replace "ExampleConnector" with the name of your connector. If the name of your connector has spaces, you can use quotations in the name:

xchange connector new --name "Example Connector"

The created "Connector" folder and solution file will organize your work - do not change the name of these files. Before you can run any more xchange commands you must first change your directory to the Connector folder.

cd Connector

In this directory you'll also find a settings.json file. The name and description of the connector will be visible on the platform, so make sure those fields are configured before you submit. When you submit your code, the field url-part must correspond to a connector key provided by Trimble App Xchange which you may see referenced elsewhere - this value is initialized based on the connector name.

Additionally, you will see a Client and Properties folder, project, connector registration, and connector registration configuration files. These will be discussed later, except for connector registration configuration. This class provides an opportunity to create a workspace level configuration. This configuration is used to store workspace level values to be accessed at the Connector level. A common example of this would be to store a tenanting value (Company ID, Account ID, etc.) if your target system leverages this pattern on its API calls. However, the class may stay empty for reasons discussed in migrating to connections.

Example of ConnectorRegistrationConfig with filter 
public class ConnectorRegistrationConfig
{
    [JsonPropertyName("companyId")]
    [Required]
    public required string CompanyId { get; init; }
}

Once you've established your connector, you will need a module to organize endpoints, objects and associated actions of your connector. Most connectors need only one module. However, if the surface area of your API is large and is itself organized with sections or modules, matching this documentation may be helpful for the end user viewing the connector on App Xchange. Otherwise we recommend simply using the example below. The module id is used throughout connector code and needs to be consistent. The key is used on platform, any change would be a breaking change. Changing the version number later would effectively create a new module with the same name, but without breaking the old module.

To create your first module for your Connector you can run the following example command:

xchange module new --id app-1 --name App --key app --version 1
Info

xchange commands should be ran in the working directory of your Connector project or with the --connector-path option supplied.

This example will create a new module named App, and populate settings.json, which once again will be used to display the name and description to the user on the platform. You can now begin creating objects and associated actions, the meat of connector development. If you use the optional --add-health-checks the command will also create optional files designed as examples that do not need an API connection that can compile and run immediately out of the box.

Expected Results

~\Connector>xchange module new --id app-1 --name App --key app --version 1 --add-health-checks
Created file "AppV1ActionProcessorConfig.cs" at: "~\Connector\App\v1\AppV1ActionProcessorConfig.cs"
Created file "AppV1ActionProcessorServiceDefinition.cs" at: "~\Connector\App\v1\AppV1ActionProcessorServiceDefinition.cs"
Created file "AppV1CacheWriterConfig.cs" at: "~\Connector\App\v1\AppV1CacheWriterConfig.cs"
Created file "AppV1CacheWriterServiceDefinition.cs" at: "~\Connector\App\v1\AppV1CacheWriterServiceDefinition.cs"
Created file "HealthCheckConfig.cs" at: "~\Connector\App\v1\HealthCheck\HealthCheckConfig.cs"
Created file "HealthCheckDataObject.cs" at: "~\Connector\App\v1\HealthCheck\HealthCheckDataObject.cs"
Created file "HealthCheckDataReader.cs" at: "~\Connector\App\v1\HealthCheck\HealthCheckDataReader.cs"
Created file "AddHealthCheckConfig.cs" at: "~\Connector\App\v1\HealthCheck\Add\AddHealthCheckConfig.cs"
Created file "AddHealthCheckHandler.cs" at: "~\Connector\App\v1\HealthCheck\Add\AddHealthCheckHandler.cs"
Created file "AddHealthCheckAction.cs" at: "~\Connector\App\v1\HealthCheck\Add\AddHealthCheckAction.cs"
Successfully created new module '"App"' with version 1.