The journal file (extension “.jnl”) is a text file that records line-by-line commands for uploading a ROAD recording. During recording the journal grows as new command lines are added, for example an updateFile command when a file expands.
When a recording is paused, the MAM Writer adds heartbeat lines so the MAM Adapter Service can cancel an upload if a timeout occurs.
Example
{ "operation": "createFile", "timestamp": "2026-04-27T12:34:56Z", "binaryFile": "myRecording884433.wav", "entryTarget": { "dbServer": "ServerDnsName", "dbTable": "TableName" }, "metadata": { "title": "my recording", "class": "audio", "customer/field": "myCustomField" } }
{ "operation": "updateFile", "timestamp": "2026-04-27T12:34:56Z", "binaryFile": "myRecording884433.wav", "fileOffset": 0, "dataLength": 25223592, "entryTarget": { "dbServer": "ServerDnsName", "dbTable": "TableName" } }
Structure of a journal JSON line
Each line is a command to execute from the MAM Adapter Service and its connected plugins as a JSON object. It may include the following parts, depending on the operation command.
operation
Every line must have an operation field. This defines the command to execute. See Description of the journal file | Journal line operation commands for details.
timestamp
This field specifies the current time in ISO 8601 date-time format as written by the MAM writer.
binaryFile
File path to the recorded audio file. The path can be absolute or relative to the journal file.
entryTarget
This object defines a database destination for the MAM system.
For DigaSystem, the fields dbServer and dbTable are required.
Other MAM vendors plugins may use different field names depending on the plugin implementation details.
metadata
This object defines the metadata to be transmitted to the destination.
For DigaSystem, field names use common database identifiers such as title, performer, artist, and author. Custom fields follow the format customer/fieldname.
Other MAM vendor plugins may use different field names or database structure.
fileOffset
During partial uploads the file grows. Here the MAM Writer defines the current offset for this part of the recording. The file offset prevents overwriting already uploaded audio. In short, the file offset marks the position where the last updateFile operation stopped. The number is defined in bytes.
dataLength
This field defines the complete length of the currently existing binary file. The number is defined in bytes.
Journal line operation commands
Depending on the command, all JSON fields are mandatory, as shown in the example.
initialize
Run this command first in a new journal file to set the upload heartbeat timeout (heartbeatInterval) or to set a context ID (contextId) for log-file readability so you can locate entries for a single upload process. This command is optional; without the MAM Adapterservice, the journal filename serves as the context ID and the heartbeat timeout is disabled.
Example:
{ "operation": "initialize", "timestamp": "2026-04-27T12:34:56Z", “contextId”: “myContextId” }
createFile
At the start of a new recording, the first line is the create file. This command passes metadata and the entryTarget information used by the MAM plugin.
Example:
{ "operation": "createFile", "timestamp": "2026-04-27T12:34:56Z", "binaryFile": "myRecording884433.wav", "entryTarget": { "dbServer": "ServerDnsName", "dbTable": "TableName" }, "metadata": { "title": "my recording", "class": "audio", "customer/field": "myCustomField" } }
updateFile
During recording, each time the MAM Writer updates the binary file, this line must be present to trigger the MAM plugin to upload that portion of the file.
{ "operation": "updateFile", "timestamp": "2026-04-27T12:34:56Z", "binaryFile": "myRecording884433.wav", "fileOffset": 0, "dataLength": 25223592 }
updateMetadata
Use this command to update metadata during a recording.
{ "operation": "updateMetadata", "timestamp": "2026-04-27T12:34:56Z", "binaryFile": "myRecording884433.wav", "metadata": { "title": "my recording update", "class": "audio", "customer/field": "myCustomField" } }
finalizeFile
Use this command to finalize an upload. The MAM Plugin uses it to mark the recording as stopped. The heartbeat watchdog does not stop when you run this command.
{ "operation": "finalizeFile", "timestamp": "2026-04-27T12:34:56Z", "binaryFile": myRecording884433.wav" }
cancel
Use this command to cancel an upload. It lets the MAM Plugin roll back created audio files and metadata entries. The heartbeat watchdog stops when you run this command.
{ "operation": "cancel", "timestamp": "2026-04-27T12:34:56Z", "binaryFile": myRecording884433.wav" }
finish
Use this command for finally finish watching the file and trigger the archiving of the source files.
The heartbeat watchdog stops when you run this command.
{ "operation": "finish", "timestamp": "2026-04-27T12:34:56Z", "binaryFile": myRecording884433.wav" }
heartbeat
After the initialize command sets a heartbeat timeout, the MAM Plugin expects heartbeats to confirm the MAM Writer is alive. If the timeout triggers, the MAM Upload stops and the source files move to the failed uploads directory.
{ "operation": "heartbeat", "timestamp": "2026-04-27T12:34:56Z", "binaryFile": myRecording884433.wav" }