HTTP Client

The HTTP Client communication point is used to make requests to remote HTTP servers and allow remote resources to be accessed using the HyperText Transfer Protocol (HTTP). Refer to Published Properties for a list of properties associated with this communication point.

The HTTP Client communication point does not support pre-emptive authentication.

Supported Operational Modes: Input, Output, Out->In.

Operational Modes

Input Mode - the HTTP Client communication point sends a request to the HTTP server at regular intervals. If the server response includes a success code, the content of the response forms the body of the Rhapsody message to be processed by the engine.
Output Mode - The HTTP Client communication point sends a request to the HTTP server when it receives a message from the Rhapsody engine. The HTTP Client communication point's Message Content configuration property determines the content of the HTTP request that is sent to the HTTP server.
Out→In Mode - The HTTP Client communication point sends a request to the HTTP server when it receives a message from the Rhapsody engine. If the server response includes a success code, the content of the response forms the body of the message to be processed by the engine.

TLS/SSL Support

For details on Transport Layer Security/Secure Sockets Layer (TLS/SSL) support in Rhapsody, refer to TLS/SSL Support in Rhapsody.

Configuration Properties

Input Mode Properties

Property	Description
URL	The URL of the resource to get. It should specify HTTP as the protocol and contain the name of the server and the path of the resource, for example: http://rhapsody.orionhealth.com/eap/login.jsp It may include request parameters followed by `?`, for example: http://rhapsody.orionhealth.com/eap/login.jsp?user=lee&password=abc The URL can also be a message property when running in Output or Out->Inmode which enables you to direct the message dynamically based on the message content.
HTTP Method	The HTTP Method for the URL request. Rhapsody currently supports `GET`, `POST`, `HEAD`, `OPTIONS`, `PUT`, `DELETE`, `TRACE` and `AUTO` methods. `GET` and `POST` are commonly used. If `AUTO` is selected, the Client will use the method set by the HTTP server, if a method is not found `GET` is used.
Request Headers	A list of request header names and the values to be mapped that enable you to put custom properties into an HTTP header. They can come from message properties or literals. Use the `$MessageProperty` notation to specify that the actual value should be retrieved from a message property.
Follow Redirects	Sets whether HTTP redirects (requests with response code 3xx) should be automatically followed: Enabled. Disabled (default) - if this property is disabled and the server response indicates a redirect of the request, an error will be generated.
Use HTTPS	Whether to use the secure HTTP protocol (HTTPS) over the connection. It is recommended that HTTPS be enabled for HTTP Client communication points whenever it is supported by the remote server. Enabled. Disabled (default). Refer to TLS/SSL Support in Rhapsody for details on TLS/SSL (Transport Layer Security/Secure Sockets Layer) support in Rhapsody.
SSL Protocol Mode	Refer to SSL Protocol Versions for details.
SSL Cipher Suites	Refer to SSL Cipher Suites for details.
Trusted Certificates	List of trusted certificates to use for authenticating the HTTPS server. This option is only available if Use HTTPS is enabled. If one or more certificates are configured in this property then the certificate presented by the server must either match one of the configured certificates, or have been signed by one of the configured certificates. If no certificates are configured in this property then the certificate presented by the server must have been signed by a trusted certificate authority. Refer to Server Authentication for details.
Secure Keys	List of private keys used for HTTPS client authentication if this is required by the HTTPS server. If HTTPS client authentication is enabled, the HTTP Client Communication Point will present the certificate associated with this private key during the TLS negotiation, allowing the server to authenticate the client. This option is only available if Use HTTPS is enabled. Optional but can be configured with the HTTPS client's private key. Refer to Client Authentication for details.
Hostname Verification	Whether to enable or disable hostname verification: `Enable` (default). `Disable`. Hostname verification is a server authentication security mechanism. It ensures that the hostname specified in the certificate presented by the server is the same as the hostname specified in the URL property above. If the hostnames are different, the connection attempt will fail. The exception to this is where the remote server is, in fact, the localhost. Setting this property to `Disable` means that the hostname used to connect to the HTTPS server is not verified against the expected hostnames included in the server's SSL certificate, however, the server's certificate is still authenticated against the Trusted Certificates configuration property. This is a weakening of the security provided by server-authenticated SSL. We strongly recommend being fully aware of the risks involved before making the decision to disable hostname verification. If you are unsure of the potential consequences, we recommend leaving verification enabled. This option cannot be disabled if the trusted certificate authorities are being used to validate the certificate presented by the server (in other words, the Trusted Certificates configuration property has not been explicitly set).
HTTP Authentication Username	The username to send if the server requires basic or digest authentication. This can be set as either a literal, a Rhapsody variable (using the `$(variableName)` notation), or a Rhapsody message property (using the `$propertyName` notation).
HTTP Authentication Password	The password to send if the server requires basic or digest authentication. This can be set as either a literal, a Rhapsody variable (using the `$(variableName)` notation), or a Rhapsody message property (using the `$propertyName` notation). As message properties are visible in the Management Console to users with the appropriate access right, it is recommended that passwords provided in message properties are kept in their obfuscated form. If those passwords are retrieved via Rhapsody variables using JavaScript, then the retrieval functions can leave them in this format - refer to Encrypted Rhapsody Variables for details. If those passwords are provided as literals elsewhere in the configuration, then the Encrypt Password function in the Rhapsody IDE can be used.
Protocol Support	Identifies the level of support for application-level protocols which use HTTP: `Standard HTTP Only` (default). `SOAP Support`. `ebXML Support`. When Protocol Support is set to `SOAP Support`, if the `soap:soapAction` property is present in the incoming message, the HTTP Client communication point uses the `soap:soapAction` property to determine the `SOAPAction` request header for outgoing HTTP messages. If the `soap:soapAction` property is not present in the incoming message, the communication point generates the property in the outgoing message, setting it by default to an empty string (`""`). When Protocol Support is set to `ebXML Support`, the communication point extracts the `eb:SOAPAction` property from incoming messages if present, or generates the property in outgoing messages with a default value of `ebXML`.
Read Timeout (ms)	How long to wait (in milliseconds) when trying to read a response from the server.
Connect Timeout (ms)	How long to wait (in milliseconds) when trying to connect to a server.
Proxy Type	The proxy type for this connection: `System` (default) - use any proxy settings configured on the JVM or host computer. `None/Direct`. `HTTP`. `SOCKS`.
Proxy Hostname	The proxy hostname. Use the `$propertyName` notation to specify that the proxy hostname should be retrieved from a message property.
Proxy Port	The proxy port. Use the `$propertyName` notation to specify that the proxy port should be retrieved from a message property.
Proxy HTTP Authentication Username	The username to send if the proxy server requires basic or digest HTTP authentication. Use the `$propertyName` notation to specify that the proxy username should be retrieved from a message property.
Proxy HTTP Authentication Password	The password to send if the proxy server requires basic or digest HTTP authentication. Use the `$propertyName` notation to specify that the proxy password should be retrieved from a message property.
Refresh Rate	Specifies the frequency (in milliseconds) that the URL request is sent to the HTTP server at the location specified in the URL configuration property. This property is optional with a default value of `60000ms` (1 minute).
Set If-Modified-Since header	`Whether to set the If-Modified-Since header:` Enabled - communication point will save the time when the received message was modified (part of the HTTP response header obtained from the HTTP server) and use it to retrieve the next message only if it was modified after the previous message. Another way to look at it is a conditional GET method based on the modification time of the content. Disabled (default).
Response Headers	A list of headers to be read from the incoming HTTP response messages and the corresponding message properties to which the header values should be written.

Output Mode Properties

Property	Description
URL	The URL of the resource to get. It should specify HTTP as the protocol and contain the name of the server and the path of the resource, for example: http://rhapsody.orionhealth.com/eap/login.jsp It may include request parameters followed by `?`, for example: http://rhapsody.orionhealth.com/eap/login.jsp?user=lee&password=abc
HTTP Method	The HTTP method for the URL request. Rhapsody currently supports `GET`, `POST`, `HEAD`, `OPTIONS`, `PUT`, `DELETE`, `TRACE` and `AUTO` methods. If `AUTO` is selected, the Client uses the method set by the HTTP server; if a method is not found, `GET` is used.
Request Headers	A list of request header names and the values to be mapped. Use the `$MessageProperty` notation to specify that the actual value should be retrieved from a message property.
Follow Redirects	Sets whether HTTP redirects (requests with response code 3xx) should be automatically followed: Enabled. Disabled (default) - if this property is disabled and the server response indicates redirect the request, an error will be generated.
Use HTTPS	Whether to use the secure HTTP protocol (HTTPS) over the connection. Enabled. Disabled (default).
SSL Protocol Mode	Refer to SSL Protocol Versions for details.
SSL Cipher Suites	Refer to SSL Cipher Suites for details.
Trusted Certificates	List of trusted certificates to use for authenticating the HTTPS server. This option is only available if Use HTTPS is enabled. If one or more certificates are configured in this property, then the certificate presented by the server must either match one of the configured certificates, or have been signed by one of the configured certificates. If no certificates are configured in this property, then the certificate presented by the server must have been signed by a trusted certificate authority. Refer to Server Authentication for details.
Secure Keys	List of private keys used for HTTPS client authentication if this is required by the HTTPS server. If HTTPS client authentication is enabled, the HTTP Client Communication Point will present the certificate associated with this private key during the TLS negotiation, allowing the server to authenticate the client. This option is only available if Use HTTPS is enabled. Optional but can be configured with the HTTPS client's private key.
Hostname Verification	Options: `Enable`, `Disable`. Default: `Enable`. Whether to enable or disable hostname verification. Hostname verification is a server authentication security mechanism. It ensures that the hostname specified in the certificate presented by the server is the same as the hostname specified in the URL property above. If the hostnames are different, the connection attempt will fail. The exception to this is where the remote server is, in fact, the localhost. Setting this property to `Disable` means that the hostname used to connect to the HTTPS server is not verified against the expected hostnames included in the server's SSL certificate, however, the server's certificate is still authenticated against the Trusted Certificates configuration property. This is a weakening of the security provided by server-authenticated SSL. We strongly recommend being fully aware of the risks involved before making the decision to disable hostname verification. If you are unsure of the potential consequences, we recommend leaving verification enabled. This option cannot be disabled if the trusted certificate authorities are being used to validate the certificate presented by the server (in other words, the Trusted Certificates configuration property has not been explicitly set).
HTTP Authentication Username	The username to send if the server requires basic or digest authentication. This can be set as either a literal, a Rhapsody variable (using the `$(variableName)` notation), or a Rhapsody message property (using the `$propertyName` notation).
HTTP Authentication Password	The password to send if the server requires basic or digest authentication. This can be set as either a literal, a Rhapsody variable (using the `$(variableName)` notation), or a Rhapsody message property (using the `$propertyName` notation). As message properties are visible in the Management Console to users with the appropriate access rights, it is highly recommended that you encrypt passwords provided in this message using the Encrypt Password function in the Rhapsody IDE. Alternatively, you can use Configuration Templates, which do not require providing the password in a message property. If the passwords are retrieved from a Rhapsody variable using JavaScript, then the retrieval functions can leave them in this format. Refer to Encrypted Rhapsody Variables for details.
Protocol Support	Identifies the level of support for application-level protocols which use HTTP: `Standard HTTP Only` (default). `SOAP Support`. `ebXML Support`. When Protocol Support is set to `SOAP Support`, if the `soap:soapAction` property is present in the incoming message, the HTTP Client communication point uses the `soap:soapAction` property to determine the `SOAPAction` request header for outgoing HTTP messages. If the `soap:soapAction` property is not present in the incoming message, the communication point generates the property in the outgoing message, setting it by default to an empty string (`""`). When Protocol Support is set to `ebXML Support`, the communication point extracts the `eb:SOAPAction` property from incoming messages if present, or generates the property in outgoing messages with a default value of `ebXML`.
Read Timeout (ms)	How long to wait (in milliseconds) when trying to read a response from the server.
Connect Timeout (ms)	How long to wait (in milliseconds) when trying to connect to a server.
Proxy Type	The proxy type for this connection: `System` (default) - use any proxy settings configured on the JVM or host computer. `None/Direct`. `HTTP`. `SOCKS`.
Proxy Hostname	The proxy hostname. Use the `$propertyName` notation to specify that the proxy hostname should be retrieved from a message property.
Proxy Port	The proxy port. Use the `$propertyName` notation to specify that the proxy port should be retrieved from a message property.
Proxy HTTP Authentication Username	The username to send if the proxy server requires basic or digest HTTP authentication. Use the `$propertyName` notation to specify that the proxy username should be retrieved from a message property.
Proxy HTTP Authentication Password	The password to send if the proxy server requires basic or digest HTTP authentication. Use the `$propertyName` notation to specify that the proxy password should be retrieved from a message property.
Message Content	This property selects what to put as the content of the HTTP request that is sent to the HTTP server: `None`. `Message Body` (default). `www-form-urlencoded`. `Message Body` and `www-form-urlencoded` are only valid for `POST` and `PUT` methods. For all other methods, this property should be set to `None`.
Content Type	The MIME type of the HTTP response body contained in the body of the returned message, for example: text or image. Refer to File Naming Options for details on using a route's published properties or a Rhapsody variable as the value for this property. This property is only available if Message Content is set to `Message Body`. The default is `text/plain`.
Content Encoding	The MIME encoding (character set) used to encode the message content. Only available if Message Content is set to `Message Body`. Refer to File Naming Options for details on using a route's published properties or a Rhapsody variable as the value for this property.
Definition File	Message definition which is used to parse and extract fields from the message that comes into the communication point from a Rhapsody route.
Additional Request Headers	A list of name-value pairs, where for each pair the name is an HTTP request parameter and the value is the value for the parameter extracted from the incoming message.
Request Parameters	A list of name-value pairs, where for each pair name is an HTTP request parameter and value is the value for the parameter extracted from the incoming message. value can be a literal value, or a message property (for example, using `$propertyName` sets value to the value of the message property `propertyName` in the incoming message). These pairs are encoded into the URL part of the HTTP request.
Form Names and Values	A list of name-value pairs which will be encoded into the content of the request, where for each pair value is extracted from the incoming message. value can be a literal value, or a message property (using `$propertyName` sets value to the value of the message property `propertyName` in the incoming message). This configuration property is available only if Message Content property is set to `www-form-urlencoded`, and the option is only valid for `POST` and `PUT` methods.
On 4xx Error Response	Sets an action for the incomplete HTTP client request errors (4xx errors): `Mark as connection failed` (default) - the settings in Connection Retries of the Connection tab of the communication point's properties are applied. `Treat as message error` - the original message is re-routed via the communication point's error output connector. However, if the error output connector is not connected to other components, the message is sent to the Error Queue. `Return message as input` - the message itself becomes the received data. `Return error content as input` - the content of the error message becomes the received data. `Mark connection as timed out` - the settings in the Out->In Properties of the Connection tab of the communication point's properties are applied.
On 5xx Error Response	Sets an action for the HTTP server errors (5xx errors): `Mark as connection failed` (default) - the settings in Connection Retries of the Connection tab of the communication point's properties are applied. `Treat as message error` - the original message is re-routed via the communication point's error output connector. However, if the error output connector is not connected to other components, the message is sent to the Error Queue. `Return message as input` - the message itself becomes the received data. `Return error content as input` - the content of the error message becomes the received data. `Mark connection as timed out` - the settings in the Out->In Properties of the Connection tab of the communication point's properties are applied.
Dynamic Connection Failed Action	Sets an action for a connection error or socket timeout when the host uses message properties: `Mark as connection failed` - the settings in Connection Retries of the Connection tab of the communication point's properties are applied. `Treat as message error` (default) - the original message is re-routed via the communication point's error output connector. However, if the error output connector is not connected to other components, the message is sent to the Error Queue. `Return message as input` - the message itself becomes the received data. `Return error content as input` - the content of the error message becomes the received data. `Mark connection as timed out` - the settings in the Out->In Properties of the Connection tab of the communication point's properties are applied.
Copy headers	When a message is received in the HTTP client the HTTP headers are copied onto message properties in lower case with the prefix `http:`. If Copy Headers is enabled, these HTTP headers can be copied to the request message using regular expressions to match the HTTP header names.
Regular expressions	The list of regular expressions to match the HTTP headers and actions (Copy to request or Discard) to take. If a regular expression matches an HTTP header it will be copied to the request, or discarded depending on the setting of 'action'. If the header does not match the next regular expression in the list will be tried. If no regular expressions match the header it will be discarded. This communication point supports Java Regex (case insensitive).

Out->In Mode Properties

The configuration properties for the HTTP Client communication point in Out->In mode is a combination of the properties for Input and Output modes.

Refer to Out->In Mode for general details on a communication point's Out->In mode.

Published Properties

Published properties for the HTTP Client communication point are:

Response Code - the status code from the HTTP response status line of the HTTP response which returned this message.
Response Message - the reason phrase from the HTTP response status line of the HTTP response which returned this message.
Content Type - the MIME type of the HTTP response body which is contained in the body of the returned message.
Content Encoding - the MIME encoding (character set) of the HTTP response body which is contained in the body of the returned message.
httpClient:DynamicConnectError - the error type when the HTTP response is not received due to a connection error (CONNECTION_FAILED) or socket timeout (SOCKET_TIME_OUT).
httpClient:DynamicConnectErrorDetail - the error message when the HTTP response is not to received due to a connection error or socket timeout.