As of version 2.0, Indivo has an official process for adding and managing apps on a given instance. For those of you familiar with using indivo_data.xml for adding apps, the <machine_apps> and <user_apps> tags will no longer be respected, and will not add apps to Indivo.
Previous releases of Indivo have relied on an implicit XML syntax in indivo_data.xml for representing an app within Indivo. Now, applications must provide a declared manifest describing the application and its requirements. We have adopted the SMART Project’s syntax for describing apps in manifests, but have added some Indivo-specific parameters to accommodate the way Indivo represents applications. For compatibility, any valid SMART manifest will also be a valid Indivo manifest.
See The SMART Project’s documentation for a description of the basic syntax of a manifest, which is JSON based. Below, we describe only the Indivo-specific modifications.
An Indivo user-app may define (beyond the SMART-supported manifest fields) any of the following additional properties in its manifest:
The following fields have changed names to match the SMART manifest fields:
{
"name" : "Problems",
"description" : "Display a list of problems, or enter new ones.",
"author" : "Arjun Sanyal, Children's Hospital Boston",
"id" : "problems@apps.indivo.org",
"version" : "1.0.0",
"smart_version": "0.4",
"mode" : "ui",
"scope": "record",
"has_ui": true,
"frameable": true,
"icon" : "jmvc/ui/resources/images/app_icons_32/problems.png",
"index": "/apps/problems/start_auth?record_id={record_id}&carenet_id={carenet_id}",
"oauth_callback_url": "/apps/problems/after_auth"
}
An Indivo user-app may define (beyond the SMART-supported manifest fields) any of the following additional properties in its manifest:
The following fields have changed names to match the SMART manifest fields:
{
"name": "Sample UI App",
"description" : "The reference Indivo UI App",
"author" : "Ben Adida, Travers Franckle, Arjun Sanyal, Pascal Pfiffner, Daniel Haas. Children's Hospital Boston",
"id" : "chrome@apps.indivo.org",
"version" : "2.0.0",
"indivo_version": "2.0.0",
"ui_app": true
}
When authenticating to Indivo using traditional oAuth, applications must provided Indivo with their consumer key and a shared consumer_secret. As this secret is private and should not be shared with other apps (i.e., via a call to GET /apps/), it should be registered in a separate file. We therefore define a simple JSON format for specifying app oAuth credentials, which is simple JSON and has two fields:
Here’s a sample credentials file, for our built-in Problems app:
{
"consumer_key": "problems@apps.indivo.org",
"consumer_secret": "SECRETFORTHEPROBLEMSAPP:CHANGEME"
}
Notes:
Thus, to register an app with Indivo, you need two files: an app manifest (manifest.json) and a credentials file (credentials.json).
Changing the set of registered apps in Indivo is now drag-and-drop, as with our process for managing datatypes and schemas. To add, remove, or change an app, you’ll need to:
Indivo apps currently have the following layout on the filesystem:
indivo_server/
registered_apps/
admin/
ui/
user/
allergies/
manifest.json
credentials.json
...
To add an app to the filesystem, simply add a subdirectory under indivo_server/registered_apps/admin, indivo_server/registered_apps/ui, or indivo_server/registered_apps/user (depending on the type of your app), and drop a manifest and a credentials file into that directory.
To remove an app, just delete its directory.
To change an app’s manifest or credentials, just modify the appropriate manifest.json or credentials.json file.
To alert Indivo that you’ve changed the registered apps, run (from indivo_server/):
python manage.py sync_apps
This will process the list of registered apps and sync any additions, deletes or updates to the database.
With the new system, there is NO NEED TO RESET INDIVO TO ADD APPS!. Simply run the sync_apps command, above.
When you do reset Indivo, the reset script now calls sync_apps, which will add all of the registered apps to Indivo.