Handling Gateway Support

Test Connection

Custom Connector support is available in both Personal and Standard modes of the on-premises data gateway. Both gateway modes support Import. Direct Query is only supported in Standard mode. OAuth for custom connectors via gateways is currently supported only for gateway admins but not other data source users.

The method for implementing TestConnection functionality is likely to change while the Power BI Custom Data Connector functionality is in preview.

To support scheduled refresh through the on-premises data gateway, your connector must implement a TestConnection handler. The function is called when the user is configuring credentials for your source, and used to ensure they are valid. The TestConnection handler is set in the Data Source Kind record, and has the following signature:

(dataSourcePath) as list => ...

Where dataSourcePath is the Data Source Path value for your function, and the return value is a list composed of:

• The name of the function to call (this function must be marked as #shared, and is usually your primary data source function).
• One or more arguments to pass to your function.

If the invocation of the function results in an error, TestConnection is considered to have failed, and the credential won't be persisted.

Note

As stated above, the function name provided by TestConnection must be a shared member.

Example: Connector with no required arguments

The code snippet below implements TestConnection for a data source with no required parameters (such as the one found in the TripPin tutorial). Connectors with no required parameters (referred to as 'Singletons') do not need any user provided input to test a connection (other than credentials). In this case, the dataSourcePath value would be equal to the name of the Data Source Kind, and can be ignored. The TripPin.Contents function is invoked with no additional parameters.

TripPin = [
    TestConnection = (dataSourcePath) => { "TripPin.Contents" },
    Authentication = [
        Anonymous = []
    ],
    Label = "TripPin"
];

Example: Connector with a URL parameter

If your data source function has a single required parameter of the type Uri.Type, its dataSourcePath will be equal to the URL provided by the user. The snippet below shows the TestConnection implementation from the Github Sample.

GithubSample = [
    TestConnection = (dataSourcePath) => {"GithubSample.Contents", dataSourcePath},
    Authentication = [
        OAuth = [
            StartLogin = StartLogin,
            FinishLogin = FinishLogin,
            Label = Extension.LoadString("AuthenticationLabel")
        ]
    ]
];

Example: Connector with required parameters

If your data source function has multiple parameters, or a single non-URL parameter, then the dataSourcePath value will be a JSON string containing the parameters. The snippet below comes from the DirectQueryForSQL sample.

DirectSQL = [
    TestConnection = (dataSourcePath) =>
        let
            json = Json.Document(dataSourcePath),
            server = json[server],
            database = json[database]
        in
            { "DirectSQL.Database", server, database },
    Authentication = [
        Windows = [],
        UsernamePassword = []
    ],
    Label = "Direct Query for SQL"
];