Skip to content

Connector Submission

How to submit a Connector to Xchange

When your Connector is in a state that is ready to be used by App Xchange you can submit the Connector to be reviewed. If approved the Connector will be available on the platform. The same process is done for when updates are made to the Connector.

First run xchange extract to check for common errors, such as build failures, too long variable names, etc. This command will be run again automatically when you submit, but it is best to address anything proactively. Double check that you have a Connector.sln file in the same directory as your Connector folder, and you do not have non-connector code in your directories. If applicable, confirm that there are not any currently open code submissions with xchange code list, otherwise you will get a 409 error. Lastly, make sure key in settings.json matches the connector key provided by App Xchange for your connector. More info can be found here connector project structure.

urlPart is replaced by key in settings.json for CLI 1.3.9 and SDK 1.3.5
Running the App Xchange CLI in headless environments

The code commands also support a --api-key option. This option can be used when wanting to run these commands in a headless environment such as your CI/CD. In order to get a token please contact Product Enablement at xchange_build@trimble.com. If the --api-key option is used then the --submitter option is required.

Create Submission

While in the root of the Connector project the following command can be ran to create a zip archive of your Connector code and submit it to Xchange for review. If an archive already exists, use --override-archive to replace it with your current code state, and remember you can see all command details in cli usage.

Submitter is defaulted by User Login

The code submit command will use the email of the logged-in user as the default for the --submitter field. The --submitter option is only required if the --api-key option is used. The CLI will provide guidance on the appropriate usage.

xchange code submit

There can only be one open submission per connector at a time

Before the archive is created it will first attempt a build of your code base, if successful all the archive will contain:

  • The CS proj file
  • settings.json
  • All csharp files

Once submitted the result of the command will return a correlation ID. This ID can be used to check the status or manually close the submission if desired.

All submitters will receive an email once code submission is reviewed.

Dry Run

There may be times when you would first like to inspect the archive (code.zip) before submitting it to Xchange. This can be done with the --dry-run option.

Early Feedback and Drafting

To get early feedback on a new connector build, which is encouraged, submit the code as a draft to let us know not to deploy the connector yet but to provide feedback or guidance if needed.

xchange code submit --draft

Lookup All Submissions

There are cases where you don't know your correlation ID or you want to audit your history of submissions. This can be done by using the list command. For example if you want to see all of the submissions for the connector:

xchange code list

Filters can also be added such as only listing submissions by a particular submitter

xchange code list --submitter developer@example.com --api-key *api_key*

Check Submission Status

The get command can be ran if you know the correlation ID of a submission and you want to look it up

xchange code get --correlation-id *correlation_id*

The status command can also be ran to only return back the status, this may be useful for an automation pipeline.

xchange code status --correlation-id *correlation_id*

Available Submission Statuses

Below is a list of statuses and a brief description

Processing - The submission is going through validation and setup before being reviewed

Pending Approval - The submission's code is awaiting human approval

Approved - The submission's code is approved and building of the Connector will begin

Building - This stage is the building the Connector's image and meta data to later be used to publish

Pending Publish - Awaiting for approval to publish the Connect onto Xchange platform

Publishing - The Connector's meta data and image is being updated on the platform

Published - The changes supplied in the submission are available to be used on the platform

Rejected - The submission is denied. A submission can be denied due to code analysis gates failing or issues found during approval phase.

Closed - Submission has been manually closed via xchange code close

Close Submission

The close command can be used to manually close out a submission. This could be desired due to finding out post submission that there is something more that needs to be done with the Connector.

xchange code close --correlation-id *correlation_id*

Once closed you are free to post another submission with your new changes.