HTTP Receiver

HTTP Receiver is a process starter activity that starts the process based on the receipt of an HTTP request.

General

Note: When configuring an HTTP activity, configuring an HTTP Connector shared resource as the value for a module property is not supported. Configure a literal value instead.

The General tab has the following fields.

Field Literal Value/Module Property/Process property Description
Name None The name to be displayed as the label for the activity in the process.
HTTP Connection Yes The HTTP Connector resource describes the characteristics of the connection used to receive incoming HTTP requests.

For more information about specifying shared resources, see HTTP Connector .

Context Path Yes This is the prefix of a URL path that is used to select the contexts to which an incoming request is passed.

You can either specify both Context Path and Path Spec, any, or none of these elements. For example, the path displays as the http://hostname.com/contextPath/pathSpec format.

If the Context Path is not specified, the Context Path is referred to as the root context.

In a Send HTTP POST request where a Path Spec is not provided, add a forward slash (/) after the Context Path (for example: http://<host>:<port>/<contextPath>/). If you do not add the forward slash, the POST request is redirected as a GET request for the resource at /<context_path>.

In a Send HTTP POST request where a Path Spec is provided no forward slash (/) is required (for example: http://<host>:<port>/<contextPath>/<pathSpec>).

Path Spec Yes If specified, it is added as a prefix of a URL of the form http://hostname.com/contextPath/pathSpec.
Output Style None The type of output. It can be either String or Binary.
Note: If you are running POST/PUT requests using HTTP 2.0 (a binary protocol), you must set this field to Binary.
Parse Post Method Data None Specifies to parse the message body of the HTTP request into a schema for the output of the activity.

When this check box is selected, the parameters specified in the Parameters field are used to validate the incoming request and parse it into the output schema. This field is present only when the Output Style is String.

Note: For an incoming GET request, there is no message body, so this field has no effect on the incoming GET requests.
Parameters None The parameters of the incoming HTTP request.

If you specify parameters in this table, the incoming request is parsed and represented as a schema in this output of the activity. For each parameter, you must provide a name, datatype, and whether the field is Optional, Required, or Repeating.

Use the and buttons to the right of the parameter table to add and remove parameters.

Note: Specifying parameters in this field parses the query string of the request into the output schema, regardless of whether the Parse Post Method Data check box is selected. Selecting the Parse Post Method Data check box and specifying parameters here is required to parse the message body along with the query string of the request.
Expose Security Context None Places the information from the user’s security context (either authentication or SSL certificate information) into the Context or SecurityContext output element.

This is a fairly expensive operation and SSL certificates can consume memory resources. Hence, select this option only if you require information from the user’s security context for later use in your process.

Default Encoding Yes Specifies the encoding to use if no charset is specified in the Content-Type header of the message. This encoding is used for the message body and URL.

However, when URIEncoding is specified in the HTTP Connector shared resource, the Default Encoding parameter specified here applies to the contentType alone and not to the URIEncoding property.

Note: Imported projects display the HTTP Authentication check box under the General section if the check box was selected in a previous version TIBCO ActiveMatrix BusinessWorks™ 6.x. Authentication remains enabled on the HTTP Reciever activity if you do not clear the check box. If you clear the Authentication check box, a warning message is displayed prompting you to confirm your action. To remove authentication from the activity, click OK. Once you have removed authentication from the HTTP Reciever activity, you can reapply it using the Basic Authentication policy.

Description

Provide a short description for the activity in this field.

Advanced

The Advanced tab has the following fields.

Field Process Property/Module Property Description
Fill Standard Headers None When this check box is selected, additional headers such as Authorization, User-agent, and Host are populated in the Dynamic Headers element in the server response received from the client.
Write to File None Select this check box to write incoming requests that exceed the specified threshold size to a file instead of storing the request in memory. You can accept large incoming requests without consuming a great deal of memory. Selecting this check box displays the Directory, Creating Non-Existing Directories, and Threshold Data Size(bytes) fields.
Note: This option is not intended to be used with the Parse Post Method Data option on the General tab. When you select Write to File, the PostData output element becomes a choice element containing either the output fileName or the PostData. This depends upon whether the data exceeds the size specified in the Threshold Data Size field. It is recommended to use either the Write to File option or the Parse Post Method Data option, but not both at the same time.

Not selecting this field keeps the incoming requests in memory.

Note: After writing, the files created using this option are not deleted automatically. You must manage the storage used by these files and delete them when they are no longer used.
Directory Yes The directory to write messages that are above the specified threshold. The process engine does not attempt to create the directory if the specified directory does not exist. Therefore, create the directory before starting the process engine.
Create Non-Existing Directories None When this check box is selected, all directories in the path specified in the Directory field are created, if they do not already exist.

If this check box is not selected and there are one or more directories in the specified path in the Directory field that do not exist, an exception is raised.

Threshold Data Size(bytes) Yes The maximum size (in bytes) of an incoming request that can be kept in the memory. Requests larger than the specified size are written to a file in the specified directory. The file’s name is output so that subsequent activities in the process can access the file and read its contents.

Specify zero (0) in this field for all incoming requests to be saved to a file.

Sequence Key None This field can contain an XPath expression that specifies which processes should run in sequence. Process instances with sequencing keys that evaluate to the same value are executed sequentially in the sequence the process instance was created.
Custom Job Id None This field can contain an XPath expression that specifies a custom ID for the process instance.

Special Characters in HTTP Requests

Depending upon the content type of the data for the request, the request can contain URL-encoded data and the server is expected to decode the data. For example, an incoming request may have the following message body:

name=John%20Smith&address=500%201%2F2%20Main%20Street

If the message body is not parsed (Parse Post Method Data check box is not selected on the General tab), the body of the message remains URL-encoded in the PostData output element. If the message body is parsed, the data is decoded before being placed in the PostData output element, and that element would display as follows:

name=John Smith&address=500 1/2 Main Street

Note: The sequence of the parameters may not be the same in the PostData output element as the sequence in the original HTTP request sent by the client when the message body is parsed.

The PostData output element can contain different data and be a different length depending upon whether the message body is parsed. Hence, ensure that you obtain data from the parameters output element when the message body is parsed.

Output Editor

The Output Editor tab describes the data structure for the headers of the HTTP request. You can use the default structure, or you can alter the structure, if the incoming request has a specific data structure for the header of the request.

The header structure is defined by the HTTP protocol. For more information about the fields and content of the header of an HTTP request, see the HTTP specification at w3.org.

Output Header Element Datatype Description
Accept string This field specifies media types that are acceptable for response messages for the incoming request. For example, text/*,text/html. Media types are described in the HTTP specification at w3.org.

If no Accept-Header field is present, it is assumed that the client accepts all media types.

Accept-Charset string This field specifies the character sets that are acceptable for response messages for the incoming request. For example, iso-8859-5, unicode-1-1. Character sets are described in the HTTP specification at w3.org.

If no Accept-Charset header is present, it is assumed that the client accepts any character set.

Accept-Encoding string This field specifies the content-coding values that are acceptable for response messages. For example, compress, gzip.

For more information about this header field, see the HTTP specification at w3.org.

Content-Type string This field indicates the media type of the entity body sent to the receiver. For example, text/html; charset=ISO-8850-4. Media types are described in the HTTP specification at w3.org.
Content-Length string This field indicates the size of the entity body (in decimal number of OCTETs) sent to the receiver.

This field takes into account the encoding of the message body.

For more information about when the message body is URL encoded, see Special Characters in HTTP Requests.

Connection string Using this field the requestor can specify options required for this connection. For example, the option close specifies that the requestor would like the connection to be closed when the request is complete.
Cookie string If you want to receive more than one cookie, set the cardinality for this field to repeating (*).
Note: For correct parsing and processing of cookies, input must be in the format "key=value".

For more information about this field, see the HTTP specification at w3.org.

Pragma string This field is used to include implementation-specific directives that might apply to the receiver.

For more information about this field, see the HTTP specification at w3.org.

Conversations

You can initiate the conversation here. Click the Add New Conversation button to initiate multiple conversations.

For more information about conversations, see TIBCO ActiveMatrix BusinessWorks™ Application Development guide.

Output

The following is the output for the activity.

Output Item Datatype Description
Method string The method specified in the request. For example, GET or POST.
RequestURI string The address portion of the request. This is the portion before the question mark (?).
HTTPVersion string The version field of the HTTP request.
PostData or BinaryContent or FileName string The message body of the HTTP request. The content of this element depends upon whether the message body is parsed. Parsing behavior is controlled by the Parse Post Method Data field on the General tab.

The content of this element is PostData if the Output Style field selected is of type String, and the element is BinaryContent if the Output Style field selected is of type Binary.

For more information, see Special Characters in HTTP Requests.

If the Write to File field is selected on the Advanced tab, and the incoming message exceeds the specified threshold size, the PostData field can also contain the file name of the file containing the message.

QueryString string The query string portion of the request. This is the portion after the question mark (?).
Header string The header of the HTTP request.
Protocol string This can be HTTP or HTTPS depending upon the protocol used by the request.
Port string The port number on which the request was received. This is the port number configured in the HTTP Connector resource.
Headers complex

The fields of the header specified on the Output Editor tab.

For more information about these items, see the description of the Output Editor tab.

Parameters complex The parameters for the incoming request. These parameters are configured in the Parameters field on the General tab.

When the Parse Post Method Data check box on the General tab is selected, the parameters include the parameters in the query string and message body of the incoming HTTP request.

When the Parse Post Method Data check box is not selected, the parameters include only the query string of the incoming request.

DynamicHeaders complex The dynamic header is an additional header parameter to receive header parameters from incoming HTTP requests. This element is specified in the Output Editor tab. The DynamicHeaders consists of the following information:
  • Name: the name of the header (case insensitive)
  • Value: the value of the header

The following overriding conditions can be considered:

  • Overrides the value of HeaderName with the value found in DynamicHeaders, if it is a non-repeating header. If more than one occurrence of this header is found under DynamicHeaders, it generates the "The header [ headerName ] is defined as non-Repeating Header in Input Headers. This header cannot have multiple occurences in DynamicHeaders." exception.
  • If it is a repeating element, add the respective name value pairs under dynamic headers, which is added to the existing list maintained for this element.
  • For a repeating element, if the new header name is not found under the Headers section declared through TIBCO Business Studio™ for BusinessWorks™, the following is added into the HTTP Headers.
    • Shows only one value, if found once in DynamicHeaders.
    • Shows array of values, if found repeating in DynamicHeaders.
mimeEnvelopeElement complex This element contains the message attachments.

This element contains a repeating element named mimePart that contains each mime attachment.

mimeHeaders complex This element contains the mime header for each mimePart. Mime headers can contain the following information:
  • content-disposition: To suggest a filename for an attachment, use "*;filename=<filename>" in this element.
    Note: HTTP servers may alter or ignore the suggested name.
  • content-type
  • content-transfer-encoding
  • content-id
  • any element

For more information about MIME headers and their syntax, see http://www.faqs.org/rfcs/rfc2045.html.

Note: When the content type is specified as "text/*" (for example, "text/xml"), the attachment content is expected to be in either the textContent input element or the file name storing the attachment is expected to be in the fileName input element. When the content type is anything other than "text/*", the attachment content is expected to be in either the binaryContent input element or the file name storing the attachment is expected to be in the fileName input element.
binaryContent | textContent | fileName choice This element contains the mime attachment.

The element can be one of the following:

  • binaryContent: content of the attachment content of the attachment when the attachment is binary data.
  • textContent: content of the attachment when the attachment is text data.
  • fileName: the file name of the attachment written to the disk.
Context complex Contains information about the client’s environment.

This element holds the optional RemoteAddress element.

RemoteAddress string The IP address of the client that submitted the HTTP request.

Threading Policy Details

The following are the details about the HTTP Receiver activity threading policy.

Activity Type Multi-Threaded? Default Thread Count Thread Count Configuration
ProcessStarter Yes
  • Minimum QTP Threads = 10
  • Maximum QTP Threads = 75
It can be configured on the HTTP Connector shared resource using the following fields:
  • Minimum QTP threads
  • Maximum QTP threads

Policy

Activities that support policies display the Policy tab. To associate a new or existing policy with the HTTP Receiver activity, click the Add Policy to Activity icon. To edit policy details, click Go to selected Policy icon. The Policy tab has the following fields.

Field Description
Name The name of the policy.
Type The type of policy associated with the activity. The HTTP Receiver activity can support the Basic Authentication policy.
Description A description of the policy.