OAuth2 Service Account

Overview

Publishing your data into Google Spreadsheets or Google Fusion Tables requires a Google Oauth2 Service Account.

NOTE: Google now throttles requests for all of its APIs. This impacts ODK Aggregate's Map visualization (which requires an API key) and the publishing to Google Sheets and the publishing to Google Fusion Tables (both of which require a service account). If you have difficulties with any of these, go to the Google Cloud Platform project in which you created your service account, navigate to the API Manager tab, navigate to the appropriate API (either via the Dashboard list or via the links on the library sub-tab). If the API is enabled, you will have a graphical overview of your use of the API. Click on the Quota heading on the page to see the quotas for the API. By clicking on the pencil icons to the right of these quotas, you will get a pop-up from which you can request an increase in a quota. The quota that most critically needs to be increased is the Google Sheets quota for write requests per second per user. A better limit is 500 per second per user, or perhaps higher if your forms have many fields and/or repeat groups.

The Google API Key used by the Maps visualization is created and managed on the same screen as the Google Oauth2 Service Account.

This page guides you through the creation and uploading of these two credentials into ODK Aggregate

Step 1: Create these Google Credentials

Credentials are associated with a Google Cloud Platform project.

  1. If you are using App Engine for your ODK Aggregate server, then you have already set up a Google Cloud Platform project -- you just need to navigate to it. Otherwise, you will need to create one. In either case, go to Google Cloud Platform and click on "My Console":
  2. If you have never configured a Google Cloud Platform project, click on "Create an Empty Project":

    Otherwise, this link will either open onto a page with a "Create Project" button and a table listing all of your projects:

    Or it will open into one of your existing projects.

    If you are using App Engine, select the project id under which your Aggregate server is running. If the console opened into a different project, click on the currently-displayed project name in the upper-right side of the screen to access a drop-down menu, and choose your Aggregate server's project id. You will end up with a screen displaying your Aggregate's project (as above).
    If you are not using App Engine, click on the "Create Project" button, either the one on the screen or within the drop-down menu.
  3. If you are not using App Engine, this pops-up a project-creation dialog; type in a project name that makes sense to you. Then choose "Edit" to edit the project id. You may want to use a project id that combines your organization name and the name of your data collection group or project (if you were to use App Engine at some later time, the project id will be the first part of the URL to your App Engine server. I.e., your server will be referenced with a URL of the form https://project_id.appspot.com). You may also need to accept Google's terms-and-conditions, as indicated in the screen-shot below:
  4. In all cases, you should now be on the project screen, showing the project name in the upper-right side of the screen. In this case, I named my project and project id the same - "msundt-agg-test3":
  5. Click on the menu icon to the right of Google Cloud Platform. This opens a large left-side menu:
  6. And click on "API Manager":
  7. This takes you to the "API Manager" page:
  8. This lists all the application APIs that Google offers. To be able to publish to Google Sheets and Fusion Tables, and to be able to view maps, we need to enable this project to use 3 of these application APIs. The 3 application APIs we need to enable are:

    • Google Maps Javascript API v3
    • Drive API
    • Sheets API
    • Fusion Tables API

    The Sheets API is under the same section heading as the Drive API.

    Note that you will need to scroll down the screen to find the Fusion Tables API:

  9. For each of these APIs, click on the API. This takes you to an information page for that API. On that page, click on the "Enable" button. E.g., on the Google Maps Javascript API v3 page, it looks like this:
  10. After clicking on "Enable", if you have more application APIs to enable, click on the back-arrow within the page to return to the list of application APIs (and repeat the previous step):

    Otherwise, on the last of these application APIs, after enabling it, click on the "Go to Credentials" button:
  11. And on the credentials page, choose to create a "service account"
  12. This takes you to the list of service accounts for your Google Cloud Platform project. If you are using App Engine, there will already be a service account listed that was created and is used by Google's infrastructure. Ignore that. Choose to "Create service account".
  13. On the next screen, enter a name for the service account (e.g., "ODK Oauth2 Publishing"), choose to furnish a new private key, and request the P12 format. Then click "Create":
  14. The private key for this service account will begin downloading (it will have a .p12 file extension). After it has downloaded, click "Close".
  15. This returns you to the list of service accounts. Click on the the menu icon to the left of "Google APIs"
  16. Click "API Manager" on the resulting left-side menu:
  17. Now click "Credentials":
  18. Choose "Create credentials" and select "API Key":
  19. Then choose "Browser key":
  20. Enter a name (e.g., "ODK Aggregate"), and enter the hostname (and port, if nonstandard) of your ODK Aggregate server, followed by a slash and star. Then click "Create":
  21. This will generate an API Key. You may want to copy-and-paste this into a Notepad+ window to save steps finding in for entry during step 2, below.
  22. Clicking "OK" on that screen will return you to the Credentials page. Click on the "OAuth consent screen" tab.
  23. Enter a product name on this screen and fill in any additional fields that you might want to provide. The product name is the only field that is required to be filled in. Click "Save".
  24. Once again, click on the "Credentials" tab, select the "ODK Oauth2 Publishing" key that you created above, and choose "Manage service accounts":
  25. This takes you to details about that "ODK Oauth2 Publishing" service account. Keep this browser screen open; you will need to cut-and-paste values from this screen into ODK Aggregate in Step 2, below. This is what those details look like:

The "Service Account" information and the downloaded private key file must be uploaded to ODK Aggregate to enable publishing to Google Spreadsheets and Google Fusion Tables.

The "API Key" is for use by Google Maps.

Step 2: Entering Credentials into ODK Aggregate 1.3 and higher

Once you have created the credentials in step 1, you need to upload these credentials to ODK Aggregate.

The same credentials can be used across multiple ODK Aggregate servers.

To upload the credentials:

  1. Log onto ODK Aggregate as a Site Administrator. Click on the Site Admin / Preferences tab:
  2. Click on "Change Google API Credentials" to bring up the "Google API Credentials Upload" dialog:
  3. From the Google website, copy-and-paste the "API key" into ODK Aggregate's "Simple API Key" field:
  4. Click on "Choose File" and select the previously-downloaded (from Step 1, above) P12 private key file.
  5. From the Google website, copy-and-paste the "Service account" section's "Key ID" into ODK Aggregate's "ID (Key ID) or perhaps Client ID" field.
  6. From the Google website, copy-and-paste the "Service account ID" (it looks like an Email address) into ODK Aggregate's "Service Account ID (looks like an Email address)" field:
  7. Click on "Upload Google Credentials." This should present a successful-upload pop-up:
  8. Click on the "X" to close that pop-up. The "Simple API Access Key" and Google OAuth2 Credentials" should be updated:

Your ODK Aggregate server is now configured to support publishing of data to Google Spreadsheets and Google Fusion Tables.

If your publishers seems to be stalled in an Active Paused or Paused state, this is most likely caused by exceeding Google's quota limits. See the note at the top of this page for how to navigate to a pop-up from which you can request a quota limit increase.