Using Web Apps

Web apps can be used for:

• Testing CommCare applications or forms

• A data entry person who needs to be able to modify a mobile users case list or add additional data

• Cases from mobile applications that are shared with a web app- for example, allowing a nurse at a clinic to update cases when patients visit. A Community Health Worker with a mobile handset is then able to view the updates from the clinic and see what instructions the patient was given.

Using Web Apps: A quick introduction to setting up and using web apps

Web Apps is the web version of CommCare.  There are two ways you can use Web Apps:

1. To test forms (using the “App Preview” feature) - you can preview your form in a virtual device that appears on the right hand side of the screen in App Manager or Form Builder.

2. To submit data -  mobile workers can log into Web Apps on a computer just like they would log into a CommCare mobile application. Web Users can also use Web Apps, but data is treated differently for a web user. More information on this point below.
   
   

First, are Web Apps Right For Me?

We recommend you use the Google Chrome web browser.

• Other browsers may work, but are not fully supported.

How is Web Apps different than Mobile Apps?

• Case sharing as a web user is not supported.

• No mobile-specific user interface settings (e.g. Sense mode) are honored.

• The time portion of 'format-date' does not work well. Time portion always shows up as 00:00:00 in Web Apps.

• The "default language" setting is not honored for applications. User-specific language setting is used instead for both Web and Mobile users. 

• Groups that contain only hidden values will be shown as empty groups in Web Apps if the display condition of the group is met.

• Case List Menu Item setting for a module.

• Alternative calendar formats are not supported.

• Multimedia upload and capture (Image, Video, Audio) are not supported.

• Most advanced Android formatting options are not respected.

• Audio files on multiple choice question choices will not show or play.

• Images on multiple choice question choices will not show or play.

• Images and audio files on buttons will not show or play.

• Incomplete Forms are available if at least one application in the project space has them enabled.

• Incomplete forms on Web Apps are deleted automatically after 7 days.

• User controlled repeat groups don't get rendered when mixed with repeat group of other types in the same form. To work around this issue , it is possible to ask the user how many repeats they require. 

• Having multiple tabs open on your browser with Web Apps is known to have caused some performance issues in the past. We'd generally recommend not opening Web Apps for data collection in multiple tabs / groups.

• 'Phone Number' format in case list in not supported on Web Apps. The phone number will not be displayed in the case list as highlighted. 

• End of Form Navigation using Home screen is not supported on Web Apps. When utilizing End of Form Navigation, Web Apps users wishing to return to the list of menus/modules should use 'First Menu' and not 'Home Screen.'

• Web Apps supports the here()  function expression in persistent entity views, which are unsupported on the Android platform

Application Preview

The Application Preview (or “App Preview”) feature is a tool available to all users in the application and form builder sections of CommCare. This feature allows you to view your application as it would appear on a mobile device and immediately test any changes that you make. Application Preview provides a quick, powerful way to test iterations and changes made to an application without having to go through the process of deploying or updating your application on a physical mobile device.

To open application preview, select the teal bar on the right hand side of the screen:

Open

You can also choose to display your application as if it were on a phone or a tablet by selecting the image of a device on the app preview. Selecting the device button will toggle between a mobile phone or tablet:

Open

There are a few things that you should know when using the app preview feature. When testing your application, the app preview will always use the most recent version of your application, regardless of what the latest release version is. Basically, you will always see a version of your application based on the last time you selected the ‘Save’ button in the application manager or form builder.

In order to ensure you are using the latest version of your application, you will need to select the refresh button on the app preview feature. You will need to press this button after you make any changes that you would like to review. Please note that if you select the refresh button while you are in a form in app preview, you will be returned to the home screen and will need to navigate back to the form that you were in:

General Tips

• While this feature allows you to test the most recent version of your application without having to deploy any changes, we do recommend deploying new versions of your application occasionally. This will allow you to have checkpoints to revert your application to in case you make a change that you cannot fix or breaks your application.

• We recommend using the 1 question per screen setting, as multiple questions per screen can cause some slowness and performance issues. To enable this, select the ‘Settings’ button from the home screen of ‘Live Preview’ and select enable for this setting.

• You can view any other languages you might have configured for your application by proceeding the ‘Settings’ page of Live Preview.

• Be sure to sync to receive the latest data for your application, especially when using the 'Login As' functionality.

Limitations

• User-controlled repeat groups (i.e. Repeat groups where the user defines how many repeats to input) do not currently work. Repeat groups where the repeat count is pre-defined should work.

• Some icons and images on questiosn may not work. Prior to deployment, we highly recommend testing on a mobile device first.

CommCare for Web Users

Web Apps

Users can access web apps by clicking on "Web Apps" at the top of the page. Note that the apps that appear here are the latest released version of the application, to ensure that your latest test changes don't affect current web apps users! This allows for more robust testing and use of the application, as it allows you to preview more than just the form as described in the section above.

To enable your application in Web Apps, see the setting up web apps section, here.

Login As Feature

In both Web Apps and in the Application Preview, there is a feature known as ‘Login As.’ This functionality allows a web user to access a form as if they were a mobile user from their project space. This is another powerful tool that allows you to truly experience what your application will look and feel like from the perspective of a mobile user. Please note that any forms or data submitted while using the Login As feature will be treated as live data and will appear in exports and reports as such. 

Accessing Login As

To enable the Login As feature, you need be logged in as a Web User with certain permissions. The user’s Web User Role will need to have permission to do the following in your project space:

1. Edit Data

2. Edit Mobile Worker Data

3. Edit Web User Data 

4. Access to Web Apps 

With these permissions enabled, you should see a 'Login As' button when using App Preview or Web Apps:

Limitations

• Any data submitted this way will be done so as if you were that mobile worker. The data will appear in exports and reports as such.

• Any limitations that would apply to a mobile worker in Web Apps. 

• The only way to confirm a form was submitted on behalf of a mobile worker by a Web User, is to find the specific form itself. You can do this by searching for submissions in the Submit History. Once you find the form in the submit history, there will be a note at the top that states 'Submitted by Web User <name> on behalf of Mobile Worker <name>':

For more information on the Login As feature, please see this document.

CommCare for Mobile Workers

Lastly, you can also use your mobile username to view your case list and fill out forms on the web just as you would on a mobile phone.

Setting up web apps

To view your application in Web Apps, you need to enable the Web App setting and mark a version of your application as released. The following steps assume you are ready to use your application in Web Apps:

1. Proceed to the Application settings by selecting the gear icon in the upper left hand corner next to the application name.

2. Proceed to ‘Advanced Settings’

3. Select the Web App checkbox

4. Save your changes

5. Select the application name in the upper left hand corner to proceed to the Release Page

6. Make a new version of your application.

7. Mark the new version as “Released”

You should now be able to view your application in web apps by selecting “Web Apps” from the navigation bar at the top of the screen!

How it Works

Web apps run off of "released" versions of your application, just like the mobile app. To ensure that your latest test changes don't get published to your web app users until they are ready, web apps will use the latest version marked as released. 

It is strongly recommended that you only allow data entry to happen in web apps from mobile worker accounts, and not web user accounts. To use web apps as a mobile worker:

1. Sign into your project using the credentials of a mobile worker. This is NOT the Web User email address and password combination you use to log in to CommCareHQ to view reports, manage users, or modify an application.

2.  

   1. From the regular CommCareHQ main login page (www.commcarehq.org) you must use the fully qualified project-specific username (mobileusername@project_name.commcarehq.org) to log in.
      
      

   2. Alternatively, if you navigate to "www.commcarehq.org/a/project_space_name]/login" you can log in with just the mobile user name and password (i.e. just use mobileusername without the "@project_name.commcarehq.org")

3. You will be automatically taken to the web apps section of CommCareHQ.

4. Enter data

Incognito Browser

If you are using Google Chrome, instead of logging out as a web user and logging in as a mobile user, you can open an "incognito window" by pressing Ctrl + Shift + N (Command + Shift +N). This allows you to have a separate log-in session in CommCareHQ. When someone logs in as a mobile user they WILL NOT be able to see reports, the application configuration, or other settings related to your work space.

Multiple Languages

Web apps will display text in the default language of your first web app.  (We're working on the ability to set defaults per app).

However, you can also set which language displays for each individual user in the Settings & Users section of CommCareHQ:

1. Navigate to your "mobile workers" page

2. Click on a mobile worker's name to edit that worker

3. Find the "language" box and enter the language code (as seen in the Application) that corresponds to the desired language

NOTE: The language will not switch if you use "login as" to log in as the mobile worker. You will have to separately log in using the username and password of the mobile worker to be able to see the app display in the desired language for the mobile worker.

For more information, please see the Login As Feature

Custom Logo

You can upload an image in Application Settings to use as the logo of your app on the main Web Apps page, in place of the CommCare logo.

General Web Apps Notes

How to restrict Mobile workers from accessing certain Web Apps?

It is possible to limit a mobile worker’s access to certain Web apps.

'Web Apps Permissions' page (Legacy) - This legacy feature was available through this feature flag. It used mobile worker groups to limit access to specific apps. This involved creating user groups and using the 'Web Apps Permissions' page to define which group has access to each Web App in the project.

This functionality is now available via the roles and permissions page, where the permission for accessing web apps supports specifying a list of apps. The Web Apps Permissions page offers instructions to migrate to the new settings.

'Roles & Permissions' page (New) -

The Roles & Permissions modal has a section to manage Web Apps access. The dropdown for ‘Use Web Apps for online data entry’ offers three options -

• No Access - Users of a given role would not be able to access web apps.

• Access All - Users of a given role would be able to access all the web apps

• Limited Access - this can be chosen to customize which web apps the given role could access.

Which version of my app is Web Apps using?

The table below is true for all projects created after March 2014; for projects before that, the default for Clicking on the Web Apps button and for accessing Web Apps as a mobile worker was always to use the most recent version, regardless of whether it was starred. If you have specific questions please "report an issue" and the support team will follow up with you.

New App Version Prompt

For projects that have shortened inactivity timeout functionality, when a new version of an app is released, users will see a pop up message allowing them to either update to the latest version now or later.

This pop up will appear with the timeout activity pop up (generated a few mins before the timeout). Clicking Update Later will close the pop up and allow the user to continue working where they were. Clicking Get Latest App will navigate the user to the WebApps home page, from where they have to select to re-enter the latest released version of the app they were working in.

Note: The new app released pop up will not appear

• For projects that do not have an inactivity timeout set.

• If use_latest_build_cloudcare feature flag is enabled.

• If the user has navigated from the Releases page to Web App.

Pagination 

Typically in our WebApps when there are multiple cases in a case list, we by default show at most 10 cases listed on a page, with options to display less or more per page. Using WebApps on screens smaller than 992px wide, this default changes to 5 cases listed on a page and we add a "skip to bottom" button if the pagination controls are off-screen. If there are more than 10 cases in that case list, we display the number of pages at the bottom of the screen (if there are 55 cases, there would be page numbers from 1 to 6). 

The pagination feature truncates the page numbers displayed to the user at a single time but allows them to:

1. Navigate to the first page and last page

2. Navigate to 2 pages previous and one page ahead of the current page

3. Navigate to an exact page

4. Choose the number of records to display on a case list page

The screenshot below shows what the pagination would look like if the case list had over 520 cases, with 10 cases to a page.

Navigating to all required questions 

When a form is long and has multiple required questions or questions with validation errors spread across the form, it is useful to be able to navigate to all these questions one by one to fix them before submitting the form. For this reason, once you click "Submit," a message box with links to any questions with errors, and a handy navigation button is displayed at the bottom of Web Apps. Clicking on the button will scroll to the next required question or question with validated errors. Once all errors are addressed, the button disappears and the Submit button is enabled. Below is a screenshot.

Successful form submission messaging

When a form is successfully submitted, Web Users will get a green message at the top of their screen that their form was successfully saved, along with links to the form submission, case affected, and the option to export the case or form data. This message includes the localized name of the form, if localization is applicable. Below is a screenshot.

If a Web User is using the Login-As feature, a similar message using the localized name of the form will appear at the top of their screen after a form is successfully submitted without any of the form submission, case, or exporting data links.