AWAITALL function
Promises
The promises.
OnSuccess
A formula fragment that is run when all promises have succeeded. The
results returned by the promises are available as an array under the
name Results. Use INDEX to retrieve individual
results.
OnFailure
A formula fragment that is run when the first promise fails. An error
is available under the name Error. Refer to the
documentation for the action function returning the promise to learn
what information is available on the error. The position of the promise
that failed in the Promises array is available under the
name Index.
If a promise fails, and you don't provide this parameter, your app displays an error message to your users. Use this parameter to show your own message instead, using a function like BANNER or ALERT. You can also provide BLANK()BLANK() as this parameter, if you don't want anything to happen if the promise fails.
Returns
A promise, which succeeds when and if all the given promises succeed and fails if a single one of those promises fails. If the promise succeeds, the returned value is an array of all the results returned by the promises. If the promise fails, the returned value is the error of the first promise to fail.
Waits for all promises to succeed before running an action. AWAITALL({ EMAILREPORT({ App }, "user1@example.com"), EMAILREPORT({ Result }, "user2@example.com") }, BANNER("All reports sent"))AWAITALL({ EMAILREPORT({ App }; "user1@example.com"); EMAILREPORT({ Result }; "user2@example.com") }; BANNER("All reports sent")) sends two reports and shows the banner All reports sent when all reports have 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 AWAITALL 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.
AWAITALL and other similar functions are used to take action when a promise succeeds or fails.
Taking action when all promises succeed
AWAITALL runs the formula fragment given as its second parameter when all
promises given to it succeed. This formula fragment has access to an array of
results, under the name Results, which contains one result per
promise of the array given to AWAITALL.
This formula asks the user two questions and shows an alert with the collected answers:
The INDEX
function is used to return an element from an array with a certain position.
Here, the first and the second elements of the Results array are
returned, representing the results from the first and second calls to the
PROMPT function.
If any promise of the given array fails, the formula fragment given as the
third parameter is run. It has access to two values, Error,
which is the error returned by the promise that failed, and
Index, which is the position of the promise that failed in the
array.
Examples
Sends two reports and shows the banner All reports sent when all reports have been sent successfully.
Sends two reports and shows the banner All reports sent when all reports have been sent successfully. When the first report has been sent, the banner First report sent is shown. This works because the nested AWAIT invocation returns the promise given to it. Refer to the documentation for AWAIT to learn more about this example.