OPENREPORT.DSV function
IncludedFields
The fields that are included in the report. This parameter is equivalent to the IncludedFields property of open 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.
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 open 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 open 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 open 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 open report buttons. If omitted, FALSE is assumed.
ResetFields
Whether the fields that are part of the report are reset after the report has been successfully opened. This parameter is equivalent to the ResetFields property of open 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 opened file. This parameter is equivalent to the FileName property of open report buttons. If omitted, a default file name is used.
If no period appears in the returned file name, a file extension (such
as ".csv") is added, depending on the Delimiter parameter.
Prologue
The text that appears before field values. This parameter is equivalent to the Prologue property of open 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 open report buttons. Refer to the property for in-depth documentation and examples. If omitted, no epilogue is used.
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.
Delimiter
The delimiter used to separate values in the CSV or TSV file. The
allowed values are DsvDelimiter.DefaultDsvDelimiter,Default, DsvDelimiter.CommaDsvDelimiter,Comma, DsvDelimiter.SemicolonDsvDelimiter,Semicolon,
DsvDelimiter.TabDsvDelimiter,Tab and DsvDelimiter.SpaceDsvDelimiter,Space. If omitted, or
if DsvDelimiter.DefaultDsvDelimiter,Default is provided,
a comma is used if the decimal separator used for the file (possibly
given explicitly as the DecimalSeparator parameter) is a
decimal point and a semicolon if the decimal separator is a decimal
comma.
Our blog has more information on this subject.
Direction
The direction that field values are laid out in the opened 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.
ExcludeDelimiterPreamble
Whether a special line, appearing first in the file, should be omitted, which tells Microsoft Excel what delimiter is used. This line should be omitted if Microsoft Excel is not used to read the file, as it otherwise shows up in the imported data. Omitting the line also results in smaller file sizes, as a more efficient character encoding can be used, but may make Microsoft Excel struggle to open the file.
This line is always omitted if the Delimiter parameter is
set to DsvDelimiter.TabDsvDelimiter,Tab (files containing
tab-separated values use the .tsv extension, which helps Microsoft
Excel import such files correctly). If this parameter is omitted, this
line is included.
Our blog has more information on this subject.
Returns
A promise, which succeeds with no value if the report is opened 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:
-
OpenReportErrorCategory.QuotaExceededOpenReportErrorCategory,QuotaExceeded
Your plan does not allow additional reports to be opened. -
OpenReportErrorCategory.ServiceErrorOpenReportErrorCategory,ServiceError
Our server failed to generate the report — please let us know.
Opens a report with delimiter-separated values on the user's device. OPENREPORT.DSV({ App })OPENREPORT.DSV({ App }) opens a report containing all fields of the app.
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 table, 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 fields to include make up the only required parameter. 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 open report buttons. No message is displayed if an error occurs, though. Use functions like AWAIT, BANNER and ALERT to display equivalent messages. See below for an example.
Use EMAILREPORT.DSV instead if a report should be emailed instead of being opened. Use OPENREPORT if the included fields should be made available as a plain text, HTML or PDF file.
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 opened file can be set using the FileName
parameter.
The IncludeBlankValues and IncludeHiddenFields
parameters may be used to determine what fields referenced by the first
parameter actually make it into the report. The ResetFields
parameter may be used to reset fields after they have been opened.
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:
The first formula provides the required parameter (the fields to include in the report) and then provides the optional parameter by naming it 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 OPENREPORT.DSV with IF
On its own, a formula button that uses OPENREPORT.DSV can do everything that open report buttons can do, but nothing more. By combining it with other functions, you unlock many more possibilities.
This formula uses IF to only open a report if the value of the number field Result is a positive number:
This formula opens a report only if Result is valid and displays an error message otherwise using the ALERT function:
Running other functions directly after OPENREPORT.DSV
An action formula can run multiple functions by separating the invocations with ;;;.
OPENREPORT.DSV can be combined with RELAY to invoke a third-party service after opening the report. A report can be opened, for instance, while simultaneously posting a message to the internal Slack channel or adding a row to a Google Sheets spreadsheet.
This formula opens a report and then invokes a third-party service:
Waiting for OPENREPORT.DSV to finish
When another function invocation follows OPENREPORT.DSV in a formula, separated by ;;;, it is run as soon as OPENREPORT.DSV has started opening its report.
If you instead need to wait for OPENREPORT.DSV 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 opens a report and shows a banner with BANNER if the report is opened successfully, and displays a message (which must be dismissed) with ALERT if the report could not be opened:
Examples
Opens a report containing Field1 and Field2. { Field1, Field2 }{ Field1; Field2 } is an example of an array, that is, a list of values.
Opens a report containing all fields of the app. The array can contain references to anything, including AppApp, which represents all fields of the app.
Opens a report containing Field1, all fields of the screen MainScreen and all the fields of the form group FormGroup1.
Opens a report containing all fields of the app. The field values are provided as an attached TSV document and use a decimal comma instead of a decimal point. Fields and their values use a horizontal layout, instead of a vertical layout.