Application Preview

Owned by Gillian Javetski
Last updated: May 01, 2024 by Krinda Wernicke
8 min read

Application Preview (aka App Preview) allows application builders to see what their app will look like before downloading it to a phone. While you are app building, mobile device that can be configured to display as a phone or a tablet will appear on the right hand side of the screen. This device will display the most recent version of your application, allowing you quickly test any changes you have made.

Table of Contents:

General Notes

  • ** Live Data ** Please note that when using this feature, you are submitting live data to your project space. When submitting data as a web user, it will appear as if submitted by an unknown user and will only appear in exports or reports if specified (via filters). When using the Login As feature, data will be submitted on behalf of the mobile worker you are logged in as and will appear in exports and reports as such. More details provided below.

  • App preview runs using the same code as CommCare Mobile and Web Apps. It is expected to perform the same functionality, with some differences in how that data is laid out on the screen. 

  • Similar to using the mobile application, ensure you press the 'Sync' button often to receive the latest data from your project space. This is particularly important when you use the 'Login As' feature described on this page. 

  • There are also some limitations with this feature that will be discussed below. In general, the same limitations that apply to Web Apps will apply to application preview. 

  • App Preview will display the latest preview of your application. This essentially means the last time you selected the 'Save' button for your application.

  • If regularly using App Preview, you will most likely not create a new build for your application after each change. While the goal of using App Preview is to make it easier to test changes made to your application, we still recommend deploying a new version of your application every so often. 

    • It can be very easy to find yourself in a situation where you make several changes to an application and something breaks. By deploying regularly, you can ensure a safe point to revert back to in case you are unable to fix an application after making changes. 

  • We do not recommend using this tool for live data submission. This tool should be used for testing purposes only. 

Setup

The App Preview feature is used in the 'Applications' section of CommCare. By default, it is hidden from view. To display the mobile device so you can test your application, you first need to select the teal bar that appears on the left hand side of the screen. Doing so will make a device appear on the screen:  

By default, the application preview will be displayed as if it were a phone. For various reasons though, you might want to display the device as if it were a tablet. Pressing the image of a device on the app preview will toggle between a device or a table.   

9965438e-34f4-4a76-a2c8-fc353094f223.png

Using App Preview

App Preview will always use the latest preview version of your application. This means that it will use a version of your application based on the last time you pressed the 'Save' button. You can check this by pressing the Start button and then proceeding to the form, just as you would on a mobile device! But, how do we use this tool to check the changes we make to our application? Let's take a look at a Registration form that contains 3 questions:

When we enter App Preview, we should see 3 questions; Name, Sample Choice Question, Sample Number Question. Let's see if those get displayed in the app preview by selecting Start, and then proceeding to the registration form:

Now, let's update the two sample question's display text and add a couple more questions. Be sure to save any changes you make:

Now that we have added a few questions, let's take another look at our app preview. Notice that we have also scrolled down on the application preview by clicking the screen and dragging down to find the submit buttons. In addition, the questions have also not updated to reflect our changes. To have the App Preview update, we first need to select the refresh button on the app preview:

Pressing this button will pull the latest changes you have made into app preview. This will also return you to the home screen of your application, so you will need to navigate back to the form to ensure the changes took place.

If you make changes to your application but have not updated app preview yet, a red dot will flash next to the refresh button to indicate changes have been made. Press the button and return to your form to confirm app preview now displays the latest version!

When in doubt, if your application is not showing the most recent changes you have made, try pressing the sync button. 

Limitations

  • If using App Preview as a Web User:

    • All web users are considered "Unknown users" and form submissions will be tagged as such in reports. To view these submissions, choose "Unknown User" in the User filter of the report.

    • If your app uses case management, all web users are considered the same "Unknown User" and will be able to view cases registered by other web users in Preview Form

    • If your app uses lookup tables or case sharing you may get an error when previewing your form because "Unknown User" does not belong to any case sharing or lookup table groups.

    • Some question/case properties will not be able to be exported if that question is not part of any application deploys.

  • 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.

  • Graphs cannot yet be displayed in App Preview

  • Videos will not be displayed in App Preview

  • App Preview doesn't validate all questions/validation conditions

  • If using the 'Login As' feature, please see the limitations described below.

Settings

The setting menu, highlighted in red in the image below, will allow you to alter two settings: 

  

  1. Use one question per screen - By default, only 1 question will be displayed on the screen. To display more than 1 question per screen, you will need to toggle this setting to 'Off.'

    1. We recommend leaving this to display 1 question per screen. Having multiple questions per screen could cause performance issues with the Application Preview. 

  2. Set the application language - This will be set to display the default language of your application. If you have multiple languages for your application, you can use this setting to switch between them. 

Login As Feature

Similar to Web Apps, we have also added the 'Login As' functionality to App Preview to make it easier for web users to test and use their applications. This feature will allow you to login as a mobile worker on your project space within the App Preview, and submit data as if you were that user. For more information on the Login as feature, please refer to https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143945116.

Note: When using the Login As feature, you are submitting live data to your project space. Since you are submitting on behalf of a mobile worker, the data will appear in your exports and reports as such. We recommend using this feature with test mobile workers to ensure your submissions do not affect any live user data.

Accessing Login As

To enable this feature, you need to be assigned to a Web User Role with the following permissions:

  1. Edit Data

  2. Edit Mobile Worker Data

  3. Edit Web User Data 

  4. Access to Web Apps 

For more information on how to use the Login As feature with Application Preview or Web Apps, please see https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143945116.

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 https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143950715. 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>':

  • If One Question per Screen is enabled, repeat groups will not be functional on App Preview.

 Common Error Messages when using App Preview

 Sometimes, you may notice the following error messages when trying to use App Preview:

Usually, this happens when you have https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143957537, https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143955074, or https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143955032 (Locations) references enabled in your app, and you need to log in as a mobile worker to be able to test the application. Logging in as a mobile worker and syncing thereafter should resolve the above error messages. You can refer to the "Login As" section above for more information.

Additionally, also ensure that your mobile workers are correctly assigned to a group or location. You can do this via https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143957537.