Search the knowledge base, browse our resources, and visit our forum for more detailed information
Last updated: 15 Oct 2025
Dynamic linking allows you to use data from a parent project within child projects, simplifying the management of longitudinal data collection. This article explains how to dynamically link data between KoboToolbox projects.
Note: Dynamic data attachments function similarly to the pulldata()
function but eliminate the need for separate CSV files, since the data from a linked parent project serves as the data source.
You can retrieve various non-media responses from a parent project and perform calculations on this linked data in a child project. This can be useful for retrieving baseline data, contact information, or health records in cohort studies, or for confirming or verifying previously collected data.
We recommend using XLSForm to set up dynamic data attachments. For examples of parent and child projects, download sample files here and here.
Dynamically linking projects requires a parent project and at least one child project. The parent project requires no modification from a normal XLSForm. However, setting up the child project(s) involves the following steps:
In the survey
worksheet of your XLSForm, add a row and set the question type to xml-external
.
In the name
column, provide a short name for the parent form. This name can consist of Latin alphabet characters, underscores, and numbers.
survey worksheet
type |
name |
label |
---|---|---|
xml-external |
parent |
|
survey |
Throughout the form, you can retrieve values from the parent project by creating a new question and including the appropriate expression in the calculation
column (see table below). You can use the following question types to retrieve data:
Use a calculate question type to retrieve and store values for future use within the form or dataset (e.g., for calculations or dynamic question labels).
Use text, integer, decimal, select_one, or select_multiple question types to include retrieved values as default responses in editable fields. Data edited in the child project will not change the original data in the parent project.
survey worksheet
type |
name |
label |
calculation |
---|---|---|---|
xml-external |
parent |
||
text |
participant_id |
What is the participant’s ID? |
|
integer |
age |
Confirm the participant’s age |
instance(‘parent’)/root/data[enrollment_id = current()/../participant_id]/age |
survey |
Note:
To display linked data without allowing users to edit the field, use a calculate question followed by a note question that displays the calculated value. Alternatively, use text, integer, decimal, select_one, or select_multiple questions with the read_only
column set to TRUE
.
In the calculation
column of the row where linked data will be retrieved, include one of the expressions in the table below. These expressions are called XPaths.
For each expression in the table below:
parent
is the unique name assigned to the parent form (e.g., in the xml-external
question of the child form).
parent_question
refers to the name
of a question from the parent form.
child_question
refers to the name
of a question from the child form.
parent_index_question
is the identifying question from the parent form that links it to the child form (e.g., unique ID, organization name).
child_index_question
is the identifying question from the child form that links it to the parent form (e.g., unique ID, organization name).
parent_group
refers to the name
of the group in the parent form in which the parent_question
is located.
parent_index_group
refers to the name
of the group in the parent form in which the parent_index_question
is located.
XPath |
Description |
---|---|
|
Returns the total number of rows in the parent project. |
|
Returns the total number of rows in the parent project where |
|
Returns the total count of instances where the value of |
|
Returns the value of |
|
Same as above, but specifies that only data from the first instance of |
|
Returns the sum of values from |
|
Returns the maximum value entered in |
|
Returns the minimum value entered in |
Note: If the parent question is not included in any group, omit parent_group
from the expression
Once your XLSForms are set up, log into your KoboToolbox account and follow these steps:
Upload and deploy the parent project, if not already deployed. Ensure the parent project has at least one submission.
Enable data sharing for the parent project:
In the SETTINGS > Connect Projects tab of the parent project, toggle the Data sharing switch (disabled by default) and click ACKNOWLEDGE AND CONTINUE in the confirmation window.
All data is shared by default, but you can restrict specific variables to share with child projects by clicking “Select specific questions to share”.
Note: If projects have different owners, the parent project owner must share the project with the child project owner. The minimum permissions required for dynamic data attachments to work are View form and View submissions. Note that this allows child project administrators to view all parent project data.
Upload and deploy the child project.
Connect the child project to the parent project:
In the SETTINGS > Connect Projects tab of the child project, click the “Select a different project to import data from.” A dropdown menu will allow you to select a parent project to link.
Rename the linked parent project to the xml-external
question name defined in the XLSForm and click IMPORT.
You can then select specific questions from the parent project to share with the child project, or select all questions.
If you add new fields to the parent form and wish to use them in the child project, re-import the parent project in the child project settings.
Note: Forms can only be linked together if they are on the same KoboToolbox server.
It is possible for a parent and child project to be the same project. The steps are the same as those described above. Examples of use cases include:
Daily monitoring: If a form is used to survey the same person over time, you can link it to itself to count previous submissions. This can allow you to display a message (e.g., “monitoring is complete”) after a certain number of entries or to inform the enumerator of the number of forms submitted, as shown in the example below.
survey worksheet
type |
name |
label |
calculation |
---|---|---|---|
xml-external |
monitoring |
||
text |
participant_id |
What is the participant’s ID? |
|
calculate |
count |
count(instance(‘monitoring’)/root/ data[monitoring/participant_id = current()/../participant_id]) |
|
note |
monitoring_note |
This participant has been surveyed ${count} times. |
|
survey |
Registration form: By linking a registration form to itself, you can check whether a user has already been registered. This can allow you to generate an error message or add a constraint if they are already registered, preventing duplicate registrations, as shown in the example below.
survey worksheet
type |
name |
label |
calculation |
relevant |
---|---|---|---|---|
xml-external |
registration |
|||
text |
customer_id |
What is the customer’s ID number? |
||
calculate |
count |
count(instance(‘registration’)/root/ data[registration/customer_id = current()/../customer_id]) |
||
note |
already_registered |
This customer is already registered. Please close this form. |
${count} > 0 |
|
survey |
Data for dynamically linked projects can be collected using the KoboCollect Android app or Enketo web forms.
When collecting data, note the following:
The parent project must have at least one submission for the child project to function correctly.
When collecting data online, there is a five-minute delay in syncing new parent project data with the child project.
In offline mode, frequently download the child project to ensure data synchronization with the parent project.
Note: You can configure the KoboCollect Android app to automatically update the parent project's data when an internet connection is available. Go to Settings > Form management > Blank form update mode and select either Previously downloaded forms only or Exactly match server. You can set the automatic download frequency to occur every 15 minutes, every hour, every six hours, or every 24 hours. Note that enabling this setting may increase battery consumption.
[position()=1]
argument, as below:
instance('parent')/root/data[parent_index_group/parent_index_question = current()/../child_index_question][position()=1]/parent_group/parent_question
Did you find what you were looking for? Was the information clear? Was anything missing?
Share your feedback to help us improve this article!
KoboToolbox is maintained by Kobo Inc.