Skip to content

Connector Registration

Introduction

All connectors used in Jitterbit Harmony are required to be registered, and developers using the Jitterbit Harmony Connector SDK need to register their connectors prior to building and packaging them.

Each connector and each of its activities receives an unique ID from Jitterbit that identifies it from all other connectors and their activities.

You’ll need to obtain from Jitterbit Harmony, for each connector developed with the SDK, these values:

  • Connector ID
  • Connector key
  • Connector secret
  • Endpoint entity ID
  • Starting activity ID
  • Ending activity ID

REST API for Registering Connectors

To obtain these values, use the JitterbitConnectorManagerAPI, available as a Postman collection included in the Dropbox connector at postman/JitterbitConnectorManagerAPI.collection.json.

The collection provides these functions (“requests”):

  • Log In User
  • Register a Connector
  • List Registered Connectors
  • Delete a Register Connector
  • Validate Connector Key/Secret

Configuring the API in Postman

Before running the REST API, import the environment variables from postman/jitterbit-env-variable-postman.json into Postman and associate them with the collection.

Edit the Postman environment and enter values for the keys host (as defined by your region; see Finding My Region), email (your Jitterbit Harmony username), password (your Jitterbit Harmony password), Harmony orgID and envId, and the connector’s name, version, and description:

The name that the connector is registered under must match the value in the adapter.json file used to describe the UI. (For details on the Cloud Studio UI and the adapter.json file, see Connector Implementation and Connector SDK UI Components.)

At the start of a session of running the API functions, always first run the Log In User function to obtain an authenticationToken. This token will be retained by Postman and used for subsequent requests in the same session.

Registering a Connector

To register a connector, run these two APIs in order from with Postman:

  1. Log In User

  2. Register a Connector

The response returned by the Register a Connector API contains the key-values that are needed for the connector’s manifest to complete the registration of the connector. You should receive a response such as:

{
  "status": true,
  "operation": "Register a connector",
  "id": "3691",
  "key": "41384368...d871d2d7ec9",
  "secret": "bb574709...7f2f79f60c49",
  "endpointEntityId": "20101",
  "functionEntityStartId": "20102",
  "functionEntityEndId": "20200"
}

As can be seen from this example, a connector has been registered, has an ID of 3691, has an endpoint entity ID of 20101, and can have function activity entity IDs ranging from 20102 through 20200. A key and a secret have also been returned.

Register Connector API Manifest File Keys
key Jitterbit-Connector-Key
secret Jitterbit-Connector-Secret
endpointEntityId Jitterbit-Connector-Endpoint-EntityTypeId
functionEntityStartId Jitterbit-Activity-EntityTypeId-<first_activity>
functionEntityEndId Jitterbit-Activity-EntityTypeId-<last_activity>

The key and secret returned will become, as shown in the table above, the Jitterbit-Connector-Key and Jitterbit-Connector-Secret in the manifest for the container.

The connector has been allocated an endpoint ID and a range of activity (function) endpoint IDs, from the first to the last. In the case of the Dropbox connector, which has four activities (fetch, get, process, and put), you would assign individual IDs to each activity such that they fall inside the assigned range. A maximum of 99 activities can be assigned to an individual connector.

Connectors can be registered at any point in the development process (either while you are formulating your design or just prior to packaging). However, it is a good practice to do this as soon as possible, in case there are any problems in your registration or in obtaining the necessary keys.

Listing Registered Connectors

Use this method to see all of the connectors currently registered in an organization. It uses the host and orgId variables of the Postman environment.

From within Postman, run these two APIs in order:

  1. Log In User (required only if you have not already run it in the current session; see Registering a Connector)

  2. List Registered Connectors

    This screenshot shows the list of registered connectors returned for the current organization:

Deleting a Registered Connector

If needed, you can delete a registered connector. To delete a connector requires that you have both the organization (orgId) that it belongs to and the connector ID (connectorId). The connector ID was displayed when the connector was registered and can be found by using the List Registered Connectors method to see all of the connectors currently registered in an organization.

From within Postman, run these two APIs in order:

  1. Log In User (required only if you have not already run it in the current session; see Registering a Connector)

  2. Delete a Registered Connector

    This screenshot shows the message returned if the connector specified by the connectorId was successfully deleted:

Validating a Connector Key/Secret

You can validate the name, key, and secret of a registered connector. Enter the values into the connectorName, key, and secret Postman environment variables, and then use this API. Note that all three items are required, including the connector name, in order to validate the connector key and secret.

These values were displayed when the connector was registered and can be found by using the List Registered Connectors method to see all of the connectors currently registered in an organization.

From within Postman, run these two APIs in order:

  1. Log In User (required only if you have not already run it in the current session; see Registering a Connector)

  2. Validate Connector Key/Secret

    This screenshot shows the message returned if the connector specified by the connectorId was successfully validated (the key and secret are correct for the named connector):

Connector Manifest

As part of the Maven build, these attributes must be present as part of the MANIFEST.MF to indicate that it is a Jitterbit Harmony connector. Using the manifest from the Dropbox connector, with its activities—fetch, put, process, and get—and the values for endpointEntityId, functionEntityStartID, and functionEntityEndID as shown above, you could construct a manifest such as:

Author: <author_name>
Version: 1.0.0
Jitterbit-Connector-Key: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Jitterbit-Connector-Secret: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Jitterbit-Connector-Endpoint-Id: 20101
Jitterbit-Connector-UI: adapter.json
Jitterbit-Activity-EntityTypeId-fetch: 20102
Jitterbit-Activity-EntityTypeId-put: 20103
Jitterbit-Activity-EntityTypeId-process: 20104
Jitterbit-Activity-EntityTypeId-get: 20105
Class-Path: lib/dropbox-core-sdk-3.0.6.jar
Manifest File Key Description
Author Replace <author_name> with your name.
Version Set the appropriate semantic version identifier (for example, version 1.0.0).
Jitterbit-Connector-* See the section above on REST API for Registering Connectors for details on obtaining these attributes using a REST API.
Jitterbit-Activity-* See the section above on REST API for Registering Connectors for details on obtaining these attributes using a REST API.
Jitterbit-Connector-UI (Optional) Provides the file that contains the UI declarations for the connector. Default name is adapter.json.
Jitterbit-Connector-Factory-Class (Optional) Provides the factory class that creates an instance of JitterbitConnector. If not provided then you must use an @Connector annotation on the entry class that implements the JitterbitConnector interface or extends the abstract class BaseJitterbitConnector.
Class-Path A list of space-separated URLs of any third-party JARs that make up the connector. In the example above, it contains Dropbox’s Dropbox SDK JAR.

In this example from the previous section, the connector endpoint ID was 20101, the starting activity ID was 20102, and the ending activity ID was 20200. The fetch activity can then be assigned 20102, the put activity can be assigned 20103, the process activity can be assigned 20104, and the get activity can be assigned 20105. Additional activities can, if necessary, be registered and assigned IDs as long as they fall within the allocated range.