Flow services

Use flow services to perform utility-type tasks.

clearPipeline

Removes all fields from the pipeline. You may optionally specify fields that should not be cleared by this service.

Input parameters for clearPipeline

preserve: String List. Field names that should not be cleared from the pipeline.

Output parameters for clearPipeline

None.

countProcessedDocuments

Counts the number of documents processed by a flow service. Details about the processed documents can be viewed in the Execution Results screen.

Input parameters for countProcessedDocuments

  • status: String. Valid values are success or fail. Set status to success to count the number of successfully processed documents, else set it to fail. Default value is success.

  • incrementBy: String. Increment the number of documents processed by a flow service. Every time the service is used, successful or failed documents are incremented by the given value. Default value is 1.

Output parameters for countProcessedDocuments

None.

Usage notes for countProcessedDocuments

To increment the number of documents processed by a list, use the sizeOfList service in the List service category.

getHTTPRequest

Retrieves information about the HTTP request, received by webMethods Integration

Input parameters for getHTTPRequest

None.

Output parameters for getHTTPRequest

  • httpRequest: Document. Contains the HTTP request received by webMethods Integration and includes following details:

    • headers: Document. Contains the header fields from the HTTP request.

    • requestURL: String. URL used by the client to invoke the service.

    • method: String. HTTP method used by the client to request the top-level service. Possible values are GET, PUT, POST, PATCH, and DELETE.

Note: The getHTTPRequest service does not retrieve the Authorization header.

getLastError

Obtains detailed information about the last error that was trapped within a flow service.

Input parameters for getLastError

None.

Output parameters for getLastError

  • lastError: Document. Information about the last error, which contains details of the time, error, user, block, and call stack information.
  • time: String. Date and time the event occurred, in the format yyyy/MM/dd HH:mm:ss.SSS
  • error: String. Error message of the exception.
  • localizedError: String. Error message in the language that corresponds to the server locale.
  • user: String. User who executed the flow service.
  • block: Document. Contains the following fields:

    name: String. Flow service, operation, or service name.

    type: String. Connector, flow service, or service.

    details: String. Account and Application name if the Block Type is Application.

  • callStack: Document List. The call stack information describing where the error occurred including details of the block. Each document represents a block on the call stack. The first document in the list represents the block that threw the error and the last document in the list represents the top level block. It contains the following fields:

    name: String. Flow service, operation or service

    name.type: String - Connector, flow service, or service.

  • errorDetails: Document. More exception information.

Usage notes for getLastError

You can use this service in the catch section of the try-catch block. Each execution of a flow service or a service (whether the flow service or the service succeeds or fails) updates the value returned by getLastError. Consequently, getLastError itself resets the value of lastError. Therefore, if the results of getLastError will be used as input to subsequent flow services, map the value of lastError to a variable in the pipeline.

If a map has multiple transformers, then a subsequent call to getLastError will return the error associated with the last failed transformer in the map, even if it is followed by successful transformers.

getLastFailureCaught

Returns information about the last failure that was caught by a CATCH step.

Input parameters for getLastFailureCaught

None.

Output parameters for getLastFailureCaught

  • failure: Object. Last failure caught by a CATCH step. The failure parameter is null if no failure has been caught.

  • failureMessage: String, Conditional, Message associated with the failure. The service returns a failureMessage output parameter only if a failure has been caught.

  • failureName: String, Conditional. Exception class name. The service returns a failureName output parameter only if a failure has been caught.

Usage notes for getLastFailureCaught

If a CATCH step can handle multiple failures, use the getLastFailureCaught service to determine which failure the step caught.

You can rethrow a caught failure by using the getLastFailureCaught service to determine the failure caught by the CATCH step, then use an EXIT step that is configured to signal failure to rethrow the failure. getLastFailureCaught need not be executed within a CATCH step. The service returns the caught failure any time after it has been started.

getSessionInfo

Obtains detailed information about the current logged-in user session. Also provides the current flow service execution result reference identifier.

Input parameters for getSessionInfo

None.

Output parameters for getSessionInfo

  • $session: Document. Returns information about the current logged-in user session. Also provides the current flow service name and the execution result reference identifier.
  • tenantId: String. Tenant Identifier.
  • stageId: String. The stage ID where the current flow service resides.
  • user: Document. Returns user details.
  • name: String. Name of the user who is executing the service.
  • CustomContextID: String. Returns the current flow service execution context ID. You can set the context ID in a flow service by using the setCustomContextID service available under the Flow category. ​ ​
  • integrationName: String. The name of the flow service. If flow service A has a referenced flow service B, and if the getSessionInfo service is called in flow service B, then integrationName will be A but if flow service B is executed independently, then integrationName will be B. ​ ​
  • executionResultReference: String. Returns the current flow service execution result reference identifier. For example, you can pass the identifier to an on-premises operation and trace the flow service execution.

getRetryCount

Retrieves the retry count and the maximum retry count for a flow service.

The retry count indicates the number of times the webMethods Integration system has re-executed a flow service. For example, a retry count of 1 indicates that the webMethods Integration system tried to execute the flow service twice (the initial attempt and then one retry).

The maximum retry count indicates the maximum number of times the webMethods Integration system can re-execute the flow service if it continues to fail because of a transient error.

Input parameters for getRetryCount

None.

Output parameters for getRetryCount

  • retryCount: String. The number of times the webMethods Integration system has re-executed the flow service.
  • maxRetryCount: String. The maximum number of times the webMethods Integration system can re-execute the flow service.

Usage notes for getRetryCount

Although the getRetryCount service can be started at any point in a flow service, the getRetryCount service retrieves retry information for the flow service when started by a subscriber. The getRetryCount service does not retrieve retry information for a nested flow service (a flow service that is started by another flow service).

The maximum number of times webMethods Integration retries a flow service depends on the retry properties set in the subscriber that invokes the flow service.

invokeService

Runs any type of service, including another flow service or a web service connector.

Note: You can use the invokeService built-in service only with deploy anywhere flow services.

Input parameters for invokeService

  • ifcname: String. The interface name of the service to run. Specify the fully qualified name of the service in the format project.projectname.integrations.
    Note: Always specify interface names in lowercase. For example, project.projectname.integrations.
  • svcname: String. The name of the service to run. Specify the name of the service name exactly as it is defined.
    Note: Service names are case-sensitive.

  • pipeline: Document. The pipeline document that contains the data to pass to the service.

Output parameters for invokeService

None.

Limitations

Restarting a Java service with the invokeService service might cause issues. Use the invokeService service with caution.

logCustomMessage

Logs a message, which can be viewed in the Execution Results screen.

Input parameters for logCustomMessage

message: String. Custom message to be logged, which can be viewed in the Execution results screen.

Output parameters for logCustomMessage

None,

Note: The default size limit for custom log messages is 1 MB. If a message exceeds this size limit, it is truncated to 1 MB and saved in the database. The truncated message is displayed in the UI.

setCustomContextID

Associates a custom value with an auditing context. This custom value can be used to search for flow service executions in the Monitor screen.

Input parameters for setCustomContextID

id: String. The custom value for the current auditing context. Specify a value that you want to associate with the auditing context. The ID length must be less than or equal to 36 characters. In the event that an ID exceeds 36 characters, only the first 36 characters are stored.

Output parameters for setCustomContextID

None.

Usage notes for setCustomContextID

  • Each client request creates a new auditing context. The auditing context is the lifetime of the top-level service. Once the custom context identifier is set, webMethods Integration includes that value in each service audit record it logs in the current context. Calls to this service affect audit logging only for the current request.
  • This service is useful when webMethods Integration is configured to log to a database. When the server logs information about a service to the database, it includes the custom context identifier in the service log. On the webMethods Integration Monitor screen, you can use the custom value as search criteria to locate and view all corresponding service audit records.
  • If webMethods Integration is configured to log to a file system, webMethods Integration writes the custom context identifier with the service audit records to a file. This file is not accessible on the Monitor screen. You cannot query service records when logging to a file.
  • If this service is started without a specified value for id, webMethods Integration writes a null value for the custom context identifier field for all subsequent service audit records that it logs in the current context.

setHTTPResponse

Sets the HTTP response information to be returned by webMethods Integration.

Input parameters for setHTTPResponse

  • httpResponse: Document. Contains the HTTP response that will be returned by webMethods Integration and includes following details:

    • headers: Document, Contains the header fields to be returned in the HTTP response.
    • responseCode: String. HTTP status code to be returned to the client. The response codes and phrases are defined in https://tools.ietf.org/html/rfc7231#section-6. If you provide a value for responseCode that is not listed in RFC 7321, Section 6, you must also provide a value for reasonPhrase.
    • responsePhrase: String. HTTP reason phrase to be returned to the client. If no reason is provided, the default reason phrase associated with responseCode will be used. You must provide a reasonPhrase for any responseCode that is not listed in RFC 7321, Section 6.
    • responseString: String. Response to be returned to the client, specified as a string.
    • responseBytes: byte[]. Response to be returned to the client, specified as a byte array.
    • responseStream: java.io.InputStream. Response to be returned to the client, specified as an InputStream.

Output parameters for setHTTPResponse

None.

Note: When working with a flow service, always set the responseString parameter in the setHTTPResponse service as the last step. This is so because the flow service does not run in debug mode as the setHTTPResponse service stops it when the responseString parameter is set. However, the setHTTPResponse service can be used at any step in a flow service if responseString is not being set.

sleep

Causes the currently executing flow service to pause for the specified number of seconds.

Input parameters for sleep

seconds: String. The number of seconds to pause the currently executing flow service. The value must be an integer between 1 second and 60 seconds.

Output parameters for sleep

None.

throwExceptionForRetry

Throws an exception and instructs webMethods Integration to re-execute the flow service using the original service input.

Input parameters for throwExceptionForRetry

  • wrappedException: Object. Any exception that you want to include as part of this exception. This might be the exception that causes the throwExceptionForRetry service to execute. For example, if a Salesforce connector fails to connect to the server due to connection timeout you can use this service inside Catch block to retry the flow service again.
  • message: String. A message to be logged as part of this exception.

Output parameters for throwExceptionForRetry

None.

Usage notes for throwExceptionForRetry

Use the throwExceptionForRetry service to handle transient errors that might occur during flow service execution. A transient error is an error that arises from a condition that might be resolved quickly, such as the unavailability of a resource due to network issues or failure to connect to a database. The flow service might execute successfully if webMethods Integration waits and then retries the flow service. If a transient error occurs, the flow service can catch this error and invoke throwExceptionForRetry to instruct the to retry the service.

The throwExceptionForRetry service must be used for transient errors only.

Only top-level services or subscribers can be retried. That is, a service can be retried only when it is started directly by a client request or by a subscriber. The service cannot be retried when it is started by another flow service (that is, when it is a nested flow service).

You can invoke the getRetryCount service to retrieve the current retry count and the maximum specified retry attempts.