Forms and collected information #

This page is for integrators who connect the forms of an Exponential site to a CRM, a ticket system or a marketing tool. A form in Exponential is a content object whose class has attributes marked Information collector; each time a visitor sends it, one collection is stored with one value per collector attribute. The administration side is Collected information.

Contents #

1. The ways out
2. collect.ini: what happens on sending
3. Reading new collections in a cronjob
4. Exports
5. Personal data
6. Checklist

The ways out #

The last one is the robust integration: it is structured, retried and logged. Mail parsing on the CRM side breaks with every template change.

collect.ini: what happens on sending #

settings/collect.ini, overridden in settings/override/collect.ini.append.php. Most settings have a default, a list per collection type (form, poll, feedback) and an attribute that lets the object choose:

Reading new collections in a cronjob #

Keep the id of the last collection you sent, read everything after it, send, and store the new last id. The tables are ezinfocollection (one row per sending) and ezinfocollection_attribute; the class is eZInformationCollection (kernel/classes/ezinformationcollection.php).

<?php
/**
 * Sends new collections of one form object to the CRM. $lastID is kept by the caller (a row of your own table).
 */
function myIntegrationSendNewCollections( $formObjectID, $lastID, $crmClient )
{
    $db = eZDB::instance();
    $rows = $db->arrayQuery( 'SELECT id FROM ezinfocollection WHERE contentobject_id = ' . (int)$formObjectID
                           . ' AND id > ' . (int)$lastID . ' ORDER BY id', array( 'limit' => 200 ) );
    foreach ( $rows as $row )
    {
        $collection = eZInformationCollection::fetch( (int)$row['id'] );
        if ( !$collection instanceof eZInformationCollection )
            continue;
        $fields = array();
        foreach ( $collection->dataMap() as $identifier => $attribute )
        {
            $fields[$identifier] = $attribute->attribute( 'data_text' );
        }
        if ( !$crmClient->sendLead( (int)$row['id'], $fields ) )
        {
            return $lastID;               // stop; the next run retries from here
        }
        $lastID = (int)$row['id'];
    }
    return $lastID;
}

dataMap() indexes the collected attributes by their class attribute identifier. Text values are in data_text; numbers in data_int or data_float, depending on the datatype. Send the collection id along, so the CRM can refuse a duplicate when a run is repeated (Idempotent imports).

For whole lists, eZInformationCollection::fetchCollectionsList( $contentObjectID, $creatorID, $userIdentifier, $limitArray, $sortArray ) and fetchCollectionsCount() are the kernel's fetches.

Exports #

• The CSV export at Setup > Collected information downloads infocollector/export/<object id>: UTF-8 with a byte order mark, the collection id, sent and changed times in UTC, the sender's user id, one column per collector attribute; at most 50 000 collections. Values that a spreadsheet would read as a formula start with an apostrophe. Each export is recorded in the audit as data.export.csv.
• bccie (required as ~1.1.18) exports collected information as CSV or SYLK on demand or by its cronjob parts (bccie).

Personal data #

Form answers are usually personal data: names, e-mail addresses, messages.

• Send only the fields the receiving system needs.
• Delete collections in Exponential once they are safely in the CRM, if the customer's retention rules allow it (Setup > Collected information, Remove; recorded as data.infocollection.remove).
• Keep exported files where personal data belongs, and delete them when no longer needed.
• Write the data flow into the customer's record of processing; this is not legal advice (Protecting customer data).

Checklist #

• To do: Which form objects are integrated, and which fields go where.
• To do: The mail on sending switched off where the cronjob replaces it, so leads do not arrive twice.
• To do: The last sent id stored durably; the CRM refuses duplicates by collection id.
• To do: Failed sends stop the run and are retried; the run is logged and monitored.
• To do: Retention agreed for collections in Exponential and in the CRM.

Related pages #

• Collected information
• bccie
• Cronjobs for integrations
• Forms and member feedback for associations
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.