HTTP v2 connection

Introduction

An HTTP v2 connection, created using the HTTP v2 connector, establishes access over the HTTP or HTTPS protocol to a service such as a REST API, GraphQL API, or web form. Once a connection is configured, you can create instances of HTTP v2 activities associated with that connection to be used either as sources (to provide data in an operation) or as targets (to consume data in an operation).

Create or edit an HTTP v2 connection

A new HTTP v2 connection is created using the HTTP v2 connector from one of these locations:

• The design component palette's Project endpoints and connectors tab (see Design component palette).
• The Global Connections page (see Create a global endpoint in Global Connections).

An existing HTTP v2 connection can be edited from these locations:

• The design component palette's Project endpoints and connectors tab (see Design component palette).
• The project pane's Components tab (see Component actions menu in Project pane Components tab).
• The Global Connections page (see Edit a global endpoint in Global Connections).

Configure an HTTP v2 connection

Each user interface element of the HTTP v2 connection configuration screen is described below.

• Connection Name: Enter a name to use to identify the connection. The name must be unique for each HTTP v2 connection and must not contain forward slashes / or colons :. This name is also used to identify the HTTP v2 endpoint, which refers to both a specific connection and its activities.

• Base URL: Enter the base URL. The base URL is used for testing the connection. Whether this field is used at runtime depends on whether the HTTP Activity URL field of an HTTP v2 activity is completed:

  • If a partial URL or no URL is provided in the HTTP Activity URL field, then the URL used at runtime is concatenated from the Base URL and HTTP Activity URL.

  • If a full URL is provided in the HTTP Activity URL field, then the Base URL is not used at runtime.

• Authorization: Use the menu to select the authentication type, summarized below. Configuration of each authentication type is described in HTTP v2 connection authentication types.

  • API Key: Specify an API key-value pair to send in headers or query parameters.

  • AWS Signature: Specify an AWS access key ID, secret access key, region, service, and session token to send using Amazon Web Services (AWS) Signature Version 2 in headers or query parameters.

  • Basic Auth: Specify a username and password to send in headers.

  • Bearer Token: Specify a bearer token to send in headers.

  • Digest Auth: Specify a username, password, realm, nonce, algorithm, QOP, nonce count, client nonce, and opaque to send in headers.

  • Hawk Authentication: Specify a Hawk authentication ID, authentication key, application-specific information, an app ID, and DLG to send in headers.

  • No Auth: Select to access the service anonymously without authorization.

  • OAuth 2.0: Specify the grant type and provide the OAuth token endpoint, client ID, client secret, and scope to send in headers or the request body.

• Retry: Functional only when using an environment associated with a private agent group, this setting is used to retry a request when an HTTP v2 endpoint returns one of these status codes: 500, 502, 503, or 504.

  This setting takes effect when used with private agents version 10.34 or later.

  Select the Retry checkbox to expand additional configuration options:

  

  • Retry Interval (Seconds): Enter the number of seconds (maximum of 5 seconds) to wait between resending a request to the HTTP v2 endpoint.

  • Max Retries: Enter the maximum number retries (maximum of 5 retries) that a request will be resent to the HTTP v2 endpoint. If the request still fails after the maximum number of retries, an exception with an error message will be returned in the operation log. In addition, the private agent will log each retry in the jitterbit.log log file.

    Each retry is treated as part of the same operation run, where only a single record appears in the operation log. Any operation actions configured to run downstream operations are triggered based on the end status of the operation after retrying up to the maximum number of retries.

• Optional Settings: Click to expand additional optional settings:

  

  • Get response content in base64 string: Select to return base64-encoded responseContent from HTTP v2 activities.

  • Proxy Settings: Use the menu to select the proxy settings, one of these options:

    • Custom: Proxy settings are enabled using the inputs specified in the additional fields that become available when this option is selected. This option bypasses the private agent proxy configuration if one exists.

      

      • Host: Enter the HTTP proxy server host name.
      • Port: Enter the HTTP proxy server port.
      • User: Enter the username for HTTP proxy server authentication.
      • Password: Enter the password for HTTP proxy server authentication.
      • NTLM Domain: Enter the NTLM domain for HTTP proxy server authentication.
      • Allow Unverified Certs Used by Proxy: Select to allow unverified certificates to be used by the HTTP proxy server.

    • Default: Proxy settings are enabled, using the private agent proxy configuration if one exists. If proxy settings are not specified in the agent configuration, then the Default setting has the same result as the Disable setting.

    • Disable: Proxy settings are disabled, bypassing the private agent proxy configuration if one exists.

  • Advanced HTTP Properties: If applicable, set these advanced options:

    • Content-Type: Enter the content-type of the request structure that is expected by the particular API. For example, text/plain, application/json, application/x-www-form-urlencoded, etc. If the method being used does not accept structured data, or if the API does not require the content-type to be specified, leave this field blank. This field is not affected by the Send request headers in activity execution setting.

      Alternatively, the content-type can be specified in other UI configuration fields or provided in the request transformation. If content-type is specified in multiple places, this order of precedence is followed:

      1. A Content-Type header provided in the Additional Settings table of an HTTP v2 activity overrides all fields below.
      2. The bodyContentType field specified in a request transformation overrides the remaining fields below.
      3. A Content-Type header provided in the request transformation headers node overrides the remaining fields below.
      4. A Content-Type header provided in the Request Headers field of an HTTP v2 activity overrides the remaining field below.
      5. A Content-Type header provided in the Request Headers field of an HTTP v2 connection, if Send Request Headers in Activity Execution is enabled, has the least precedence.

      Note

      If a header is defined in multiple locations, every instance of the header will be added to an activity's request following the order of precedence above. This order is based on how services typically handle duplicate headers in a request.

    • Enable content encoding: Select to send the Accept-Encoding header with Gzip encoding. This field is not affected by the Send Request Headers in Activity Execution setting.

      Alternatively, this header can be defined in other UI configuration fields or provided in the request transformation. If this header is specified in multiple places, this order of precedence is followed:

      1. An Accept-Encoding header provided in the request transformation headers node overrides all fields below.
      2. An Accept-Encoding header provided in the Request Headers field of an HTTP v2 activity overrides the remaining field below.
      3. An Accept-Encoding header provided in the Request Headers field of an HTTP v2 connection, if Send Request Headers in Activity Execution is enabled, has the least precedence.

      Note

      If a header is defined in multiple locations, every instance of the header will be added to an activity's request following the order of precedence above. This order is based on how services typically handle duplicate headers in a request.

    • Enable chunked transfer encoding: Select to send the Transfer-Encoding: chunked header. Use this option if you are transferring large data sets. This field is not affected by the Send Request Headers in Activity Execution setting.

      Alternatively, this header can be defined in other UI configuration fields or provided in the request transformation. If this header is specified in multiple places, this order of precedence is followed:

      1. A Transfer-Encoding header provided in the request transformation headers node overrides all fields below.
      2. A Transfer-Encoding header provided in the Request Headers field of an HTTP v2 activity overrides the remaining field below.
      3. A Transfer-Encoding header provided in the Request Headers field of an HTTP v2 connection, if Send Request Headers in Activity Execution is enabled, has the least precedence.

      Note

      If a header is defined in multiple locations, every instance of the header will be added to an activity's request following the order of precedence above. This order is based on how services typically handle duplicate headers in a request.

    • Allow weak ciphers: This option is not currently functional.

    • Keep alive: Select to allow a single TCP connection to remain open for multiple HTTP requests and responses.

    • SSL certificate verification: Select to verify the service by validating the SSL / TLS certificate presented during the handshake process.

    • Encode request URL: Select to URL encode the request URL.

    • Follow redirects: Select to allow the connector to reroute with any redirects present on the Base URL. If the Base URL redirects and this setting is unselected, an error will occur when testing the connection and on the first run of an operation. When this option is selected, the following field becomes visible:

      • Maximum number of redirects: Enter the amount of redirects the connection will follow before returning an error.

    • Only applicable when using HTTPS: Use the menu to change the selection from Negotiate (default) to a specific TLS version if the service requires it, selecting from TLS 1.0, TLS 1.1, TLS 1.2, or TLS 1.3.

    • Request Headers: Define HTTP headers for the connection. Click the add icon to add a header to the table below and enter a key-value pair for each request parameter.

      To save the row, click the submit icon in the rightmost column.

      To edit or delete a single row, hover over the rightmost column and use the edit icon or delete icon .

      To delete all rows, click Clear All.

      Alternatively, headers can be defined in other UI configuration fields or provided in the request transformation. Headers that do not share a key are sent cumulatively, regardless of where they are specified.

      If the same header key is specified in multiple places, this order of precedence is followed:

      1. A header provided in the request transformation headers node overrides all fields below.
      2. A header provided in the Request Headers field of an HTTP v2 activity overrides the remaining field below.
      3. A header provided in the Request Headers field of an HTTP v2 connection (this field), if Send Request Headers in Activity Execution is enabled, has the least precedence.

      Note

      If a header is defined in multiple locations, every instance of the header will be added to an activity's request following the order of precedence above. This order is based on how services typically handle duplicate headers in a request.

      Important

      Fields in the Request Headers table display the variable icon only in edit mode. For these fields' variable values to be populated at runtime, the agent version must be at least 10.75 / 11.13.

    • Send request headers in activity execution: Select to pass headers defined in Request Headers to HTTP v2 activities. Refer to the orders of precedence above to determine how headers defined in an HTTP v2 connection interact with headers defined in other locations.

• Test: Click to verify the connection by sending an HTTP GET request using the configured authorization. A test is considered successful if any 2xx HTTP status code is returned. A 405 Method Not Allowed response is also treated as successful. When the connection is tested, the latest version of the connector is downloaded by the agent(s) in the agent group associated with the current environment. This connector supports suspending the download of the latest connector version by using the Disable Auto Connector Update organization policy.

• Save Changes: Click to save and close the connection configuration.

• Discard Changes: After making changes to a new or existing configuration, click to close the configuration without saving. A message asks you to confirm that you want to discard changes.

• Delete: After opening an existing connection configuration, click to permanently delete the connection from the project and close the configuration (see Component dependencies, deletion, and removal). A message asks you to confirm that you want to delete the connection.

Next steps

After an HTTP v2 connection has been created, you place an activity type on the design canvas to create activity instances to be used either as sources (to provide data in an operation) or as targets (to consume data in an operation).

Menu actions for a connection and its activity types are accessible from the project pane and design component palette. For details, see Actions menus in Connector basics.

These activity types are available:

• PATCH: Applies partial modifications to an existing resource on a service accessible over the HTTP or HTTPS protocol and can be used as a source or target in an operation.

• HEAD: Retrieves the status line and header section of a resource on a service accessible over the HTTP or HTTPS protocol and can be used as a source or target in an operation.

• POST: Creates a new resource on a service accessible over the HTTP or HTTPS protocol and can be used as a source or target in an operation.

• GET: Retrieves information about a resource on a service accessible over the HTTP or HTTPS protocol and can be used as a source or target in an operation.

• OPTIONS: Retrieves information about the communication options for a resource on a service accessible over the HTTP or HTTPS protocol and can be used as a source or target in an operation.

• BULK: Sends multiple requests to a service accessible over the HTTP or HTTPS protocol and can be used as a source or target in an operation.

• DELETE: Deletes a resource on a service accessible over the HTTP or HTTPS protocol and can be used as a source or target in an operation.

• PUT: Replaces an existing resource on a service accessible over the HTTP or HTTPS protocol and can be used as a source or target in an operation.