Test method is used for purposes of testing the connection and verifying permissions. It’s being used by the Syncari application once it is approved and a user installs it. During that process there is an authentication test step, where the test method is utilised. Bellow are UI elements that trigger the method: when setting up the authentication for the synapse and once the synapse is live.
The method receives a Connection object as an argument and is expected to return a Connection object as well. The object doesn’t need to be modified by the method, but it can be if the use case requires it (for example, creating webhooks, authentications, etc.).
The connection object is going to persist in the framework and it can be used in other methods, for example if the authentication method requires to generate an authentication token it is possible to generate it inside the test method and then use it in other methods.
Example Code
In the example below we can see how our Pipedrive Synapse utilizes the test method. It first checks if credentials are valid by making a request to the user endpoint. If the request is successful then it proceeds to check if a metaConfig object with webhookIdentifier key already exists for the setup, if not it’ll run the helper method to register a webhook. This is a best practice we recommend with systems that use webhooks so that once the webhook is set, future invocations of the test method won’t make unnecessary registrations. If the call to the user endpoint fails the method would just raise an exception and the user would be prompted with an error message.
def test(self, connection: Connection) - Connection :
# receives `Connection` object from framework
auth_data = {'api_token':connection.authConfig.accessToken}
resp = self.client.get('users', params=auth_data)
if 'success' in resp.json() and resp.json()['success']:
connection_resp = connection
connection_resp.authConfig.accessToken = connection.authConfig.accessToken
if not connection_resp.metaConfig:
connection_resp.metaConfig = dict()
connection_resp.metaConfig['dummy'] = 'dummy_metaconfig_value'
if 'webhookIdentifier' not in connection.metaConfig:
self.__register_webhook(connection)
return connection_resp
raise Exception('Failed to validate credentials for pipedrive connection')
# returns the `Connection` object after augmenting with additional info like acquired token.
Simple oAuth Example
When using SIMPLE_OAUTH authentication type, the test method can be used to generate the token for the first time. For token refreshes the refresh_token method can be added, which gets triggered by the platform automatically. You can read more on this in the authentication article.