Form Data Model

The Form Data Model (FDM) is used to configure what non-application data (data that doesn’t come from 3rd party app integrations) will be collected from your end user. It is also used to configure what data may be entered or imported when an end user is invited to the platform as well as what data is displayed in the portfolio view.

The FDM is a hybrid model that configures both storage of data as well as data entry. It includes data types, validations, transformations and access control in a succinct JSON5 based data format.

Example FDM configurations can be seen in the https://github.com/boss-insights/kitchen-sink and https://github.com/boss-insights/simple-account repositories, the FDM must always be named data.json5 .

Configuration sections

The configuration is composed of the following sections: profile, portfolio, invitations.

Profile & Forms

By default every account has a built-in profile, this profile is a set of information that can be configured to contain an arbitrary number of data fields that will be associated with the end users account. Once defined the fields are displayed in an automatically generated HTML form for use within a workflow.

Each field should be given a name and type. The name is how the field can be uniquely referenced, should not contain space characters and is not visible to the end user. A field type should be specified to govern what type of data is required, if the type is not provided it will default to the text type. Depending on the field type chosen default validations will be applied, e.g. the email type will ensure a valid email address is provided.

Fields types

Type	Description
`text`	Regular plain text, no line breaks
`url`	A uniform resource locator
`email`	An email address
`number`	A number, can be either an integer or decimal
`table`	A method of managing rows and columns of data
`fieldset`	A container of fields, used to create logical groupings and repeating sets of fields
`divider`	Decorative field type, does not store data but creates a visual separator across a form page to create sections
`comment`	Decorative field type that creates an HTML comment
`blank`	Decorative field type that creates an empty field
`hidden`	Stores data but is not visible to the end user
`textarea`	Regular plain text, supports line breaks for multiline text
`richtext`	Formatted text that can contain a subset of HTML formatting including basic text formatting and hyperlinks
`fileselect`	Allows for the selection of a file previously uploaded in the document manager
`select`	Allows for the selection of one or more predefined options
`file`	One or more files can be uploaded and accessed
`address`	A single line address, can optionally show a map for visual confirmation
`month`	Select a specific Month/Year combination
`date`	Select a specific date
`signature`	Regular plain text, no line breaks, decorated with a cursive signature like font
`tel`	Telephone number

Fields support a common set of attributes as well as attributes that are unique to a specific field type

Common attributes

Attribute	Sub Attributes	Description
`name`		The name is used to uniquely identify this field Every non-decorative field should have a name
`type`		Field type governs what type of data can be input, e.g. date or richtext
`title`		Used to label a field and is the primary indicator of what the user should enter, e.g. “Date of birth”
`access`	`read` , `modify`, `readHide`	Read and modify control which user groups can either read or modify a given field. If readHide is set to true, the field is hidden to users with read-only permissions. If false, then it will be visible to users with read-only permissions.
`attributes`	`pattern` , `placeholder` , `required` , `min` , `max` , `step`	Custom HTML attributes can be set on any field, which fields will be supported depends on the field type, e.g. “step” is supported for the “number” field type
`description`		Additional context can be provided to augment the field title and further explain a field
`sync`	`push` , `pull` , `entity` , `field`	Used to indicate whether a field should synchronize with an external CRM/LOS platform
`visibility`	`contains`(field,value) OR `condition`, `requiredWhenVisible`	A visibility condition can be provided as a Javascript expression, which when evaluating to true will show the field, otherwise hiding it. A simpler alternative is using “contains” and then specifying a field name on the same form and what value it should contain in order to show the current field. If `requiredWhenVisible` is set to `true`, the field will also gain the `required` attribute when visible.
`hint`		An icon close to the field title which when clicked on or hovered over will reveal additional information. Supports HTML formatting and links.

Unique attributes

Attribute	Applies to	Sub Attributes	Description
`multiple`	`file` `select` `fieldset`		true or false, whether the field can allow multiple values. For fieldsets this allows for multiple copies of all fields.
`accept`	`file`		a string that describes a type of file that may be selected by the user, e.g. “.pdf“
`fields`	`fieldset`		A fieldset can contain a list of fields. Note a fieldset cannot contain a fieldset.
`values`	`select`	`title` , `value` , `data`	Values for `select` fields contain a `title`, `value` and optionally `data` . If a title is not provided then the `value` will be used also as a title.
`default`	`date`		e.g. “today”
`prepend`	`text` `number` `url` `email`		A short piece of text to add to the right side of an input, e.g. “%”
`append`	`text` `number` `url` `email`		A short piece of text to add to the left side of an input, e.g. “$”
`width`	`text` `number` `url` `email`		Specified in CSS width units. Useful to indicate to the user the expected length of input.
`typeDisplay`	`select`		Select inputs automatically adjust to either HTML select or input widgets (as either radio or checkboxes) depending on the number of selectable values. This attribute allows you do override this to be either: “full” - forces use of Radio or Checkbox widgets depending on the value of `multiple` “select” - forces use of an HTML select field
`link`	`text` `number` `url` `email`	`values` [(key, field)] , `byRef`, `ifEmpty`	It is possible for one field to refer to the value of another field, either in the same form or a different one, i.e. an additional form may refer to a value in the profile form. When byRef is set true then the value of the current field is always the value of the referred field. When it is set to false, the value can be modified. When ifEmpty is set to true then the link field will only be overwritten if it is empty. If this is true and the field has an existing value then it will not be overwritten. When it is set to false, it will always overwrite.

Example Code

JSON

      {
        name: 'full_name',
        type: 'text',
        title: 'Full Name',
        access: {
          read: [
            'admins','underwriters','borrowers'
          ],
          modify: [
            'admins','underwriters','borrowers'
          ]
        },
        attributes: {
          placeholder: "Enter your full name",
          required: true,
        },
        description: "This is the full name input field",
        visibility: {
          contains: {field: 'required-info', value: 'user-info'},
// OR     condition: '$("input[title=\\\'User Info\\\']:checked").val() === "user_info"'
        },
        hint: "Enter your full name"
      },

Output

Additional Forms

In addition to the built in “profile” you may add additional forms by specifying them in the forms object within the data.json5 file. Additional forms may be added by specifying a unique form key which will be used to refer to the form from a workflow, then form then has a fields property which contains fields in the same format as the built in profile, a form may also have a title attribute which will be used as the form page header.

Portfolio

The portfolio is configured in the following sections:

owners - specifies the user groups that can be owners (managers, officers) of your portfolio accounts. Anyone who is a member of a group listed here will be able to be assigned as an owner
permissions - a list of permissions which specify view, edit and add access
fields - a set of profile fields to be shown in the portfolio, the syntax of these is similar to form fields (see above) but they are used for display purposes only and do not store data

Invitations

The invitations are configured in the following sections:

uniqueJoinField - specifies a unique field the value of which will be shown to an end user when they join the platform, e.g. “legal_name”. This helps disambiguate multiple invitations sent to the same email address
owners - specifies the user groups that can be owners (managers, officers) of your invitations, usually this is the same set as the portfolio but may be different. Anyone who is a member of a group listed here will be able to be assigned as an owner.
permissions - a list of permissions which specify view, edit and add access
fields - a set of fields that will appear when adding a new invitation and will also be available in the invitation file import process (when bulk importing users). When the names of these fields match names in the profile they will be automatically copied in to the profile when the user joins the platform. The syntax of these is similar to form fields (see above).

Deployment

To deploy changes to the FDM you upload the new data.json5 via WebDAV to the /public/dashboard folder.

Additional Logic

Javascript code can be added to FDM pages by creating a forms.js in the same folder as the data.json5 file. This Javascript will be included on every FDM based form page and can be used to provide additional logic, fetch external data and other purposes.