33619 A - Converge EMS API Guide for Common RESTful API · Fax: 952-941-2322 Revision History Rev...

Converge™ EMS API

Guide for Common RESTful API Software Version 1.3.0

33619 Rev. A

Transition Networks ConvergeTM EMS API Guide for Common RESTful API

33619 Rev. A www.transition.com of 69

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 Common RESTful API Software Version 1.3.0 PN 33619 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/14/15 Initial release with Converge EMS API version 1.3.0.



ContentsPreface ......................................................................................................................................................... 4

Purpose of document .............................................................................................................................. 4

Scope ....................................................................................................................................................... 4

Intended Audience .................................................................................................................................. 4

Related Documents ................................................................................................................................. 4

Device Firmware Version Requirements ................................................................................................. 4

Glossary ....................................................................................................................................................... 6

Converge EMS RESTful API – General Information ...................................................................................... 7

REST Web Services Interfaces Overview .................................................................................................. 8

Domain Object REST Web Services Interface ........................................................................................ 10

HTTP Requests ....................................................................................................................................... 14

HTTP Responses ..................................................................................................................................... 16

Common RESTful Endpoints .................................................................................................................. 17

Converge EMS REST Web Services API – Authorization Requests ............................................................ 18

Login ...................................................................................................................................................... 18

Logout .................................................................................................................................................... 20

Web Login .............................................................................................................................................. 22

Web Logout ........................................................................................................................................... 24

Web Verify ............................................................................................................................................. 26

Converge EMS REST Web Services API – Domain Object Requests .......................................................... 27

Create Domain Object ........................................................................................................................... 27

Read Domain Object .............................................................................................................................. 29

Update Domain Object .......................................................................................................................... 33

Delete Domain Object ........................................................................................................................... 35

Converge EMS REST Web Services API – Meta Model Requests .............................................................. 36

Read Meta Model Class, Fields and Validators ...................................................................................... 36

Read All Meta Model Classes with Fields and Validators ...................................................................... 39

Get Meta Model Hierarchy .................................................................................................................... 40

Read Meta Model Classes (Domain Object API for Meta Model Access) .............................................. 42

Read Meta Model Fields (Domain Object API for Meta Model Access) ................................................ 46

Read Meta Model Field Validators (Domain Object API for Meta Model Access) ................................ 50

Re‐discover Meta Model (Business Component API for Meta Model Discovery) ................................. 53

Converge EMS REST Web Services Integration ......................................................................................... 55

Converge EMS REST Web Services Integration – Message Exchange ....................................................... 56

Alarms and Stats ........................................................................................................................................ 58

Index .......................................................................................................................................................... 59

Appendix A – Filter Operators ................................................................................................................... 64



Preface

Purpose of document

This document describes the REST Web Services Interface provided by Converge EMS and used for integration with other software applications.

Scope

The present document contains an overview of the REST Web Services Interface used by all REST interfaces provided by Converge EMS. It also contains example of messages for logging in and out of the application, and basic Domain Object, Meta Model, Business Component and Documents Retrieval Commands.

Intended Audience

This document is intended for developers dedicated to creating an integration of RESTful Web services in the context of Converge EMS.

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).



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.

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.



Glossary API

Application Programming Interface CRUD

Create, Read, Update, Delete EMS

Element Management System GUI

Graphical User Interface HTTP

Hypertext Transfer Protocol NMS

Network Management System OSS

Operations Support System REST

Representational State Transfer RMI

Remote Method Invocation URL

Uniform Resource Locator



Converge EMS RESTful API – General Information

Converge EMS Application Programming Interface makes it possible for third-party entities to integrate their applications with Converge EMS via REST Web Service Interfaces.

Converge’s API has been designed to comply with the Representational State Transfer (REST) style recommendations, therefore the communication is mainly implemented using the HTTP protocol, and the possible types of interactions are represented by resources and their related operations.



REST Web Services Interfaces Overview

The general Converge EMS API architecture is presented below:

Figure 1: Converge EMS REST Web Services Interface Overview

Converge EMS provides the REST Web Services API for integration with:

This interface is used by the Converge EMS GUI to access Domain Object API, Meta Model API, Business Component API and Document Retrieval API.

The interface also contains the internal Converge GUI interface used for dynamic menus.

This is the same interface as the one used for GUI without the capability to expose the internal interface for dynamic menus.

Any OSS or Software Application can re-use this API.

Converge EMS can use the REST Web Services to invoke the API of external applications:



This is the RESTful Domain Object Interface that can be used for integration with external EMS/NMS and any other Software Applications.

This interface is similar to the RESTful Domain Object API used to integrate Converge GUI with other OSSs.

The interface can be used WITH or WITHOUT Data Mediation.

WITHOUT MEDIATION: When used WITHOUT Data Mediation, external EMS/NMS/devices have to support Converge RESTful interface and Meta Model.

WITH MEDIATION: When used WITH Data Mediation, the interface can be mediated to any other RESTful interface and any custom Meta Model.

The same interface is used as the RESTful Domain Object API used to integrate with EMS/NMS.

Other interfaces, shown in blue in Figure 1 can also be provided by Converge EMS if another type of integration is required. They can be used for tightly (e.g. Java), or loosely (e.g. Java RMI, SNMP) coupled integration.

Note: Converge EMS also provides a framework for building new custom adapters and extending the existing adapters, if required. Another customizability feature of Converge is the capability to configure Mediation to external Meta Models.

For REST Web Services APIs see:

Domain Object REST Web Services Interface Meta Model Object REST Web Services Interface

For REST Web Services Integration see Converge EMS™ REST W eb Services Inte gr ation .



Domain Object REST Web Services Interface

External software applications can integrate with Converge EMS via the REST Web Service Interfaces. They can use the Domain Object REST API for creation, read, update and deletion of objects managed by Converge EMS or external, integrated Oss (EMS / NMS). Each user role can be configured with any CRUD access per any object type.

Converge EMS GUI

Figure 2: Converge EMS Domain Object REST Web Services Interface

Converge EMS provides the Domain Object REST Web Services API for integration with:


Any OSS or software application that requires the CRUD access to Converge EMS or external Domain Objects (EMS / NMS / Network, etc.).



Meta Model Object REST Web Services Interface

External software applications can integrate with Converge EMS via the REST Web Service Interfaces.

They can use the Meta Model REST API for reading Meta Model used by Converge EMS.

They can use the Domain Object REST API for reading the Meta Model Classes, Meta Model Fields and Meta Model Validators as Domain Objects.

They can use the Business Component API for initiating re-discovery of the Meta Model.

Converge EMS GUI

Figure 3: Converge EMS Meta Model REST Web Services Interface

Converge EMS provides the Domain Object REST Web Services API for integration with:


Any OSS or software application that requires access to Converge EMS Meta Model.



Converge EMS REST Web Services API – Message Exchange

The following sequence diagram shows the message exchange between the Converge EMS GUI / OSS and Converge EMS.

Figure 4: Converge EMS REST Web Services API Message Exchange Matrix

The message exchange matrix consists of the following REQUEST / RESPONSE messages, where Login and Logout must be first and last, respectively, and the remaining transactions can be executed in any order (if at all).

Request Name Request Description Request Elements Response Elements

Login Logging in to interface http(s) request, PUT, http(s) response, status



Note: This can be replaced with a Web Login to provide for a web browser login via a web form.

URI, credentials token

Meta Model API Reading Meta Model

See also Meta Model Object REST Web Services Interface

http(s) request, GET, URI, authorization

()

Domain Object

API

Creation, Reading, Updating, and Deleting Domain Objects (CRUD)

http(s) request, GET / PUT / POST / DELETE, URI, authorization

()

Business

Component API

Invocation of Business Component methods

http(s) request, POST, URI, authorization

()

Document

Retrieval API

Retrieving documents http(s) request, GET, URI, authorization

Logout Logging out of interface

Note: This can be replaced with a Web Logout to provide for a web browser logout via a web form.

http(s) request, DELETE, URI, token

http(s) response, status

Table 1: Converge EMS REST Web Services API Message Exchange Matrix



HTTP Requests

As a result of the assumed communication architecture, 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



Table 2: Requirements for HTTP Requests

for the CRUD type interface, or a method name for other interface types)



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 3: Requirements for HTTP Responses



Common 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 that are currently supported by Converge EMS:

Endpoint Endpoint URL Endpoint Description

Authentication Endpoint <contextRoot>/rest/ security

Security endpoint for login and logout.

Domain Objects

Endpoint

<contextRoot>/rest/ domainObjects

Endpoint for Domain Object API. Used for managing CRUD access to the Domain Objects.

Also used for read access to the Meta Model, when access to individual Meta Model Classes, Fields and Validators as Domain Objects is required.

Meta Model Endpoint <contextRoot>/rest/ metaModels

Endpoint for Meta Model API. Used for managing access to the Meta Model.

Business Component

Endpoint

<contextRoot>/rest/ businessLogic

Endpoint for Business Component API.

Used for invocation of Business Components methods.

Also used for initializing Meta Model re-discovery.

Document Retrieval

Endpoint

<contextRoot>/rest/ documentRetrieval

Endpoint for Document Retrieval API.

Used for retrieving documents.

Table 4: Common RESTful Endpoints



Converge EMS REST Web Services API – Authorization Requests

Login

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. See Web Login.

Login Request Example

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.

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>



If the login fails, for example due to incorrect credentials, the UNAUTHORIZED (401) Status is returned.

Login Response Example (OK)

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: Thursday, 16 April 2015 16:53:16 GMT User Un‐Authorized

HTTP/1.1 200 OK


Set‐Cookie: JSESSIONID=D38E9D0E460311BFEB5AD3FEDBD68796; Path=/convergeEMS/;

HttpOnly

Content‐Type: text/plain


Date: Thursday, 16 April 2015 16:53:16 GMT admin‐‐ D38E9D0E460311BFEB5AD3FEDBD68796



Logout

Description Logs out a user

HTTP Method DELETE

URL http://a.b.c.d:port/<contextRoot>/rest/security/login

*Note: The correct URL is /rest/security/login as the operation of logging out is a delete of the ‘login’ resource.

Header Obligatory: ‘Authorization’ header containing the token (e.g. TOKEN admin- - 3510EBCC2B5555AEBA3FEA6F6EFF3DE5)

Message Body Empty

Table 6: Logout Request

Note: Logout can be replaced with a Web Logout to provide for a web browser login via a web form. See Web Logout.

Logout Request Example

Logout Response If the logout is successful, the OK Status (200) is returned.

If the login fails, an ERROR Status is returned.

Logout Response Example (OK)

HTTP/1.1 200 OK


Content‐Length: 0

Date: Thursday, 16 April 2015 16:53:16 GMT

DELETE http://localhost:8080/convergeEMS/rest/security/login HTTP/1.1


Authorization: TOKEN admin‐‐ 3510EBCC2B5555AEBA3FEA6F6EFF3DE5



User‐Agent: Apache‐HttpClient/4.1.1 (java 1.5)



Logout Response Example (Error)

HTTP/1.1 404 Not Found


Content‐Type: text.html;charset=utf‐8


Date: Thursday, 16 April 2015 16:53:16 GMT <html><head> <title>Apache Tomcat/7.0.37 – Error report</title><style>...



Web Login

Description Logs in a user via a web form (when logging in in a browser)

HTTP Method POST

URL http://a.b.c.d:port/<contextRoot>/rest/security/web-login

Header Not required

Message Body Two form parameters, username and password

Table 7: Web Login Request

Web Login Request Example

Web Login Response If the login is successful, the user is redirected to <contextRoot>/main/main.html through the location header. The response also includes the security token in the ‘Authorization’ header and in the Cookie.

If the login fails, the user is redirected to the login page, and an error message is returned.

POST http://localhost:8080/convergeEMS/rest/security/web‐login HTTP/1.1

Host: 127.0.0.1:6090

User‐Agent: Mozilla/5.0 (X11; U; Linux i686; en‐US; rv:1.9.2.13) Gecko/20101206

Ubuntu/10.04 (lucid) Firefox/3.6.13

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 Accept‐

Language: en‐gb, chrome://global/locale/intl.properties;q=0.5 Accept‐Encoding:

gzip,deflate

Accept‐Charset: ISO‐8859‐1,utf‐8;q=0.7,*;q=0.7

Keep‐Alive: 115

Connection: keep‐alive

Referer: http://127.0.0.1:6090/convergeEMS/login.jsp

Content‐Type: application/x‐www‐form‐urlencoded

Content‐Length: 39 username=admin&x=32&y=29&password=admin



Web Login Response Example (with Redirect)

HTTP/1.1 200 OK


X‐Powered‐By: Servlet 2.5; JBoss‐5.0/JBossWeb‐2.1

Accept‐Ranges: bytes

ETag: W/"919‐1297776468000"

Last‐Modified: Thursday, 16 April 2015 16:53:16 GMT

Content‐Type: text/html


Date: Thursday, 16 April 2015 16:53:16 GMT <!DOCTYPE HTML PUBLIC "‐//W3C//DTD HTML> ....

GET /convergeEMS/main/main.html HTTP/1.1

Host: 127.0.0.1:6090





gzip,deflate


Keep‐Alive: 115 Connection: keep‐alive

Referer: http://127.0.0.1:6090/convergeEMS/login.jsp

Cookie: JSESSIONID=819B5BA280CB23BD57491136DB192B7D;

SECURITY_TOKEN=admin‐‐ 97e00033‐0cfe‐4b3f‐b3f1‐cfa6e7648f23

If‐Modified‐Since: Thursday, 16 April 2015 16:53:16 GMT

If‐None‐Match: W/"919‐1297771918000"

HTTP/1.1 302 Moved Temporarily




Set‐Cookie: SECURITY_TOKEN=admin‐‐97e00033‐0cfe‐4b3f‐b3f1‐cfa6e7648f23; Path=/

Location: http://127.0.0.1:6090/convergeEMS/main/main.html Content‐Length: 0




Web Logout

Description Logs out a user through a web browser

HTTP Method POST

URL http://a.b.c.d:port/<contextRoot>/rest/security/web-logout

Header Obligatory: The token in the Cookie

Message Body Empty

Table 8: Web Logout Request

Web Logout Request Example

Web Logout Response If the login is successful, the user is redirected to the login page <contextRoot>/login.jsp.

If the login fails, the user is redirected to the login page, and an error message is returned.

Web Logout Response Example

HTTP/1.1 302 Moved Temporarily



Location: http://127.0.0.1:6090/convergeEMS/login.jsp

POST http://localhost:8080/convergeEMS/rest/security/web‐logout HTTP/1.1

Host: 127.0.0.1:6090





gzip,deflate


Keep‐Alive: 115

Connection: keep‐alive

Referer:

http://127.0.0.1:6090/convergeEMS/main/D93D980CFB734DEDD87EB1BF83D4EBAF.cache.html

Cookie: JSESSIONID=819B5BA280CB23BD57491136DB192B7D; SECURITY_TOKEN= admin‐‐97e00033‐

0cfe‐4b3f‐b3f1‐cfa6e7648f23



Content‐Length: 0




Web Verify

Description Verifies if a token is still active

HTTP Method POST

URL http://a.b.c.d:port/<contextRoot>/rest/security/web-verify

Header Obligatory: ‘Authorization’ header containing the token (e.g. TOKEN admin- - 3510EBCC2B5555AEBA3FEA6F6EFF3DE5)

Message Body Empty

Table 9: Web Verify Request

Web Verify Response If the token is still active, the Status Code is OK (200).

If the token is not active any more, and Error Status is returned.



Converge EMS REST Web Services API – Domain Object Requests

Create Domain Object

Description Creates a new Domain Object instance

HTTP Method PUT

URL http://a.b.c.d:port/<contextRoot>/rest/domainObjects/{metaModelClassName}

Header Obligatory: ‘Authorization’ header containing the token (e.g. TOKEN admin-- 3510EBCC2B5555AEBA3FEA6F6EFF3DE5)

Message Body The following is the XML format that must be used in the message body to describe the Domain Object instance to be created (see also the example below):

<metaModelClassName classVersion=”x.y”>

<name>name1</name>

<field1>value1</field1>


</metaModelClassName>

Table 10: Create Domain Object Request

Create Domain Object Request Example

PUT http://localhost:8080/convergeEMS/rest/domainObjects/Subscriber HTTP/1.1


Accept: text/html

Content‐Type: text/plain; charset=UTF‐8





User‐Agent: Apache‐HttpClient/4.1.1 (java 1.5) <Subscriber classVersion="1.0">

<name>subscriber1</name>

<owner>ConvergeMSS<owner>



Create Domain Object Response If the request is successful, the response is sent with an empty message body, and the CREATED (201) Status Code.

If the request fails, the possible status can be FORBIDDEN (403) if the user does not have the create access to the Meta Model Class with the name ‘metaModelClassName’, or INVALID DATA (456) if validation fails on the object and its fields.

Create Domain Object Response Example

HTTP/1.1 201 Created


Content‐Length: 0


<userLabel>Subscriber‐1</userLabel>

<description>This is Subscriber‐1</description>

<phone>+353‐166380000</phone>

<address>Century Court, Dun Laoghaire</address>

</Subscriber>



Read Domain Object

Description Reads all Domain Object instances meeting the specified criteria

HTTP Method GET


http://a.b.c.d:port/<contextRoot>/rest/domainObjects/{metaModelClassName} /{version}*

*Note: An optional {version} path should be used to specify a particular version of the Meta Model Class. If it is omitted, the latest version is used.


Optional: ‘filter’ header – this is an optional header used if not all instances of some Domain Object are required, but only particular instances as defined in the filtering conditions. See Read Domain Object Request Example (with Filter and Parameters).

A filter example:

<filter operator="and"><condition field="name" operator="eq"

value="subscriber1"/></filter>

Note: See APPENDIX – Filter Operators to learn what syntax and operators can be used for filters here.

Message Body Not required

Query Parameters

Two parameters can be used, start and limit.

start: the index of the first object to be returned

limit: the maximum number of instances to be returned

See Read Domain Object Request Example (with Filter and Parameters).

Note: start should be set to 0 and limit to -1 to return all instances. If neither of these parameters is used, all instances are returned as well.

Table 11: Read Domain Object Request

Read Domain Object Request Example (without Filter or Parameters)

GET http://localhost:8080/convergeEMS/rest/domainObjects/Subscriber HTTP/1.1




The above request returns all Subscribers.

Read Domain Object Request Example (with Filter and Parameters)

The above request returns only the first ten Subscribers that meet the filter conditions. The number and index of the desired Subscribers are defined in the endpoint parameters.

Note: See APPENDIX – Filter Operators to learn what operators and syntax can be used for filters here.

Read Domain Object Response A response is sent with a list of Domain Objects in the following format:

<list>

<MetaModelClassName classVersion="1.0" expanded=”no”>

<name>object1</name>

<field1 >value1</field1>


</MetaModelClassName> < MetaModelClassName version="1.0">

<name>object2</name>


GET http://localhost:8080/convergeEMS/rest/domainObjects/

Subscriber?start=0&limit=10 HTTP/1.1



filter: <filter operator="and"><condition field="name" operator="contains"

value="subscriber"/></filter>










If the request is successful, the status of the response is OK (200).

If the request fails, the response status is FORBIDDEN (403) if the user does not have the read access to the Meta Model Class with the name ‘metaModelClassName’.

Read Domain Object Response Example

HTTP/1.1 200 OK


startRow: 0

endRow: 2

totalRows: 2

Cache‐Control: max‐age=0

Content‐Type: text/xml

Date: Thursday, 16 April 2015 16:53:16 GMT <list>

<Subscriber classVersion="1.0" expanded=”no”>


<discoveredName>N/A</discoveredName>

<discoveredHiddenId>‐1</discoveredHiddenId>

<namingOs>convergeEMS </namingOs>

<owner>convergeEMS</owner>

<createdBy>admin</createdBy>

<createDate>16/04/2015 16:53:16</createDate>

<modifiedBy>N/A</modifiedBy>

<modifyDate>N/A</modifyDate>

<planned>true</planned>

</Subscriber> <Subscriber classVersion="1.0" expanded=”no”>


<discoveredName>N/A</discoveredName>

<discoveredHiddenId>‐1</discoveredHiddenId>

<namingOs>convergeEMS</namingOs>

<owner>OS‐SM‐Amartus</owner>


</MetaModelClassName>

</list>



Three extra header parameters are sent in the response: startRow, endRow and totalRows. These are useful for paging in the GUI or for iterators:

startRow: specifies the index of the first row returned endRow: specifies the index of the last row returned

totalRows: specifies the total number of rows that meet the request

<createdBy>admin</createdBy>

<createDate>16/04/2015 16:53:16</createDate>

<modifiedBy>N/A</modifiedBy>

<modifyDate>N/A</modifyDate>

<planned>true</planned>

</Subscriber>

</list>



Update Domain Object

Description Updates a Domain Object instance

HTTP Method POST



Message Body

The following is the XML format that must be used in the message body to describe the Domain Object instance to be updated (see also the example below):

<metaModelClassName classVersion=”x.y”>

<name>name1</name>



</metaModelClassName>

Table 12: Update Domain Object Request

Update Domain Object Request Example

POST http://localhost:8080/convergeEMS/rest/domainObjects/Subscriber HTTP/1.1


Accept: text/html






User‐Agent: Apache‐HttpClient/4.1.1 (java 1.5) <Subscriber classVersion="1.0">


<description>New Description</description>

</Subscriber>



Update Domain Object Response If the request is successful, the status of the response is OK (200), and the Message Body is empty.

If the request fails, the response status is FORBIDDEN (403) if the user does not have the read access to the Meta Model Class with the name ‘metaModelClassName’, or INVALID DATA (456) if validation fails on the object and its fields.

Update Domain Object Response Example

HTTP/1.1 200 OK


Content‐Length: 0




Delete Domain Object

Description Deletes a Domain Object instance

HTTP Method DELETE

URL http://a.b.c.d:port/<contextRoot>/rest/domainObjects/{metaModelClassName} /{objectName}


Message Body

Not required

Table 13: Delete Domain Object Request

Delete Domain Object Request Example

Delete Domain Object Response If the request is successful, the response is sent with an empty message body, and the NO CONTENT (204) Status Code.

If the request fails, the possible status is FORBIDDEN (403) if the user does not have the delete access to the Meta Model Class with the name ‘metaModelClassName’.

Delete Domain Object Response Example

HTTP/1.1 204 No Content



DELETE

http://localhost:8080/convergeEMS/rest/domainObjects/Subscriber/subscriber2

HTTP/1.1


Accept: text/html







Converge EMS REST Web Services API – Meta Model Requests

Read Meta Model Class, Fields and Validators

Description Reads a Meta Model Class with its fields and validators

HTTP Method GET

URL http://a.b.c.d:port/<contextRoot>/rest/metaModels/{metaModelClassName}

http://a.b.c.d:port/<contextRoot>/rest/metaModels/{metaModelClassName} /{version}



Message Body

Not required

Table 14: Read Meta Model Class, Fields and Validators Request

Read Meta Model Class, Fields and Validators Request Example

Read Meta Model Class, Fields and Validators Response If the request is successful, the status of the response is OK (200), and the response contains all Meta Data from the corresponding ‘metaModelClassName.meta.xml’ file, for the class, its fields and all validators. The content depends on the Meta Model Class.

GET http://localhost:8080/convergeEMS/rest/metaModels/Subscriber HTTP/1.1








Read Meta Model Class, Fields and Validators Response Example Only an excerpt of a response is provided here as an example. The original response was much longer, but this example is to show the format in which elements of the response are presented.

HTTP/1.1 200 OK





<MetaModelClass name=”Subscriber”

compressedName=”Subscriber_1.0”

className=”Subscriber”

title=”Subscriber”

namespace=”service/Subscriber/v1.0”

module=”entities”

expanded=”true”

isAbstract=”false”

inheritsFrom=”CommonObjectInfo”

inheritsFromVersion=”1.0”

containedIn=”root”

userAccess=”crud”

version=”1.0”

hasObject=”true”

discover=”yes”

aggregated=”no”

description=””

deprecated=”false”>

<fields>

<field name=”CommonObjectInfo_1.0_name” metaClassName=”CommonObjectInfo”

compressedName=”a_name” fieldname=”name” title=”Name” type=”text”

primaryKey=”true” foreignKey=”” rootValue=”” required=”true” length=”100”

Multiple=”false” detail=”false” hidden=”false” canEdit=”createOnly”

description=”name” globallySet=”false” canBeOverridden=”false” contained=”never”

metaClassId=”CommonObjectInfo_1.0” metaClassVersion=”” ordinalPosition=”0”

defaultValue=”” monitored=”false” pattern=”” inherited=”true”>

<validators>



Read All Meta Model Classes with Fields and Validators

Description Reads all Meta Model Classes with their fields and validators

HTTP Method GET

URL http://a.b.c.d:port/<contextRoot>/rest/metaModels


Message Body

Not required

Table 15: Read All Meta Model Classes, Fields and Validators Request

Read All Meta Model Classes with Fields and Validators Request Example

Read All Meta Model Classes with Fields and Validators Response If the request is successful, the status of the response is OK (200), and the response contains all Meta Data from all ‘*.meta.xml’ files, for the classes, all their fields and all validators. The content depends on the Meta Model Classes.

Read All Meta Model Classes with Fields and Validators Response Example The response format is the same as in Read Meta Model Class, Fields and Validators Response Example, but it lists all, not just on Meta Model Class.

GET http://localhost:8080/convergeEMS/rest/metaModels HTTP/1.1








Get Meta Model Hierarchy

Description Returns the inheritance hierarchy for a specific class

HTTP Method GET

URL http://a.b.c.d:port/<contextRoot>/rest/metaModels/hierarchy /{metaModelClassName}


Message Body

Not required

Table 16: Get Meta Model Hierarchy Request

Get Meta Model Hierarchy Request Example

Get Meta Model Hierarchy Response If the request is successful, the status of the response is OK (200), and the response contains a list of base class names.

Get Meta Model Hierarchy Response Example

HTTP/1.1 200 OK





<string>CommonObjectInfo</string>

GET http://localhost:8080/convergeEMS/rest/metaModels/hierarchy/Subscriber

HTTP/1.1





User‐Agent: Apache‐Http‐Client/4.1.1 (java 1.5)



<string>Subscriber</string>

</list>



Read Meta Model Classes (Domain Object API for Meta Model Access)

Domain Object API can be used for accessing Meta Model if it is required to have the read access to Meta data of Meta Model Classes, fields and validators individually. Below is an example for reading Meta Model Classes only.

This Domain Object API can be used for reading all Meta Model Classes, several Meta Model Classes that meet the specified criteria, or a single Meta Model Class.

Description Reads Meta Model Class instances that meet the specified criteria

HTTP Method

GET

URL http://a.b.c.d:port/<contextRoot>/rest/domainObjects/MetaModelClass

http://a.b.c.d:port/<contextRoot>/rest/domainObjects/MetaModelClass/{version}



Optional: ‘filter’ header – this is an optional header. If it is not used, all Meta Model Classes are returned. If used, then only Meta Model Classes that meet the conditions defined in the filter are returned. See Read Meta Model Classes Request Example (with Filter and Parameters).

A filter example:

<filter operator="and"><condition field="name" operator="eq" value="subscriber1"/></filter>


Message Body

Not required

Query Parameters




See Read Meta Model Classes Request Example (with Filter and Parameters).



Table 17: Read Meta Model Classes (Domain Object API) Request

Read Meta Model Classes Request Example (without Filter or Parameters)

The above request returns all Meta Model Classes.

Read Meta Model Classes Request Example (with Filter and Parameters)

The above request returns only the first ten Meta Model Classes that meet the filter conditions. The number and index of the Meta Model Classes are defined in the endpoint parameters.


Read Meta Model Classes Response A response is sent with a list of Domain Objects in the following format:

GET http://localhost:8080/convergeEMS/rest/domainObjects/MetaModelClass

?start=0&limit=10 HTTP/1.1






filter: <filter operator="and"><condition field="name" operator="eq"

value="Subscriber_1.0"/></filter>

GET http://localhost:8080/convergeEMS/rest/domainObjects/MetaModelClass HTTP/1.1











Read Meta Model Classes Response Example

HTTP/1.1 200 OK


startRow: 0

endRow: 2

totalRows: 2




<MetaModelClass classVersion=”1.0” expanded=”no”>

<name>Subscriber_1.0</name>

<compressedName>Subscriber_1.0</compressedName> <className>Subscriber</className>

<title>Subscriber</title>

<namespace>service/Subscriber/v1.0</namespace>

<module>entities</module>

<expanded>true</expanded>

<isAbstract>false</isAbstract> <inheritsFrom>CommonObjectInfo</inheritsFrom>

<list>

<MetaModelClass version="1.0" expanded=”no”>

<name>class1</name>

<field1 >value1</field1 >


</MetaModelClass> < MetaModelClass version="1.0" expanded=”no”>

<name>class2</name>



</MetaModelClass>

</list>




startRow: specifies the index of the first row returned

endRow: specifies the index of the last row returned totalRows: specifies the total number of rows that meet the request

<inheritsFromVersion>1.0</inheritsFromVersion> <containedIn>root</containedIn>

<userAccess>crud</userAccess>

<version>1.0</version>

<hasObject>true</hasObject>

<discover>yes</discover>

<aggregated>no</aggregated>

<description></description>

<deprecated>false</deprecated>

</MetaModelClass>

</list>



Read Meta Model Fields (Domain Object API for Meta Model Access)

Domain Object API can be used for accessing Meta Model if it is required to have the read access to Meta data of Meta Model Classes, fields and validators individually. Below is an example for reading Meta Model fields only.

This Domain Object API can be used for reading all Meta Model fields, several Meta Model fields that meet the specified criteria, or a single Meta Model field.

Description Reads Meta Model field instances that meet the specified criteria

HTTP Method

GET

URL http://a.b.c.d:port/<contextRoot>/rest/domainObjects/MetaModelField

http://a.b.c.d:port/<contextRoot>/rest/domainObjects/MetaModelField/{version}

*Note: An optional {version} path should be used to specify a particular version of the Meta Model Field. If it is omitted, the latest version is used.


Optional: ‘filter’ header – this is an optional header. If it is not used, all Meta Model Fields are returned. If used, then only Meta Model Fields that meet the conditions defined in the filter are returned. See the request example below.

A filter example:

<filter operator="and"><condition field="required" operator="eq" value="true"/></filter>


Message Body

Not required

Query Parameters




See the request example below.

Note: start should be set to 0 and limit to -1 to return all instances. If neither of



Table 18: Read Meta Model Fields (Domain Object API) Request

Read Meta Model Fields Request Example

The above request returns only the first ten Meta Model Fields that meet the filter conditions. The number and index of the desired Meta Model Classes are defined in the endpoint parameters.


Read Meta Model Fields Response A response is sent with a list of Domain Objects in the following format:

<list>

<MetaModelField classVersion="1.0" expanded=”no”>

<name>field1</name>



</MetaModelField> <MetaModelField classVersion="1.0" expanded=”no”>

<name>field1</name>



</MetaModelField>

</list>

GET http://localhost:8080/convergeEMS/rest/domainObjects

MetaModelField?start=0&limit=10 HTTP/1.1






filter: <filter operator="and"><condition field="required" operator="eq"

value="true"/></filter>

these parameters is used, all instances are returned as well.





Read Meta Model Fields Response Example

HTTP/1.1 200 OK


startRow: 0

endRow: 2

totalRows: 2




<MetaModelField classVersion=”1.0” expanded=”no”>

<name>AccessSpecification_1.0_associateRemoteObjects</name>

<compressedName>a_description</compressedName> <fieldName>description</fieldName>

<title>Description</title>

<type>text</type>

<primaryKey>false</primaryKey>

<foreignKey></foreignKey>

<rootValue></rootValue>

<required>true</required>

<length>120</length>

<multiple>false</multiple>

<detail>true</detail>

<hidden>false</hidden>

<canEdit>createAndUpdate</canEdit>

<description>description</description>

<globallySet>false</globallySet>

<canBeOverridden>false</canBeOverridden>

<contained>never</contained> <metaClassName>CommonObjectInfo</metaClassName>

<metaClassId>CommonObjectInfo_1.0</metaClassId>

<metaClassVersion></metaClassVersion>

<ordinalPosition>6</ordinalPosition>

<defaultValue></defaultValue>

<monitored>false</monitored>

<pattern></pattern>



Read Meta Model Field Validators (Domain Object API for Meta Model Access)

Domain Object API can be used for accessing Meta Model if it is required to have the read access to Meta data of Meta Model Classes, fields and validators individually. Below is an example for reading Meta Model validators only.

This Domain Object API can be used for reading all Meta Model validators, several Meta Model validators that meet the specified criteria, or a single Meta Model validator.

Description Reads Meta Model validator instances that meet the specified criteria

HTTP Method

GET

URL http://a.b.c.d:port/<contextRoot>/rest/domainObjects/MetaModelFieldValidator

http://a.b.c.d:port/<contextRoot>/rest/domainObjects/MetaModelFieldValidator /{version}

*Note: An optional {version} path should be used to specify a particular version of the Meta Model Field Validator. If it is omitted, the latest version is used.


Optional: ‘filter’ header – this is an optional header. If it is not used, all Meta Model Field Validators are returned. If used, then only Meta Model Field Validators that meet the conditions defined in the filter are returned. See the request example below.

A filter example:

<filter operator="and"><condition field="type" operator="eq"

value="integerRange"/></filter>


Message Body

Not required

Query Parameters





Table 19: Read Meta Model Field Validators (Domain Object API) Request

Read Meta Model Field Validators Request Example

Read Meta Model Field Validators Response A response is sent with a list of Domain Objects in the following format:

<list>

<MetaModelFieldValidator classVersion="1.0" expanded=”no”>

<name>validator1</name>



</MetaModelFieldValidator>

< MetaModelFieldValidator classVersion="1.0" expanded=”no”>

<name>validator2</name>




</list>

GET http://localhost:8080/convergeEMS/rest/domainObjects/

MetaModelFieldValidator?start=0&limit=10 HTTP/1.1


Accept: text/html




User‐Agent: Apache‐HttpClient/4.1.1 (java 1.5) filter: <filter operator="and"><condition field="type" operator="eq"

value="integerRange"/></filter>


See the request example below.









Read Meta Model Field Validators Response Example

HTTP/1.1 200 OK



startRow: 0

endRow: 1

totalRows: 1



Content‐Length: 413 <list>

<MetaModelFieldValidator version="1.0">

<name>CommonObjectInfo_1.0_name_isString</name>

<validatorType>isString</validatorType>

<metaFieldName>name</metaFieldName>

<metaFieldId>CommonObjectInfo_1.0_name</metaFieldId>

<stopIfFalse>false</stopIfFalse>

<isClientOnly>false</isClientOnly>

<errorMessage>Value must be a string</errorMessage>

<isServerSide>true</isServerSide>


</list>



Re-discover Meta Model (Business Component API for Meta Model Discovery)

As mentioned in Meta Model Object REST Web Services Interface, Business Component API may be used for re-discovery of the Meta Model. In such a case, the following request may be sent via this API.

Description Re-discover the Meta Model by discovering new classes and new class versions

HTTP Method

POST

URL http://a.b.c.d:port/<contextRoot>/rest/businessLogic /metaModelDiscoveryService/discover


Message Body

Not required

Table 20: Re-discover Meta Model (Business Component API) Request

Re-discover Meta Model Request Example

Re-discover Meta Model Response If the request is successful, the status of the response is OK (200), and an empty message body.

POST http://localhost:8080/convergeEMS/rest/businessLogic/

spring:metaModelDiscoveryService/discover HTTP/1.1


Content‐Type: application/xml


Content‐Length: 0



User‐Agent: Apache‐HttpClient/4.1.1 (jave 1.5)



Re-discover Meta Model Response Example

HTTP/1.1 200 OK


Content‐Length: 0




Converge EMS REST Web Services Integration

REST Web Services Integration Interface is used to invoke the API of external applications to integrate with ANY software application using the REST interface. Another capability of this interface is to integrate with another Converge EMS instance.

Figure 5: REST Web Services Integration Interface

Converge EMS can use the REST Web Services API for integration with:

EMSs / NMSs that provide the REST Web Services API.

Any Software Application that provides the REST Web Services API, including any OSS.

Network Devices that provide the REST Web Services API.

Other Converge EMS instances.



Converge EMS REST Web Services Integration – Message Exchange

The following sequence diagram shows the message exchange between the Converge EMS and external applications.

Figure 6: Converge EMS REST Web Services Integration Message Exchange Matrix

The message exchange matrix consists of the following REQUEST / RESPONSE messages, where Login and Logout must be first and last, respectively.

After Converge EMS logs in, it can create, read, update and delete Domain Objects through the Domain Object API; see Converge™ EMS REST W eb Services AP I – Domain Object Requests.

The security can be disabled if not required. If disabled, there will be no login and logout messages, and all other messages will not require authorization / token.

The interface can be used with or without Mediation. For Mediation details please refer to appropriate Mediation customization documents.



Tip: If the external EMS/NMS/Network application uses the same Meta Model and the same REST Web Services Interface as Converge EMS, there is NO NEED for Mediation.

Mediation is also NOT REQUIRED at integration with another instance of Converge EMS.

Request Name Request Description Request Elements Response Elements

Login Logging in to interface http(s) request, PUT, URI, credentials

http(s) response, status token

Domain Object

Interface

Creation, Reading, Updating, and Deleting Domain Objects (CRUD) through Domain Object API

http(s) request, GET / PUT / POST / DELETE, URI, authorization

()

Logout Logging out of interface http(s) request, DELETE, URI, token

http(s) response, status

Table 21: Converge EMS REST Web Services Integration Message Exchange Matrix

The default HTTP Requests and Responses are described in HTTP Requests and HTTP Responses, respectively. Mediation can be used to modify the default messages.

The default Restful Endpoints are described in Common RESTful Endpoints. For REST Web Services Integration, the Authentication and the Domain Objects Endpoints are used. Mediation can be used to modify the default endpoints.

The default Authentication (login and logout messages) are described in Converge EMS™ REST Web Services API – Authorization Requests. Mediation can be used to modify the default messages. Authentication can be also disabled by configuring Operations System without logging credentials.

The default messages for CRUD operations are the same as the ones used in Domain Object API – see Converge EM S™ REST Web Services AP I – Domain Object Requests. Mediation can be used to modify the default messages.



Alarms and Stats

The Stats are under model_home/common/measurements model_home/resource/measurements and model_home/service/measurements. The Alarm objects are under ModelHome/common/event and model_home/service/event.



Index

A

Authentication Endpoint, 21

B

Business Component Endpoint, 21

C

Converge EMS REST Web Services API Authorization Requests, 22 Business Component API, 17

Document Retrieval API, 17

Domain Object API, 17, 61 Domain Object Requests, 31 Login, 16, 61

Logout, 17, 61 Message Exchange, 16, 60 Meta Model API, 17 Meta Model Requests, 40

Converge EMS REST Web Services Integration, 59

Converge EMS RESTful API Introduction, 10

Common RESTful Endpoints, 21

Create Domain Object, 31 Request Example, 31 Response, 32 Response Example, 32

CREATED, 20

D

DELETE, 18

Delete Domain Object, 39 Request Example, 39 Response, 39 Response Example, 39

Document Retrieval Endpoint, 21

Domain Object REST Web Services Interface, 13



Domain Objects Endpoint, 21

F

Filter Operators, 67 allEq, 69

begins, 69

between, 69 contains, 69

ends, 69

eqField, 69

ge, 69

geField, 69 gt, 69

gtField, 69

iEquals, 70

in, 70

iNotEquals, 70

inSet, 70 isEmpty, 70

isNotEmpty, 70

isNotNull, 70 isNull, 70

le, 70

leField, 70

lt, 70

ltField, 70

ne, 70

neField, 70

notInSet, 71

FORBIDDEN, 20

G

GET, 18

Get Meta Model Hierarchy, 44 Request Example, 44 Response, 44 Response Example, 44

Glossary, 9

H

HTTP Requests, 18 DELETE, 18 GET, 18 HTTP Message, 18



HTTP Message Type, 18

HTTP Methods, 18

HTTP Version, 18 POST, 18 PUT, 18 URL, 18

HTTP Responses, 20 HTTP Message, 20

HTTP Message Type, 20

Status Codes, 20

I

INTERNAL SERVER ERROR, 20

INVALID DATA, 20

L

Login, 22 Request Example, 22 Response, 22 Response Example (OK), 23 Response Example (Unauthorized), 23

Logout, 24 Request Example, 24 Response Example (Error), 25 Response Example (OK), 24

M

Meta Model Endpoint, 21

Meta Model Object REST Web Services Interface, 14

N

NO CONTENT, 20

O

OK, 20



P

POST, 18

PUT, 18

R

Read All Meta Model Classes with Fields and Validators, 43 Request Example, 43 Response, 43 Response Example, 43

Read Domain Object, 33 Request Example (with Filter and Parameters), 34 Request Example (without Filter or Parameters), 33 Response, 34 Response Example, 35

Read Meta Model Class, Fields and Validators, 40 Request Example, 40 Response, 40 Response Example, 41

Read Meta Model Classes Domain Object API for Meta Model Access, 46 Request Example (with Filter and Parameters), 47 Request Example (without Filter or Parameters), 47 Response, 47 Response Example, 48

Read Meta Model Field Validators Domain Object API for Meta Model Access, 54 Request Example, 55 Response, 55 Response Example, 56

Read Meta Model Fields Domain Object API for Meta Model Access, 50 Request Example, 51 Response, 51 Response Example, 52

Re‐discover Meta Model Business Component API for Meta Model Discovery, 57 Request Example, 57 Response, 57

Related Documents, 6

REST Web Services Interfaces Overview, 11



S

Status Codes

200, 20 201, 20 204, 20 401, 20 403, 20 456, 20 500, 20 CREATED, 20 FORBIDDEN, 20 INTERNAL SERVER ERROR, 20 INVALID DATA, 20 NO CONTENT, 20 OK, 20 UNAUTHORIZED, 20

T

Typographical Conventions, 8

U

UNAUTHORIZED, 20

Update Domain Object, 37 Request Example, 37 Response, 38 Response Example, 38

W

Web Login, 26 Request Example, 26 Response, 26 Response Example (with Redirect), 27

Web Logout, 28 Request Example, 28 Response, 28 Response Example, 28

Web Verify, 30 Response, 30



Appendix A – Filter Operators

Note: For more detailed information on filters used in GUI, see the relevant Converge EMS filter documentation.

Below is an example of a filter that can be used in a request header in order to limit the number of objects returned in the response, or to point to exact instances of the desired objects. This filter returns only Meta Model objects for which the inherited attribute equals false.

Filters consist of the <filter> and <condition> tags that configure filter and condition objects, respectively. These tags can take the following attributes:

Field Example Description

operator (filter) <filter operator="and"> Defines logical relation between condition fields. When set to and, the results have to meet ALL conditions.

The example below returns all Meta Model objects with inherited field set to false AND the type field set to boolean.

<filter operator="and"><condition field="inherited"

operator="eq" value="false"/><condition field="type"

operator="eq" value="boolean"/></filter>

<filter operator="or"> Defines logical relation between condition fields. When set to or, the results have to meet ANY of the conditions.

The example below returns all Meta Model objects with inherited field set to false OR the type field set to boolean. For any returned object it is enough if either of the two conditions

<filter operator="and"><condition field="inherited" operator="eq"

value="false"/></filter>



has been met.

<filter operator="or"><condition field="inherited"



<filter operator="not"> Defines logical relation between condition fields. When set to not, the results CANNOT meet any of the conditions.

The example below returns all Meta Model objects with inherited field set to any value other than false AND the type field set to any value other than boolean. Any returned object has the values of the two conditions different from the values provided in the condition.

<filter operator="not"><condition field="inherited"



field (condition) field="inherited" Points to the name of a Meta Model Class field.

operator

(condition)

operator="eq" Defines the operator for the field value.

For example, eq is used to determine that the value of the field for the returned results has to equal the provided value.

Note: See next table for a description, examples and specific syntax for each operator.

value (condition) value="false" Defines the value for the field.

Table 22: Filter Structure



The following is a list of available filter operators (ordered alphabetically):

Warning: Most API operators are case-sensitive unless specifically stated otherwise in any description.

Field Description

allEq Used to search for all values equal to the range of values provided by the user. It matches multiple values.

begins Used to search for instances where the value of the given attribute starts with the value provided by the user.

between This operator takes two values

Used to search for instances where the value of the given attribute fits between the two values provided by the user.

contains Used to search for instances where the value of the given attribute contains the value provided by the user.

ends Used to search for instances where the value of the given attribute ends with the value provided by the user.

eq (equals) Used to search for instances for which the given attribute exactly matches the value provided by the user.

eqField (equals to

field)

Used to search for instances where the values of two provided attributes are the same.

ge (greater than or

equal to)

Used to search for instances where the value of the given attribute is greater than or equal to the value provided by the user.

geField (greater

than or equal to

field)

Used to search for instances where the values of the first is greater than or equal to the value of the second attribute.

gt (greater than) Used to search for instances where the value of the given attribute is greater than the value provided by the user.

gtField (greater

than field)

Used to search for instances where the values of the first is greater than the value of the second attribute.



iEquals Case insensitive operator

Used to search for instances where the value of the given attribute is anything different than the value provided by the user.

in This operator takes n values

iNotEquals Case insensitive operator

Used to search for instances for which the given attribute exactly matches the value provided by the user.

inSet Used to search for instances where the value of the given attribute is the same as one of the listed values.

isEmpty Used to search for instances where the value of the given attribute is set to empty.

isNotEmpty Used to search for instances where the value of the given attribute is set to any value other than empty.

isNotNull Used to search for instances where the value of the given attribute is not null.

isNull Used to search for instances where the value of the given attribute is null.

le (less than or

equal to)

Used to search for instances where the value of the given attribute is smaller than or equal to the provided value.

leField (less than or

equal to field)

Used to search for instances where the value of the first attribute is smaller than or equal to the value of the second attribute.

lt (less than) Used to search for instances where the value of the given attribute is smaller than the provided value.

ltField (less than

field)

Used to search for instances where the value of the first attribute is smaller than the value of the second attribute.

ne (not equals) Used to search for instances where the value of the given attribute is anything different than the value provided by the user.

neField (not equals Used to search for instances where the values of two provided

to field) attributes are different from each other.

notInSet Used to search for instances where the value of the given attribute is anything different from one of the listed values.

Table 23: List of Filter Operators



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 Common RESTful API Software Version 1.3.0 PN 33619 Rev. A

33619 A - Converge EMS API Guide for Common RESTful API · Fax: 952-941-2322 Revision History Rev...

Documents

Transcript of 33619 A - Converge EMS API Guide for Common RESTful API · Fax: 952-941-2322 Revision History Rev...