HTTP Receive Request activity

Use the HTTP Receive Request activity to configure the Integration Appliance to act as an HTTP listener

The following figure shows the Integration Appliance acting as an HTTP listener.
Figure 1.
The HTTP Receive Request activity is a starter activity. When an orchestration that starts with an HTTP Receive Request activity is deployed to the Integration Appliance, the Integration Appliance acts as an HTTP listener waiting for HTTP requests. When a HTTP request is received, the following actions occur:
  1. An orchestration job is started.
  2. The HTTP Receive Request activity processes the incoming HTTP request and maps the HTTP request to the output parameters of the activity.
  3. The output parameters are mapped to the specified orchestration variables. During design time in the Map Outputs task of the Checklist, the mapping between the output parameters and the orchestration variables is defined.
  4. The remaining activities in the orchestration are processed. (In the graphical representation of the orchestration,  the remaining activities are the activities located on the right side of the HTTP Receive Request activity).
By default, decompression is enabled for the HTTP Receive Request activity. For more information, see Decompression with the HTTP Receive Request activity.

You cannot deploy two HTTP Receive Request activities to the appliance with the same endpoint details, URL and method.

For single HTTP Receive Request activity

If you deploy only one HTTP Receive Request activity for a URL, the orchestration accepts all requests of those URLs starting with that base URL. For example, if you deploy /customer then it accepts requests for /customer, /customer/21, /customer/21/dept, and so on.

If you deploy an HTTP Receive Request activity for a URL with path parameters, then the orchestration accepts only those requests whose URLs match with the configured URL with values for path parameters. For example, if you deploy /customer/{custid} then it accepts requests such as /customer/10, /customer/21, /customer/dept . The following URLs are not accepted: /customer, /customer/21/dept, and so on.

For multiple HTTP Receive Request activities

If you deploy two HTTP Receive Request activities that are configured with the same base URL, and one with path parameter, then the activities accept requests whose URLs strictly match with the configured URL. For example, if you deploy /customer and /customer/{path parameter}, and if /customer is invoked the request goes to the activity configured with /customer. If /customer/007 is invoked, the request goes to the activity configured with /customer/{path parameter}. Also, if you invoke the following URLs: /customer/dept/1 or /customer/12/21, none of the activities accept the requests.

Note: If you deploy two activities, the first one as /customer/department and the second one as/customer/{path parameter}, and if /customer/department is invoked, then the request goes to the activity which was deployed first (/customer/department). If /customer/{path parameter} is deployed first, then the request goes to /customer/{path parameter}.
Note: It is also recommended that you do not deploy the same URL for Web Services and HTTP.
Base URL - Part of the URL before path parameters. For example - If the configured URL is/employee/manager/{id}, then Base URL will be /employee/manager.

Adding an HTTP Receive Request activity to the orchestration

  1. Create or open an orchestration. A graphical representation of the orchestration is displayed.
  2. Select the Activities tab and expand the HTTP folder.
  3. Drag the Receive Request activity onto the orchestration.
  4. Select the activity. The Checklist is displayed with the Summary task active in the properties pane. The Properties pane is located under the graphical representation of the orchestration in the Workspace.

Creating, selecting, or editing an HTTP endpoint

  1. Click Pick Endpoint task from the Checklist and choose from one of the following actions:
    • Select an existing endpoint:
      1. Select Browse. The Project Explorer is displayed.
      2. Select an existing endpoint and click OK. Skip to the "Configure the activity" procedure.
    • Select an existing endpoint and edit the endpoint:
      1. Select Browse. The Project Explorer is displayed.
      2. Select an existing endpoint and click OK.
      3. Click Edit. The Edit Endpoint pane is displayed.
    • Create a new endpoint: Select New. The Create Endpoint pane is displayed.
  2. Create or edit a HTTP endpoint, see Creating or editing an HTTP endpoint.

Configuring the activity

  1. Select the Configure task from the Checklist. The Configure pane is displayed.
  2. Configure all the fields and check boxes in this pane as described in the following table:
    Table 1.
    Field Description
    URL (Path After Hostname) Specifies the resource path where the Integration Appliance listens for inbound HTTP requests, for example: /mypath. The string you specify in this field must exclude the string: http://, the hostname, and the port number of the Integration Appliance. The full URL that the Integration Appliance uses to listen for inbound HTTP requests is automatically constructed from the hostname of the Integration Appliance, the port number specified in the HTTP endpoint, and the path specified in this field. For example, if the full URL that the Integration Appliance listens for HTTP requests is http://myAR:myPort/myPath, in this field you only need to specify the string: /myPath. The specified path must be unique for the HTTP Receive Request activities that are deployed at the same time on the same Integration Appliance using the same port.

    To make use of path parameters and query parameters, enter a URL in this format, url/ {path}?name1=value1&name2=value2. This allows you to map a string value to the "{path}" parameter and to specify query parameter names: name1 and name2 in this example. If you choose to declare multiple "{path}" parameters, it is recommended that each parameter has a unique name. Parameters with the same name are represented by only one node in the map. The path parameters are displayed under /httpheaders/pathParameters in Map Output. Query parameters are displayed under /httpheaders/queryParameters in Map output.

    Note: In the URL, any value assigned to a query parameter is not passed to the mapper. The value comes from the server based on the actual incoming request.
    Note: The path that the Integration Appliance listens for inbound HTTP requests is a resource path string that you specify and does not correspond to actual directory path on the Integration Appliance.
    Method Specifies which HTTP method is accepted by the listening server.
    Of Type Specifies the expected message type of the HTTP request - either Text or Binary.
    Requires a Reply Specifies if a reply should be sent to the sender of the request.
    Note: If this check box is selected, you must add and configure a HTTP Send Response activity in your orchestration.
    Use Compression/Decompression Specifies if compression/decompression is turned on or off at the activity level. By default, the Use Compression/Decompression check box is clear and compression/decompression is disabled for this activity. Select the Use Compression/Decompression check box to enable compression/decompression for this activity. For more information, see Compression/Decompression with the HTTP Invoke/Get/Post/Head/Put/Delete Request activity

Specifying the request headers

  1. Select the Request Headers task from the Checklist. The Request Headers pane is displayed. A Custom Headers table is displayed at the top, a Include pre-defined standard headers checkbox is displayed in the middle and a Standard Headers table is displayed at the bottom.
  2. Click the Add button to add a header to the Custom Headers table. Click on the new entry to enter a header name or select a header name from the drop down list. If the header name is a pre-defined header name, a description is displayed in the Description column, otherwise enter your own description for your headers.
  3. To use the pre-defined standard headers, check the Include pre-defined standard headers checkbox. Note that duplicate header names are not allowed (ignoring the case difference) and you may be prompted to remove any duplicate headers in the Custom Headers table. The selected HTTP headers are displayed under /httpheaders in Map Output.

Specifying Swagger information

  1. Select the Swagger task from the Checklist to set sample message.
  2. Specify the Request sample (JSON) and Response sample (JSON) information. If you do not specify any request sample, the Swagger Output will display with empty sample objects.
  3. Click on Generate Swagger button which will display the code in the Swagger Output textbox. You can also click Download Swagger to download and share the file, if required.

Mapping the output of the activity

  1. Select the Map Outputs task in the Checklist. The output parameters of the activity are displayed in the From Activity pane of the Map Outputs task as described in the following table:
    Table 2.
    Output Parameter Description
    httpheaders Specifies the header of the HTTP request.
    body Specifies the body of the HTTP request message.
    The following table defines the nodes of the optional httpheaders output parameter.  
    Table 3.
    Nodes of the httpheaders Output Parameter Description
    httpheaders/uri Specifies the resource path of the incoming request, for example: /myPath.
    httpheaders/method Specifies the type of HTTP request.
    httpheaders/host Specifies the IP address or the host name of the client.
    httpheaders/otherHeaders/headerItem Specifies an element that contains a set of HTTP header parameters as name/value pairs. Multiple HTTP header parameters can be specified in the HTTP request, so this is a recurring node.
    httpheaders/<configured_header_name> If you configured at least one request header in Request Headers step, each is displayed here. <configured_header_name> is replaced with the actual header names you selected or entered.
    httpheaders/pathParameters If you configured path parameters in the URL in the Configure step, each is displayed here. If no path parameter is specified, this node does not display.
    httpheaders/queryParameters If you configured query parameters in the URL in Configure step, each is displayed here. If no query parameter is specified, this node does not display.
    httpheaders/otherHeaders/headerItem/name Specifies the name of the HTTP header parameter.
    httpheaders/otherHeaders/headerItem/value Specifies the value of the HTTP header parameter.
  2. Create a map between the output parameter or parameters of the activity and orchestration variable or variables. See Creating a map for general instructions on mapping.
    Note: To test your orchestration that starts with the HTTP Receive Request activity, you can use the HTTP Post Utility included with the Studio installation, to send HTTP requests to the listening Integration Appliance during run time. You can access the HTTP Post Utility from the start menu, select Programs > IBM > Cast Iron Studio > HTTP Post Utility option. The URL you specify in the URL of the inbound connector field must contain the full URL, for example: http://myAR:myPort/myPath.



Feedback | Notices


Timestamp icon Last updated: Wednesday, 15 June 2016


http://pic.dhe.ibm.com/infocenter/wci/v7r0m0/topic/com.ibm.wci.doc/http_receive_request_activity.html