-
Notifications
You must be signed in to change notification settings - Fork 26
/
delete_unfinalized_submissions.html
75 lines (62 loc) · 3.18 KB
/
delete_unfinalized_submissions.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
---
layout: default
navPage: docs
heading: deleteUnfinalizedSubmissions()
breadcrumbs:
- API,/api/
- API v2.x,/api/v2
- Class Methods,/api/v2/class_methods/
- Other Functions,/api/v2/other_functions/
- deleteUnfinalizedSubmissions()
prev: displayCaptcha(),/api/v2/display_captcha/
next: checkSubmissionIsUnique(),/api/v2/check_submission_is_unique/
versions: FT3
categories: api
tags: developer,submissions
---
{% include open_section.html nav='nav_api_v2.html' selected='delete_unfinalized_submissions' nav_width=4 %}
<h3>The problem</h3>
<p>
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.
</p>
<p>
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.
</p>
<p>
But now onto the <b>real</b> 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
<code>processFormSubmission()</code> 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.
</p>
<h3>The solution</h3>
<p>
Enter the <code>deleteUnfinalizedSubmissions()</code> method. This function does the job of both deleting those
unfinalized submissions and associated files, keeping your server nice and tidy.
</p>
<p>
It takes two parameters: the required form ID, and optional parameter: a boolean (true / false).
</p>
{% codemirror php %}
$api = new FormTools\API();
$api->deleteUnfinalizedSubmissions($form_id, false);
{% endcodemirror %}
<p>
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 <b>false</b>.
</p>
<h3>Return Value</h3>
<p>
The method returns the number of unfinalized submissions that it just deleted.
</p>
{% include close_section.html %}