2. Associating Metadata via NexLog Metadata Feeds

2.1. Metadata Feeds

NexLog recorders support Metadata Feeds, which are used to send control data to the recorder. The format of these feeds and the behavior the recorder will take upon receiving commands via these feeds is programmable in the Recorder’s Configuration Manager under System ->Configuration Files. The Metadata Feed parser is highly configurable and often used to parse ANI/ALI or SMDR data in a fixed format. However it can also be configured to parse a simple set of commands received as ASCII text over a UDP or TCP port. This document will focus on this use of the Metadata Feed Parser.

Metadata feeds are a licensed feature on the recorder and a license key must be programmed into the recorder to activate the feed. The charge for the license key may also include assistance from an Eventide Integrations engineer to program the recorder’s metadata feed format and behavior to match the customer’s needs. Please contact Eventide Sales for information on pricing. A metadata feed can be configured to take commands from the recorder’s built-in serial ports or an add-on serial port board available from Eventide, or from a UDP or TCP connection over the recorder’s Ethernet port. Commands are sent to the recorder using a simple unidirectional ASCII-based protocol, and the format is configurable. Upon receiving a message via this connection, the recorder can be configured to perform a command on a given channel; for example, “Start a call if not already recording,” “Stop a call that is in progress,” “Stop the current call and start a new one,” or “Delete the call in progress.” In addition, the metadata feed can send additional information about the call in-progress to the recorder to be stored in the recorder database along with the other normally stored information. This information can be viewed or queried using Eventide’s graphical retrieval clients (MediaWorks, MediaAgent). It can also be accessed programmatically over ODBC. For example, this can be used to have an external controlling program start a call and give it a known identifier so that the call can later be retrieved by that identifier.

The examples below describe one simple command set which can be programmed into the Metadata Feed Parser. Different command formats and semantics can also be programmed for cases where the remote software sending commands to the recorder cannot be modified. For new development or integrations, these standard commands normally suffice for most needs. From this point forward the information in this section refers only to this single possible command set configuration.

Commands will be sent to the recorder from remote software by sending a UDP/TCP command packet to the recorder on port 5000. The data is sent as an ASCII text string starting with the string ‘<<’ and ending with the string ‘>>’. Individual fields are separated with the string ‘::’. A newline (\n) may be sent between commands and will be ignored. Commands are executed by the recorder as they arrive.

2.2. Metadata Commands

2.2.1. Start

Start recording on a given physical recorder channel.

Format:

<<CHANNEL_NUMBER::START>>

Example:

<<61::START>>

Description:

When this command is received, the recorder will start recording on channel 61. If a call is already in progress on 61, nothing will be changed, and the current call in progress will continue to record.

2.2.2. Stop

Stop recording on a given physical recorder channel.

Format:

<<CHANNEL_NUMBER::STOP>>

Example:

<<54::STOP>>

Description:

When this command is received, the recorder will stop recording on channel 54. If no call is in progress on 54, nothing will be changed.

2.2.3. Break

Perform a call break on a physical recorder channel.

Format:

<<CHANNEL_NUMBER::BREAK>>

Example:

<<36::BREAK>>

Description:

When this command is received, if no call is in progress on channel 36, the recorder will begin recording a new call. If a call is already in progress on channel 36, that call will be terminated and a new call started.

2.2.4. Delete

Delete the current call in progress or previous call on a physical recorder channel.

Format:

<<CHANNEL_NUMBER::DELETE>>

Example:

<<24::DELETE>>

Description:

When this command is received, if no call is in progress on channel 24, the previous call on the channel will be deleted. If a call is in progress, it will continue to record until it is stopped, at which point it will be purged from the recorder’s call database within the next few minutes. Note that unless this API command is specifically requested by the customer, it will not be programmed in or available on the recorder.

2.2.5. Start (with Metadata)

Start recording on a given recorder channel and apply metadata to it.

Format:

<<CHANNEL_NUMBER::START::METADATA KEY::METADATA VALUE>>

Example:

<<16::START::CUSTOMER_NAME::Eventide, Inc.>>

Description:

When this command is received, if no call is in progress on channel 16, a new call is started, if a call is already in progress, it is allowed to continue. In addition, regardless of whether a new call is started or not, the value sent in “Metadata Value” will be written to the database field “Metadata Key” in the database record for the call. The Metadata field specified by “Metadata Key” must have already been created in the Recorder’s Configuration Manager under Recording -> Custom Fields, and be of a data type compatible with the value sent as “Metadata Value”. The Text sent as the Metadata Key must match exactly the name of one of the configured Custom Fields.

2.2.6. Stop (with Metadata)

Apply metadata to a call on a given channel and stop it.

Format:

<<CHANNEL_NUMBER::STOP::METADATA KEY::METADATA VALUE>>

Example:

<<8::STOP::CUSTOMER_NAME::Eventide, Inc.>>

Description:

If no call is in progress on channel 8, the command is ignored; otherwise, the metadata is applied and the call stopped. See Start (with Metadata) for more info about the Metadata Key and Value fields.

2.2.7. Break_Then_Apply (Metadata)

Break the current call, start a new one, and apply metadata to it.

Format:

<<CHANNEL_NUMBER::BREAK_THEN_APPLY::METADATA KEY::METADATA VALUE>>

Example:

<<125::BREAK_THEN_APPLY::CUSTOMER_NAME::Eventide, Inc.>>

Description:

If a call is in progress on the channel it will be stopped. Regardless of whether a call was in progress or not, a new call will then be started and the metadata included in the command string will be applied to it.

2.2.8. None

Apply metadata to the current/last call and perform no additional actions.

Format:

<<CHANNEL_NUMBER::NONE::METADATA KEY::METADATA VALUE>>

Example:

<<34::NONE::Foo::Bar>>

Description:

If no call is in progress, the metadata is applied to the most recent call that took place on channel 34. If no call has taken place on channel 34 since recorder start-up, the metadata is ignored. If a call is currently in progress, the metadata is applied to that call. No call stops or starts take place. This command can be sent multiple times with different Key/value pairs to set multiple custom fields.

2.2.9. Cache

Apply Metadata to the current/next call and perform no additional action.

Format:

<<CHANNEL_NUMBER::CACHE::METADATA KEY::METADATA VALUE>>

Example:

<<45::CACHE::Foo::Bar>>

Description:

If a call is currently in progress on the channel, the metadata in the command string is applied to it. If no call is currently in progress, the metadata is cached. The next call to start on this channel will get the metadata applied to it. If no more calls start on this channel before the recorder is powered off, the metadata will be discarded. In addition, if another CACHE command string is received by the recorder for this channel before call start, the old cached metadata will be discarded.

2.3. Metadata Notes

1. In addition to calls being started or stopped by the external program, the recorder channels will still respond to start/stop events from other configured methods. For example, it is acceptable to configure a channel to have calls starting and stopping due to VOX call detection and also provide additional start/stop events. Normally however, the recorder channels to be externally controlled will be configured to ignore all other call start sources and to obey only external sources, or they will be configured to use their normal internal methods for start/stop control, and the metadata feed will only be used to apply metadata to the calls. In some applications though, the hybrid approach is desirable and is available. In other systems, only CACHE or NONE events are sent to apply metadata to calls started and stopped via the standard VOX or signaling interfaces.

2. All command strings above are available with analog call sources. There is one caveat for digital call sources (T1/E1, ISDNBRI, PBX, etc.). Unlike an analog source, which always has data available to record (though it may simply be silence), on digital sources no data is available to record if no call is being sent along the signal path. Therefore, forcing a call start on a digital channel may not perform as expected if no corresponding signal is available to record. To work around this issue, the external application should only send a call start for a channel if it knows audio data is currently being sent on that channel. In addition, for these digital channels, it is preferable to send START events without metadata and then send the metadata via a NONE or CACHED event a few seconds later. This is because the recorder cannot force an immediate call start to make sure there is a call to which the metadata should be applied. This method allows the recorder to request a call start and wait for the data to begin to flow, and then apply the metadata when data is available. With analog sources, this is not necessary because the data is always “flowing” into the system regardless of the call states. With Digital sources, typically only the NONE, CACHE and DELETE commands are used and call control is based on presence or absence of data.

3. The command formats above are the defaults supplied by Eventide, however the formats can be altered and some of the behavior of the commands themselves can be altered.