Trademarks
All trademarks and registered trademarks are the property of their respective owners.
Copyright Notice/Restrictions
Copyright © 2015 Transition Networks. All rights reserved.
No part of this work may be reproduced or used in any form or by any means (graphic, electronic or mechanical) without written permission from Transition Networks.
The information contained herein is confidential property of Transition Networks, Inc. The use, copying, transfer or disclosure of such information is prohibited except by express written agreement with Transition Networks, Inc.
Printed in the U.S.A.
Converge™ EMS API Guide for Real-time Data Collection PN 33630 Rev. A
Contact Information
Transition Networks 10900 Red Circle Drive Minnetonka, MN 55343 USA Tel: 952- 941-7600 or 1-800-526-9267 Fax: 952-941-2322
Revision History
Rev Date Description
A 05/22/15 Initial release with Converge EMS API version 1.3.0.
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Table of Contents
Table of Contents __________________________________________________ 3
Preface _________________________________________________________ 4
Purpose of document _____________________________________________________ 4
Scope ________________________________________________________________ 4
Intended Audience _______________________________________________________ 4
Typographical Conventions _________________________________________________ 5
Glossary ________________________________________________________ 6
Related Documents ______________________________________________________________ 6
Device Firmware Version Requirements _______________________________________________ 6
Overview ________________________________________________________ 7
Requirements for HTTP Requests ____________________________________________ 8
Requirements for HTTP Responses ___________________________________________ 9
Real-time Collections RESTful Endpoints _____________________________________ 10
Real-time Collections JAVA API ______________________________________ 11
PerformanceManagementRetrievalService.java __________________________________ 11
Real-time Collections REST Web Services API Requests _____________________ 13
Login _______________________________________________________________ 13
Login Request Example __________________________________________________________ 14
Login Response ________________________________________________________________ 14
Login Response Example (OK) _____________________________________________________ 14
Login Response Example (Unauthorized) _____________________________________________ 14
Start Real-time Collection _________________________________________________ 16
Start Real-time Collection Request Example ___________________________________________ 17
Start Real-time Collection Response Example __________________________________________ 19
Subscribe for Statistics ___________________________________________________ 20
REQUEST EXAMPLE __________________________________________________________ 20
RESPONSE EXAMPLE _________________________________________________________ 21
Stop Real-time Collection _________________________________________________ 24
Stop Real-time Collection Request Example ___________________________________________ 25
Stop Real-time Collection Response Example __________________________________________ 25
Delete Real-time Collection ________________________________________________ 26
Delete Real-time Collection Request Example __________________________________________ 27
Delete Real-time Collection Response Example _________________________________________ 27
Index __________________________________________________________ 28
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Preface
Purpose of document
The purpose of this document is to explain how to integrate with Converge™ EMS API and formulate HTTP requests for collection of real-time performance data.
Scope
The present document provides a description of JAVA and RESTful APIs for collection of real-time performance data in Converge™ EMS. Real-time data collections refer to collection of performance data executed on-demand from the context of a selected measurement component (e.g. a port, device, or VLAN) for a choice of performance counters. The Overview describes generic requirements for RESTful HTTP requests and responses, and provides a list of Real-time Collections RESTful Endpoints. Chapter Real-time Collections JAVA API lists all JAVA interfaces that are used to manage real-time data collections, while chapter Real-time Collections REST Web Services API Requests provides examples of RESTful API calls that execute different real-time data collection operations.
Intended Audience
The intended audience of the present document are EMS developers who want to execute and manage real-time statistics collections via Converge™ EMS APIs. Warning: This manual is for use by Licensed Users only.
Warning: The exact format of the presented HTTP requests and responses may be different when using various API tools.
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Typographical Conventions
The following typographical conventions apply throughout this document:
Commands, options, windows, dialogs
Command and options names are presented in bold type. Names of windows and dialogs also appear in bold type.
‘Object Names’ Object names appear in inverted commas.
User-supplied information
Variable information, e.g. logins, passwords, other user-supplied data, appears in italic type.
Hyperlinks Hyperlinks are presented in underlined blue type.
Code and cmd
commands
Fragments of code and cmd commands are presented in the Consolas font.
[ENTER] Names of GUI buttons appear in square brackets and are printed in the Consolas font.
Note:
Guidelines which are particularly important are distinguished with a notepad and quill symbol, the blue bold type and a ‘Note’ tag.
See also: References to other Converge™ EMS documents are distinguished with a plus symbol, the violet bold type and a ‘See also’ tag.
Warning: Warnings for operations that may result in serious consequences are distinguished with an exclamation mark, the red bold type and a ‘Warning’ tag.
Tip:
Useful tips are distinguished with a light bulb symbol, the
green bold type, and a ‘Tip’ tag.
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Glossary API
Application Programming Interface CRUD
Create, Read, Update, Delete
EMS
Element Management System
GUI
Graphical User Interface
HTTP
Hypertext Transfer Protocol
OSS
Operations Support System
REST
Representational State Transfer
URL
Uniform Resource Locator
Related Documents
Converge EMS API Guide for Common RESTful API (33619): describes the REST Web Services Interface provided by Converge EMS and used for integration with other software applications. Converge EMS API Guide for Service Activation API (33620): explains how to integrate with Converge EMS API and formulate HTTP requests for activation of services and service components. Converge EMS API Service Model Overview (33621): a generic document that describes Service Inventory and Design metamodel classes and fields, and provides explanation of service objects.
Device Firmware Version Requirements
Managed devices should be at the latest version available (e.g., S3290 v 1.9.4 or above).
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Overview
Converge™ EMS API – Application Programming Interface, makes it possible for third-party developers to integrate applications with Converge™ EMS. The Converge API provides access to resources via URI paths, and it has been designed to comply with the Representational State Transfer (REST) style recommendations.
The communication is implemented using the XML format over the HTTP protocol (RESTful XML).
Figure 1: Converge™ EMS Transaction Formats
See also: Please refer to Converge™ EMS API Guide – Common RESTful API to learn about REST Web Services Interface, basic transactions, and the syntax for basic requests and responses.
All API access is handled via the http://a.b.c.d:port/<contextRoot>/rest/ domain, where ‘contextRoot’ can be either convergeEMS, or any other, as modified for a specific vendor solution. For example: PUT http://localhost:8080/convergeEMS/rest/security/login HTTP/1.1.
The requirements for the HTTP request format are listed below, in HTTP Requests.
The requirements for the HTTP response format are listed in HTTP Responses.
A list of RESTful endpoints used for real-time collections API is provided in Real-time Collections RESTful Endpoints.
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Requirements for HTTP Requests
The following are the requirements for the HTTP messages sent to Converge™ EMS over the REST Web Services API:
Element Requirement
HTTP Message Type Request (mandatory)
HTTP Message must contain a header (the content of which depends on the endpoint and the method)
may contain a message body (only for some endpoints and methods)
HTTP Version HTTP/1.1
HTTP Methods GET – retrieves or read a representation of a resource in XML or JSON; the desired Status Code for this operation is 200 (OK)
PUT – updates (or creates) a resource on the basis of the request information; the desired Status Code for this operation is 200 (OK) for a successful update along with the content of the response body, 204 (NO CONTENT) if no content is returned in the body but the resource has been updated, or 201 (CREATED) upon successful creation
POST – creates resources, in particular subordinate ones; the desired Status Code for this operation is 201 (CREATED)
DELETE – deletes resources identified by a URI; the desired Status Code for this operation is 200 (OK) along with a response body, or 204 (NO CONTENT) if no content is returned but the resource has been deleted
URL Must contain:
the context root path
the endpoint path (which defines a specific Converge™ EMS interface)
the resource path (which contains either the resource for the CRUD type interface, or a method name for other interface types)
Table 1: Requirements for HTTP Requests
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Requirements for HTTP Responses
Converge™ EMS sends responses to each request sent over the API. The response must comply with the following requirements:
Element Requirement
HTTP Message Type Response (mandatory)
HTTP Message must contain a header (the content of which depends on the endpoint and the method in the corresponding Request)
may contain a message body (only for some endpoints and methods in the corresponding Request)
HTTP Version HTTP/1.1
Status Codes OK (200) – the request has succeeded; the information returned in the response depends on the method used in the request
CREATED (201) – the request has been fulfilled and a new resource has been created
NO CONTENT (204) – the request has been fulfilled but does not need to return the message body (this response may include new or updated information in the header)
UNAUTHORIZED (401) – the request requires user authentication
FORBIDDEN (403) – the request has been recognised, but the server has refused to fulfil it
INVALID DATA (456) – the request has been rejected due to incorrect data that could not be validated
INTERNAL SERVER ERROR (500) – the request could not be fulfilled due to an unexpected server error
Table 2: Requirements for HTTP Responses
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Real-time Collections RESTful Endpoints
The common REST Web Services endpoint is <contextRoot>/rest, where ‘contextRoot’ can be either convergeEMS, or any other, as modified for a specific vendor solution. The following table lists all endpoints used for performance management via RESTful API:
Endpoint Endpoint URL Endpoint Description
Authentication
Endpoint
<contextRoot>/rest/
security Security endpoint for login and logout.
Basic security requests are provided in Converge™ EMS API Guide – Common RESTful API.
Domain Objects
Endpoint
<contextRoot>/rest/
domainObjects Endpoint for Domain Object API. Used for managing CRUD access to the Domain Objects (e.g. Collection Tasks).
Business
Component
Endpoint
<contextRoot>/rest/
businessLogic Endpoint for Business Component API.
Used for invocation of Business Components methods (e.g. creation of collection tasks).
Table 3: Real-time Collections RESTful Endpoints
Note: For Domain Object endpoints it is possible to add query parameters, start and limit. Start specifies the index of the first object return, and limit specified the maximum number of instances to return.
For example: <contextRoot>/rest/domainObjects/CollectionTask?start=0&limit=4
returns Collection Tasks with indexes 0 to 4.
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Real-time Collections JAVA API
JAVA services for real-time collections are available in the following common-mgt subdirectory: businesslogic/performance/src/main/java/com/transition/unifiedmanager/business/com
ponents/performance/. The real-time collections JAVA service available in this directory – ‘PerformanceManagementRetrievalService.java’, allows management of real-time data collections.
PerformanceManagementRetrievalService.java
public interface PerformanceManagementRetrievalService
The PerformanceManagementRetrievalService interface allows management of ‘Collection Task’ metamodel class objects for real-time data collections.
Method summary
stopCollection (DomainObject
collectionTask)Saves a specific data collection template with a list of statistics.
deleteCollection(DomainObject
collectionTask)Deletes a specific data collection template.
startCollection(DomainObject
collectionTask) throws ExceptionStarts real-time collection of data from the context of the provided measurement component object (a device, port, VLAN, SAP, etc.).
Table 4: PerformanceManagementRetrievalService Method Summary
Details of each method are provided below.
stopCollection
public void stopCollection (DomainObject collectionTask);
Stop a running real-time data collection task.
Parameters
collectionTask – the collection task to stop
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
deleteCollection
public void deleteCollection(DomainObject collectionTask);
Deletes a data collection task.
Parameters
collectionTask – the collection task to delete
startCollection
public void startCollection(DomainObject collectionTask) throws Exception;
Starts a real-time data collection task.
Parameters
collectionTask – the collection task to start
Throws Exception – exception thrown if start fails
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Real-time Collections REST Web Services API Requests
This chapter provides examples of basic RESTful API requests and responses for PerformanceManagementRetrievalService JAVA interfaces, as well as API requests to log in to the system. Some HTTP requests require input of metamodel instance (Domain Object) attributes and values (e.g. for creation or deletion of data collection tasks). All attributes of a particular metamodel class are described in the model_home/metamodel directory of Converge™ EMS, in a respective meta.xml file.
Login
The first step is to log in to the application and obtain the authorization key that is needed to proceed with any other operations via API.
Description Logs in a new user
HTTP Method PUT
URL http://a.b.c.d:port/<contextRoot>/rest/security/login
Header Not required
Message Body The following information in the xml format must be included in the message body:
<login><username>name</username><password>value</password></login>
Table 5: Login Request
Note: Login can be replaced with a Web Login to provide for a web browser login via a web form.
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Login Request Example
PUT http://localhost:8080/convergeEMS/rest/security/login HTTP/1.1
Accept‐Encoding: gzip,deflate
Accept: text/plain
Content‐Type: application/xml
Content‐Length: 73
Host: localhost:8080
Connection: Keep‐Alive
User‐Agent: Apache‐HttpClient/4.1.1 (java 1.5)
<login><username>admin</username><password>adminpassword</password></login>
Login Response
If the login is successful, the token is returned in the message body with the Status OK (200). The returned token must be used in all subsequent messages in the ‘Authorization’ header. The token value is stored in the ${AUTH} variable.
If the login fails, for example due to incorrect credentials, the UNAUTHORIZED (401) Status is returned.
Login Response Example (OK)
HTTP/1.1 200 OK
Server: Apache‐Coyote/1.1
Set‐Cookie: JSESSIONID=D38E9D0E460311BFEB5AD3FEDBD68796; Path=/convergeEMS/;
HttpOnly
Content‐Type: text/plain
Transfer‐Encoding: chunked
Date: Friday, 22 May 2015 10:25:20 GMT
admin‐‐ D38E9D0E460311BFEB5AD3FEDBD68796
Login Response Example (Unauthorized)
HTTP/1.1 401 Unauthorized
Server: Apache‐Coyote/1.1
ErrorMessage: User Un‐Authorized
WWW‐Authenticate: TOKEN
Content‐Type: text/plain
Transfer‐Encoding: chunked
Date: Friday, 22 May 2015 10:25:20 GMT
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
User Un‐Authorized
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Start Real-time Collection
This request starts the provided real-time collection of data from the context of a selected object (e.g. port, device).
Description Starts a provided real-time data collection.
HTTP Method POST
URL http://a.b.c.d:port/<contextRoot>/rest/businessLogic/spring:performa
nceManagementRetrievalService/startCollection
Header Obligatory:
‘Authorization’ header containing the token (e.g. TOKEN admin-- 3510EBCC2B5555AEBA3FEA6F6EFF3DE5)
Message Body Contains Request Payload with specification of the real-time collection to start. See Start Real-time Collection Request Example.
Table 6: Start Real-time Collection Request
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Start Real-time Collection Request Example
Header
POST
http://localhost:8080/convergeEMS/rest/businessLogic/spring:performanceManagementRetr
ievalService/startCollection HTTP/1.1
Accept‐Encoding: gzip,deflate
Authorization: TOKEN admin‐‐ 3510EBCC2B5555AEBA3FEA6F6EFF3DE5
Host: localhost:8080
Connection: Keep‐Alive
User‐Agent: Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like
Gecko) Chrome/42.0.2311.152 Safari/537.36
Message Body
<list>
<CollectionTask expanded="no">
<collectionInterval>5</collectionInterval>
<name>admin‐‐E956C2FC6A92CD474ADA0FAA07819A84‐‐
1432111525158.1432111747922</name>
</CollectionTask>
<InterfaceInStatsSpec expanded="no">
<name>Acme:01</name>
<namingOs>convergeEMS</namingOs>
<owner>Acme</owner>
<discoveredHiddenId>1</discoveredHiddenId>
<discoveredName>Port 1</discoveredName>
<objectName>Acme:01</objectName>
<ifInOctets>true</ifInOctets>
<ifInNUcastPkts>true</ifInNUcastPkts>
</InterfaceInStatsSpec>
<InterfaceOutStatsSpec expanded="no">
<name>Acme:01</name>
<namingOs>convergeEMS</namingOs>
<owner>Acme</owner>
<discoveredHiddenId>1</discoveredHiddenId>
<discoveredName>Port 1</discoveredName>
<objectName>Acme:01</objectName>
<ifOutOctets>true</ifOutOctets>
</InterfaceOutStatsSpec>
</list>
Where:
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
<CollectionTask> provides the details of the collection task to be launched, including the <collectionInterval> at which data is collected, and <name> - a unique identifier of the task. Task name in the above example uses the session ID from the GUI, but this can be replaced by any value, as long as it is unique.
<InterfaceInStatsSpec> specifies data collection Spec used in this real-time collection. This is example-specific value, any other data Specs can be used instead. The <name> of each statistics Spec is the same as <objectName> of the measurement component (the object from which statistics are collected, e.g. a device, port, VLAN or MEP). The attributes <owner>, <discoveredName>, <discoveredHiddenId> and <objectName> are taken from the measurement component object. Each Spec includes some counters, here <ifInOctets> and <ifInNUcastPkts>. The maximum number of counters passed in a request depends on the settings defined in the ‘RealTimeStatsSpecification’, which defines default settings for real-time collections.
Data collection Specs for Service objects, i.e. SAPs and Service Components, include an additional field, <role> of this object in a service. See the following example:
<list>
<CollectionTask expanded="no">
<collectionInterval>15</collectionInterval>
<name>admin‐‐E956C2FC6A92CD474ADA0FAA07819A84‐‐
1432111525158.1432285142929</name>
</CollectionTask>
<InterfaceInStatsSpec expanded="no">
<name>Acme:02</name>
<namingOs>convergeEMS</namingOs>
<owner>Acme</owner>
<discoveredHiddenId>2</discoveredHiddenId>
<discoveredName>Port 2</discoveredName>
<role>UNI</role>
<objectName>Acme:02</objectName>
<ifInOctets>true</ifInOctets>
</InterfaceInStatsSpec>
</list>
If the request is successful, the Status of the response is OK (200) and the real-time collection with the specified characteristics is started. Otherwise, an exception is thrown.
Warning: Once a collection is started, the user has to subscribe for events on the collected statistics. See Subscribe for Statistics.
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Start Real-time Collection Response Example
HTTP/1.1 200 OK
Server: Apache‐Coyote/1.1
Content‐Length: 0
Date: Mon, 18 May 2015 11:48:25 GMT
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Subscribe for Statistics
In order to receive data from a launched real-time collection, use WebSocket API to subscribe for notifications about incoming statistics.
Note: Detailed information on object notification subscription is provided in the document Converge™ EMS API Guide – Object Notifications.
REQUEST EXAMPLE
To register for a statistics object notifications, initialize WebSocket connection, and send the following request to listen for data collection results (here for two Stats objects):
{"filter":null,"object":"InterfaceInStats","subscriber":"admin‐‐
E956C2FC6A92CD474ADA0FAA07819A84‐‐
1432111525158.1432111747922","type":"SUBSCRIBE"},
{"filter":null,"object":"InterfaceOutStats","subscriber":"admin‐‐
E956C2FC6A92CD474ADA0FAA07819A84‐‐
1432111525158.1432111747922","type":"SUBSCRIBE"},
where:
Field Example Value Description
filter null PLANNED FOR FUTURE RELEASES
XML filter on the subscriber, which allows narrowing down the scope of notifications.
If a filter is passed in a request, then only notifications that meet its criteria are returned.
object InterfaceInStats Name of the Stats Spec metamodel class for which the user wants to receive notifications about collected data.
subscriber admin--E956C2FC6A92CD474ADA0FAA07819A84--1432111525158.1432111747922
Local Id of the subscriber used to distinguish between multiple subscriptions for the same object from different processes that use the same connection.
This has to correspond to the <CollectionTask> <name> attribute of the Start Real-time Collection Request.
type SUBSCRIBE Always set to ‘SUBSCRIBE’.
Type of transaction.
Table 7: Subscribe for Statistics Registration Details
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
RESPONSE EXAMPLE
The following is an example of messages received to the above request. Messages are printed as a continuous string of characters, but here they are broken down into separate lines for clarity:
{"subscriber":"admin‐‐E956C2FC6A92CD474ADA0FAA07819A84‐‐1432111525158.1432111747922","filter":null,"type":"create","object":"
<InterfaceOutStats classVersion=\ " expanded=\ " no \>
<name>admin‐‐E956C2FC6A92CD474ADA0FAA07819A84‐‐1432111525158.1432111747922</name>
<taskRef>admin‐‐E956C2FC6A92CD474ADA0FAA07819A84‐‐1432111525158.1432111747922</taskRef>
<collectionType>REAL‐TIME</collectionType>
<objectName>ACME:01</objectName>
<createdBy>System</createdBy>
<createDate>05/21/2015 18:08:25:338 +0100</createDate>
<owner>Acme</owner>
<namingOs>convergeEMS</namingOs>
<planned>true</planned>
<discoveredName>N/A</discoveredName>
<discoveredHiddenId>1</discoveredHiddenId>
<ifOutMulticastPkts>43867</ifOutMulticastPkts>
<ifOutBroadcastPkts>4</ifOutBroadcastPkts>
<ifHCOutOctets>7193081</ifHCOutOctets>
<ifHCOutUcastPkts>25113</ifHCOutUcastPkts>
<ifHCOutMulticastPkts>43867</ifHCOutMulticastPkts>
<ifHCOutBroadcastPkts>4</ifHCOutBroadcastPkts>
<ifOutOctets>7193081</ifOutOctets>
<ifOutUcastPkts>25113</ifOutUcastPkts>
<ifOutNUcastPkts>43871</ifOutNUcastPkts>
<ifOutDiscards>0</ifOutDiscards>
<ifOutErrors>0</ifOutErrors>
<ifOutQLen>0</ifOutQLen>
<timeStamp>05/21/2015 18:08:25:337 +0100</timeStamp>
</InterfaceOutStats>”,
"objectId":"admin‐‐E956C2FC6A92CD474ADA0FAA07819A84‐‐1432111525158.1432111747922","objectMetaClass":null}
{"subscriber":"admin‐‐E956C2FC6A92CD474ADA0FAA07819A84‐‐1432111525158.1432111747922","filter":null,"type":"create","object":"
<InterfaceInStats classVersion=\ " expanded=\ " no \>
<name>admin‐‐E956C2FC6A92CD474ADA0FAA07819A84‐‐1432111525158.1432111747922</name>
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
<taskRef>admin‐‐E956C2FC6A92CD474ADA0FAA07819A84‐‐1432111525158.1432111747922</taskRef>
<collectionType>REAL‐TIME</collectionType>
<objectName>ACME:01</objectName>
<createdBy>System</createdBy>
<createDate>05/21/2015 18:10:14:101 +0100</createDate>
<owner>Acme</owner>
<namingOs>convergeEMS</namingOs>
<planned>true</planned>
<discoveredName>N/A</discoveredName>
<discoveredHiddenId>1</discoveredHiddenId>
<ifInMulticastPkts>1329</ifInMulticastPkts>
<ifInBroadcastPkts>11</ifInBroadcastPkts>
<ifHCInOctets>1802207</ifHCInOctets>
<ifHCInUcastPkts>24523</ifHCInUcastPkts>
<ifHCInMulticastPkts>1329</ifHCInMulticastPkts>
<ifHCInBroadcastPkts>11</ifHCInBroadcastPkts>
<ifInOctets>1802207</ifInOctets>
<ifInUcastPkts>24523</ifInUcastPkts>
<ifInNUcastPkts>1340</ifInNUcastPkts>
<ifInDiscards>0</ifInDiscards>
<ifInErrors>0</ifInErrors>
<ifInUnknownProtos>0</ifInUnknownProtos>
<timeStamp>05/21/2015 18:10:14:100 +0100</timeStamp>
</InterfaceInStats>",
"objectId":"admin‐‐E956C2FC6A92CD474ADA0FAA07819A84‐‐1432111525158.1432111747922","objectMetaClass":null}
Note: To find the response for the desired collection, filter out the results using the <taskRef> field value. The field provides the collection task name, see the highlighted sections above.
The following table provides the details of the response parameters:
Field Example Value Description
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
subscriber admin--E956C2FC6A92CD474ADA0FAA07819A84--1432111525158.1432111747922
Local Id of the subscriber.
Corresponds to subscriber in the request call.
filter null PLANNED FOR FUTURE RELEASES
XML filter on the subscriber, which allows narrowing down the scope of notifications.
If a filter is passed in a request, then only notifications that meet its criteria are returned.
type create One of create, update, delete operations that triggered the notification.
object <InterfaceOutStats…>
Details of the returned statistics Spec serialized to XML and escaped Domain Object (notification).
objectId admin--E956C2FC6A92CD474ADA0FAA07819A84--1432111525158.1432111747922
Name of the returned object retrieved with the method eventObject.getName().
objectMetaClass null DEPRECATED attribute that pointed to the metamodel class of the returned statistics.
Table 8: Subscribe for Statistics Response Details
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Stop Real-time Collection
This request stops the provided real-time collection of data.
Description Stops a provided real-time data collection.
HTTP Method POST
URL http://a.b.c.d:port/<contextRoot>/rest/businessLogic/spring:performa
nceManagementRetrievalService/stopCollection
Header Obligatory:
‘Authorization’ header containing the token (e.g. TOKEN admin-- 3510EBCC2B5555AEBA3FEA6F6EFF3DE5)
Message Body Contains Request Payload with specification of the real-time collection to stop. See Stop Real-time Collection Request Example.
Table 9: Stop Real-time Collection Request
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Stop Real-time Collection Request Example
Header
POST
http://localhost:8080/convergeEMS/rest/businessLogic/spring:performanceManagementRetr
ievalService/stopCollection HTTP/1.1
Accept‐Encoding: gzip,deflate
Authorization: TOKEN admin‐‐ 3510EBCC2B5555AEBA3FEA6F6EFF3DE5
Host: localhost:8080
Connection: Keep‐Alive
User‐Agent: Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like
Gecko) Chrome/42.0.2311.152 Safari/537.36
Message Body
<CollectionTask expanded="no">
<collectionInterval>5</collectionInterval>
<name>admin‐‐E956C2FC6A92CD474ADA0FAA07819A84‐‐
1432111525158.1432111747922</name>
</CollectionTask>
Where:
<CollectionTask> provides the details of the collection task to stop. The task is identified by <collectionInterval> at which data is collected, and <name> - a unique identifier of the task.
If the request is successful, the Status of the response is OK (200) and the provided real-time collection is stopped.
Stop Real-time Collection Response Example
HTTP/1.1 200 OK
Server: Apache‐Coyote/1.1
Content‐Length: 0
Date: Mon, 18 May 2015 11:48:25 GMT
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Delete Real-time Collection
This request deletes the provided real-time collection of data. While ‘stopCollection’ only pauses a collection, and makes it possible to restart again, ‘deleteCollection’ permanently removes it from the database so that it cannot be recovered.
Description Permanently removes a provided real-time data collection.
HTTP Method POST
URL http://a.b.c.d:port/<contextRoot>/rest/businessLogic/spring:performa
nceManagementRetrievalService/deleteCollection
Header Obligatory:
‘Authorization’ header containing the token (e.g. TOKEN admin-- 3510EBCC2B5555AEBA3FEA6F6EFF3DE5)
Message Body Contains Request Payload with specification of the real-time collection to delete. See Delete Real-time Collection Request Example.
Table 10: Delete Real-time Collection Request
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Delete Real-time Collection Request Example
Header
POST
http://localhost:8080/convergeEMS/rest/businessLogic/spring:performanceManagementRetr
ievalService/stopCollection HTTP/1.1
Accept‐Encoding: gzip,deflate
Authorization: TOKEN admin‐‐ 3510EBCC2B5555AEBA3FEA6F6EFF3DE5
Host: localhost:8080
Connection: Keep‐Alive
User‐Agent: Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like
Gecko) Chrome/42.0.2311.152 Safari/537.36
Message Body
<CollectionTask expanded="no">
<collectionInterval>5</collectionInterval>
<name>admin‐‐E956C2FC6A92CD474ADA0FAA07819A84‐‐
1432111525158.1432111747922</name>
</CollectionTask>
Where:
<CollectionTask> provides the details of the collection task to delete. The task is identified by <collectionInterval> at which data is collected, and <name> - a unique identifier of the task.
If the request is successful, the Status of the response is OK (200) and the provided real-time collection is deleted.
Delete Real-time Collection Response Example
HTTP/1.1 200 OK
Server: Apache‐Coyote/1.1
Content‐Length: 0
Date: Mon, 18 May 2015 11:48:25 GMT
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Index
A
API Overview, 7
Authentication Endpoint, 10
B
Basic Information, 7
Business Component Endpoint, 10
C
CollectionTemplateService.java, 11
CREATED, 9
D
DELETE, 8
Delete Real‐time Collection, 26 Request Example, 27 Response Example, 27
Domain Objects Endpoint, 10
E
Endpoints, 10
F
FORBIDDEN, 9
G
GET, 8
Glossary, 6
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
H
HTTP Requests, 8 DELETE, 8 GET, 8 HTTP Message, 8
HTTP Message Type, 8
HTTP Methods, 8
HTTP Version, 8 POST, 8 PUT, 8 URL, 8
HTTP Responses, 9 HTTP Message, 9
HTTP Message Type, 9
Status Codes, 9
I
INTERNAL SERVER ERROR, 9
INVALID DATA, 9
J
JAVA API, 11 CollectionTemplateService.java, 11
L
Login, 13 Request Example, 14 Response, 14 Response Example (OK), 14 Response Example (Unauthorized), 14
N
NO CONTENT, 9
Notification Response filter, 23 object, 23 objectId, 23 objectMetaClass, 23 subscriber, 23 type, 23
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
O
OK, 9
P
POST, 8
PUT, 8
R
Real‐time Collections JAVA API, 11
Real‐time Collections RESTful API, 13
Registration for Notifications object, 20 subscriber, 20 type, 20
RESTful Endpoints, 10
S
Start Real‐time Collection, 16 Request Example, 17 Response Example, 18
Status Codes 200, 9 201, 9 204, 9 401, 9 403, 9 456, 9 500, 9 CREATED, 9 FORBIDDEN, 9 INTERNAL SERVER ERROR, 9 INVALID DATA, 9 NO CONTENT, 9 OK, 9 UNAUTHORIZED, 9
Stop Real‐time Collection, 24 Request Example, 25 Response Example, 25
Subscribe for Statistics, 20 Request, 20 Response, 21
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
T
Typographical Conventions, 5
U
UNAUTHORIZED, 9
Transition Networks Converge™ EMS API Guide - Real-time Data Collection
33630 Rev A www.transition.com Page 49 of 51
Transition Networks
10900 Red Circle Drive
Minnetonka, MN 55343 USA
Tel: 952- 941-7600 or 1-800-526-9267
Fax: 952-941-2322
Copyright© 2015 Transition Networks
All rights reserved.
Printed in the U.S.A.
Converge™ EMS API Guide for Real-time Data Collection PN 33630 Rev. A