webMethods and Intelligent Business Operations 10.2 | Integrating Cloud Applications | Integration Server Built-In Services | Client Folder | pub.client:http
 
pub.client:http
WmPublic. Issues an HTTP request that you specify and returns the HTTP response.
Input Parameters
url
String URL of the resource that you want to access. For example:
http://www.rubicon.com/orders/orders.html
Important: This string must begin with http:// or https://.
method
String Specifies the HTTP method you want to use. Valid values are:
delete
get
head
options
patch
post
put
trace
loadAs
String Optional. Form in which you want the pub.client:http service to store the returned document. Set to:
*bytes to return the body of the response as a byte[ ]. Use this option if the body will be used as input to a service that operates on whole HTML or XML documents (for example, pub.xml:queryXMLNode). This is the default.
*stream to return the body of the response as a java.io.InputStream. Use this option if the document will be used as input to a service that can process documents incrementally (for example, pub.xml:getXMLNodeIterator).
data
Document Data that you want the pub.client:http service to submit with the HTTP request. Specify data using one or more of the following keys.
Important: When you use more than one key, args is appended first, table is appended second, and string is appended last.
Key
Description
args
Document Optional. Name/value pairs that you want this service to submit to the resource in url. You can use args to submit data via the POST, PUT, PATCH, GET, DELETE, or HEAD method.
To specify data using args, create one String element for each name/value pair that you want to submit, where the element's name represents the name portion of the pair and the element's value represents the value portion of the pair.
When you use args, the pub.client:http service will automatically:
*URL-encode name/value pair, so you do not need to URL-encode the values you specify in args.
*Insert the "&" character between pairs, so you do not need to include it in args.
*Prefix the entire query string with the "?" character if it submits the data in args via a GET or HEAD. You do not need to include this character in args.
When you submit data using args, Integration Server automatically sets the value of the Content-Type header to application/x-www-form-urlencoded.
If you want to explicitly specify a different Content-Type value, you must submit the value using the string or bytes variable.
table
String Table Optional. Data that the pub.client:http service will use to construct a query string to submit to the resource specified in url. You can use table to submit data via the POST, PUT, PATCH, GET, DELETE, or HEAD method.
table is similar to args, but it allows you to submit unnamed values in a query string, not just name/value pairs.
To specify data using table, create one row for each value that you want to submit, where the contents of column 0 of the String Table represents the name portion of the pair (leave this column null to submit an unnamed value) and the contents of column 1 represents the value portion of the pair.
When you use table, the pub.client:http service will automatically:
*URL-encode name/value pair, so you do not need to URL-encode the values you specify in table.
*Insert the "&" character between the pairs (or unnamed values) that it constructs, so you do not need to include it in table.
*Prefix the entire query string with the "?" character if it submits the data in table via the GET method. You do not need to include this character in table.
When you submit data using table, Integration Server automatically sets the value of the Content-Type header to application/x-www-form-urlencoded. If you want to explicitly specify a different Content-Type, you must submit your data using the string or bytes variable.
string
String Optional. Text that you want the pub.client:http service to submit to the resource in url. You can use string to submit data via the POST, PUT, PATCH, GET, or HEAD method.
If you use string to submit data, make sure that you specify the string exactly as you want it presented in the HTTP request. (If you are using the GET or HEAD method, make sure you URL-encode the contents of string.)
Note: When you use string, the pub.client:http service will automatically prefix the entire query string with "?" if it submits the data in string via a GET or HEAD. You do not need to include this character in string.
When performing a POST, PUT, or PATCH, string will be submitted to the resource defined by url as the body of the request message.
bytes
byte[ ] Optional. Data that you want this service to submit to the resource in url. You can use bytes to submit data via the DELETE, POST, PUT, or PATCH methods only.
Important: When you use bytes and another element (args, table, or string) to specify data, the service appends the data from the args, table, or string element to url. The service appends args to url first, table second, and string last. The service encodes the data from the bytes element in the body of the post.
Note: For POST, PUT, and PATCH, you can specify only stream, bytes, or mimeStream. If you specify more than one, the pub.client:http service ends with an exception.
mimeStream
Java.io.InputStream Optional. MIME or SMIME message that you want this service to submit to the resource in url. A mimeStream is created by the pub.mime:getEnvelopeStream, pub.smime:createEncryptedData, pub.smime:createSignedData, pub.smime.keystore:createSignedData or services. It contains both headers and content. The headers in the mimeStream are appended to the http headers.
You can use mimeStream to submit data via the POST, PUT, or PATCH methods only.
Note: For POST, PUT, and PATCH, you can specify only stream, bytes, or mimeStream. If you specify more than one, the pub.client:http service ends with an exception.
stream
java.io.InputStream Optional. Data that you want the pub.client:http service to submit to the resource in url. You can use stream to submit data via the POST, PUT, or PATCH methods only.
Important: When you use stream and another element (args, table, string or bytes) to specify data, the service appends the data from the args, table, or string element to url. The service appends args to url first, table second, and string last. The service encodes the data from the stream element in the body of the post.
Note: For POST, PUT, and PATCH, you can specify only stream, bytes, or mimeStream. If you specify more than one, the pub.client:http service ends with an exception.
encoding
String Optional. Character set in which the URL data parameters are encoded (args, table and string). Encoding is required to correctly convert the String object to bytes when generating the URL for a post. Specify an IANA-registered character set (for example, ISO-8859-1).
If this variable is null, the default JVM encoding is used. Because string is used in the body of the post and not used for building the URL, you do not need to specify encoding for the data parameter string.
auth
Document Optional. Authorization information that the pub.client:http service will submit if the resource specified in url is protected.
Key
Description
type
String Type of authentication scheme that you want this service to use when it submits this request. Set to:
*Basic to submit a user name and password. This is the default.
*Bearer to submit authorization information for an OAuth resource server.
*Digest to submit a password digest for authentication.
*NTLM to use NTLM authentication.
You do not need to specify a value for type if this request will specify values for kerberos to use Kerberos authentication. If you specify a value for type and provide kerberos values, Integration Server includes the authentication information related to the specified type and the Kerberos ticket in the outbound request.
user
String User name that this service will submit when requesting a protected resource.
Note: If you have specified NTLM as type, you must specify user in the following format:
domain_name\user_name
pass
String Password associated with user.
delegation
String Type of delegation to execute a service on behalf of other user. Set to:
*kerberos to use Kerberos delegation.
*none to not use delegation. This is the default.
token
String The access token to submit to the OAuth resource server. Required only when type is set to Bearer.
kerberos
Document Optional. Kerberos information that Integration Server uses to acquire a Kerberos ticket to include in the outbound client request. Integration Server includes the ticket in the HTTP Authorization header using the Negotiate authentication scheme. Specify kerberos details only if you need to use Kerberos authentication to access a secured website.
Key
Description
jaasContext
String Optional. The custom JAAS context used for Kerberos authentication. You must specify a JAAS context for the outbound request to use Kerberos authentication.
Integration Server includes a JAAS context named IS_KERBEROS_OUTBOUND that can be used with outbound requests.
If you specify a value for jaasContext, you must also specify a value for servicePrincipal.
clientPrincipal
String Optional. The name of the client principal to use for Kerberos authentication.
You must specify a clientPrincipal value if the specified jaasContext does not include the principal parameter. If you specify clientPrincipal and the specified jaasContext includes a principal parameter, the principal parameter in the jaasContext takes precedence.
The IS_KERBEROS_OUTBOUND JAAS context does not include a principal parameter. You must specify clientPrincipal if you specified IS_KERBEROS_OUTBOUND as the jaasContext value.
clientPassword
String Optional. The password for the specified client principal. You must specify clientPassword if the specified jaasContext does not specify a keytab file.
servicePrincipal
String Optional. The name of the principal that is used with the service that the Kerberos client wants to access. The service provider provides the Service Principal Name.
Specify the Service Principal Name in the following format:
principal-name.instance-name@realm-name
You must specify servicePrincipal if you supplied a jaasContext.
servicePrincipalForm
String Optional. The format in which you want to specify the principal name of the service that is registered with the principal database. Set to:
*host-based to represent the principal name using the service name and the hostname, where hostname is the host computer.
This is the default.
*username to represent the principal name as a named user in the LDAP or central user directory used for authentication to the key distribution center.
requestDelegatableToken
String Optional.
Specify if you want to request for a forwardable ticket granting ticket to send to the intermediary. The intermediary can use this forwardable ticket granting ticket for Kerberos delegation. Set to:
*true to request for a forwardable ticket granting ticket.
*false to request for non-delegable token. This is the default.
headers
Document Optional. Fields that you want to explicitly override in the HTTP request header issued by the pub.client:http service.
Specify a key in headers for each header field that you want to set, where the key's name represents the name of the header field and the key's value represents the value of that header field.
If you do not set headers, the pub.client:http service uses its default header values.
timeout
String Optional. Time, measured in milliseconds, that Integration Server waits for a response from the remote server before timing out and terminating the request. If you do not specify a value, Integration Server uses the value of the watt.net.timeout server configuration parameter.
For information about the watt.net.timeout server configuration parameter, see webMethods Integration Server Administrator’s Guide.

maxKeepAlive Connections
String Optional. Number of client keep alive connections that you want Integration Server to retain in the client connection pool it uses for this HTTP connection.
Integration Server establishes a client connection pool for each protocol (i.e., HTTP or HTTPS), host, and port combination. How the service uses this input value differs based on whether a suitable client connection pool already exists for the HTTP connection.
*If a suitable pool already exists, Integration Server uses a connection from the pool for the HTTP request. If the specified maxKeepAliveConnections is different from what is currently being used for the pool, Integration Server updates the pool to use the value you specify.
*If a suitable pool does not exist, Integration Server establishes one, using the maximum connections defined by this parameter. If you do not specify a value, the service uses the default value defined by the watt.net.maxClientKeepAliveConns server configuration parameter. After establishing the client connection pool, the service uses a connection from the newly established connection pool to the HTTP request.
keepAliveTimeout
String Optional. Number of seconds that you want Integration Server to keep an idle connection in the client connection pool before closing it.
Integration Server establishes a client connection pool for each protocol (i.e., HTTP or HTTPS), host, and port combination. How the service uses this input value differs based on whether a suitable client connection pool already exists for the HTTP connection.
*If a suitable pool already exists, Integration Server uses a connection from the pool for the HTTP request. If the specified keepAliveTimeout is different from what is currently being used for the pool, Integration Server updates the pool to use the value you specify.
*If a suitable pool does not exist, Integration Server establishes one, using the timeout value defined by this parameter. If you do not specify a value, the service uses the default value defined by the watt.net.clientKeepAliveTimeout server configuration parameter. After establishing the client connection pool, the service uses a connection from the newly established connection pool to the HTTP request.
newSession
String Optional. Flag indicating whether a new session will be created for this HTTP request. This parameter overrides the watt.server.new.http.session.context server configuration parameter. For information about the watt.server.new.http.session.context server configuration parameter, see webMethods Integration Server Administrator’s Guide.
Set to:
*no to use the current session, if one is available, for this HTTP request. This is the default.
*yes to create a new session for this HTTP request.
proxyAlias
String Optional. Name of the proxy alias for the proxy server to which Integration Server routes the HTTP request.
If you do not specify a proxyAlias, Integration Server routes the HTTP request through the proxy server specified in the default HTTP proxy alias. If there is no default HTTP proxy alias, the action taken by Integration Server depends on the value specified for the watt.net.proxy.useNonDefaultProxies parameter.
*If the watt.net.proxy.useNonDefaultProxies parameter is set to true, Integration Server routes the HTTP request through the proxy server in any configured HTTP proxy alias. If the Integration Server does not have any defined HTTP proxy aliases, Integration Server sends the HTTP request directly to the HTTP server or throws an exception depending on the settings specified for the watt.net.proxy.fallbackToDirectConnection parameter.
*If the watt.net.proxy.useNonDefaultProxies parameter is set to false, Integration Server sends the request to the remote server using a direct connection.
For more information about proxy server usage, refer to webMethods Integration Server Administrator’s Guide.
connectTimeout
String Optional. Time, measured in milliseconds, that Integration Server waits to connect to the remote server before timing out and terminating the request. If you do not specify a value for connectTimeout, Integration Server uses the value specified for the watt.net.timeout server configuration parameter. If no value is specified for the watt.net.timeout server configuration parameter, Integration Server waits for the timeout value defined by the operating system before terminating the connection request.
For more information about the watt.net.timeout server configuration parameter, see webMethods Integration Server Administrator’s Guide.
useJSSE
String Optional. Whether to enable the use of the Java Secure Socket Extension (JSSE) socket factory for creating outbound HTTPS connections. Set to:
*yes if the connection requires the use of TLS 1.1 or TLS 1.2. When set to yes, Integration Server creates the connection using the Java Secure Socket Extension (JSSE) socket factory.
*no if the connection does not require support for TLS 1.1 or TLS 1.2. When set to no, the connection supports only SSL 3.0 and TLS 1.0 and Entrust IAIK library is used to create the outbound HTTPS connection.
Note: A value of yes or no for the useJSSE input parameter overrides the value of the watt.net.ssl.client.useJSSE server configuration property.
Note: To control the cipher suites used on JSSE sockets that are used while making outbound HTTPS requests, set the server configuration property watt.net.jsse.client.enabledCipherSuiteList. For more information, see webMethods Integration Server Administrator’s Guide.
Output Parameters
encodedURL
String The URL that was submitted by pub.client:http. This will contain any argument set in args, table, or string.
If the remote server redirected pub.client:http to a different location, encodedURL will contain the URL that pub.client:http submitted to the server to which it was redirected.
header
Document Conditional. HTTP response headers.
Key
Description
lines
Document Fields in the response header, where key names represent field names and values represent field values.
status
String HTTP status code of the response.
statusMessage
String HTTP status message of the response.
body
Document Body of the HTTP response.
Key
Description
bytes
byte[ ] Conditional. Body of the HTTP response represented as a byte[ ]. bytes is returned only when the loadAs input parameter is set to bytes.
stream
java.io.InputStream Conditional. The body of the HTTP response represented as an InputStream. stream is returned only when the loadAs input parameter is set to stream.
Usage Notes
For the GET, HEAD, OPTIONS, and TRACE methods, the pub.client:http service sends a URL only. The service does not send a body.
The pub.client:http service sends the data/string input in the query of the URL when using the GET or HEAD methods, but sends the input as the body of the request when using the POST, PUT or PATCH methods.
If url begins with https:, you can use pub.security:setKeyAndChain to specify the certificate chain. If you do not specify a certificate chain, pub.client:http uses the default outbound SSL certificate settings to authenticate the resources.
When using pub.client:http to create an outbound HTTPS connection, before initiating the SSL handshake with the remote server, Integration Server sets the SSL socket timeout to the value of the watt.net.ssl.server.clientHandshakeTimeout value.
If pub.client:http does not receive a response within the time-out period specified in the server's watt.net.timeout server configuration parameter, it will throw an exception. For information about the watt.net.timeout server configuration parameter, see webMethods Integration Server Administrator’s Guide.
For the HTTP request, the pub.client:http service uses a client connection from a client connection pool. When you set the loadAs input parameter to stream so that the service returns the response body as a stream, the connection remains in use and is not returned to the connection pool until you close the stream. To close the stream and return the connection to the pool, you can use the pub.io:close service or the close() method on the returned stream object.
When the HTTP response contains the 401 status code, the pub.client:http service does one of the following depending on the value of the watt.net.http401.throwException server configuration parameter.
*When watt.net.http401.throwException is set to true, if the pub.client:http service receives a 401 error, the service throws a NetException.
*When watt.net.http401.throwException is set to false, if the pub.client:http service receives a 401 error, the service suppresses the NetException and places the HTTP response header and body, if one exists, into the header and body fields in the service output.
When the HTTP response contains the HTTP 302 redirection status code, the pub.client:http service automatically redirects the request to the URL provided by the remote server. If the remote server redirected pub.client:http to a different location, the output parameter encodedURL will contain the URL that pub.client:http submitted to the server to which the service was redirected.
If the server to which pub.client:http is redirected returns an HTTP response with a 401 status code and watt.net.http401.throwException is set to false, the pub.client:http services places the header and body of the response in the output pipeline. The service that invokes pub.client:http can examine the header/status field to determine if the server to which pub.client:http was redirected returned a 401. If it did, the service can re-issue the outbound request directly to the URL in encodedURL field, making sure to supply credentials with the request.
When the HTTP response contains the status code in the 501 to 599 range, the pub.client:http service does one of the following depending on the value of the watt.net.http501-599.throwException server configuration parameter:
*When set to true, the pub.client:http service throws a ServiceException when it receives a 501 to 599 level response from a remote HTTP server.
*When set to false, the pub.client:http service returns the status code, response headers, and response body in the service output when it receives a 501 to 599 level response from a remote HTTP server.
When the method input variable is DELETE, you can supply a value in the data/bytes input variable. The pub.client:http service will transmit the value in the body of the request to the remote server
If data is supplied in a format that is not supported with an HTTP method, the pub.client:http service ignores the data. For example, use of the data/stream and data/mimeStream input variables is not supported with DELETE. If the data/stream or data/mimeStream input variables specify a value when method is set to DELETE, the pub.client:http service ignores data/stream or data/mimeStream.
For POST, PUT and PATCH, if a value is supplied for data/args and/or data/table, the pub.client:http service sets the Content-Type header for the request to is set to application/x-www-form-urlencoded. The service ignores a Content-Type value supplied using a name/value pair in headers.
You can append query parameters directly to the url input parameter value. If you do this, any value supplied for data/args and data/table will be appended. For the GET method, the data/string value would also be appended. For example, these inputs:
*url = http://example-host:8080/getOrders?cust=116
*data/args= {{“since”, “20180201”}, {“greaterThan”, “250.00”}}
Result in pub.client:http sending this URL: http://example-host:8080/getOrders?cust=116&somce=20180201&greaterThan=250.00
When using Kerberos authentication, principal name and principal password can be specified in the JAAS context file and in the pub.client:http service in the clientPrincipal and clientPassword fields in the auth\kerberos document. If the principal name and password are specified in the JAAS context file supplied to jaasContext and in the pub.client:http service, the values in the JAAS context file take precedence.
When Integration Server acts as a client (original requester) and requires a forwardable ticket granting ticket, ensure that you set the requestDelegatableToken parameter to true.
When Integration Server acts as an intermediary, ensure that you set the delegation parameter to kerberos to use Kerberos delegation.
Copyright © 2015- 2018 | Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors.
Innovation Release