Downloading attachments from a delivery's results

This documents describes how to fetch audio recording files (that were collected through the usage of a PCI Audio Recording interactions) using the Dynamic Query REST API. This method can be applied to other types of attachments, such as spreadsheets in the File Upload interaction.

Prerequisites

API authentication

Fetch a Single Audio Recording

1. General Approach

To retrieve the recording(s) included in a delivery’s results, identify the following values:

[DELIVERY_ID] : The delivery Identifier associated with the delivery. This value is required to complete the query. This can be found in TAO Authoring in the Deliveries tab.
[LOGIN]: The username of the test taker. This value may be used to narrow down your search.
[ITEM_ID]: The resource Identifier of the item containing the attachment; this can be found in the Item Properties (in Item authoring). This value may be used to narrow down your search.
The responseVariable with identifier [YOUR_RESPONSE_VARIABLE_IDENTIFIER], where the item contents are stored. This value may be used to narrow down your search.

Retrieving the assessmentItemSession data for the deliveryExecutions record related to that test-taker for a given delivery is possible by searching the uploads entity in Dynamic Query REST API:

CODE

curl -X POST "[YOUR_DYNAMIC_QUERY_URL]/api/v1/search/uploads" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer [YOUR_ACCESS_TOKEN]" \
     --data '{"filters": [{"type": "terms", "field": "deliveryId", "values": ["[DELIVERY_ID]"]}, {"type": "terms", "field": "login", "values": ["[LOGIN]"]}], "response":{"fields": ["deliveryId", "login", "deliveryExecutionId", "itemId", "fileName", "rawResponses.value", "rawResponses.identifier", "rawResponses.baseType", "rawResponses.uploadDocumentIdentifier", "rawResponses.docDownloadUrl"]}}'

The results will be returned as complex structure that would be difficult to traverse without knowing what to search for. Using the item identifier ([YOUR_ITEM_ID]) and the response identifier ([YOUR_RESPONSE_VARIABLE_IDENTIFIER]), you can traverse the payload in multiple ways, using your preferred programming language. However, this example will continue to use the command line.

2. Traversing the Payload

One of the most know ways to traverse a JSON data structure is JSONPath. If [ITEM_ID] is “item-1” and [RESPONSE_VARIABLE_IDENTIFIER] is “RESPONSE“. In JSONPath, it would look like:

CODE

$.data[?(@.itemId=='item-1')].rawResponses[?(@.identifier=='RESPONSE')]

And would resolve to something similar to:

CODE

{
  "identifier": "RESPONSE",
  "correct": null,
  "uploadDocumentIdentifier": "7cjga824c64cb#64e858f5e9a8#0a92fab3230134cca6eadd9898325b9b2ae67998#2001/item-1/RESPONSE/3ac38gded791c87fbcb5573ac7fa86b886fe",
  "value": "audioRecording_1738079545434.ogg",
  "cardinality": "single",
  "baseType": "file",
  "docDownloadUrl": "https://a.location.to/download/file.ogg"
}

3. Identifying the attachment(s)

In order to download the file, dereference the URL found in the docDownloadUrl using for instance the wget command. You can also paste it into a web browser.

CODE

wget -O /tmp/audio.ogg https://a.location.to/download/file.ogg

For obvious security purpose, URLs are signed and valid for a limited period of time. It is highly encouraged to download files as soon as you receive the JSON payload, and store it for later usage.

4. Going Further

Here is an example curl call combined with jq in order to retrieve, traverse, and display the results in a more readable format.

CODE

curl -s -X POST "[YOUR_DYNAMIC_QUERY_URL]/api/v1/search/uploads" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer [YOUR_ACCESS_TOKEN]" \
     --data '{"filters": [{"type": "terms", "field": "deliveryId", "values": ["[DELIVERY_ID]"]}, {"type": "terms", "field": "login", "values": ["[LOGIN]"]}]}' | jq '.data[] | select(.itemId == "[ITEM_ID]") | .rawResponses[] | select(.identifier == "[RESPONSE_VARIABLE_IDENTIFIER]")'

The jq filter, considering that [ITEM_ID] is “item-1” and [RESPONSE_VARIABLE_IDENTIFIER] is “RESPONSE“, would be the following:

CODE

jq '.data[] | select(.itemId == "item-1") | .rawResponses[] | select(.identifier == "RESPONSE")'

Fetch Multiple Audio Recordings

In order to fetch multiple recordings from the same delivery, remove filters (including [LOGIN]) from your search and repeat the process described above.