Setting up a Form within a Workflow

This article walks through the basic steps of setting up a Form within a Workflow.

Table of contents:

Getting Started

Where do I find the Form Configuration page?

How do I start building a Form?

How do I add fields to an existing Form?

How do I edit Section visibility?

How do I make a field Mandatory or Hidden?

How do I add a Section Description?

How do I "lock" a field?

How do I "unlock" a field?

Updates & Amendments to your Configuration

How do I delete a Form field?

How do I delete a Form section?

How do I edit fields in a Section?

Appearance & Other Settings

How do I set the Card Name?

How do I amend Form Layouts?

 

Where do I find the Form configuration page?

On the FIRST Workflow Phase, click the menu icon (three vertical dots) and then select "Edit this Phase"
Then, navigate to the "Form" tab along the right-hand side



💡 This FIRST phase is where the majority of your form-building should take place (i.e. adding form sections, editing fields, adding descriptions etc.)

You will see why in later configuration chapters...

How do I start building a Form?

From the Form tab, click "ADD SECTION" to start building the Form. 

Gatekeeper 2020-09-10 12-55-34

The Form Section builder will open. This will allow you to create a new form section from the 2 below categories:

    • Core Metadata - to select this, choose a Predefined option (Supplier or Contract) then leave the Custom Data Group option blank
    • Custom Metadata - to select this, choose a Predefined option (Supplier/Contract) then select the name of the Custom Data Group you wish to add to the form
    • Attached file with Expiry Date

💡 Once you have added a Custom Metadata group to a Workflow Form - any new fields which are added to the custom group will automatically add themselves to the workflow form too! 

  • Workflow Only Forms - these fields exist only in the Workflow and are primarily used to drive the form experience and build automated Workflow transitions based on a specific input.
    • To select this section type, leave the Predefined option blank

Ensure that a "Section Name" has been added and specify any Predefined data fields before clicking on "Save"

Gatekeeper 2020-09-10 13-12-14

Please keep the following considerations in mind when configuring Sections:

Section Name - Freeform text. This will be shown and formatted as a heading on the Form

Predefined - Dropdown. When used, this will build the form section from metadata fields in your repository

Custom Data Group - Dropdown (hidden until "Predefined" is set). This allows for the use of Custom Data Groups (if present)

Description - Freeform text. Populate this if you wish to give guidance/context to your users when they come to this form section (and be sure to check "Display Description"!)

 

If any "Predefined" options are selected (Supplier, Contract, File with Expiry), the form will be populated with all the related fields. The below example displays Gatekeeper core Contract fields. 

How do I add Fields to an existing Form?

You may add fields directly to a form section in 2 scenarios:

1) While building a "Workflow Only" Form Section

2) When re-adding fields to a "Predefined" Form Section (e.g. where a field had previously been deleted and you wish to restore it!)

From any Section where visible, click the available "ADD FIELD" option. 

Gatekeeper 2020-09-10 14-18-12

Then, simply enter a Label along with any other the specifics before selecting "Save". 

Gatekeeper 2020-09-10 14-24-08

Any newly created Workflow form fields should now appear in the appropriate Section. 

Gatekeeper 2020-09-10 14-25-47

Here's how the new "Request Priority" field would display on the Form:

How do I edit Section visibility?

Each Section of a form can be set as:

  • Read only
  • Hidden
  • Editable

Note: Section visibility can be set independently in each phase of any Workflow.

EditVisiblity

"Custom" offers the flexibility to build tailored visibility criteria. This means that Gatekeeper will check a set of criteria (configured by you) to set the visibility of the Form Section for each card which arrives at the phase and is viewed by users.

Tailored visibility criteria can be applied to all users viewing the form or can be applied at a Workflow Group level.

💡 If no workflow group is set, the rules will apply to all users

For more detailed information on Workflow Groups, click here.

CustomVisibility

To add conditions to form visibility, select Custom then click the "ADD" button to add your rule/s

If your rules are set to "Based on: And", ALL conditions must be true when a card enters the phase for the designated visibility option to be applied

If your rules are set to "Based on: Or", ANY conditions in the list being true will apply the designated visibility option

If no conditions are entered then the visibility will always be considered as true

It is possible to create complex form visibility rules through using multiple sets of conditions. The system will prioritise the most specific rule to the user. i.e. applying visibility for the user's Workflow Group first

How do I make a field Mandatory or Hidden?

For each field,  you have the following checkbox options:

  1. Mandatory - You can set this field to be required for Form/Phase completion on a field by field basis, or for all fields in the Section by choosing the first "Mandatory" checkbox. 
  2. Hidden - You can select this option to hide the field from your Form/Phase completion on a field by field basis, or for all fields in the Section by choosing the first "Hidden" checkbox. 

Note: You cannot have a field set to Hidden and Mandatory at the same time. In this case, selecting the second option will deselect the first automatically. 


Gatekeeper 2020-09-10 14-16-08

How do I add a Section Description?

When creating the Section, ensure that a Description is included and "Display Description" is checked before hitting "Save". 

Gatekeeper 2020-09-10 13-21-54

To edit or add the Description for an existing Section, click on the "Edit" icon to the right-hand side.

Gatekeeper 2020-09-10 13-26-21

The Description will display on the Form as highlighted in light yellow below: 

Gatekeeper 2020-09-10 13-28-48

How do I lock a field?

Locking a field is a way to remove the amount of manual input required by users when submitting new request forms. When a field is locked on a start phase, it cannot be edited by a user submitting a new card

i.e. the field will always be pre-populated and uneditable for all new cards

To lock a field to a pre-determined value, from the Form tab of the Start Phase, hit the pencil icon to edit a field, then click "Locked".

This will open a new pop-up, allowing you to choose what to set as the locked value

Ensure you Click ✅ Save after selecting the Locked value!

This will appear to the user pre-filled and greyed-out:

This is common to perform for fields such as "Contract Status" and "Contract Approval" which will always be "Pipeline" and "Awaiting Approval" respectively for any new contract request but you may think of uses for other fields where it is possible!

NB. After a card has been created, locked fields can be edited later in the workflow. They are not locked for the whole process!

💡 Pro Tip: To make your request forms shorter and clearer, it can be useful to set any locked fields to "hidden" so your users only see what is relevant to them! 💡

How do I unlock a field?

After "locking" a field, it is possible to remove the Locked value (or "Locker" as they're sometimes referred to in the system)

1. Click to Edit the field

2. Untick the ☑️ Locked checkbox

3. Hit ✅ Save

This field will now be unlocked for new forms

4. Click to Edit the field again

5. Tick the ☑️ Locked checkbox

6. Hit the X next to the saved field value

7. Hit ✅ Submit

8. Untick the ☑️ Locked checkbox

9. Hit ✅ Save

You will now be able to remove the field value stored as the "Locker" value.

(This is a mandatory step for any values you wish to remove permanently from Gatekeeper)

How do I delete a Form field?

If a Form field is available for deletion, clicking the "Edit" (three dots) icon to the right of the field will reveal a trash can icon. Gatekeeper will ask if you are sure before you select "Delete". 

Gatekeeper 2020-09-10 14-48-03

How do I delete a Form section?

If a Form section is available for deletion you can do this by clicking the trash can icon to the right of the form visibility rules. Gatekeeper will ask if you are sure before you select "Delete". 

⚠️ Warning - once you delete a Field or Form Section, any workflow cards with those value populated will permanently lose that data!

Re-adding the fields/sections will not restore previous card data to the workflow form!

How do I edit fields in a Section?

To edit any of the fields housed in a Gatekeeper Form Section, just select the Edit icon (three dots) to the right of the appropriate field. 

Gatekeeper 2020-09-10 13-42-37

Click the pencil/paper icon to modify the Form field.

Gatekeeper 2020-09-10 13-44-50

From the corresponding screen, designate any of the following:

  • Label - This is how the field will be labelled in the Form and throughout the Workflow process
  • Set as card name - This determines the Card Name as shown in the Workflow
  • Type  - Choose from an available Gatekeeper field type. For more detailed information regarding field Types, click here

Note: The Type for any Gatekeeper field is locked once created and cannot be changed. This option will be restricted unless a new field is being added. 

  • Description - This offers a place to house a description of this field Gatekeeper for informational purposes
  • Text - This is the text appearing when a user hovers over the "i" icon (only visible on the Form if Text has been added).
  • Link - A URL can be added here if desired, recommended to use a shortened link for user experience.
  • Link Text - If entering a Link for your field, this can be used to give the URL a title (rather than displaying the whole URL itself!)

Gatekeeper 2020-09-10 14-05-40Here's how the "Contract Name" field would display on the Form based on the above configuration. 

Screen Shot 2020-09-10 at 2.02.14 PM

Be sure to click ✅ Save when done. 


How do I set the Card Name?

Typically, we see the card name being the Contract Name or Supplier Name.

In fact, if you add a Predefined Contract Core Metadata or Supplier Core Metadata form section to your workflow, Gatekeeper will choose the Contract Name or Supplier Name as your default Card Name automatically - whichever you add first

However, you can use almost any field in your workflow form to serve as the card name

To set the Card Name 🛠

1. Find your desired field within the First Phase's Form tab and select the Edit icon (three dots) to the right as shown below

Gatekeeper 2020-09-10 13-42-37

2. Click the pencil/paper icon to modify the field settings

Gatekeeper 2020-09-10 13-44-50

Check the box that says "Set as card name" and click "Save".

Gatekeeper 2020-09-10 14-32-23

 

The card name can be identified at a glance by the bold font when viewing it in the Form configuration page:

How do I amend Form Layouts?

There are 2 types of Form Layout.

1. Simple Layout

This presents all form sections to the form submitter in one continuous page. It maximises the width available for the input boxes.

This layout is better suited for shorter forms or forms where long inputs need to be provided

i.e. the Side Menu layout takes away some of the screen space from fields to display a menu. Therefore, users typing long answers or viewing long question names may prefer the Simple layout

2. Side Menu Layout

This layout gives the form submitter a way to paginate through each section.

This layout is better suited for long forms with many complex sections.

Changing Form Layout 🛠

Click LAYOUT on the form Phase

Form.Layout.Changing

You can customise the layout on a phase-by-phase basis or quickly set all phases to use the same layout by selecting "Apply to all Phases."

 

Up Next

Please read this article if you would like to understand how to now make your Form Public.