RELAY function
IncludedFields
The fields that are sent. This parameter is equivalent to the IncludedFields property of server relay buttons — refer to the property for in-depth documentation and more examples.
{ Field1, Field2 }{ Field1; Field2 } sends Field1 and Field2. Field1:Field100Field1:Field100 sends Field1, Field100 and all fields that appear between them. { App }{ App } sends all the fields of the app. { Field1, MainScreen, FormGroup1 }{ Field1; MainScreen; FormGroup1 } sends Field1, all the fields of the screen MainScreen and all the fields of the form group FormGroup1.
FILTER(Field1:Field5, (Field1:Field5).Visible)FILTER(Field1:Field5; (Field1:Field5),Visible)} potentially sends Field1, Field5 and all fields that appear between them, but ultimately only sends those that are visible. Similarly, FILTER(Field1:Field5, Field1:Field5 > 4)FILTER(Field1:Field5; Field1:Field5 > 4)} only sends those fields whose values are greater than 4.
Fields included in this array are not sent if they are hidden and
the IncludeHiddenFields parameter is FALSE. Fields whose
values are blank are not sent if
the IncludeBlankValues parameter is FALSE.
Address
The address (URL) where the data is sent. This parameter is equivalent to the Address property of server relay buttons.
IncludeBlankValues
Whether fields whose values are blank are sent. This parameter is equivalent to the IncludeBlankValues property of server relay buttons. If omitted, FALSE is assumed.
IncludeHiddenFields
Whether hidden fields are sent. This parameter is equivalent to the IncludeHiddenFields property of server relay buttons. If omitted, FALSE is assumed.
ResetFields
Whether the fields that are sent are reset after the data has been sent. This parameter is equivalent to the ResetFields property of server relay buttons. Refer to the property for in-depth documentation and examples. If omitted, FALSE is assumed.
When a field is reset, its value is set to the initial value. The property documentation includes an example demonstrating how to set the value to a blank value instead.
Returns
A promise, which succeeds with no result if the data is sent successfully and fails otherwise. Pass this promise as the first parameter to AWAIT (and related functions) to take action after the promise has succeeded or failed.
If the promise fails, the provided Error value provides an
error message through Error.Message and an error origin
through Error.Origin (often in the form of a function name
or an operator symbol). Additionally, the HTTP status code returned
from the server is available through Error.HttpStatusCode.
An error category is provided through the Error.Category
value. These are the categories:
-
RelayErrorCategory.QuotaExceededRelayErrorCategory,QuotaExceeded
Your plan does not allow additional calls to be made. -
RelayErrorCategory.ServiceErrorRelayErrorCategory,ServiceError
The server could not complete its task. The HTTP status code returned from the server is available throughError.HttpStatusCode. When this category is used, the HTTP status code is less than 200 or greater than or equal to 300.
Enables apps to invoke thousands of third-party services. RELAY({ App },
"https://hooks.example.com/123")RELAY({ App };
"https://hooks.example.com/123") sends the values of all fields of the
app to https://hooks.example.com/123.
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.
This function can send field values to any server, but is typically used to send data to third-party services like Zapier, Microsoft Power Automate and Zoho Flow. These services integrate with thousands of third-party services, enabling them to do things like adding a row to a Google Sheets spreadsheet, sending a message to a Slack channel or creating a Salesforce lead, all based on data entered into an app or calculated by the app.
Once configured, these services provide you with the address you need to use
with this function. It is often something along the lines of
https://hooks.example.com/123.
Refer to our video tutorial to learn more about using third-party services with your app.
Combining RELAY with other action functions
RELAY returns a promise, which succeeds when the data has been sent and fails if there is a problem with the data transmission. Use AWAIT to take action when the promise succeeds or fails.
The first parameter to AWAIT should be the promise returned from RELAY and the second parameter should be a formula fragment that is run when the data has been successfully sent. If you want to run a formula fragment if there is a problem with the data transmission, use the third parameter to AWAIT.
This formula sends data to a third-party service, after receiving consent from the user through the CONFIRM function. When the data has been sent, the message Done! is shown using the BANNER function:
Sending data to an on-premises server (advanced)
You can also send the data to a server you control, enabling your apps to integrate with any software you may run, including on-premises software.
This is an advanced feature, which requires you to operate a server and write the software which accepts the data sent by the app (or have someone write the software for you). This section describes, in technical terms, the steps you need to take to enable your server to receive data sent from an app built with Calcapp.
Data is sent over HTTP using the POST request method. You need to configure an HTTP endpoint on your server and use this address as the first parameter to the RELAY function. We highly recommend that you use an HTTPS endpoint to ensure that the data is not intercepted by a third party while in transit.
The data is sent as JSON data. This data
consists of an object with a single key, named values. The
corresponding value is a JSON object with one key for every form screen that
is part of the collected data. Every form screen key is associated with an
object representing the collected values in the form of an object. This
innermost object has a key for every field.
Calcapp numbers map to JSON numbers, text strings map to JSON strings and logical values map to JSON boolean values.
Form screen labels and field labels are used for the keys, if possible. If a form screen has no title or a field has no label, its name is used instead. All keys belonging to the same object are unique — a serial number in parentheses is appended if there is a name conflict.
Dates are numbers and use the same format used by popular spreadsheets.
Here's an example:
{
"values": {
"Unit conversion": {
"Enter a length": 52,
"Result": 20.472440944882,
"Enter a volume": 6.3,
"Result (2)": 213.02834301
},
"Break-even analysis": {
"Fixed cost": 600000,
"Cost per unit": 125,
"Price per unit": 265,
"How many?": 4286
},
"°F to °C": {
"Enter temperature": 32,
"Result": 0
},
"°C to °F": {
"Enter temperature": 0,
"Result": 32
}
}
}
Examples
Sends the values of all fields of the app to
https://hooks.example.com/123. Refer to our video tutorial to
learn more about using third-party services with your app.