Overview

3VR Appliances and Enterprise Appliances support several APIs which can be accessed using web services. This has two key advantages for those writing client applications:

1. These APIs can be used by client applications remotely across a network.

2. Client applications can be written in almost any programming language.

3VR's Web Services APIs are based on standard protocols and formats such as HTTP, XML, REST, and SOAP which are supported in all major programming environments. In addition, the 3VR Web Services SDK contains sample code and support libraries for several popular programming languages.

In total, the 3VR Web Services API is comprised of 4 APIs:

• The 3VR REST API gives client programs access to camera information, system settings, health monitoring data, video, images, and more with RESTful HTTP requests

• The 3VR External System Activity API (SOAP) is used by client programs to add events to the 3VR system's database. These include bridges to Point of Sale (POS) systems, access control systems and transaction recording systems. The External System Activity API uses a Simple Object Access Protocol (SOAP) binding that lets client applications define event types and metadata types and inject individual events.

• The 3VR External Query API lets client programs query for specific events in the set of events recorded by the 3VR system. 3VR provides RESTful access to some of the most common queries, but client programs can also send custom XML-based queries to return only events of interest. Regardless of which method is chosen, events are returned in XML format and use URLs to reference associated images and videos.

• The 3VR Live Query API allows client programs to receive a continuous stream of new events matching an XML query. Clients can choose feeds based on the type of event or whether the event has a particular alert associated with it. The Live Query API uses the same XML predicate request as the External Query API, except the appliance will returns a continuous stream of events instead of a fixed set.

Application developers may use one API or a combination of APIs depending on their needs.

What does an Event mean?

3VR's "Searchable Surveillance" model is built around the creation of events. An event represents an action detected by the 3VR system, such as motion observed by a camera or the detection of a specific face. An event consists of two main components:

• Event data: pieces of information such as the date, camera number, transaction ID, etc.

• Event video: a video clip from the time when the event occurred.

Each event captured by the 3VR system is represented in OpCenter by an event card. Event cards are labeled with the type of event, the date and time the event card was created, and other information about the event.

The simplest event type is a Motion event. Motion events are created when the system detects movement in a camera's field of view. All motion event cards contain the following elements in storyboard view:

• Images: each motion event card displays up to three still frames from the event:

• Camera number and name: the number and name of the camera that captured the motion event.

• Event start time: the time that motion was first detected by the camera.

• Event duration: the length of time continuous motion was detected.

In addition to basic video recording, events can be generated by integration with external systems (e.g. transaction, access control, POS, etc.) and analytics plug-ins.

Choosing the Right API

Before embarking on a project using a 3VR API, application developers should carefully review each API's description and sample code to ensure they have selected the correct API(s) for their purposes. The following guidelines apply:

• To create events on the 3VR appliance, use the 3VR External System Activity API

• To request and obtain events from the 3VR Appliance that match certain criteria (date, camera, event type, etc.) use the 3VR External Query API.

• To request and obtain a continuous stream of events matching a query, use the 3VR Live Query API.

• To request information about a 3VR Enterprise Appliance, a single appliance, a camera, or to obtain video or images from a particular camera, use the 3VR REST API.

There are two approaches to developing with the 3VR API: you can either work with the API directly using libraries provided in your programming language of choice, or use 3VR's helper code provided for the language in which you are programming. Both approaches are supported, and the approach you choose will depend on your particular circumstances.

Even if you are writing directly to your language's interfaces, you may find it useful to review the helper code. The source code to the helper code is included in the SDK.

What’s in the SDK?

This manual is associated with a Software Development Kit that has useful tools for programming with 3VR Web services. These include specification files, such as XML schemas, WSDL files, library bindings, source code, and samples of real applications built using these APIs. Also included is a copy of the API documentation in PDF form.

Structure of the API Documentation

3VR's API documentation contains sections for each of the individual APIs. All users should read this Overview and the "Getting Started" section, and then proceed to the documentation for their API of choice.

All of the API-specific sections contain information on the format of the request to the appliance and what to expect in return.

The 3VR External System Activity API and the 3VR External Query API also include sample code to demonstrate the format of the XML request predicate. The 3VR External System Activity API currently includes examples in C# and Java. The 3VR External Query API has examples in Java and Python. Contact your 3VR representative if you are interested in writing client code in other languages.

The final section contains reference material on the structure of XML-formatting for use in specifying queries and processing the events returned from queries.

Getting Started

Enabling Web Services

A 3VR VIP Appliance or Enterprise Appliance must have web services enabled in order to accept incoming messages. Enable web services with the following steps:

1. Launch 3VR System Manager.

2. In the Configure panel of System Manager, right-click the name of the appliance and select Start Web Services.

   

3. A pop up will appear indicating that web services is now running.

Enabling Demand Video Recording

If you plan to create events, set the Enable Demand Video Recording setting to Yes for each camera that will have generic events. This setting will buffer video so it is available for events even if there is not any current motion.

3VR REST API

The 3VR REST API gives client programs access to camera information, system settings, health monitoring data, video, images, and more with HTTP GET requests.

Authentication

The 3VR REST API uses HTTP Basic Authentication and validates against an appliance’s users. This requires an ’Authorization: Basic’ header in the request followed by a base64 encoded user name and password. This request header is case sensitive and must be passed with every request. The format for the user name and password is username:password. As an example, encoding ‘username:password’ to base64 results in ‘dXNlcm5hbWU6cGFzc3dvcmQ=’, and the request header would be the following:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

The server will also provide the challenge required for browser authentication. To test in a browser, navigate to a route and enter a valid user name and password in the dialog that’s displayed. The browser will then handle the authentication call.

All permissions, password constraints, authentication attempt limits, and inactivity limits for users are respected. If a user does not have access to an appliance, channel, view, etc. that information will not be returned in the response. When authentication fails the server will respond with a 401 HTTP status code and a JSON object in the body that includes the ‘AuthenticateResponse’ and a ‘Message’ describing the error. For example:

{ "AuthenticateResponse": "PasswordIncorrect", "Message": "Invalid user name or password" }

The following table lists the possible responses:

Port

The 3VR REST API runs on port 8080 and uses SSL, so the server can be accessed via:

https://hostaddress:8080

All exchanges are secured using HTTP BASIC authentication. The user names and passwords must match users that have been added to the 3VR system in System Manager.

Sample Request API

This sample displays the structure of a GET request to an appliance using the 3VR REST API.

In this example, we are requesting a list of system settings, but requests for different information may be made by modifying the path of the request URL (shown in bold text in the following example).

import urllib2, sys
def auth(hostname,username,password):
url = “https://%s:8080/” % (hostname)
password _ mgr = urllib2.HTTPPasswordMgrWithDefaultRealm()
handler = urllib2.HTTPBasicAuthHandler(password _ mgr)
opener = urllib2.build _ opener(handler)
urllib2.install _ opener(opener)
password _ mgr.add _ password(None, url, username, password)
def get _ settings(hostname):
url = "https://%s:8080/settings" % (hostname) #url path to request settings
try:
req = urllib2.urlopen(url)
return req.read()
except urllib2.HTTPError, e:
print "HTTP error: %s" % e.code
except Exception, e:
print e
return ""
if _ _ name _ _ == "_ _ main _ _":
try:
hostname = sys.argv[1]
except:
print "usage: settingsAPI.py [IP address or hostname]"
sys.exit(1)
auth(hostname,"techrep","3MeDeee")
settingsxml = get _ settings(hostname)

Headers and Responses

The information below will apply to most 3VR REST API routes. 3VR is in the process of unifying and normalizing its API, so the 3VR REST API routes marked with an asterisk (*) are those still in need of updating. For now, their response will be in XML and they will not take the 'Accept' request header, but will do so in the future.

The default response of all routes will be formatted as JSON objects except for the channel image and video routes.; images routes will return an image, see the routes below for more details. The ‘Accept’ request header allows specifying the desired content type to be returned. For example:

Accept: application/xml
Accept: application/json

Please note most browsers will include application/xml in the request header by default, so for debugging purposes an accept argument in the query string may be required to request a JSON formatted response. For example, when retrieving the list of appliances in JSON format using a browser, access the following URL:

https://hostaddress:8080/appliances?accept=application/json

3VR REST API Routes

/appliances

https://[IP address or hostname]:[port]/appliances

Options

?regions=true if included, the returned list of appliances will be arranged in regions

Sample XML Response

<ArrayOfApplianceInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ApplianceInfo>
<Id>1</Id>
<Name>3VR Enterprise Appliance</Name>
<Address>10.100.2.22</Address>
<MachineType>EnterpriseServer</MachineType>
<TimeZoneKey>Pacific Standard Time</TimeZoneKey>
<TimeZoneOffset>480</TimeZoneOffset>
<Created>0001-01-01T00:00:00</Created>
<Updated>2012-07-26T00:42:04</Updated>
<VideoStart>0001-01-01T00:00:00</VideoStart>
<SyncDate>2012-07-02T11:00:14</SyncDate>
<ObjectType>appliance</ObjectType>
</ApplianceInfo>
<ApplianceInfo>
<Id>2</Id>
<Name>Lake Merritt Branch</Name>
<Address>10.100.2.202</Address>
<MachineType>Integrated</MachineType>
<TimeZoneKey>Pacific Standard Time</TimeZoneKey>
<TimeZoneOffset>480</TimeZoneOffset>
<Created>2011-04-26T18:37:30</Created>
<Updated>2012-07-27T08:56:51</Updated>
<VideoStart>2011-04-26T18:46:35</VideoStart>
<SyncDate>2012-07-27T08:56:51</SyncDate>
<ObjectType>appliance</ObjectType>
</ApplianceInfo>
</ArrayOfApplianceInfo>

Sample JSON Response

[
{
Id: 1,
Name: "3VR Enterprise Appliance",
Address: "10.100.2.22",
MachineType: "EnterpriseServer",
TimeZoneKey: "Pacific Standard Time",
TimeZoneOffset: 480,
Created: "/Date(-62135568000000)/",
Updated: "/Date(1343549702000)/",
VideoStart: "/Date(-62135568000000)/",
SyncDate: "/Date(1341252014000)/",
ObjectType: "appliance"
},
{
Id: 2,
Name: "Lake Merritt Branch",
Address: "10.100.2.202",
MachineType: "Integrated",
TimeZoneKey: "Pacific Standard Time",
TimeZoneOffset: 480,
Created: "/Date(1303868250000)/",
Updated: "/Date(1343673311000)/",
VideoStart: "/Date(1303868795000)/",
SyncDate: "/Date(1343673311000)/",
ObjectType: "appliance"
}
]

/health

https://[IP address or hostname]:[port]/health

Sample XML Response

<?xml version="1.0" ?>
<ArrayOfHealthAlertInfo xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<HealthAlertInfo>
<DisplayLabel>Camera or Camera Connection Failure</DisplayLabel>
<Id>3</Id>
<StartTime>2012-06-20T11:24:10</StartTime>
<EndTime>2012-07-27T04:03:55</EndTime>
<Message>Camera '1. Shipping Room' is not sending video.</Message>
</HealthAlertInfo>
</ArrayOfHealthAlertInfo>

/enterprisehealth

https://[IP address or hostname]:[port]/enterprisehealth

Sample XML Response

<ArrayOfEnterpriseHealthAlertInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<EnterpriseHealthAlertInfo>
<ApplianceId>2</ApplianceId>
<ApplianceName>Lake Merritt Branch</ApplianceName>
<ApplianceAddress>10.100.2.202</ApplianceAddress>
<DisplayLabel>Camera or Camera Connection Failure</DisplayLabel>
<Id>6</Id>
<StartTime>2012-06-11T22:32:45</StartTime>
<EndTime>2012-07-27T15:03:55</EndTime>
<TriggerTime>2012-06-11T23:32:45</TriggerTime>
<Message>Camera '7. Mercado' is not sending video.</Message>
</EnterpriseHealthAlertInfo>
<EnterpriseHealthAlertInfo>
<ApplianceId>2</ApplianceId>
<ApplianceName>Lake Merritt Branch</ApplianceName>
<ApplianceAddress>10.100.2.202</ApplianceAddress>
<DisplayLabel>Camera or Camera Connection Failure</DisplayLabel>
<Id>7</Id>
<StartTime>2012-06-11T22:32:45</StartTime>
<EndTime>2012-07-27T15:03:55</EndTime>
<TriggerTime>2012-06-11T23:32:45</TriggerTime>
<Message>Camera '6. Caja' is not sending video.</Message>
</EnterpriseHealthAlertInfo>
</ArrayOfEnterpriseHealthAlertInfo>

/appliancemetadata*

https://[IP address or hostname]:[port]/appliancemetadata

Sample XML Response

Sample Response XML
<InfoCollectionOfMetadataInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Infos>
<MetadataInfo>
<Guid>d4fd02e5-d035-4d7e-9aa4-2535a561a748</Guid>
<Name>Custom Text Field</Name>
<Value>Test Value</Value>
</MetadataInfo>
<MetadataInfo>
<Guid>d4fd02e5-d035-4d7e-9aa4-2535a561a748</Guid>
<Name>Custom Number Field</Name>
<Value>12</Value>
</MetadataInfo>
</Infos>
</InfoCollectionOfMetadataInfo>

/settings*

https://[IP address or hostname]:[port]/settings

Sample XML Response

<InfoCollectionOfSettingDefinitionInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Infos>
<SettingDefinitionInfo>
<Id>1</Id>
<Name>AdminEMail</Name>
<Category>Email</Category>
<ChannelId>0</ChannelId>
</SettingDefinitionInfo>
<SettingDefinitionInfo>
<Id>2</Id>
<Name>AllowLocalCaseManagement</Name>
<Category>General</Category>
<ChannelId>0</ChannelId>
</SettingDefinitionInfo>
<SettingDefinitionInfo>
<Id>3</Id>
<Name>BackupMedia</Name>
<Category>General</Category>
<ChannelId>0</ChannelId>
</SettingDefinitionInfo>
</SettingDefinitionInfo>
...
</Infos>
</InfoCollectionOfSettingDefinitionInfo>

/settingvalue*

https://[IP address or hostname]:[port]/settingvalue

Sample XML Response

<InfoCollectionOfSettingValueInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Infos>
<SettingValueInfo>
<Id>20</Id>
<Value>false</Value>
<ComponentId>5</ComponentId>
</SettingValueInfo>
</Infos>
</InfoCollectionOfSettingValueInfo>

/channelinfo*

https://[IP address or hostname]:[port]/channelinfo

<InfoCollectionOfChannelInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Infos>
<ChannelInfo>
<Name>Street View</Name>
<Number>4</Number>
<Id>19</Id>
<ChannelDriverName>GenericIPCameraDriver</ChannelDriverName>
<PtzState>2</PtzState>
<IsActive>false</IsActive>
<ChannelType>3</ChannelType>
</ChannelInfo>
<ChannelInfo>
<Name>Classroom</Name>
<Number>5</Number>
<Id>20</Id>
<ChannelDriverName>GenericIPCameraDriver</ChannelDriverName>
<PtzState>2</PtzState>
<IsActive>false</IsActive>
<ChannelType>3</ChannelType>
</ChannelInfo>
...
</Infos>
</InfoCollectionOfChannelInfo>

/hosts

https://[IP address or hostname]:[port]/hosts

Sample XML Response

<ArrayOfHostsInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.
w3.org/2001/XMLSchema">
<HostsInfo>
<Label>Lake Merritt Branch</Label>
<Id>2</Id>
</HostsInfo>
<HostsInfo>
<Label>Mission District Branch</Label>
<Id>3</Id>
</HostsInfo>
</ArrayOfHostsInfo>

/person/*

https://[IP address or hostname]:[port]/person/

Sample XML Response

<?xml version="1.0" encoding="utf-8"?> <ThreeVRDbSync version="7.0" sourceSystem="">
<Persons>
<Person primarykey="Id">
<simplefield name="Id" value="1"/>
<simplefield name="FirstName" value="John"/>
<simplefield name="LastName" value="Smith"/>
<simplefield name="LastSeen" value="2013-03-02T21:22:32-05:00"/>
<simplefield name="FirstSeen" value="2013-03-02T21:22:32-05:00"/>
<simplefield name="UseForAutoMatch" value="false"/>
<complexfield name="Group">
<values>
<value>
<simplefield name="objectName" value="Imported People"/>
<simplefield name="Description" value="Imported People"/>
<simplefield name="AutoMatchType" value="UsePersonAutoMatchSetting"/>
</value>
</values>
</complexfield>
<image format="jpeg" width="303" height="300">
[IMAGE DATA]
</image>
</Person>
<Person primarykey="Id">
<simplefield name="Id" value="2"/>
<simplefield name="FirstName" value="Julie"/>
<simplefield name="LastName" value="Smith"/>
<simplefield name="LastSeen" value="2013-03-02T21:22:33-05:00"/>
<simplefield name="FirstSeen" value="2013-03-02T21:22:33-05:00"/>
<simplefield name="UseForAutoMatch" value="false"/>
<complexfield name="Group">
<values>
<value>
<simplefield name="objectName" value="Employees"/>
<simplefield name="Description" value="Employees"/>
<simplefield name="AutoMatchType" value="UsePersonAutoMatchSetting"/>
</value>
</values>
</complexfield>
<simplefield name="Employee ID" value="80"/>
<simplefield name="Employee Type" value="Full Time"/>
<simplefield name="Gender" value="Female"/>
<simplefield name="Hair Color" value="Black"/>
<image format="jpeg" width="280" height="280">
[IMAGE DATA]
</image>
</Person>
</Persons>
</ThreeVRDbSync>

/livevideo

https://[IP address or hostname]:[port]/livevideo

Sample Response

/video

https://[IP address or hostname]:[port]/video/

WILL BE DEPRECATED IN NEXT RELEASE, USE /channels

Returns stored video from the camera with the given camera number and options (start time, end time, length, framerate, and/or resolution). Note: Datetime values are formatted according to the ISO 8601 specification: YYYY-MM-DDTHH:MM:SS For example, 2012-12-05T13:40:27. For more information, see this article from the W3C W3.org: Date and Time Formats.

/event*

https://[IP address or hostname]:[port]/event/

Sample Response

/liveimage

https://[IP address or hostname]:[port]/liveimage/

Sample Response

/channels

https://[IP address or hostname]:[port]/channel

/time

https://[IP address or hostname]:[port]/time

/version

https://[IP address or hostname]:[port]/version

/views

https://[IP address or hostname]:[port]/views

Input for POST/views

{
"Id":null,
"Name":"1 Channel",
"Shared":false,
"UserName":"user",
"UserId":null,
"Channels":[
{
"Id":9,
"Name":"Camera 9",
"ChannelDrive":null,
"IsActive":true,
"ChannelType":"IPNetworkCamera",
"ThumbnailUrl":null,
"LocalId":0,
"Appliance":{
"Id":1,
"Name":"Developer Workstation",
"Address":null,
"MachineType":"Integrated",
"TimeZoneKey":"Pacific Standard Time",
"TimeZoneOffset":480,
"Created":"/Date(1351818098000)/",
"Updated":"/Date(1353442448000)/",
"VideoStart":"/Date(1352497452000)/",
"SyncDate":"/Date(1351818098000)/"
},
"selected":false,
"isEnterprised":false,
"Number":9,
"ChannelDriver":"GenericIPCameraDriver",
"ImageUrl":"https:///channels/9/image",
"hostname":""
}
],
}

Input for PUT/views

{
"Id":15,
"Name":"Single Channel View",
"Shared":false,
"UserName":"techrep",
"UserId":2,
"Channels":[
{
"Id":9,
"Name":"Camera 9",
"ChannelDrive":null,
"IsActive":true,
"ChannelType":"IPNetworkCamera",
"ThumbnailUrl":null,
"LocalId":0,
"Appliance":{
"Id":1,
"Name":"Developer Workstation",
"Address":null,
"MachineType":"Integrated",
"TimeZoneKey":"Pacific Standard Time",
"TimeZoneOffset":480,
"Created":"/Date(1351818098000)/",
"Updated":"/Date(1353442448000)/",
"VideoStart":"/Date(1352497452000)/",
"SyncDate":"/Date(1351818098000)/"
},
"selected":false,
"isEnterprised":false,
"Number":9,
"ChannelDriver":"GenericIPCameraDriver",
"ImageUrl":"https:///channels/9/image",
"hostname":""
}
],
}

/rtsp

https://[IP address or hostname]:[port]/rtsp

Sample XML Response

<RestRTSPResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Message>OK</Message>
<Uri>rtsp://10.10.10.10:554/Stream3</Uri>
</RestRTSPResponse>

Sample JSON Response

{
"Message": "OK",
"Uri": "rtsp:\/\/10.10.10.10:554\/Stream3"
}

3VR External System Activity API - SOAP

Overivew

The 3VR External System Activity API allows third parties to define their own event types for the 3VR system and add instances of these events to the 3VR system. These events can then be displayed and searched for using 3VR's OpCenter application. In OpCenter, these events can be correlated with other event types using the "Search for related events" option in the Search panel.

The 3VR External System Activity API is built on the Simple Object Access Protocol (SOAP) using HTTP, a standard web services protocol accessible from a wide variety of platforms and languages. Since SOAP is based on XML, it is easy to build requests and process replies.

To support custom events, 3VR has a framework called generic events. These events are similar to internally defined events, but their structure can be defined by external agents. A given 3VR system can have an arbitrary number of defined generic event types. However, for usability reasons, we recommend that a given vendor use a single event type and differentiate using metadata. However, this is not a hard rule. Generic events will be displayed alongside the other event types, such as Motion and Face, in the Monitor, Search, and Cases panels of OpCenter.

Generic events appear in the software using individually defined names, displayed on each generic event card. When the user chooses to view smaller event cards, the short name is displayed. For example, in the event card below, the generic event name is "Bank Teller"

Generic events can integrate custom field data. The API name for a custom field is a metadata field. The generic event definition specifies the event type name, short name, help text, metadata fields, and a globally unique identifier (GUID). The generic event definition GUID identifies the generic event type and metadata fields across different 3VR servers.

Each metadata field has name, description, type, display position, display format and GUID.

• Name appears in the event details and may appear on the event card depending on the display format.

• Type specifies the kind of data stored in the field. The type can be String, Number, DateTime, or EnumeratedType.

• Description is a text string that describes the field.

• Display position controls the order in which the metadata fields are displayed.

• Display format controls the way the data is displayed on the large event cards.

When you define a new generic event type, you will have to create GUIDs for the event type itself and each of the metadata fields that you are defining. It is important to use the same GUIDs for every server on which you use your application. GUIDs can be generated in a number of ways.

• At the time of this writing, GUIDs could be generated on the following sites:

  • GUID Generator

  • GUID Gen

• Microsoft Visual Studio includes a GUID generating tool called GUIDGen.exe. This program is located in \Program Files (x86)\Microsoft SDKs\Windows\v7.0A\Binin Visual Studio 2010.

• When the generic event definition is created, if a GUID has not been specified, a GUID will be generated automatically and returned in the response. Incorporate the response GUID into your code whenever you create the definition.

A typical application of the External System Activity API will:

1. Authenticate the user of the application. The user needs to be defined in 3VR System Manager. The authenticate call returns an authentication token that is used in SOAP Header for all subsequent requests.

2. Create the generic event definition if it does not already exist.

3. Based on some external stimulus, create a generic event associated with a camera.

Authentication is accomplished using the IAuthenticateService. The IGenericEventService provides the rest of the API.

Browsing 3VR External System Activity API Services

Verify that the Web Services is running by pointing a browser at any of the following 3VR External System Activity API services

• https://hostaddress:8080/3vr/IAuthenticateService.asmx

• https://hostaddress:8080/3vr/IGenericEventService.asmx

Click on any of the asmx links to see the available services. The SOAP WSDL is available at the Service Description link. The service call XML specification is available on the operation link.

Authentication

• https://hostaddress:8080/3vr/IAuthenticateService.asmx?op=Authenticate

Authenticate against the 3VR users. The Soap Header can be blank. It will return the Token for use in the SOAP header for subsequent operations.

Create Events

Once authenticated you are ready to create events with the IGenericEventService. The WSDL is available by clicking the Service Description link.

https://hostaddress:8080/3vr/IGenericEventService.asmx:

The primary operations are:

• CreateGenericEventDefinition: Create a Generic Event Definition for new generic events. Values for Type = String, Number, DateTime, or EnumeratedType

• CreateGenericEvent: Create a Generic Event from the server.

The other operations are used in support of generic event creation.

• Channels: Get a list of channels.

• CustomFieldNames: Get a list of Custom Field Names associated with a person profile in the 3VR system. Used for FaceComparison events.

• DeleteGenericEvent: Delete a Generic Event.

• DeleteGenericEventDefinition: Delete a Generic Event Definition.

• GenericEvent: Get a Generic Event from the server.

• GenericEventDefinitionByGUID: Find an the Generic Event Definitions with the specified GUID.

• GenericEventDefinitionsAll: Get all Generic Event Definitions.

• GenericEventDefinitionsByName: Find all the Generic Event Definitions with the provided name.

• UpdateGenericEvent: Update a Generic Event.

• UpdateGenericEventDefinition: Update an existing Generic Event Definition GUIDs must match for existing elements

Developing Client Programs

3VR Web Services are design to work in various environments (.NET, Java, Python, etc.).

.NET

If you are working in .NET, the program wsdl.exe (in \Program Files (x86)\Microsoft SDKs\Windows\v7.0A\Bin) will automatically generate client code. For example, to generate C#, run the following at the command line:

> wsdl /language:CS https://[IP or host name of 3VR appliance]:8080/3vr/IGenericEventService.asmx?WSDL

and WSDL.exe will generate client code to access Generic Event operations.

Java XML

For Java systems, 3VR provides an example using Apache.org's Axis package and WSDL2Java to generate the client code using JAX-RPC and JAWS API's. This sample uses Axis 1.4 from Apache.org and JAF activation.jar and mail.jar from java.sun.com

1. Set AXIS _ HOME to where you installed Axis, e.g. C:\java\axis-1 _ 4\lib.

2. Set up or copy the log4j properties from AXIS _ HOME, and set up AXIS _ HOME in the environment.

3. The CLASSPATH will look something like:
   

   CLASSPATH = .;%AXIS _ HOME%\axis.jar;%AXIS _ HOME%\commons-discovery-0.2.jar;%AXIS _ HOME%\commons-
   logging-1.0.4.jar;%AXIS _ HOME%\jaxrpc.jar;%AXIS _ HOME%\log4j-1.2.8.jar;%AXIS _ HOME%\saaj.
   jar;%AXIS _ HOME%\wsdl4j-1.5.1.jar;%AXIS _ HOME%\mail.jar;%AXIS _ HOME%\activation.jar

4. Run WSDL2Java at the command line to create the client library.
   

   > java org.apache.axis.wsdl.WSDL2Java --output src --package com. _ 3vr.Services http://
   localhost/3vr/IAuthenticateService.asmx?WSDL>java org.apache.axis.wsdl.WSDL2Java --output
   src --package com. _ 3vr.Services http://localhost/3vr/IGenericEventService.asmx?WSDL

5. With the generated code, use of the Authenticate operation in Java becomes:
   

   try{
   IAuthenticateServiceLocator locator = new IAuthenticateServiceLocator();
   java.net.URL url = new java.net.URL(serverUrl + "IAuthenticateService.asmx");
   IAuthenticateServiceSoap _ PortType port = locator.getIAuthenticateServiceSoap(url);
   AuthenticateToken token = port.authenticate("user", "password");
   System.out.println("Status " + token.getStatus() + "Token " + token.getToken());
   if(token.getStatus().equals("Success"))
   {
   return token.getToken();
   }
   }
   catch(Exception e)
   { System.out.println(e.getMessage());
   
   

6. To use the generic operations, the token needs to be set in the header. The SoapHeaderInfo class 3VR uses to put the Service Token in the SoapHeader is not created by WSDL2Java. We created one to match the other classes generated. Putting the Service token in the SoapHeader becomes:

import javax.xml.namespace.QName;
import org.apache.axis.message.SOAPHeaderElement;
try
{
IGenericEventServiceLocator locator = new IGenericEventServiceLocator();
java.net.URL url = new java.net.URL(serverUrl + "IGenericEventService.asmx");
genericEventService = locator.getIGenericEventServiceSoap(url);
QName qname = new QName("http://3vr.com", "SoapHeaderInfo");
SoapHeaderInfo SoapHeaderInfo = new SoapHeaderInfo("", token);
SOAPHeaderElement header = new SOAPHeaderElement(qname, SoapHeaderInfo);
org.apache.axis.client.Stub stub = (org.apache.axis.client.Stub)genericEventService;
stub.setHeader(header);
}c
atch(Exception e)
{
System.out.println(e.getMessage());
}

For more details, see the source for the BankTeller Java sample.

Sending Request XML

The SOAP Envelope wraps the request, and the <soap:body>contains the details of the request. Here are examples of the XML for Authenticate. In following example we will usually display the XML for the body and omit the header and wrapping XML.

SOAP 1.1 Request Envelope

POST /3vr/IAuthenticateService.asmx HTTP/1.1
Host: 10.100.1.105
Port: 8080
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://3vr.com/Authenticate"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<SoapHeaderInfo xmlns="http://3vr.com">
<Address>string</Address>
<ServiceToken>string</ServiceToken>
</SoapHeaderInfo>
</soap:Header>
<soap:Body>
<Authenticate xmlns="http://3vr.com">
<username>string</username>
<password>string</password>
</Authenticate>
</soap:Body>
</soap:Envelope>

SOAP 1.1 Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<AuthenticateResponse xmlns="http://3vr.com">
<AuthenticateResult>
<Token>string</Token>
<Status>string</Status>
</AuthenticateResult>
</AuthenticateResponse>
</soap:Body>
</soap:Envelope>

SOAP 1.2 Request Envelope

POST /3vr/IAuthenticateService.asmx HTTP/1.1
Host: 10.100.1.105
Port: 8080
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
<soap12:Header>
<SoapHeaderInfo xmlns="http://3vr.com">
<Address>string</Address>
<ServiceToken>string</ServiceToken>
</SoapHeaderInfo>
</soap12:Header>
<soap12:Body>
<Authenticate xmlns="http://3vr.com">
<username>string</username>
<password>string</password>
</Authenticate>
</soap12:Body>
</soap12:Envelope>

SOAP 1.2 Response

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
<soap12:Body>
<AuthenticateResponse xmlns="http://3vr.com">
<AuthenticateResult>
<Token>string</Token>
<Status>string</Status>
</AuthenticateResult>
</AuthenticateResponse>
</soap12:Body>
</soap12:Envelope>

Authenticate

As shown in the examples above, the Authenticate operation sends the user name and password and receives a <Token> and <Status> in the response:

<AuthenticateResult>
<Token>string</Token>
<Status>string</Status>
</AuthenticateResult>

If all goes well the <Status> will contain "Success". The <Token> is used on the following request in the soap:Header<ServiceToken>.

CreateGenericEventDefinition

Generic event definitions control how events are displayed in OpCenter. The name and metadata fields are displayed on the event card, and metadata is displayed in event details. Users can search for events using metadata fields in the Search panel.

The metadata fields define custom data fields for the generic event. The GUID identifies the generic event and metadata fields across different 3VR servers. The GUID is instrumental when identifying the generic event and editing the generic event definition.

Each metadata field has a Name, Description, Type, Display Position, Display Format and GUID elements:

Generic Event Definition Metadata Fields

<Name> Appears in the event details and may appear on the event card, depending on the Display Format.
<Type> Defines the data type. Values include "String", "Number", "DateTime", or "EnumeratedType".

<Description> Describes the field.
<DisplayPosition> Sets the order the Metadata Fields are displayed. Valid display values are 0-100. Values over 100 are not displayed.
<DisplayFormat> Controls the way the data is displayed on large event cards. Allows simple formatting (bolding, joining lines and inserting new lines). See the following code sample for more information.
<EnumeratedData> Lists the valid data values for an EnumeratedType.

<CreateGenericEventDefinition xmlns="http://3vr.com">
<eventDefinition>
<Name>string</Name>
<ShortName>string</ShortName>
<GUID>string</GUID>
<HelpText>string</HelpText>
<MetadataFields>
<MetadataField>
<GUID>string</GUID>
<Name>string</Name>
<Description>string</Description>
<Type>String or Number or DateTime or EnumeratedType</Type>
<DisplayPosition>int</DisplayPosition>
<DisplayFormat>string</DisplayFormat>
<EnumeratedData xsi:nil="true" />
</MetadataField>
<MetadataField>
...
</MetadataField>
</MetadataFields>
</eventDefinition>
</CreateGenericEventDefinition>

Here is an example of a simple CreateGenericEventDefinition named "Example Event":

<CreateGenericEventDefinition xmlns="http://3vr.com">
<eventDefinition>
<Name>Example Event</Name>
<ShortName>Example</ShortName>
<GUID>66B886FA-F097-4290-89DD-E308E5E05A5</GUID>
<HelpText>Some help text that describes an Example Event.</HelpText>
<MetadataFields>
<MetadataField>
<GUID>1FE84583-F770-4b89-AE2B-FD247C90785</GUID>
<Name>Data</Name>
<Description>Data for the example</Description>
<Type>String</Type>
<DisplayPosition>1</DisplayPosition>
<DisplayFormat>{name} {value}</DisplayFormat>
</MetadataField>
</MetadataFields>
</eventDefinition>
</CreateGenericEventDefinition>

If we were to generate a generic event with this definition on a 3VR Appliance, "Example Event" would appear as an option in the event selector in OpCenter's Monitor and Search panels.

Furthermore, since Example Event has a metadata item with the <name> "Data" that is of <type> "string", users could create a search that would return only Example Events with a "Data" value matching their search string.

Generic Event Definition DisplayFormat

There are seven tags that can be used to format the text displayed for a generic event data field: {name}, {value}, {bold}, {newline}, {oneline}, {joinline}, and {wrap}. All other text inserted into the display format will be displayed as plain text.

To display a field with the name “Amount” and the value “$100” as “Amount: $100”, then, would require the following display format: Format: {name}: {value}

Result: Amount: $100

Bolding a portion of the text field requires putting a {bold} tag at the beginning and end of that section of text. There can only be two{bold} tags, and the first must be at the beginning of the display format. Displaying “Amount: $100” would require the following display format: {bold}{name}:{bold} {value}

The {newline} tag inserts a newline character into the text. The display format {name}:{newline}{value} will result in

Amount: $100

Conversely, the {oneline} tag removes all newline characters from the name and value strings not explicitly defined by a {newline} tag, replacing them with a single space.

The {joinline} tag can be used to put two or more fields on a single line. Placing {joinline} in a field’s display format will
cause the next field to be displayed on the same line, to the right of the current field. For two fields, one describing gender and the
other eye color, to be displayed as “Gender: Male Eye Color: Brown”, both fields can be given the following display format: {name}:
{value} {joinline}. An arbitrary number of fields can be placed on the same line, limited only by screen space.
By default, OpCenter will display as much of each line as possible, and truncate any text that does not fit in the available space. If
you do not wish to truncate text, use the {wrap} tag to wrap oversized strings in a given field onto multiple lines. This tag cannot be
used in conjunction with the {joinline} tag.
Putting it all together, the Bank Teller event card shown here: