Copyright © Cloud Software Group, Inc. All Rights Reserved

Send HTTP Request

Activity

The Send HTTP Request activity sends a HTTP request to a web server.

This activity can send a request to a server that complies with either the HTTP 1.0 or 1.1 specification. You do not need to specify the HTTP version of the server you are sending the request to. TIBCO ActiveMatrix BusinessWorks automatically sends the request using the correct version based on the version supported by the HTTP server.

Configuration

The Configuration tab has the following fields.

Field	Description
Name	The name to appear as the label for the activity in the process definition.
Description	Short description of the activity.
Host	The host machine name or IP address to send the request to. For example, www.tibco.com.
Port	The port on the host machine to send the request to. The default port is 80.
Use Proxy Setting	Specifies to use a proxy server to gain access outside of a firewall. The Proxy Configuration shared configuration resource specifies the configuration of the proxy server. See Proxy Configuration for more information.
Accept Redirects	Checking this field indicates that the request should be automatically redirected when the HTTP server sends the redirection status code (302) in response to this request and the remote host redirects the request to the same host and port. If the remote host redirects the request to a different host or a different port on the same host, the request is not automatically redirected. The maximum number of redirections is 100. When this field is unchecked, the request is not redirected.
Parameters	The parameters of the HTTP request. For each parameter, you must provide a name, datatype (must be type string), and whether the parameter is required, optional, or repeating. These parameters are specified in the parameters element on the Input tab. See Sending Data in the HTTP Request for more information about this field.
HTTP Authentication	Specifies what authentication should be used . An authentication can be of the following three types: • NONE - is default. • BASIC - to continue with the current implementation of using username and password credentials. The Identity field appears when this field is enabled. • NTLM - Identity and Domain fields appear when NTLM is selected. Identity is a reference of the Username and Password combination.
Identity	This is an Identity resource that contains the client’s username and password. This identity is used to perform only Basic and NTLM authentication. See TIBCO Designer Palette Reference for more information.
Domain	Specifies the domain to be used for Authentication. The username and password specified in the Identity must exist in the domain.
SSL	When the Use SSL? check box is checked, this specifies to use the HTTPS (secure socket layer, or SSL) for the request. This protocol authenticates the server to the client, and optionally, the server can require that the client authenticate itself to the server. The Configure SSL button becomes enabled when this field is checked. See Configure SSL Button for more information.
Upgrade Configuration	This field is visible 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.

Sending Data in the HTTP Request

There are several HTTP methods that can be used in an HTTP request. Each method sends data in the request in a different manner. For example, the GET method uses the query string of the request URI to pass parameter/value pairs. Other methods use the HTTP message body to send data in the request.

The Send HTTP Request activity has three input elements for sending data in a request:

•	PostData — corresponds to the body of the HTTP message. All methods except the GET method accept data in this element.

•	QueryString — corresponds to the query string of the request URI. You can use this input element to dynamically construct the query string using an XPath expression when you do not know the names or number of input parameters for the request until the activity executes.

•

Parameters — corresponds to parameters defined in the Parameters field on the Configuration tab. This is useful if you have a fixed set of parameters that you send with the request. For requests that use the GET method, these parameters are passed as the query string of the request URI. For requests that use the POST method, these parameters are usually sent as the body of the HTTP message, but they can also be included in the query string.

For some methods, these input elements are mutually exclusive. For example, for POST requests, you can specify parameters on the Configuration tab and in the parameters input element or you can specify a PostData input element. However, you should not specify both input elements. In the case of a POST request, the PostData input element is ignored when parameters are specified on the Configuration tab.

For GET requests, you can specify parameters on the Configuration tab and in the parameters input element or you can specify a QueryString input element. Typically, if you know the list of parameters for the request, you should configure the parameters on the Configuration tab. If the list of parameters is not known until the activity executes, you should use the QueryString element. However, when all parameters on the Configuration tab are specified as Optional, you can use the QueryString input element instead of the parameters input element (but if any elements in the parameters element contain an expression, the QueryString element is ignored).

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. If this is the case and you want to send special characters such as +, /, or = in your HTTP request, your data string must be URL-encoded if you send the data using the PostData or QueryString input elements. If you send the data using the parameters specified on the Configuration tab, encoding is done automatically.

For example, you want to specify the following PostData:

 

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

Your PostData input element should result in the following string:

 

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

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

Configure SSL Button

The Configure SSL button allows you to specify the SSL parameters for the HTTP request. The following are the fields in the SSL Configuration for HTTPS Client Requests dialog:

Field	Description
Trusted Certificates Folder	Folder in the project containing one or more certificates from trusted certificate authorities. This folder is checked when a client connects to the HTTP server to ensure that the server is trusted. This prevents connections to rogue servers.
Identity	This is an Identity resource that contains the client’s digital certificate and private key. See TIBCO Designer Palette Reference for more information.
Verify Host Name	This field specifies to check the host name of the HTTP server against the host name listed in the server’s digital certificate. This provides additional verification that the host name you believe you are connecting to is in fact the desired host. If the host name specified in the Host field on the Configuration tab is not an exact match to the host name specified in the server’s digital certificate, the connection is refused. Note: If you specify an equivalent hostname (for example, an IP address) in the Host field, but the name is not an exact match of the hostname in the host’s digital certificate, the connection is refused.
Strong Cipher Suites Only	When checked, this field specifies that the minimum strength of the cipher suites used can be specified with the bw.plugin.security.strongcipher.minstrength custom engine property. See TIBCO ActiveMatrix BusinessWorks Administration for more information about this property. The default value of the property disables cipher suites with an effective key length below 128 bits. When this field is unchecked, only cipher suites with an effective key length of up to 128 bits can be used.

 

Server Name Indication (SNI) is available only when the security provider is J2SE and is enabled by default with this provider. Set the property jsse.enableSNIExtension to false to disable the SNI extension.

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.

Input Headers/Output Headers

The Input Headers and Output Headers tabs describe the data structure for the headers of the HTTP request and the HTTP reply message. You can use the default structure, or you can alter the structure, if the outgoing request or the reply to the request has a specific data structure for the header. This tab uses the same mechanism described Appendix A, Specifying Data Schema to specify the data structure for the headers. See that section 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 (input header)	string	This field specifies media types that are acceptable for response messages for the request. For example, text/*,text/html. Media types are described in the HTTP specification. If no Accept header field is specified, then the server assumes that all media types are acceptable.
Accept-Charset (input header)	string	This field specifies the character sets that are acceptable for response messages for the request. For example, iso-8859-5, unicode-1-1. Character sets are described in the HTTP specification. If no Accept-Charset header is specified, then the server assumes that any character set is acceptable.
Accept-Encoding (input header)	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 (input/output header)	string	This field indicates the media type of the entity body for the outgoing message and the incoming response. Media types are described in the HTTP specification. An example of the media type is text/html; charset=ISO-8850-4.
Content-Length (output header)	string	This field indicates the size of the entity body (in decimal number of OCTETs) of the response message.
Content-Encoding (output header)	string	This field is used as a modifier to the content-type. When present, its value indicates what additional content encodings have been applied to the entity-body, and thus what decoding mechanisms must be applied in order to obtain the media-type referenced by the Content-Type header field. Content-Encoding is primarily used to allow a document to be compressed without losing the identity of its underlying media type. See the HTTP specification for more information about this field.
Date (output header)	string	The date and time when the response message was sent.
Server (output header)	string	The server sending the original response message.
Location (output header)	string	This field is used to redirect the receiver to a location other than the Request-URI for completion of the request or for identification of a new resource.
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.
Set-Cookie (output header)	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 (*).
Cookie (input header)	string	A name/value pair (also known as a cookie) containing information that the HTTP server may be expecting. You can set the Cardinality field for this element to Repeating (*) to specify more than one cookie. You can also specify multiple name/value pairs in a single non-repeating element by separating each pair with a comma (for example, "name1=value1, name2=value2"). If you set the custom engine property bw.plugin.http.protocol.single-cookie-header to true, multiple name/value pairs are sent as a single header element. See TIBCO ActiveMatrix BusinessWorks Administration for more information about custom engine properties.
Pragma (input/output header)	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.

Input

See TIBCO ActiveMatrix BusinessWorks Process Design for more information about mapping and transforming input data.

The input for the activity is the following.

Input Item	Datatype	Description
Host	string	The HTTP host you want to connect to. Specifying a value for this input item overrides any value specified on the Configuration tab.
Port	integer	The port number that the HTTP server uses for incoming requests. Specifying a value for this input item overrides any value specified on the Configuration tab.
Method	string	The HTTP method to use for the request. All HTTP 1.1 methods are supported, but the CONNECT method is unnecessary because TIBCO ActiveMatrix BusinessWorks automatically uses the connect method when connecting by way of a proxy server. If no method is specified in this element, the GET method is used by default.
RequestURI	string	The address portion of the request. This is the portion of the URI before the question mark (?).
PostData	string	The message body of the HTTP request. Do not specify this element when the method of the request is GET. See Sending Data in the HTTP Request for more information about this input element.
QueryString	string	The query string portion of the request. This is the portion after the question mark (?). See Sending Data in the HTTP Request for more information about this input element.
Timeout	integer	The amount of time (in milliseconds) to wait for a response from the HTTP server.
Headers	complex	The header fields to send for the request. This element is specified on the Input Headers tab, and you can use this input item to supply values for the header when sending the 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.
parameters	complex	Parameters for the incoming request. These parameters are configured in the Parameters field on the Configuration tab. This element is only available when there are items specified in the Parameters field. See Sending Data in the HTTP Request for more information about this input element.
mimeEnvelope Element	complex	This element contains the message attachments. This element contains a repeating element named mimePart that contains each mime attachment. Note: Only HTTP POST method can send messages with attachments.
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. • textConetnt — content of the attachment when the attachment is text data. • fileName — the file name of the attachment written to the disk.

Output

The output for the activity is the following.

Output Item	Datatype	Description
Header	string	The header of the HTTP request.
statusLine	complex	This field is the first line of the response message. This consists of the protocol version, a numeric status code, and the text phrase explaining the status code. See the HTTP specification for more information about status codes in HTTP responses.
binaryContent	binary	The binary content of the response to the request from the HTTP server.
asciiContent	string	The ASCII content of the response to the request from the HTTP server.
Headers	complex	The header fields of the reply. The structure of this output item is specified on the Output Headers tab.
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.
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. • textConetnt — content of the attachment when the attachment is text data. • fileName — the file name of the attachment.

Persistent Connections

A Send HTTP Request activity requires a connection to the HTTP server. The activity exclusively uses the connection until the HTTP server sends the response message. If you have many process instances connecting to a HTTP server, each Send HTTP Request opens a connection, holds the connection, and then closes the connection when the activity completes. Opening and closing a large number of connections causes a significant overhead. Persistent connections play a major role here. Persistent connections maintain a pool of connections that can be reused by Send HTTP Request activities so that each activity does not need to open and close the connection. Once the connection is released by the process instance, it is returned to the pool maintained.

Not all HTTP servers support the use of persistent connections. To determine if the HTTP Server supports the use of persistent connections, read the documentation of that HTTP Server.

Figure 10 illustrates the persistent connection pool.

Persistent Connection Manager allows you to specify the total number of connections as well as the maximum number of connections per HTTP Server. The total number of connections is a total of connections to all HTTP Servers handled by that connection pool.

For each SSL configuration, a different Persistent Connection pool is created and maintained. All connections using the same SSL Configuration, irrespective of the HTTPS Server they are connecting to, is maintained by this pool.

When a Send HTTP Request activity requires a connection, the pool is requested for a connection that corresponds to the HTTP server. If an idle connection for that HTTP Server is found, it is used. If no idle connection is found, the pool tries to create one depending on whether the maximum connections limit for that HTTP Server has been reached. If the maximum connections limit is reached, the request waits for a connection to be released back to the pool. If the maximum connections limit is not reached, the pool creates a connection to use.

Figure 10 Persistent HTTP Connection Pool

Persistent connections are managed by custom engine properties. See TIBCO ActiveMatrix BusinessWorks Administration for more information about setting custom engine properties.

The following section describe the engine properties that control persistent connections.

bw.plugin.http.client.usePersistentConnectionManager

This property specifies that a pool of HTTP connections to each HTTP server must be created for the connections to be reused by the Send HTTP Request activities. This property enables persistent connections for all non-SSL Send HTTP Request in that ActiveMatrix BusinessWorks engine.

When this property is set to true, a pool of connections is created for each HTTP server that Send HTTP Request connects to. The total number of connections in the pool is limited by the bw.plugin.http.client.maxTotalConnections property. The number of connections for each host (each HTTP server) is limited by the bw.plugin.http.client.maxConnectionsPerHost property.

The default value of this property is false.

bw.plugin.http.client.usePersistentConnectionManagerForSSL

This property specifies that a pool of HTTPS connections to each HTTP server must be created for connections to be reused by the Send HTTP Request activities. This property enables persistent connections for all SSL Send HTTP Request in that ActiveMatrix BusinessWorks engine.

When this property is set to true, a pool of connections is created for each HTTPS server that Send HTTP Request connects to. The total number of connections in the pool is limited by the bw.plugin.http.client.maxTotalConnections property. The number of connections for each host is limited by the bw.plugin.http.client.maxConnectionsPerHost property.

The default value of this property is false.

SSL Configuration - consists of Trusted Certificates folder, Identity, verifyHostName flag, and strongCipherSuites flag. NTLM Authentication Configuration - consists of Identity and domainName. Different connections pools get created for the following combinations: • HTTP • HTTP and NTLM • HTTPS (using SSL) and NTLM • HTTPS (using SSL) All persistent connection properties like maxTotalConnections, maxConnectionsPerHost, idle connections check, and timeout value are applied on each connection pool.

To enable Persistent Connections for both HTTP and HTTPS, set bw.plugin.http.client.usePersistentConnectionManager and bw.plugin.http.client.usePersistentConnectionManagerForSSL properties to true.

Define the engine property bw.plugin.http.client.authentication.preemptive to False, if you don’t need the preemptive authentication applied for the HTTP Requests. The default value of this property is True.

bw.plugin.http.client.connectionTimeout

The value of this property is ignored unless the bw.plugin.http.client.usePersistentConnectionManager or bw.plugin.http.client.usePersistentConnectionManagerForSSL property is set to true. This property specifies that the timeout period (in milliseconds) for which persistent connections should be alive to each remote HTTP server.

The default value of this property is 3000 ms.

bw.plugin.http.client.maxConnectionsPerHost

The value of this property is ignored unless the bw.plugin.http.client.usePersistentConnectionManager or bw.plugin.http.client.usePersistentConnectionManagerForSSL property is set to true. This property specifies the maximum number of persistent connections to each remote HTTP server.

The default value of this property is 20.

bw.plugin.http.client.maxTotalConnections

The value of this property is ignored unless the bw.plugin.http.client.usePersistentConnectionManager or bw.plugin.http.client.usePersistentConnectionManagerForSSL property is set to true. This property specifies the maximum number of persistent connections for all HTTP servers.

The default value of this property is 200.

bw.plugin.http.client.checkForStaleConnections

The value of this property is ignored unless the bw.plugin.http.client.usePersistentConnectionManager or bw.plugin.http.client.usePersistentConnectionManagerForSSL property is set to true. When using persistent connections, a connection can become stale. When this property is set to true, a persistent connection is checked to determine if it is stale before it is used by a Send HTTP Request activity. Checking for the stale connections adds significant processing overhead, but it improves reliability.

The default value of this property is false.

Error Output

The Error Output tab lists the possible exceptions that can be thrown by this activity. See TIBCO ActiveMatrix BusinessWorks Error Codes for more information about error codes and corrective actions to take.

Exception	Thrown When...
HttpClientException	The HTTP server replied with a message that has the 4XX status code.
HttpServerException	The HTTP server replied with a message that has the 5XX status code.
HttpCommunicationException	An HTTP exception occurred when trying to execute the specified method, or when trying to read the response.
ActivityTimedOutException	A timeout has been reached.

Copyright © Cloud Software Group, Inc. All Rights Reserved