This article is a supplement to our documentation on the phone-call-log() function, and it is accompanied by a basic sample form, as well as an advanced sample version which retrieves even more information.
The phone-call-log() function is an essential function when running phone surveys. With this function, you can see when calls were started, ended, merged, placed on hold, and more. You can also use expressions in your form to process the logs for you. This article will walk you through a form design approach to summarize the raw phone call log data into quick, immediately understandable statistics.
Here is an example of raw (unmodified) data retrieved using the phone-call-log() function:
Form started||0
Call started (dialed manually)|0123456789|19
Call connected|0123456789|29
Call added (dialed manually, other call placed on hold)|5555555555|37
Call connected|5555555555|45
Call added (dialed manually, other call placed on hold)|+910123456789|49
Call added (dialed manually, other call placed on hold)|+915555555555|49
Call added (dialed manually, other call placed on hold)|0123456789|86
Call connected|0123456789|94
Call added (dialed manually, other call placed on hold)|+910123456789|96
Call added (dialed manually, other call placed on hold)|+915555555555|96
Call ended (other call resumed)||96
Call ended||120
Form exited||173
While much of the log is understandable at a glance, it can be tough to say how long calls last, how many phone numbers were called, and more. You can use a series of calculate fields to retrieve all of the information you need, as demonstrated in the sample forms.
In the basic sample form, calculate fields are used to retrieve these details from the call logs:
- Number of calls started
- A list of all phone numbers called, including doubles
The advanced sample form retrieves these details:
- Number of calls started
- Number of calls ended
- If there is a discrepancy between the number of calls started and the number of calls ended
- How long each call lasted
- Number of unique phone numbers called
- A list of unique phone numbers called
- Phone number of the longest call
- Length of the longest call
The most important fields can be found in the section Using the sample form below, but they are also referenced in the label of the note field "formatted_disp" in both forms. Each calculate field also has a label that describes what it does; because calculate fields labels do not appear in the form, use these to help you understand the form.
Using the sample form
To try either sample form on your own server, deploy it to your server with the phone-call field plug-in, download it to a device that can make calls, and try it out. The forms have different form IDs, so you can deploy both to your server at the same time. To learn more, check out our support article on deploying form definitions and server datasets.
To set up this system in your own form, first add a calculate field to your form called "phone-call-log" with a calculation of phone-call-log(). Then, in the sample form, copy either the fields on rows 27-37 of the basic form, or rows 27-74 of the advanced form, into your own form. That way, when the form is completed, the expressions will recalculate, and process the phone log. When reviewing your data, you will be able to view the completed phone log, as well as the result of the calculate field values. You can also reference those calculate fields as needed.
Here is a list of the most important fields in the basic form:
- num_started: Number of calls started while completing the form.
- All_pn: A comma-space separated list of all phone numbers called, including doubles.
And here is a list of the most important fields in the advanced form:
- all_simp_logs: A simplified call log showing a list of phone numbers called, when each call started and ended (time stamps given in time spent completing the form so far), and how long each call lasted.
- num_started: Number of calls started while completing the form.
- num_ended: Number of calls ended while completing the form.
- num_unique: Number of unique phone numbers called.
- unique_pn: A space-separated list of all unique phone numbers called.
- longest_pn: Phone number of the longest call made.
- longest_length: Length in seconds of the longest call.
The other fields in the form are used to determine the values of those fields.
How it works
To learn about the functions used in the sample forms, check out our documentation on using expressions.
Both forms
The repeat group "call_log_rep" cycles through each log, separating out each row of the log. Then, the item-at() function is used to retrieve the log action (the first part of each log) in the field "log_action" which is simplified using the field "log_action_simp" (e.g. the log "Call started (dialed manually)" becomes "Call started".
Basic form
Then, once each part of the log is retrieved and stored in a repeat group, it is time to use that information. The field "num_started" uses the count-if() function to count how many times the field "log_action_simp" has a value of "Call started" or "Call added", which is the number of times a call was started (it counts the number of instances of the field "log_action", but this is arbitrary, and any field in that repeat group will do). Then, the field "all_pn" uses the join-if() function to create the list of phone numbers called, only including the times the phone number is not blank.
Advanced form
In the "call_log_rep" repeat group, if the log is "Call started" (meaning the field "log_action_simp" has a value of "Call started") or "Call added", then it knows to start looking for when the call ended; if it is not, then it can move on to the next repeat, which is why the group "check_call_end" is only relevant when the simplified action is "Call started".
Once a call has been started, it retrieves the other pieces of information about the call, the time it started. Then, the repeat group "find_call_ended" looks ahead in the logs until it has found where the "Call ended", once it has, it stops repeating, and that log is stored in the field "call_end_log", and the time it stops is stored in the field "call_end_time". With the information stored in a repeat group, the join() function is used in the fields "all_pn_called", "all_call_start", and "all_call_ends" (rows 52-54) to combine all of that information; since the fields being joined are only relevant when the log action was "Call started", the join() expressions only join those "Call started" events.
With the information processed so far, it can then be further processed to retrieve other information about the calls. For example, the field "unique_pn" on row 56 uses the field "log_pn" to retrieve a list of all unique phone numbers, the field "num_started" on row 58 uses the field "log_action_simp" to determine how many times a call was started or added, and so on. Also, the repeat group "call_logs_simp_rep" and its subsequent field uses the values generated by the join() expressions to create a new, simplified call log that also shows how long each call lasted, along with other pieces of information.
Limitations
The sample form only works correctly when one call is made at a time, and no calls are merged or split (so if you're using conference calling for remote accompaniment, this solution won't work as-is). If a call is placed on hold, it will count that time spent on hold as part of the call. The form only accounts for when a call was started, ended, or added, but support for "Call added" in this sample form is limited.
Applying this to your needs
The sample form is an example, so feel free to change it depending on your own needs. If you like what this sample form can do, and you would like a more advanced version (i.e. a sample form or field plug-in that also checks for when calls were merged or split, takes call holds into account, etc), you can create a post in the forums, or submit a support request.
Do you have thoughts on this support article? We'd love to hear them! Feel free to fill out this feedback form.
0 Comments