Registering Apps with Indivo

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.

App Manifests

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.

User Apps

New Fields

An Indivo user-app may define (beyond the SMART-supported manifest fields) any of the following additional properties in its manifest:

  • oauth_callback_url: A callback URL for Indivo-style oAuth access
  • autonomous_reason: An explanation for why the app requires offline access to patient records
  • has_ui: true or false, whether the app can be displayed in a browser.
  • frameable: true or false, whether the app should be loaded in an iframe in the Indivo UI.
  • indivo_version: Required version of Indivo for compatibility

Changes from the indivo_data.xml fields

The following fields have changed names to match the SMART manifest fields:

  • email: Has been renamed id, per SMART.
  • start_url_template: Has been renamed index. If using Indivo-style oAuth authentication, the same templating parameters may be passed in the URL (i.e. {record_id})
  • is_autonomous: Has been moved to the SMART mode property. Acceptable modes are:
    • background: This app will act like an autonomous Indivo app.
    • ui: This app will act like a non-autonomous Indivo app.

Example

{
  "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}&amp;carenet_id={carenet_id}",
  "oauth_callback_url": "/apps/problems/after_auth"
}

UI and Admin Apps

New Fields

An Indivo user-app may define (beyond the SMART-supported manifest fields) any of the following additional properties in its manifest:

  • ui_app: true or false. Whether the machineapp is a UIApp (‘chrome app’).
  • indivo_version: Required version of Indivo for compatibility

Changes from the indivo_data.xml fields

The following fields have changed names to match the SMART manifest fields:

  • email: Has been renamed id, per SMART.
  • app_type: Please use the ui_app field, above.

Example

{
  "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
}

App oAuth Credentials

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:

  • consumer_key: The oAuth consumer key for the app.
  • consumer_secret: The oAuth consumer secret for the app.

Here’s a sample credentials file, for our built-in Problems app:

{
    "consumer_key": "problems@apps.indivo.org",
    "consumer_secret": "SECRETFORTHEPROBLEMSAPP:CHANGEME"
}

Notes:

  • If your app is a SMART app, you probably haven’t explicitly generated a ‘consumer key’. You should set the consumer_key field of the credentials file to match the id field of your app manifest file.
  • If your app is a SMART CONNECT app (or connects to Indivo using In-Browser Connect Authentication), you do not need a consumer secret. In such a case, set the consumer_secret field of the credentials file to the empty string: ''.

Managing the Registered Apps

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:

  • Create a manifest and credentials file for the app (or modify existing manifests/credentials)
  • Drop the files into the filesystem
  • Sync the database with the filesystem

Apps in the Indivo Filesystem

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.

Syncing the Database with the Filesystem

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.

Resetting Indivo

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.