Skip to Content

Harmony Connector SDK

Overview

Connectors allow end users in Jitterbit to connect to and interact with endpoints, and a custom connector built with the Harmony Connector SDK extends the capabilities of the endpoints a Harmony Cloud Studio project can connect to and interact with. Connectors built with the Connector SDK are not limited to HTTP/REST APIs (as is the Connector Builder) but can use any API provided by an endpoint.

Creating a connector with the Connector SDK requires a developer to be familiar with standard Java development practices and tools, such as Maven, Docker, Postman, and Git.

This documentation is the starting point in the development of a connector, and assumes that you are already familiar with Jitterbit, Harmony, Harmony Cloud Studio, Harmony Private Agents, and Java development. Please see the related parts of our documentation at Jitterbit’s Success Central if you are not familiar with Jitterbit.

The current version of the Connector SDK is version 1.0.0.

Connector SDK Concepts

Connectors built with the Connector SDK show up in Cloud Studio just as any other connector. Once a connection is configured, they provide specific activities—as determined by the connector developer—that can be used as sources or targets in an operation. They run on Private Agents and work with Cloud Studio.

The Harmony Dropbox Connector is a custom connector developed using the Connector SDK, shown in Cloud Studio with its activities: Process File, Fetch File, Get File, and Put File:

Dropbox Activities

This Harmony connector interacts with Dropbox, providing both reading and writing of files from and to Dropbox. The example is available as source code through the GitHub repository jitterbit/dropbox-connector and is used as the basis for the Dropbox Connector Tutorial.

Warning

The example Dropbox connector is not for production use. It is intended as a starting point for developing Harmony connectors built with the Connector SDK.

From a development perspective, these are the main elements of a Harmony connector:

  • Connector: A collection of activities that interacts with a system. A connector needs to implement the JitterbitConnector interface.
  • Activity: Represents the smallest unit of execution within a Jitterbit operation. It matches to a node within a Cloud Studio operation. Every activity needs to implement a JitterbitActivity interface with these two parts:
    • Configuration: Performed by an end user using the Cloud Studio UI.
    • Execution: Executes an activity according to the user configuration.
  • Endpoint: Represents a connection to a system, with endpoint information provided by an end user configuring a connection using the Cloud Studio UI.
  • Payload: Represents a request/response (input/output) of an activity during execution; maps to a Payload interface.
  • Request/Response: The request and response of an activity developed with the Connector SDK will always be in XML format.
  • adapter.json: A JSON file containing the declarative UI associated with an endpoint connection and the activities that make up a connector. As the developer, you set the parameters that need to be configured and the types associated with each parameter. For more complex interfaces, there are components available as part of the Cloud Studio UI.
  • XML Schema: An XML XSD file containing the declaration of the data structures used for the request or response of each activity. These XSD files are the contract between Harmony and the connector, and determine how data is mapped between Harmony and the connector.

Note

These terms are specific to custom connectors developed using the Connector SDK and differ slightly from those used in the Cloud Studio UI.

Connector Implementation

The Connector SDK allows developers to create custom connectors for end users to configure endpoints, whose activities can be used as sources or targets within the Cloud Studio UI. There are a number of interfaces that the developer must complete when writing a connector; they are described with related code samples in Connector Implementation.

Connector Registration

All connectors to be used in Harmony are required to be registered, and developers need to register their connectors before building and packaging them. Detailed instructions for registering your connector and setting appropriate values in the manifest file are described in Connector Registration.

Connector UI in Cloud Studio

The UI of the connector as displayed in Cloud Studio is defined by a JSON file (by default called adapter.json) included in the JAR file that packages the connector.

Available UI elements—including icons and components, with code samples to create them—are described in Connector SDK UI Components.

Connector Synchronization

Public connectors are connectors built and maintained by Jitterbit. They are available to all users, on all agents. The JAR files for these public connectors are automatically installed and updated as required on agents, for both the public Cloud Agent Groups and for Private Agents (as of Harmony version 10.1).

The public connector JAR file will be downloaded to an agent as needed once a connector has been configured and either the configuration’s Test button clicked or an activity added and configured.

Private connectors are connectors built by third-party developers (such as yourself) and are installed on Private Agents directly by copying the JAR file to the Private Agent’s connectors directory.

APIs are available for login, registering, listing, and deleting connectors. See REST APIs for details of the APIs and Registration for examples of using the APIs with Postman.