4. Accessing Eventide NexLog via SOAP

4.1. Overview

This document requires you have the SOAP API Example Application (Part Number: 141250-01) that demonstrates access to Eventide’s NexLog server via Simple Object Access Protocol (SOAP) using a .NET client. If you do not, contact service@eventidecommunications.com to request this application.

The application demonstrates the following features:

• Logging into NexLog

• Retrieving channel names

• Retrieving channel information

• Retrieving call history

• Retrieving call metadata

• Starting and stopping recording

• Squashing a recording

• Setting channel metadata

4.2. Setting up Visual Studio 2012

The Demo was built as a WPF (Windows Presentation Foundation) application using Visual Studio Professional 2012. The only additional download required was the Extended WPF Tookit which provides the DateTimePicker control. This is available as described in the Supporting Information section, or may be downloaded via the NuGet Package Manager.

The WSDL is loaded into the project as a Service Reference. To create a Service Reference for your own project you can use the WSDL link in the Supporting Information section. It can be loaded into VS2012 via Project|Add Service Reference, and enter the link into the Address field.

The Demo is written in C#.

4.3. Source Files

MainWindow.xaml.cs

This module is created by VS when the project is created. It sets up the UI and is the coordinating code for the application.

Login.cs

This module manages the login dialog that appears when you start the app. It creates the client object which represents the WSDL document as a service reference.

SetMetadata.xaml.cs

This module manages the ‘Set Channel Metadata’ window.

NexLog.cs

This module encapsulates the service reference and is the only direct user of the reference. It provides methods for use by the other classes.

CookieBehavior.cs

This module encapsulates the manual re-injection of the session cookie into each outgoing HTTP packet. It is reusable and may be considered opaque after its initialization.

4.4. Expectations

The Expect100Continue setting configures how the HTTP session is handled. For details on this see: http://msdn.microsoft.com/en-us/library/system.net.servicepointmanager.expect100continue.aspx

The setting must be false to achieve compatibility with NexLog.

// Code Snippet
System.Net.ServicePointManager.Expect100Continue = false;
// disable expectations

4.5. Cookie Handling

The NexLog requires a session cookie to maintain the integrity of the session. By default, WPF applications do not handle cookie management automatically; the cookie has to be inserted into the outgoing HTTP. This functionality is encapsulated in class CookieBehavior. If this module is not installed then all SOAP operations after the initial login will fail.

// Code Snippet:
// See the CookieBehavior.cs module for details
_client.Endpoint.EndpointBehaviors.Add(new CookieBehavior());

4.6. Logging In

The code snippet shows the login method and the returned objects sessionKey and passwordExpire. Both of these are both unused as the CookieBehavior class handles the session key.

// Code Snippet
_client.login(txtUsername.Text, // text from controls
   txtPassword.Text,
   txtIPAddress.Text,
   out sessionKey, // unused
   out passwordExpire); // unused

4.7. Retrieving Channel Names

The getAllChannel() call returns an array of ChannelEntity objects, each describing a recording channel.

// Code Snippet
// Retrieve the channel names from NexLog
//
ServiceReference2.ChannelEntity[] channels = _client.getAllChannel();
foreach (ServiceReference2.ChannelEntity channel in channels)
{
_channelEntity[channel.name] = channel;
}

See the ChannelEntity object definition for a full description of the channel. A channel may be analog (ie, accepting an interface with POTS), or digital. This characteristic defines what the channel can and cannot do, and this will be outlined later in this document.

Note

NexLog systems with a large number of channels (>32) may not be queried in this way because the returned data can exceed the maximum 64K message size specified by WPF. For details on this, check the following link: http://blogs.msdn.com/b/drnick/archive/2006/03/10/547568.aspx

You can adjust the MaxBufferSize parameter or use the following code. Be aware, though, that the getChannelCount and getChannelByIndex calls are not implemented in all versions of NexLog.

// Code snippet
for (int ii = 1; ii <= _client.getChannelCount(); ii++)
{
ServiceReference2.ChannelEntity channel =
_client.getChannelByIndex(ii);
_channelEntity[channel.name] = channel;
}

4.8. Retrieving Call Data

A call is encapsulated by the MediaRecordEntity object. When a new channel is selected in the application it submits a query to NexLog to retrieve some of the most recent calls for that channel. The MediaRecordEntity includes a GUID which uniquely identifies the call. See NexLog::getRecordsForChannelName for details on how to build a query filter.

4.9. Applying Metadata

NexLog provides the ability to associate user-customized information with each call. The metadata field names and types are entered via the front panel or via Mediaworks Express, and the values of these fields (also called “custom fields”) are available in the MediaRecordEntity object (see Retrieving Call Data).

4.10. Call Breaks

A “call break” can occur when metadata is received by NexLog during a recording. Depending on the metadata “action” the call may be broken into one or more recordings on the NexLog, each recording being associated with its unique metadata. The .NET application shows how metadata can be applied to a recording and when to use a call break.

Three actions are specified, and the NexLog will choose on of them depending on the channel’s type and whether or not a recording is in progress.

The metadata actions are:

Action	Description
NONE	apply the metadata to the current recording
APPLY_BREAK	apply the metadata to the current recording, stop the recording and immediately start another
BREAK_APPLY	top the current recording, immediately start a new recording and apply the metadata to it
CACHE	cache this metadata and apply it the next time a call starts
DELETE	schedule the current recording for deletion
START	Start a new call and apply the metadata. This generally applies to analog audio sources only, although digital sources can be configured to accept this action
STOP	apply the metadata and stop recording

If a recording is in progress then the accepted actions are NONE, STOP, APPLY_BREAK, BREAK_APPLY and DELETE.

If a recording is not in progress then the accepted actions are NONE, START, CACHE and DELETE.

// code snippet
return _client.setChannelMetadata(channel,
      callHasMetadataStartAction,
      noCallInProgressAction,
      callInProgressAction,
      metadata);

4.11. Channel Recording Control

A NexLog may be fitted with an analog telephone interface. This kind of interface can be set to record at any time, even if a call is not in progress. Digital channels (E1/T1, SIP Trunk etc) can also be set to act in this way, although this usage is not common and the facility is not provided by the .NET application. Recording can be initiated with the “Record” button.

Either type of channel can be set to stop recording at any time; this action is invoked with the “Stop” button.

// code snippet
// Start and stop recording with a 2 second timeout
//
public ServiceReference2.RecordingStatus
startRecording(int channelNumber)
{
   return _client.startRecording(channelNumber, 2);
}
public ServiceReference2.RecordingStatus
   stopRecording(int channelNumber)
{
   return _client.stopRecording(channelNumber, 2);
}

4.12. Squashing a Channel

When a channel is put into “squashed” state, it is actively recording but the recording information is replaced with silence. This might be used when accepting credit card information or other confidential information.

// snippet
if (true == squash)
{
_client.recordDisable(channelNumber);
}
else
{
   _client.recordEnable(channelNumber);
}

4.13. Supporting Information

Extended WPF Tookit is at http://nuget.org/packages/Extended.Wpf.Toolkit

Your NexLog WSDL is at http://YourLogger/soap.fcgi?wsdl