Integration Server 10.11 | Built-In Services Reference Guide | Remote Folder | Summary of Elements in this Folder | pub.remote:invoke
 
pub.remote:invoke
WmPublic. Invokes a service on a remote webMethods Integration Server.
The remote server is identified by an alias, which is configured on the Remote Servers tab in the Integration Server Administrator. Connection and authentication to the remote server is managed transparently to the caller of this service.
All current pipeline inputs are passed to the remote service. To improve performance and minimize the amount of data sent over the wire, scope the pipeline to a separate document or drop unneeded fields before invoking this service. The same advice applies to the output values of the remote service because all values returned from the service are sent over the wire in response to the caller.
Input Parameters
$alias
String Name of the target server on which to invoke the specified service. This name and its associated connection attributes are defined on the Create Remote Server Alias page in the Integration Server Administrator.
Note:
If you protect the alias using an Access Control List, the user invoking invoke must be a member of this list or the invocation will fail.
$service
String Fully qualified name of the service to invoke on the remote server, in the format folderName.folderName:serviceName (for example: wm.server:ping).
$scope
String Flag that specifies how the session to the remote server should be managed. Set to:
*SESSION to store the remote session in the current user session. This is the default.
Further calls by the same user to pub.remote:invoke for the same server alias reuse the existing remote session with the server.
Stateful interactions with the remote server are maintained and protected inside the current user's session.
When the current user disconnects, the remote session expires, or the local server is shut down, the remote session is automatically disconnected.
*GLOBAL to tore the remote session in a shared pool of sessions. If another user invokes a service on the same remote server with GLOBAL scope, the session will be reused.
Stateful interactions with the remote server could be destroyed by other users' invocations.
When the remote session expires due to inactivity or the local server is shut down, the remote session is automatically disconnected.
$close
String Optional. Flag to indicate whether Integration Servercloses the connection to the remote server after the service invocation or keeps the connection open until it times out. Set to:
*true to close the connection to the remote server immediately after the service invocation.
*false to keep the connection open until it times out. This is the default.
Note:
If the watt.server.trigger.reuseSession server configuration parameter is set to true, Integration Server expects trigger sessions to be reused and the connection to the remote server to remain open. Hence, if watt.server.trigger.reuseSession parameter is set to true, Integration Server will ignore the value of the $close parameter when a trigger service for a webMethods messaging trigger executes the pub.remote:invoke service.
$clusterRetry
String Optional. Flag to indicate whether Integration Servershould retry a failed connection request on other Integration Servers in the cluster. Set to:
*true to retry a request automatically on other Integration Servers in the cluster if the initial attempt to connect to a remote Integration Server fails. Integration Serverwill attempt to connect to each Integration Servers in the cluster until the connection is made or all Integration Servers have been tried with no success. If the service cannot connect to another Integration Server in the cluster, the service tries to connect to the retry server specified in the alias definition for the remote server.
*false to issue an error if the attempt to connect to the remote Integration Server fails. If the alias definition for the remote server specifies a retry server, the service tries to connect to that server.
Note:
Once a connection to a remote server has been established, that connection is cached and reused. The $clusterRetry setting is established when the connection is first created and used. Subsequent invokes to the same remote server will not change the $clusterRetry setting, even if a different value is passed in the pipeline. Client applications must determine whether or not they want cluster retries before establishing the connection.
Output Parameters
Returns the output of the invoked service. The output signature matches the output signature of the invoked service.
When the pub.remote:invoke service executes, Integration Server creates a Pinger thread that sends a wm.server.ping request to the remote Integration Server every n seconds while the connection to the remote Integration Server is active. The time interval, n, is either one third of the wait time set in the Keep Alive Timeout field for the remote server alias, or, if that is not specified, the value of the server configuration parameter watt.server.ping.
Usage Notes
If pub.remote:invoke does not receive a response within the timeout period specified in the server's watt.net.timeout parameter, it will throw an exception. For information about the watt.net.timeout parameter, see webMethods Integration Server Administrator’s Guide.