OPENREPORT.DSV function

OPENREPORT.DSV(IncludedFields, SeparateScreens?, IncludeScreenLabels?, IncludeBlankValues?, IncludeHiddenFields?, ResetFields?, FileName?, Prologue?, Epilogue?, DecimalSeparator?, Delimiter?, Direction?, ExcludeDelimiterPreamble?) OPENREPORT.DSV(IncludedFields; SeparateScreens?; IncludeScreenLabels?; IncludeBlankValues?; IncludeHiddenFields?; ResetFields?; FileName?; Prologue?; Epilogue?; DecimalSeparator?; Delimiter?; Direction?; ExcludeDelimiterPreamble?)

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

Logical (optional)

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

Logical (optional)

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

Logical (optional)

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

Logical (optional)

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

Logical (optional)

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

Text (optional)

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

Text (optional)

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

Text (optional)

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

DecimalSeparator (optional)

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

DsvDelimiter (optional)

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

DsvDirection (optional)

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

Logical (optional)

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

Promise

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:

OPENREPORT.DSV( { MainScreen, DetailsScreen }, ResetFields: TRUE)OPENREPORT.DSV( { MainScreen; DetailsScreen }; ResetFields: TRUE)
OPENREPORT.DSV( { MainScreen, DetailsScreen }, TRUE, TRUE, FALSE, FALSE, TRUE)OPENREPORT.DSV( { MainScreen; DetailsScreen }; TRUE; TRUE; FALSE; FALSE; 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:

IF(Result >= 0, OPENREPORT.DSV({ App }))IF(Result >= 0; OPENREPORT.DSV({ App }))

This formula opens a report only if Result is valid and displays an error message otherwise using the ALERT function:

IF(Result.Valid, OPENREPORT.DSV({ App }), ALERT("Could not open report", "Error"))IF(Result,Valid; OPENREPORT.DSV({ App }); ALERT("Could not open report"; "Error"))

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:

OPENREPORT.DSV({ App }); RELAY({ App }, "https://hooks.example.com/123")OPENREPORT.DSV({ App });; RELAY({ App }; "https://hooks.example.com/123")

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:

AWAIT(OPENREPORT.DSV({ App }), BANNER("Done!"), ALERT("Could not open report: Error: " & Error.Message))AWAIT(OPENREPORT.DSV({ App }); BANNER("Done!"); ALERT("Could not open report: Error: " & Error,Message))

Examples

OPENREPORT.DSV({ Field1, Field2 })OPENREPORT.DSV({ Field1; Field2 })

Opens a report containing Field1 and Field2. { Field1, Field2 }{ Field1; Field2 } is an example of an array, that is, a list of values.

OPENREPORT.DSV({ App })OPENREPORT.DSV({ App })

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.

OPENREPORT.DSV({ Field1, MainScreen, FormGroup1 })OPENREPORT.DSV({ Field1; MainScreen; FormGroup1 })

Opens a report containing Field1, all fields of the screen MainScreen and all the fields of the form group FormGroup1.

OPENREPORT.DSV({ App }, DecimalSeparator: DecimalSeparator.DecimalComma, Delimiter: DsvDelimiter.Tab, Direction: DsvDirection.Horizontal)OPENREPORT.DSV({ App }; DecimalSeparator: DecimalSeparator,DecimalComma; Delimiter: DsvDelimiter,Tab; Direction: DsvDirection,Horizontal)

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.

AWAIT(OPENREPORT.DSV({ App }), BANNER("Done!"))AWAIT(OPENREPORT.DSV({ App }); BANNER("Done!"))

Opens a report containing all fields of the app and displays a banner with the message "Done!" once the report has been opened.