Skip to main content

Reference Key for Supplementary Forms

· 4 min read

If your workflow has more than one form in it - say, a Manager Approval form followed by a Finance Review form - you've probably referenced one of those forms in a template or condition using something like forms.2.remark. That "2" just means "the second form in the workflow." It's based on position, so if you later add, remove, or reorder a step, that "2" can end up pointing at the wrong form without any warning.

This release adds a small option to work around that: Reference Key, an optional name you can set on a form step so you can refer to it by name instead of by position.

Why this comes up​

Say you have:

Initial Form -> Manager Approval -> Finance Review -> Final Processing

Finance Review is the 2nd step, so a document template uses forms.2.amount.

Later you insert a "Budget Check" step before it:

Initial Form -> Manager Approval -> Budget Check -> Finance Review -> Final Processing

Finance Review is now the 3rd step. The forms.2.amount reference didn't move with it - it's quietly pointing at the wrong form (or nothing), and there's no error to flag it. Usually this only gets noticed once a document or email goes out with the wrong value.

Branching workflows make it worse​

Workflows aren't always a straight line - a Condition task can split a workflow into two branches, and those branches can later merge back into the same downstream task. That's where positional numbering really breaks down.

                    -> [true]  Finance Check -> Extra Approval -\
Initial Form -> Condition                                        -> Manager Sign-off -> ...
                    -> [false] Quick Check --------------------->/

One branch has two steps before reaching Manager Sign-off, the other has just one. There's no single "step number" that makes sense for Manager Sign-off - it depends on which branch a submission actually took, and it shifts again if you add or remove a step on either branch, even one you never touched. Targeting Manager Sign-off with forms.N.field_name in this kind of workflow is basically a guessing game.

A Reference Key set on Manager Sign-off sidesteps that entirely: forms.id:signoff.remark always means "the Manager Sign-off task," regardless of which branch led to it or how many steps that branch had.

What Reference Key does​

You can now set a Reference Key on a Form, Approve, Review, or Process task - a short name like finance or review1.

Once it's set, you can use forms.id:finance.amount instead of forms.2.amount, in the same places: document templates, email/notification templates, conditions, transform inputs and outputs, and Output task data.

Since the key is attached to the task itself rather than its position, it keeps pointing at the right form even after the workflow gets reordered later.

How to set it​

  1. Open the workflow in the Workflow Builder
  2. Click on a Form, Approve, Review, or Process task (any step after the initial form)
  3. Open More settings and find the Reference Key field
  4. Type a short name using letters and numbers only - it's lowercased automatically as you type
  5. Save and publish

From there, use [forms.id:finance.field_name] wherever you'd normally write [forms.N.field_name]. The smart-tag picker will suggest the Reference Key version automatically once one is set on a task.

A few notes:

  • It's optional - if you don't set one, forms.N keeps working exactly as before
  • Keys must be unique within a workflow
  • Only available on tasks after the initial form

Documentation​