6. NexLog Generic CAD API

6.1. Overview

The NexLog Generic CAD API provides a simple mechanism to allow CAD systems to inject data about call records into the NexLog database, where they are stored, archived, retrieved, and displayed along with the call records and the native metadata stored with the call. The Generic CAD API allows arbitrary additional metadata fields including call ids and incident id’s to be provided from the CAD system to the recorder. Users of the NexLog system can then choose to display and/or search based on these metadata values associated with the call records.

The NexLog Recording system has a facility for ‘Metadata Feeds’. A Metadata Feed is a configurable TCP, UDP, or Serial Input, configured to expect data in a given data format. The Metadata Feed framework allows the format of a given metadata feed to be programmatically defined in a configuration file on the recorder and can support a myriad of different input formats. The Generic CAD API is implemented as a specific realization of this more generalized feature. To use the NexLog Generic CAD API on a given recorder, a License for ‘Generic CAD API’ must be purchased from Eventide for the specific recorder. By purchasing this license, the end user will receive a license key to activate the Metadata Feeds recorder feature, the specific configuration file to load on the recorder to support the Generic CAD API data format, and the legal permission to utilize the feature on the recorder. The Generic CAD API licensed feature must be purchased and installed on a given recorder prior to using the Generic CAD API.

6.2. Initial Setup

To enable and configure the Generic CAD API on a given recorder, first log into the recorder’s Configuration Manager via a web browser as a user account with administrative access to the recorder. First, navigate to System->License Keys and add the license key for ‘Metadata Feeds’ if this has not already been installed. Next, under System->Configuration Files, find the Metadata Feeds configuration file and paste in the ‘Generic CAD API’ Configuration file provided when the feature was purchased. This will enable the feature with the default settings. See sections below about modifying default settings if required for your usage.

6.3. Transport Mechanism

The Generic CAD API allows ASCII formatted commands to be sent to the recorder in predefined formats to accomplish various tasks related to recorder metadata. By default, the Generic CAD API will expect these commands to be sent to the recorder as UDP on port 5000, but both of these settings are configurable. When using UDP, the recorder will expect to receive one full ASCII command per UDP datagram. To alter which port the recorder will listen on for commands, look near the top of the configuration file for a line which says

InputPort = 5000

This can be changed to any other available port that you wish the recorder to listen on for Generic CAD API Messages. Instead of listening on a UDP port, it is also possible to configure the Generic CAD API to listen on a TCP Port. To configure TCP Mode, change the line near the top of the configuration file from:

InputType = UDP

To:

InputType = TCP

The recorder will now listen on the configured port number as a TCP port instead of UDP. Unlike UDP, which is stateful, and each inbound UDP message can come from a different source, TCP is a stateful, connection based protocol. The Generic CAD API when configured in TCP mode will expect a single TCP connection to be made from the CAD system to its configured TCP port, and will expect ASCII commands to be sent to this TCP port. It is the CAD system’s responsibility to maintain the TCP connection, detecting when it is no longer connected, and reconnecting as needed. Multiple simultaneous TCP connections are not supported. Connecting an additional TCP connection will automatically disconnect any established connection.

In addition to TCP and UDP, the Generic CAD API can be configured to listen on a serial port instead of on a TCP or UDP port. To configure this mode, change the line near the top of the configuration file that says:

InputType = UDP

To:

InputType = Serial

And add in the additional required configuration lines immediately below. For example:

SerialType = n81
SerialBaud = 9600
SerialDevice = /dev/ttyS0

The SerialType configuration setting defined the parity, number of data bits, and number of stop bits for the serial connection, for example, N81, or E72. The SerialBaud configuration setting defines the baud rate to be used on the serial connection. Finally, the SerialDevice configuration setting tells the recorder which serial port to connect to the Generic CAD API for receiving commands. A standard NexLog has two serial ports, which are referenced as /dev/ttyS0 and /dev/ttyS1. If additional serial port add-in cards have been purchased and installed into the NexLog, then they can be accessed as /dev/ttyS2, /dev/ttyS3, etc.

6.4. Verification of Data Received

Generic CAD API can receive data over TCP, UDP, or Serial, but regardless of the transport mechanism used, the format of the data conveyed is identical. The Data format is ASCII text, so the commands are human readable over the transport layer. Each command is sent followed by a newline (‘n’) character, so each command is a separate line. Commands will have varying number of parameters, and the meaning of those parameters differs depending on the command, but the command format is always the same. The example below is a 4 parameter command; though various numbers of parameters are possible depending on the command.

<Command:Param1:Param2:Param3:Param4>\n

Commands open with a left bracket character (‘<’), and close with a right bracket character (‘>’). The command itself and all its parameters are separated by colon (‘:’) characters. If a parameter needs to contain a right bracket (‘>’) or a colon (‘:) character, these are reserved characters and need to be escaped as to not interfere with processing. To insert these characters into parameters escape them as \COLON and \RIGHTBRACKET (a backslash followed by the actual name of the character all in uppercase).

Upon receiving a command, the API will attempt to parse it. If the format matches a valid command, the API will respond with the ASCII text

OK\n

If the command is not successfully parsed, no response will be sent. Note that the OK response verifies only that the command was successfully parsed and passed on to the rest of the system. It does not guarantee that the command actually had its desired effect. For example, if a command tells the system to apply data to a given metadata field, and that metadata field does not exist, the command will parse successfully and return OK, but its actual result will be to raise an alert on the recorder warning about the missing metadata field.

6.5. API Command Data Format

In the NexLog Configuration Manager, you can verify what data has been received by the Generic CAD API by going to Utilities -> Metadata Feeds and selecting Generic_CAD_API and clicking View Feed. From this screen, you can View Input Logs for the Generic_CAD_API metadata feed which will show all recent data received by the configured input port (whether UDP, TCP, or Serial). This can be useful to verify that the data is being properly sent and received. It is also possible from this screen to View Processing Logs, which shows the received messages color coded and describes how they are being extracted and processed by the Generic CAD API. A command is displayed in the Processing Logs once it is successfully identified and parsed by the API, whereas the Input Logs show every character received, regardless of proper formatting, etc.

6.6. Physical Channel Commands

There will be multiple groups of commands described in this document. The first group to be handled are the commands that reference a physical channel on the recorder. Every NexLog recorder has a certain number of channels installed and configured, up to a maximum of 255 channels. For example, inserting a 24 channel Analog board into the recorder will add 24 channels to the recorder, each of which is hardware defined by two pins on the analog card; when audio is sent to those pins, they record on the hard coded corresponding recorder channel. In addition to Analog, Digital PBX, and T1/E1 tapping boards, channels can belong to ‘Virtual’ boards that are installed and licensed, such as ScreenAgent channels, and VoIP channels. Though there are not physical pins and wires in these configurations, each channel number is still hard coded and defined by a single input, for example a particular IP and Port, or a particular PC Workstation. Physical channel commands allow metadata to be assigned to the current call recording on a known physical channel. Physical channels are the simplest available commands for attaching metadata to recordings and are most useful when the physical recording channel has a one to one correspondence with the CAD system. For example, if individual channels on the recorder are recording audio feeds from individual CAD positions and the CAD system sends per-position metadata, or when individual recorder channels are recording audio feeds from individual Trunks, and the CAD system sends per-trunk metadata. When this correspondence does not exist due to the way the recorder and CAD system are configured and connecting, physical channel commands cannot be used, and other types of command described later in this document should be used instead.

Physical Channel Commands have the following format:

<Command:ChannelNumber:Field1:Value1:Field2:Value2:Field3:Value3: .....Field8:Value8>

Though they can have less than 8 Field/Value fields if less metadata needs to be attached to the call.

The Following Physical Channel Commands are available:

ATTACH: Attach the given metadata to the current recording call on the physical channel. If No call is currently recording, attach it to the most recent call to complete on the channel. Note that if a call record already has a value in a given field that is included in the command, that field will be overwritten with the new value.

ATTACH_OR_CACHE: Attach the given metadata to the current recording call on the physical channel. If No call is currently recording, attach it to next call to start on the channel

BREAK_ATTACH: If a call was started using a CAD API START command and is recording then it will trigger a call break, start a new call, and attach metadata to this new call. If a call was started without using the CAD API START command (example: triggered by calls based on the different detect type of the channel) and is recording, then it will not trigger a call break but attach the metadata to the current call. If no call is currently recording on the channel then BREAK_ATTACH will start recording a new call and attach the specified metadata to this new call.

BREAK_ATTACH_OR_CACHE: If no call is currently recording on the channel, it will attach the metadata to the next call to start on the channel, otherwise it will perform the same action as BREAK_ATTACH.

Under normal circumstances, the recorder will start and stop recordings based on its own internally configured criteria, for example, VOX levels and hold times, or Tip/Ring voltages, and the CAD API will be used only to attach metadata to existing calls (and possibly break a call into multiple pieces so different metadata can be attached to different segments). It is possible, however, with certain recorder configurations, for the Generic CAD API to be used to control the starting and stopping of recording on the physical channel. These commands are only available for physical channels. Note that in for these commands to work on a given channel, the channel itself must be configured to allow scripted control and not to use the available internal mechanisms to control recording. The following additional call control commands are available for physical channels:

START: If No call is in progress on the physical channel, begin recording, and attach the metadata given in the command to the new call. If a call is already in progress, attach the metadata to it

START_OR_BREAK: If No call is in progress on the physical channel, being recoding and attach the metadata given in the command to the new call. If a call is already in progress, stop it, start a new call, and attach the metadata to it

STOP: If no call is in progress, attach the metadata to the most recent call on the channel, otherwise stop recording immediately and attach the given metadata to the recently stopped call.

In addition to attaching metadata to call records and starting, stopping call records, there is one additional command which creates a standalone call record with no audio to store an event. This command could be used, for example, to insert a received text message into the recorder, or to insert a note about the console position going off line, or a new agent logging into it, etc.

EVENT: Regardless of whether or not a call is present on the channel, create a call record with no duration or audio and place it at the current time on the physical channel. This command is especially useful with the ANNOTATION metadata field to create standalone annotation pins on the timeline. For example, an Event could be given an annotation text, ChannelName, Caller_ID, and CallType of ‘TEXT’ for a text message arriving at the CAD position. Unlike the other physical channel messages, this one is useful even if there is no one-to-one physical channel mapping, the messages can be hard coded to a specific physical channel such as ‘1’, and then use the ChannelName metadata field to make sure it appears where you want it to. Since there is no actual audio, the physical channel is not important in most cases.

While the ChannelNumber given in the physical channel commands can be the actual physical channel number (for example 12 for the 12th channel on the recorder), using this mechanism requires the CAD system to know which position or trunk, etc., is wired to which physical channel number on the recorder, which would require the CAD side of the integration to be altered per-site to put in the matching recorder channel numbers for the position, trunk, etc. To work around this issue, the Generic CAD API allows a mapping table to be configured on the recorder from a given value to a channel. For example, the CAD system could send as the channel ‘POSITION 1’, or ‘555-1212’ or ‘911 Trunk 12’, and when the Generic CAD API configuration file is loaded onto the recorder, it can be altered to contain the mappings from these tags to actual physical channel numbers. Again, it is important to note, this can only be done when there is a one-to-one correspondence between the tag and a physical channel, e.g. ‘POSITION 1’ is Channel 43. If CAD commands are being sent for a given position, but the recorder is recording Trunks, there is not a defined relationship that ‘Position 1’ is Channel X, calls for position 1 could record on any channel, and in this configuration, physical channel commands cannot be used, and more advanced commands described in sections below must be used instead.

To configure a mapping from CAD supplied tags to physical channel numbers, edit the Generic CAD API configuration file loaded onto the recorder. Look for the section:

[ChannelMap]
MapType = Lookup
Map = 1 <- Example1
Map1 = 2 <- Example2

The supplied example mappings would map the tag Example1 to channel 1 and Example2 to channel 2. Regardless of the ChannelMap, if an integer from 1-255 is sent as the channel number in a Generic CAD API command, then the corresponding physical channel ID will automatically be used. The mapping only needs to be supplied if alternative tags are to be used. The two example entries can be modified to suit your purposes, and additional Map entries can be added, e.g. Map2 = 6<-Position 1 would add a new mapping from the tag ‘Position 1’ to channel 6. Note that each Map value should be unique and in ascending order without any gaps, Map, Map1, Map2, Map3, etc. but otherwise the number appended to the word map have no semantic meaning. The format is MapX = <channel ID> <- <Tag Name>

After the command and the physical channel number come between zero and eight Field/Value pairs of metadata to attach to the call. (Though zero would only be useful in the case of a START or STOP command, as attaching no metadata to a call and taking no action would not do anything, and not be a command worth sending). The field should be the name of a recorder metadata field, and the value is the value you wish to place in that metadata field for the call record referenced by the command. Generic CAD API commands can reference any metadata field that has been added to the recorder via the NexLog Configuration Manager, including default fields that are shipped with every recorder, such as Caller_ID, CallType, and DTMF. In addition to filling in existing metadata fields, Generic CAD API based integrations can utilize arbitrarily named additional metadata fields defined by the CAD integrator / API user. It is recommended that these metadata fields be added to the NexLog recorder at the time the Generic CAD API configuration file is loaded onto the recorder. If the CAD system attempts to apply metadata to a field that has not been created on the recorder, the metadata will not be attached, and an alert will be raised on the recorder about the mismatch between configured fields and the fields expected by the integration.

The following built-in and default metadata fields have special meaning:

CHANNELNAME: The name of each physical channel can be configured in the NexLog Configuration Manager. Each call on that physical channel will default to the CHANNELNAME of the physical channel it was recorded on. However, using the Generic CAD API, the CHANNELNAME can be modified from this default to provide an alternate name. For example, it might be desired that while the physical connection is ‘Position 1’, to set the CHANNELNAME for each call to ‘Position 1 - Admin’ or ‘Position 1 - Emergency’ if the position takes both administrative and 911 calls. The CHANNELNAME is the primary way that calls are searched by users of the NexLog system and also the names available in the browse tree in the Browse tab in MediaWorks DX.

CALLER_ID: This field is used, not only for actual caller ID, but is generally the primary ‘Calling Party’ field on NexLog and is a default field in MediaWorks DX and the Front Panel.

DTMF: This field is used not only for parsed DTMF tones, but is generally the primary ‘Called Party’ field on NexLog and is a default field in MediaWorks DX and the Front Panel.

CALLTYPE: The CALLTYPE of each physical channel can be configured in the NexLog Configuration Manager. Each call on that physical channel will default to the CALLTYPE of the physical channel it was recorded on. However, using the Generic CAD API, the CALLTYPE can be modified from this default to provide an alternative CALLTYPE. For example, a channel might be configured to mark the call type as ‘PHONE’ or ‘POSITION’, but it may be desirable to mark calls as being of type ‘FIRE’ or type ‘EMERGENCY’. CALLTYPE is configured to display an icon (if available) as opposed to the actual text in MediaWorks DX. The icon associated with a given text string is configured in the NexLog Configuration Manager under Recording->Custom Fields. While any metadata field can be configured to use icons, CALLTYPE is special in that not only do its icons appear in the CALLTYPE column in the call grid, but there is an option in MediaWorks DX to turn on CallType icons in the timeline, where the configured icon is shown on top of the call record in the timeline as well.

ANNOTATIONS: Annotations are snippets of text that occur at a specific time during the call. Unlike other metadata fields, where a subsequent update will overwrite old values, a single call record can have multiple annotations. MediaWorks DX will show annotations as pins on calls where the text they contain can be seen on mouse-over. The mouse-over effect will also happen automatically during playback to create an annotation on the call, enter the text you wish to annotate onto the call into this field

ANNOTATION_TYPE: Only valid if the command also has ANNOTATIONS. If ANNOTATIONS is present, and ANNOTATION_TYPE is not, ANNOTATIONS default to type SYSTEM which means they display as a gear icon on the MediaWorks DX timeline, and are not user editable/deletable. If ANNOTATION_TYPE is set to USER, then they appear as a pin in the timeline and are editable / deletable by users. These are currently the only valid annotation types, though more may be added in future NexLog firmware release.

ANNOTATION_TIME: Only valid if the command also has ANNOTATIONS. If ANNOTATIONS is present and ANNOTATIONS_TIME is not, the ANNOTATION time defaults to the current recorder time when the command was received. If present ANNOTATION_TIME should contain a UTC timestamp, in the format of number of milliseconds since UNIX Epoch.

LOCATION: This metadata field is only available if a GeoLocation license is installed on the recorder. The LOCATION metadata field must be populated with data in a specific format. The valid format is (latitude,longitude) including the parenthesis. The LOCATION metadata field represents the GPS coordinates from which the call originates. If present, and the necessary licenses are loaded on the recorder, this allow the recorder to display the call as a pin on a map, and also allows searching for calls based on location (The user can draw a shape on the map to find calls that occurred inside of it).

In addition to these fields, any additional desired metadata fields can be created and used. Don’t forget to escape ‘>’ and ‘:’ characters in values as described above. Up to eight key/value pairs can be provided, or they can be left out. If left out, leave them blank, but still provide the correct number of colons in the command. Note also that while most fields are created in the Configuration Manager as Text fields, meaning they can contain any ASCII (or UTF8) data, it is possible to create integer only fields, where if non integer data is applied to them, the insert will fail and the recorder will raise an alert.

Examples:

<ATTACH:43:CALLTYPE:FIRE:CALLER_ID:(201)-555-1212:LOCATION:(40.8529,-74.0421)::::::::::>\n

Would attach metadata to the current call on channel 43 (or most recent call on 43 if one is not currently in progress.) CallType, Caller_ID, and Location fields are set. Note the extra colons for unused metadata fields:

<ATTACH_OR_CACHE:Position_1:CALLER_ID:(201)-551-1212:INCIDENT_ID:160628-43::::::::::::>\n

Would attach metadata to the current call on the channel mapped to the tag ‘Position_1’ in the Generic CAD API configuration file, or cache it for the next call to start on the channel if no call is currently in progress. The metadata attached will be a Caller_ID, and an INCIDENT_ID field from the CAD system which is not a standard NexLog field, but has been added to the recorder using the Configuration Manager.

One additional Physical Channel Based Command is available:

ATTACH_AT_TIME: Attaches the metadata to the call that was in progress at a given time on the given physical channel. The first parameter is the physical channel ID or a tag that is configured to map to a physical channel id in the Generic CAD API configuration file on the recorder. The second parameter is the time, in seconds since UNIX Epoch (UTC). After that are up to eight field/value pairs to set.

<ATTACH_AT_TIME:22:1467909534:INCIDENT_ID:2016-444::::::::::::::>

Would set the INCIDENT_ID metadata field to 2016-444 for the call that was in progress at 1467909534 UNIX Epoch time (which is July 7, 2016 at 16:38:54 UTC) on physical channel 22. If no such call exists, the metadata is attached to the most recent call to end before the given time on the physical channel.

6.7. Non-Physical Channel Commands

Non-physical channel commands differ from physical channel commands in that they do not include a physical channel number (or physical channel mapping tag) and cannot perform actions on the call (such as call breaks, starting, or stopping calls), only attach metadata. They work, not by specifying ‘The Current Call on Channel X’, to act upon, but by specifying some condition that must be met by a call in order for the metadata to be attached for it. For example, a command could say “Attach this metadata to all calls that have Caller_ID=(201)-555-1212.” At the point the command is run, any call that currently meets the given criteria will have the metadata attached. Note that unlike physical channel commands, a non-physical channel command can act on more than one call record if more than one call record meets the given criteria. Non-physical channel commands will only affect calls that are no more than 24 hours old. Any call less than 24 hours old that matches the given criteria will be affected.

Non-physical channel commands can be used to attach data to call records based on the metadata they already have attached to them, via other interfaces, including ANI/ALI, SIP Signaling, MF Tones, etc. The call must already have the matching values at the point in time when the command is sent. There are two variants of the non-physical channel command:

ATTACH_ON_MATCH: Attaches the metadata to all calls from the past 24 hours that match the given criteria

ATTACH_ON_MATCH_1: Attaches the metadata to only the call that matches the given criteria with the most recent start time (must be within 24 hours).

The first two parameters for a non-physical channel command are the metadata field and value to match on, the rest (up to eight) are the metadata to attach, e.g.:

<ATTACH_ON_MATCH_1:CALLER_ID:2015551212:INCIDENT_ID:2016-4432::::::::::::::>

Would set the INCIDENT_ID metadata field to 2016-4432 to the most recent call on the recorder that has the CALLER_ID metadata field set to 2015551212. The value to match must be exact, and is case sensitive.

One additional command is available:

ATTACH_ON_MATCH_AT_TIME: Attaches the metadata to the call that was in progress at a given time that matches the given field/value. The first parameter is the time, in seconds since Unix Epoch (UTC). The second and third parameters are the field and value to match, and after that are up to 8 field/value pairs to set. This command is most useful for attaching to a call on a given ChannelName at a given time regardless of the physical channel. For example:

<ATTACH_ON_MATCH_AT_TIME:1467909534:CHANNELNAME:Position12:INCIDENT_ID:2016-444::::::::::::::>

Would set the INCIDENT_ID metadata field to 2016-444 for the call record that was in progress at 1467909534 UNIX Epoch time (which is July 7, 2016 at 16:38:54 UTC) which also had the ChannelName set to ‘Position12’, regardless of what physical channel the call was recorded on. If no such call exists, the metadata will be attached to the most recent call to complete before the given time that meets the given criteria.

6.8. Text Call Commands

Text Call commands can be used to attach text messages to text call records. The following format applies for both Physical and Non-Physical Channels:

<command: ChannelNumber: Sender’s Name: Text Body>

ATTACH_OR_CACHE_TEXT: Attach the given text body to the current recording text call on the physical channel. If no text call is currently recording, attach it to the next text call to start on the channel. This option is intended for use with analog channels. Use the START commands to start recording calls on analog channel to create a call for this text record. Either the STOP command or VOX timeout can be used to end text calls for analog.

ATTACH_OR_START_TEXT: Attach the given text body to the current recording text call record on a non-physical channel. If no text call is currently recording, start a text call on the given channel and attach it. This command is intended for use with RTP channels. For RTP, there is no stop command and the RTT Timeout set for the channel is what will be used instead.

For example, for analog channels:

<START:42::::::::::::::::::>
<ATTACH_OR_CACHE_TEXT:42:A:What are you doing now?>
<ATTACH_OR_CACHE_TEXT:42:B:I'm watching TV.>
<STOP:42::::::::::::::::::>

And for RTP:

<ATTACH_OR_START_TEXT:57:A:What are you doing now?>
<ATTACH_OR_START_TEXT:57:B:I'm watching TV.>

6.9. Agent Login/Workstation Tagging Commands

Agent_(Login/Logout/Info) Commands can be used to log an agent into the Client Activity Table to enable workstation tagging on specified channels. Each of these actions have the following format:

<AgentAction:AgentId:ChannelNo:ClientAddress:Field1:Value1:Name2:Value2:…Field8:Value8>

AGENT_LOGIN: Log the Agent into the Client Activity Table and attach the given metadata to the specified channel.

AGENT_LOGOUT: Log the Agent out of the Client Activity Table.

AGENT_INFO: Change the metadata to be attached to the calls that start on the specified channel for an agent already logged into the Client Activity Table.