Toggle menu

Forms and External Type Definitions

This documentation describes form data stored using the Database Save Action and queried in the Form Data Browser. In most situations where you need to pass data between forms, it is far better to use features in the workflow process modeller (see Getting Started with Workflow)

Forms and Type Definitions

When a form is published, it creates an Object Type Definition named after the form, called FORM_FORMNAME. This type definition describes the structure of the data submitted by the form. Although these type definitions can't be seen directly in iCM, it's handy to know how they work.

A type definition, whether created manually in the Object Types section of iCM, or via a form, contains properties. In the case of forms, each property is a field on your form - properties and fields share their names.

This form, called EXAMPLEEXTERNALTYPE, has two fields. The fields are called FIRSTNAME and SECONDNAME.

A Simple iCM Form
 

If your form includes a "Database Save Action" field, when users submit it, iCM objects are created for each submission. Each object holds the data of the form submission, and the structure of the object's data is defined by its type definition. When you view saved form data in the Form Data Browser, you are viewing saved objects.

Here's an example object, exported as XML, created when the form above was submitted. You can see the two properties, firstname and secondname, in the <content> element.

<?xml version="1.0" encoding="UTF-8" ?>-
<icm format="2" version="10.0.5.0">
    <objects type="FORM_EXAMPLEEXTERNALTYPE">
        <alldata>
            <properties>
                <objectid>170</objectid>
                <label>F01347C1-4276-440D-8FFF-BFD656E515DB</label>
                <type>FORM_EXAMPLEEXTERNALTYPE</type>
                <createdby>ANONYMOUS</createdby>
                <createdon>10-05-2017 10:09:01</createdon>
                <lastupdatedby>ANONYMOUS</lastupdatedby>
                <lastupdatedon>10-05-2017 10:09:01</lastupdatedon>
            </properties>
            <content>
                <firstname>Leo</firstname>
                <secondname>Haynes</secondname>
            </content>
        </alldata>
    </objects>
</icm>

Forms and External Type Definitions

When you create a form you can select an "External type" definition for it to use.

Selecting an External Type
 

This means that, rather than it creating its own type definition when you publish it, it will use a type definition that already exists.

Sharing a type definition means that your form will map its structure (ie the fields in the form) to the structure of the type definition.

As we've already seen, a type definition contains properties, and these properties correspond to the fields on a form. When you create a form with an external type, the fields on the form need to map their names to those of the chosen type.

The forms designer helps you do this.

Designing a Form

When you add a field to a form that uses an external type, the "name" property of the field lists all of the properties of the external type. You need to pick the property you would like to map your field to.

The example below shows a new form being created. It uses the EXAMPLEEXTERNALTYPE form above as its external type.

Field Name Mapping with External Types
 

A text input field has been added to the form and you can see the two possible names it could be given. These names are the name of the object type definition (the name of the other form) and the names of properties in that definition (fields on the other form), separated by a dot.

Mapping names like this is how iCM ties the two sets of data together.

Once you have selected a name, further fields on the form won't be able to reuse it - they will need to map to a different property.

Which Fields?

Only input fields are mapped between forms that share their type definitions.

Fields like layouts, guidance text, helper variables and the "template" types don't store any data when a form is submitted. This means that the object type definition ignores them.

Adding More Fields

Because your new/second form is mapped to the structure of an existing definition, it can only include input fields that exist in that external type definition.

If you need to add additional input fields to the new/second form, they first need to be added to the definition.

Searchable

If you are saving form data and want the values submitted in a field to be indexed by the search, the "searchable" property of a field should be set to true. If your form uses an external type definition, the settings in the external type determine whether a field is searchable, not the settings in the form you are designing.

An Example

This example demonstrates two forms sharing a common type definition. It uses a simple "customer" form which a website user submits, and an internal "staff" form for a staff member to view the submission and add notes to.

The Type Definition - A Master Form

The type definition can be created in two ways.

You could go to the Object Types section of iCM management and create the type and its properties manually.

An easier way is to create a "master form" in the iCM Forms Designer. This master form won't be completed or even seen by anyone, it is simply used to create the underlying properties of our type definition.

This master form has four fields, NAME, DATE, ENQUIRY and RESPONSE.

A Master Form
 

The fields are all text input fields. The values of their labels and other properties are not important. The form shouldn't contain any action fields or buttons.

The master form should always be a single page form with all of the fields you may need on it. The user forms you design can be multipage or single page.

The User Forms

This example uses two user forms - one for the customer, one for the staff member.

Each of these forms has their external type set as the master form created above. Here's how the customer facing form looks. You can see the external type has been set.

The Customer Form
 

Our two forms are slightly different. The customer facing form only includes the NAME, DATE and ENQUIRY fields we'd like the customer to fill out. The staff form includes the extra RESPONSE field.

Here's an image showing the two forms and the underlying object type definition.

Two Forms with Shared Type Definitions
 

The only restriction when designing forms like this is that their input fields must be mapped to a property of the type definition. You are free to make fields required, add validation and include JavaScript handlers as you wish.

There is no restriction on the number of forms that can share an external type. You could create another form that only displayed the name field, or displayed some fields as read-only.

The Published Forms

In our example above the customer form is published on our website.

The Form on the Website
 

Our staff form is used in the Form Data Browser to view the form submission.

The Form in the Data Browser
 

Our staff member can add a response to the enquiry, which will be saved in the same data object as the original.

Last modified on August 21, 2023

Share this page

Facebook icon Twitter icon email icon

Print

print icon