Call ODK Central API

Introduction

This tutorial provides a comprehensive guide on calling the ODK Central API from xMart, or other oauth-like API that require a token.

Step 1: Obtain an ODK Central Account

Before proceeding, ensure you have the following information:

ODK Central server URL (e.g., https://collect.novel-t.ch)
Valid username and password (e.g., myuser@who.int and mypassword)

Step 2: Configure xMart Connection

Navigate to your mart Admin > Connections: https://extranet.who.int/xmart4/YOUR_MART/admin/connections

ODK Central supports both Basic Authentication and Bearer Token Authentication. While Basic Authentication is simpler, it’s not recommended for production use. Bearer Token Authentication is the recommended approach and can also be used with other APIs that support custom OAuth2-like authentication.

Basic Authentication

Under Webservice Basic Auth Connections, click the + button:

Set Name to MY_ODK_CENTRAL_API.
Enter your ODK Central account credentials for Username and Password.

Click Save to save the connection.

Bearer Token Authentication

Under Webservice Bearer Token Connections, click the + button:

Set Name to MY_ODK_CENTRAL_API.
Click the “Current Azure AD” button.
In the “Token Endpoint URL” field, set the ODK Central server URL followed by /v1/sessions (e.g., https://collect.novel-t.ch/v1/sessions).
In the JSON textbox, set the required properties.

{
  "Sys_TokenRequestFormat": "json", // either "json" or "form-data" for some APIs
  "Sys_ResponseTokenProperty": "token",  // where to find the token in the login response
  "Sys_AuthHeaderPrefix": "Bearer", // what goes in the "Authorization" header for the next request

  // then, append all json params expected by the API
  "email": "myuser@who.int",
  "password" : "${mart.ODK_PASSWORD}"
}

Note: ${mart.ODK_PASSWORD} refers to a mart variable that should be set in the mart Variables to avoid storing the password in clear text.

Step 3: Modify xMart Pipeline

Create or edit your pipeline: https://extranet.who.int/xmart4/YOUR_MART/pipelines/PIPELINE_CODE

In the Extract section, insert the following command:

<GetWebService Url="https://collect.novel-t.ch/v1/projects" ConnectionName="MY_ODK_CENTRAL_API"  TableName="data">
   <GetJson>
      <Path>$</Path>
   </GetJson>
</GetWebService>

You can replace the Url and Path elements with the actual API endpoint to be called.

Note: <GetOData > command can be used to call URLs that return ODK submission Data.

Ensure that any & characters in the Url attribute are XML-escaped as & to avoid parse errors.

Complete your pipeline by loading the stage table data into your target table using the regular <Load SourceTable="data" TargetTable="...">.