Skip to end of metadata
Go to start of metadata

Introduction

This page describes how to create and configure a new connector or edit an existing connector using Connector Builder.

Creating a New Connector

When you access the Connector Builder index, if no custom-built Connector Builder connectors yet exist in the selected organization or you do not have access to them, this screen will be blank. Click New Connector to get started:

Upon clicking New Connector, the connector creation screen opens. There are four configuration steps, each covered in the next sections:

To demonstrate the creation of a connector, these steps show how to configure a custom connector using Atlassian Jira.

Step 1 – Basic Settings

  • Upload Image: Use the link to Browse Local Files to select an SVG file to be used as the thumbnail image on the connector. The image should be no more than 120 KB in size. To replace an image that has already been selected, click Browse Local Files again to select a different file.
  • Remove Image: To clear an image that has been selected, click the Remove Image link. This will revert the image to the default Connector Builder image.
  • Connector Name: Enter a name for the connector that will be used for registering the connector with Jitterbit Harmony. The connector name will also be shown to end users as a tooltip when they hover over the connector in the design component palette.

    Only letters, numbers, or spaces are allowed (no special characters). Some names may be reserved that are already in use in other areas of the product, in which case a message will indicate that the name is already in use.

  • Display Name: Enter a name for the connector that will be the primary connector name seen by end users.
  • Version #: Enter a version number to use for identifying this connector. Only letters and numbers are allowed (no special characters or spaces).
  • Description: Enter a description of the connector. This description will appear in the Connector Builder index and may be useful to help organization administrators understand the connector. The description will not be displayed to end users.
  • Next: Click to temporarily store the configuration for this step and continue to the next step.
  • Save Changes: Click this button to save the configuration for this step and jump to Step 4 – Summary and Confirmation.
  • Delete: After opening an existing connector to edit, click Delete to permanently delete the connector from the organization and close the configuration. A message will ask you to confirm you want to delete the connector.

    NOTE: Connectors that are currently in use cannot be deleted. A connector is considered to be in use if a connection has been configured in a project, regardless of whether any activities are configured. To delete the connector, first delete the connection (see Component Dependencies, Deletion, and Removal).
  • Discard Changes: After making changes, click Discard Changes to close the configuration without saving changes made to any step. A message will ask you to confirm that you want to discard changes.

Step 2 – Authentication

  • Authentication Type: Use the dropdown to select either Anonymous or Basic authentication. Other authentication types are not currently supported.
    • Anonymous: Select this type if no HTTP authentication is required. This is also known as authenticating anonymously, with no username or password.
    • Basic: Select this type to use basic HTTP authentication without SSL encryption. Note that if this option is used, the provided password will be sent in clear text.
  • Authentication Test URL: When Basic is selected, enter a URL that you want to be tested against with an end user's credentials when they are configuring this connector. This is for purposes of validation to ensure that a connection can be made using the configured type of authentication with the end user's credentials. This field is not present when Anonymous is selected.

    • Hidden: If you do not want end users to see the Authentication Test URL field when configuring this connector, select this checkbox.
    • Lock: Applicable only when a field is not hidden, the lock icon is an indication of whether the field will be read-only or editable by end users. This is provided for informational purposes only; when creating a connector, you are not able to toggle this.
      • Locked: A closed lock icon  indicates the field is read-only for end users. 
      • Unlocked: An open lock icon  indicates the field is available for end users to edit.
  • Authentication Test Method: When Basic is selected, use the dropdown to select the method type to use with the Authentication Test URL entered above, selecting from GET, PUT, or POST. This field is not present when Anonymous is selected.

    TIP: To choose a URL and method for testing authentication, we recommend using a simple GET request. Check the API documentation for your endpoint to construct a URL for your endpoint to test against.
  • Credentials: When Basic is selected, this table shows information about the fields that the end user will use to provide their credentials:
    • Field Name: The name of the field in Connector Builder. This will not be seen by end users and cannot be edited.
    • Display Name: This name will be seen by the end user configuring the connection. By default, this is the same as the Field Name. You can rename this field using the actions available in the last column. For example, you may wish to rename "Username" to "Email Address" or rename "Password" to "API Token," depending on the specific requirements of the endpoint.
    • Actions: In the column with the actions menu icon , hover over the column cell and click the edit icon  to make changes to the row. When finished, click the Save button that appears within this column.
  • Next: Click to temporarily store the configuration for this step and continue to the next step. 
  • Save Changes: Click this button to save the configuration for this step and jump to Step 4 – Summary and Confirmation.
  • Delete: Available only after opening an existing connector to edit, click Delete to permanently delete the connector from the organization and close the configuration. A message will ask you to confirm you want to delete the connector.

    NOTE: Connectors that are currently in use cannot be deleted. A connector is considered to be in use if a connection has been configured in a project, regardless of whether any activities are configured. To delete the connector, first delete the connection (see Component Dependencies, Deletion, and Removal).
  • Discard Changes: After making changes, click Discard Changes to close the configuration without saving changes made to any step. A message will ask you to confirm that you want to discard changes.

Step 3 – Connector Activities

  • Base URL: Enter a base URL that you want to be used for all activities configured by the end user. Do not include any query parameters or paths unless they will be used for all activities (An end user will be able to specify unique paths and parameters during activity configuration.).

    TIP: If a version is included in the endpoint's URL, you may want to include it here so that if it is updated, you can change it here for all activities to inherit the new version path. (Note that you should validate paths will be valid with a new version.)

    • Hidden: If you do not want end users to see the Base URL field when configuring this connector, select this checkbox.
    • Lock: Applicable only when a field is not hidden, the lock icon is an indication of whether the field will be read-only or editable by end users. This is provided for informational purposes only; when creating a connector, you are not able to toggle this.
      • Locked: A closed lock icon  indicates the field is read-only for end users. 
      • Unlocked: An open lock icon  indicates the field is available for end users to edit.
  • Global Request Headers: To add request headers that apply across all activities, use the Add link  to insert a new blank row in the table below, then fill out the fields:

    • Name and Value: Enter a header name and corresponding value to use across all activities.

      TIP: Request headers to enter can be found within the endpoint's API documentation or by testing with a third-party tool such as Postman or SoapUI.

    • Actions: In the column with the actions menu icon , click the Save button to save the row.

      To delete or edit a header row that has been saved, hover over the column cell and click the edit icon  or delete icon , respectively, to make changes or remove the header row.

  • Activities: To add activities that will become available for an end user to configure, use the Add link  to insert a new activity. Upon clicking this link, a new screen will open for you to enter information about the activity:

    • Activity Name: Enter a name for the activity. This will be seen only by those with access to connector creation and will not be seen by end users.

    • Display Name: Enter a name for the activity to be seen by end users who will be using the connector.

    • Description: Enter a description of this activity. This will be seen only by those with access to connector creation and will not be seen by end users.

      TIP: It can be a good idea to use the same name and description that is used in the endpoint's API documentation to help others with access to connector creation in understanding exactly what the activity is for.
    • Method: Use the dropdown to select the appropriate method, selecting from GET, PUT, POST, DELETE, PATCH, or MERGE. Custom methods are not supported for connector creation Connector Builder, but can be configured using a generic HTTP endpoint instead.

    • Path: Enter a path that should be appended to the Base URL supplied in the previous step. Path parameters that you want the end user to configure can be specified within curly brackets. For example, /users/{firstname}/{lastname} defines two path parameters, firstName and lastName. Path parameters entered in this fashion will automatically appear as rows in the Path Parameters field below.

    • Path Parameters: This field displays a summary table of path parameters entered in the Path as described above, with these columns:

      • Name: The name of the path parameter entered above is displayed. To edit the path name, edit the Path field above.
      • Display Name: This name will be seen by the end user configuring the activity. By default, this field is the same as the Name field. You can rename this field using the actions available in the last column.
      • Type: By default, the type is string. You can make this field editable using the actions available in the last column. These data types are available in the dropdown: string, integer, long, date, float, double, boolean.
      • Actions: In the column with the actions menu icon , to delete or edit a parameter row, hover over the column cell and click the edit icon  or delete icon , respectively, to make changes or remove the parameter row. If the row is currently editable, click the Save button to save the row.
    • Query String Parameters: To add query string parameters for the activity, use the Add link  to insert a new blank row in the table below, then fill out the fields:

      • Name: Enter the name of the query string parameter to use.
      • Display Name: Enter the name you want to display in the connector for the query string parameter. This name will be seen by the end user configuring the activity.
      • Type: Use the dropdown to select from these data types: stringintegerlongdatefloatdoubleboolean.
      • Required: Select the checkbox to make the query string parameter required to be entered by the end user configuring the activity.
      • Default: If applicable, enter a default value for the query string parameter that will be provided for the end user configuring the activity.
      • Actions: In the column with the actions menu icon , click the Save button to save the row. 

        To delete or edit a query string parameter row that has been saved, hover over the column cell and click the edit icon  or delete icon , respectively, to make changes or remove the query string parameter row.

    • Request Headers: To add request headers for the activity, use the Add link  to insert a new blank row in the table below, then fill out the fields:

      • Name: Enter the name of the request header to use.
      • Display Name: Enter the name you want to display in the connector for the request header. This name will be seen by the end user configuring the activity.
      • Type: Use the dropdown to select from these data types: stringintegerlongdatefloatdoubleboolean.
      • Required: Select the checkbox to make the request header required to be entered by the end user configuring the activity.
      • Default: If applicable, enter a default value for the request header that will be provided for the end user configuring the activity.
      • Actions: In the column with the actions menu icon , click the Save button to save the row. 

        To delete or edit a request header row that has been saved, hover over the column cell and click the edit icon  or delete icon , respectively, to make changes or remove the request header row.

    • Request Body Schema (Optional) and/or Response Body Schema (Optional): These areas are used to provide any request and/or response structures, if required. Whether these structures are required depends on the specific API call. Sample request and response structures can often be obtained from an endpoint's API documentation, but should be validated using a third-party tool such as Postman or SoapUI to verify their accuracy.

      WARNING: Inaccurate request and/or response structures will lead to errors in Jitterbit Harmony. Testing with a third-party tool is strongly recommended to verify accuracy prior to using here.

      NOTE: The uploaded schema(s) are used solely for the purpose of defining the Connector Builder activity request or response schemas. Unlike in a Cloud Studio project, the schemas are not saved and are not available for reuse elsewhere within Connector Builder or Cloud Studio.

      TIP: If an API may respond with more than one possible JSON response structure, it is recommended to combine the response structures into one structure to handle all possible responses, as all fields in a JSON structure are optional.
      CAUTION: After editing the schemas in an existing Connector Builder connector that is already in use in the project, the connector user must use the Refresh button on the Data Schema step in order to bring in the current defined schema (see Connector Builder User Configuration).
      • Load URL: Click this button to open a window where you can load a schema from a URL:

        • File Type: Use the dropdown to select from the supported file types, including JSONXML, and XSD.
        • URL: Enter a URL that is accessible without authentication. Files up to 5 MB in size can be uploaded.
        • Load: Click this button to load the schema from the URL. Note that the file is retrieved only a single time for schema generation.

          NOTE: When uploading an XSD file that contains multiple top-level elements, you will be prompted to select the desired root node. Select the element and then click Finish to upload the file.

        • Cancel: Click Cancel to close the Upload Schema URL window without saving.

      • Upload File: Click this button to open a window where you can load a schema from a file that is accessible from the current machine:

        • File Type: Use the dropdown to select from the supported file types, including JSONXML, and XSD.
        • File: Use the Browse button to the right to browse to a file that has not yet been used in the current project. Files up to 5 MB in size can be uploaded.

        • Load: Click this button to load the schema from the file.

          NOTE: When uploading an XSD file that contains multiple top-level elements, you will be prompted to select the desired root node. Select the element and then click Finish to upload the file.

        • Cancel: Click Cancel to close the Upload Schema File window without saving.

      • View/Edit Schema: After a schema is loaded, you can view or edit it directly within the text area below the Load URL and Upload File buttons, or click the popout icon  to edit it in a larger area (once within that area, click the return icon  to come back to this screen). Another option is to manually enter or paste a schema into this area without loading a schema from a URL or file.
    • Save Activity: Click this button to save the activity and return to the main screen of step 3 with the activity added as a row in the table.

    • Save & New: Click this button to save the activity and open another screen where information for another new activity can be added.

    • Cancel: Click this button to close the activity screen without saving and return to the main screen of step 3.

  • Activities:

    • Activity Name and Display Name: These fields show the values entered during creation of the activity.

    • Request and Response: These fields indicate if a request or response schema was entered during creation of the activity.
    • Actions: In the column with the actions menu icon , to delete or edit an activity row that has been saved, hover over the column cell and click the edit icon  or delete icon , respectively, to make changes or remove the activity row.

  • Next: Click to temporarily store the configuration for this step and continue to the next step.
  • Save Changes: Click to save the configuration for this step and continue to the next step.
  • Delete: Available only after opening an existing connector to edit, click Delete to permanently delete the connector from the organization and close the configuration. A message will ask you to confirm you want to delete the connector.

    NOTE: Connectors that are currently in use cannot be deleted. A connector is considered to be in use if a connection has been configured in a project, regardless of whether any activities are configured. To delete the connector, first delete the connection (see Component Dependencies, Deletion, and Removal).
  • Discard Changes: After making changes, click Discard Changes to close the configuration without saving changes made to any step. A message will ask you to confirm that you want to discard changes.

  • Test: Click to open a separate screen where you can test the connector:

    • Base URL: Enter the base URL to be used for testing the connector.
    • Path: If applicable, enter a path to be appended to the base URL to be used for testing the connector.
    • HTTP Verb: Use the dropdown to select the appropriate method to test the connector with the URL listed to the right. The URL is constructed from the provided base URL and path. You can select from GET, PUT, POST, DELETE, or PATCH.
    • Username and Password: These fields are present only if Basic authentication is selected in step 2 of configuration.
    • Request body: This area is present only if the selected HTTP Verb is PUT, POST, or PATCH. Manually enter or paste the request body into this area. You can use the popout icon  to edit the request body in a larger area (once within that area, click the return icon  to return to this screen). Loading a file from a schema from a URL or file is not supported.

    • Test: Upon clicking Test, a message will appear next to the button indicating whether the connection succeeded or failed. If the connection failed, a link to more details will be present.

Step 4 – Summary and Confirmation

  • Basic Settings: Along the top is a summary of the information entered in step 1, including the image, connector name, display name, version, and description.

    To make changes, click the edit icon  to go back to step 1.

  • Authentication: The next section is a summary of the information entered in step 2, including authentication type. If basic authentication is used, the authentication test URL and method used for testing will also be displayed, with indication if this field is hidden.

    To make changes, click the edit icon  to go back to step 2.

  • Connector Activities: The last section is a summary of the information entered in step 3, including the base URL, global request headers, and activities.

    To make changes, click the edit icon  to go back to step 3.

  • Save: Click Save to save and close the connector. The connector will be saved in Cloud Studio but is not yet published or available for end users to use. When you save a connector, it is accessible from the Connector Builder index by the person who created it and by other members of the organization who have administrator permissions.
  • Publish: Click Publish to save and publish the connector. When you publish, the connector is automatically registered with Jitterbit Harmony and published to the agent. It is then available to be used by end users in the organization (see Connector Builder User Configuration).

    If you edit and then republish a connector that has already been published, a message will ask you to confirm you want to overwrite the previously published version:

    WARNING: If the connector is already in use, depending on the changes, this may cause some operations to become invalid. We recommend checking each place where the connector is used to validate it is working properly after re-publishing.

  • Unpublish: Available only for connectors that have been published, click Unpublish to hide the connector from end users. The connector will still be accessible in the Connector Builder index for the person who created it and organization administrators, but will no longer be visible to end users. Unpublished connectors are able to be re-published using the Publish button.

    NOTE: Connectors that are currently in use cannot be unpublished. A connector is considered to be in use if a connection has been configured in a project, regardless of whether any activities are configured. To unpublish the connector, first delete the connection (see Component Dependencies, Deletion, and Removal).
  • Delete: Available only after opening an existing connector to edit, click Delete to permanently delete the connector from the organization and close the configuration. A message will ask you to confirm you want to delete the connector.

    NOTE: Connectors that are currently in use cannot be deleted. A connector is considered to be in use if a connection has been configured in a project, regardless of whether any activities are configured. To delete the connector, first delete the connection (see Component Dependencies, Deletion, and Removal).
  • Export: This generates and downloads the connector as a JSON file with the connector metadata (see Connector Builder Exports and Imports).

Next Steps

After you publish a connector, members of the Jitterbit Harmony organization where it is published will have access to configure and use the connector in Cloud Studio projects. Learn more in Connector Builder User Configuration.

On This Page

Last updated:  Jul 28, 2020

  • No labels