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.

Before building a connector JAR file, you’ll need to obtain from Jitterbit Harmony these values for each connector:

• 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 Jitterbit Connector Manager API, 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/JitterbitConnectorManagerAPIEnvVariables.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 the connector’s name, version, and description. The other environment variables (authToken, connectorID, key, and secret) will be entered by Postman as you use the APIs:

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.

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 File, Get File, Process File, and Put File), 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 File, Put File, Process File, and Get File—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

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 File activity can then be assigned 20102, the Put File activity can be assigned 20103, the Process File activity can be assigned 20104, and the Get File activity can be assigned 20105. Additional activities can, if necessary, be registered and assigned IDs as long as they fall within the allocated range.