Polling Consumer

Use the Polling Consumer pattern when an integration must decide when it is ready to read from a channel instead of receiving pushed messages automatically.

The pattern is implemented at the point where the flow controls the receive call. Use a loop when the integration must keep asking until a message or terminal state is available. Use a scheduled automation when each execution should perform one explicit pull operation.

Loop-driven polling

Use loop-driven polling with while loops when the integration should keep checking a channel or endpoint while it controls the maximum attempts and wait interval. The receive or status-check call stays inside the loop, and the flow exits when it receives a message that is ready to process.

Visual Designer

1. Create or open the HTTP service resource that starts the polling flow.
2. Add an HTTP client connection for the source that the flow must poll. See adding a connection and the HTTP client reference.
3. Add configurable variables for values such as maxAttempts and pollDelaySeconds.
4. Add a While node that runs while the attempt count is less than maxAttempts.
5. Inside the loop, add the HTTP client operation that asks for the current message or status.
6. Add an If node that returns the message when it is ready. Otherwise, wait for the configured delay and continue the loop.

Ballerina Code

service /messages on new http:Listener(8080) {
    resource function get [string messageId]() returns StatusMessage|error {
        int attempt = 0;

        while attempt < maxAttempts {
            StatusMessage message = check statusClient->/[messageId]();
            if message.status == "READY" {
                return message;
            }

            attempt += 1;
            runtime:sleep(pollDelaySeconds);
        }

        return error("Message was not ready before the polling limit");
    }
}

Scheduled broker polling

Use scheduled broker polling when each automation run should pull at most one message from a broker and then stop. This keeps the schedule outside the receive logic while the flow still controls when it asks the broker for the next message. For JMS-backed channels, use the JMS Message Consumer actions with receive or receiveNoWait.

Visual Designer

1. Create a scheduled automation for the polling interval.
2. Add the java.jms JMS MessageConsumer connection and bind the broker settings to configurable variables. See the JMS consumer example.
3. Add the Receive operation from the JMS consumer connection and set the timeout value for the polling window.
4. Add an If node that checks whether the received value is a message.
5. Add the processing steps inside the branch that received a message.
6. Acknowledge the message only after the processing steps finish successfully.

Ballerina Code

public function main() returns error? {
    jms:MessageConsumer consumer = check createConsumer();
    jms:Message? message = check consumer->receive(pollTimeoutMillis);

    if message is jms:TextMessage {
        check processMessage(message.content);
        check consumer->acknowledge(message);
    } else if message is jms:Message {
        log:printInfo("Received a non-text JMS message");
        check consumer->acknowledge(message);
    } else {
        log:printInfo("No message was available in this polling window");
    }
}