EMAILREPORT.TSV function
IncludedFields
The fields that are included in the report. This parameter is equivalent to the IncludedFields property of email report buttons — refer to the property for in-depth documentation and more examples.
{ Field1, Field2 }{ Field1; Field2 } includes Field1 and Field2 in the report. Field1:Field100Field1:Field100 includes Field1, Field100 and all fields that appear between them. { App }{ App } includes all the fields of the app. { Field1, MainScreen, FormGroup1 }{ Field1; MainScreen; FormGroup1 } includes 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 includes Field1, Field5 and all fields that appear between them, but ultimately only includes those that are visible. Similarly, FILTER(Field1:Field5, Field1:Field5 > 4)FILTER(Field1:Field5; Field1:Field5 > 4)} only includes those fields whose values are greater than 4.
Fields included in this array are not part of the report if they are
hidden and the
IncludeHiddenFields parameter is FALSE. Fields whose
values are blank are not part of
the report if the IncludeBlankValues parameter is FALSE.
Recipients
The primary recipients of the email. This parameter is equivalent to the Recipients property of email report buttons — refer to the property for in-depth documentation and more examples.
This parameter must consist of one or several email addresses, in the form of a text string or in the form of an array of text strings. A text string can contain multiple email addresses separated by spaces, commas or semicolons. Use & to join text strings together.
"user1@example.com;user2@example.com""user1@example.com;user2@example.com"
sends the report to user1@example.com and to
user2@example.com.
{ "user1@example.com", "user2@example.com" }{ "user1@example.com"; "user2@example.com" } has the same effect.
{ "office@example.com",
EmailAddress}{ "office@example.com";
EmailAddress} sends the report to
office@example.com and to the email address specified in
the text field EmailAddress.
ReplyTo
The Reply-To field of the email. This parameter is
equivalent to the ReplyTo property
of email report buttons — refer to the property for in-depth
documentation and examples.
SubjectLine
The subject line of the email. This parameter is equivalent to the SubjectLine property of email report buttons.
SeparateScreens
Whether field values belonging to different screens are separated from one another in the report. This parameter is equivalent to the SeparateScreens property of email report buttons. Refer to the property for in-depth documentation and examples. If omitted, TRUE is assumed.
IncludeScreenLabels
Whether screen labels are included in the report. This parameter is equivalent to the IncludeScreenLabels property of email report buttons. Refer to the property for in-depth documentation and examples. If omitted, TRUE is assumed.
IncludeBlankValues
Whether fields whose values are blank are included in the report. This parameter is equivalent to the IncludeBlankValues property of email report buttons. If omitted, FALSE is assumed.
IncludeHiddenFields
Whether hidden fields are included in the report. This parameter is equivalent to the IncludeHiddenFields property of email report buttons. If omitted, FALSE is assumed.
ResetFields
Whether the fields sent in the report are reset after the report has been successfully sent. This parameter is equivalent to the ResetFields property of email report 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.
FileName
The name of the file that emailed attachments are saved to when the email is sent. This parameter is equivalent to the FileName property of email report buttons. If omitted, a default file name is used.
If no period appears in the returned file name, the file extension ".tsv" is added.
Body
The body of the sent email. This parameter is equivalent to the Body property of email report buttons. Refer to the property for in-depth documentation and examples. If omitted, a default body is used.
Prologue
The text that appears before field values. This parameter is equivalent to the Prologue property of email report buttons. Refer to the property for in-depth documentation and examples. If omitted, no prologue is used.
Epilogue
The text that appears after field values. This parameter is equivalent to the Epilogue property of email report buttons. Refer to the property for in-depth documentation and examples. If omitted, no epilogue is used.
CarbonCopy
The carbon copy ("CC") recipients of the email. This parameter is
equivalent to the CarbonCopy
property of email report buttons. Refer to the property for in-depth
documentation and examples. The Recipients parameter is
similar and its examples apply to this parameter as well. If omitted,
no carbon copy recipients are used.
BlindCarbonCopy
The blind carbon copy ("BCC") recipients of the email. This parameter
is equivalent to the BlindCarbonCopy
property of email report buttons. Refer to the property for in-depth
documentation and examples. The Recipients parameter is
similar and its examples apply to this parameter as well. If omitted,
no blind carbon copy recipients are used.
Sender
The sender of the email. This parameter is equivalent to the Sender property of email report buttons. Refer to the property for in-depth documentation and examples.
If omitted, a default sender is used which uses the
calcapp.net domain, which increases the odds that an email
sent through an app is successfully delivered and is not classified as
spam. Consider using the ReplyTo parameter instead to
direct replies to your reports.
DecimalSeparator
The decimal separator used to separate the integer and fractional parts of numeric field values. The allowed values are DecimalSeparator.DecimalPointDecimalSeparator,DecimalPoint and DecimalSeparator.DecimalCommaDecimalSeparator,DecimalComma. If omitted, the language settings of the app are consulted to determine the decimal separator (a decimal comma for an app in German and a decimal point for an app in English, for instance).
Our blog has more information on this subject.
Direction
The direction that field values are laid out in the attached file. The allowed values are DsvDirection.HorizontalDsvDirection,Horizontal and DsvDirection.VerticalDsvDirection,Vertical. If omitted, field values are laid out vertically.
Our blog has more information on this subject.
Returns
A promise, which succeeds with no value if the report 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).
An error category is provided through the Error.Category
value. These are the categories:
-
EmailReportErrorCategory.InvalidEmailAddressEmailReportErrorCategory,InvalidEmailAddress
An email address — a recipient, a carbon copy ("CC") recipient, a blind carbon copy ("BCC") recipient, the sender address or the Reply-To address — was found to be invalid. -
EmailReportErrorCategory.QuotaExceededEmailReportErrorCategory,QuotaExceeded
Your plan does not allow additional reports to be sent. -
EmailReportErrorCategory.TooManyRecipientsEmailReportErrorCategory,TooManyRecipients
There are too many recipients. -
EmailReportErrorCategory.ServiceErrorEmailReportErrorCategory,ServiceError
Our email service provider could not deliver your report — please let us know.
Sends a report with tab-separated values through email. EMAILREPORT.TSV({ App },
"test@example.com")EMAILREPORT.TSV({ App };
"test@example.com") sends a report containing all fields of the app,
in the form of an attached file containing tab-separated values (TSV), to
test@example.com.
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.
A report contains field labels and their values in a grid, with the labels appearing in the first column and the values in the second column. A report can also omit fields and their values entirely and only include arbitrary text (see below).
The fields to include are given as the first parameter to this function, as an array. { Field1, Field2 }{ Field1; Field2 } includes the Field1 and Field2 fields, { Field1, MainScreen }{ Field1; MainScreen } includes Field1 and all the fields of the screen MainScreen, { App }{ App } includes all the fields of the app and {}{} includes no fields.
The recipients are given as the second parameter, and must be either a text string containing one or several email addresses, separated by spaces, commas or semicolons, or an array of such text strings.
The fields to include and the recipients are the only required parameters. However, there are a very large number of optional parameters, allowing you to customize the report. These are detailed above (press Details).
This function is mostly equivalent to email report buttons. No messages are displayed when a report is successfully sent or if an error occurs, though. Use functions like AWAIT, BANNER and ALERT to display equivalent messages. See below for an example.
Use OPENREPORT.TSV instead if a report should be opened directly on your user's device, instead of being emailed. Use EMAILREPORT.CSV to send comma-separated values (CSV) instead. Finally, use EMAILREPORT if the included fields should be sent as text or as an attached PDF document.
Optional parameters
Arbitrary text can be included before and after the field values using the
Prologue and Epilogue parameters, respectively. The
file name of the attached file can be set using the FileName
parameter. The email body is automatically generated with helpful suggestions
on how to use the attached file — use the Body parameter to
provide your own email body. Use the SubjectLine parameter to
provide a custom subject line for the email.
The IncludeBlankValues and IncludeHiddenFields
parameters may be used to determine what fields referenced by the first
parameter actually make it into the report. The ReplyTo,
Sender, CarbonCopy and BlindCarbonCopy
parameters may be used to customize other aspects of the email. The
ResetFields parameter may be used to reset fields after they have been sent.
Again, refer to the details above for more information.
Customizing the look
The SeparateScreens parameter determines if values belonging to
different screens are separated from one another in a report. The
IncludeScreenLabels parameter determines if screen labels are included in
reports. IncludeScreenLabels has no effect unless
SeparateScreens is TRUE.
These are examples of what reports look like, depending on what values are
given to the SeparateScreens and
IncludeScreenLabels parameters:
Without separated screens
| Field1 | 1 |
| Field2 | 2 |
| Field3 | 3 |
With separated screens and screen labels
| Screen1 | |
|---|---|
| Field1 | 1 |
| Screen2 | |
| Field2 | 2 |
| Field3 | 3 |
With separated screens and no screen labels
| Field1 | 1 |
| Field2 | 2 |
| Field3 | 3 |
The examples above assume that the Direction parameter is either
omitted or is set to DsvDirection.VerticalDsvDirection,Vertical.
Named parameters
Parameters are typically provided in the order they are expected. By preceding a parameter with its name and a colon, it can be provided out-of-order and optional parameters normally expected prior to it can be omitted entirely.
As an example of named parameters, consider these two formulas. They both set
the ResetFields parameter to TRUE and provide a custom subject
line:
The first formula provides the two required parameters (the fields to include in the report and the recipients) and then provides two optional parameters by naming them explicitly.
The second formula explicitly provides values for all parameters, up to and
including the ResetFields parameter.
We recommend the first version, with named parameters, as such formulas tend to be shorter and easier to understand.
Combining EMAILREPORT.TSV with IF
On its own, a formula button that uses EMAILREPORT.TSV can do everything that email report buttons can do, but nothing more. By combining it with other functions, you unlock many more possibilities.
This formula uses IF to only send a report if the value of the number field Result is a positive number:
This formula sends a report only if Result is valid and displays an error message otherwise using the ALERT function:
Running other functions directly after EMAILREPORT.TSV
An action formula can run multiple functions by separating the invocations with ;;;.
This formula sends two reports, containing different fields, with only the last report including field values as tab-separated values:
The first report doesn't contain any fields in the traditional sense. Instead, it sends an email with a custom body, containing a result. It is sent to the user's email address, which is only available if the app is a private app.
The second report contains Field1, Field20 and all fields
that appear between them, as well as Result, and sends it to
office@example.com as an attached TSV file.
With ;;;, EMAILREPORT.TSV can be combined with RELAY to also invoke a third-party service. A report can be sent to a customer, for instance, while simultaneously posting a message to the internal Slack channel or adding a row to a Google Sheets spreadsheet.
Waiting for EMAILREPORT.TSV to finish
When another function invocation follows EMAILREPORT.TSV in a formula, separated by ;;;, it is run as soon as EMAILREPORT.TSV has sent its report.
If you instead need to wait for EMAILREPORT.TSV to finish before continuing, you need to use the AWAIT function (or a related function). AWAIT accepts an action (returning a promise) as its first parameter. It runs the formula fragment given as the second parameter if the action succeeds and runs the formula fragment given as the third parameter if the action fails.
This formula sends a report and shows a banner with BANNER if the report is sent successfully, and displays a message (which must be dismissed) with ALERT if the report could not be sent:
Using PROMPT to collect parameters for EMAILREPORT.TSV
AWAIT can also be used to wait for other functions to complete their work. PROMPT is one such function, which asks the user to provide information with a window that pops up.
This function asks the user which email address to send the report to before invoking EMAILREPORT.TSV:
the report be sent to?", Title: "Question", OkLabel: "Send report"), EMAILREPORT.TSV({ App }, Result))AWAIT(PROMPT(Body: "What email address should
the report be sent to?"; Title: "Question"; OkLabel: "Send report"); EMAILREPORT.TSV({ App }; Result))
AWAIT makes the result returned from PROMPT available as the
Result value, which is the text string entered by the user.
Examples
Sends a report containing Field1 and Field2 to
test@example.com. { Field1,
Field2 }{ Field1; Field2 } is an
example of an array, that is, a list of values.
Sends a report containing Field1, Field100 and all
fields that appear between them to user1@example.com and
user2@example.com. The recipients can also be specified as
an array.
Sends a report containing all fields of the app to
user1@example.com and user2@example.com. The
first array can contain references to anything, including AppApp, which represents all fields of
the app. The recipients can be specified as a single text string, where
individual addresses are separated by spaces, commas or semicolons.
Sends a report containing Field1, all fields of the screen
MainScreen and all the fields of the form group
FormGroup1 to test@example.com.
contains the readings taken on " & FORMATDATE(TODAY()) & ".")EMAILREPORT.TSV({ App }; "test@example.com"; SubjectLine: "A report"; Body: "The attached TSV file
contains the readings taken on " & FORMATDATE(TODAY()) & ".")
Sends a report containing all fields of the app to
test@example.com. The subject line is set to "A report" and
the email body is set to a custom text string incorporating today's date.
Named parameters are used to provide just two optional parameters (the
subject line and email body), while leaving the rest of the optional
parameters at their default values.
Sends a report containing all fields of the app to
test@example.com. The field values are provided as an
attached TSV document and use a decimal comma. Fields and their values
use a horizontal layout, instead of a vertical layout.
Sends a report containing all fields of the app to
test@example.com and displays a banner with the message "Done!" once
the report has been sent.
Asks the user to provide the recipients of the report. Once the user has
done so, a TSV report is sent containing all fields of the app to
test@example.com. -> is used to rename the
value returned from the AWAIT function to
Recipients, which in turn is the value provided from the
PROMPT
function to AWAIT, containing the recipients entered by the user.