Tutorial

This guide will walk you through publishing a form to ODK Central using ODK Publish.

1. Setup ODK Central

Create or access an existing ODK Central instance. You can use ODK Cloud, a local Docker-based instance, or your own deployment.

  1. Create an admin user for Publish MDM to use. This user will be used to publish forms to ODK Central.

  2. Create a project for the forms you will be publishing.

2. Setup Publish MDM

Follow the Quickstart with Docker or Local Development guide to run Publish MDM locally.

  1. Configure Publish MDM environment variables. You will need to set the following environment variables:

    • GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET: These are the OAuth credentials for the Google account you will use to authenticate with ODK Central and to download forms from Google Sheets.

    • GOOGLE_API_KEY and GOOGLE_APP_ID are used to enable the Google Picker, which users will use to give access to specific spreadsheets in their Google accounts. To get the API key, create it in your Google Cloud dashboard. The GOOGLE_APP_ID is the “Project number” in the Google Cloud dashboard.

    • INFISICAL_API_URL, INFISICAL_TOKEN, and INFISICAL_KMS_PROJECT_ID: See Inifisical.

    • To use Android Enterprise as your MDM Service Provider, set these server-wide environment variables:

      • ANDROID_ENTERPRISE_SERVICE_ACCOUNT_FILE: The path to a Google service account file. See the Google docs on how to create one.

      • ANDROID_ENTERPRISE_PUBSUB_TOKEN: (Optional, required if you’ll enable real-time device enrollment notifications). This is the shared secret token that will be used for the notifications push endpoint at /mdm/api/amapi/notifications/. The Pub/Sub API must be enabled for the Google project used to create the service account, and the service account must have the “Pub/Sub Admin” role. See this guide for more details. Then run python manage.py configure_amapi_pubsub to create the Pub/Sub topic (projects/{project_id}/topics/publish-mdm-{environment}) and subscription, and grant Android Device Policy the right to publish to it. If the configure_amapi_pubsub command is not run, real-time device enrollment notifications will not be enabled when an enterprise is created.

    • The MDM type (TinyMDM or Android Enterprise) and TinyMDM API credentials are configured per-organization in the Django admin (/admin/publish_mdm/organization/).

  2. Start the Publish MDM server, login with your Google account, and make yourself an admin.

  3. Create a Central Server using your ODK Central server’s base URL and credentials. You can do this in Admin (/admin/publish_mdm/centralserver/) or on the frontend.

    If you’re using the local Docker-based ODK Central instance, you can set the base URL to http://central-dev.localhost:9100. Additionally, you may need to add central-dev.localhost to your /etc/hosts so Python can resolve the lookback address.

  4. Sync your ODK Central project by visiting http://localhost:8000/odk/servers/sync/.

3. Setup project in Publish MDM

Now that you have ODK Central and Publish MDM set up, you can add form templates to Publish MDM.

  1. Define variables: If your forms use template variables, you will need to add template variables and then associate them with the project in the admin.

  2. Add forms: Use Add a form template in the Django admin to add each project form to Publish MDM. You will need to provide the form’s title, form ID base, and the form’s Google Sheet URL.

  3. Create app users with variables: Export App Users and fill in app user details, variable values, and assign them to forms. Then Import App Users using the exported file to create or update app users in Publish MDM.

  4. Generate ODK Collect QR codes: Generate QR codes by clicking Actions->Regenerate QR Codes on the App Users page.

  5. Publish forms: Publish the forms to ODK Central by clicking Publish on a form detail page.