Forms

Forms are used to capture data from end users (humans) and also to create tables (lists) of data that can be leveraged throughout the system. Forms are built using the Kinetic Form Builder, which allows builders to rapidly create interfaces that capture, validate, and store data.

Overview General Categories Attributes Security Indexes Submissions Workflow Best Practices

Overview

The Forms landing page lists all forms for the selected Kapp. From here, you can select a form to view details, filter the list of displayed forms, import forms, and add new forms.

General

The General tab is where we set the form name, slug, and other identifying information. It includes the following information:

Name: The Form's name.
Slug: The Form's unique identifier within the kapp. This value needs to be able to render in the URL, so the characters available are limited.
Description: A description of the Form.

Note: Descriptions are technically optional, but highly recommended even when the description will not be shown to the user. Including a description of the functionality provides some measure of basic documentation for the functionality of the form.
Status: This value doesn't do anything within the console or within the application. Instead, this value is used by the themes to determine which items render and can be submitted.
Type: A classification for use in the theme or by users as an additional form search parameter. It's not functional in the system beyond that.
Submission Label: A customizable way of identifying individual requests. These can include text and any value from the submission. For example, you could enter the following submission label for onboarding:
On-boarding for ${values('New Hire Name')} Requested by ${values('Requested By Display Name')}
This label could then be used when identifying the request, either instead of or in conjunction with an Id sort of identifier.

Attributes

The Attributes tab is where you apply attributes to the Form. As with Categories, Attributes cannot be created here, only applied. If you need to create new attributes, go to Attribute Definitions within the Kapp the form is in.

Note: Form attributes are Kapp-specific. Defining form attributes in one kapp does not make them available in other Kapps in the same Space.

To add an attribute, you need to select it from the drop-down list, add the desired value for that attribute, click Add Attrbute, then click Save Attributes. If you leave the tab without clicking Save Attributes, your changes won't be applied.

Some attributes can only be added once, while others can be added more than once. This is set at the attribute definition level and can only be changed there.

What attributes are used for is limited only by imagination. For example, the workflow engine can use attributes to determine the correct assignee group(s). They are there to be used as needed.

Security

This is where the security definitions defined in the Kapp are applied to the form.

Note: You don't need to specify security rules for a form unless you want to override what is defined at the Kapp level.

The Security tab has the following options:

Anonymous: Indicates whether the form should allow for anonymous submissions. See Anonymous Forms for more information.
Form Display: Controls who can see (and therefore submit) the form. It is not possible at this level to allow someone access to see but not submit the form. That would need to be controlled with rules on the front-end, such as an advance condition, or within the workflow engine after submit (to not process or delete the submission).
Form Modification: Controls who can change/update the form. This is often set to a security definition that includes form developers and platform admins.
Submission Display: Controls who can see submissions. This is often set to the submitter of the submission and platform admins. Submission Display access also becomes important when retrieving search results. Searches will error if they contain too many (>25) submissions the user cannot access. This is something to keep in mind when determining access for various forms and when constructing search queries.
Submission Modification: Controls who can modify a particular submission. This is often set to the submitter of the submission and platform admins.

Anonymous Forms

Anonymous forms allow you to capture data from your target audience without knowing who they are. The Anonymous feature is typically used for surveying employees or customers without revealing their identity, even if they are users in other areas of the Kinetic system.

When the Anonymous feature is enabled, submitting, closing, or otherwise updating a submission sets the submittedBy, updatedBy, and closedBy properties will all be set to "Anonymous".

Forms set as Anonymous and forms that allow unauthenticated users to submit are not the same.

To set a form to be Anonymous, select the Anonymous checkbox on the Security tab. This tells the application not to capture any of the information about the user who submitted it.

Forms can be set up to require the user to log in but do not not capture the submitter's information, or to be public and not require a login.

To make a form public so that users don't need to be logged in, you can do one of the following:

Set the form's "Form Display" security policy to "Everyone" for submitting a new submission
Set the form's "Submission Access/Modification" security policy to "Everyone" if they are pre-generating a submission and sending it as a link (for example, when filling out a survey).

Important: If a user is logged in and you have a Bridge that is fetching the user's information and setting a field (such as the "Requested By/For" field), that information will still be captured and stored as a field value – even if the form is set to Anonymous.

If you want your forms to be truly anonymous, you'll need to disable any Bridges that are fetching user info and setting that data into fields.

Indexes

The Index Tab contains the Indexes information for the form.

Definitions tab

This section displays the form's indexes. As you add and remove fields the indexes are created for the individual fields. There are also standard indexes which are created for certain core fields and on the forms. Additional indexes may be manually created.

Any search performed must use indexed fields. If a search is performed using multiple field values in a Bridge or API for example, those fields must be indexed. When multiple vaues are used in a search an index must contain the fields in the search.

To add an index, use the "Add Index Definition" button and add 1 or more fields or core values to an idex. The indexes may be edited and deleted using the coresponding buttons at the right of each row.

Kapp Definitions tab

This section displays the Kapp's indexes. Not all indexes and fields displayed for the Kapp apply to every form. If the "Applies?" column is checked for a row, the index applies to this current form.

Note: You cannot make changes to the Kapp indexes from this tab. Click Go To Kapp Index Definitions to make changes.

Maintenance tab

This tab displays the status of any indexing jobs for the form.

Submissions

This tab displays a list of submissions for the form, beginning with the most recent. When you click on a submission, the details for the submission are displayed.

The Submission Actions option lets you export, import, and bulk submit submission records. See How to Mass Submit Form Submissions and How to Mass Update Form Submissions for more information.

Submission States

All form submissions are assigned one of three coreState values, which are displayed in the State column of the Submissions tab:

Draft: Used for partially completed submissions. Records with incomplete required fields can be saved with this state.
Submitted: Used for records that that have been submitted but have not been closed. This coreState can't be applied to records with incomplete required fields.
Closed: Used for submissions that have been deemed complete. Submissions that are marked Closed are locked from further edits.

The coreState tells the Platform when to fire different workflow events.

Workflow

This tab displays the workflows for the form. A status of "Undefined" indicates that no workflow exists for the coresponding event in the row.

You can add, edit, or delete workflows using the icons at the right of each row.

Note: Workflows defined at the form level apply to submissions for the specific form. To apply workflows to all submissions for the Kapp, you'll need to create the workflow at the Kapp level.

Best Practices

Keep the following best practices in mind when creating, editing, or deleting forms:

Form Slugs

Because the form slug is the form's unique identifier, we recommend that you do not update the slug once the form has production submissions. The form name, however, can be updated as desired.

Logged In Users and Anonymous Forms

If a user is logged in and you have a Bridge that is fetching the user's information and setting a field (such as the "Requested By/For" field), that information will still be captured and stored as a field value – even if the form is set to Anonymous.

If you want your forms to be truly anonymous, you'll need to disable any Bridges that are fetching user info and setting that data into fields.

Closing Submission Records

While not technically required, we recommend you include an step in your workflows to move the coreState of submissions that are no longer required to Closed. This reduces the number of records that need to be queried if you are looking for Draft or Submitted records.