CRS CommCare Advanced Training

April 24 - 28 2017

1A - Training Overview

Day 1

April 23, 2017

1A - Training Overview

1B - Quick App/Form Builder Overview

1C - Advanced Form Building

1D - Lookup Tables

1E - Repeat Groups

​

​

Training Overview

Session 1A

• Overall Goals
• Facilitator(s)
• Resources
• Guidelines
• Daily Workflow

Overall Goals

• Orient CRS’s technical staff to advanced use of CommCare
• Introduce CommCare advanced functionality that can be hard to discover
• Generate useful videos, presentations, and other resources for CRS
• Answer questions!

​

Facilitators

Jeremy Wacksman

jwacksman@dimagi.com

Special Guests!

Resources

Training Website:

• https://sites.google.com/dimagi.com/crs/home
• Overview of training and schedule
• Daily Notes with relevant links, exercises, clarifications
• Q&A document
• CommCare general resources and support

​

Guidelines

• Feel free to ask questions at any time…
• … unless we are running way behind, in which case I’ll ask you to hold questions
• Sometimes the answer will be “I’ll let you know later”
• Please reach out if you have any questions/concerns/suggestions
• All presentation materials will be shared afterwards
• If you have time, try the exercises that are recommended each day

Daily Workflow

Each day we will follow a rough schedule/pattern.

The website will be updated each evening with content from the day and a preview of the next day.

During training week you can ask questions to Jeremy at jwacksman@dimagi.com

• Intro (10 min)
• Quick recap from the prior day
• Plan for the day
• Answer to any questions posed yesterday or corrections
• Follow-up to any exercises
• Technical Topics 1 (~ 80 min)
• Break/Buffer (~15 min)
• Technical Topics 2 (60 min)
• Wrap-up/Buffer (~15 min)
• Recommended practice
• Highlight of key resources
• Any preparation for the next day

Dimagi

1B - App/Form Builder Review

App/Form Builder Review

Key Topics:

• Project Settings
• All key features of App Builder
• All key features of Form Builder
• Efficient use of Form/App Builder

​

1C - Advanced Calculations

Advanced Calculations

Key Topics:

• Review common useful CommCare functions, by data type
• Finding additional functions
• Use the App Preview to test functions

​

​

CommCare Data Types and Functions

• Data Types
• Possible data types: strings, numbers, dates and times, lists
• The data type of the input doesn’t need to be the same as the data type of the output

​

​

​

• Each function may take:
• 0 inputs: random(), today()
• 1 input: int(value)
• 2 inputs: pow(base_value, exponent)
• 3 inputs: if(condition_to_test, value_if_true, value_if_false)
• multiple inputs: max(1, 4, 6, 2, 8, 9)

​

• Functions are useful for display conditions, validation conditions, and calculations

​

CommCare Functions: Strings

• In CommCare, textual input (sequences of letters, numbers, spaces, punctuation, and/or symbols) are referred to as “strings”

​

• When referring to a string in a function, you must put quotation marks around it (single or double quotes):
• concat(“jessica”, “ “, “denise”, “ “, “long”) => “jessica denise long”
• lower-case(‘Jessica Denise Long’) => ’jessica denise long’�
• Strategically choosing double / single quotes can sometimes be useful -- primarily when you want to include quotes inside your text
• "jessica’s house"
• ‘you said, "tell me more"’

​

• CommCare should always support special characters in strings, like ç or ñ in values
• Special characters are not supported in ids�

CommCare Functions: Strings

• Checks about string contents
• starts_with(text, prefix)
• ends_with(text, suffix)
• contains(text, search_text)

​

• concat(text1, text2, text3, ...)
• Joins all pieces of text together in sequence. Does not add spaces.
• concat(first_name, " ",last_name)

​

• string-length(text)
• Returns the number of characters in the string

​

​

CommCare Functions: Strings

• Capitalization
• lower-case(my_text) - Converts ALL letters to lowercase.
• upper-case(my_text) - Converts ALL letters to uppercase.

​

• substr(text_value, start_position, end_position)
• Takes a substring of the text_value, starting at start_position [inclusive] and ending at end_position [exclusive].
• The characters are numbered starting at zero (zero-indexed).

​

​

CommCare Functions: Strings

• Regular expressions
• regex(value, regular_expression)
• Evaluates whether the given value matches the regular expression. Returns true or false.
• Lots of options - based on normal regex syntax
• regex(#form/numero_cnib, "^[A-Z][0-9]{7}$")
• Validates that #form/numero_cnib is a 7-digit alphanumeric code.

​

• replace(text, pattern, replacement)
• Replaces all instances of the pattern in the source text with the replacement character.
• replace("jessica","s","z") => "jezzica"

​

CommCare Data Types: Numbers

• Kinds of numbers
• Integer (a whole number: -3, -2, -1, 0, 1, 2, 3 …)
• Decimal (a number with a decimal point: 1.2456, -2.345, 1034.829)
• Phone number or Numeric ID (sequence of integers that can start with 0; stored as a string)

​

​

CommCare Functions: Numbers

• Basic operations: +, -, *, div
• Aggregate operations:
• min(value1, value2, value3, …)
• max(value1, value2, value3, …)
• Rounding numbers
• ceiling(value)
• ceiling(2.3) = 3 – always rounds up
• floor(value)
• floor(2.7) = 2 – always rounds down
• round(value)
• round(2.3) = 2 – rounds to the nearest whole number
• int(value)
• int(2.4) = 2 – always rounds towards zero

​

​

CommCare Functions: Numbers

• random()
• Returns a random decimal between 0.0 (inclusive) and 1.0 (exclusive). For instance: 0.738928374923874923874293742983472938472
• uuid() or uuid(num_chars)
• Returns a unique identifier with the specified number of alphanumeric characters.
• abs(value)
• Returns the absolute value of a number
• number_being_divided mod number_to_divide_by
• Returns the remainder when number_being_divided is divided by number_to_divide_by

​

Data Types: Booleans

• You can input these directly with two CommCare functions:
• true()
• false()
• You can also calculate booleans dynamically:
• today() > date("2016-01-01")
• #form/num_children <= 6
• Comparison functions: >, >=, =, !=, <, <=
• != means "not equal to"
• Double equals sign for checking if two values are equal does not work in CommCare
• Logical connectors: and, or, not(value_to_negate)

​

• if(condition_to_test, value_if_true, value_if_false)
• if(#form/age <= 12, "child", if(#form/age > 12 and #form/age < 20, "teen", "adult"))

​

• cond(first_condition, value_if_first_true, second_condition, value_if_second_true, ..., default_value)
• cond(#form/age <= 12, "child", #form/age > 12 and /data/age < 20, "teen", "adult")

Data Types in CommCare: Date and Time

• Dates in CommCare have a dual representation!
• String: ‘2016-11-01’
• Numeric: 42675.00 – the number of days since January 1, 1970

​

• Sometimes the string version is more helpful
• Today’s date is 2016-11-01 (human readable)
• month = substr(today(), 5, 6) = ’11’

​

• Sometimes the numeric version is more helpful
• today() + 30 = 42675 + 30 = 42705 (this is the number for December 1, 2016)

​

​

Data Types in CommCare: Date and Time

• As soon as you do a calculation with a date, it is forced into either numeric or string representation.
• To get it back to having the dual representation, use the date() function.
• Examples:
• today() + 30 = 42675 + 30 = 42705 (this is the number for December 1, 2016)
• date(today() + 30) = date(42705) = ‘2016-12-01’
• concat(’2016’, ‘-12-01’) = ‘2016-12-01’ (a string, not a date)
• concat(’2016’, ‘-12-01’) + 5 = ERROR!
• date(concat(’2016’, ‘-12-01’)) + 5 = 42710
• date(date(concat(’2016’, ‘-12-01’)) + 5) = ‘2016-12-06’
• Useful function: format-date(date, date_format)
• You’ll probably have to keep looking up the codes for the date_format you’re interested in.
• Ex: format-date(today(), "%Y - %n - %e") => "2016 - 11 - 1"
• Date arithmetic
• today() + 2 => "2016-11-3"

​

Data Types: Lists

• Lists come from a few sources in CommCare:
• Responses to checklist questions
• Repeat groups
• Internally, lists are represented as strings separated by spaces
• Special Functions
• sum(question_group)
• count(question_group)
• min(question_group)
• max(question_group)
• join(separating_text, nodeset)
• Returns a single string where each node is listed in order, with the separating_text in between all adjacent nodes
• join(", ", /data/repeat_group/child_name) => "Danny, Fatou, Boubacar"
• Multi-select helper functions
• selected(my_question, value_to_check)
• count-selected(my_question)
• selected-at(my_question, position)

Combining multiple functions

• Functions are evaluated from the inside out
• Order of operations matters!
• floor(ceiling(2.7))
• ceiling(floor(2.7))
• Function for all data types:
• coalesce(value_1, default_value)
• Returns value_1 if it is not empty. Otherwise, returns default_value.

​

​

Converting Data Types

• Examples
• number() – converts to a decimal
• int() – converts to an integer
• date() – converts to a date
• string() – converts to a string

​

1D - Lookup Tables

The Mission

Create an easy way to look up Dimagi employees in a form and save information about them!

​

https://www.commcarehq.org/a/crs-training/apps/view/0dcaf06061f36b53b6bf6c4ba1731aa5/modules-0/forms-0/source/

​

1E - Repeat Groups

Presentation

Day 1 Wrap-up

Next Steps:

• Day 1 page is live on the training website!
• Please complete the Day 1 training evaluation (link coming in email)
• Example exercises are posted on the training website - answers to follow tomorrow!
• You can request access to the demo project (crs-training) if you want to see things later, just please don’t make modifications
• Questions?
• Feel free to reach out to jwacksman@dimagi.com

Day 2

Day 2

Tuesday, April 25

• 2A - Case Management Advanced Topics
• 2B - User Case
• 2C - Case List and Case Details
• 2D - Advanced Workflow Design
• 2E - Organizations

Recap

• Answers to your questions

​

• Content of the Dimagi Academy course

​

• Feedback from yesterday - slow down a bit

​

2A - Case Management

Advanced Topics

Presentation

2B - User Case

CommCare Mobile Workers

Some data is available about all (or many) users:

• Username
• (location)
• (userid)
• (groups)

Custom User Data

But, you can also add additional information called Custom User Data

​

These fields can be referenced within the app:

• Only show specific questions to a subset of users
• Unlock different parts of the app
• Filter the case list differently

​

Custom User Data can only be updated from the Users section of CommCareHQ

What is it?

The User Case is a special type of case associated with a mobile worker which can be updated by the application.

​

Each mobile worker has one "user case" associated with them. You can design an application to update or reference "properties" associated with a user case. This is useful for:

​

• Keeping count of something across all cases assigned to a user, like number of referrals or number of cases with a certain response to a question
• Having a dynamic form or module filter that references something about the user case
• Creating a unique ID that increments over each case

​

User Case 101

Some general characteristics of the user case:

• There is only one user case per mobile worker
• The case type is "commcare-user"
• The data can be exported just like any other case
• The special syntax to reference user-case properties in a filter is #user/<property name>

How do you use it?

• User Case Management is configured on the Form Properties Page
• Unlike normal case properties, you must manually load user case properties into the app from this page.

Example 1: Creating a User-Counter

https://www.commcarehq.org/a/crs-training/apps/view/0dcaf06061f36b53b6bf6c4ba1731aa5/modules-2/forms-0/source/

Example 2: Forcing a Correct Workflow

https://www.commcarehq.org/a/crs-training/apps/view/0dcaf06061f36b53b6bf6c4ba1731aa5/modules-2/forms-0/source/

Other Workflow Examples

• Check in / check out
• Group Visits -> Update lots of cases
• User preferences

2C - Case List and Details

Case List and Details

Demo: https://www.commcarehq.org/a/crs-training/apps/view/029cb95dfb0def2243479c88ea3237f2/modules-4/

Key Features:

• Types of fields
• Filters
• Tabs
• Sorting
• Calculations

2D - Advanced Workflow Design

Presentation

2E - Organizations

Presentation

Day 2 Wrap-up

Next Steps:

• Day 2 page is live on the training website!
• Please complete the Day 2 training evaluation (link coming in email)
• Questions?
• Feel free to reach out to jwacksman@dimagi.com

Day 3

Day 2 Recap

• New answers added to Q&A doc

Day 3

Wednesday, April 26

• 3A - Application Design Best Practices
• 3B - Application Release Management
• 3C - Supporting mServices Deployments
• 3D - Overview of Project Reporting Tools

3A - App Design Best Practices

Presentation

3B - App Release Management

Presentation

3C - Supporting mServices Deployments

Presentation

3D - Overview of Reporting Tools

1 - Pre-build Online Reports

• Worker Monitoring
• Project Health
• Data Inspection

2 - Export Raw Data

• Form Exports

​

• Case Exports

​

• SMS Exports

3 - Excel Dashboard

4 - Report builder

5 - Integration

6 - Custom Reports

Day 4

Day 3 Recap

• New answers added to Q&A doc - lookup tables

Day 4

Thursday, April 27

• 4A - Report Builder
• 4B - Worker Monitoring Reports
• 4C - Data Management

4A - Report Builder

4B - Worker Monitoring Reports

Overview of Worker Monitoring Reports

• Reports available on all CommCare projects
• Based on metadata
• Useful for monitoring activity in terms of form submissions, times, and case updates
• Most can be exported for further analysis
• Filter options:
• Users/groups/locations
• Completion/submission and/or case type
• App
• Date range

Project Performance Report (1)

• Shows the overall trends in mobile worker performance and activity, with an emphasis on monthly trends. It all identifies workers who have had a change in their performance
• Key definitions:
• Performing User - submits at least the minimum threshold of forms per month (default 15)
• Active User - submits at least 1 form last month

Project Performance Report (2)

Project Performance Report (3)

Worker Activity Report

• Quick view of worker activity over a specified time interval. Includes:
• Last form submission
• Avg forms submitted
• Case creation/updates
• Case activity

Daily Form Activity

• Total number of form submissions per day

Submissions by Form

• Number of specific form types submitted by each work over a time interval

Form Completion Time

• Looking at a single form, compares the time it takes each user to complete it

Case Activity

• Follow-up rates for cases over 30, 60, and 90 days

Form Completion vs Submission Trends

• Time difference between a form’s completion time and submission time
• Can reveal:
• Levels of connectivity
• Phone time issues

Worker Activity Times

• Qualitative view of when forms are being submitted or completed

Saved/Emailed Reports

• For most reports it is possible to save them (preserves all filters) as Saved Reports
• Most Saved Reports can be scheduled to go out by email as Scheduled Reports
• Reports are managed per-user, not per-project (unlike exports)

4C - Data Management

Presentation

Day 5

Day 5

Friday, April 28

• 5A - Integration
• 5B - Further Learning/Support
• 5C - Q&A

5A - Integration

Getting CommCare Data: The Options

If you don’t want or need to directly link into another system, you can:

• Export and then import to a different system for analysis
• Use the CommCare Report Builder
• Create an Excel Dashboard

​

If you want to programmatically push data into another system you have two major options:

• CommCare Data Export Tool
• Data Forwarding

Moving Data #1: CommCare Data Export Tool

This tool allows you to export your data from CommCareHQ in a simple, configurable, and reusable way

​

• Simplest option for directly syncing your data to a personally hosted SQL database
• You would have to build any data visualizations, aggregations, or reports on top of this database yourself
• Extensive documentation available on how to set this up

​

Moving Data #2: Data Forwarding

This tool allows you to configure your project to forward any incoming forms and/or cases to a specified URL.

​

• Requires maintaining a web service that handles incoming data, edits it, and saves it in whatever format/structure is desired
• Requires writing visualizations, aggregations, or reports they wanted to get from it themselves

​

5B - Learning More

Key Resources

• Help Site
• Dimagi Academy
• CommCare Users
• Support Desk
• Uservoice

5C - Q&A

If we have extra time...

• Talk through examples of workflows to support
• (SMS) Messaging options
• Review case management concepts
• Walk through the Day 4 data management examples