rohan_jain

September 2017 Release Deep Dive: Test Connection Button

Blog Post created by rohan_jain Employee on Sep 6, 2017

Dell Boomi recently released a new version of Connector SDK which allows connection components to have a Test connection button to verify credentials and connectivity without having to run the process. This means Connector SDK developers can leverage this to add Test connection capabilities for their custom connectors.

 

The September 2017 release enabled Test Connection button for Amazon SNS connector, Amazon S3 connector, Amazon SQS connector, NetSuite connector, and AtomSphere API connectors.

 

What is Test Connection?

Test connection allows you to test connection credentials on connection components before you use it in a process. You do not need to save the component and execute a process to verify the credentials are correct. A "Test Connection" button is added directly to the connection configuration screen to test the connectivity with the specified credentials:

 

 

Implement Test Connection

A test connection button will be added to the connector connection component when the connector descriptor contains the <testConnection> element with a valid method attribute. The <testConnection> is an optional element and should be between the <field> (ConnectionFieldConfig) and <operation> (OperationConfig) element in the connector descriptor XML.

 

In many cases connectivity is required to browse an API for available objects and actions. For those APIs, you can use your existing connector browse methods as-is by simply modifying the descriptor--no additional code required!

 

However in cases when a connector's browsing does not actually make a connection to the endpoint (for example, if the objects are statically defined within the connector or if the connector does not perform browsing at all), you can write a custom test connection method with the logic required to perform test connection. Therefore there are three types of methods to perform test connection:

 

  1. GET_OBJECT_TYPES - Use Browser.getObjectTypes() to perform test connection.
  2. GET_OBJECT_DEFINITIONS - Use Browser.getObjectDefinitions(objectTypeId, roles) to perform test connection. 
  3. CUSTOM - Use the method ConnectionTester.testConnection() to write custom test connection code.

 

Connector browsing methods sometimes use operation type, custom operation type, object type or operation fields from the BrowseContext to perform browse operation. Test connection element can be configured with attributes such as operationType, customOperationType, objectType or nested elements of fieldValue. The attribute or field value present in descriptor will be placed in BrowseContext when performing test connection.

 

More information on the <testConnection> element and its attributes can be found in Connector descriptor.

 

Sample Test Connection Implementation 

 

Type A: GET_OBJECT_TYPES

In cases when Browser.getObjectTypes( ) method validates connection credentials, you could use the same code to perform test connection by using GET_OBJECT_TYPES method.

 

Assuming your browsing code looks like this:

 

 

In the above method we can see getObjectTypes() forms a connection to the API when the operation type is CREATE.  Therefore following test connection config in connector descriptor could be used to enable test connection functionality for this connector.

 

Type B: GET_OBJECT_TYPES

In cases when Browser.getObjectDefinitions(objectTypeId, roles) method validates connection credentials, you could use the same code to perform test connection by using GET_OBJECT_DEFINITIONS method.

 

Assuming your browsing code looks like this:

 

 

Also, the connector descriptor is configured with a QUERY operation containing a "useRestAPI" operation field like this:

 

 

There are two major configurations what the getObjectDefinitions() method needs to validate credentials in the above case:

  1. useRestAPI operation property is set to true
  2. Operation type is QUERY

 

The following test connection config in connector descriptor allows us to set these conditions and use the getObjectDefinitions method to perform test connection:

 

 

Type C: CUSTOM

When connector browsing methods such as GET_OBJECT_TYPES and GET_OBJECT_DEFINITIONS cannot be used to perform test connection a CUSTOM method should be used. This method allows developers to write code only dedicated to perform the connectivity test. This method requires the 1.2.21 or later released version of the connector-sdk.  

 

To write a custom test connection code, the connector class that extends BaseBrowser or implements Browser should also implement ConnectionTester. This will allow you to override the ConnectionTester.testConnection() method in which you can write custom test connection code. The example below shows how you can do this:

 

 

The ConnectorException thrown in the code above is what is displayed on the test connection UI when the connection fails. The method attribute value should be CUSTOM in this case. The following test connection config is descriptor enables test connection for this connector:

 

 

And that is all you need to implement test connection for your own connector. 

 

Feel free to post your views and questions on Test Connection.

Outcomes