Custom Workflows

Triggers, Actions, Inputs, and Outputs

Common Inputs and Outputs

Custom Workflows

Note: We recommend you have some familiarity with GoFormz Workflow Automation and recipe workflow variables before digging into custom workflows.

A workflow is a repeatable automated process. GoFormz Workflow lets you set up form actions that happen automatically based on certain triggers. For example, you may want to send an email to your customer whenever a form is completed. In this case, form completion is the trigger, and emailing the customer is the action.

Custom workflows inject some additional flexibility into what you can do with workflows. Custom workflows are an extension of the Recipe Workflow Model, in the sense that a workflow is modeled as a series of steps, starting with a trigger and followed by one or more actions. However, instead of using a pre-defined sequence of steps, you can choose your own steps from a wide selection of triggers and actions. In effect, you create your own recipe.

Here is one example of a custom workflow:

When a new Work Order object is created in Salesforce that has a particular value in one of its fields (trigger), create a new GoFormz form with some of its fields pre-filled with fields from the Salesforce Work Order (actions).

It would be difficult to accomplish this with a simple recipe-driven workflow because there are so many possible choices — each form has different fields, and you may want different fields pre-filled depending on your needs. Custom workflows make this possible. Custom workflows also allow you to extend the example above in countless ways — what if instead of creating a form based on the Salesforce trigger, you want to do one of the following:

  • Complete a form

  • Send an email notification

  • Add rows to a GoFormz data source

  • Export a form to PDF and send it to Box

  • All of the above at once

With custom workflows, all of these possibilities are on the table.

Triggers, Actions, Inputs, and Outputs

Triggers and Actions

A custom workflow consists of a trigger and one or more actions.

  • The trigger is the event that puts the workflow into motion. Triggers can be internal (e.g. when a user completes a form) or external (e.g. when a new object is created in Salesforce).

  • Actions are what you want GoFormz to do when the trigger occurs. You can string multiple actions together, so the same trigger may cause a series of actions to occur.

Inputs and Outputs

Each trigger and action has inputs and outputs:

  • Inputs are fields that must be filled in for the trigger to function properly. Input values can make use of recipe workflow variables to reference outputs from previous steps.

    • Required vs Optional: Required inputs must be filled in for the step to function properly; your workflow will halt with an error if a required field is not filled in. Optional inputs are not needed for a step to work, but provide additional specifications for how the step should function.

  • Outputs are data returned upon the action’s successful completion; this data can be used in subsequent workflow steps.

Inputs and outputs have two other properties that are important to understand:

  • A step's input automatically becomes its output. This means you can use recipe workflow variables to reference a prior step's input in the same way that you reference its output.

  • Trigger outputs automatically become inputs for all subsequent steps. One consequence of this is that when you use the Form Completed trigger, you don't have to explicitly specify a form ID on any subsequent actions, since the completed form's ID will automatically be included as an input on all subsequent actions. However, be careful — if you want to perform an action on a form other than the completed form and forget to specify the form ID, your workflow will still work but you will get some unexpected results! For this reason, as a best practice, we recommend that you always explicitly specify step inputs, rather than relying on this transference property.

Workflow Example

Here is an example of a simple custom workflow that shows the interplay of triggers and actions, as well as their inputs and outputs. In this example, the custom workflow sends a form PDF and some form data to a Salesforce object whenever a form is completed.

  • First, we have the Form Completed trigger. It has a required built-in Template input as shown below; this specifies which type of form should trigger the workflow. It also includes the completed form's field values and some form metadata as its outputs.

  • Next, we have the Export Form To PDF action. It has an optional pages input to determine which form pages should be exported. Additionally, you can input the filename at this step, if left blank the form name will be used. This step will output the URL of the PDF it creates.

  • Finally, we have the Salesforce Upload File action. It has four required built-in inputs, which include Connection, sObject ID, File Name, & File List. Note also that in this example we use recipe workflow variables to reference outputs from both the Form Completed trigger (form fields values, form name) and the Export action (PDF URL).

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 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).

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, 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 DataSource. 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.

Did this answer your question?