Easy References FAQ

This is a FAQ for existing users who have been using case management without Easy References.

How do Easy References change my app building workflow?

Easy References make it a whole lot easier to reference case properties in a form, effectively getting rid of the "loading" step. See this blog for a detailed outline.

You will also stop seeing "/data/" as a way to reference form questions. Instead, we have replaced "/data/" with a more intuitive "#form". See our handy hashtag reference cheat sheet for more information.

If you have been using "Edit" forms to edit case data, you can recreate the same functionality by referencing a case property in the "Default Value" field of a form question.

Do Easy References affect how I save questions to the case as case properties?

No, this workflow is unchanged.

Can I use Easy References with Child cases?

Easy References work with parent/child relationships for up to two levels. The case properties window will display case properties of the child case, its parent, and even its grandparent if that exists.

See our handy hashtag reference cheat sheet for more information.

Do Easy References work with the user case?

No, unfortunately Easy References do not yet work with the user case. You will still need to "load" user case properties into the form for now. We hope to have Easy References for the user case soon!

Is there anything I can't do with Easy References that I could do before?

This update does not remove any functionality - there is nothing you cannot do with Easy References that you could not do before. Some very advanced workflows will become harder - for example, if you are referencing a great-grandparent case (four levels of child relationships), you will have to use a longer, more complicated reference. Everything else should be easier!

I want my existing app to use Easy References. How do I make that happen?

We hope to give every application access to Easy References in the app builder. However, this involves converting your "loaded" case properties to Easy References. We are happy to do this for you, just sign up here.

I'm not sure I'm ready for Easy References, do I have to upgrade my app?

Not right away - but eventually every app will upgrade to Easy References. We will reach out to the web users on your project to give you plenty of notice before we convert your application.

I'm about to copy my existing app, will the copy use Easy References?

Copying your app will make an exact copy. If your app does not currently have easy references, the copy will not as well.

Can I "undo" the upgrade if I don't like it?

There's no way to undo the upgrade. If you upgrade to Easy References and don't like it, you can "revert" to a previous version of your application that was not using Easy References and continue using the older version of the app builder. However, all applications must eventually upgrade to Easy References.

Do Easy References work with imported cases?

Yes, but you may see warnings. You can directly type in the case property as #case/<property_name> to reference a property that is not in the app structure but was imported via the case importer. However, if that property is not used anywhere else in your application, you will see an "Unknown question" warning. This warning will not prevent you from building your application.

You can make the warnings disappear by creating a "fake" form in your application that references the imported properties:

  • Set the form's display condition to "false()" so it does not appear for mobile workers.

  • Create a question in the form for each imported property.

  • In the form's case management, save each question to the property it matches.

This will not affect your application, but it will enable CommCare's easy references to recognize the imported properties.

Please see the following confluence page for more detailed instructions: Case Importer with Easy References.

Can I reference specific iterations in a repeat with Easy References?

Currently this is not possible. To do this you can use the old style of reference: /data/path/to/repeat/question[1]