- Upgrading from v1.x
- Finalized Submissions
- Debugging Mode
- API Error Codes
- API Sessions
- Feature Suggestions
This page explains a problem that arises from using the API for your forms. For multi-page forms, it's entirely possible that some users will begin entering the form but never complete it. As you may know, Form Tools accounts for this by only "finalizing" the submission (i.e. making it appear in the UI) when it's explicitly told to do so. This is generally done on the very final step of your form.
But what about all those orphaned, unfinalized submissions? Well, they end up hidden in the database, never to be used or seen again. Generally, this is not a big deal. In fact, during the entire lifespan of Form Tools 1.x (which uses a similar finalization mechanism), no-one once asked about this in the forums (!). A little database clutter isn't a disaster, but it would be nice to avoid.
But now onto the real problem. What if your form contains one or more file upload fields? What happens
to those files that are attached to these unfinalized submissions? Exactly: they end up on your server, wasting
valuable disk space. With the new API functions in Form Tools 2, this could become a real problem. The
processFormSubmission() function significantly improves the file uploading mechanism to allow file
uploads on any page - hence, could result in files being uploaded that are associated with submissions that
never get finalized. So they end up stored on your server indefinitely. Boo.
deleteUnfinalizedSubmissions() method. This function does the job of both deleting those
unfinalized submissions and associated files, keeping your server nice and tidy.
It takes two parameters: the required form ID, and optional parameter: a boolean (true / false).
If the second parameter is set to true, it deletes ALL unfinalized submissions in the database - everything made up to this very moment. By default, it's set to false. The default setting is that it deletes all unfinalized submissions that have been made more than 2 hours ago. This is because it assumes that people may be in the process of putting through a form - you don't want to delete those unfinalized submissions! So in 99% of cases, leave the second parameter to false.
The method returns the number of unfinalized submissions that it just deleted.