Implementing Test Connection

Test Connection is a simple entry point that can be defined for a connector for use with Azure Logic Apps, Power Automate, or Power Apps. By exposing an operation for test connection, the connector can provide design-time and runtime validation of connection parameters.

Prerequisites

Adding a new test connection operation

Adding an operation for TestConnection is a very simple process. You have the option of using any existing operation as a means of testing the connection, or adding a specific operation whose job is only to test the connection parameters. The operation must be a "get" and support a call with no parameters, or with hard-coded parameters.

Adding a new operation for this purpose might look like this in the OpenAPI specification:

    "/diagnostics/testconnection": {
      "get": {
        "tags": [ "Diagnostics" ],
        "operationId": "TestMyAPIConnection",
        "consumes": [],
        "produces": [],
        "responses": {
          "200": { "description": "OK" },
          "default": { "description": "Operation Failed." }
        },
        "x-ms-visibility": "internal"
      }
    }

Important

Notice that this operation is marked as internal. If you add a new entry point for this purpose, it is highly encouraged to hide this operation from the user by marking the visibility as such.

The endpoint meant to be used as test connection must be identified by adding an extension to the API at the top-level, like so:

 "x-ms-capabilities": {
    "testConnection": {
      "operationId": "TestMyAPIConnection",
      "parameters": {}
    }
  }

The operationId specified in this attribute must exist within this same OpenAPI specification to be valid.

Re-using an existing operation for test connection

Often it is simpler and more manageable to identify an existing operation that can validate the viability of the connection without incurring much cost or latency. This can be accomplished without adding a new operation, but by simply indicating which operation to use, and which parameters to pass (if any).

The following example uses an existing "get" operation called GetTables which should succeed if the connection is valid and the parameters are correct. In order to ensure that test connection operation executes as quickly as possible, the example also adds a parameter to the call to specify that only the very first row should be returned.

 "x-ms-capabilities": {
    "testConnection": {
      "operationId": "GetTables",
      "parameters": {
        "$top": 1
      }
    }
  }

Implementing test connection

If you need to implement test connection, and no other existing operation is appropriate for this purpose, you can do so with a very simple backend call. The operation need not take any parameters or return any content. The URL path is also unimportant, and can be selected based on your preference. The only measure of success for a test connection call is simply a successful response (200, for example) from the HTTP call. Within the test connection operation, the contract simply requests that the connector validate the authentication context and the connection parameters.

This can be accomplished by simply querying for something simple on the backend, which will make use of the authentication parameters and any database or scoping that might be implied. Querying for the top row of a simple table is a good example of one test connection approach.