Skip to content

Connector Criteria

App Xchange code approval focuses on safety and avoiding security and performance risks, not optimization or design. It is typically the connector builder's responsibility to do quality assurance on their connector and confirm that the connector design supports their business requirements, including taking any pre-development considerations into account..

Connectors that do not meet minimum criteria will not be deployed to the platform, and connectors that do not follow best practices will receive feedback and require specific reasoning before deployment.

How to use these criteria

  • Connectors that do not meet the "mandatory" criteria will not be released or may be withdrawn from production
  • Connectors that do not meet the "prefer" criteria will receive feedback and guidance before approval
    • We will typically ask for an explanation if not provided if these criteria are not followed

Criteria

MANDATORY

PREFER

  • Use PascalCase for names and follow naming conventions
  • Limit dependencies on additional third party libraries
  • Favor .NET and Xchange libraries over unsupported third-party libraries for equivalent function, e.g. prefer System.Text.Json over NewtonSoft.Json
  • Use cancellation token support when applicable within action handlers and data readers
  • Avoid mixing JSON serialization libraries
  • Use public NuGet repositories for additional dependencies
  • Use StandardActionFailure types for failed action outcomes
  • Handle and inform service runners of exception cases
  • Limit source files to those needed for operating the connector
  • Aggregate related errors when appropriate - e.g. based on a previous response, handle recovery, failure and next steps
  • Use base Config types when extending service configurations
  • Use configurations from the host context rather than custom configuration strategies
  • Represent a reasonably stable API, i.e. version or modules are not expected to change frequently
  • Compile without warnings
  • Descriptions are provided for all data objects and actions

CONSIDER USING

  • Asynchronous iterators for data reader implementations
  • Supported API clients, middleware, and delegating handlers
  • Action and Data Object names which follow connecting API resource naming conventions
  • Validation on Action inputs
  • Data object definitions which are generally less restrictive than action input validations

Examples and additional guidance

The examples and guidance provided assume the connector code uses organization concepts encouraged by the SDK tooling, i.e. CLI code generation commands.

Limit network calls in a connector to the connecting system

  • Most network calls should be limited to provided ApiClient classes to leverage middleware, i.e. connections, authentication, retry policies, etc.
  • Do not use HttpClient classes, hardcoded URLs, or other libraries that make network requests invoked within data readers or action handlers.
  • Verify that ApiClient classes use injected HttpClient classes and connection details from configurations
// Connector.Client.ApiClient.cs - Good usage of connection details from configuration
...
    public ApiClient(HttpClient httpClient, ConnectorRegistrationConfig registrationConfig)
    {
        _httpClient = httpClient;
        _httpClient.BaseAddress = new System.Uri(registrationConfig.ApiDetails.BaseUrl);
    }
...

Not use conditional compilation preprocessor directives

Conditional preprocessor directives are often used for environment or configuration conditions. We support configuration from the App Xchange app and local testing cases.

Not include credentials or sensitive information within connector code

Connections, Connector Registrations, any API client pipeline code, should not have credentials in the connector code. Sensitive credentials should be marked as such and loaded from configuration or Connections. No business logic or proprietary information should be included.

Not connect production data sources to the Xchange test environment

To limit PII risk, production data sources should not connect to the Xchange test environment. Review connections usage for the connector code to ensure this case does not happen.

Not introduce breaking schema changes for existing connectors without a migration or versioning plan for dependent integrations

Connector code should be reviewed for breaking changes if updates are made to an existing connector that has in-use integrations, i.e. the connector is not longer under development and is used to transfer customer data.

Breaking changes are changes to connector code that cause downstream issues to caching data from the connector or detecting changes to cached data.

The key areas to examine breaking changes are:

  • Changes that impact the data object and action path as they could impact caching and change detection
    • Connector key, module URL part, data object URL part, data object keys
  • Changes to schema generation points that introduce a breaking change, e.g. removal of a non-nullable property, more restrictive type-change
    • Data object annotations, data object key names, data object key changes, action input/output/error objects
  • Changes to actions or data objects that impact cached objects
    • Default values or nullable values for properties used by data objects or actions

Limit dependencies on additional third party libraries

  • The more external tools are brought in for validation, mapping, or serialization, the more moving parts exist that may be out of date or break later
  • Some external libraries have performance considerations

Compile without warnings

  • the most common example is missing the nullable type ? which is needed in addition to the Json attribute [nullable(true)] as applicable on data object properties. See here for more: Object Schema Nullable Attribute