Waiting for engine...
Skip to main content

Best practices for connector development

To help you successfully build a connector using the Connector SDK, we recommend that you follow this set of design considerations and best practices.

API service endpoint​

  • Do not change the behavior of any current connector in regards to operation status. For example, a document previously marked as an application error is now marked as a failure.
  • Honor the intent of the underlying system/API.
  • Do not arbitrarily suppress failed operations and treat them as a success.
  • Do not manufacture artificial errors for a successful operation.

Browser implementation​

  • The Browser should not modify data in the service.
  • The Browser does not need to be thread-safe.
  • Logging should have a static instance of java.util.logging.Logger that uses the current package name.
    • runtimes and runtime cloud clusters — Log messages are located in <atom_installation_directory>/logs/yyyy_mm-dd.container.log.
    • Clouds — Log messages are located in <my-cloud>/accounts/<my-account>/execution/history/yyyy.mm.dd/browser-xxx/runner.log.
  • Use a proper structure (for example, JSON) if you store ObjectDefinition cookies. Unstructured cookies are harder to manipulate than structured cookies and they make it harder to preserve backwards compatibility.
  • Objects represent the actual resources in the application. You can import these objects through the import configuration wizard. Boomi recommends that these Object names are nouns, for example, File, Records, etc. If you know the list of objects and need not discover through service lookups, you can provide them as browseable objects through objectTypes element in the descriptor file.

Configuring connector-descriptor.xml file​

Example: Configuring objectTypes in the descriptor file
<?xml version="1.0" encoding="UTF-8"?>
<GenericConnectorDescriptor requireConnectionForBrowse="true">
    <operation types="EXECUTE" supportsBrowse="true" customTypeId="POST" customTypeLabel="Post">
        <browseConfiguration>
            <objectTypes>
                <object id="/pet" label="addPet"/>
            </objectTypes>
        </browseConfiguration>
    </operation>
    <operation types="EXECUTE" supportsBrowse="true" customTypeId="GET" customTypeLabel="Get">
        <browseConfiguration>
            <objectTypes>
                <object id="/pet/findByStatus" label="findByStatus"/>
                <object id="/store/inventory" label="getInventory"/>
            </objectTypes>
        </browseConfiguration>
    </operation>
</GenericConnectorDescriptor>
note

All operations support field selection so users can determine the fields that are returned in the response. Refer to the Query operation field selection, filtering, and sorting topic to learn how to add field selection annotation to your schemas.

Caching​

  • Be careful with caches. A common pitfall when working with connector caches is to forget that it is accessible to multiple threads. Make sure operations on these objects are thread-safe.
  • The following class, and its subclass, must be thread-safe: Connector class
  • The following classes, and their subclasses, do not need to be thread-safe:

Connector implementation​

  • You can use the com.boomi.connector.api.Connector class to cache non-user-specific, expensive resources that are needed for connector operation.
  • The connector implementation must have a no-argument constructor so it can be instantiated by the Runtime. The Runtime will only instantiate a connector class once, so the implementation must be both thread and account safe. This means that your connector implementation should not cache any account-specific resources because multiple accounts can interact with the same connector instance.
  • Assume that the connector class will be used in a multi-user environment. Use the ConnectorContext method (see the Javadoc) to get a handle to a user-specific cache that lives for the lifetime of the connector. Use this cache to cache any resources that contain user-specific information such as login credentials. Resources in this cache must be thread-safe because this cache shares the lifetime of the connector instance.
  • Log using a static instance of java.util.logging.Logger constructed with the current package name. Messages from this logger are in <atom_installation_directory>/logs/yyyy_mm-dd.container.log.

Connector actions​

Connector actions represent the base operations executed on the resources located in the application endpoint. Boomi recommends that these Actions names are verbs. Examples of Action names are Create, Retrieve, Update, etc.

note

Ensure that you mention all connector actions in title case, except for the LISTEN action, which must be in uppercase.

Operation implementation​

  • All TrackedData must be passed to the OperationResponse (refer to the Javadoc topic) except in the case of total operation execution failure. See Operation.execute() (see the Javadoc) for more details on data tracking.

  • Services are not required to support all operation types.

  • Operations do not need to be thread-safe.

  • Operation implementations must be single-threaded and they should not attempt to do work on other threads.

  • Process execution logging should use the logger returned from OperationResponse.getLogger() (refer to the Javadoc topic) for general execution events. Do not log all requests and responses for the operation because this data is available to the user. Instead, log important information that the user does not have access to. Excessive logging takes up container resources. For information about logging, see the topic Implementing the Connector.

  • An Operation can write the connection information that was used at the time of the connector call to the process execution log. This write is accomplished by overriding the generateConnectionInfo() method in the connector’s subclass of BaseConnection and returning a string containing the information to be logged, for example the result of concatenating the username, @, and the endpoint URL.

Operation status​

When adding a result to the operation response, you must assign an operation status.

  • SUCCESS — This status indicates a successful operation execution for a document and is assigned for the following common use cases:

    • Any successful operation.
    • A GET operation that fails because the ID does not exist.
    note

    This may not honor the intent of the underlying system, but should be strictly followed for consistency within the platform.

    • A DELETE operation where the ID does not exist, but the underlying system does not return an error.

  • FAILURE — This status indicates a document-related failure which is unknown or some indication of a communication failure with the underlying service. For example, an authentication failure or a network failure. Also use this when your connector cannot communicate with the underlying service.

  • APPLICATION_ERROR — This status indicates a document-related failure where communication with the service was successful, but the document cannot be processed for some reason. For example, the document is in the incorrect format or is missing required information. This status is assigned for the following common use cases:

    • The system returns an error.

    • The system does not return a response but one is expected/required.

    • The system returns a response but it is not in the expected format and cannot be processed.

    • The input document is formatted incorrectly or is missing required information.

      note

      This assumes that up-front validation of the document was required, includes Query filters, and when a payload is not required if no call is made to the underlying system.

    • A DELETE operation where the ID does not exist and the underlying system returns an error.

Partial results​

  • Always finish partial results. If an error occurs, add it as a partial result and then finish the partial result.
  • The payload for the additional partial result should contain or match the error response from the external system (if there was a response).
  • The status for additional partial results should ideally be APPLICATION_ERROR. This allows process designers to access the partial results. A FAILURE will not allow this.
  • The status code for the error result should be different than the successful results.
  • Always finish partial results, or use addResult to add the final document which implicitly finishes the partial result.

Payloads​

  • Include consistent, structured documents for payloads. Payloads for successful operations should match the response profile.
  • Include consistent, structured documents for error payloads. Error profiles are not currently supported, but may be added in the future. Error payloads should be consistent for an object and operation (same as Request/Response profiles) to allow the use of a profile in the future.
  • Do not echo unaltered input documents as a payload.
  • Do not use a simple string message as a payload. Consider using the status message first. If the status message cannot be used, create a structured response (JSON/XML) containing the message.

Resources​

  • Connectors are expected to be "good citizens" of the JVM in which they are executed. This is particularly important in multi-tenant environments. In general, any resource that is opened must be released/closed correctly. To learn more about resource management, see the topic Resource management for data streams.
  • Try to stay away from in memory hogging resources if possible such as large strings, large objects, large list of values, and byte arrays. To help, use a streaming parser to get the information that is needed.

Results​

  • Add a result to the operation response for every document passed into a connector operation. If not, the result is an "input lost" error.
  • Do not add multiple results for the same document. If you do, the result is an "input already marked as finished" error.
  • If a document errors, do not throw an exception back to the container because an exception will fail the rest of the documents before they are processed. Instead, add a failure result for the document that caused the error. The ideal situation for throwing an exception is when the connector has connection and/or server issues.
  • Do not manufacture artificial errors for a successful operation.

Security Manager​

Status codes and status messages​

  • Include a status code and status message when assigning a status. These will be available as document metadata. Ideally, the values come directly from the underlying system. Status codes are often used to differentiate between successful and error document.
  • If the status message cannot be used, create a structured response (JSON/XML) that contains the message.
On this Page