ArticleWithInlines

This overview describes what happens when form data is saved to the iCM database. It provides information about object types, forms that use external types, and how best to interact with saved form data.

If you are creating forms that save their data to iCM, or forms that have an external type definition (map their fields to another form's object type definition), you need to be understand how the form data browser works before giving users "edit" access to the saved data.

Saved Data and iCM Objects

A published form creates an  Definition named after it, which is the form name with a FORM_ prefix. This type definition describes the structure of the form data. (It actually creates one per page, carry on reading for why you need to keep that in mind)

Object type definitions contain properties. In the case of forms, each property is a field on your form.

If your form does not save submissions using the , the type definition simply exists with its collection of properties.

If your form does save data, it creates an iCM object of its type each time it is submitted. An iCM object is the data that has been written to the database. The type definition describes the structure of the data, each individual object is a packet of saved data (a form submission).

Example Form, Object Type Definition and Object

This form, called SAVESOMEDATA, has two fields, one called FIRSTNAME and another called SECONDNAME. It saves data to the iCM database when it is submitted.

Here's the form's type definition, created automatically when the form was published. Note its name and the names of the properties.

As the form is submitted, objects of this type are created. You can export these objects as XML documents from this management section, as described in the  article.

Here's a single object created by our example form. It contains a section of data properties (information about the object, not to be confused with the properties described above!) and our saved form data.

<?xml version="1.0" encoding="UTF-8" ?>-
<icm format="2" version="10.0.5.0">
    <objects type="FORM_SAVESOMEDATA">
        <alldata>
            <properties>
                <objectid>170</objectid>
                <label>F01347C1-4276-440D-8FFF-BFD656E515DB</label>
                <type>FORM_SAVESOMEDATA</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>

If the example form had been submitted multiple times, the <alldata> element would be repeated for each form submission (that is, for each object).

Each object has a unique label and a unique object ID.

Edit Mode in the Data Browser

The Form Data Browser lets you edit the objects created by a form submission.

It does this by loading a form in iCM, just as your site does when you view a form using the Forms template. It then populates the fields on the form with the object data that was created by the form submission you are interested in.

Because the data browser is using a form to display the data, all of the buttons, actions, functions and handlers present in the form design will also be present when when you edit the form data. That means that if your form has a page initialisation handler that clears all of the fields on the form when it first loads, it will also be triggered in the data browser and you'll clear all of the field values when you edit the saved data.

You'll also need to be aware that if you add or remove fields or pages in a form, or change the names of existing fields or pages, you will orphan data that has already been saved. That is because the properties of an object have the same names as the fields of the form that created them. If you change the names of those fields, the link will be broken with any eject data that has already been created.

In the example above, if I remove the FIRSTNAME field, or change its name, the saved value "Leo" will still be in the iCM database, but when I view the data in the Form Data Browser, the link between the saved data and the form will have been broken. This will also happen if you add an additional page to a single page form, because the type definition name will change to include the page names.

Finally, if you submit a form while editing its data in the Form Data Browser, all of the action fields on the form will be triggered too. That means you'll send emails, start workflows, trigger payment fields, log histories... you can see why this gets problematic. Having said that, if you do need to update saved form data, you will need the "Database Save Action" on the form, just like when the data was first submitted.

Working With Form Data

So, what is the best approach to take when working with saved form data?

View, Search and Export

In the vast majority of cases, all you will need to do is view the data that has been saved by your form. Fortunately iCM makes this easy.

When browsing through the form data explorer you can choose to "view" data rather than edit it. Viewing data gives you a read-only version, which means all of the potential problems mentioned above don't apply.

Searching and exporting data also works in read-only mode, so you will only ever see the object data as it was submitted by the user who filled out your form.

External Types - The Safe Way to Edit Form Data

As described above, when you publish a form it usually creates an object type definition of its own that defines the structure of the objects that store the data of the form submission.

When you , one of the options is to assign it an "External type definition". This means that the form will map all of its fields to the properties (ie the fields) of another form (or any other object type) instead of creating its own object type definition.

That means you can create one form that is published on your website for people to fill in, and another, which uses the website form as its external type definition, which is used in the form data browser to view or edit the data.

The website form can include all of the action fields and JavaScript handlers, while the data browser version will have simple fields to hold the values of the other form and a database save action to perform the update.

Furthermore, you can use iCM Content Privileges to stop users having access to the website form in the data browser - they will only see and be able to use the "safe" form.

There's a more detailed look at external types in the  knowledge base article.