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). Although this field is not required, it is recommended to supply a version number in case you make updates to the connector later.
  • 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 Next to save 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 to this step, click Discard Changes to close the configuration without saving changes to this 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 Next to save 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 to this step, click Discard Changes to close the configuration without saving changes to this 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.)

  • 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, /{paramname}. 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.
      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.
      • 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, except those containing cyclical references.
        • URL: Enter a URL that is accessible without authentication. Files up to 10 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, except those containing cyclical references.
        • 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 10 MB in size can be uploaded.

          WARNING: If you try to upload a file with the same name as an existing file already defined in the project, a popup will ask if you want to overwrite the existing file. If you click Continue, the file will be replaced with the new file with the same name in all places where it is used in the project. If you don't want to overwrite the file, click Cancel and then manually modify the file so it has a name that is not already being used, then try to upload it again.

        • 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 or Save Changes: Click Next or Save Changes 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 to this step, click Discard Changes to close the configuration without saving changes to this step. A message will ask you to confirm that you want to discard changes.

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.

  • 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).
  • 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).
  • 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:  Aug 06, 2019

  • No labels