How to use App Connect with HTTP

A business scenario

Your company plans to host a week-long outdoor event, with anticipated attendance figures that run into the thousands. You set up the event in your ticketing application so potential attendees can book tickets. When each attendee registers, you want to send them an email with more details about the event. And because the event is outdoors, you want to help the attendees to dress for the weather by including a weather forecast for each day that they book. But, you're busy so you want a fast way to make sure that each attendee receives the relevant forecast.

How can App Connect help?

Use App Connect to set up a flow that queries the Weather API, then uses the response to add details about the weather forecast to generated emails whenever an attendee registers for your event. By automating this process, you can concentrate on organizing a top-notch event that impresses your attendees.

What to consider first

If the HTTP server is in a private network (for example, behind a firewall in an on-premises location or in a private cloud), create a private network connection. App Connect can use this private network connection to access the HTTP server securely. For more information, see Connecting to a private network.

Connecting to HTTP

To connect App Connect to an HTTP endpoint, see Connecting to HTTP from App Connect.

General considerations for using HTTP in App Connect

• (General consideration) You can see lists of the trigger events and actions that are available on the Applications and APIs page of the App Connect Designer.

  For some applications, the events and actions depend on the environment and whether the connector supports configurable events and dynamic discovery of actions. If the application supports configurable events, you see a Show more configurable events link under the events list. If the application supports dynamic discovery of actions, you see a Show more link under the actions list.

• (General consideration) If you are using multiple accounts for an application, the set of fields that is displayed when you select an action for that application can vary for different accounts. In the flow editor, some applications always provide a curated set of static fields for an action. Other applications use dynamic discovery to retrieve the set of fields that are configured on the instance that you are connected to. For example, if you have two accounts for two instances of an application, the first account might use settings that are ready for immediate use. However, the second account might be configured with extra custom fields.
• Be aware of the following considerations for the Invoke method action.
  • The supported HTTP methods are GET, POST, PUT, PATCH, DELETE, and HEAD.
  • The HTTP and HTTPS transports are supported, and the URL that you specify must be fully qualified, as shown in the following examples.

    http://www.example.com/

    https://host_name:port/path

    https://my_API_URL?query_parameter1=value1&query_parameter2=value2

    The URL can also contain mappings from previous nodes in the flow. The following example shows a Postal/Zip Code mapping that was inserted using Insert a reference:

    

    Note: If you specified an override URL when you connected to the HTTP account, the protocol, hostname, and port that you specify in the URL (fully qualified) field are replaced by your override settings when the flow runs.
  • Request headers (if required to define extra operating parameters) can be specified as data properties (with a name and String data type) or as a JSON object that consists of comma-separated name-value pairs.
    • To specify request headers as data properties, complete the following steps.
      1. Click Add property to define each property with a data type of String.

         

      2. Click Edit mappings to show these properties as fields, then specify their values. (To add or remove properties, click Edit properties.)

         

         To update the name of a defined property, make sure that the associated field is empty before you click Edit properties. For more information about specifying data properties, see Defining your own data properties.

    • To specify request headers as JSON (for example {"Accept": "application/json", "Content-Type":"application/json"}), click Map to object and then enter the JSON.

      

      If you already defined one or more property fields under the Request headers heading, but prefer to use JSON, delete the properties then click Map to object to display a Request headers field that you can type into.

  • Optionally implement your own error handling within the flow by indicating whether the flow continues if something unexpected occurs. Set Continue flow (non-2xx) to true to continue running the flow if a status code other than 2xx (Success) is returned by the HTTP call.

    

    If set to false (the default), flow processing stops when a non-2xx status code is issued.

  • A maximum of three attempts are made to call the HTTP server, with a five-second delay between retries. A flow will typically time out after 60 seconds.
  • Depending on the format of the test results, the test results tree view for the HTTP connector might not show every entry. Use the code view to see the complete JSON input and output.

Ways of processing the HTTP response

The response from an HTTP invoke method is returned in a format that the endpoint supports (for example, JavaScript Object Notation (JSON), XML, or CSV format) and is passed as a string. To map the response headers and response body in a subsequent action in your flow, use one of the built-in App Connect parsers to convert the string into an object that represents the string. For example, if the response is in JSON format, you can use the JSON parser to convert the JSON string into a JSON object. You can map to the response by selecting either Response headers or Response body for the HTTP / Invoke method in the list of available inputs.

Troubleshooting tips

• If you observe network errors for an HTTP Invoke method action in your flow, the cause might be related to connectivity or security issues. Use these tips to help with error resolution:
  • Verify that the network is available and that the HTTP server can be reached. For example, the error might be due to a network timeout.
  • If you can successfully call out to the HTTP endpoint by using an API tool, verify that your request header specifications in that tool are identical to the ones that are specified in the Request headers field of your HTTP node.
  • Investigate whether SSL certificate errors caused the issue. App Connect uses Transport Layer Security (TLS) to establish a secure communication channel to the HTTP endpoint, and rejects the certificate that a target server presents if issues are detected. For example, the certificate is rejected if it is untrusted or expired, or has missing intermediate (or chain) certificates.

    If you can successfully call out to the HTTP endpoint by using an external utility, check whether SSL certificate checking is enabled for that utility. If it isn't, you can enable it and test the call again to see whether it passes.

  • To help you determine the cause of the error, make sure that the Continue flow (non-2xx) field is set to true, then map to the HTTP response status code in a subsequent node in the flow, as shown in the following example.

    Then run the flow again and check to see which status code is returned.

• When you employ the HTTP connector and specify the Request header field as content-type: application/x-www-form-urlencoded, you need to provide a set of key-value pairs in the corresponding Body field. If you use the Variable node to incorporate variables that are established earlier in the flow, and any of these variables contain an ampersand (&), the ampersand serves as a separator between key-value pairs. This separator might lead to an unexpected result from the flow.
  For example, consider the following setup.

  • The header is set to application/x-www-form-urlencoded and key-value pairs of the body are set to colors={{$Setvariable.variable.colors}}&pets={{$Setvariable.variable.pets}}.
  • The variable is set to colors=blue pets=dog&cat.
  • The test considers the ampersand (&) as a separator and the result is "colors": "blue", "dog": "", "pets": "cat".
  Tip: To avoid interpreting an ampersand as a separator, use proper URL encoding for the ampersand character. However, not all websites support this encoding method.

Events and actions

HTTP events

These events are for changes in this application that trigger a flow to start completing the actions in the flow.

Your flow completes these actions on this application.