Application terminology
Applications (and builds)
An application typically has many different Application
documents:
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 origin_id
.
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 version
is
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
the copy_of
field will be set to the ID of the primary application
document. Both builds and primary docs contain built_on
and
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 profile.xml
and suite.xml
and saves then to
the build doc (see create_all_files
).
When a build is released, its is_released
attribute will be set to
True
. is_released
is always false for primary application docs.
Modules
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
the application.
Forms
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
commit
for detail.
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
to
secure_post.
For reports to identify forms accurately, xmlns must be unique within an
app.
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.
Exceptions
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.
Features
Template apps
HQ currently has two versions of “template apps.”
Onboarding 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
template_apps
directory. They are imported using the view app_from_template
.
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 ExchangeApplication
model.
These applications are visible via the app_exchange
view.
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.