Data Source Actions

These actions let you manipulate GoFormz Data Sources. The following actions are available:

Add Data Source Rows: Bulk add rows to a Data Source from a DataSet file.
Delete Data Source Rows: Bulk delete rows from a Data Source, as specified by row ID.
Get Data Source: Generate a DataSet JSON file from a Data Source.
Update Data Source Rows: Bulk update some Data Source rows from a DataSet file.
Upsert Data Source Row: Add or update a single row in a GoFormz Data Source.
Compare Data Source To DataSet: Compare a Data Source to a DataSet file and generate lists of rows to add to, update in, and delete from the Data Source in order to make it identical to the comparison DataSet. This action is actually documented under Utility Actions, but we mention it here because the Update and Delete actions are dependent on this Compare action.

There are a number of possible use cases for the Data Source actions. For instance:

Updating your GoFormz Data Source with data from an external data source.
Updating your external Data Source with data from a GoFormz data source.
Updating your GoFormz Data Source with data from a GoFormz form (see Upsert Data Source Row Usage section for more)

However, the first use case is the most common and most involved, so we go over it here.

Extended Use Case: Updating a Data Source with external data

The motivation for this use case is keeping your GoFormz Data Sources in sync with your system of record. GoFormz isn't going to be your system of record, and we're not trying to be. But we do want to make it easy for you to keep your GoFormz Data Sources up to date by periodically updating them from your system of record. This way, your forms can draw on your most current data.

This operation is typically accomplished with the following steps:

Obtain a JSON file representing the contents of the external data source.
Obtain a JSON file representing the contents of the GoFormz data source using the Get Data Source action.
Compare the two files using the Compare Data Source To DataSet action. This comparison will return 3 JSON files representing the Data Source rows that should be added, updated and deleted to bring the GoFormz Data Source in sync with the external data source.
Use the Add Data Source Rows, Update Data Source Rows and Delete Data Source Rows actions to add, update and delete the appropriate rows based on the previous step's outputs.

Let us go through an example of this. Suppose that Salesforce is the system of record for all your customers. You keep a Data Source of customers in GoFormz for use in your forms — one common use case for this is to have a form auto-fill a customer's information (address, phone number, etc.) when the customer's name is entered. You want to update the GoFormz Data Source whenever a change is made to a customer record in Salesforce. Here is how you can do this.

Step 1. Initiate the workflow when a customer record changes in Salesforce using the Salesforce Webhook trigger.

Step 2. Use the Salesforce: Query action to obtain a JSON file representing the contents of the Salesforce customer records database.

Step 3. Use the Get Data Source action to obtain a JSON file representing the contents of the GoFormz customers database.

Step 4. Compare the JSON file rows from steps 2 and 3 (dataSourceUrl and dataSetUrl) using the Compare Data Source To DataSet action. The comparison keys will be drawn from the "DisplayName" row in SalesForce (see dataSetKeyColumn input) and the "Key" row in the GoFormz data. So, for instance, if both data sets have a row with "Acme, Inc." in those columns, those rows are considered to be matching. The comparison output consists of 3 components:

A DataSet file containing all rows from the SalesForce data that do not have matching keys in the GoFormz data. These rows should be added to the GoFormz Data Source.
A DataSet file containing all rows from the GoFormz data that have matching keys in the SalesForce data. These are rows that you may want to update in the GoFormz Data Source.
A comma-separated list of GoFormz row IDs corresponding to rows in the GoFormz data that do not have matching keys in the SalesForce data. These are rows that you may want to delete from the GoFormz Data Source.

Step 5. Add the appropriate rows to the GoFormz customer Data Source. The DataSet file with the rows to be added comes from the Compare step, as described above (#{CompareCustomerDataset.[add_storageFileName]}). We include the dataSetKeyColumn to determine which column from the DataSet will go into the Data Source's "Key" column. columnOrder determines the order in which the remaining columns will be added to the Data Source; note that the DataSet file may contain more columns, but only the columns in the columnOrder input will be used.

Step 6. Update the appropriate rows of the GoFormz customer Data Source. The file with the Data Source rows to be updated comes from the Compare step (#{CompareCustomerDataset.[add_storageFileName]}), while the file with the new values for those rows is just the SalesForce data file from the Query step. This file contains all the SalesForce rows, but only rows that match a row in the updateDataSetStorageFileName will be used. Row matching is performed by key matching in the same way as in Step 4. Column mapping is determined by the columnOrder input as in Step 5.

Step 7. Delete the appropriate rows of the GoFormz customer Data Source. The delete list of row IDs comes from the Compare step.