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.