DPE Writer Filter Specification

The DPE Writer filter can only be used as the last filter in an output graph. It creates a new audio entry in a DigaSystem database table, using the DPE ContentService. To generate a valid file, it should be preceded in the output graph by a WAVDest filter.

Optionally a local file can be created while upload to DPE is running. This file is either kept afterwards or removed after a successful upload has been finished. See description for parameter keeplLocalFiles below.

JSON Structure

JS

{
    "name": "DPE Writer",
    "dpeUrl": "...",
    "uploadBlockSize": ...,
    "retryInterval": ...,
    "maxRetryCount": ...,
    "maxRetryTime": ...,
    "dbServer": "...", 
    "dbTable": "...",
    "userName": "...",
    "password": "...",
    "localFile": "...",
    "keepLocalFiles": ...,
    "zeroLengthFileDeletion": "...",
    "deferEntryCreation": true/false,
    "directFileAccess": "...",
    "allowFileRenaming": true/false,
    "metadata": {
        "title", "...",
        "...": "...",
        ...
    }
}

Field	Description
dpeUrl	Base URL of the DPE installation; or "(none)" (see section "Omitting DPE Upload" below)
uploadBlockSize	Number of bytes which are uploaded to DPE in one HTTP request. The parameter is optional, the default is 1048576 (1 MB).
retryInterval	Interval (in milliseconds) between tries to upload one block of data to DPE after the first attempt failed. The parameter is optional, the default is 1000.
maxRetryCount	Maximum number of retries to upload one block of data to DPE after the first attempt failed. The parameter is optional, the default is 60.
maxRetryTime	Maximum time frame (in milliseconds) in which the upload of one block of data to DPE must succeed. The parameter is optional, the default is 600000 (10 minutes).
dbServer	Name of the database server in the DigaSystem installation.
dbTable	Name of the table on the server, into which the new entry will be uploaded.
userName	User name and password to logon to DPE. This user must have the right to create and write an entry to the specified DigaSystem table. If these fields are both missing, the ROAD Service will fill it with defaults defined by the DpeDefaultUser and DpeDefaultPassword variables (see paragraph "Special Variables" in api/variables). This is applied in the moment when the job is being created. Since v1.5.514.0 this password field is encrypted when written to the database. An encrypted password can be recognized, so it won’t be encrypted again. By this it is possible read and write back an encrypted password without caring about this.
password
localFile	Full path name of a local file, which is written as "backup" in case the DPE upload fails. If only a filename is given but no path, the file is written to the default folder for temporary files. The parameter is optional; if it's not specified, no local file is written. If the file already exists (e.g. from a previous job with a failed upload), a numerical suffix is appended to the base name of the file to create a unique new filename. While creation is still in progress, two files are created (.wav for audio and .dbx for meta data), which are mostly merged into a .entry when finishing. It is strongly recommended to specify a local file as otherwise a failing DPE upload (e.g. because of a temporary problem) will lead into losing the whole audio. Placeholders are supported in this field. Whenever a change in a placeholder changes the filename, the local file is closed, renamed, and reopened. Note: On a truly local file, this renaming will never fail. However, be careful with using the feature, when the "local" backup file is actually stored on a network path. Some network storage devices may not behave reliably in such a situation.
keepLocalFiles	Specifies if and how long the local file is being kept even after a successful upload to DPE. If a number > 0 is specified here, the local file generated by the filter is not deleted even if no error occurred during the upload to DPE. Instead, the file is moved into an "Archive" sub-folder at its location. The value of the parameter defines the number of days, for which files are kept in this "Archive". If -1 (or any value < 0) is specified, the local files are left untouched at the end of the recording, regardless whether the upload to DPE was successful or not. The parameter is optional. If not specified, it defaults to 0, which means that local files are deleted immediately after a successful upload. In case the DPE upload did not succeed until its end, the local file will be kept and not automatically deleted. In this case the local file can be imported to Digas via manually dropping it to the target table (in Content Manager or DBM).
zeroLengthFileDeletion	This parameter controls what happens, if a recorded file has an audio play length of 0 (e.g. if a start level filter has never triggered). It is a string, which the following possible values: "soft": The database entry is soft-deleted. "hard": The database entry is hard-deleted "no": The database entry is not deleted The string is case-insensitive. The parameter is optional, and the default is "soft". Any value not in the list, incl. an empty string, is also handled like "soft".
deferEntryCreation	If `false` , the database entry is created immediately when the filter is connected. If `true` , database entry creation is deferred until the first audio data is going to be written. The parameter is optional, the default is `true` .
directFileAccess	The parameter controls, how the audio file is written to its storage location. "off": The audio is streamed via the UploadMedium handler of the DPE backend. "on": The audio file is directly written to the file share, where the destination table stores its audio data. "auto": The filter checks, if the file share is accessible for read/write access. If yes, the file is written to that share, otherwise, it's streamed via the DPE backend. The parameter is optional, the default is "auto". This is a change from ROAD 1.4 to 1.5 - up to version 1.4, the option didn't exist, and ROAD only implemented the "off" behavior. Notes: If "on" is specified, and the file share is not accessible, the upload will fail. The account, under which the ROAD Service (and therefore the ROAD Workers) run, has to have access rights to the file share. This is not possible for the “Local System” or “Local Service” accounts! Therefore, to use direct file access the ROAD Service must run under an appropriate domain account.
allowFileRenaming	If `true`, recorded files can be renamed during the recording. For details and an important warning, see paragraph about File Naming below. The parameter is optional, the default is `false` .
metadata	A list of field/value pairs which are sent as metadata for the new table entry. The field names must match the field names as used by the DPE Content Service. To write DigaSystem custom fields, use the "/" syntax, e.g. "CUSTOMER/MYFIELD". All metadata fields can contain Placeholders . The metadata field is optional; if it's not specified, only a generic default title is used and the other database fields will be left empty. Note: The metadata field "filename" is handled specially. See paragraph about File Naming below.

Omitting DPE Upload

In test scenarios or for special use cases, you can omit the DPE upload altogether, and write the data only to a file on disk. To do this, you specify the string "(none)" (including the parentheses) in field "dpeUrl" , and in addition provide only the field "localFile" . All other fields are ignored and can be omitted in this case.

The main advantage of using this feature as compared to using a plain File Writer Filter is, that the file will be properly switched if you have an Output Switch configured in the job.

File Naming

The field "filename" in "metadata" is treated in a special way, depending on the "directFileAccess" option.

DPE Writer streams the audio to the DPE backend

"filename" is ignored, because it's up to the DPE backend to create a suitable unique file name

DPE Writer writes the audio directly to the file

If no "filename" is specified, the DPE Writer creates a unique name. Otherwise, DPE Writer tries to use the name and extension provided in "filename". Placeholders are supported in this field, incl. the ${Starttime} variable for a job's starting time. If the resulting name is already in use, a numerical suffix is automatically appended.

Renaming

ROAD has some internal logic to change the actual start time to the nominal one (e.g. as specified in the Job Schedule) in ${Starttime} evaluation, shortly after the recording has actually started. This typically results in a change of a few hundred milliseconds. Every metadata field containing a ${Starttime} placeholder is then updated accordingly. In principle, this should also apply to the file name. However, by default files are not renamed. You can override this by setting option "allowFileRenaming": true - but see the following warning!

WARNING In general, you should not use "allowFileRenaming": true, for the following reasons:

Closing, renaming and reopening a file in quick succession doesn't work reliably on some network file storage systems. This could lead to a failure of otherwise perfectly running recordings.
Renaming the audio file of a running recording can disturb any read-while-write workflows, even if the file is renamed relatively soon after it has been created.

Note: When using a ${Starttime} placeholder in "filename" and option "allowFileRenaming": true, you should make sure that the constant part of the filename (i.e. the one outside the placeholder) is unique for all jobs which can potentially start at the same nominal time.