WARNING: this is a new and advanced CommCare feature

This page contains advanced CommCare functions and so is not recommended for CommCare beginners. The functionality explained here is also quite new and limited for the moment. Feedback to improve this functionality is appreciated.


The call center application setting allows an application to reference a mobile user as a case that can be monitored using CommCare.  This allows supervisors to view their workforce within CommCare.  From here they can do things like monitor workers with performance issues, update their case with possible reasons for poor performance, and offer guidance towards solutions.

The setting is called “call center application” because it was originally envisioned as a way to outsource workforce monitoring to call centers, who could contact FLWs experiencing performance issues, offer feedback, and provide basic troubleshooting support, and ultimately escalate issues that are beyond the scope of call center troubleshooting to project managers.  Project managers, therefore, would have to spend less time dealing with trivial issues that can easily be remedied remotely, and instead focus more of their attention to larger issues and project goals.

To enable the call center application :

  1. Navigate to orange “Project Settings" button on the top right-hand side of the CommCareHQ domain (the button should have a gear symbol and the name of your project domain).
  2. Go to "Feature Previews" under "Project Administration".
  3. Enable the "Call Center" feature (tick the box and click on the "Update previews" button).
  4. Go to "Basic" under "Project Administration".
  5. Check the box entitled “Call Center Application”. This will cause two more test fields to appear :
    • “Call Center Case Owner” is the mobile worker or group to whom you would like the "mobile worker" cases to be assigned - in other words, this is the mobile worker that is the call center agent or field supervisor. Note that only groups or mobile workers that have case sharing enabled can be used here.
    • “Call Center Case Type” is the case type of your mobile worker cases. This case type is independent of the user-as-a-case feature which is of type commcare-user and owned by that particular user. In contrast, the call center/supervisor case is a user-defined case type and owned by the user-defined case sharing group or a particular supervisor user.

 

For our purposes let’s assume the owner of the call center cases will be a group called “Call Center Group” and the case type will be “FLW”.

In order for FLWs to appear in the case list, there is currently an additional step required where you need to update the mobile worker properties in some way i.e. make sure that they are "touched".  A fast way to do this is to bulk download and then bulk upload your mobile users. After this, the auto-registered FLW user-cases should appear in your case list. 

In order to build an app that will automatically create cases based on mobile workers within the project space, simply create a new application (or enter an already existing one) within the project space, make a form that requires a case (More on application building here), and assign the case type for that module to be whatever case type you assigned as “Call Center Case Type”.  In our example, we’ll need to make a module that uses the case type “FLW”.  This will allow the case list to automatically populate with a list of mobile workers for all CommCare users with access to this case type (in our example the user group “Call Center Group”).  Please note that the Call Center Application will make cases for all mobile workers in a given project space (see note at the bottom of the page about what data gets added to these cases). 

The performance data about a particular worker will only be available in a user's lookup-table if that user has access to that worker's case. In other words, the user must either be the owner of the worker's case or be part of a case sharing group that owns the worker's case. The permissions as well as the performance data itself in the lookup-table is only updated once a day at midnight. Consequently, changing the case ownership or case sharing structure will only have an impact the next day. To verify what data a particular user can access, this internal tool can help. Provide the user's ID (not username), date and whether to use cached data (from last midnight) or re-generate the data. The Phone Restore Data can also help in debugging.

The name of the cases in this module will automatically be assigned according to the fields First Name and Last Name completed in settings and user when registering a new users.  So for example, a user with a username of jdoe@callcenterapp.commcarehq.org and First Name of “John” and a Last Name of “Doe” would automatically appear in the case list as “John Doe”.

                                              
 

Through the use of fixtures, call center applications can also reference workforce monitoring information about individual mobile workers.  Currently available indicators include: Number of forms submitted in the 7 days, Number of forms submitted in the 7 days prior to the current week, Number of forms submitted in the last 30 days, Number of cases updated in the last 30 days, Number of cases updated in the 30 days prior to the current month, and Total number of cases for the user.  Use the following terms to reference these indicators: 

Indicator Date Ranges

The available indicator date ranges are as follows:

Name

Description

Lower Date Range

Upper Date Range

week0

The last 7 days

today - 7 days

today-1

week1

The 7 days prior to Week 0

today - 14 days

today - 8 days

month0

The last 30 days

today - 30 days

today-1

month1

The 30 days prior to Month0

today - 60 days

today - 31 days

 

Standard Indicators

Name

Description

forms_submitted_date-range

Count of forms submitted in chosen time period

cases_total_date-rangeThe total number of cases owned by the user in the time period. This includes cases shared with other users.
cases_active_date-rangeThe number of cases owned by the user that were either opened, updated or closed in the time period. This includes cases that they may share with other users.
cases_opened_date-rangeThe number of cases created by the user in the time period.
cases_closed_date-rangeThe number of cases closed by the user in the time period.

Each indicator is available over each of the date ranges defined above.  For example, to view cases opened in the last week, use the indicator cases_opened_week0.  Similarly, you can view cases active two months ago by using cases_active_month1.  

Case Type Specific Indicators

In addition to standard indicators, indicators specific to the case types available in your form are also available.  These are listed below:

Name

Description

cases_total_case-type_date-rangeThe total number of cases of the chosen case type owned by the user in the time period. This includes cases shared with other users.
cases_active_case-type_date-rangeThe number of cases of the chosen case type owned by the user that were either opened, updated or closed in the time period. This includes cases that they may share with other users.
cases_opened_case-type_date-rangeThe number of cases of the chosen case type created by the user in the time period.
cases_closed_case-type_date-rangeThe number of cases of the chosen case type closed by the user in the time period.

 

For example to view the number of mother cases created two weeks ago, you can use cases_opened_mother_week1.  To see the total number of farm cases a user was responsible for in the last month, use the indicator cases_total_farm_month0.  

Displaying Indicators in the Case List

In order to reference these indicators in the case list or case details view simply input the following into the Property field of the case list (Format should be set to Plain).
 

indicator:call-center/[indicator_name]
 

so for example, if you wanted to display the number of forms completed by a user in the last week  then in the properties field you’d write:

indicator:call-center/forms_submitted_week0


   


Setting up indicators in the case list and case details page will allow call center users to get a glimpse of the performance record of other users, and allows the app to filter and order cases based on performance.  Indicators appearing in the case list and details page may appear as follows:


                                           

Displaying Indicators In a Form

In order to allow your app to use these indicators in a form, you must reference them in your form’s XML.

To do this, in the form builder you must select the Tools dropdown in the upper right-hand corner of your screen, and select Edit Source XML.  In the pop-up window, underneath the line:

</instance>

And directly above the bind nodesets, enter the following script:

<instance id="indicators" src="jr://fixture/indicators:call-center" />


                                          

This will automatically reference the indicator fixtures where they need to be.

Once this is done, you can reference these indicators in forms.   Simply create a hidden value, let’s call it: forms_submitted_this_week.  Then input the following formula into this value’s calculate condition:

 

instance('indicators')/indicators/case[@id = instance('commcaresession')/session/data/case_id]/forms_submitted_week0

In order to reference other indicators follow this formula:

instance('indicators')/indicators/case[@id = instance('commcaresession')/session/data/case_id]/[NameOfIndicator]

You can then use these values as you would any other hidden value, and will update each time you open a form.  Below there is an example of how you might manipulate these figures to provide meaningful prompts, which calculate for the number of forms submitted compared to the total number of cases a user has, as well as the change in forms submitted from the previous week to this week:

                                           

 

A note on User Cases

The supervisor / call center functionality works by creating a case for each mobile worker. These cases will contain the following case properties:

 

  • name - the full name of the mobile worker (or their username if they don't have a first name and last name specified)
  • username
  • email
  • language
  • phone_number

In addition to these standard properties the case will also have a property for each piece of custom user data.

Custom user data rules

Only custom user data conforming to the following rules will be synced to the user case:

  • Names can contain letters, numbers, and other characters
  • Names cannot start with a number or punctuation character
  • Names cannot start with the letters xml (or XML, or Xml, etc)
  • Names cannot contain spaces