Skip to main content
Utility Actions

These actions do not access GoFormz objects directly, but are handy when preparing inputs and handling outputs

Updated over 5 months ago

These actions do not access GoFormz objects directly, but are handy when preparing inputs and handling outputs of other GoFormz actions and triggers. Below, we go over the Utility actions.

Utility Actions List

The following utility actions are available:

Compare DataSource to DataSet

Perform a comparison between a GoFormz DataSource and a comparison DataSet file, and output three smaller DataSets representing the DataSource rows that must be added, updated and deleted in order to make the DataSource identical to the comparison DataSet. The files are compared using the "Key" column from the GoFormz DataSource.

This action compares a DataSet file representing a GoFormz DataSource and another DataSet file representing an external DataSource.

Below are the inputs for Compare DataSource to DataSet.

  • DataSet Key Column (required): The name of the comparison DataSet column containing the key. This should match the "Key" column from the GoFormz DataSource.

  • DataSource (required): The URL of the DataSource DataSet. This DataSet should represent an existing GoFormz DataSource that you wish to update, and is typically obtained using the Get DataSource action.

  • DataSet (required): The URL of the comparison DataSet. This typically comes from an external DataSource that we want to use to update the GoFormz DataSource.

The comparison output consists of 3 components:

  • A DataSet file containing all rows from the external data that do not have have a match in the GoFormz data. These rows should be added to the GoFormz DataSource.

  • A DataSet file containing all rows from the GoFormz data that DO have a match in the external data/ These are rows that you may want to update in the GoFormz DataSource.

  • A comma-separated list of GoFormz row IDs corresponding to rows in the GoFormz data that do not have a match in the comparison data. These are rows that you may want to delete from the GoFormz DataSource.

Filter DataSet

Filter the rows of a DataSet file to include only rows with your desired properties.

Filtering a DataSet is a powerful action. There are many situations where you might have a large DataSet and you want to use only a subset of that DataSet that fits certain criteria. This is the action you want to use in such situations. You can use this to filter any DataSet; for instance:

  • A DataSet representing a form table (obtained via Get Form Table). Perhaps you want to grab all table rows that are above a certain cost because purchases above a certain amount require special approval.

  • A DataSet representing a DataSource (obtained via Get DataSource). Perhaps you want to generate a list of all contacts that you have for one specific customer.

  • A DataSet representing an external DataSource (obtained via one of a number of actions, e.g. Salesforce: Lookup).

Another common use case is when you want to extract individual column values from a particular row of your DataSet. In this situation, you can use Filter DataSet first to isolate the row you want, and then use Select DataSetRow with rowNum=1 to extract the column values.

Below are the inputs for Filter DataSet.

  • DataSet (required): The URL of the DataSet file that you want to filter.

  • Filter Expression (required): A filter expression, using C# DataView RowFilter syntax.This allows you to filter DataSet rows based on column values. For example, Category='Prospect' AND Address LIKE 'San Francisco' AND AnnualRevenue>10000000 is a filter string that would output all rows where the Category column is "Prospect", the Address column contains "San Francisco", and the AnnualRevenue column is greater than 10 million.

  • Sort By: Sorting your Data by Ascending or Descending.

Format DataSet Column

Add a new formatted column to your DataSet using one or more existing DataSet columns as input. This includes adding various types of formatting to numbers and dates/times, and converting them to strings. This action creates a column of formatted values.

This action can be used to format some input columns of a DataSet before adding the DataSet to a GoFormz DataSource, a form table, or some external input. You can also use it to combine values from multiple columns in some way; this can be handy when creating a "Key" column for a GoFormz DataSource.

Below are the inputs for Format DataSet Column.

  • Format String (required): A format string, using .NET composite formatting syntax, to be used for generating a new formatted column. For instance, {0:dddd dd MMMM} would convert a date input in each row of formatInputColumn1 into day of week, day and month; a value in the resulting column might read "Thursday 3 May".

  • DataSet (required): The URL of the DataSet file that you want to filter.

  • Formatted Column Name: Column name of the formatted column in the Output DataSet

  • DataSet Column Name: Original Column Name

Pdf Page Numbers

This action generates a string to be used for the pages input of the Export Form To PDF action. The string is based on a set of inputs you provide about the form that will be exported. This is an unusual action in that it is rarely if ever used independently — it is typically used in conjunction with the the Export Form To PDF action.

This action is most useful when the form pages that you want to export are not the same for every completed form, but rather depend on one or several variables. You can then use these variables in the various inputs of this action in order to generate that list of pages that should be exported.

In the example below, we do exactly that. Let's break down how the desired page string is built up in this example:

  • Pages 3 and 4 will always be included, because those are the first 2 pages (section1_pagesUsed) of the specified page range (3-8, section1_pageRange)

  • Page 1 will be included only if the Date field from the completed form is filled in.

  • Page 2 will be included only if the Customer Name field from the completed form is filled in.

Below are the inputs for Pdf Page Numbers.

  • totalPages (required): The total number of pages in the form template that you are targeting.

  • section#_pageRange: A single page (e.g. 2) or a page range using dash notation (e.g. 2-4 would signify pages 2 through 4).

  • section#_pagesUsed: The number of pages that should be included starting from the beginning of the section. For example, if section2_pageRange is 5-9 and section2_pagesUsed is 2, then pages 5 and 6 will be included.

  • page$_<anything>(page1_<anything>,page2_<anything>,etc.): If this value is not null, then the page with the corresponding number will be included; otherwise it won't be. For instance, if page3_Customer has the value from your form's "Customer Name" field — that means that page 3 will be included if the "Customer Name" field has a value, and will not be included otherwise. (Note that the "Customer Value" field itself does not need to be on page 3.)

Select DataSet Row

Access column values for a selected DataSet file row. This is currently the only action that outputs individual values from a DataSet in a way that can be used by other actions.

Extracting individual values from a DataSet can be handy in a number of situations. For example, you may want to use values from a (GoFormz or external) DataSource to fill in a form.

There are a number of different ways to use this action. For instance:

  • If you know the row number that you want to extract from the DataSet, you can use this action directly, setting rowNum to the row number you want.

  • If you want to select a row based on certain properties, you can use Filter DataSet first to isolate the row you want from the DataSet, and then use Select DataSet Row with rowNum=1 to extract the row values. This use case shown in the image below. This shows the Select DataSet Row step of the same example that we review in the Filter DataSet documentation. In this scenario, we find a customer in a GoFormz DataSource using the Get DataSource and Filter DataSet actions; then use Select DataSet Row to extract the column values from the one row of the filtered DataSet (#{FilterDS.[dataSetUrl]}); then use those column values in Create Form to fill form fields.

  • Another use case for this action is to simply check if a DataSet is empty. You can do this by using rowNum=1 and then checking to see if rowFound=false. In the example below, we have a Create Form action that only executes if a DataSet is not empty. We do this by setting skip_if_false to the rowFound output of the Select DataSet Row step.

Below are the inputs for Select DataSet Row.

  • DataSet (required): The URL of the DataSet JSON file from which you want to extract row values.

  • Row Number (required): The row number that you want to access from the DataSet.

Did this answer your question?