AWAITANY function

Waits for the first of multiple promises to succeed before running an action. AWAITANY({ EMAILREPORT({ App }, "user1@example.com"), EMAILREPORT({ Result }, "user2@example.com") }, BANNER("First report sent"))AWAITANY({ EMAILREPORT({ App }; "user1@example.com"); EMAILREPORT({ Result }; "user2@example.com") }; BANNER("First report sent")) sends two reports and shows the banner First report sent when confirmation is received that either of the two reports has been sent successfully.

This function can only be used from an action formula. It is typically invoked from a formula associated with the OnPress property of a formula button.

The first parameter to AWAITANY must be an array of promises. A function returning such a value promises to return a value at some point in the future, or at the very least indicate whether the operation the function started was successful. A promise either succeeds or fails, and it can only succeed or fail once.

The promise returned from PROMPT succeeds when the user has entered a value and presses a button. The value returned is the text string the user entered. The promise returned from EMAILREPORT succeeds when the report has been successfully sent — with no value returned — and fails if there is a network problem.

AWAITANY and other similar functions are used to take action when a promise succeeds or fails.

Taking action when the first of many promises succeeds

AWAITANY runs the formula fragment given as its second parameter as soon as a promise given to it succeeds. The result returned by this promise is available under the name Result and the position of this promise in the promises array is available under the name Index.

Let's look at the example formula again:

AWAITANY({ EMAILREPORT({ App }, "user1@example.com"), EMAILREPORT({ Result }, "user2@example.com") }, BANNER("First report sent"))AWAITANY({ EMAILREPORT({ App }; "user1@example.com"); EMAILREPORT({ Result }; "user2@example.com") }; BANNER("First report sent"))

The two promises given to AWAITANY are returned from EMAILREPORT, which sends two reports. The promise returned from EMAILREPORT succeeds when it receives confirmation that a report has been successfully sent.

While sending the report bound for user1@example.com is initiated before the one bound for user2@example.com, there is no telling which report will be successfully sent first. AWAITANY picks the first promise to succeed and forwards its result, and its position in the promises array, to its second parameter.

Handling errors

The formula fragment given as the third parameter to AWAITANY is only run if all promises fail. If that is the case, the errors returned by the promises are available as an array under the name Errors.

This is different from how AWAITRACE works. Both functions perform identically when handling promises that succeed, but handle errors differently. AWAITRACE does not wait for all promises to fail before running the formula fragment given as its third parameter, it invokes it immediately once the first promise to return a result has failed. AWAITANY, on the other hand, waits for all promises to fail before invoking the formula fragment given as its third parameter.

Examples

AWAITANY({ EMAILREPORT({ App }, "user1@example.com"), EMAILREPORT({ Result }, "user2@example.com") }, BANNER("First report sent"))AWAITANY({ EMAILREPORT({ App }; "user1@example.com"); EMAILREPORT({ Result }; "user2@example.com") }; BANNER("First report sent"))

Sends two reports and shows the banner First report sent when the first report to make it through has been sent.

AWAITANY({ EMAILREPORT({ App }, "user1@example.com"), EMAILREPORT({ Result }, "user2@example.com") }, OnFailure: BANNER("Sending all reports failed"))AWAITANY({ EMAILREPORT({ App }; "user1@example.com"); EMAILREPORT({ Result }; "user2@example.com") }; OnFailure: BANNER("Sending all reports failed"))

Sends two reports and shows the banner Sending all reports failed if both reports could not be sent.