Working with a form's schema
The first step to building out a custom form is to know the schema for the form you wish to create. Form schemas contain all of the relevant information to build out a user interface to populate a form. They also include information for possible reviewers as well as available statuses. This data can be used in other API calls to set assignees and statuses for specific form entries.
To fetch the model and schema for a form, use the endpoint GET /formsapi/public/form/{formId}. The form ID can be found by going to the main Form admin landing page and editing the desired form. You will see the form ID as part of the URL for the page (e.g. /forms/manage/2 is form ID 2).
The properties for a form are available via the auto-generated documentation for the FormFlow API. This can be found by adding /formsapi/apidocs/index.html to your sites root URL (e.g. https://myintranet.com/formsapi/apidocs/index.html). Look at the bottom of the page for the Model definitions.
Sections and Fields
All forms are separated into sections. Each contains a list of fields. Some fields, like table fields, also contain child fields themselves. API consumers may iterate on the sections, fields, and child fields as specified from the Form schema to build out a form interface based on the appropriate field type.
Details on turning form input values into a valid form entry data object for submitting or editing a form entry can be found on the page API form field data.
Just looking for Fields?
Sometimes all you need is the list of fields, and what the labels are for those fields. This is useful when processing data for form entries, when you want to figure out what the corresponding field is given just a field ID. To get just a flattened list of all the fields available for any given form use the endpoint GET /formsapi/public/form/{formId}/fields.
Working with form logic
Most properties are self-explanatory. Some complexity is involved when dealing with form fields that have logic associated with them. These are fields which when set to specific values, will either show or hide other areas of the form. The main actions that can be performed are specified in the FormLogicAction enumeration.
FormLogicAction:
- 0 = None
- 1 = ShowField
- 2 = HideField
- 3 = ShowSection
- 4 = HideSection
To get this data from the form schema there are 2 options available.
Form logic from field options
Any field that has logic associated with it will have the relevant properties set as part of the options for that field. Options are for dropdowns, radio buttons, and checkboxes. For example:
"options": [ { "optionId": 342, "sortOrder": 0, "value": "1597254385352", "label": [ { "key": "en", "value": "Choice 1" } ], "logicAction": 3, "logicTargetId": 11, "isDeleted": false }, { "optionId": 343, "sortOrder": 1, "value": "1597254497857", "label": [ { "key": "en", "value": "Choice 2" } ], "logicAction": 0, "logicTargetId": 0, "isDeleted": false } ]
In the above, the first option has a logicAction of 3 which corresponds to FormLogicAction.ShowSection. When this field is set to this option with value "1597254385352" then the section with id 11 should show. Based on this, the section with id 11 should NOT be visible by default when building out the form.
This data is available on every option. Any option that has logicAction of 0 has no logic associated with it.
FormLogicMapping list
This is a special array property available at the top level of the form schema. No need for processing sections, fields, and child fields. This array of objects simply aggregates all fields that have logic on them and makes them available in one convenient place. This way you have less processing to do when building out your form.
The property is a list of type FormLogicMapping that contains the following:
- sourceFieldId: The field for which the logic mapping applies. NOTE: The same source field may occur multiple times if it has multiple options that contain logic.
- triggerLogicValue: When the source field is set to this value then the logic action should be triggered.
- logicTargetId: This is the target of the logic. It may be a section or a field depending on the FormLogicAction type.
- formLogicAction: This is the action to be performed when the trigger logic value has been set.
- 0 = None
- 1 = ShowField
- 2 = HideField
- 3 = ShowSection
- 4 = HideSection
- targetVisibleByDefault : This helper property will state the default visibility of the target. It can be deduced from the FormLogicAction as well.
For example:
"formFieldLogicMappings": [ { "sourceFieldId": 36, "triggerLogicValue": "1620144359981", "logicTargetId": 37, "formLogicAction": 1, "targetVisibleByDefault": false } ]
This means the form contains only 1 field that has logic associated with it. When the source field with ID 36 is set to 1620144359981 then the field with id 37 should show. The target field 37 is not visible by default.
Comments
0 comments
Please sign in to leave a comment.