Avni Data Source

Avni is an open-source field-data platform for health, livelihoods, and social-sector programs. Follow the instructions below to create a new data flow that ingests data from an Avni source in Nexla.

Avni

Create a New Data Flow

1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

2. Select the Avni connector tile from the list of available connectors. Then, select the credential that will be used to connect to the Avni instance, and click Next; or, create a new Avni credential for use in this flow.

3. In Nexla, Avni data sources can be created using pre-built endpoint templates, which expedite source setup for common Avni endpoints. Each template is designed specifically for the corresponding Avni endpoint, making source configuration easy and efficient.
   • To configure this source using a template, follow the instructions in Configure Using a Template.

   Avni sources can also be configured manually, allowing you to ingest data from Avni endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
   • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Avni endpoints. Each template is designed specifically for the corresponding Avni endpoint, making data source setup easy and efficient.

Endpoint Settings

• Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

  List Subjects

  This endpoint returns a paginated list of Avni subjects — the top-level entity in the Avni domain model, representing the people, households, or other units that programs are run for. Use this endpoint to sync your beneficiary registry into a warehouse, build longitudinal cohorts, or feed downstream analytics.

  • Enter an ISO 8601 datetime in the Last Modified Date Time field to fetch only subjects modified on or after that timestamp. Leave the field blank to fetch all subjects. For incremental syncs, use a datetime macro such as {'{now-1}'} with a Day time unit to pull subjects modified in the last 24 hours.
  • Enter the page size in the Page Size field (Avni's default is 100). Smaller pages reduce per-request payload size but require more round trips.
  • Enter the zero-indexed starting page in the Page Number field. Nexla advances the page automatically; in most cases this should be set to 0.

  Avni list endpoints return data under $.pageOfResources[*], which is set automatically by the template. Observation dates within each subject are returned in yyyy-MM-dd format rather than ISO timestamps. For complete field reference, see the Avni API Guide.

  Get Subject

  This endpoint retrieves a single Avni subject by its internal ID or UUID. Use it to enrich an existing dataset of subject IDs with the latest full subject record, or to drive a chained API call from another source.

  • Enter the subject's internal ID or UUID in the Id field. Subject IDs and UUIDs can be obtained from the List Subjects endpoint or from upstream Nexla data flows.

  This endpoint returns a single subject object (not a paginated array). The path to data is set to the response root ($) so the subject is treated as the record.

  Get Subject With All Entities

  This endpoint retrieves a subject and all its related entities — enrolments, encounters, program encounters, checklists, and relationships — in a single call. Use it to hydrate a complete longitudinal record for one subject without making multiple round trips.

  • Enter the subject's UUID in the Subject UUID field. The internal numeric ID is not accepted by this endpoint — only the UUID. UUIDs can be obtained from the List Subjects endpoint.

  This endpoint is significantly heavier than Get Subject. Use it when you need the complete history for a small set of subjects; for bulk longitudinal extracts, the individual list endpoints (List Enrolments, List Encounters, List Program Encounters) with lastModifiedDateTime filters are more efficient.

  List Enrolments

  This endpoint returns a paginated list of Avni program enrolments — the registration of a subject into a longitudinal program (for example, antenatal care, child nutrition, or a livelihoods scheme). Use it to sync program participation into a warehouse or to feed downstream cohort analysis.

  • Enter an ISO 8601 datetime in the Last Modified Date Time field to fetch only enrolments modified on or after that timestamp. For incremental syncs, use a datetime macro such as {'{now-1}'}.
  • Enter the page size in the Page Size field (Avni's default is 100).
  • Enter the zero-indexed starting page in the Page Number field — typically 0.

  Each enrolment is a child of a subject. Observation dates within enrolment records are returned in yyyy-MM-dd format rather than ISO timestamps.

  Get Enrolment

  This endpoint retrieves a single program enrolment by its internal ID or UUID. Use it to fetch the full enrolment record — including observations recorded at enrolment and exit — for a known enrolment.

  • Enter the enrolment's internal ID or UUID in the Id field. Enrolment IDs and UUIDs can be obtained from the List Enrolments endpoint.

  List Encounters

  This endpoint returns a paginated list of general subject encounters — visits or interactions with a subject that are not part of a program (for example, a one-off home visit or a non-programmatic health checkup). Use it to sync ad-hoc visit data into a warehouse.

  • Enter an ISO 8601 datetime in the Last Modified Date Time field to fetch only encounters modified on or after that timestamp. For incremental syncs, combine this with a datetime macro such as {'{now-1}'}.
  • Enter the page size in the Page Size field (Avni's default is 100).
  • Enter the zero-indexed starting page in the Page Number field — typically 0.

  General encounters are distinct from program encounters. To sync visits made within an enrolled program (such as antenatal-care visits), use the List Program Encounters endpoint instead.

  Get Encounter

  This endpoint retrieves a single general subject encounter by its internal ID or UUID. Use it to fetch the full record for one encounter, including observations and cancellation observations.

  • Enter the encounter's internal ID or UUID in the Encounter ID field. Encounter IDs and UUIDs can be obtained from the List Encounters endpoint.

  List Program Encounters

  This endpoint returns a paginated list of program encounters — visits made within the context of a program enrolment (for example, a scheduled antenatal-care visit or a growth-monitoring check). Use it to sync longitudinal program visit data into a warehouse for cohort analysis or reporting.

  • Enter an ISO 8601 datetime in the Last Modified Date Time field to fetch only program encounters modified on or after that timestamp.
  • Enter the page size in the Page Size field (Avni's default is 100).
  • Enter the zero-indexed starting page in the Page Number field — typically 0.

  Program encounters are children of an enrolment, which is in turn a child of a subject. To reconstruct the full hierarchy downstream, join program encounters to enrolments by the enrolment UUID, and enrolments to subjects by the subject UUID.

  Get Program Encounter

  This endpoint retrieves a single program encounter by its internal ID or UUID. Use it to fetch the full record for one program-encounter visit.

  • Enter the program encounter's internal ID or UUID in the Program Encounter ID field. IDs and UUIDs can be obtained from the List Program Encounters endpoint.

  List Tasks

  This endpoint returns a paginated list of Avni tasks — actionable items (call tasks or open-subject tasks) assigned to frontline workers. Use it to sync the task queue into a downstream operations dashboard or to monitor task throughput.

  • Enter an ISO 8601 datetime in the Last Modified Date-Time field to fetch only tasks modified on or after that timestamp.
  • Enter the page size in the Page Size field. The default page size for the tasks endpoint is 50.
  • Enter the zero-based starting page in the Page Number field — typically 0.

  The tasks endpoint returns data under $.content[*], which is set automatically by the template. Tasks can only be created via the external API, so this list represents tasks originally created by Nexla or another integration.

  Get Task

  This endpoint retrieves a single task by its ID. Use it to look up the current status of a task previously created via the Create Task destination.

  • Enter the task ID in the Task ID field. Task IDs are returned by the List Tasks endpoint or by the Create Task destination response.

  List Datasets

  This endpoint returns a list of all available Avni datasets. Datasets are pre-defined data extracts that an Avni administrator has configured for downstream consumption. Use this endpoint as a catalog to discover available datasets and their IDs.

  • No configuration is required for this endpoint beyond selecting it. All datasets accessible to your OAuth client are returned automatically.

  Dataset IDs returned by this endpoint are required by the Get Dataset and List Dataset Items endpoints.

  Get Dataset

  This endpoint retrieves a specific dataset's metadata by its ID. Use it to inspect a dataset's definition (columns, filters, source entity) before fetching its contents.

  • Enter the dataset's unique identifier in the Dataset ID field. Dataset IDs can be obtained from the List Datasets endpoint.

  List Dataset Items

  This endpoint returns the items (rows) contained within a specific dataset. Use it to bulk-ingest the rows of a configured Avni dataset into a warehouse or downstream analytics system.

  • Enter the dataset's unique identifier in the Dataset ID field. Dataset IDs can be obtained from the List Datasets endpoint.

  The template's path to data is set to $.items[*], which exposes each row of the dataset as a Nexla record.

  Get Segments

  This endpoint returns a list of available Avni segments — named cohorts of subjects defined by an administrator. Use it to keep downstream systems in sync with the segment catalog or to enrich subject data with cohort membership.

  • No configuration is required for this endpoint beyond selecting it. All segments accessible to your OAuth client are returned automatically.

  List Notes

  This endpoint returns a list of available notes from Avni. Use it to sync free-text notes captured by frontline workers into a downstream review or analytics system.

  • No configuration is required for this endpoint beyond selecting it. All notes accessible to your OAuth client are returned automatically.

Endpoint Testing

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually

Avni data sources can be manually configured to ingest data from any valid Avni external API endpoint. Manual configuration provides maximum flexibility for accessing endpoints not covered by pre-built templates or when you need custom query parameters, custom paths to data, or chained API calls.

With manual configuration, you can also create more complex Avni sources — for example, sources that chain a list endpoint to a detail endpoint, or sources that filter on additional query parameters not exposed by the pre-built templates.

API Method

1. To manually configure this source, select the Advanced tab at the top of the configuration screen.

2. Select the API method that will be used for calls to the Avni API from the Method pulldown menu. Avni read endpoints use GET:

   • GET: For retrieving data from the Avni API (list and get endpoints)
   • POST: For idempotent create-or-update operations on subjects, enrolments, encounters, program encounters, and tasks (configured on the destination side)

API Endpoint URL

3. Enter the URL of the Avni API endpoint from which this source will fetch data in the Set API URL field. All Avni external API URLs are of the form <base_url>/api/<resource> — for example, https://app.avniproject.org/api/subjects or https://app.avniproject.org/api/programEncounters. The credential's Base URL value is automatically available as {data_credential["avni_api.base_url"]} if you need to reference it dynamically.

Only the documented Avni external API endpoints (under /api/*) should be used. The undocumented internal endpoints used by the Avni mobile and web apps are not designed for third-party integration and may change without notice. For a full list of documented endpoints, see the Avni API Guide.

Date/Time Macros (API URL)

Optional

Optionally, the API URL can be customized using macros—all macros added to the API URL will be converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that can adapt to different time periods. They are particularly useful for the Avni list endpoints, which support a lastModifiedDateTime query parameter for incremental syncs.

For example, use {'?lastModifiedDateTime={now-1}'} with a Day time unit to always fetch records modified in the last 24 hours, enabling efficient incremental ingestion of subjects, enrolments, encounters, or program encounters.

1. To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.

   • {now} – The current datetime

   • {now-1} – The datetime one time unit before the current datetime

   • {now+1} – The datetime one time unit after the current datetime

   • custom – Datetime macros can reference any number of time units before or after the current datetime—for example, enter (now-4) to indicate the datetime four time units before the current datetime

2. Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. Avni's lastModifiedDateTime filter expects an ISO 8601 datetime, so the format should produce ISO 8601 output (for example, yyyy-MM-dd'T'HH:mm:ss.SSSXXX).

3. Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu—for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.

Lookup-Based Macros (API URL)

Optional

Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic API endpoints that can adapt based on existing data. For Avni, this is useful when you have a Nexla dataset of subject UUIDs, enrolment UUIDs, or encounter UUIDs and want to fetch the related detail record for each.

Lookup-based macros are useful for chained Avni sources — for example, listing subject UUIDs from List Subjects and then fetching the full longitudinal record for each via Get Subject With All Entities.

1. To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.

2. Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.

Path to Data

Optional

If only a subset of the data returned by an Avni endpoint is needed, you can designate the part(s) of the response that should be included in the Nexset(s) by specifying the path to the relevant data within the response.

Avni list endpoints wrap their results in a response envelope, so the path to data must point to the relevant array within that envelope. Common paths are:

• $.pageOfResources[*] – For the paginated list endpoints (/api/subjects, /api/enrolments, /api/encounters, /api/programEncounters)
• $.content[*] – For the tasks list endpoint (/api/tasks)
• $.data[*] – For the datasets, segments, and notes list endpoints
• $.items[*] – For the dataset-items endpoint (/api/datasets/{id}/items)
• $ – For single-resource endpoints (/api/subjects/{id}, /api/enrolments/{id}, etc.)

Path to Data is essential when API responses have nested structures. Without specifying the correct path, Nexla might not be able to properly parse and organize your data into usable records.

• To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

  • For responses in JSON format enter the JSON path that points to the object or array that should be treated as relevant data. JSON paths use dot notation (for example, $.pageOfResources[*] to access every element of the paginated response array).
  Path to Data Example:

  For an Avni list endpoint such as GET /api/subjects, enter $.pageOfResources[*] as the path to data so each subject in the paginated array is treated as a record. For a single-resource endpoint such as GET /api/subjects/{'{id}'}, enter $ so the whole response body is treated as a single record.

Autogenerate Path Suggestions

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

• To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

• Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

  

Metadata

If metadata is included in the response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record. This is useful when you want to preserve important contextual information that applies to all records but isn't part of the main data array.

For Avni paginated list endpoints, response envelopes typically include sibling metadata such as totalElements, totalPages, pageNumber, and pageSize. You can preserve these on every record by configuring a metadata path.

For example, enter $ in the metadata path field to attach the entire response envelope (excluding the array specified by Path to Data) to every record produced from an Avni list endpoint.

• To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

  • For responses in JSON format, enter the JSON path to the object or array that contains the metadata.

Request Headers

Optional

• If Nexla should include any additional request headers in API calls to this source, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (for example, header1:value1,header2:value2).

  You do not need to include any headers already present in the credentials. The AUTH-TOKEN header carrying the Avni JWT is added automatically based on your Avni credential.

Endpoint Testing

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source

1. Once all of the relevant steps in the above sections have been completed, click the Create button in the upper right corner of the screen to save and create the new Avni data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.