Client Folder

You can use the elements in the client folder to formulate and submit requests to HTTP, FTP, SFTP, e-mail, WebSocket, and LDAP servers.

Summary of Elements in this Folder

The following elements are available in this folder:

Element Package and Description
pub.client:ftp WmPublic. Performs a series of FTP actions.
pub.client.ftp:append WmPublic. Appends data to a remote file.
pub.client.ftp:cd WmPublic. Changes the working directory on the FTP server. (This service corresponds to the standard FTP command cd dirpath.)
pub.client.ftp:cdls WmPublic. Changes the working directory on the FTP server and retrieves a list of file names. (This service corresponds to the standard FTP commands cd dirpath and ls namePattern.)
pub.client.ftp:delete WmPublic. Deletes a file in the current working directory on an FTP server. (This service corresponds to the standard FTP command delete somefile.)
pub.client.ftp:dir WmPublic. Retrieves the file list during an FTP session. (This service corresponds to the standard FTP command dir namepattern.)
pub.client.ftp:get WmPublic. Retrieves a file from a remote FTP server. (This service corresponds to the standard FTP command get.)
pub.client.ftp:getCompletedNotification WmPublic. A publishable document type that represents the document published to notify parties that an FTP get command has completed.
pub.client.ftp:login WmPublic. Connects to a remote FTP server and logs in with a specified user name and password.
pub.client.ftp:logout WmPublic. Logs off of the FTP server and ends the current FTP session.
pub.client.ftp:ls WmPublic. Retrieves the file list during an FTP session. (This service corresponds to the standard FTP command ls namepattern.)
pub.client.ftp:mdelete WmPublic. Deletes multiple files in the current working directory on an FTP server. (This service corresponds to the standard FTP command mdelete pattern.)
pub.client.ftp:mget WmPublic. Transfers multiple files from the remote FTP server. (This service corresponds to the standard FTP command mget.)
pub.client.ftp:mput WmPublic. Transfers multiple files to a remote FTP server. (This service corresponds to the standard FTP command input.)
pub.client.ftp:put WmPublic. Transfers a file to a remote FTP server. (This service corresponds to the standard FTP command put.)
pub.client.ftp:putCompletedNotification WmPublic. A publishable document type that represents the document published to notify parties that an FTP put command has completed.
pub.client.ftp:quote WmPublic. Executes a given FTP command.
pub.client.ftp:rename WmPublic. Renames a file on a remote FTP server. (This service corresponds to the standard FTP command rename.)
pub.client.ftp:sessioninfo WmPublic. Returns session information for all of the FTP servers that users are currently logged into.
pub.client:http WmPublic. Issues an HTTP request that you specify and returns the HTTP response.
pub.client.ldap:add WmPublic. Inserts a new entry into the directory.
pub.client.ldap:bind WmPublic. Performs an LDAP bind operation that associates the connection with the specified principal.
pub.client.ldap:cancelNotification WmPublic. Cancels a previously created notification request.
pub.client.ldap:compare WmPublic. Compares the value of an attribute in the LDAP directory with a value specified by the service.
pub.client.ldap:delete WmPublic. Removes an entry from the directory.
pub.client.ldap:modify WmPublic. Performs an LDAP modify operation that allows you to specify a list of attributes with corresponding lists of values to add to, replace, or remove from the directory entry.
pub.client.ldap:registerNotification WmPublic. Creates a notification (or "persistent search") that causes Integration Server to listen for LDAP events. When the notification gets an event, the specified service is called.
pub.client.ldap:rename WmPublic. Performs an LDAP rename (move) operation allowing you to rename an entry.
pub.client.ldap:search WmPublic. Performs an LDAP search operation with the specified parameters and returns the results of the search.
pub.client.oauth:executeRequest WmPublic. Allow clients to access protected resources using an OAuth token.
pub.client.oauth:​getExternalAccessToken WmPublic. Requests an access token from the authorization server.
pub.client:restClient WmPublic. Creates and sends REST API requests over HTTP or HTTPS.

This service is internal to Integration Server and you must not execute this service manually.

pub.client.sftp:cd WmPublic. Changes the working directory on the remote SFTP server.
pub.client.sftp:chgrp WmPublic. Changes the group ownership of one or more remote files.
pub.client.sftp:chmod WmPublic. Changes permissions of one or more remote files.
pub.client.sftp:chown WmPublic. Changes the user of one or more remote files.
pub.client.sftp:get WmPublic. Retrieves a file from a remote SFTP server and saves it on the local machine.
pub.client.sftp:login WmPublic. Creates a secure connection to the SFTP server using the specified user alias or configuration parameters.
pub.client.sftp.admin:getDefaultAlgorithms WmPublic. Returns the default key exchange algorithms, Message Authentication Code (MAC) algorithms, and ciphers for the specified SFTP client version.
pub.client.sftp.admin:getHostKey WmPublic. Gets the host key from the SFTP server.
pub.client.sftp:logout WmPublic. Logs off the user from the SFTP server and ends the current SFTP session.
pub.client.sftp:ls WmPublic. Retrieves the remote directory listing of the specified path or current remote directory if path is not specified.
pub.client.sftp:mkdir WmPublic. Creates a new remote directory.
pub.client.sftp:put WmPublic. Transfers a file to a remote SFTP server.
pub.client.sftp:pwd WmPublic. Displays the remote working directory on the SFTP server.
pub.client.sftp:rename WmPublic. Renames a file or directory on a remote SFTP server.
pub.client.sftp:rm WmPublic. Deletes one or more remote files on the SFTP server.
pub.client.sftp:rmdir WmPublic. Deletes one or more remote directories on the SFTP server.
pub.client.sftp:symlink WmPublic. Creates a symbolic link between the old path and the new path of a file.
pub.client:smtp WmPublic. Sends a MIME-type e-mail message.
pub.client:soapClient WmPublic. Creates and sends SOAP 1.1 and SOAP 1.2 messages over HTTP, HTTPS, or JMS transports for any style/use combination supported by Integration Server.
pub.client:soapHTTP WmPublic. Deprecated - There is no replacement service. Submits a SOAP message to a server via HTTP or HTTPS.
pub.client:soapRPC WmPublic. Deprecated - There is no replacement service. Submits a SOAP remote procedure call via HTTP or HTTPS.
pub.client:websocket WmPublic. Establishes a WebSocket connection to the URL captured in the identified WebSocket client endpoint.

pub.client:ftp

WmPublic. Performs a series of FTP actions.

This service executes the following sequence:

  1. Logs on to an FTP server.
  2. Changes to a specified working directory.
  3. Performs one of the following FTP commands: ls, put, or get.
  4. Logs off the FTP server.
Important: Integration Server allows you to invoke the pub.client:ftp service to get a file from a remote FTP server and place it in the WmRoot folder, which may be a security concern.

Input Parameters

serverhost String Name or IP address of the FTP server (for example, ftp.netscape.com).
serverport String Port number of the FTP server (for example, 4566).
username String Valid FTP user of the remote FTP server (for example, anonymous).
password String Optional. Valid password of the FTP user.
command String One of the following FTP commands: ls, put, or get.
dirpath String Working directory of the FTP server (for example, /tmp/pub). If the directory does not exist, the server throws an exception.
transfermode String One of two FTP file transfer modes: ascii or binary. The default is ascii.
transfertype String One of two FTP data transfer types: passive or active. The default is active.
localfile String When command is set to put, this parameter specifies the name of the local file you want to transfer. (If content is specified, this field is ignored.)

When command is set to get, this parameter specifies the name of the local file in which you want the retrieved content saved.

remotefile String When command is set to put, this parameter specifies the name of the remote file in which you want the save the data you are sending.

When command is set to get, this parameter specifies the name of the remote file that you want to retrieve.

content java.io.InputStream, byte[ ], or String Data to be transferred when command is set to put.
encoding String Optional. Character set in which the document is encoded. Specify an IANA-registered character set (for example, ISO-8859-1).

This information is required to correctly convert the String object to bytes when performing a get. If parameter is null, the default JVM encoding is used.

serverencoding String Optional. Specifies the encoding this service uses to convert the incoming FTP command string to encoded bytes that are supported by IANA and the FTP server. If the parameter is null, the service uses the 'UTF-8' character set to encode the FTP command String to bytes.
timeout String Time (measured in seconds) this service waits for the FTP server response on the command channel before timing out and aborting the request. Default is to wait forever.
putunique String Optional. Indicates whether to send a STOR or a STOU (Store as Unique File) command to the remote FTP server. Set to:
  • true to send a STOU (Store as Unique File) command.
  • false to send a STOR command. This is the default.
secure Document Indicates whether the FTP session is with a secure FTP server.
Note: Integration Server does not support FTPS (FTP over SSL) requests through FTP proxy.
  Key Description
  auth String The kind of authentication mechanism to use: None, SSL, TLS, or TLS-P.

None specifies that the FTP session is with a non-secure FTP server. This is the default. If the value of auth is None, the securedata variable is ignored.

TLS-P is a shortcut that is equivalent to the sequence AUTH TLS, PBSZ 0, and PROT P. If the value of auth is TLS-P, the securedata variable is ignored.

  securedata String Use the value false for a client sending PROT C (Data Channel Protection Level Clear).

Use the value true for a client sending PROT P (Data Channel Protection Level Private).

Note: If you do not set a value, the default is false.
  useJSSE String Optional. Whether to enable the use of the Java Secure Socket Extension (JSSE) library for creating outbound FTPS connections. Set to:

  • yes if the connection requires the use of TLS 1.1, TLS 1.2, or TLS 1.3. When set to yes, Integration Server creates the connection using the Java Secure Socket Extension (JSSE) library.

  • no if the connection does not require support for TLS 1.1, TLS 1.2, or TLS 1.3. When set to no, the connection supports only TLS 1.0 which is not secure. The Entrust IAIK library is used to create the outbound FTPS connection.

When the value of useJSSE is not specified, Integration Server uses the value set for the watt.net.ssl.client.ftps.useJSSE server configuration parameter.

Note:
  • A value of yes or no for the useJSSE input parameter overrides the value of the watt.net.ssl.client.ftps.useJSSE server configuration parameter.
  • To control the cipher suites used on JSSE sockets that are used while making outbound FTPS requests, set the server configuration property watt.net.jsse.client.enabledCipherSuiteList. For more information, see Integration Server.
  • When using this service to set up an FTPS connection over JSSE with an FTPS server, you must ensure that the FTPS port on the destination Integration Server is configured with the Use JSSE parameter set to Yes. For more information about configuring the FTPS port, see webMethods Integration Server Administrator’s Guide.
cleanlinefeeds String Optional. Indicates whether the service should retain or remove carriage return characters at the end of each line of text. Set to:
  • true to remove carriage returns. This is the default.
  • false to retain carriage returns.
newSession String Optional. Flag indicating whether a a new FTP session will be created for this FTP operation. Set to:
  • yes to create a new session for this FTP operation.
  • no to use the current session, if one is available, for this FTP operation. This is the default.
clientTimeout String Optional. Specifies the idle time-out, measured in seconds, for this FTP session. If clientTimeout is set to 0 (zero), the session will never time out. The default is 600 seconds (10 minutes).
proxyAlias String Optional. Name of the proxy server alias for the proxy server to which Integration Server routes the FTP request.

If you do not specify a proxyAlias, Integration Server routes the FTP request through the proxy server specified in the default FTP proxy alias. If there is no default FTP 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 FTP request through the proxy server in any configured FTP proxy alias. If the Integration Server does not have any defined FTP proxy aliases, Integration Server sends the FTP request directly to the FTP 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 How Uses Proxy Servers.

Output Parameters

command String FTP command that was executed (ls, get, or put).
dirlist String List File names returned by the ls command.
localfile String Name of the local file used for a get or put operation.
remotefile String Name of the remote file used for a get or put operation.
content byte[ ] If localfile was not specified, this parameter contains the Content object sent to the remote server (if a put command was executed) or received from the remote server (if a get command was executed).
returncode String Standard FTP protocol return code.
returnmsg String Standard FTP protocol return message.
logmsg String FTP log message.

Usage Notes

If you set the auth variable in the secure parameter to SSL, TLS, or TLS-P, pub.client.ftp automatically sends the following sequence of FTP commands prior to sending the USER command: 

AUTH <SSL | TLS | TLS-P>  PBSZ 0  PROT <P | C>

The client FTP services will not negotiate for less security than you have specified with the auth parameter. However, if you set the auth variable to None, the client FTP services can operate (in a non-secure mode) with any FTP server.

The FTP services will always connect to a secure FTP server using a non-secure (SSL) socket. After getting a valid reply from the AUTH command, the FTP services will convert the connected socket to an SSL socket and initiate SSL handshaking.

pub.client.ftp:append

WmPublic. Appends data to a remote file.

If the remote file does not exist, the service creates the file.

Input Parameters

sessionkey String Unique key for the current FTP session. The sessionkey is returned by the pub.client.ftp:login service.
transfermode String FTP file transfer mode (ascii or binary). The default is ascii.
content java.io.InputStream, byte[ ], or String Data to be transferred to the remote file.
localfile String Optional. Name of the local file to append to the remote file. Used only when content is not specified.
remotefile String Name of the remote file to which to append the data specified in content or localfile.

Output Parameters

returncode String Standard FTP protocol return code.
returnmsg String Standard FTP protocol return message.
logmsg String FTP log messages for the entire user session.

pub.client.ftp:cd

WmPublic. Changes the working directory on the FTP server. (This service corresponds to the standard FTP command cd dirpath.)

Input Parameters

sessionkey String Unique key for the current FTP session. The sessionkey is returned by the pub.client.ftp:login service.
dirpath String Directory to which you want to switch on the FTP server. For example: pub

Output Parameters

returncode String Standard FTP protocol return code.
returnmsg String Standard FTP protocol return message.
logmsg String FTP log messages for the entire user session.

pub.client.ftp:cdls

WmPublic. Changes the working directory on the FTP server and retrieves a list of file names. (This service corresponds to the standard FTP commands cd dirpath and ls namePattern.)

Input Parameters

sessionkey String Unique key for the current FTP session. The sessionkey is returned by the pub.client.ftp:login service.
dirpath String Directory to which you want to switch on the FTP server (for example, pub).
filenamepattern String Optional. Pattern that specifies the file names to list (for example, *.txt).
orderby String Optional. The order of the returned file list. Set to:
  • none to send an NLST command to the remote FTP server. This is the default.

  • timestamp to return the list in order of the timestamp. Sends an NLST -t command to the remote FTP server.

    Note: The -t command is not part of the RFC959 standard. Some FTP servers may not support this command. Servers that support this command may return the results in either ascending or descending order of creation time.

Output Parameters

dirlist String List List of file names matching filenamepattern.
returncode String Standard FTP protocol return code.
returnmsg String Standard FTP protocol return message.
logmsg String FTP log messages for the entire user session.

pub.client.ftp:delete

WmPublic. Deletes a file in the current working directory on an FTP server. (This service corresponds to the standard FTP command delete somefile.)

Input Parameters

sessionkey String Unique key for the current FTP session. The sessionkey is returned by the pub.client.ftp:login service.
remotefile String Name of the file to be deleted from the current working directory. For example: text.txt

If you specify pattern-matching characters in remotefile, all files matching the pattern will be deleted.

Output Parameters

returncode String Standard FTP protocol return code.
returnmsg String Standard FTP protocol return message.
logmsg String FTP log messages for the entire user session.

pub.client.ftp:dir

WmPublic. Retrieves the file list during an FTP session. (This service corresponds to the standard FTP command dir namepattern.)

Input Parameters

sessionkey String Unique key for the current FTP session. The sessionkey is returned by the pub.client.ftp:login service.
filenamepattern String Optional. Pattern that specifies the names of the files to include in the list (for example, *.txt).

Output Parameters

dirlist String List Directory listing of the files matching filenamepattern including the file names and timestamps.
returncode String Standard FTP protocol return code.
returnmsg String Standard FTP protocol return message.
logmsg String FTP log messages for the entire user session.

pub.client.ftp:get

WmPublic. Retrieves a file from a remote FTP server. (This service corresponds to the standard FTP command get.)

Input Parameters

sessionkey String Unique key for the current FTP session. The sessionkey is returned by the pub.client.ftp:login service.
transfermode String FTP file transfer mode (ascii or binary). The default is ascii.
localfile String Optional. Name of a local file where the retrieved file is to be saved.
remotefile String Name of the remote file.
encoding String Optional. Character set in which the file is encoded. This variable is required to convert the file to bytes correctly. Specify an IANA-registered character set (for example: ISO-8859-1).

If this variable is null, the encoding currently set for the FTP session is used. If encoding was never set for this FTP session, the default JVM encoding is used.

largefilethreshold String Optional. Defines the size (in bytes) of a "large" file. For more information, see the Usage Notes.
  If you... Then...
  Set to 0 All files will be considered large files. This means:
  • The output parameter islargefile will always be true.
  • The file content will be returned in the output parameter contentstream (as a java.io.InputStream object).
  • The output parameter content will be null.
  Set to any value greater than 0 Any file larger than the value you specify will be considered large. This means:
  • The output parameter islargefile will be true.
  • The file content will be returned in the output parameter contentstream (as a java.io.InputStream object).
  • The output parameter content will be null.
  Leave blank No file is considered large. This means:
  • The output parameter islargefile will always be false.
  • The file content will be returned in the output parameter content.
  • The output parameter contentstream will be null.
cleanlinefeeds String Optional. Indicates whether the service should retain or remove carriage return characters at the end of each line of text. Set to:
  • true to remove carriage returns.
  • false to retain carriage returns. This is the default.

Output Parameters

content byte[ ] Data retrieved from the remote file.
returncode String Standard FTP protocol return code.
returnmsg String Standard FTP protocol return message.
logmsg String FTP log messages for the entire user session.
islargefile String Indicates whether the file is considered to be large (as specified by the input parameter largefilethreshold). A value of:
  • true indicates that the file is larger than the value of largethreshold.
  • false indicates that the file is not larger than the value of largethreshold (or largethreshold is blank).
contentstream Object An java.io.InputStream object.

Usage Notes

The largefilethreshold parameter improves the ability of pub.client.ftp:get to retrieve larger files. If a retrieved file is larger than the size specified in the largefilethreshold parameter, and the localfile parameter is empty (which means the retrieved file is retrieved to memory, not to a file on disk), the Integration Server streams the large file to a temporary file. While this will improve the scalability of pub.client.ftp:get, it will also reduce the throughput of the operation because the retrieved file will be written to a temporary file.

Tip: Due to the impact to the throughput of pub.client.ftp:get when streaming is enabled, you should set the value for largefilethreshold to a sufficiently large value so that it causes only minimal degradation to throughput and yet allows the service to retrieve large files without encountering an OutOfMemory exception.

See Also

pub.client.ftp:getCompletedNotification

WmPublic. A publishable document type that represents the document published to notify parties that an FTP get command has completed on Integration Server which is acting as the FTP server.

When a user completes an FTP get command in his or her own user directory (that is, when the RETR command is completed on the server side but the server has not yet acknowledged the client with return code 226), an event is fired to notify interested parties by publishing a document. EDI packages that subscribe to this document will remove the file from the server.

Parameters

username String The login user name through the FTP Listener.
filename String The absolute path name of the file.
_env Document Optional. A document reference to pub.publish:envelope which defines the structure and contents of the envelope of a published document.

Usage Notes

Integration Server publishes an instance document of pub.client.ftp:getCompletedNotification when an FTP client has completed an FTP get command on Integration Server through an FTP/S port. Because the retrieved file is located on the Integration Server file system, only subscribers located on the same Integration Server would have access to the file. Consequently the pub.client.ftp:getCompletedNotification publishable document type is set to publish locally only and uses the IS_LOCAL_CONNECTION messaging connection alias. When Integration Server publishes an instance document for pub.client.ftp:getCompletedNotification, only subscribers located on the same Integration Server receive the document. Software AG does not recommend changing the assigned messaging connection alias.

pub.client.ftp:login

WmPublic. Connects to a remote FTP server and logs in with a specified user name and password.

Input Parameters

serverhost String Name or IP address of the FTP server (for example, ftp.netscape.com).
serverport String Port number on which the FTP server listens for requests (for example, 4566).

The default is 21.

dataport String Optional. Listener port number of the data transfer channel (for example, 3345).

If you do not specify dataport, the Integration Server will choose the listener port number. This value is used only when the transfertype value is active.

username String Valid FTP user on the remote FTP server (for example, anonymous).
password String Optional. Valid password for the FTP user specified in username (for example, someone@somewhere).
account String Optional. The user name for an account on the FTP server. Specify account if your FTP host requires account information. The account is defined in the FTP protocol to further identify the user that is identified by the username and password input variables.
transfertype String Type of the FTP data transfer mode (passive or active). The default is active.
encoding String Optional. Default character set for encoding data transferred during this session. Specify an IANA-registered character set (for example, ISO-8859-1).

If you do not set encoding, the default JVM encoding is used.

serverencoding String Optional. Specifies the encoding this service uses to convert the incoming FTP command string to encoded bytes that are supported by IANA and the FTP server. If the parameter is null, the service uses the 'UTF-8' character set to encode the FTP command String to bytes.
timeout String Optional. Time (measured in seconds) to wait for a response from the FTP server before timing out and terminating the request. The default is to wait forever.
secure Document Indicates whether the FTP session is with a secure FTP server.
Note: Integration Server does not support FTPS (FTP over SSL) requests through FTP proxy.
Note: Integration Server does not support implicit FTPS, which is also deprecated.
  Key Description
  auth String The kind of authentication mechanism to use: None, SSL, TLS, or TLS-P.

None specifies that the FTP session is with a non-secure FTP server. This is the default. If the value of auth is None, the securedata variable is ignored.

TLS-P is a shortcut that is equivalent to the sequence AUTH TLS, PBSZ 0, and PROT P. If the value of auth is TLS-P, the securedata variable is ignored.

  securedata String Use the value false for a client sending PROT C (Data Channel Protection Level Clear).

Use the value true for a client sending PROT P (Data Channel Protection Level Private).

Note: If you do not set a value, the default is false.
  useJSSE String Optional. Whether to enable the use of the Java Secure Socket Extension (JSSE) library for creating outbound FTPS connections. Set to:

  • yes if the connection requires the use of TLS 1.1, TLS 1.2, or TLS 1.3. When set to yes, Integration Server creates the connection using the Java Secure Socket Extension (JSSE) library.

  • no if the connection does not require support for TLS 1.1, TLS 1.2, or TLS 1.3. When set to no, the connection supports only TLS 1.0 which is not secure. The Entrust IAIK library is used to create the outbound FTPS connection.

When the value of useJSSE is not specified, Integration Server uses the value set for the watt.net.ssl.client.ftps.useJSSE server configuration parameter.

Note:
  • A value of yes or no for the useJSSE input parameter overrides the value of the watt.net.ssl.client.ftps.useJSSE server configuration parameter.
  • To control the cipher suites used on JSSE sockets that are used while making outbound FTPS requests, set the server configuration property watt.net.jsse.client.enabledCipherSuiteList. For more information, see webMethods Integration Server Administrator’s Guide.
  • When using this service to set up an FTPS connection over JSSE with an FTPS server, you must ensure that the FTPS port on the destination Integration Server is configured with the Use JSSE parameter set to Yes. For more information about configuring the FTPS port, see webMethods Integration Server Administrator’s Guide.
newSession String Optional. Flag indicating whether a a new FTP session will be created for this FTP operation. Set to:
  • yes to create a new session for this FTP operation.
  • no to use the current session, if one is available, for this FTP operation. This is the default.
clientTimeout String Optional. Specifies the idle time-out, measured in seconds, for this FTP session. If clientTimeout is set to 0 (zero), the session will never time out. The default is 600 seconds (10 minutes).
proxyAlias String Optional. Name of the proxy alias for the proxy server through which Integration Server routes the FTP request.

If you do not specify a proxyAlias, Integration Server routes the FTP request through the proxy server specified in the default FTP proxy alias. If there is no default FTP 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 FTP request through the proxy server in any configured FTP proxy alias. If the Integration Server does not have any defined FTP proxy aliases, Integration Server sends the FTP request directly to the FTP 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.

Output Parameters

sessionkey String Unique key for the current FTP session. This session key must be provided to execute most other services in pub.client.ftp.
returncode String Standard FTP protocol return code.
returnmsg String Standard FTP protocol return message.
logmsg String FTP log messages for the entire user session.

Usage Notes

If you set the auth variable in the secure parameter to SSL, TLS, or TLS-P, pub.client.ftp:login automatically sends the following sequence of FTP commands prior to sending the USER command: 

AUTH <SSL | TLS | TLS-P>  PBSZ 0  PROT <P | C>

The client FTP services will not negotiate for less security than you have specified with the auth parameter. However, if you set the auth variable to None, the client FTP services can operate (in a non-secure mode) with any FTP server.

The FTP services will always connect to a secure FTP server using a non-secure (SSL) socket. After getting a valid reply from the AUTH command, the FTP services will convert the connected socket to an SSL socket and initiate SSL handshaking.

If the watt.client.ftp.session.logoutOnServiceCompletion parameter is set to true, the FTP session created by the pub.client.ftp:login service closes automatically when the invoking service completes execution. If the value is set to false, then the pub.client.ftp:logout service must be invoked to close the FTP(S) session.

pub.client.ftp:logout

WmPublic. Logs off of the FTP server and ends the current FTP session.

Input Parameters

sessionkey String Unique key for the current FTP session. The sessionkey is returned by the pub.client.ftp:login service.

Output Parameters

returncode String Standard FTP protocol return code.
returnmsg String Standard FTP protocol return message.
logmsg String FTP log messages for the entire user session.

pub.client.ftp:ls

WmPublic. Retrieves the file list during an FTP session. (This service corresponds to the standard FTP command ls namepattern.)

Input Parameters

sessionkey String Unique key for the current FTP session. The sessionkey is returned by the pub.client.ftp:login service.
filenamepattern String Optional. Pattern that specifies the names of the files to include in the list (for example, *.txt).
orderby String Optional. The order of the returned file list.
  Value of orderby Description
  none Default. Sends an NLST command to the remote FTP server.
  timestamp Returns the list in order of the timestamp. Sends an NLST -t command to the remote FTP server.
Note: The -t command is not part of the RFC959 standard. Some FTP servers may not support this command. Servers that support this command may return the results in either ascending or descending order of creation time.

Output Parameters

dirlist String List List of file names matching filenamepattern.
returncode String Standard FTP protocol return code.
returnmsg String Standard FTP protocol return message.
logmsg String FTP log messages for the entire user session.

Usage Note

During an FTP session, this service uses the character set specified in the encoding parameter of the pub.client.ftp:login service. If the file list this service retrieves includes characters from other languages, set the encoding parameter appropriately. For example, set encoding to SJIS for file names containing Japanese characters. If you do not set encoding in pub.client.ftp:login, the default JVM encoding is used.

pub.client.ftp:mdelete

WmPublic. Deletes multiple files in the current working directory on an FTP server. (This service corresponds to the standard FTP command mdelete pattern.)

Input Parameters

sessionkey String Unique key for the current FTP session. The sessionkey is returned by the pub.client.ftp:login service.
filenamepattern String Pattern that specifies the names of the files to be deleted from the current working directory (for example, *.txt).
Important: If you do not specify a value for filenamepattern, all files in the working directory are deleted.

Output Parameters

returncode String Standard FTP protocol return code.
returnmsg String Standard FTP protocol return message.
logmsg String FTP log messages for the entire user session.

pub.client.ftp:mget

WmPublic. Transfers multiple files from the remote FTP server. (This service corresponds to the standard FTP command mget.)

Input Parameters

sessionkey String Unique key for the current FTP session. The sessionkey is returned by the pub.client.ftp:login service.
transfermode String FTP file transfer mode (ascii or binary). The default is ascii.
localdir String Directory in the local file system where the retrieved files are to be saved (for example, c:\temp\ftpfiles).
filenamepattern String Pattern that specifies the names of the files to be retrieved (for example, *.txt).
encoding String Optional. Character set in which the files are encoded. This variable is required to convert the files to bytes correctly. Specify an IANA-registered character set (for example, ISO-8859-1).

If you do not specify encoding, the encoding assigned to the FTP session is used. If the encoding was not set for the FTP session, the default JVM encoding is used.

Output Parameters

filenames String List List of files retrieved from the remote FTP server.
returncode String Standard FTP protocol return code.
returnmsg String Standard FTP protocol return message.
logmsg String FTP log messages for the entire user session.

pub.client.ftp:mput

WmPublic. Transfers multiple files to a remote FTP server. (This service corresponds to the standard FTP command input.)

Input Parameters

sessionkey String Unique key for the current FTP session. The sessionkey is returned by the pub.client.ftp:login service.
transfermode String FTP file transfer mode (ascii or binary). The default is ascii.
localdir String Local directory containing the files you want to transfer to the remote FTP server (for example, c:\temp\ftpfiles).
filenamepattern String Pattern that specifies the names of the files to be transferred (for example, *.txt).
putunique String Optional. Indicates whether to send a STOR or a STOU (Store as Unique File) command to the remote FTP server. Set to:
  • true to send a STOU (Store as Unique File) command.
  • false to send a STOR command. This is the default.

Output Parameters

filenames String List List of files transferred to the remote FTP server.
returncode String Standard FTP protocol return code.
returnmsg String Standard FTP protocol return message.
logmsg String FTP log messages for the entire user session.

Usage Note

Some FTP servers, such as the Integration Server FTP Listener, do not support "putting" a unique file. When using the pub.client.ftp:put or pub.client.ftp:mput service to put a unique file to an FTP server that does not support putting a unique file, you will encounter an error like this one: 

com.wm.app.b2b.server.ServiceException: 500 'STOU': command not understood.

pub.client.ftp:put

WmPublic. Transfers a file to a remote FTP server. (This service corresponds to the standard FTP command put.)

Input Parameters

sessionkey String Unique key for the current FTP session. The sessionkey is returned by the pub.client.ftp:login service.
transfermode String FTP file transfer mode (ascii or binary). The default is ascii.
content java.io.InputStream, byte[ ], or String Data to be transferred to the remote file.
localfile String Optional. Name of the local file to be appended to the remote file. Used only if content is not specified.
remotefile String The name of the remote file.
putunique String Optional. Indicates whether to send a STOR or a STOU (Store as Unique File) command to the remote FTP server. Set to:
  • true to send a STOU (Store as Unique File) command.
  • false to send a STOR command. This is the default.

Output Parameters

returncode String Standard FTP protocol return code.
returnmsg String Standard FTP protocol return message.
logmsg String FTP log messages for the entire user session.

Usage Notes

  • Some FTP servers, such as the Integration Server FTP Listener, do not support "putting" a unique file. When using the pub.client.ftp:put or pub.client.ftp:mput service to put a unique file to an FTP server that does not support putting a unique file, you will encounter an error like this one: 

    com.wm.app.b2b.server.ServiceException: 500 'STOU': command not understood.

  • When a client invokes this service to transport a file, the FTP listener determines the content handler to use based on the file's extension. The content handler converts the file content to the input values for the service to invoke. The Integration Server_directory \instances\instance_name\lib\mime.types file contains the mappings of file extension to content type.

    By default, if this service encounters a file that has no file extension, the default content handler is used. To override this, you can configure any content handler to handle files that have no file extension. To do this, add a line in the Integration Server_directory \instances\instance_name\lib\mime.types file that specifies the content type of the files with no extension, and the ftp_no_extension key. For example, to allow a content handler to accept text/xml files that have no extension, add this line to your mime.types file: 

    text/xml          ftp_no_extension

pub.client.ftp:putCompletedNotification

WmPublic. A publishable document type that represents the document published to notify parties that an FTP put command has completed on Integration Server which is acting as the FTP server.

When a user completes an FTP put command in his or her own user directory (that is, when the STOR command is completed on the server side but the server has not yet acknowledged the client with return code 226), an event is fired to notify interested parties by publishing a document. EDI packages that subscribe to this document will retrieve the file from the server.

Parameters

username String The login user name through the FTP Listener.
filename String The absolute path name of the file.
_env Document Optional. A document reference to pub.publish:envelope which defines the structure and contents of the envelope of a published document.

Usage Notes

Integration Server publishes an instance document of pub.client.ftp:putCompletedNotification when an FTP client has completed an FTP put command on Integration Server through an FTP/S port. Because the put file is located on the Integration Server file system, only subscribers located on the same Integration Server would have access to the file. Consequently the pub.client.ftp:putCompletedNotification publishable document type is set to publish locally only and uses the IS_LOCAL_CONNECTION messaging connection alias. When Integration Server publishes an instance document for pub.client.ftp:putCompletedNotification, only subscribers located on the same Integration Server receive the document. Software AG does not recommend changing the assigned messaging connection alias.

pub.client.ftp:quote

WmPublic. Executes a given FTP command.

You can use this service to execute non-standard FTP commands.

Input Parameters

sessionkey String Unique key for the current FTP session. The sessionkey is returned by the pub.client.ftp:login service.
string String The command to be executed on the FTP server. This service submits the command exactly as it is specified in string.

Output Parameters

returncode String Standard FTP protocol return code.
returnmsg String Standard FTP protocol return message.
logmsg String FTP log messages for the entire user session.

pub.client.ftp:rename

WmPublic. Renames a file on a remote FTP server. (This service corresponds to the standard FTP command rename.)

Input Parameters

sessionkey String Unique key for the current FTP session. The sessionkey is returned by the pub.client.ftp:login service.
oldname String Fully qualified name of the file you want to rename (for example, temp/oldname.txt).
newname String New fully qualified name for the file (for example, temp/newname.txt).

Output Parameters

returncode String Standard FTP protocol return code.
returnmsg String Standard FTP protocol return message.
logmsg String FTP log messages for the entire user session.

pub.client.ftp:sessioninfo

WmPublic. Returns session information for all of the FTP servers that users are currently logged into.

Input Parameters

name Not used. Reserved for future use.

Output Parameters

sessioninfo Document List Information about the current FTP sessions. Each document in sessioninfo represents a single session and contains the following information:
  Key Description
  serverhost String Name or IP address of the FTP server.
  serverport String Port number on which the FTP server listens for requests.
  dataport String Listener port of the data transfer channel used by this session.
  username String User logged on to FTP server.
  password String Password for the FTP user specified in username.
  account String Conditional. The user name for an account on the FTP server. The account is defined in the FTP protocol to further identify the user that is identified by the username and password input variables.
  transfertype String Data transfer mode (passive or active) used by this session.
  encoding String Conditional. IANA character set used by this session. If encoding is not returned, the encoding was not explicitly set and the default JVM encoding is in effect.

Usage Notes

When you start an FTP session with pub.client.ftp:login, you can set the optional dataport parameter to specify the port number for data transfers. During the FTP session, pub.client.ftp:sessionInfo returns the dataport parameter with the port number used for data transfers.

If you do not set the dataport parameter in pub.client.ftp:login, the server uses a random port number. During the FTP session, pub.client.ftp:sessionInfo will return a 0 for the dataport parameter to indicate that the port number used for data transfers is random.

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 the default header values for the Accept and User-Agent headers as determined by the watt.net.default.accept and watt.net.userAgent respectively.

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. If one is not available, Integration Server creates one with the name “(httpclient)”. This is the default.
  • yes to create a new session for this HTTP request. Integration Server creates one with the name “(httpclient)”.
trustStore String Optional. Alias for the truststore that contains the list of certificates that Integration Server uses to validate the trust relationship. If you do not specify a truststore alias, the default truststore alias will be used.
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, TLS 1.2, or TLS 1.3. 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, TLS 1.2, or TLS 1.3. When set to no, the connection supports only TLS 1.0 which is not secure. The 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.
followRedirect String Optional. Whether the outbound request follows a redirect when receiving a response code between 300 and 400. Set to one of the following:
  • yes if the request follows the redirect.
  • no if the request does not follow the redirect and instead returns the response code and all the response headers from the original outbound request.
  • <null> if the value of the watt.net.http.followRedirect parameter determines whether or not the request follows a redirect.
Note: A value of yes or no overrides the value of the watt.net.http.followRedirect parameter.

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 and the pub.client:http service is configured to redirect, the service 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.

You can use the watt.net.http.redirect.performSSRFcheck server configuration parameter to have Integration Server perform an IP address and protocol check to prevent Server-Side Request Forgery (SSRF) when following a redirection request.

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.

The watt.server.http.setDefaultContentType server configuration parameter determines whether Integration Server sets the default Content-Type header in outbound http requests. This includes requests sent by the pub.client:http service. If the parameter value is true, Integration Server sets the default Content-Type header in the request even though the client does not include it. If the parameter value is false, Integration Server does not set the default Content-Type header, when it is originally absent in the request. However, Integration Server automatically sets the Content-Type header to "application/x-www-form-urlencoded" when data is passed to the pub.client:http service using the data/args or data/table input parameters, irrespective of the watt.server.http.setDefaultContentType parameter value.

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 NTLM, Integration Server supports authentication for both HTTP and HTTPS. Web server providing NTLM authentication must be configured to return the response header WWW-Authenticate: NTLM and optionally the header WWW-Authenticate: Negotiate. If the NTLM server returns only WWW-Authenticate: Negotiate header, then authentication cannot proceed.

When the pub.client:http service submits a password digest for authentication (that is, the auth/type field is set to Digest) and the HTTP server response includes the header field “Content-Type” but does not contain the charset parameter, Integration Server uses the value of the watt.server.netEncoding server configuration parameter as the default character set.

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.

By default, for outbound requests that require Kerberos authentication, Integration Server generates a Java Kerberos ticket using the JGSS Kerberos OID. If you need Integration Server to generate a SPNEGO-based Kerberos ticket for outbound requests that use Kerberos authentication, set the watt.security.kerberos.client.useSPNEGO server configuration parameter to true. This instructs Integration Server to generate a SPNEGO token using SPNEGO OID (Object Identifier) for all outbound requests that require Kerberos authentication.

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.

If you have a large set of data and want to compress the data before sending it via pub.client:http, then you can use pub.compress:compressData service to compress the data and then send it. For more information on pub.compress:compressData, see pub.compress:compressData.

pub.client.ldap:add

WmPublic. Inserts a new entry into the directory.

Input Parameters

url String Optional. URL of the directory server to connect to. For example ldap://servername:389.
principal String Optional. The principal for the directory server.
credentials String Optional. Credentials for the directory server.
timeout String Optional. Connection timeout in milliseconds.

The default value is 30000 milliseconds.

ldapEnv Record Optional. Key/value parameters to be passed to JNDI to further define the connection environment. See your JNDI provider documentation or the Oracle JNDI documentation for more information about parameters you can pass to JNDI.
close String Flag that specifies whether to close the connection after the service finishes. Set to:
  • yes to close the connection. This is the default.
  • no to leave the connection open and available.
dn String The distinguished name of the new entry to add to the directory.
attrs Document List Optional. LDAP attributes and their corresponding values. If an attribute is specified more than once, it will be assigned multiple values. The following example shows how to specify a user name of John Smith and one nickname.
attrsData Document Optional. LDAP attributes and their corresponding values. If an attribute is specified more than once, it will be assigned multiple values. The following example shows how to assign a user name of John Smith with two nicknames.

Output Parameters

connectionHandle Object Optional. The returned connection object. Returned only if the close parameter is set to "no".

Usage Notes

Specify only one of attrs or attrsData. If you specify both, the service uses attrs and ignores attrsData.

When close is set to yes, Integration Server removes the connectionHandle from the pipeline, but does not close the LDAP connection. To close the LDAP connection, set the watt.server.ldap.cleanContext server configuration parameter to true. For information about the watt.server.ldap.cleanContext server configuration parameter, see webMethods Integration Server Administrator’s Guide.

pub.client.ldap:bind

WmPublic. Performs an LDAP bind operation that associates the connection with the specified principal.

Input Parameters

url String URL of the LDAP server to connect to.
principal String Optional. The principal for the LDAP server.
credentials String Optional. Credentials for the LDAP server.
timeout String Optional. Connection timeout in milliseconds.

The default value is 30000 milliseconds.

ldapEnv Record Optional. Key/value parameters to be passed to JNDI to further define the connection environment. See your JNDI provider documentation or the Oracle JNDI documentation for more information about parameters you can pass to JNDI.
close String Flag that specifies whether to close the connection after the service finishes. Set to:
  • yes to close the connection. This is the default.
  • no to leave the connection open and available.

Output Parameters

connectionHandle Object Optional. The returned connection object. Returned only if the close parameter is set to "no".

Usage Notes

When close is set to yes, Integration Server removes the connectionHandle from the pipeline, but does not close the LDAP connection. To close the LDAP connection, set the watt.server.ldap.cleanContext server configuration parameter to true. For information about the watt.server.ldap.cleanContext server configuration parameter, see webMethods Integration Server Administrator’s Guide.

pub.client.ldap:cancelNotification

WmPublic. Cancels a previously created notification request.

Input Parameters

url String Optional. URL of the LDAP server to connect to.
principal String Optional. The principal for the LDAP server.
credentials String Optional. Credentials for the LDAP server.
timeout String Optional. Connection timeout in milliseconds.

The default value is 30000 milliseconds.

ldapEnv Record Optional. Key/value parameters to be passed to JNDI to further define the connection environment. See your JNDI provider documentation or the Oracle JNDI documentation for more information about parameters you can pass to JNDI.
close String Flag that specifies whether to close the connection after the service finishes. Set to:
  • yes to close the connection. This is the default.
  • no to leave the connection open and available.
dn String The distinguished name of the entry.
connectionHandle Object Optional. Connection object returned by a previously invoked LDAP service.
scope String The scope of the search. Must be "object" (only search the specified directory entry), "onelevel" (only search the immediate children of the specified directory entry), or "subtree" (search the directory, its children, and all of their children).

Output Parameters

connectionHandle Object Optional. The returned connection object. Returned only if the close parameter is set to "no".

Usage Notes

When close is set to yes, Integration Server removes the connectionHandle from the pipeline, but does not close the LDAP connection. To close the LDAP connection, set the watt.server.ldap.cleanContext server configuration parameter to true. For information about the watt.server.ldap.cleanContext server configuration parameter, see webMethods Integration Server Administrator’s Guide.

pub.client.ldap:compare

WmPublic. Compares the value of an attribute in the LDAP directory with a value specified by the service.

Input Parameters

url String Optional. URL of the LDAP server to connect to.
principal String Optional. The principal for the LDAP server.
credentials String Optional. Credentials for the LDAP server.
timeout String Optional. Connection timeout in milliseconds.

The default value is 30000 milliseconds.

ldapEnv Record Optional. Key/value parameters to be passed to JNDI to further define the connection environment. See your JNDI provider documentation or the Oracle JNDI documentation for more information about parameters you can pass to JNDI.
close String Flag that specifies whether to close the connection after the service finishes. Set to:
  • yes to close the connection. This is the default.
  • no to leave the connection open and available.
dn String The distinguished name of the entry whose attribute value you want to compare to attrValue.
connectionHandle Object Optional. Connection object returned by a previously invoked LDAP service.
attrName String Name of the attribute whose value you want to compare to attrValue.
attrValue String The string to compare against the value of the attribute identified by attrName.

Output Parameters

connectionHandle Object Optional. The returned connection object. Returned only if the close parameter is set to "no".
result String The result of the compare operation. Can be "true" or "false".

Usage Notes

When close is set to yes, Integration Server removes the connectionHandle from the pipeline, but does not close the LDAP connection. To close the LDAP connection, set the watt.server.ldap.cleanContext server configuration parameter to true. For information about the watt.server.ldap.cleanContext server configuration parameter, see webMethods Integration Server Administrator’s Guide.

pub.client.ldap:delete

WmPublic. Removes an entry from the directory.

Input Parameters

url String Optional. URL of the LDAP server to connect to.
principal String Optional. The principal for the LDAP server.
credentials String Optional. Credentials for the LDAP server.
timeout String Optional. Connection timeout in milliseconds.

The default value is 30000 milliseconds.

ldapEnv Record Optional. Key/value parameters to be passed to JNDI to further define the connection environment. See your JNDI provider documentation or the Oracle JNDI documentation for more information about parameters you can pass to JNDI.
close String Flag that specifies whether to close the connection after the service finishes. Set to:
  • yes to close the connection. This is the default.
  • no to leave the connection open and available.
dn String The distinguished name of the entry to delete.
connectionHandle Object Optional. Connection object returned by a previously invoked LDAP service.

Output Parameters

connectionHandle Object Optional. The returned connection object. Returned only if the close parameter is set to "no".

Usage Notes

This service does not flag an error if the entry is not deleted. One way to check is to use pub.client.ldap:search to search for the entry. If the entry is not found, you know it has been deleted.

When close is set to yes, Integration Server removes the connectionHandle from the pipeline, but does not close the LDAP connection. To close the LDAP connection, set the watt.server.ldap.cleanContext server configuration parameter to true. For information about the watt.server.ldap.cleanContext server configuration parameter, see webMethods Integration Server Administrator’s Guide.

pub.client.ldap:modify

WmPublic. Performs an LDAP modify operation that allows you to specify a list of attributes with corresponding lists of values to add to, replace, or remove from the directory entry.

Input Parameters

url String Optional. URL of the LDAP server to connect to.
principal String Optional. The principal for the LDAP server.
credentials String Optional. Credentials for the LDAP server.
timeout String Optional. Connection timeout in milliseconds.

The default value is 30000 milliseconds.

ldapEnv Record Optional. Key/value parameters to be passed to JNDI to further define the connection environment. See your JNDI provider documentation or the Oracle JNDI documentation for more information about parameters you can pass to JNDI.
close String Flag that specifies whether to close the connection after the service finishes. Set to:
  • yes to close the connection. This is the default.
  • no to leave the connection open and available.
dn String The distinguished name of the entry to modify.
connectionHandle Object Optional. Connection object returned by a previously invoked LDAP service.
attrs Document List Optional. For each LDAP attribute to change, specifies the attribute name, the values affected, and the action to perform on those values. The following example shows how to specify the removal of John Smith's nickname Johnny.

Output Parameters

connectionHandle Object Optional. The returned connection object. Returned only if the close parameter is set to "no".

Usage Notes

When close is set to yes, Integration Server removes the connectionHandle from the pipeline, but does not close the LDAP connection. To close the LDAP connection, set the watt.server.ldap.cleanContext server configuration parameter to true. For information about the watt.server.ldap.cleanContext server configuration parameter, see webMethods Integration Server Administrator’s Guide.

pub.client.ldap:registerNotification

WmPublic. Creates a notification (or "persistent search") that causes Integration Server to listen for LDAP events. When the notification gets an event, the specified service is called.

Input Parameters

url String Optional. URL of the LDAP server to connect to.
principal String Optional. The principal for the LDAP server.
credentials String Optional. Credentials for the LDAP server.
timeout String Optional. Connection timeout in milliseconds.

The default value is 30000 milliseconds.

ldapEnv Record Optional. Key/value parameters to be passed to JNDI to further define the connection environment. See your JNDI provider documentation or the Oracle JNDI documentation for more information about parameters you can pass to JNDI.
close String Flag that specifies whether to close the connection after the service finishes. Set to:
  • yes to close the connection. This is the default.
  • no to leave the connection open and available.
dn String The distinguished name of the entry to be monitored.
connectionHandle Object Optional. Connection object returned by a previously invoked LDAP service.
scope String The scope of the search. Must be "object" (only search the specified directory entry, "onelevel" (only search the immediate children of the specified directory entry), or "subtree" (search the directory entry, its children, and all of their children).
service String The target service to be invoked when the LDAP event is retrieved.
user String Optional. Integration Server user to run service (the target service to be invoked when the LDAP event is retrieved). If you do not specify a user, the service runs as the Default user. Make sure user has the permissions necessary to run the service. Be careful when assigning the user because no password is required when invoking a service in this manner. It is recommended that you create a special account just for invoking the target service.

Output Parameters

connectionHandle Object Optional. The returned connection object. Returned only if the close parameter is set to "no".

Usage Notes

When the pub.client.ldap:registerNotification service creates a notification, Integration Server listens for four different types of events: objectAdded, objectRemoved, objectRenamed, and objectChanged. If any one of these events is triggered, pub.client.ldap: registerNotification calls the specified target service and passes these inputs to it:

Pipeline Input Description
type One of the following depending on which event was triggered - "objectAdded", "objectRemoved", "objectRenamed", "objectChanged".
dn Distinguished name of the entry that triggered the event.
attributes Any additional LDAP attributes from the event.
oldDn Applicable only for objectRenamed event. Distinguished name of the entry before it was renamed.

If an error occurs, pub.client.ldap:registerNotification places an input called "exception" in the pipeline. This input includes details on the exception that occurred.

Some LDAP servers do not support persistent searches and therefore do not support notifications.

When close is set to yes, Integration Server removes the connectionHandle from the pipeline, but does not close the LDAP connection. To close the LDAP connection, set the watt.server.ldap.cleanContext server configuration parameter to true. For information about the watt.server.ldap.cleanContext server configuration parameter, see webMethods Integration Server Administrator’s Guide.

pub.client.ldap:rename

WmPublic. Performs an LDAP rename (move) operation allowing you to rename an entry.

Input Parameters

url String Optional. URL of the LDAP server to connect to.
principal String Optional. The principal for the LDAP server.
credentials String Optional. Credentials for the LDAP server.
timeout String Optional. Connection timeout in milliseconds.

The default value is 30000 milliseconds.

ldapEnv Record Optional. Key/value parameters to be passed to JNDI to further define the connection environment. See your JNDI provider documentation or the Oracle JNDI documentation for more information about parameters you can pass to JNDI.
close String Flag that specifies whether to close the connection after the service finishes. Set to:
  • yes to close the connection. This is the default.
  • no to leave the connection open and available.
connectionHandle Object Optional. Connection object returned by a previously invoked LDAP service.
newDn String The new name for the entry.

Output Parameters

connectionHandle Object Optional. The returned connection object. Returned only if the close parameter is set to "no".

Usage Notes

When close is set to yes, Integration Server removes the connectionHandle from the pipeline, but does not close the LDAP connection. To close the LDAP connection, set the watt.server.ldap.cleanContext server configuration parameter to true. For information about the watt.server.ldap.cleanContext server configuration parameter, see webMethods Integration Server Administrator’s Guide.

pub.client.ldap:search

WmPublic. Performs an LDAP search operation with the specified parameters and returns the results of the search.

Input Parameters

url String Optional. URL of the LDAP server to connect to.
principal String Optional. The principal for the LDAP server.
credentials String Optional. Credentials for the LDAP server.
timeout String Optional. Connection timeout in milliseconds.

The default value is 30000 milliseconds.

ldapEnv Record Optional. Key/value parameters to be passed to JNDI to further define the connection environment. See your JNDI provider documentation or the Oracle JNDI documentation for more information about parameters you can pass to JNDI.
close String Flag that specifies whether to close the connection after the service finishes. Set to:

  • yes to close the connection. This is the default.

    If the close parameter is set to "yes", the connectionHandle parameter must also be mapped.

  • no to leave the connection open and available.
dn String The distinguished name indicating the root from to begin the search.
connectionHandle Object Required if the close parameter is set to "yes", otherwise it is optional. Connection object returned by a previously invoked LDAP service.
scope String The scope of the search. Must be "object" (only search the specified directory entry), "onelevel" (only search the immediate children of the specified directory entry), or "subtree" (search the directory entry, its children, and all their children).
filter String The filter string that works with RFC 2254.
countLimit String Optional. The maximum number of results to return (0, the default, indicates no limit).
pageSize String Optional. The number of entries to return in a page.
timeLimit String Optional. The number of milliseconds to wait for the search to complete (0, the default, indicates to wait forever).
returnAttributes Record Optional. A list of attribute names to return (an empty array indicates that no results should be returned. A null array, the default, indicates that all attributes should be returned).
returnObjects String Optional. Specifies whether or not objects associated with the results should be returned. Can be "yes" or "no". The default is "no".
dereferenceLinks String Optional. Whether to return the symbolic link to the entry or the entry itself. Can be "yes"/"no". The default is "yes", which returns the entry to which the link points.
isDocumentList String Optional. Whether to return results as a list. Set to:
  • Yes to return results as a Document List containing Documents (IData). The results are returned in the resultsList output parameter.
  • No (the default) to return results as a Document containing Documents. The results are returned in the results output parameter.
ldapCookie byte[] Optional. Contains the index of the page count for the search.

Output Parameters

connectionHandle Object Optional. The returned connection object. Returned only if the close parameter is set to No.
ldapCookie byte[] Optional. Contains the index of the page count for the search.
results Document Conditional. The returned results of the search. Returned only if isDocumentList is set to No.
resultsList Document List Conditional. Returned only if isDocumentList is set to Yes.

Usage Notes

To see if no match was found, check for either:

  • A results parameter that does not contain a key-value pair.
  • A resultsList parameter with a size of 0.

When close is set to yes, Integration Server removes the connectionHandle from the pipeline, but does not close the LDAP connection. To close the LDAP connection, set the watt.server.ldap.cleanContext server configuration parameter to true. For information about the watt.server.ldap.cleanContext server configuration parameter, see webMethods Integration Server Administrator’s Guide.

pub.client.oauth:executeRequest

WmPublic. Allows Integration Server to access protected resources on a resource server using an existing Open Authentication (OAuth) access token.

When a client application requires the OAuth protocol to access a user’s protected resources on a third-party resource server (for example, Facebook, Google, Twitter, or another Integration Server), the client application must present an access token on behalf of the user in order to gain access. This service presents the access token to the resource server on behalf of the user.
Note: To use this service, you must have registered the client with the provider's authorization server and received an access token. You will use the information given to you by the provider to configure this service. For information about registering a client and obtaining an access token, refer to the provider's documentation.

Integration Server uses the Scribe API, a simple open source client implementation, to connect to OAuth providers. The Scribe API provides client implementations for many providers such as Facebook, Google, and Twitter. For information about using the Scribe API, see the Usage Notes.

Input Parameters

provider String Name of the service provider to which the client will connect. Integration Server uses this parameter to determine which OAuth client implementation in the Scribe library to use when issuing requests.

Possible values are IntegrationServer and Other (case insensitive).

Note: If set to Other, you must specify a value for providerClass.
providerClass String Name of a class that implements the org.scribe.builder.api.Api interface.

This parameter is required only when the provider parameter is set to Other.

Note: The org.scribe.builder.api.Api interface is part of the Scribe API. It facilitates the use of the pub.client.oauth:executeRequest service to connect to providers other than IntegrationServer. For more information about org.scribe.builder.api.Api see the Usage Notes.
clientID String The client identifier assigned to the client by the provider.

The clientID is used to authenticate the client to the provider. The value is assigned by the provider at registration time.

clientSecret String The secret assigned to the client when it registered with the provider.

Use this parameter to specify either the client secret or the key to the client secret in the outbound password store. For information about using the outbound password store, see the Usage Notes.

accessToken String The access token assigned to the client application when it registered with the provider.
Note: The process for obtaining the accessToken varies depending on the provider. For information about obtaining the accessToken, refer to your provider's documentation.

Use this parameter to specify either the access token or the key to the access token in the outbound password store. For information about using the outbound password store, see the Usage Notes.

acccessTokenSecret String Optional. The access token secret assigned to the client application when it registered with the provider.
Note: The process for obtaining the accessTokenSecret varies depending on the provider. For information about obtaining the accessTokenSecret, refer to your provider's documentation.

Use this parameter to specify either the access token secret or the key to the access token secret in the outbound password store. For information about using the outbound password store, see the Usage Notes.

Note: Not all providers use an access token secret. If the provider issued a secret with the token, you must specify it with the accessTokenSecret parameter.
resourceUri String The URI given to the client application when it registered with the provider.

The client application uses this URI when issuing requests to the provider. It points to the resource that the client application wants to access on the provider.

method String The HTTP method Integration Server will use to issue the request to the provider.

Possible values are get, post, put, and delete.

headers Document List Optional. One or more name/value pairs to add to the header of the request sent to the provider.

If the provider requires a request header, you must provide a value.

queryString Parameters Document List Optional. One or more name/value pairs to add to the URL of the get request sent to the provider.
bodyParameters Document List Optional. One or more name/value pairs to add to the body of the request sent to the provider.
requestDataType String Optional. If supplying data with the request to the provider, indicates the data type of the requestData parameter. If set to:
  • bytes, requestData must be a byte[]. This is the default.
  • string, requestData must be a java.lang.String.
requestData Object Optional. Data to include in the body of the request sent to the provider. The value can be a string or a byte[].
Note:

The data type of requestData must match what is specified by the requestDataType parameter. requestData is ignored if bodyParameters is specified.

responseDataType String Optional. Indicates the data type of the responseData output parameter. Set to:
  • stream to return the responseData as a java.io.InputStream. This is the default.
  • bytes to return the responseData as a byte[].
  • string to return the responseData as a java.lang.String, constructed using the default platform encoding (indicated by the file.encoding Java system property, or UTF-8 if file.encoding is not set).

Output Parameters

responseData Object The response from the provider. If the responseDataType is set to:
  • stream, responseData is a java.io.InputStream.
  • bytes, responseData is a byte[].
  • string, responseData is a java.lang.String, constructed using the default platform encoding (indicated by the file.encoding Java system property, or UTF-8 if file.encoding is not set).

Usage Notes

  • Since the values for the clientSecret, accessToken, and accessTokenSecret parameters contain sensitive data, you might want to consider storing their values in the Integration Server outbound password store. For information about services you can use to store these values in the outbound password store, see the pub.security.outboundPasswords in the About the Security Elements folder.

    If you decide to use the outbound password store, the value for each parameter (clientSecret, accessToken, and accessTokenSecret) must match the key you supplied in the pub.security.outboundPasswords services. Integration Server uses that key to retrieve the values from the store, then uses the values to send the request to the provider.

    If you decide not to use the outbound password store, Integration Server sends the request to the provider using the values you supply with the clientSecret, accessToken, and accessTokenSecret parameters.

  • You can use this service to connect to OAuth providers other than Integration Server by setting the provider parameter to Other and the providerClass parameter to the name of an org.scribe.builder.api.Api implementation. The org.scribe.builder.api.Api interface is defined in the Scribe open source API. For this approach, Software AG recommends the following:
    • That you download the Scribe API source code from the GitHub website. You can either browse the code or generate the Javadoc for the Scribe classes using the following command:

      javadoc -sourcepath your_scribe_install_dir/src/main/java -d your_destination_dir org.scribe.builder.api

    • That you check the Scribe OAuth library to see if an implementation for the provider that you want to use already exists. Scribe provides client implementation for many providers.
      Important: If an implementation already exists but the provider has changed its interface and the implementation in the Scribe library no longer works, you can either modify the implementation yourself or request an update from the author of Scribe.
    • If your provider supports OAuth 2.0, then extend org.scribe.builder.api.DefaultApi20. If your provider supports OAuth 1.0a, then extend org.scribe.builder.api.DefaultApi10a.

pub.client.oauth:​getExternalAccessToken

WmPublic. Gets the access and refresh tokens that the OAuth server generates for the Integration Server. This service can be used when Integration Server uses the OAuth authentication mechanism for services such as pub.client:smtp.

Input Parameters

grant_type String. Specify one of the following values:
  • authorization_code, to get an access token using the authorization code issued by the OAuth server.
  • refresh_token, to use the refresh token issued by the OAuth server to obtain a new access token, when the current access token expires.
token_endpoint String. The URL of the endpoint that Integration Server must use to request an access token from the OAuth server.
code String. Conditional. Get the authorization_code manually from the OAuth server. The procedure to get the authorization_code varies depending on your OAuth server. You must provide a value for this parameter only when the grant_type is authorization_code.
client_id String. The unique public identifier that the OAuth server generates for Integration Server during registration.
client_secret String. The unique string that the OAuth server provides to Integration Server during registration. It is only known to Integration Server and the OAuth server.
scope String. The e-mail server access permissions configured for Integration Server during registration. Multiple scopes can be specified by separating them with a space.
redirect_uri String. The URL that the OAuth server must use to send authentication responses to Integration Server.
  • If you are accessing Integration Server locally, enter the redirect URLs in one of the applicable formats:

    http://localhost:{port}/WmRoot/security-oauth-get-authcode.dsp or https://localhost:{port}/WmRoot/security-oauth-get-authcode.dsp

  • If you are accessing Integration Server remotely, use https://{ISHostName}:{port}/WmRoot/security-oauth-get-authcode.dsp.
refresh_token String. Conditional. The refresh token issued by the OAuth server. You can use this token to obtain new access tokens using the refresh_token authorization grant.
Note: An OAuth server issues refresh tokens based on certain conditions, which vary across OAuth servers. For example, Microsoft Azure issues refresh tokens only when the scope input parameter contains offline_access.

Output Parameters

token_type String. The type of access token issued by the authorization server. The value is Bearer.
access_token String. The access token issued by the authorization server.
expires_in String. The number of seconds for which the access token is valid.
refresh_token String. Conditional. The refresh token issued by the authorization server. You can use this token to obtain new access tokens using the same authorization grant.
Note: An OAuth server issues refresh tokens based on certain conditions, which vary across OAuth servers. For example, Microsoft Azure issues refresh tokens only when the scope input parameter contains offline_access.
scope String. Set of scopes requested by Integration Server.

pub.client:restClient

WmPublic. Creates and sends REST API requests over HTTP or HTTPS. Integration Server generates the REST connector services while creating a consumer REST API descriptor and calls this service while executing any REST connector service.

Note: This service is entirely internal to Integration Server and you must not execute this service manually.

Input Parameters

path String Relative path of the individual endpoints of the REST API.
httpMethod String Specifies the HTTP method you want to use. Valid values are:
  • get
  • post
  • put
  • delete
  • patch
  • options
  • head
body Document Optional. Body of the REST API request.
scheme String Transfer protocol that you want to use to send the REST API request. Valid values are:
  • http
  • https
produces String Optional. MIME media type the REST operation can produce and send back to the REST client. Valid values are:
  • application/xml
  • application/json
consumes String Optional. MIME media type the REST operation can consume or accept from the REST client. Valid values are:
  • application/xml
  • application/json
basePath String Optional. Base path on which the REST API is served, which is relative to the host. If base path is not included, the REST API is served directly under the host. The path must begin with a “/” (slash).
auth Document Optional. Authorization information that this service submits to the server.
  Key Description
  type String Type of authentication scheme that you want this service to use. Set to:
  • BASIC: The basic authentication scheme that is built into the HTTP protocol. You need to submit a user name and password. This is the default.
  • OAUTH: The OAuth authentication scheme according to the OAuth 2.0 Authorization Framework.
  • APIKEY: APIkey-based authentication uses a special token or key that the client needs to provide while accessing the API. The key is usually sent as a request header or a query parameter.
  username String User name that this service will submit when requesting a protected resource. Required only when type is set to Basic.
  password String Password associated with username. Required only when type is set to Basic.
  token String The access token to submit to the OAuth resource server. Required only when type is set to OAUTH.
  apiKey String The alphanumeric key that this service uses to make the API calls.
    in String Specifies whether Integration Server passes the API key in header or in query. For example, in: header or in: query.
    name String Name of the API key.
    value String Alphanumeric value of the API key.
secure Document Optional. Specifies the truststore information for certificate validation that Integration Server uses when communicating with the HTTPS server port.
  trustStoreAlias String Alias for the truststore that contains the list of certificates that Integration Server uses to validate the trust relationship. If you do not specify a truststore alias, the default truststore alias is used.
params Document Optional. All path parameters must be added under this document as key value pairs.
  Key Description
  path Document. Optional. Path parameters of the REST API request.
  query Document. Optional. Query parameters of the REST API request.
  form Document. Optional. Form parameters of the REST API request.
  header Document. Optional. Headers from the REST API request and responses.
host String Host serving the REST API.
radName String The namespace of the consumer REST API descriptor.

Output Parameters

response Object Optional. Body of the REST API response as a document or document list.
code String HTTP code of the REST API response.
phrase String HTTP message of the REST API response.

pub.client.sftp:cd

WmPublic. Changes the working directory on the remote SFTP server.

Input Parameters

sessionKey String Unique key for the current SFTP session. The sessionKey is returned by the pub.client.sftp:login service.
path String Absolute or relative path of the directory that you want as the working directory on the remote SFTP server.

Output Parameters

returnCode String Standard SFTP protocol return code.
returnMsg String Text message describing the return code.

Usage Notes

You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:chgrp

WmPublic. Changes the group ownership of one or more remote files.

Input Parameters

sessionKey String Unique key for the current SFTP session. The sessionKey is returned by the pub.client.sftp:login service.
groupId String Numeric group identifier of the group to which you want to transfer ownership of the remote files.
path String Absolute or relative path of the remote files.

Output Parameters

returnCode String Standard SFTP protocol return code.
returnMsg String Text message describing the return code.

Usage Notes

You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:chmod

WmPublic. Changes permissions of one or more remote files.

Input Parameters

sessionKey String Unique key for the current SFTP session. The sessionKey is returned by the pub.client.sftp:login service.
mode String The permission mode to apply to the remote file (for example, 777).
path String Absolute or relative path of the remote files.

Output Parameters

returnCode String Standard SFTP protocol return code.
returnMsg String Text message describing the return code.

Usage Notes

You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:chown

WmPublic. Changes the owning user of one or more remote files.

Input Parameters

sessionKey String Unique key for the current SFTP session. The sessionKey is returned by the pub.client.sftp:login service.
uid String Numeric user ID of the new owning user of the file.
path String Absolute or relative path of the remote files.

Output Parameters

returnCode String Standard SFTP protocol return code.
returnMsg String Text message describing the return code.

Usage Notes

You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:get

WmPublic. Retrieves a file from a remote SFTP server and saves it on the local machine.

Input Parameters

sessionKey String Unique key for the current SFTP session. The sessionKey is returned by the pub.client.sftp:login service.
remoteFile String Absolute or relative path of the remote file.
localFile String Optional. Absolute or relative path of the local file.

If localFile is not specified, the pub.client.sftp:get service returns the retrieved file in the output parameter contentStream (as a java.io.InputStream object).

mode String Optional. Specifies how the retrieved file is to be saved to the local file. Use this parameter only if you have specified a value for localFile. Set to:
  • overwrite to overwrite the contents of the local file with the contents of the remote file. This is the default.
  • append to append the entire contents of the remote file to the local file.
  • resume to resume writing the contents of the remote file to the local file from the point at which the writing stopped during previous SFTP sessions.

Output Parameters

returnCode String Standard SFTP protocol return code.
returnMsg String Text message describing the return code.
contentStream Object Conditional. A java.io.InputStream object.

The pub.client.sftp:get service returns the retrieved file in the output parameter contentStream (as a java.io.InputStream object) if localFile is not specified.

Usage Notes

You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:login

WmPublic. Creates a secure connection to the SFTP server using the specified user alias or configuration parameters.

Important: The sessionKey returned by this service is used by most other pub.client.sftp services.

Input Parameters

userAlias String. Optional. Alias containing the SFTP client configuration for an SFTP user account.

Integration Server creates a new session each time it logs in to the SFTP server and returns the session key to the user.

This parameter is optional. Instead of using this parameter, you can pass the login credentials and the configuration parameters using the fields within the sftpConfigurationParameters document.
Note: It is recommended to use userAlias instead of the fields within the sftpConfigurationParameters document because it is resilient to changes in configuration, such as removal of algorithms or ciphers in favor of stronger algorithms and ciphers.

If you provide inputs for both userAlias and SFTP configuration parameters, then userAlias takes precedence.

reuseSession String. Optional. Flag indicating whether or not Integration Server reuses a session that is already open for the specified user alias. Set to:
  • true, to reuse the session that is already open for the specified user alias. If a session is not open for this user alias, the pub.client.sftp:login service creates a new session and returns the key for this new session.
  • false, to create a new session for the specified user alias. This is the default.
sftpConfigurationParameters Document. Optional. The following parameters are part of this document.
sftpClientVersion String. Indicates the Integration Server SFTP client version, which can be version1 (existing) or version2 (new). Set to version2, if you want Integration Server to use the newer SFTP client that has new configuration properties, additional Key Exchange Algorithms, Machine Access Code (MAC) algorithms, and ciphers.
serverHost String. The IP address or the host name of the SFTP server.
serverPort Integer. The SFTP server port number. The port number must be within the range of 0 and 65535 (inclusive).
  hostKeyBytes Object. Optional. An array of bytes (byte[]). The host key of the SFTP server. If this field is empty, then host key verification is not strict: Integration Server ignores the value of the strictHostKeyChecking field and trusts the host key received from the SFTP server while creating a connection.
Note: You can get the host key of the SFTP server by using the pub.client.sftp.admin:getHostKey service.
userName String. The user name for the SFTP user account.
authenticationType String. Type of authentication that Integration Server uses to authenticate itself on the SFTP server. Set to:
  • password, to use password-based authentication.
  • public key, to use public key-based authentication. If the authentication type is password, then the value in the password field is used. If the authentication type is publicKey, then the value provided in the privateKeyBytes field is used.
  password String. Optional. Password of the specified SFTP user account. This is required if authenticationType is password.
privateKeyBytes Object (an array of bytes (byte[])). Optional. If the authentication type is publicKey, then provide the private key of the specified SFTP user account.
  passPhrase String. Optional. It is required if you select publicKey as the authentication type and the private key that you specified requires a passphrase
minDHKeySize Integer. Optional. The minimum DH key size. The default value is 1024. This field is not applicable if sftpClientVersion is version1.
maxDHKeySize Integer. Optional. The maximum DH key size. The default value is 8192. This field is not applicable, if sftpClientVersion is version1.
  preferredKeyExchangeAlgorithms String. Optional. A comma-separated list of preferred key exchange algorithms. If not defined, then the default list of key exchange algorithms (in the default order) is used.
Note: You can get the list of default key exchange algorithms, MAC algorithms, and ciphers by using the pub.client.sftp.admin:getDefaultAlgorithms service.
preferredCiphersS2C String. Optional. A comma-separated list of preferred server-to-client ciphers. If no value is provided, then the default list of server-to-client ciphers (in the default order) is used.
  preferredCiphersC2S String. Optional. A comma-separated list of preferred client-to-server ciphers. If a value is not provided, then the default list of client-to-server ciphers (in the default order) is used.
preferredMacC2S String. Optional. A comma-separated list of preferred client-to-server Message Authentication Code (MAC) algorithms. If a value is not provided, then the default list of client-to-server MAC algorithms (in the default order) is used.
  preferredMacS2C String. Optional. A comma-separated list of preferred server-to-client Message Authentication Code (MAC) algorithms. If a value is not provided, then the default list of server-to-client MAC algorithms (in the default order) is used.
proxyAlias String. Optional. The proxy alias through which the request should be routed. The proxy alias can be HTTP, HTTPS, or SOCKS. If a proxy alias is not specified, Integration Server makes outbound requests using each enabled proxy server alias until the request is sent successfully or all proxy servers are tried.
  maximumRetries Integer. Optional. The maximum number of times Integration Server tries to connect to the SFTP server, if login fails. The default value is 5. This field is applicable, if sftpClientVersion is version1.
connectionTimeout Integer. Optional. The time (in seconds) that Integration Server waits for a response from the SFTP server before timing out and terminating the request. The default is 0, which indicates that the session never times out.
  sessionTimeout Integer. Optional. The number of minutes that Integration Server waits before terminating an idle session. The default is 30 minutes.
compression String. Optional. Determines whether data should be compressed or not, to reduce the size of the data in transition. Integration Server supports compression using the zlib compression algorithm. The allowed values for this field are none and zlib.
Note: Use compression, only if the SFTP server to which you connect supports compression.
  compressionLevel Integer. Optional. The compression level to use, if you select zlib in the compression field. The minimum allowed value is 1 (fast, minimum compression). The maximum allowed value is 6 (slow, maximum compression). The default value is 6. This field is not applicable if sftpClientVersion is version2.
strictHostKeyChecking String. Optional. Enables host key checking. The default value is Yes.
  • If set to Yes and the host key does not match the host key provided in the hostKeyBytes field at the time of handshake, then the connection fails.
  • If set to No, then the host key is not checked during the handshake.
This field is ignored if the hostKeyBytes field is empty.

Output Parameters

sessionKey

String. On successful login, this field contains the session key.

returnCode

String. The code returned for the login command.

returnMsg String. The message returned for the login command.

Usage Notes

You cannot execute SFTP commands in parallel using the same session key.

If the watt.client.sftp.session.logoutOnServiceCompletion parameter is set to true, the FTP session created by the pub.client.sftp:login service closes automatically when the invoking service completes execution. If the value is set to false, then the pub.client.sftp:logout service must be invoked to close the FTP(S) session.

pub.client.sftp.admin:getDefaultAlgorithms

Gets the default list of algorithms supported by the Integration Server SFTP client. It returns the default values for the following parameters: keyExchangeAlgorithms, ciphersC2S, ciphersS2C, macC2S, and macS2C. The values are returned as a comma-separated list.

Input Parameters

sftpClientVersion String. Indicates the Integration Server SFTP client version, which can be version1(existing) or version2(newer). Set to version2, if you want Integration Server to use the newer SFTP client that has new configuration properties, additional Key Exchange Algorithms, Machine Access Code (MAC) algorithms, and ciphers.

Output Parameters

keyExchangeAlgorithms String. A comma-separated list of supported Key Exchange Algorithms.
ciphersC2S String. A comma-separated list of supported client-to-server ciphers.
ciphersS2C String. A comma-separated list of supported server-to-client ciphers.
macC2S String. A comma-separated list of supported client-to-server Message Authentication Code (MAC) algorithms.
macS2C String. A comma-separated list of supported server-to-client Message Authentication Code (MAC) algorithms.

pub.client.sftp.admin:getHostKey

WmPublic. Gets the host key of the SFTP server.

Input Parameters

sftpClientVersion String. Indicates the Integration Server SFTP client version, which can be version1(existing) or version2(newer). Set to version2, if you want Integration Server to use the newer SFTP client that has new configuration properties, additional Key Exchange Algorithms, Machine Access Code (MAC) algorithms, and ciphers.
serverHost String. The IP address or the host name of the SFTP server.
serverPort Integer. The SFTP server port number. The port number must be within the range of 0 and 65535 (inclusive).
preferredKeyExchangeAlgorithms String. Optional. A comma-separated list of preferred key exchange algorithms. If not defined, then the default list of key exchange algorithms (in the default order) is used.
Note: You can get the list of default key exchange algorithms, MAC algorithms, and ciphers by using the pub.client.sftp.admin:getDefaultAlgorithms service.
preferredCiphersS2C String. Optional. A comma-separated list of preferred server-to-client ciphers. If no value is provided, then the default list of server-to-client ciphers (in the default order) is used.
preferredCiphersC2S String. Optional. A comma-separated list of preferred client-to-server ciphers. If a value is not provided, then the default list of client-to-server ciphers (in the default order) is used.
preferredMacC2S String. Optional. A comma-separated list of preferred client-to-server Message Authentication Code (MAC) algorithms. If a value is not provided, then the default list of client-to-server MAC algorithms (in the default order) is used.
preferredMacS2C String. Optional. A comma-separated list of preferred server-to-client Message Authentication Code (MAC) algorithms. If a value is not provided, then the default list of server-to-client MAC algorithms (in the default order) is used.
minDHKeySize Integer. Optional. The minimum DH key size. The default value is 1024. This field is not applicable if sftpClientVersion is version1.
maxDHKeySize Integer. Optional. The maximum DH key size. The default value is 8192. This field is not applicable, if sftpClientVersion is version1.
proxyAlias String. Optional. The proxy alias through which the request should be routed. The proxy alias can be HTTP, HTTPS, or SOCKS. If a proxy alias is not specified, Integration Server makes outbound requests using each enabled proxy server alias until the request is sent successfully or all proxy servers are tried.

Output Parameters

hostKeyBytes Object. An array of bytes (byte[]). The host key in byte array format.
fingerprint String. Fingerprint of the host key.

pub.client.sftp:logout

WmPublic. Logs off the user from the SFTP server and ends the current SFTP session.

Input Parameters

sessionKey String Unique key for the current SFTP session. The sessionKey parameter is returned by the pub.client.sftp:login service.

Output Parameters

returnCode String Standard SFTP protocol return code.
returnMsg String Text message describing the return code.

Usage Notes

You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:ls

WmPublic. Retrieves the remote directory listing of the specified path. If path is not specified, the pub.client.sftp:ls service retrieves the file listing of the current remote directory. The pub.client.sftp:ls service also retrieves additional details such as permissions and ownership information.

Input Parameters

sessionKey String Unique key for the current SFTP session. The sessionKey parameter is returned by the pub.client.sftp:login service.
path String Optional. Absolute or relative path of the remote directory. If no path is specified, the pub.client.sftp:ls service retrieves the directory listing of the current remote directory.

You can use the wildcard characters asterisk (*) and question mark (?) after the last slash mark (/) to view all remote directories that match the specified path.

Output Parameters

returnCode String Standard SFTP protocol return code.
returnMsg String Text message describing the return code.
dirList Document List of directories matching the pattern specified in the path parameter. Following are the parameters in the document:
  Key Description
  fileName String Specifies the name of the remote file.
  fileSize String Specifies the size of the remote file.
  permissions String Specifies the access permission of the file (read, write, or execute).
  lastAccessTime String Specifies the time when the file was last accessed.
  lastModifiedTime String Specifies the time when the file was last modified.
  uid String Specifies the user ID of the file owner.
  gid String Specifies the group id associated with the file.
  longName String Specifies the long name of the ls entry. It contains all the parameters space separated.

Usage Notes

You cannot execute SFTP commands in parallel using the same session key.

The date format for SFTP client services is determined by the watt.server.sftp.dateStampFmt property.

pub.client.sftp:mkdir

WmPublic. Creates a new remote directory.

Input Parameters

sessionKey String Unique key for the current SFTP session. The sessionKey parameter is returned by the pub.client.sftp:login service.
path String Absolute or relative path of the remote directory where you want to create a new directory.

Output Parameters

returnCode String Standard SFTP protocol return code.
returnMsg String Text message describing the return code.

Usage Notes

You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:put

WmPublic. Transfers a file to a remote SFTP server.

Input Parameters

sessionKey String Unique key for the current SFTP session. The sessionKey is returned by the pub.client.sftp:login service.
contentStream java.io.InputStream Optional. Data to be transferred to the remote file.
localFile String Optional. Name of the local file to be appended to the remote file. Use localFile only if contentStream is not specified.
remoteFile String Optional. Absolute or relative path of the remote file to which the local file is to be appended.
mode String Optional. Specifies how the local file is to be transferred to the remote SFTP server. Set to:
  • overwrite to overwrite the contents of the remote file with the contents of the local file. This is the default.
  • append to append the entire contents of the local file to the remote file.
  • resume to resume writing the contents of the local file to the remote file from the point the writing was stopped during previous SFTP sessions.

Output Parameters

returnCode String Standard SFTP protocol return code.
returnMsg String Text message describing the return code.

Usage Notes

If you specify contentStream, you must specify remoteFile. In this case, localFile is optional.

If you specify localFile, then remoteFile and contentStream are optional. In this case, the remote file will be given the same name as the local file.

You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:pwd

WmPublic. Displays the remote working directory in the SFTP server.

Input Parameters

sessionKey String Unique key for the current SFTP session. The sessionKey is returned by the pub.client.sftp:login service.

Output Parameters

returnCode String Standard SFTP protocol return code.
returnMsg String Text message describing the return code.
path String Absolute or relative path of the working directory on the remote SFTP server.

Usage Notes

You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:rename

WmPublic. Renames a file or directory on a remote SFTP server.

Input Parameters

sessionKey String Unique key for the current SFTP session. The sessionKey is returned by the pub.client.sftp:login service.
oldPath String Fully qualified name of the file you want to rename (for example, temp/oldname.txt).
newPath String New fully qualified name for the file (for example, temp/newname.txt).

Output Parameters

returnCode String Standard SFTP protocol return code.
returnMsg String Text message describing the return code.

Usage Notes

You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:rm

WmPublic. Deletes one or more remote files on the SFTP server.

Input Parameters

sessionKey String Unique key for the current SFTP session. The sessionKey is returned by the pub.client.sftp:login service.
path String Absolute or relative path of the file you want to delete.

Output Parameters

returnCode String Standard SFTP protocol return code.
returnMsg String Text message describing the return code.

Usage Notes

You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:rmdir

WmPublic. Deletes one or more remote directories on the SFTP server.

Input Parameters

sessionKey String Unique key for the current SFTP session. The sessionKey is returned by the pub.client.sftp:login service.
path String Absolute or relative path of the directory you want to delete.

Output Parameters

returnCode String Standard SFTP protocol return code.
returnMsg String Text message describing the return code.

Usage Notes

The remote directories that you want to delete must be empty.

You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:symlink

WmPublic. Creates a symbolic link between the old path and the new path of a file.

Input Parameters

sessionKey String Unique key for the current SFTP session. The sessionKey is returned by the pub.client.sftp:login service.
oldPath String Old path of the file for which you want to create a symbolic link.
newPath String New path of the file to which the symbolic link should point.

Output Parameters

returnCode String Standard SFTP protocol return code.
returnMsg String Text message describing the return code.

Usage Notes

You cannot execute SFTP commands in parallel using the same session key.

pub.client:smtp

WmPublic. Sends a MIME-type e-mail message.

You may attach one or more content objects or files to the message.

Input Parameters

to String Optional. E-mail address of the receiver. If you specify multiple addresses, separate them with commas.
cc String Optional. E-mail addresses of additional receivers. If you specify multiple addresses, separate them with commas.
bcc String Optional. E-mail addresses of additional receivers. If you specify multiple addresses, separate them with commas.
subject String Optional. Subject of the message.
subjectCharset String Optional. The character set used to encode the MIME message headers (including subject). If subjectCharset is not specified, then charset is used. If charset is not specified, the value in the server configuration parameter watt.server.email.charset is used. If that parameter is not set, the utf-8 encoding is used.
charset String Optional. The character encoding of the body text. If you do not specify the value of charset, the value in the server configuration parameter watt.server.email.charset is used. If that parameter is not set, the utf-8 encoding is used.
from String Optional. E-mail address of the sender. If you do not specify a from value, Integration Server uses the value specified for the mail.smtp.from JVM property. If no value is specified for that property, Integration Server uses the default value, user@servername, where user is the operating system user ID, and servername is the host name of the Integration Server.
mailhost String SMTP host name for outbound messages. For example: smtp.webMethods.com

If no value is provided for the mailhost parameter, Integration Server uses the value of the Java system property mail.smtp.host set for Integration Server as the mailhost value. For more information about setting Java system properties for Integration Server, which includes modifying the custom_wrapper.conf file, see Changing Settings in the Configuration File custom_wrapper.conf.

If no value is supplied for the mailhost parameter and the mail.smtp.host Java system property is not set, the pub.client:smtp service ends with an exception.

mailhostPort String Optional. The number of the port on which the SMTP host listens. This parameter does not need to be set if the host listens on port 25 (the standard SMTP port).
auth Document Optional. Authorization information that the SMTP service will submit.
  Key Description
  type String. Specifies how you want to authenticate the user on the specified e-mail server.
  • Select Basic to authenticate the user on the specified e-mail server with only username and password. This is the default authentication type.
  • Select Bearer to authenticate the user on the specified e-mail server with the access token issued by the OAuth server.
  user String. The username that this service submits when requesting a protected resource.
  pass String. Conditional. Password associated with user. This parameter is required only when auth is Basic.
  token String. Conditional. The access token issued by the OAuth server to Integration Server. This parameter is required only when auth is Bearer. To get the access token, see to-oauth_folder.html#getTokenForEmail
secure Document Optional. Parameters specifying the security protocol and truststore information for certificate validation that Integration Server uses when communicating with the SMTP server port.
  Key Description
  transportLayerSecurity String Type of security protocol Integration Server uses when communicating with the SMTP server port. Set to:
  • none to use a non-secure mode when communicating with the port on the SMTP server. This is the default.
  • explicit to use explicit security when communicating with the port on the SMTP server. With explicit security, Integration Server establishes an un-encrypted connection to the e-mail server and then switches to the secure mode.
  • implicit to use implicit security when communicating with the port on the SMTP server. With implicit security, Integration Server always establishes an encrypted connection to the e-mail server.
  truststoreAlias String Optional. Alias for the truststore that contains the list of certificates that Integration Server uses to validate the trust relationship.If you do not specify a truststore alias, the default truststore alias will be used.
useJSSE String. Optional. Determines if the JSSE library is used to create outbound SMTP connections. This parameter can have one of the following values:
  • Blank (default). The value of the watt.net.ssl.​email.client​.useJSSE configuration property is used.

  • yes, to use the JSSE library to create a port that supports TLS 1.1, TLS 1.2, or TLS 1.3.

  • no, to use the Entrust IAIK library to create a port that supports only TLS 1.0. This is not secure.
body String Optional. The content of the message.
mimeStream java.io.InputStream Optional. MIME or S/MIME message that you want to send in the e-mail. A mimeStream is created by the pub.mime:getEnvelopeStream, pub.smime:createEncryptedData, pub.smime:createSignedData, or pub.smime.keystore:createSignedData services. It contains both headers and content. If the mimeStream already contains the from, to, and subject headers, you do not need to pass them as individual inputs to this service.
attachments Document List Optional. Attachments to the message. Each attachment defines one message part in a multi-part message.
  Key Description
  contenttype String MIME type of the message. For example: 
application/x-edi-message    
  content byte[ ], String, or java.io.InputStream Content of the message.
  filename String Name to assign to the attachment. If you do not specify attachment/content, the parameter specifies the file name of a local file to attach to the message. In other words:
  • If you specify attachment/content and attachments/filename, the service uses the value of attachments/filename as the name to assign to the attachment specified by attachment/content .
  • If you specify attachments/filename, but not attachment/content, the service attaches the local file specified by attachments/filename.
  encoding String Optional. Encoding of the message. For example: base64 or 7bit. If encoding is not specified, 7bit is used.
  charset String Optional. Character set encoding of the attachment. This value is added to the Content-Type header for the attachment. If charset is not specified, the value in the server configuration parameter watt.server.email.charset is used. If that parameter is not set, the utf-8 encoding is used.
properties Document List Optional. SMTP system properties to send to the SMTP server. This parameter overrides the settings on the watt.config.systemProperties server configuration parameter. If you omit this properties parameter, Integration Server uses the settings specified on the watt.config.systemProperties server configuration parameter.
  Key Description
  name Name of the SMTP system property.
  value Value to specify for the SMTP property.

Output Parameters

status String Final status of service.

Usage Notes

Any one of the recipient fields, that is the to, cc, or the bcc parameter, must be defined.

If you are using filename to attach a file to the message and the file is not a plain text file, you must set the contenttype and encoding. For example, to attach IntegrationServer_directory\instances\instance_name\mydir\myfile.doc to a pub.client:smtp service, you would invoke the service with the following values in attachments:

contenttype:application/msword

filename:instances/instance_name/mydir/myfile.doc

encoding:base64

pub.client:soapClient

WmPublic. Creates and sends SOAP 1.1 and SOAP 1.2 messages over HTTP, HTTPS, or JMS transports for any style/use combination supported by Integration Server.

Input Parameters

address String String specifying the URI of the web service endpoint. If you are submitting the request to an Integration Server, remember to direct it to the default SOAP processor (ws) as shown in the following example: 
http://rubicon:5555/soap/ws/example:calculator
request Document The input parameters that are to be passed to the web service.
wsdName String The name of the consumer web service descriptor that contains the operation you want to invoke.
wsdBinderName String The name of a binder that contains information to use to create and send the request. This binder must be in the consumer web service descriptor specified in wsdName.
Note: The consumer web service endpoint alias assigned to a binder indicates which proxy server Integration Server uses to send the request. For more information about proxy server usage and web service endpoint aliases, see Creating an Endpoint Alias for a Provider Web Service Descriptor for Use with HTTP/S.
wsdOperationName String The name of the operation that you want to invoke. This operation must be contained in the binder specified in wsdBinderName.
targetInputSignature String Fully qualified name of the IS document type to use to validate and encode the contents of request.
targetOutputSignature String Fully qualified name of the IS document type to use to validate and decode the output value returned by the web service.
soapHeaders Document Optional. Header documents included in the SOAP request as SOAP headers.
transportHeaders Document Optional. Transport header fields that you want to explicitly set in the request issued by the pub.client:soapClient service.

Specify a key in transportHeaders 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.

The names and values supplied to transportHeaders must be of type String. If a transport header has a name or value that is not of type String, the header will not be included in the message.

The headers that you pass in to transportHeaders vary depending on the transport used to send the SOAP message. The supplied wsdBinderName determines the transport.

For more information about specifying transportHeaders, refer to the Usage Notes.

method Document Optional. The QName of the requested procedure. The name is defined as follows:
  Key Value
  namespaceName String Namespace portion of the procedure's QName.
  localName String Local portion of the procedure's QName.
 
Note: The method parameter applies when style is RPC.
auth Document Optional. Parameters specifying the credentials that are to be submitted to the server specified in address.

Integration Server allows two levels of authorization credentials: transport level and message level.

Each element is defined as follows:

  Key Description
  transport Document Optional. Transport level authorization parameters.
    Key Description
    type String Optional. Type of authentication that the service will perform. Set to:
  • Basic to submit a user name and password. This is the default.
  • Digest to submit a password digest for authentication.
  • NTLM to use NTLM authentication.
    user String Optional. User name that this service will use if one is requested.
Note: If you have specified NTLM as type, you must specify user in the following format:

domain_name\user_name

    pass String Optional. Password that this service will submit if one is requested.
    serverCerts Document Optional. The message signer's private key and certificate chain.

privateKey Object The SOAP message signer's private key.

certChain Object List A list containing the signer's complete certificate chain, where element 0 in the list contains the signer's certificate and element 1 contains the CA's certificate.

  message Document Optional. Message level authorization parameters.
    Key Description
    user String Optional. User name that this service will use if one is requested.
    pass String Optional. Password that this service will submit if one is requested.
    serverCerts Document Optional. The message signer's private key and certificate chain.

privateKey Object The SOAP message signer's private key.

certChain Object List A list containing the signer's complete certificate chain, where element 0 in the list contains the signer's certificate and element 1 contains the CA's certificate.

    partnerCert Object Optional. The partner's complete certificate chain, where element 0 in the list contains the message signer's certificate and element 1 contains the CA's certificate.
timeout String Optional. Time (measured in milliseconds) to wait for a response from the server hosting the web service before timing out and terminating the request.

A value of 0 means Integration Server waits for a response indefinitely. If the connection to the host or JMS provider ends before Integration Server receives a response, the service ends with an exception and a status code of 408.

If this parameter is not specified, or an invalid (non-numeric) value is specified, Integration Server uses one of the following values:

  • For HTTP, Integration Server uses the value of the watt.server.SOAP.request.timeout server configuration parameter as the timeout value
  • For JMS, Integration Server uses the value of the watt.server.soapjms.request.timeout server configuration parameter as the timeout value.

For more information about watt.server.SOAP.request.timeout and watt.server.soapjms.request.timeout server configuration parameter, see webMethods Integration Server Administrator’s Guide.

Integration Server ignores timeout if the name/value pair jms.async= true is passed in to transportHeaders.

soapAction String Optional. Specifies one of the following:
  • If soapProtocol is set to SOAP 1.1 Protocol, specifies the value to which you want to set the SOAPAction HTTP header.
  • If soapProtocol is set to SOAP 1.2 Protocol, specifies the value to which you want to set the action attribute in the Content-Type header.

Integration Server ignores soapAction in either of the following situations:

  • The Content-Type header is passed in to transportHeaders and soapProtocol is set to SOAP 1.2 Protocol.
  • The soapAction header is passed into transportHeaders and soapProtocol is set to SOAP 1.1 Protocol.
soapProtocol String Optional. Indicates the SOAP protocol the service uses to send messages. Valid values are SOAP 1.1 Protocol or SOAP 1.2 Protocol.
encoding String Optional. Specifies the encoding method. Default value is UTF-8.

Integration Server ignores encoding if the Content-Type header is passed in to transportHeaders.

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, TLS 1.2, or TLS 1.3. 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, TLS 1.2, or TLS 1.3. When set to no, the connection supports only TLS 1.0, which is not secure. The 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

soapResponseData Object A SOAP object containing the SOAP response message returned by the server specified in address.
response Document Output parameters returned from the web service.
header Document Conditional. Headers from the response and request messages.

header contains the following keys:

  Key Value
  requestLines Document Conditional. Header fields from the request message. Each key in requestLines represents a line (field) in the request header. Key names represent the names of header fields. The keys' values are Strings containing the values of the fields.

The contents of the requestLines document are not identical to transportHeaders. The transport can add, remove, or alter specific headers while processing the request.

Whether or not the web service connector returns the requestLines parameter depends on the success or failure of the pub.client:soapClient service. In the case of failure, the point at which the failure occurs determines the presence of the requestLines parameter. For more information, see the usage notes for this service.

   

For the HTTP or HTTPS transports, the requestLines parameter will not contain any HTTP headers that the transport mechanism added or modified when sending the request.

For the JMS transport, each key in requestLines represents a JMS message header. Key names represent the names of header fields. Key values are Strings containing the values of the header fields. The JMS provider populates some JMS message header fields after it successfully receives the JMS message. Additionally, the Integration Server specific run-time properties (properties that begin with the “jms.” prefix) are not returned in JMS transport, each key in requestLines. The JMS provider uses the information in these properties to populate the JMS message header fields that correspond to the properties.

  lines Document Header fields from the response. Each key in lines represents a field (line) of the response header. Key names represent the names of header fields. The keys' values are Strings containing the values of the fields.

Whether or not the pub.client:soapClient service returns the lines parameter depends on the success or failure of the service. In the case of failure, the point at which the failure occurs determines the presence of the lines parameter. For more information, see the usage notes for this service.

For the HTTP or HTTPS transports, the lines parameter contains any HTTP/HTTPS headers present in the response.

For the JMS transport, the lines parameter contains the JMS headers present in the response.

  status String Status code from the request, returned by the underlying transport. response. For more information about status codes returned by the service, see the usage notes for this service.
  statusMessage String Status message returned by the transport. For more information about status messages returned by the service, see the usage notes for this service.
soapStatus String Flag indicating whether the SOAP request message was processed successfully.
  A value of... Indicates that...
  0 The remote server successfully processed the SOAP request and returned a SOAP response message.
  1 The remote server returned a SOAP fault, indicating that the SOAP request was received but was not processed successfully.
  2 The server returned an error that was not a SOAP fault. This indicates that some type of HTTP error occurred (often, an HTTP 404). You can check the status field in header to determine the type of HTTP error that occurred.

Usage Notes

If the address begins with https:, you must specify a private key and certificate chain. You can use the auth/transport/serverCerts parameters to do so. If you do not specify them using the auth/transport/serverCerts parameters, pub.client:soapClient uses the web service endpoint alias specified in the binder. If the endpoint alias does not have an associated private key and certificate chain, then the default outbound SSL certificate settings are used to authenticate the resources.

Note: pub.client:soapClient supports NTLM protected web service over HTTP as well as HTTPS.

As part of executing pub.client:soapClient, Integration Server executes any service handlers assigned to the consumer web service descriptor specified in wsdName.

When a document type contains a String variable that represents a required attribute (meaning that the variable name starts with the "@" symbol and the Required property is set to True in Designer) and the input document does not contain the required attribute, Integration Server adds an empty attribute during document encoding. For example, if the document type contains a required String variable named @myAttribute but @myAttribute is missing from the input document, Integration Server adds myAttribute ="" to the XML document.

Note: Because empty xmlns attributes are invalid, if the document type contains a required String variable named @xmlns and the input document does not specify a value for the @xmlns attribute, Integration Server does not add xmlns="" to the XML document.

Keep the following points in mind when specifying transportHeaders for HTTP or HTTPS:

  • For any header name/value pair supplied in transportHeaders, Integration Server simply passes through the supplied headers and does not perform any validation for the headers.

  • If you do not set transportHeaders or do not specify the following header fields in transportHeaders, Integration Server adds and specifies values for the following header fields:

    • Accept
    • Authorization
    • Connection
    • Content-Type
    • Host
    • SOAPAction (Added when soapProtocol is SOAP 1.1 only)

    • User-Agent

      Important: Pass in the preceding headers to transportHeaders only if you are an experienced web service developer. Incorrect header values can result in failure of the HTTP request.
  • If you specify Content-Type in transportHeaders, Integration Server ignores the value of the encoding input parameter.
  • If you specify Content-Type in transportHeaders and the soapProtocol input parameter is set to SOAP 1.2, Integration Server ignores the value of the soapAction input parameter.
  • If you specify the SOAPAction header in transportHeaders and the soapProtocol input parameter is set to SOAP 1.1 Protocol, Integration Server ignores the value of the soapAction input parameter.
  • If MTOM processing converts any portion of the SOAP request to an MTOM/XOP attachment, it will overwrite the Content-Type value supplied to the transportHeaders input.
  • Integration Server sets the value of Content-Length automatically and overrides any value passed in to transportHeaders.
  • Integration Server automatically adds the Cookie header to the HTTP header and supplies any cookies established between Integration Server and the HTTP server with which it is interacting. If you supply the Cookie header to transportHeaders, Integration Server prepends the values you supply to the already established Cookie header value.
  • The following headers are considered to be standard and require the specified capitalization: Accept, Authorization, Connection, Content-Type, Cookie, Host, SOAPAction, User-Agent.
  • Using capitalization other than that which is specified results in undefined behavior.
  • Supplying duplicate entries for any standard header results in undefined behavior.

Keep the following points in mind when specifying transportHeaders for JMS:

  • Specify a key in transportHeaders 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.
  • You can specify the following JMS message header fields in transportHeaders:
    • JMSCorrelationID
    • JMSType
    Note: The JMSCorrelationID and JMSType names are case-sensitive.
  • You can specify the following JMS-defined properties in transportHeaders:
    • JMSXGroupID
    • JMSXGroupSeq

      If the value of JMSXGroupSeq is not an integer, Integration Server ignores the name/value pair and does not place it in the message header.

      Note: The JMSXGroupID and JMSXGroupSeq names are case-sensitive.
  • The “JMSX” prefix is reserved for JMS-defined properties. If a header whose name starts with “JMSX” is passed into transportHeaders and it is not named JMSXGroupID or JMSXGroupSeq, Integration Server generates a fault and returns it to the service.
  • You can set any provider-specific property whose name starts with “JMS_” in transportHeaders. Integration Server maps a supplied name/value pair whose name starts with “JMS_” directly to a JMS message property. Because the JMS standard reserves the prefix “JMS_<vendor_name>” for provider-specific properties, Integration Server does not validate the name or value of this content.
    Note: The JMS provider determines which provider-specific properties to accept and include in the JMS message properties. For more information about provider-specific message properties how the JMS provider handles them, review the JMS provider documentation.
  • You can use transportHeaders to specify run-time properties that affect the values of the JMS message and JMS message headers. The following table identifies these properties and indicates the JMS message header fields affected by each property.
    Property Name Description
    jms.async Indicates whether this is a synchronous or asynchronous request/reply. This run-time property does not affect a JMS message header field.
    Note: This property applies when pub.client:soapClient calls an operation with an In-Out message exchange pattern only
      Value Description
      true Indicates this is an asynchronous request/reply. Integration Server does not wait for a response message before executing the next step in the flow service.

    If jms.async is true, Integration Server ignores the timeout input parameter.

      false Default. Indicates this is a synchronous request/reply. Integration Server waits for a response before executing the next step in the flow service.
    jms.deliveryMode Specifies the message delivery mode for the message. Integration Server uses this value to set the JMSDeliveryMode header.
         
      Value Description
      PERSISTENT Indicates the request message is persistent.
      2 Default. Indicates the request message is persistent.
      NON_PERSISTENT Indicates the request message is not persistent.
      1 Indicates the request message is not persistent.
     
    Note: If the jms.deliveryMode is not one of the above values, Integration Server ignores the name/value pair and uses the default value of 2.
    jms.messageType Message type identifier for the message. Integration Serveruses this value to set the JMSType header.
    Specify one of the following:
    • BytesMessage
    • TextMessage
    Note: If thejms.messageTypevalue is not BytesMessage or TextMessage, Integration Server ignores the name/value pair and uses the default value of BytesMessage
    jms.timeToLive Length of time, in milliseconds, that the JMS provider retains the message. A value of 0 means that the message does not expire.

    The JMS provider uses this value to set the JMSExpiration header in the sent JMS message.

    Note: If the jms.timeToLivevalue is not a valid Long, Integration Server ignores the property and uses the default value of 0.
    jms.priority Specifies the message priority. The JMS standard defines priority levels from 0 to 9, with 0 as the lowest priority and 9 as the highest.

    Integration Server uses this value to set the JMSPriority header.

    If the jms.priority value is not a value between 0 to 9, Integration Server ignores the property and uses the default value of 4.

  • The lowercase “jms.” prefix is reserved for run-time properties used by Integration Server. If a header starts with “jms.”and is not one of the “jms.” properties defined by Integration Server, Integration Server ignores the property.

The header information returned when pub.client:soapClient executes an operation in a web service descriptor created on Integration Server version 8.2 or later varies depending on the following:

  • The transport used to send the SOAP message which is determined by the wsdBinderName
  • The success or failure of the pub.client:soapClient service and if failure occurs, the point at which that happens
  • The message exchange pattern for the operation specified in wsdOperationName
Note: The same conditions that affect the contents of header also determine whether the soapResponseData contains a SOAP response, a SOAP fault, or an exception.

The following table identifies the basic success and failure scenarios when pub.client:soapClient service executes an operation in a web service descriptor created on Integration Server version 8.2 or later and the header information that would be returned in each scenario. The table also indicates whether the scenario results in a SOAP response, SOAP fault, or exception being returned in soapResponseData.

Note: JMS status codes as well as the status code 900 are specific to Integration Server and are not derived from any standard.
Use Case
The pub.client:soapClient service fails before sending the SOAP request.
Parameter Description
status 900
statusMessage Error occurred while preparing SOAP request
requestLines returned? Yes, if the web service connector created the SOAP request successfully but execution failed before sending the request.
lines returned? No
soapResponseData Contains an exception.
Use Case
The pub.client:soapClient service fails while sending the SOAP request.
Parameter Description
status For HTTP, the status code will be the value returned by the HTTP server.

For JMS, the status code will be 400.

statusMessage For HTTP, the status message will be the message returned by the HTTP server.

For JMS, the status message will be: Error occurred while sending request to JMS provider.

requestLines returned? Yes
lines returned? For HTTP, lines may be returned. For example, when the provider returns a status code in the 300 range or 400 range, it is possible that the provider populated response headers.

For JMS, lines will not be returned.

soapResponseData Contains an exception.
Use Case
The pub.client:soapClient service fails while sending the SOAP request because a timeout occurs.
Parameter Description
status 408
statusMessage Timeout
requestLines returned? Yes
lines returned? No
soapResponseData Contains an exception.
Use Case
The pub.client:soapClient service executes successfully.
Parameter Description
status For HTTP, the status code will be the value returned by the HTTP server. The status code will typically be in the 200 range.

For JMS and an In-Out or Robust In-Only operation, the status code will be 200.

For JMS and an In-Only operation, the status code will be 202.

statusMessage For HTTP, the status message will be the message returned by the HTTP server.

For JMS, the status message will be: OK

requestLines returned? Yes
lines returned? Depends on the message exchange pattern (MEP) of the operation.

For In-Only and Robust In-Only, lines is not returned.

For In-Out, lines is returned.

soapResponseData Contains the SOAP response for In-Out MEP only.
Use Case
The pub.client:soapClient service executes successfully but the JMS provider is not available, causing Integration Server to write the JMS message to the client side queue.
Note: This use case applies to JMS only. It occurs only when the client side queue is enabled for the JMS binder specified in wsdBinderName.
Parameter Description
status 300
statusMessage Message written to the client side queue.
requestLines returned? Yes
lines returned? No.
soapResponseData Not returned.
Use Case
The pub.client:soapClient service sends the SOAP request successfully but receives a SOAP fault from the web service provider.
Parameter Description
status For HTTP, the status code will be the value returned by the HTTP server. The status code will typically be in the 500 range.

For JMS, the status code will be 500.

statusMessage For HTTP, the status message will be the message returned by the HTTP server.

For JMS, the status message will be: SOAP Fault

requestLines returned? Yes
lines returned? No
soapResponseData Contains an SOAP fault.
Use Case
The pub.client:soapClient service fails while processing the SOAP response.
Parameter Description
status 900
statusMessage Error occurred while processing SOAP request
requestLines returned? Yes
lines returned? Yes
soapResponseData Contains an exception.

When invoking pub.client:soapClient to execute an In-Out operation asynchronously using SOAP over JMS, keep the following information in mind:

  • For an asynchronous request/reply, you must pass jms.async= true into the transportHeaders input parameter.
  • To instruct Integration Server to write the request message for an asynchronous request/reply to the client side queue when the JMS provider is not available, the JMS binder must be configured to use the client side queue. Specifically, in the consumer web service descriptor, the Use CSQ property for the JMS binder must be set to true.
  • When pub.client:soapClient sends an asynchronous request it executes to completion without populating any response headers for the lines output parameter.
  • Even though pub.client:soapClient does not wait for a SOAP response, it will execute the response handlers assigned to the consumer web service descriptor. However, the messageContext that is available to handler services will not contain a response message. Handler services that do not operate on the response message and instead perform activities such as clean up following a request handler invocation might still provide value for an asynchronous request/reply.
  • If you want to retrieve the SOAP response from the provider, you need to receive and process the response with a custom solution. This might include using standard JMS trigger or an on-demand message consumer to receive the message and then using the pub.soap* services to process the SOAP message.
    Note: Using a JMS trigger or message consumer to receive the response bypasses any response handlers or policies applied to the SOAP response, including any WS‑SecurityPolicy. The SOAP response does not undergo any processing provided by the response handlers or policies attached to the consumer web service descriptor. Any response messages that require decryption or authentication will not be usable. Consequently, do not use an asynchronous request/reply to invoke an In-Out operation to which the WS-SecurityPolicy is applied.

When using pub.client:soapClient to execute a Robust In-only operation using SOAP over JMS, keep the following information in mind:

  • For a consumer web service descriptor, Integration Server provides partial support for Robust In-Only operations with a SOAP over JMS binding. When Integration Server creates a consumer web service descriptor from a WSDL that contains a Robust In-Only operation and that operation is defined as part of a portType with a SOAP over JMS binding, Integration Server populates the reply destination in the JMS message header (the JMSReplyTo header field) but otherwise treats the operation as In-Only.

    Specifically, pub.client:soapClient will not produce or wait for any output besides the transportInfo parameter. If an exception occurs while the provider processes the request, the web service connector does not retrieve or process the SOAP response.

  • If you want to retrieve a SOAP response (which includes the SOAP fault) that the provider sends when an exception occurs during web service execution, you need to receive and process the response with a custom solution. This might include using a standard JMS trigger or an on-demand message consumer to receive the message and using the pub.soap* services to process the SOAP message.
    Note: Using a JMS trigger or message consumer to receive the response bypasses any policies applied to the SOAP response and any response handlers assigned to the consumer web service descriptor. The SOAP response does not undergo any processing provided by the response handlers or policies attached to the consumer web service descriptor. Any response messages that require decryption or authentication will not be usable. Consequently, do not use an asynchronous request/reply to invoke an In-Out operation to which the WS-SecurityPolicy is applied.

If the Docker image for a Microservices Runtime excludes the web services functionality, then the Docker image for the Microservices Runtime running in the Docker container cannot execute the pub.client:soapClient service. Attempts to execute pub.client:soapClient fail with a ServiceException.

See Also

pub.client:soapHTTP

WmPublic. Deprecated - There is no replacement service.

Submits a SOAP message to a server via HTTP or HTTPS.

Input Parameters

soapRequestData Object SOAP message that is to be sent. This object must be produced with the services in the soap folder. See the Usage Notes for more information.
address String URL to which you want the SOAP message sent. For example: 
https://servername:5555/soap/default
auth Document Optional. Parameters specifying the credentials that are to be submitted to the server specified in address. Each element is defined as follows:
  Key Description
  type String Type of authentication that the service will perform. Leave this field blank, as the only option currently available is basic HTTP authentication.
  user String User name that this service will use if one is requested.
  pass String Password that this service will submit if one is requested.
validateSOAP String Optional. Indicates whether or not the response message is to be validated against the SOAP schema. Set to:
  • true to validate the response message and throw an exception if the response does not conform to the SOAP schema.
  • false to bypass the validation process. This is the default.
SOAPAction String Optional. Value to which you want to set the SOAPAction HTTP header.
contentType String Optional. Specifies the value of Content-Type in the HTTP header. Set to:
  • text/xml; charset="utf-8" to specify the content type as XML and the character encoding of the message text as UTF-8. This is the default.
  • text/xml to specify the content type as XML. Since the charset parameter is not specified, the character encoding of the message text defaults to US-ASCII.
loadAs String Optional. Specifies the format of the soapResponseData. Default value is stream for an HTTP service and byteArrayStream for an HTTPS service. Set to:
  • stream to return the body of the response as a java.io.InputStream. Use this option when you will invoke an HTTP web service. This is the default for an HTTP service.
  • 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).
  • byteArrayStream to have the response stream fully read and converted to java.io.ByteArrayStream. This prevents data loss or a truncated SOAP response if the connection closes prematurely. Use this option when you will invoke an HTTPS web service. This is the default for an HTTPS service.
timeout String Optional. Time (measured in milliseconds) to wait for a response from the remote server before timing out and terminating the request. The default value is to wait forever.
encoding String Default character set for encoding SOAP message. Specify an IANA-registered character set (for example, ISO-8859-1). The default is UTF-8.

The encoding parameter is used to override the encoding determined by the watt.server.netEncoding server configuration parameter. For more information about watt.server.netEncoding, see webMethods Integration Server Administrator’s Guide .

Output Parameters

soapResponseData Object The SOAP response message returned by the server specified in address.
header Document Conditional. Headers from the HTTP response. Will contain the following keys:
  Key Description
  lines Document Header fields from the HTTP response. Each key in lines represents a field (line) of the response header. Key names represent the names of header fields. The keys' values are Strings containing the values of the fields.
  status String Status code from the HTTP response.
  statusMessage String Status message from the HTTP response.
soapStatus String Flag indicating whether the SOAP request message was processed successfully.
  A value of... Indicates that...
  0 The remote server successfully processed the SOAP request and returned a SOAP response message.
  1 The remote server returned a SOAP fault, indicating that the SOAP request was received but was not processed successfully.
  2 The server returned an error that was not a SOAP fault. This indicates that some type of HTTP error occurred (often, an HTTP 404). You can check the status element in header to determine the type of HTTP error that occurred.

Usage Notes

This pub.client:soapHTTP service is deprecated. There is not a replacement service.

If address begins with https:, you can use pub.security.keystore:setKeyAndChain to specify the certificate chain. If you do not specify a certificate chain, pub.client:soapHTTP uses the default outbound SSL certificate settings to authenticate the resources.

To send a SOAP message with this service, you must first generate an empty SOAP object with the pub.soap.utils:createSoapData service and then populate it using services such as pub.soap.utils:addHeaderEntry and pub.soap.utils:addBodyEntry.

If the Docker image for a Microservices Runtime excludes the web services functionality, then the Docker image for the Microservices Runtime running in the Docker container cannot execute the pub.client:soapHTTPservice. Attempts to execute pub.client:soapHTTP result in a ServiceException.

See Also

pub.client:soapRPC

WmPublic. Deprecated - There is no replacement service.

Submits a SOAP remote procedure call via HTTP or HTTPS.

Input Parameters

address String String specifying the numeric address or name of the server on which the remote procedure resides. If you are submitting the request to an Integration Server, remember to direct it to the RPC processor as shown in the following example: 
http://rubicon:5555/soap/rpc
reqParms Document The input parameters that are to be passed to the remote procedure. For example, if you wanted to pass three String parameters, acct, amt, and org, containing the values Cash, 150.00, and Sales, reqParms would contain the following:
  Key Value
  acct Cash
  amt 150.00
  org Sales
method Document The QName of the requested procedure where:
  Key Value
  namespaceName String Namespace portion of the procedure's QName.
  localName String Local portion of the procedure's QName.
auth Document Optional. User name and password that are to be submitted to the server specified in address.
  Key Value
  type String Type of authentication that the service will perform. Leave this field blank, as the only option currently available is basic HTTP authentication.
  user String User name that this service will use if one is requested.
  pass String Password that this service will submit if one is requested.
targetInputSignature String Optional. Fully qualified name of the IS document type to use to validate and encode the contents of reqParms.
targetOutputSignature String Optional. Fully qualified name of the IS document type to use to validate and decode the output value returned by the remote procedure.
SOAPAction String Optional. Value to which you want to set the SOAPAction HTTP header.
contentType String Optional. Specifies the value of Content-Type in the HTTP header. Set to:
  • text/xml; charset="utf-8" to specify the content type as XML and the character encoding of the text as UTF-8. This is the default.
  • text/xml to specify the content type as XML. Since the charset parameter is not specified, the character encoding of the text defaults to US-ASCII.
encoding String Optional. Specifies the encoding method. Default value is UTF-8.
loadAs String Optional. Specifies the format of the soapResponseData. Default value is stream. Set to:
  • stream to return the body of the response as a java.io.InputStream. Use this option when you will invoke an HTTP web service. This is the default.
  • byteArrayStream to have the response stream fully read and converted to java.io.ByteArrayStream. This prevents data loss or a truncated SOAP response if the connection closes prematurely. Use this option when you will invoke an HTTPS web service.
timeout String Optional. Time (measured in milliseconds) to wait for a response from the server hosting the remote procedure before timing out and terminating the request. The default value is to wait forever.

Output Parameters

soapResponseData Object A SOAP object containing the SOAP response message returned by the server specified in address.
respParms Document Output parameters returned by the remote procedure. For example, if the remote procedure returned two String parameters, status and balance, containing the values closed and -4.95, respParms would contain the following:
  Key Value
  status closed
  balance -4.95
header Document Conditional. Headers from the HTTP response. Will contain the following keys:
  Key Value
  lines Document Header fields from the HTTP response. Each key in lines represents a field (line) of the response header. Key names represent the names of header fields. The keys' values are Strings containing the values of the fields.
  status String Status code from the HTTP response.
  statusMessage String Status message from the HTTP response.
soapStatus String Flag indicating whether the SOAP request message was processed successfully.
  A value of... Indicates that...
  0 The remote server successfully processed the SOAP request and returned a SOAP response message.
  1 The remote server returned a SOAP fault, indicating that the SOAP request was received but was not processed successfully.
  2 The server returned an error that was not a SOAP fault. This indicates that some type of HTTP error occurred (often, an HTTP 404). You can check the status field in header to determine the type of HTTP error that occurred.

Usage Notes

The pub.client:soapRPC service is deprecated. There is not a replacement service.

To disable output validation for pub.client:soapRPC, set the watt.server.soap.validateResponse server configuration parameter to false. For more information about watt.server.soap.validateResponse, see webMethods Integration Server Administrator’s Guide.

If address begins with https:, you can use pub.security.keystore:setKeyAndChain to specify the certificate chain. If you do not specify a certificate chain, pub.client:soapRPC uses the default outbound SSL certificate settings to authenticate the resources.

If the Docker image for a Microservices Runtime excludes the web services functionality, then the Docker image for the Microservices Runtime running in the Docker container cannot execute the pub.client:soapRPC. Attempts to execute the pub.client:soapRPC service end with a ServiceException.

See Also

pub.client:websocket

WmPublic. Establishes a WebSocket connection to the URL captured in the identified WebSocket client endpoint.

Input Parameters

nsName String Namespace name of the WebSocket client endpoint.
headers Record Optional. Headers that are part of the HTTP request used to establish the WebSocket connection.
  Key Description
  name The name of the header.
  value The value of the header
   
auth String Authentication information that the pub.client:websocket service will submit to the URL in WebSocket client endpoint.
  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 username and password.

  username String Username that this service will submit when requesting a protected resource.
  password String Password associated with user.
   
secure String Optional. Parameters specifying the truststore information for certificate validation that Integration Serveruses when communicating with the WebSocket server port:
  Key Description
  truststoreAlias String Alias for the truststore that contains the list of certificates that Integration Server uses to validate the trust relationship. If you do not specify a truststore alias, the default truststore alias specified in the watt.security.trustStoreAlias property will be used.
connectTimeout String Optional. Time (measured in milliseconds) the server will wait to connect to the remote server before timing out and terminating the request.

If a value for connectTimeout is not specified, 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, the server will wait 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.

cookies String Optional. The cookies which are to be part of the HTTP request used to establish a WebSocket connection.
extensions String Optional. The extensions which are to be part of the HTTP request used to establish a WebSocket connection.
subProtocols String Optional. The subprotocols which are to be part of the HTTP request used to establish a WebSocket connection.

Output Parameters

sessionId String Session ID to identify the WebSocket session.