Remote Folder

You use the elements in the remote folder to invoke services on other webMethods Integration Server.

You can also use remote services for guaranteed delivery transactions. For more information about guaranteed delivery transactions, see the Guaranteed Delivery Developer’s Guide and webMethods Integration Server Administrator’s Guide.

Summary of Elements in this Folder

The following elements are available in this folder:

Element Package and Description
pub.remote:invoke WmPublic. Invokes a service on a remote webMethods Integration Server.
pub.remote.gd:end WmPublic. Ends a guaranteed delivery transaction.
pub.remote.gd:getStatus WmPublic. Returns the status of the guaranteed delivery transaction.
pub.remote.gd:invoke WmPublic. Invokes the service for a guaranteed delivery transaction by making a synchronous call to a remote webMethods Integration Server.
pub.remote.gd:restart WmPublic. Restarts an expired guaranteed delivery transaction.
pub.remote.gd:retrieve WmPublic. Retrieves the results of a guaranteed delivery transaction submitted asynchronously or synchronously to a remote webMethods Integration Server.
pub.remote.gd:send WmPublic. Makes a guaranteed one-way call (fire-and-forget) to the webMethods Integration Server to invoke a service for which no output is needed or expected.
pub.remote.gd:start WmPublic. Starts a guaranteed delivery transaction.
pub.remote.gd:submit WmPublic. Invokes a service for a guaranteed delivery transaction by making an asynchronous call to a remote webMethods Integration Server.

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 screen 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.

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.

pub.remote.gd:end

WmPublic. Ends a guaranteed delivery transaction.

Input Parameters

tid String Transaction ID of the transaction you want to end.

Output Parameters

None.

Usage Notes

This service is used to eliminate a guaranteed delivery transaction from the jobstore.

pub.remote.gd:getStatus

WmPublic. Returns the status of the guaranteed delivery transaction.

Input Parameters

tid String Transaction identification number.

Output Parameters

status String Current status of the transaction. status can have one of the following values:
  • NEW indicates that the transaction is new.
  • PENDING indicates that the transaction is pending.
  • DONE indicates that the transaction is completed.
  • FAILED indicates that the transaction expired because the time-to-live or the retry limit has been exceeded.
  • UNKNOWN indicates that the transaction identification number in tid is not recognized.

Usage Notes

Use the pub.remote.gd:restart service to restart a FAILED (expired) guaranteed delivery transaction.

pub.remote.gd:invoke

WmPublic. Invokes the service for a guaranteed delivery transaction by making a synchronous call to a remote webMethods Integration Server.

Input Parameters

service String Name of the service to be run on the remote webMethods Integration Server.
tid String Transaction identification number for the service.
inputs Document Optional. Document (IData object) containing the inputs for the service.

Output Parameters

results Document Conditional. Document (IData object) containing the pipeline as it exists after the service is invoked.

Usage Notes

To use an asynchronous call to the server to invoke a service for a guaranteed delivery transaction, use the pub.remote.gd:submit service.

If the remote server does not respond within the timeout limit specified in this server's watt.net.timeout setting, the Integration Server treats it as a failed attempt and retries the request.

pub.remote.gd:restart

WmPublic. Restarts an expired guaranteed delivery transaction.

Input Parameters

tid String Transaction identification number for the guaranteed delivery transaction you want to restart.

Output Parameters

None.

Usage Notes

If a guaranteed delivery transaction failed because of server or network failure, use this service to restart the transaction without resubmitting it.

pub.remote.gd:retrieve

WmPublic. Retrieves the results of a guaranteed delivery transaction submitted asynchronously or synchronously to a remote webMethods Integration Server.

Input Parameters

tid String Transaction identification number.
block String Optional. Flag that specifies whether to block or poll for the results of the transaction. Set to:
  • true to wait until the invoked service completes before retrieving results. This is also known as blocking mode. This is the default.
  • false to retrieve the results immediately, whether or not the invoked service is completed. This is also known as polling mode.

Output Parameters

results Document Conditional. Document (IData object) containing the results of the service in the guaranteed delivery transaction.

Usage Notes

If block is false, and the results of the transaction are still pending when this service executes, the results are returned as null.

pub.remote.gd:send

WmPublic. Makes a guaranteed one-way call (fire-and-forget) to the webMethods Integration Server to invoke a service for which no output is needed or expected.

Input Parameters

service String Service to be run on the remote Integration Server.
tid String Transaction identification number for the service.
inputs Document Optional. Document (IData object) containing the inputs for the service.

Output Parameters

None.

Usage Notes

The results of the service specified in service cannot be retrieved. However, errors that occur will be logged when the guaranteed delivery transaction ends.

Use the pub.remote.gd:send service to invoke a service remotely only if you want to run a guaranteed delivery transaction and are not concerned about the results of the invoked service. After pub.remote.gd:send completes the call, the service ends the transaction; therefore, you do not need to use the pub.remote.gd:end service to end the transaction.

pub.remote.gd:start

WmPublic. Starts a guaranteed delivery transaction.

Input Parameters

alias String Name of the webMethods Integration Server on which you want to invoke a guaranteed delivery transaction. This name and its associated connection attributes are defined on the Remote Servers tab of the Integration Server Administrator.
ttl String Optional. Transaction time-to-live measured in minutes. The transaction expires when ttl is exceeded.

Default is the value set in the watt.tx.defaultTTLMins property or, if the property is not set, 30 minutes.

retries String Optional. Maximum number of times to retry the transaction. Default is 0 (no retry limit).
followtid String Optional. Identification number of the transaction you want this guaranteed delivery transaction to follow. The current transaction executes only after the transaction indicated by followtid completes.

Output Parameters

tid String Transaction identification number.

pub.remote.gd:submit

WmPublic. Invokes a service for a guaranteed delivery transaction by making an asynchronous call to a remote webMethods Integration Server.

Input Parameters

service String Service to be run on the remote webMethods Integration Server.
tid String Transaction identification number for the service.
inputs Document Optional. Document (IData object) containing the inputs for the service.

Output Parameters

None.

Usage Notes

To remove the transaction from the remote webMethods Integration Server, use the pub.remote.gd:end service.

To use a synchronous call to invoke the service, use the pub.remote.gd:invoke service.