Common Inputs and Outputs

Certain inputs and outputs come up in many different actions and triggers. We go over some of these common inputs and outputs here, in several categories:

  • Form Fields: Inputs and outputs representing form fields, either within a GoFormz form, or a third-party application object.
  • GoFormz Object IDs: 32-digit IDs of various GoFormz objects.
  • Form Metadata: Inputs and outputs that provide information about a GoFormz form.
  • DataSet Specs: Inputs and outputs that deliver DataSets and specify how DataSet columns map to other objects.

Form Fields

Several of custom workflow steps (actions and triggers) either output individual form fields (e.g. Form Completed and Get Form), or can be used to fill in individual form fields (e.g. Create Form and Update Form). These outputs are always named using "field_" as a prefix, followed by the field's name:

Input/Output Name

Value

field_<field_name>

When used as an output, this is the value contained in the "<field_name>" field of the form. So for instance the output field_TechnicianName will contain the value of the "TechnicianName" field in the completed form.

When used as an input, this is the value that should be placed into the form field with name "<field_name>". So if the input is field_TechnicianName and the value is "Jane Doe", then "Jane Doe" will be placed in the form’s “TechnicianName” field. Any pre-existing value in the field will be overwritten.

Note that this description applies to GoFormz form fields only! Field inputs/outputs for third-party apps may behave differently.

GoFormz Object IDs

Every object (e.g. form, template, data source, etc.) in GoFormz has a unique 32-digit hexadecimal identifier, or ID. These IDs are used as inputs in many different actions, in order to identify the object that the action should target. There are also a handful of actions and triggers that return an ID as their output.

In this section, we go over some commonly used object IDs and where to obtain them.

ID

Value

formId

The ID associated with a GoFormz form. You can obtain a form ID in two ways:

  • Open the form in the GoFormz web app's Form Editor. You will see the form ID in the URL.
  • The Form Completed trigger returns the ID of the form that was completed as one of its outputs.

formTemplateId

The ID associated with a form template. You can obtain a template ID in a few ways:

  • Open the desired template in the GoFormz web app's Template Editor. You will see the template ID in the URL.
  • The Form Completed trigger returns the ID of the template on which the completed form was based.
  • The Get Form action returns the ID of the template on which the chosen form was based.

dataSourceId

The ID associated with a GoFormz Data Source. To find a desired Data Source's ID, open it in the GoFormz web app. You will see the ID in the URL.

A common workflow practice is storing important IDs somewhere as a reference for future use:

  • For instance, you might have a main work order form and several forms that feed data into it (e.g. timesheets, purchase orders, inspection checklists, etc.). If you include the main form's ID in a field of each of these supplemental forms, you can create workflows to automate much of the main form's data entry. Or you can store the IDs of all related forms in a Data Source row, automating it that way.
  • Or suppose you want to keep a one-to-one relationship between GoFormz work order forms and Salesforce work order objects. Then you might store the GoFormz form ID on the Salesforce work order object, and use a custom workflow to auto-update the form whenever the Salesforce object changes.

Form Metadata

Form metadata variables provide information about the form itself, rather than the values of any specific fields within the form. Note that while formId is technically a metadata variable, we treat it separately in the previous section, because it comes up so frequently.

Output

Value

formName

The name of the completed form. Note that this is the name of the form rather than the template. Depending on your configuration, each form created from the same template may or may not have a unique name.

formStatus

The form's current status. This can be either "complete" or "draft".

formChangeDate

The timestamp when the form's status last changed, in the following format: "MM/DD/YYYY hh:mm:ss". This includes form completions and form transfers.

formLastUpdateDate

The timestamp when the form's content was last updated, in the following format: "MM/DD/YYYY hh:mm:ss". Use this to see the last time any update was made to the form.

formLocationLatitude

The latitude of the location where the form was completed.

formLocationLongitude

The longitude of the location where the form was completed.

formAssignmentId

The unique 32-digit hexadecimal identifier of the user or group to whom the form is currently assigned. If you open the user/group in the GoFormz web app, this is the ID you will see in the URL.

formAssignmentType

This will be either "User" or "Group", depending on whether the form is assigned to a user or group.

DataSet Specs

DataSet JSON files are used as inputs and outputs in a number of actions that read or write tabular data (like form tables, Data Sources, Salesforce queries, etc.). Here we describe some common variables that are frequently seen as inputs and outputs for DataSets.

Whenever an action outputs a DataSet, it always includes two components:

  • The DataSet URL, which is the URL where the newly created DataSet is stored in the GoFormz system. The full name of the actual output varies depending on the action, but will almost always end in dataSetUrl.
  • The DataSet storage file name, which is just the name of the file without the full URL. The full name of the actual output varies depending on the action, but will almost always end in storageFileName.

Both outputs are given because different actions use one or the other of them as an input. In practice, you will almost always use another action's DataSet output as an input. However, when the input requires a DataSet URL (rather than a file name), you are free to provide your own DataSet file URL — just make sure the columns match what the action expects.

Two other common inputs for DataSet-driven actions have to do with how the DataSet's columns are mapped to other objects. These inputs are used when a DataSet is used as a source for data to be inserted into some destination — be it a Data Source, a form table, or another DataSet.

Input/Output

Value

columnMapping

This input specifies how the source DataSet's columns map to the destination's columns, using the following syntax:
<source_column~destination_column|source_column~destination_column|...>. For instance, suppose the columnMapping value is SKU~SKUNumber|Description~Description|PurchaseCost~Cost. This means that:

  • the source DataSet's SKU column maps to the destination's SKUNumber column;
  • the source DataSet's Description column maps to the destination's Description column;
  • and the source DataSet's PurchaseCost column maps to the destination's Cost column.

Source DataSet columns that are not included in the mapping will typically be ignored, while destination columns that are not included in the mapping will typically be left as is if they already contain data, or left blank if they do not.

columnOrder

This input is really a special case of columnMapping where the destination side of the mapping is implied. It specifies the order in which source DataSet columns should be inserted into the destination, separated by pipe characters. For instance, if the value is SKU|Description|PurchaseCost, that means:

  • the source DataSet's SKU column will map to the destination's first column;
  • the source DataSet's Description column will map to the destination's second column;
  • the source DataSet's PurchaseCost column will map to the destination's third column

As with columnMapping, source DataSet columns that are not included here will typically be ignored.

Updated 2 years ago

Common Inputs and Outputs


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.