MobileView 4.2 Integration Guide - AeroScout 4.2 Integration Guide Table of Contents 3 Table of...

MobileView 4.4 Integration

Guide Version 2.1

MV4-INTG-020511-01

Disclaimer

The information and know-how included in this document are the exclusive property of AeroScout Inc. and are intended for the use of the addressee or the user alone. The addressees shall not forward to another their right of using the information, know-how or document forwarded herewith, in whole or in part in all matters relating or stemming from or involved therein, whether for consideration or without consideration, and shall not permit any third party to utilize the information, know-how or the documents forwarded herewith or copies or duplicates thereof, unless at the company’s consent in advance and in writing. Any distribution, advertisement, copying or duplication in any form whatsoever is absolutely prohibited. The Company reserves the right to sue the addressee, user and/or any one on their behalves, as well as third parties, in respect to breaching its rights pertaining to the intellectual rights in particular and its rights of whatever kind or type in the information, know-how or the documents forwarded by them herewith in general, whether by act or by omission.

This document is confidential and proprietary to AeroScout Inc. and is not to be distributed to any

persons other than licensed AeroScout Visibility System users or other persons appointed in writing by AeroScout Inc.

Trademark Acknowledgements

AeroScout™ is a trademark of AeroScout, Inc. Other brand products and service names are trademarks or registered trademarks of their respective holders. Below is a partial listing of other trademarks or registered trademarks referenced herein:

Cisco™ is a trademark of Cisco Systems, Inc.

Sun, Sun Microsystems, the Sun Logo, Java, JRE and all other Sun trademarks, logos, product names, service names, program names and slogans that are referred to or displayed in this document are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

This product includes code licensed from RSA Data Security

Skype, SkypeIn, SkypeOut, Skype Me, the Skype Logo and the S logo and other marks indicated on Skype’s website are trademarks of Skype Limited or other related companies.

ESper is a trademark of EsperTech, Inc.

Jboss is a trademark of Red Hat Middleware, LLC.

Oracle 10G is a registered trademark of Oracle Corporation and/or its affiliates.

MS SQL Server 2005 is a registered trademarks of Microsoft Corporation in the United States and/or other countries.

JasperSoft, the JasperSoft Logo, JasperReports, the JasperReports logo, JasperIntelligence, JasperDecisions, JasperAnalysis, Scope Center, Scope Designer, and JasperServer are trademarks or registered trademarks of JasperSoft, Inc. in the United States and other countries.

Copyright 2010 AeroScout Inc. All rights reserved.

MobileView 4.2 Integration Guide

Table of Contents 3

Table of Contents

Overview................................................................................................................................. 6

MobileView API ................................................................................................................. 6

MobileView Events ............................................................................................................ 7

When to Use the APIs and When to Use Events ............................................................ 8

MobileView Architecture .................................................................................................. 8

Document Organization .................................................................................................... 9

MobileView Events ............................................................................................................ 10

Choosing an Action Type ................................................................................................ 10

Using Update Asset/Zone Property Action Types ...................................................... 11

Action and Message Types ............................................................................................. 11

Message Types 12

Action Types 13

JMS 14

API Services ......................................................................................................................... 15

Utilizing AeroScout’s Proxies ......................................................................................... 15

Downloading WSDLs Directly ....................................................................................... 16

Summary of Services ........................................................................................................ 16

Deprecated Methods 18

AreaAPIService 18

AssetAPIService 19

AssetBusinessStatusAPIService 21

CategoryAPIService 21

DepartmentAPIService 22

EventAPIService 23


Table of Contents 4

GroupAPIService 24

LocatorAPIService 25

PermissionAPIService 27

RoleAPIService 27

SystemAPIService 28

TagAPIService 28

UserAPIService 28

ExciterAPIService 29

MeasurementApiService 30

SavedSearchApiService 30

Enhancement and Bug Fixes ............................................................................................. 31

Enhancements ................................................................................................................... 31

Enhancements MobileView 4.3.0.20 31

Enhancements in MobileView 4.2.17 31

Enhancements in MobileView 4.1.17 32

Bug Fixes ............................................................................................................................ 32

Bug Fixes in MobileView 4.3.0.20 32

Bug Fixes in MobileView 4.2.17 33

Bug Fixes in MobileView 4.1.17 34

Appendix A – Troubleshooting Tips .............................................................................. 35

Appendix B - Code Samples ............................................................................................. 36


Document History 5

REVISION HISTORY

Revision Date Comments Author

1 2 Match 2010 New document A Ben Shach

2 28 April 2011 Upgrade document to MobileView 4.3 Avi Chalbani

Relevant Documents

Document Description

MobileView 4 User’s Guide The MobileView User Guide

MobileView Deployment Guide The MobileView Deployment Guide

MobileView Integration Tools Tool and software samples for MobileView 4.3

MobileView 4 API Reference Document


Chapter 1 Overview 6

1 Overview

This document provides information on how to integrate to AeroScout MobileView

4 using the API (Application Programming Interface) or using MobileView events.

This document assumes a basic understanding of integrations, software

development and of MobileView.

MobileView API

The MobileView API can be used to perform almost any operation. Here are a few

examples of what you can do with the MobileView API:

Add a new asset

Add a new tag

Assign a tag to an asset

Get the location of an asset

Get the battery status of a tag

Assign an asset a category

Assign an asset a department

Change the business status of an asset.

The MobileView API is provided over SOAP (Simple Object Access Protocol) a

widely used standard for integrating applications. SOAP is supported by most

development platforms including, but not limited to, J2EE and .NET for use with

Java, C# and Visual Basic languages.



MobileView Events

MobileView can be configured to proactively notify a third-party application of a

particular event. An event is an occurrence such as an asset leaving an area or a

temperature exceeding a threshold.

An event monitor corresponds to the logic that introduces event criteria and the type

of notification that will be sent when the criteria is met. When the conditions are met

for a particular monitor, an event is created by the monitor to record the occurrence.

A notification can also be sent to a third-party application.

MobileView comes with out-of-the-box monitor types. These monitors have pre-

defined logic and parameters. Once the parameters are chosen for a monitor and the

monitor is activated, it will generate events for the third-party application. More

information on monitor types, monitors and events are available in the MobileView

User's Guide.

To enable the monitor to send data automatically to another application, an action

must be defined. For an event-based integration one of the following action types

can be configured:

HTTP Post (.xml or map)

JMS (XML or map)

Web Service (.xml or text based)

SMTP (configurable message)

The SMTP action type is almost never used when integrating to third-party

applications. The e-mail and JMS messages are configurable and can include many

fields that enable the third-party application to process the incoming event. Here are

a few sample fields:

Monitor Name

Date/time stamp

Asset Name

Asset Location

For a complete list of all event attributes please refer to MobileView Events.



When to Use the APIs and When to Use Events

There are three integration options:

Use only events

Use only the API

Use both the API and events

Events are very useful for notifying a third-party application immediately when

something has happened. An event is generated, for example, when an asset has

moved to a new area or passed through a specified doorway. Immediately upon

recognizing this movement, an event is fired and can be used for providing an

update to the third-party application. The benefits to the third-party application

include the ability to react to events quickly. This type of integration keeps the third-

party application always up-to-date with information regarding the asset's last

reported location.

Event integrations are message-based and cannot change any attributes in

MobileView. The API integration, on the other hand, can be used to adjust entities in

MobileView. The API can also be used to pull information about assets and their

location.

As already suggested, you can combine event reporting and API calls. For example,

it is common to use the API to keep information on assets/tags synchronized with a

third-party system and to use events to keep the location information in the third-

party system up to date.

MobileView Architecture

AeroScout MobileView is the industry's most advanced application in the area of

Unified Asset Visibility (UAV). MobileView is designed to consolidate all location

applications in an organization into a single, normalized source of location data and

logic. Integrations can be developed for a wide variety of applications using

MobileView as the single source.

The figure below illustrates how MobileView integrates to multiple location

technologies using hardware, location engines and gateways.



MobileView also provides a robust user interface for end-users to easily view the

location of assets or to update asset information. The result is a complete and unified

asset visibility application which delivers substantial value to end-users and third-

party applications.

Document Organization

The rest of the document is organized as follows:

MobileView Events - Provides description on the specific data included in the

alert messages sent by MobileView.

API Services - Describes the web services that are particularly useful for

determining integration feasibility and for integration planning. It is also

recommended to consult the more technical API reference document.


Chapter 2 MobileView Events 10

2 MobileView Events

MobileView events are a powerful integration feature, which allow for a change in

location (or other event) to be updated into another system. When an event is fired,

it delivers useful data such as timestamp, asset name and location, which can be

used by the receiving system to trigger a certain action.

One of MobileView integration features is the asynchronous hooks. Asynchronous

hooks provide the ability to receive notifications on asset manipulation actions, such

as Creating, removing and updating assets.

Choosing an Action Type

The possible action types are:

HTTP Post – Field list/Xml

Web Service – Xml/Customized text

JMS - Field list/Xml

Update Asset Property

Update Zone Property

Email – Customized text

Transports 1 to 3 are used for integrating with external applications.

The other transports are typically used to update properties within MobileView or

notify people that an event has occurred. These actions would never (or at least

rarely) be used for software integrations.



Using Update Asset/Zone Property Action Types

Transports 4-5 can be used as an optional feature for enhancing integrations. For

example, "Update Asset Property" can be used to update the status of an asset to a

different value, when a certain condition is met. This status can be used to

communicate information to end users (e.g. an asset is out of service, available for

use, etc.). These statuses can be configured to different values.

Asset can be activated or suspended based on an event. An asset has to be active to

fire events and to have its location tracked in MobileView, thus, by suspending an

asset – it can toggle whether that particular asset will fire events or not.

“Update Zone Property” action changes the zone status and or the zone color. The

user can select the zone type to which the change applies (or all zones). The affected

zone is the zone where the event takes place.

Action and Message Types

MobileView provides ample flexibility for action types that are transporters of

different message types. Many message types can be sent over driftnet action types.

As explained in the previous section, the common action types for software

integration are:

HTTP Post

JMS

Web Service

Event information can be sent using the following message types:

Customized Text Messages: Message templates can be configured in MobileView.

Key-Value Map: Key value pairs of all the fields.

Alert XML Message: The XML construct is built according a predefined alert

schema.

The following table shows the available message type for each action type.

Action Type/ Message Type

Customized text based message

XML Field list/Map

HTTP Post + + +

Web Service + + -



JMS - + +

Message Types

Customized Text Messages

Customized messages can be sent as events occur. The message has first to be

configured in the template configuration file located at:

[MobileView_HOME]\tomcat\webapps\asset-manager-web\WEB-

INF\am\conf\alertTemplates.xml

After a system restart, the new message type can be selected during the event

definition process. Please refer to the MobileView User Guide for a detailed event

definition description.

Key-Value Map

The event information can be sent as a key value map. The following table illustrates

some sample values of the keys available in the key value map:

Key Sample Value

EventName Repair Equipment Call Button

AssetPrimaryCategoryName Heavy Equipment

AreaName Main Warehouse/1st Floor

EventID 2764

EventType Call Button

Date 02 Jul 08 11:06 AM

AssetName Tag 29F7

AssetBusinessStatus In Use

AssetId 945

XML Message

The receiving side extracts the XML message and retrieves the required fields by

parsing the incoming structure



The third-party software component can receive an XML message with the relevant

event data. Available fields vary, depending on the event type. The full list of the

available fields can be found in alert message XSD:


INF\xsd\alert.xsd.

Use the XSD in order to parse and validate the received XML structure.

alert.sample.xml

Action Types

HTTP Post

HTTP Post can be selected as action type during the event definition process. The

receiving side should parse the HTTP Post data and extract the relevant information.

MobileView expect an HTTP response line, called the status line. It consists of three

parts separated by spaces:

The version of HTTP being used.

A response status code that gives the result of the request.

Text describing the status code.

Here is an example of initial line for a response message.

HTTP/1.0 200 OK

In the case of an XML message type, the following key-value pairs are sent:

Key Description of value

XML This is the XML message represented as a long string. See XML

sample below.

Eventide This is the unique event ID (string).

Web Service

A web service calls a particular method on the third-party server (the IP address and

web service are specified in the action). The method called must be a specific name

with specific parameters and return values. AeroScout provides a WSDL to quickly

create a web service that can receive MobileView alerts.



The method must be defined as follows:

public AlertResult Alert(string subject, string message, long eventId, long

eventDate);

The WSDL that specifies the called Web Service can be found at:


INF\classes\wsdl\mv4alert.wsdl

To receive events you need to create a web service server which implements the

above WSDL file. As indicated above, the web service channel can transmit either a

text message or an XML message that needs to be parsed by the web service server.

When the web service alert is sent as XML, the subject parameter in the web service

call will contain the word ‘Xml’ and the body the XML structure. The application

developer can use the subject parameter to determine if the message is of XML or

text type. Please refer to the HTTP Post XML Structure section for sample XML code.

JMS

JMS is a transport which queues messages for the receiving application. These

messages can be retained for a given period. One advantage of using JMS is that, if

the third-party application experiences a period of downtime, data sent from

MobileView is not lost. This is because JMS keeps the events in the queue until the

third-party system is ready to receive the messages.

JMS supports messages in either XML format or in a map object.

The XML format is the same as described above. The received message type would

be “TextMessage” and the XML message has to be parsed

The map contains all the available fields in a structure with key-value pairs which

can be extracted easily. The received message type would be “ObjectMessage” and

the XML message has to be parsed


Chapter 2 API Services 15

3 API Services

This chapter provides a description of the MobileView API services and the

capabilities of each. There is also general information about best integration

practices.

Specifically, this section will help with the following purposes:

Determining feasibility

Planning effort estimates for integrations

Writing function specifications

Helping rapidly introduce developers to the MobileView API framework.

For coding purposes, developers should refer to the MobileView API Reference

document which has specifics on each method, each object, language syntax,

parameters and return values. The MobileView API Reference is part of the

MobileView installation and can be found at:

[MobileView_HOME]\api\mv-ws\apidocs

Utilizing AeroScout’s Proxies

Since the MobileView API is implemented as a web services, you can download one

or more of the API WSDL (Web Services Description Language) files from a

MobileView application server. Once a WSDL is downloaded, it can be used to

generate the language-specific code required for integration. This code provides the

objects required for passing arguments and receiving data. It also provides the stubs

for the MobileView methods which are necessary for compilation.



To get started quickly, AeroScout supplies ready-made proxies for Java and .Net.

Developers can include them in their environment. Once included, all that is left for

the developer to do is setting the host name and supplying the credentials.

Downloading WSDLs Directly

If the developer needs to develop the integration in a development environment

other than C# or Java, it is always possible to generate the necessary code directly

from MobileView WSDL files. The WSDLs can be downloaded from a running

MobileView server as follows:

1. Go to http://[MobileView 4 server IP]: [MobileView 4 server port]/asset-

manager-web/services.

2. Enter a valid MobileView 4 login ("system") and password {"manager"}.

This will bring you to a screen that lists each of the API services and the

associated hyperlink for its WSDL.

3. Click on the WSDL and save the XML file as a text file for importing into your

development environment.

Summary of Services

The MobileView Server organizes the API into several functional groups. Each

functional group has its own service.

Generally, each service manages a single entity – an asset, a tag, a department or a

group. Typically, services provide at least one create, update, delete and a find

methods.

Each service is identified by the web service WSDL. The WSDL defines the

functionality offered by a web service. The WSDL document also defines the

methods, parameter names, parameter data types and return data types for the web

service.

List of available services

Service Name Purpose 4.3.0.20 4.2.17 4.1.17

AreaAPIService Provides functions for manipulating Locations, Areas and Zones.

+ + +

AssetAPIService Provides functions for Asset management.

+ + +



Service Name Purpose 4.3.0.20 4.2.17 4.1.17

AssetBusinessStatusAPIService API for fetching Asset Business Status Entities.

+ + +

CategoryAPIService Provides functions for Category management.

+ + +

DepartmentAPIService Manages Department entities.

+ + +

EventAPIService Manages Event, EventSpec, EventSpecTemplate entities

+ + +

GroupAPIService Manages Group entities. + + +

LocatorAPIService Provides functions for querying the different types of Location Reports.

+ + +

PermissionAPIService Manage Permission entities.

+ + +

RoleAPIService Manage Role entities. + + +

SystemAPIService For non-specific system calls. For example, use this to get the API version which is in use.

+ + +

TagAPIService Manages Tag entities. + + +

UserAPIService Manages User entities. + + +

ExciterAPIService Provides functions for retrieving exciter configuration information

+ + -

MeasurementApiService Provides methods for retrieving information on measurements:

+ + -

SavedSearchApiService This service provides methods for retrieving saved searches.

+ + -

Security is still enforced when API calls are performed, so make sure the user

defined in the credentials has the appropriate permissions to invoke the required

methods and objects.

Data syntax checking which is done in the MobileView user interface is not always

performed at the API level. Developers are responsible for utilizing the API carefully

and making sure the integrations appropriately handle data checking and

exceptions.

MobileView supports a locking mechanism. If two separate API calls try

simultaneously to update the same object, the first call will succeed but the second

update call will fail and a data integrity exception will be thrown. The second user



will have to retrieve the updated object again. API designs which can create this

scenario need to catch or manage the exceptions.

There are many MobileView data transfer objects (DTOs) which are used as

parameters in the API and as return values. Data objects are not described in detail

in this document but are well documented in the MobileView API Reference

Document.

Deprecated Methods

MobileView API evolving, additional functionally was added and old methods

become deprecated. Deprecated methods are marked with Asterisk ‘*’. It is strongly

recommended not use deprecated methods, even if there are still available, its main

purpose is to support backwards compatibility.

The accessibility of deprecated methods is limited to three major releases before the

deprecated method will no longer be available.

Note

All API services had create, update and delete methods, using those functions cussed unexpected behavior due to ambiguous methods names. New methods have been added to all relevant services.

AreaAPIService

MobileView organizes maps and zones into a hierarchical structure of sites,

buildings, floors and areas where a site can have many buildings, a building can

have many floors, and a floor can have many areas. All of these are stored as a set a

generic area objects within a tree structure. Each map is assigned an area. Each zone

is assigned to a map.

Methods are available for:

Service Method Description 4.3.0.20 4.2.17 4.1.17

createZone Create new zone. + + +

updateZone Update zone properties. + + +

removeZone Remove zone. + + +

findAllPassiveZones Retrieve all passive zones.

+ + -

findZonesByMapId Retrieve zone that belong to a given map id.

+ + +

findPopulatedZoneById Retrieve single zone by id.

+ + +




findPopulatedZonesByIds Retrieve populated zones by ids.

+ + -

findZoneTypeById Retrieve zone type by id

+ + -

findAllZoneTypes Retrieve all zone type. + + -

createArea Create area. + + +

updateArea Update area properties. + + +

removeArea by AreaDTO Deprecated. Use removeArea (By ID) instead.

- - -

removeArea by Id Remove area. + + +

findRootAreaTree Retrieve full area tree structure.

+ + +

findPopulatedAreaById Retrieve populated area object by id.

+ + +

findAllMaps Retrieve all system maps without images.

+ + +

findMapById Retrieve map by id. + + +

findAllMaps Retrieve all system maps without images.

+ + +

findPopulatedMapById Retrieve populated map object by id.

+ + +

findCustomLocationStringPattern Return system custom location string pattern.

+ + -

Note

It is highly recommended to create, edit and delete MobileView locations (such as areas and zones) through the user interface.

AssetAPIService

The asset object is the primary object used for location. Tags are associated with asset

objects and the location is tracked on the asset itself. Assets can have one or more

categories, departments, groups and tags associated with it. In addition, an asset has

one primary category, one business status and one activity status. Assets that are in

inactive status will not generate events and will not track location information.

Although there are predefined fields for an asset (name, description, serial number,

etc.), assets can be extended using custom properties to store additional fields as

required.





create Deprecated. Use createAsset instead.

-* -* -*

createAsset Creates asset. + + +

remove Deprecated. Use removeAsset instead.

-* -* -*

removeAsset removes asset + + +

update Deprecated. Use updateAsset instead.

-* -* -*

updateAsset Update given asset properties. + + -

updateAssetByLayout Updates given asset properties and associations according to specific layout object.

+ + -

findPopulatedAssetById Retrieve populated asset by asset id.

+ + +

findPopulatedAssetByNaturalKey Retrieves asset by name and application id which is an asset natural key

+ + +

findPopulatedAssetByTagNetworkId Retrieve asset by mac address of its associated tag.

+ + +

findPopulatedAssetsByApplicationId Retrieve populated assets array by application id.

+ + -

findAssetsByIds Retrieve array of assets by ids.

+ + +

findPopulatedAssetsByIds Retrieve array of populated assets by ids.

+ + +

findAssetsByCriteria Deprecated. Use findAssetsBySearchCriteria instead.

-* -* +

findAssetsBySearchCriteria Retrieve page of asset entities by criteria.

+ + -

makeTagBlink Deprecated. Use makeAssetTagBlink instead.

-* -* +

makeAssetTagBlink Make Asset tags led blink, blink period defined by MobileView system settings.

+ + -

makeAssetTagBlinkForPeriod Make Asset tags led blink for a specific time period.

+ + -



AssetBusinessStatusAPIService

The Asset Business status object stores the current business status for assets. The

Asset Business Status service includes only asset searching methods. It does not

include methods such as create, update and delete.



findAssetBusinessStatus Return Asset Business Status by ID

+ + +

findAssetBusinessStatusByName Return Asset Business Status by name

+ + +

findAllAssetBusinessStatuses Return all asset business statuses + + +

CategoryAPIService

Each asset must be assigned at least one category. Categories are the primary and the

required means to group and organize assets. Typically, a category will have many

assets assigned to it, though it is possible to have categories with no assets or just

one asset as well. Categories are organized in a tree structure.

The field names and data types for custom properties, a feature to create additional

fields for assets, are defined at category level. Once assigned to a category, all of the

subcategories for the specified category inherit these fields as well. To set the value

of a custom property, you need to update the asset object.



create Deprecated. Use createCategory instead.

-* -* -*

createCategory Creates category + + +

remove Deprecated. Use removeCategory instead.

-* -* -*

removeCategory removeCategory category + + +

update Deprecated. Use updateCategory instead.

-* -* -*

updateCategory Updates existing category properties.

+ + +

findPopulatedCategoryById Retrieve populated category by id.

+ + +

findAllCategories Retrieve all categories in the system.

+ + +




findCategoryByName Retrieve category by name. + + -

findCategoriesByNames Retrieve categories array by names.

+ + +

moveCategoryParent Moves given category from one parent to another.

+ + +

findRootCategoryTree Returns root category tree with all category hierarchy.

+ + +

DepartmentAPIService

Departments are organized in a tree structure. Assets, areas and users can be

assigned one or more departments.

This is an optional visibility feature, which allows specified users to view only

certain assets and certain maps. For example, this could be used to configure

MobileView such that a certain set of users can only see assets which belong to them.

Alternatively, MobileView can be configured such that users only see certain maps.

To set up this capability, assets can be assigned a department or an area can be

assigned a department, or both. Users are assigned a department and inherit their

viewing options from that department (or child departments) and the assets and

maps it is associated to.

A user can view an asset or an area if:

The user is a member of the same department as the asset or area;

The user is a member of a parent department.

If a user has access to an asset but not to the area where the asset is located, the

asset’s location will appear in the Asset Locator Search results list but not on the

map.

Methods are available for


create Deprecated. Use createDepartment instead.

-* -* -*

createDepartment Create new department. + + +

update Deprecated. Use updateDepartment instead.

-* -* -*

updateDepartment Update department properties. + + +

remove Deprecated. Use removeDepartment instead.

-* -* -*




removeDepartment Remove department. + + +

findPopulatedDepartmentById Return populated department by department id.

+ + +

findAllDepartments Return an array of all departments. + + +

findRootDepartmentTree Return department tree with all department hierarchy.

+ + +

EventAPIService

The EventAPIService can be used for working programmatically with the objects

described above. The API uses slightly different names to describe these objects:

Common Name

API Name Description

Monitor type or even type

Event EventType

Predefined logic and parameters. Used as a basis for creating monitors.

Monitor Event specification

Based on a template, but with specific parameters. Create events automatically when conditions are met.

Event Event The object which represents the date/time a condition was met. Contains information about the specific event such as the asset name, location, etc.



update Deprecated. Use updateEventSpec instead.

-* -* -*

updateEventSpec Update event spec properties. + + +

activate Deprecated. Use activateEventSpec instead.

-* -* -*

activateEventSpec Change EventSpec status to active.

+ + +

suspend Deprecated. Use suspendEventSpec instead.

-* -* -*

suspendEventSpec Change EventSpec status to suspend.

+ + +

remove Deprecated. Use removeEventSpec instead.

-* -* -*

removeEventSpec Remove event spec. + + +

findPopulatedEventSpecById Return populated event spec by event id.

+ + +

findPopulatedEventSpecByName Return populated event spec by event spec name.

+ + +




findAllEventSpecs Return an array of all event spec objects.

+ + +

findAllEventTypes Return and array of all event types.

+ + +

findEventsByCriteria Deprecated. Use findEventsBySearchCriteria instead.

-* -* +

findEventsBySearchCriteria Return Event query result + + -

addOrUpdateCorrectiveAction Add or update event corrective action.

+ + +

findAllCorrectiveActionTypes Return an array of available corrective action types.

+ + -

updateEventStatusAndCorrectiveAction

Update the Event status and its corrective Action

+ + -

findEventById(long id); Returns a fully populated EventDTO with all it's

associations

+ - -

GroupAPIService

Assets can optionally be assigned to groups. Groups are useful for creating a

specified collection of assets that can be used for searching or filtering. For example,

the following can be done with groups:

Searching through the asset locator.

Monitors can use groups to generate events only on assets belonging to a certain

group.

Groups can be selected when generating reports in MobileView to further filter

specific assets on the report output.

When using the MobileView API, it is also possible to use groups as a means to

filter or organize assets.

A group cannot contain another group.

An asset can be assigned to more than one group, or not assigned to any groups.



create Deprecated. Use createGroup instead.

-* -* -*

createGroup Create new group + + +




remove Deprecated. Use removeGroup instead.

-* -* -*

removeGroup Remove + + +

update Deprecated. Use updateGroup instead.

-* -* -*

updateGroup Update group properties. + + +

findPopulatedGroupById Return populated group object by ID.

+ + +

findAllGroups Return an array of all groups + + +

LocatorAPIService

A location report is a key concept in MobileView. It informs that an asset has been

reported at a particular location at a particular time. It also provides additional

information about the tag. Specifically, a location report presents the following

information:

date/time

the asset

the map

the x, y location (on the map)

the zone

A fully qualified location path (e.g. building\floor\zone)

the battery level of the tag

Motion status

Current temperature

Tamperproof status

Telemetry message

(and more)

Location reports are created automatically by MobileView. The API, therefore, only

allows read-only access to location reports.





findAssetCurrentLocation Retrieve asset current location. + + +

findAssetsCurrentLocation Retrieve current location of assets identified by id set on the given map.

+ + +

findAssetsHistoryLocation Retrieve historic locations of a given asset within specified time frame.

+ + +

findAssetsHistoryZone Retrieve historic zones of a given asset within specified time frame.

+ + +

findAssetsCurrentLocationByMap Retrieve page of current location entities identified by map and query control structure.

+ + +

findAssetsCurrentLocationByArea Retrieve page of current location entities identified by area and query control structure.

+ + +

findAssetsCurrentLocationByZone Retrieve page of current location entities identified by zone and query control structure.

+ + +

findAssetsCurrentLocationByCriteria Deprecated. Use findAssetsCurrentLocationBySearchCriteria instead.

-* -* +

findAssetsCurrentLocationBySearchCriteria

Retrieve page of current location entities that match asset criteria and query control structure.

+ + -

findAssetsCurrentLocationBySavedSearch

Retrieve page of current location entities that match locator saved search criteria and query control structure.

+ + -

findAssetsNearAsset Deprecated. Use findAssetsNearAssetByCriteria instead.

-* -* +

findAssetsNearAssetByCriteria Searching for assets near a certain asset.

+ + -

findAssetsNearPoint Deprecated. Use findAssetsNearPointByCriteria instead.

-* -* +

findAssetsNearPointByCriteria Search for assets near a certain location.

+ + -

findAssetsNearAssetBySavedSearch This method is used for searching for assets near a certain asset by saved search.

The radius of the search in centimeters

+ - -



PermissionAPIService

The PermissionAPIService part of MobileView role-based security framework. This

service can be used to generate a list of all security permissions in MobileView. From

this list, the permission can be assigned to roles. When users are assigned roles, they

inherit the permissions assigned. This permission is required for the user to be able

to use the parts of MobileView their specific role allows them to use.

Since MobileView’s permissions are native and hardwired into the application, this

service is read-only.



finadAllPermissions retrieves all permissions + + +

RoleAPIService

Roles are very useful for organizing sets of security permissions which apply to a

collection of users. Roles can be created, edited and assigned users.

Users can be assigned to roles. Roles have permissions. Users inherit their

permissions from roles. One user may be assigned multiple roles.

A role cannot contain another role.



create Deprecated. Use createRole instead. -* -* -*

createRole Create a new role. Return created role id.

+ + +

update Deprecated. Use updateRole instead. -* -* -*

updateRole Update role, return true if updated succeeded, false otherwise.

+ + +

remove Deprecated. Use removeRole instead. -* -* -*

removeRole Remove a roll from DB by role id. + + -

findPopulatedRoleById Return populated role object by id. + + +

findAllRoles Return an array of all roles. + + +

findUsersByRole Return all users that belong to a specific role.

+ + +



SystemAPIService

This service is used to group system calls. Presently there is only one system call.



getMobileViewVersion Return the current MobileView version + + +

getAPIVersion Return the current API MobileView version.

+ + +

isAssetManagerInControll Return true if asset manager is in control, false otherwise.

+ + -

TagAPIService

Tags are assigned to assets. More than one tag can be assigned to an asset. Tags have

a type (e.g. active, passive, etc.).



create Deprecated. Use createTag instead. -* -* -*

createTag Create a new Tag. + + +

remove Deprecated. Use removeTag instead. -* -* -*

removeTag Delete a tag by tag id. + + +

update Deprecated. Use updateTag instead. -* -* -*

updateTag Update tag. + + +

findPopulatedTagById Find a tag by id. Return populated tag. + + +

findPopulatedTagByNetworkId Find a tag by tag network id. Return populated tag.

+ + +

findTagsByCriteria Return Tag query result + + +

makeTagBlink Make tag led blink. + + +

makeTagBlinkForPeriod Make tag led blink. + + +

UserAPIService

A user carries a username and a password. A user must have a role.

User records are used for more than just authentication and role-based security.

Users can have, among others, the following properties:

Contact details (e.g. phone numbers, e-mail);



Regional settings (e.g. time/zone, language, date format);

Employee IDs;

A department (for controlling viewing of maps and assets);



create Deprecated. Use createUser instead -* -* -*

createUser Create a new user, return created user id.

+ + +

update Deprecated. Use updateUser instead -* -* -*

updateUser Update user details + + +

remove Deprecated. Use removeUser instead -* -* -*

removeUser Remove/delete a user by user id + + +

findPopulatedUserById Return fully populated user by id. + + +

findAllUsers Return an array of all users in the system

+ + +

findUsersByDepartmentId Return an array of all users that belong to to a specific department

+ + +

findCurrentUser Return the current user + + +

findCurrentUserWithPermissions

Return the current user + + +

createTempUserCredentials Creates a temp user which is valid for

10 MIN

+ - -

ExciterAPIService

This service provides APIs for receiving information on Exciters. Exciter is an

AeroScout device that triggers very precise and immediate notification when a tag

passes a certain threshold. Exciters are logically located on a map and can trigger

events when assets enter their range.


Service Method Description 4.2.17 4.1.17 4.0.19

findAllExciters Return all exciter entities. + - -

findPopulatedExciterById Retrieves exciter entity with all associations initialized.

+ - -

findExcitersByMapId Return all exciter entities, located on a specific map.

+ - -



MeasurementApiService

This service provides methods for retrieving information on measurements:

Temperature and Humidity are measurements which are part of additional

information that is available for each asset. This feature enables monitoring the asset

condition in a proper way. For each asset a valid range can be defined. A

corresponding event can be configured to fire when the measurements values

exceeds the defined range.



findMeasurementTypes Return available measurement types.

+ + -

findAssetNumericMeasurementCondition

Return asset measurement condition by measurement type. Return null if.

+ + -

findAssetNumericMeasurementsCondition

Return asset measurements conditions Return empty array if no measurement

+ + -

findAssetMeasurementResult Return asset current measurement results for specific asset.

+ + -

findAssetsMeasurementResultByIds Return assets current measurement results for list of assets.

+ + -

findAssetsMeasurementResultByCriteria

Return a page of assets current measurement results for asset entities

+ + -

findAssetsMeasurementHistoryResults

Return asset historic measurement results.

+ + -

SavedSearchApiService

This service provides APIs for retrieving saved searches. A Saved Search entity has a

type attribute that defines the search type - currently only 'Asset Locator Search' is

available. Creating, updating and deleting saved searched is available from

MobileView UI only.


findById Get saved search object by ID. + + -

findByName Find array of saved search objects by name.

+ + -

findMySavedSearches Returns the saved searches that the current user has permission to use

+ + -


Chapter 2 Enhancement and Bug Fixes 31

4 Enhancement and Bug Fixes

The following list contains fixes and enhancements made to MobileView versions

4.3.0.20, 4.2.17 and 4.1.17:

Enhancements

Enhancements MobileView 4.3.0.20

Send customized messages using the available actions types. Please refer to section

Customized Text Messages for a more detailed description.

Temporary User Credentials Feature

Logging on to MV4 through direct links requires a user name and password to be

part of the URL. A new API function is provided which creates temporary

credentials that can be used for direct link access.

Make Asset tags led blink on specific Exciter

A specific Exciter is transmitting the make tag blink command to the tag. A new

method is provided to send make asset tags blink with a specific exciter.

Enhancements in MobileView 4.2.17

New API services were added to MobileView, please refer to the relevant section

for detailed information.

ExciterAPIService

MeasurementApiService

SavedSearchApiService

http://www.vocera.com/ts/updates/4.1/vrs/ReleaseNotes_vrs41SP5.html#WhatsFixed



Additional alert fields were added. Please refer to Action and Message Types for

a complete list of fields.

Zone Type find methods were added to the AreaAPIService. MobileView Zone

types are logical grouping of zones.

The configured custom location string pattern can be retrieved over the

AreaAPIService. The FormattedLocationPath field in MobileView Alerts contains

the location sting that meets the custom location pattern. For example:

Location pattern: "{BUILDING}/{FLOOR}/{AREA}/{ZONE_STR}"

Location string: "Building 1/Floor 1/Nursing Unit/Room 107"

MobileView Entities can now be retrieved by Search Criteria and updated by a

predefined layout that specifies the properties of concern. The Search Criteria are

similar to search by criteria; except that the specified properties can be retrieved.

Enhancements in MobileView 4.1.17

New function in System API Service getAPIVersion.

Bug Fixes

Bug Fixes in MobileView 4.3.0.20

Component Description Bug #

Locator API Service Exception while calling locator API. 14584

Tag API Service Updating an associated tag cause exception 14129

Asset API Service

The Activity Status is a mandatory

Field that must be provided. The Asset Api

Service Fails due to a "NullPointerException" 13938

http://bugzilla.corp.aeroscout.com/bugzilla/show_bug.cgi?id=14584





Bug Fixes in MobileView 4.2.17


API Documentation

Improved java documentation. 8108

8207

10354

12372

12395

12958

Asset API Service

When calling the findAssetsLocation Service

from the Asset API the primary category is

now available

10558

The call findAssetsByCriteria failed no order

property was set.

12072

Wrong exception was thrown when asset was

created or updated

12356, 12612

Assets with an category mismatch could be

created over the API

12359, 12363

Remove Asset from CategoryDTO and

DepartmentDTO (RN)

10325

There arenג€™t any validation errors for

criteriaDTOs objects.

11177

User API Service

The retrieved UserDTO object from the service

findPopulatedUserById didn’t return version

information.

10972

Department API

Service

Allowed to update department with lower

version then the db entity.

10322

Update Department resulted in an optimistic

looking error

12614

Area API Service

No gateway information was available in the

MapDTO object.

10324

Remove MapId from AssetDTO. 8347






















Bug Fixes in MobileView 4.1.17


Asset API Service

possible to assign assets to "all asset" category

over API 7395

Failed to update Asset with custom properties. 8121

Fixed error messages 10272

Tag API Service

The method findPopulatedTagByNetworkId

should not be case sensitive 7956

Fixed error messages 10336

Area API Service The removeArea method call returns deleted

department 9870

Category API Service

The getIcon method should return byte[] and

not filename 7959

Get populated category returns all assets that

associated with the category. 8415

User API Service

Role based security is not enforced for API

calls. 9006

Fixed error message 8210

Department API

Service

The removeDepartment call returns deleted

department 9838

Alert Fields

Telemetry field should contain 512 characters.

(instead 55) 8022

JMS alert should have XML message and Map

object message only. 8122

Date in JMS and Xml Aelrts should be long and

not String. 8166

Spelling mistake in Xml send via Web Service -

hexStoredDate. 8105

Event API Service

Failed to update event spec. - Integrity

Violation 8207

The findEventsByCriteria function doesn't

work if the fromDate field is not specify. 9057



















Chapter 3 Appendix A – Troubleshooting Tips 35

3 Appendix A – Troubleshooting Tips

Ping the server IP at the command prompt to make sure you are connected to the server.

Make sure the credentials are entered correctly.

Make sure the server does not have a firewall blocking the connection.

Make sure that asset and tag details are correct.

Make sure you are not creating an existing tag. For example,

Adding a tag MAC which exists already

Adding an asset with the same asset name (and application ID).

Make sure that all involved assets and tags are in working order.


Chapter 4 Appendix B - Code Samples 36

4 Appendix B - Code Samples

Contact AeroScout to obtain code samples to help expedite development. Examples

are available in Java and C#. For a full description of all available samples, please

refer to MobileView Integration Tools document.

About AeroScout

AeroScout is the market leader in Unified Asset Visibility solutions. Clients improve operational

efficiency and quality using AeroScout products that leverage standard Wi-Fi networks to track and

manage the location, condition and status of mobile assets and people. AeroScout’s global customer

base consists of leading hospital, manufacturing and logistics organizations, including many of the

Fortune 500. The company originally invented the first Wi-Fi-based Active RFID tag, and today is

widely recognized as leading the market in number of deployments and tags shipped. Headquartered

in Redwood City, Calif., AeroScout has offices in Europe, Asia, the Middle East, Latin America and

Australia. For more information, please visit www.aeroscout.com.

AeroScout (Headquarters)

1300 Island Drive

Suite 202

Redwood City, CA 94065

Tel: +1 (650) 596-2994

Fax: +1 (650) 596-2969

E-mail: [email protected]

Europe, Middle East, Africa Office

Tel : +32 2 709 29 49

Fax : +32 15 30 80 99


Japan Office

Tel: +81 3 3556 9003

Fax: + 81 3 5875 3723


Latin America Office

Tel : +52 55 5001 5769


Asia-Pacific Sales

Tel : +1 650 596 2994


Australia and New Zealand Sales

Tel : +61 3 9038 8690


http://www.aeroscout.com/

MobileView 4.2 Integration Guide - AeroScout 4.2 Integration Guide Table of Contents 3 Table of...

Documents

Transcript of MobileView 4.2 Integration Guide - AeroScout 4.2 Integration Guide Table of Contents 3 Table of...