Implementing TestConnection

You can use the Connector SDK to implement a Test Connection, allowing users to verify their connection settings prior to using the connection in a process. The Connector SDK provides these three methods to implement the Test Connection:

• GET_OBJECT_TYPES
• GET_OBJECT_DEFINITIONS
• CUSTOM

Test Connection using the GET_OBJECT_TYPES method

When the getObjectTypes( ) method forms a connection with the API, you can use the same code to implement a Test Connection using the GET_OBJECT_TYPES method. In this example, your browsing code may look like the following:

Code sample

// The provided Java code snippet defines a class `ExampleBrowser` that extends `BaseBrowser`. This
// class is used to implement the `getObjectTypes()` method, which is part of the Connector SDK for
// implementing Test Connection functionality.
public class ExampleBrowser extends BaseBrowser
{
    public ExampleBrowser(ExampleConnection conn)
    {
        super(conn};
    }

    @Override
    public ObjectTypes getObjectTypes()
    {
        List<String> returnedTypeNames;

        ObjectTypes types = new ObjectTypes();

        switch (getContext().getOperationType()) {
            case QUERY:
            //...Not a good option for test connection because no connection is formed ...//
            types.add(new ObjectType().withId("account"));
            types.add(new ObjectType().withID("contact"));
            return types;
            break;

            case CREATE:
            //...Good option for test connection because a connection is formed ...//

            String requestUrl = "http://www.example.com/service/type:;
            //....Make GET request to requestUrl ...//
            //...parse results into list ...//
            List<String> returnedTypeNames = ...;

            // process returned list of type names
            for(String typeName : returnedTypeNames) {
                types.add(new ObjectType().withId(typeName);
            }
            return types;
            break;
        }
    }

}

The following TestConnectionConfig can be used in the descriptor to enable Test Connection functionality for the connector:

<testConnection method="GET_OBJECT_TYPES" operationType="CREATE" />

Test Connection using the GET_OBJECT_DEFINITIONS method

When the getObjectDefinitions( ) method forms a connection with the API, you can use the same code to implement a Test Connection using the GET_OBJECT_DEFINITIONS method. In this example, your browsing code may look like the following:

Code sample

// The provided Java code snippet defines a class ExampleBrowser that extends BaseBrowser and // implements the getObjectDefinitions method. This method retrieves object definitions // based on the object type ID and roles provided.

public class ExampleBrowser extends BaseBrowser
{
    public ExampleBrowser(ExampleConnection conn)
    {
       super(conn);
    }

    @Override
    public ObjectTypes getObjectDefinitions(String objectTypeId, Collection<ObjectDefinitionRole> roles)
    {
       if(getContext().getOperationProperties().getProperty("useRestAPI")) {

          switch (getContext().getOperationType()) {
            case QUERY:
                String requestUrl = "http://www.example.com/service/type/" + objectTypeId + "/def";
                // ... Make GET request to requestUrl ...
                // ... parse returned stream into DOM ...
                Document schemaDoc = ...;
            
                //create new definition
                ObjectDefinition def = new ObjectDefinition();
                def.setSchema(schemaDoc.getDocumentElement());
                ObjectDefinitions defs = new ObjectDefinitions();
                defs.getDefinitions().add(def);
                return defs;
                break

            default
                throw new ConnectorException("Operation unsupported");
            }
            
        }
        else {
            throw new ConnectorException("Select the Use Rest API check box to perform this operation")}
        }
    }

}

Continuing with this example, the connector descriptor for this connector has an OperationConfig for the QUERY operation that contains the following field:

<operation types="QUERY">
     <field id="useRestAPI" label="Use Rest API" type="boolean">
          <helpText>If selected, use the REST API to form connections</helpText>
     </field>
</operation>

The getObjectDefinitions( ) method needs the following two configurations to form a connection successfully:

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

You can use the following TestConnectionConfig in the descriptor to set these conditions and use the getObjectDefinitions method to perform a Test Connection:

<testConnection method="GET_OBJECT_DEFINITIONS" operationType="QUERY" objectType="account">
     <fieldValue id="useRestAPI">true</fieldValue>
</testConnection>

Test Connection using the CUSTOM method

When connector browsing methods such as GET_OBJECT_TYPES and GET_OBJECT_DEFINITIONS cannot be used to implement Test Connection, use a CUSTOM method. You can use this method to write dedicated Test Connection-specific code in the connector.

To write custom Test Connection code, the connector class that BaseBrowser should also implement is ConnectionTester. This allows you to overwrite the testConnection() method and write your custom code. The following code example illustrates how you can do this:

Code sample

// The Java code snippet you provided defines a class ExampleBrowser that extends BaseBrowser // and implements the ConnectionTester interface. This class handles the Test Connection // functionality for a connector.

public class ExampleBrowser extends BaseBrowser implements ConnectionTester
{
     public ExampleBrowser(ExampleConnection conn)
     {
         super(conn);
     }

     @Override
     public void testConnection() {
         try {
             ///.. Code here to form a connection ..///
         }
         catch (Exception e) {
             throw new ConnectorException("Could not establish a connection", e);
         }
     }
}

The ConnectorException thrown in the previous code displays during Test Connection when the connection fails.

The following TestConnectionConfig in the descriptor enables Test Connection for the connector. In this example, the method attribute value should be CUSTOM.

<testConnection method="CUSTOM" />