Copyright © Cloud Software Group, Inc. All Rights Reserved

HTTP Receiver

Process Starter

Starts a process based on the receipt of a HTTP request.

Configuration

The Configuration tab has the following fields.

Field	Global Var?	Description
Name	No	The name to appear as the label for the activity in the process definition.
Description	No	Short description of the activity.
HTTP Connection	No	The HTTP Connection resource describes the characteristics of the connection used to receive incoming HTTP requests. See HTTP Connection for more information about specifying shared resources.
Output Style	No	Type of output. Can be either String or Binary.
Parse Post Method Data	No	Specifies to parse the message body of the HTTP request into a schema for the activity’s output. 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. Note: In the case of an incoming GET request, there is no message body, so this field has no effect on incoming GET requests.
Parameters	No	The parameters of the incoming HTTP request. Specifying parameters in this table allows the incoming request to be parsed and represented as a schema in this activity’s output. For each parameter, you must provide a name, datatype, and whether the field is required, optional, or repeating. Use the + and x buttons to the right of the parameter table to add and remove parameters. Use the up and down arrows to move parameters to new positions in the table. 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 field is checked. Checking the Parse Post Method Data field and specifying parameters here is required to parse the message body along with the query string of the request.
HTTP Authentication	No	Specifies that the client sending the HTTP request must be authenticated. The user name and password specified in the incoming request must exist in the domain. Users are created and managed in the domain using TIBCO Administrator.
Expose Security Context	No	Places the information from the user’s security context (either authentication or SSL certificate information) into the Context/SecurityContext output element. This is a fairly expensive operation and SSL certificates can consume memory resources, so check this option only if you require information from the user’s security context for later use in your process definition.
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 Connection shared resource, the Default Encoding parameter specified here applies to the contentType alone and not to the URIEncoding property.
Upgrade Configuration	No	This field is available only when projects created in BusinessWorks 5.2.x or earlier versions are migrated to a higher version. Selecting the check box upgrades the schema in the input/output tab for the activity. You can revert back to the old schema by clearing the check box. However, if you create new processes in the older projects, the activities will always show the new schema in their input/output tabs. In this case, it is not possible to revert to the old schema.

Advanced

The Advanced tab contains the following fields:

Field	Global Var?	Description
Write to File	No	Checking this field specifies to write incoming requests that exceed the specified threshold size to a file instead of storing the request in memory. This allows you to accept large incoming requests without consuming a great deal of memory. When this field is checked, the Directory and Threshold Size fields appear. Note: This option is not intended to be used with the Parse Post Method Data option on the Configuration tab. When Write to File is specified, the PostData output element becomes a choice element containing either the output FileName or the PostData depending upon whether the data exceeds the size specified in the Threshold 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. Leaving this field unchecked specifies to keep incoming requests in memory. Note: Once written, the files created by 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	Create Non-Existing Directories
Threshold Size (bytes)	Yes	The maximum size (in bytes) of an incoming request that can be kept in 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 definition can access the file and read its contents. Specifying zero (0) in this field causes all incoming requests to be saved to a file.

Misc

The Misc tab contains the following fields:

Field	Description
Sequencing Key	This field can contain an XPath expression that specifies which processes should run in order. Process instances with sequencing keys that evaluate to the same value will be executed sequentially in the order the process instance was created. See TIBCO ActiveMatrix BusinessWorks Process Design for more information about controlling the execution order of process instances and about XPath expressions.
Custom Id	This field can contain an XPath expression that specifies a custom ID for the process instance. This ID is displayed in the View Service dialog of TIBCO Administrator, and it is also available in the $_processContext process variable.

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 is unchecked on the Configuration 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 into the PostData output element, and that element would appear as follows:

 

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

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

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

See http://www.rfc-editor.org/rfc/rfc1738.txt for more information about the URL specification.

Output Headers

The Output Headers 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. This tab uses the mechanism described in Appendix A, Specifying Data Schema to specify the data structure for the headers. See that appendix for more information about creating a customized data structure.

Header structure is defined by the HTTP protocol. See the HTTP Protocol specification for more information about the fields and content of the header of a HTTP request. You can obtain this specification at www.w3.org.

The default header fields are the following.

Header	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. If no Accept header field is present, then 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. If no Accept-Charset header is present, then 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. See the HTTP specification for more information about this header field.
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.
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. See Special Characters in HTTP Requests for more information on when the message body is URL encoded.
Connection	string	This field allows the requestor to specify options desired 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	See the HTTP specification for more information about this field. If you want to receive more than one cookie, set the Cardinality for this field to Repeating (*).
Pragma	string	This field is used to include implementation-specific directives that might apply to the receiver. See the HTTP specification for more information about using this field.

Output

The output for the activity is the following.

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	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 Configuration tab. See Special Characters in HTTP Requests for more information. If the Write to File field is checked on the Advanced tab, this field can also contain the file name of the file containing the message, if the incoming message exceeds the specified threshold size.
Command	string	Command portion of the HTTP request.
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.
DynamicHeaders	complex	The dynamic header is an additional header parameter to add runtime headers to the Outgoing Http Messages. This element is specified in the Input tab. Dynamic header consists of the following information: • Name — name of the header. • Value — 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 throws the following exception: "The header [ headerName ] is defined as non-Repeating Header in Input Headers. This header cannot have multiple occurences in DynamicHeaders." • If it is repeating element, add the respective name value pairs under dynamic headers, which will be added to the existing list maintained for this element. • For a repeating element, if the new header name is not found under Headers section declared via TIBCO Designer, 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.
Protocol	string	Can be either HTTP or HTTPS depending upon the protocol used by the request.
Port	string	Port number on which the request was received. This is the port number configured in the HTTP Connection resource.
mimeEnvelope Element	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 choose to ignore the suggested name. • content-type • content-transfer-encoding • content-id • other mime header information See http://www.faqs.org/rfcs/rfc2045.html for more information about MIME headers and their syntax. 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 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.
Headers	complex	The fields of the header specified on the Output Headers tab. See the description of the Output Headers tab for more information about these items.
parameters	complex	Parameters for the incoming request. These parameters are configured in the Parameters field on the Configuration tab. When the Parse Post Method Data field on the Configuration tab is checked, the parameters include the parameters in the query string and message body of the incoming HTTP request. When the Parse Post Method Data field is unchecked, the parameters only include the query string of the incoming request.
Context	complex	Contains information about the client’s environment. See the description of the following elements contained in the Context element for more information.
RemoteAddress	String	The IP address of the client that submitted the HTTP request.
Context	complex	This element holds the optional SecurityContext element and the RemoteAddress and RemoteHost elements described below.
SecurityContext	complex	This output element is only available when the Expose Security Context field is checked on the Configuration tab. This element contains information about the requestor’s authentication or certificate information, depending upon the security scheme used. See the description of the following elements contained in the SecurityContext element for more information.
Username PasswordToken	complex	The username and password of the HTTP client that made the request. The elements in this element are populated only when the client uses HTTP authentication.
CertificateToken	complex	This element contains the SSL certificate and certain useful information taken from the certificate, such as the CipherSuite, the certificate issuer, and so on. If the client has more than one certificate in a certificate chain, all certificates are contained in the repeating Certificate element.
RemoteAddress	String	IP address of the remote host that sent the HTTP request.
RemoteHost	String	Host name of the remote host that sent the HTTP request. This element is only available when the Enable DNS Lookups field is checked on the Advanced tab of the HTTP Connection used by this activity.

Copyright © Cloud Software Group, Inc. All Rights Reserved