Avicenna Research Transfers
An Avicenna Research transfer is a saved configuration on a virtual machine that pulls study exports from Avicenna Research, a third-party research data platform, into a directory on that VM. A transfer names an Avicenna study, the account used to reach it, the data to export (device and sensor data sources and survey responses), and the VM directory the files are written to. A transfer is not a copy of the data: it is the recipe for fetching it. Each time you run it, tiCrypt asks Avicenna Research to build fresh exports and writes the finished files to the VM.
Why Avicenna transfers live on the VM
The data should land where it is protected. Study data exported from Avicenna Research is research data like any other. Writing it straight into a directory on the VM puts it on the VM's encrypted drive, under the VM's own users, groups, and access directories, instead of on the computer of whoever downloaded it. Nobody has to save the files locally and upload them again.
The configuration belongs with the machine that analyses the data. Transfer configurations, including the Avicenna API key, are stored in the settings of the VM's controller, next to the data they produce, and only the VM's managers can open them in VM Settings and Details. The history of past runs is kept in tiCrypt.
The run is repeatable. A study keeps collecting data. Saving the study, the data sources, and the destination once means that pulling the latest data is a matter of choosing a date range and running the transfer again.
When to use an Avicenna transfer
- Recurring device or sensor exports: Use a transfer when you need the same sensor data sources from a study for different date ranges over time.
- Survey responses: Use a transfer to export the responses to published surveys in a study, by their activity IDs.
- One study per transfer: Create a separate transfer for each study or each destination directory, so that each configuration stays easy to recognise in the run history.
- Not for files you already have: To move files you already hold into the VM, use the File Transfer window instead.
Before you begin
- The VM is running, and you are its Owner, a Co-owner, or a Manager. Only they can open VM Settings and Details.
- You hold the system permission Share VMs with other users. Without it, the Avicenna Research Transfers section is visible but its actions are not offered.
- You have an Avicenna Research username and API key with access to the study, and you know the study ID.
- For survey exports, you know the numeric activity IDs of the published surveys.
- The destination directory exists on a drive mounted in the VM.
Configure a Transfer
- Go to the Virtual Machines icon in the top left taskbar.
- Click the VMs section on the top left panel.
- In the left panel, click the virtual machine to receive the data.
- Click the VM Settings and Details option in the bottom center.
- In the new window, expand Applications in the left panel and select Avicenna Research Transfers.
- Click Configure transfer in the top right panel.
- In the Configure Avicenna Research Transfer for
vm-nameprompt, fill in the fields described below. - Click Configure Transfer.
tiCrypt shows Created transfer "transfer-name", and the transfer appears in the list with
its Name, Study ID, Username, and
Destination. Before the first transfer, the list shows "This VM has no Avicenna
transfer configurations."
The following table describes the fields of the Configure Avicenna Research Transfer prompt.
| Field | Description |
|---|---|
| Name | A name for the transfer, up to 64 characters, unique on this VM. |
| Avicenna Username | The Avicenna Research account the transfer uses. Up to 128 characters. |
| API Key | The API key of that account. The field is masked. Up to 256 characters. |
| Study ID | The Avicenna Research study to export from. Up to 64 characters. |
| Device / Sensor Data Sources (optional) | The sensor data sources to export, chosen from the list Avicenna Research supports (for example Accelerometer, Gyroscope, or Light). The prompt shows how many sources are selected. |
| Survey Activity IDs | Under Survey Exports: the numeric activity IDs of published surveys in the study, separated by commas or spaces. The transfer exports the survey responses (ACTIVITY_RESPONSE data) for each ID. The prompt shows how many surveys will be exported. |
| Destination Directory | The VM directory the exported files are written to. |
The prompt shows the alert "Please select at least one device data source or enter at least one survey activity ID." until the transfer has something to export. You do not enter participant IDs: "Participant IDs will be automatically fetched from Avicenna when the transfer runs."
The API key is saved in the VM controller's settings with the rest of the transfer. Anyone who can manage transfers on this VM can run exports with it, so treat it as a credential you share with the VM's managers.
Run a Transfer
A run asks Avicenna Research to build new exports for a date range, waits for them to finish, and writes the files to the destination directory. There is no recurring schedule: each run is started by hand.
Location: Virtual Machines > VMs > select the virtual machine > VM Settings and Details > Applications > Avicenna Research Transfers
- Click the name of the transfer to open its detail page.
- Click Run Transfer in the top right panel.
- In the Run "
transfer-name" transfer prompt, set the Start date and End date. They default to seven days ago and today. - Click Run Transfer.
tiCrypt first runs the task Fetching participants for "transfer-name",
then starts one export per selected data source and per survey ID, in parallel. When every export
has been written, tiCrypt shows "Transfer completed:" followed by the number of files downloaded. If
some exports fail, it shows "Partial success:" with the numbers downloaded and failed. The run is
added to the transfer's history.
The run happens in your tiCrypt session, as a task you can follow in the task list. Keep tiCrypt open until it finishes.
What a run does
- Participants: tiCrypt asks Avicenna Research for the study's participant IDs. If that fails, it shows "Failed to fetch participants from Avicenna" and the run continues.
- Device exports: For each selected data source, tiCrypt requests an export for the date range and the study's participants.
- Survey exports: For each survey activity ID, tiCrypt requests an export of the survey responses. Survey exports do not use the date range or the participant list.
- Waiting: tiCrypt checks each export every 10 seconds. An export that is not ready within 15 minutes fails with "Export did not complete within the timeout".
- Files: Each finished export is downloaded and written to the destination directory as a ZIP file named after the data source or survey, the word
export, the export's study-specific ID, and the export date, for exampleaccelerometer-export-<id>-<YYYY-MM-DD>.zip.
The prompt rejects an end date earlier than the start date: "End date must be on or after start date".
Download Exports That Already Exist
The transfer's detail page lists the exports Avicenna Research holds for this transfer's data sources and surveys, so you can fetch an export again or fetch one that a run did not write.
Location: Virtual Machines > VMs > select the virtual machine > VM Settings and Details > Applications > Avicenna Research Transfers
- Click the name of the transfer to open its detail page.
- Review the Available Exports table.
- Click Download All New to write every successful export that is not yet in the destination directory, or select exports in the table and click Transfer followed by the number of files.
The selected exports are written to the destination directory, and their Downloaded column changes to Yes.
The following table describes the columns of the Available Exports table.
| Column | Description |
|---|---|
| File Name | The name the file is given in the destination directory. |
| Format | CSV or ZIP. |
| Status | Success, Processing, or Failed. Only successful exports can be downloaded. |
| Downloaded | Yes if a file with this name is already in the destination directory, No if not, and N/A for exports that did not succeed. |
| Time Created | When Avicenna Research created the export. |
Download All New does nothing when every successful export is already in the destination directory. Transfer is offered only when the selection includes at least one successful export.
View the Run History of a Transfer
- On the transfer's detail page, click View History.
- In the Run history dialog, review the Run Date, Data Start, and Data End of each run.
- Click Close.
The dialog lists the runs of this transfer, newest first. Before the first run it shows "No runs recorded yet."
To remove records, select them and click Delete followed by the number of records. The history record is removed; files already written to the VM are not.
Edit or Delete a Transfer
Location: Virtual Machines > VMs > select the virtual machine > VM Settings and Details > Applications > Avicenna Research Transfers
To edit a transfer:
- Select the transfer, then choose Edit from Open full menu. On the transfer's detail page, use Edit Transfer.
- In the Edit transfer
transfer-nameprompt, change the fields. - Click Save Changes.
tiCrypt shows Updated transfer "transfer-name".
To delete one or more transfers:
- Select the transfers, then choose Delete from Open full menu. On the transfer's detail page, use Delete Transfer.
- In the Delete
transfer-name? prompt, click Delete transfer.
The transfer configuration is removed from the VM. "Existing data in Avicenna will not be deleted." Files already written to the VM stay where they are.