Applications (and builds)
An application typically has many different
one for the current/primary/canonical application, plus one for each
saved build. The current app’s id is what you’ll see in the URL on most
app manager pages. Most pages will redirect to the current app if given
the id of an older build, since saved builds are essentially read-only.
In saved builds,
copy_of contains the primary app’s id, while it’s
None for the primary app itself. If you need to be flexible about
finding primary app’s id on an object that might be either an app or a
build, use the property
Within code, “build” should always refer to a saved build, but “app” is used for both the current app and saved builds. The ambiguity of “app” is occasionally a source of bugs.
Every time an app is saved, the primary doc’s
incremented. Builds have the
version from which they were created,
which is never updated, even when a build doc is saved (e.g., the build
is released or its build comment is updated).
When a user makes a build of an application, a copy of the primary
application document is made. These documents are the “versions” you see
on the deploy page. Each build document will have a different id, and
copy_of field will be set to the ID of the primary application
document. Both builds and primary docs contain
built_with information - for a primary app doc, these fields will
match those of the most recent build. Additionally, a build creates
attachments such as
suite.xml and saves then to
the build doc (see
When a build is released, its
is_released attribute will be set to
is_released is always false for primary application docs.
An application contains one or more modules, which are called “menus” in user-facing text. These modules roughly map to menus when using the app on a device. In apps that use case management, each module is associated with a case type.
Each module has a
unique_id which is guaranteed unique only within
A “form” in HQ may refer to either a form definition within an application or a form submission containing data. App manager code typically deals with form definitions.
A module contains one or more form definitions. Forms, at their most basic, are collections of questions. Forms also trigger case changes and can be configured in a variety of ways.
Each form has a
unique_id which is guaranteed unique only within the
domain. For the most part, being unique within an application is
sufficient, but uniqueness across the domain is required for the sake of
multimaster linked applications. See this
Forms also have an xml namespace, abbreviated
xmlns, which is part
of the form’s XML definition. Reports match form submissions to form
definitions using the xmlns plus the app id, which most apps pass along
For reports to identify forms accurately, xmlns must be unique within an
Duplicate xmlnses in an app will throw an error when a new version of the app is built. When an app is copied, each form in the copy keeps the same XMLNS as the corresponding form in the original. When a form is copied within an app - or when a user uploads XML using an xmlns already in use by another form in the same app - the new form’s xmlns will be set to a new value in save_xform.
Linked apps use similar workflows to app copy for creating and pulling. See docs for more detail on how they handle form unique ids and xmlnses.
Shadow forms are a variation of advanced forms that “shadow” another form’s XML but can have their own settings and actions. Because they don’t have their own XML, shadow forms do not have an xmlns but instead inherit their source form’s xmlns. In reports, submissions from shadow forms show up as coming from their source form.
HQ currently has two versions of “template apps.”
The first set of template apps are simple apps in different sectors that
we’ve experimented with adding to a user’s project when they first sign
up for an account. These template apps are stored as json in the code
base, in the
directory. They are imported using the view
COVID app library
This is a set of template applications that exist in a real project
space and are made publicly visible to other domains. A record of each
app is stored as an
These applications are visible via the
To add a new app, add a new
ExchangeApplication model via django
admin. You must supply a domain and an app id. Use the “canonical” app
id used in app manager URLs, not a specific build id. You may also
provide a help link and/or a link to a version history. All released
versions of the app will be available via the app library, with the
versions labeled by date of release, not by version number. The
application title displayed in the library will be from the latest
version of the app.