Converge API Guide for Service Activation API

120 Pages·2015·1.04 MB·English

™
Converge EMS API
Guide for Service Activation

Software Version 1.3.0

33620 Rev. A
Transition Networks ConvergeTM EMS API Guide for Service Activation

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 Service Activation Software Version 1.3.0 PN 33620 Rev. A

Contact Information
Transition Networks
10900 Red Circle Drive
Minnetonka, MN 55343 USA
Tel: [phone] or 1-800-526-9267
Fax: [phone]

Revision History
Rev Date Description
A 05/14/15 Initial release with Converge EMS software version 1.3.0.

33620 Rev. A www.transition.com Page 2 of 120
Transition Networks ConvergeTM EMS API Guide for Service Activation

Contents
Preface ......................................................................................................................................................... 4
Purpose of document .............................................................................................................................. 4
Scope ....................................................................................................................................................... 4
Intended Audience .................................................................................................................................. 4
Related Manuals ...................................................................................................................................... 4
Device Firmware Version Requirements ................................................................................................. 4
Typographical Conventions ..................................................................................................................... 5
Glossary ....................................................................................................................................................... 6
Overview ..................................................................................................................................................... 8
Requirements for HTTP Requests ............................................................................................................ 9
Requirements for HTTP Responses ........................................................................................................ 10
Service Activation RESTful Endpoints .................................................................................................... 11
Service Activation over API ........................................................................................................................ 12
Activate Services ........................................................................................................................................ 14
Login ...................................................................................................................................................... 16
Get UNI SAPs ......................................................................................................................................... 18
Get NNI SAPs ......................................................................................................................................... 21
Check Service Feasibility ........................................................................................................................ 23
Design Service ........................................................................................................................................ 32
Provision Service .................................................................................................................................... 37
Execute Pause ........................................................................................................................................ 48
Retrieve Service ..................................................................................................................................... 48
Terminate Service .................................................................................................................................. 51
Retire Service ......................................................................................................................................... 54
Activate Service Components .................................................................................................................... 57
Login ...................................................................................................................................................... 59
Get NNI SAPs ......................................................................................................................................... 59
Check Service Component Feasibility .................................................................................................... 63
Design Service Component .................................................................................................................... 73
Provision Service Component ................................................................................................................ 79
Execute Pause ........................................................................................................................................ 92
Retrieve Service Component ................................................................................................................. 92
Retrieve First Child Service Component ................................................................................................ 95
Retrieve Child’s First SAP ..................................................................................................................... 102
Terminate Service Component ............................................................................................................ 105
Retire Service Component ................................................................................................................... 109
Index ........................................................................................................................................................ 112
Appendix A – User-defined Variables ...................................................................................................... 117
Appendix B – Service Management GUI .................................................................................................. 118
Service Activation via the GUI .............................................................................................................. 120

33620 Rev. A www.transition.com Page 3 of 120
Transition Networks ConvergeTM EMS API Guide for Service Activation

Preface

Purpose of document

The purpose of this document is to explain how to integrate with Converge EMS API and
formulate HTTP requests for activation of services and service components.

Scope

The present document explains the overall flow of API service and service component
activation, describes each step, and provides details of each transaction. For every activation
step, the guide gives an example of request and response along with any crucial details.
The Overview presents some general information about Converge EMS API in the context of
service activation, including service activation endpoints and HTTP requirements for requests
and responses.

The document uses two examples of service objects, i.e. EVPL services and ERPS rings
(service components). Other services and service components are activated in the same way
as presented. Activate Services details all possible service activation transactions and
provides example requests and responses. Activate Service Components does the same for
service components.

Intended Audience

This document is intended for EMS developers who want to perform service activation via
Converge EMS RESTful API.

Warning: The exact format of the presented HTTP requests and responses may be
different when using various API tools. If request variables, or properties are required,
please check the list of variables in Appendix A – User-defined Variables.

Related Manuals

Converge EMS API Guide for Common RESTful API (33619)
Converge EMS API Guide for Service Activation API (33620)
Converge EMS API Service Model Overview (33621)

Device Firmware Version Requirements

Managed devices should be at the latest version available (e.g., S3290 v 1.9.4 or above).
33620 Rev. A www.transition.com Page 4 of 120
Transition Networks ConvergeTM EMS API Guide for Service Activation

Typographical Conventions

The following typographical conventions apply throughout this document:

Commands, options, Command and options names are presented in bold type.
windows, dialogs Names of windows and dialogs also appear in bold type.
‘Object Names’ Object names appear in inverted commas.
User-supplied Variable information, e.g. logins, passwords, other user-
information supplied data, appears in italic type.
Hyperlinks Hyperlinks are presented in underlined blue type.
Fragments of code and cmd commands are presented in the
Code and cmd
commands Consolas font.

Names of GUI buttons appear in square brackets and are
[ENTER]
printed in the Consolas font.
Guidelines which are particularly important are
Note: distinguished with a notepad and quill symbol, the blue
bold type and a ‘Note’ tag.
Warnings for operations that may result in serious
Warning: consequences are distinguished with an exclamation mark,
the red bold type and a ‘Warning’ tag.

Useful tips are distinguished with a light bulb symbol, the

Tip: green bold type, and a ‘Tip’ tag.
33620 Rev. A www.transition.com Page 5 of 120
Transition Networks ConvergeTM EMS API Guide for Service Activation

Glossary
API
Application Programming Interface
CRUD
Create Read Update Delete – reference to the four types of access rights to system objects.
Create makes it possible to add new object instances to the database, Read allows one to
display database objects, Update enables object modification, Delete – complete removal of
objects from the database.
EMS
Element Management System
ERPS
Ethernet Ring Protection Switching – an independent Service Component that can be
provisioned and managed on its own, independently from any service. It is used to ensure
ring protection of an Ethernet connection in case one of the working paths fails.
EVPL
Ethernet Virtual Private Line
HTTP
Hypertext Transfer Protocol
NNI
Network-to-Network Interface - can distinguish between I-NNI and E-NNI, i.e. Internal NNI
and External NNI, respectively.
REST
Representational State Transfer
SAP
Service Access Point
TMF
TeleManagement Forum – an industry association for service providers and suppliers in the
telecommunications market. The strategic goal of the association is to create standard
interfaces to allow consistent network management across different suppliers. Converge
EMS service inventory and management follow the association’ recommendations for
telecom and IT business processes, collectively known as Telecom Operations Map.
UNI
User-to-Network Interface – the UNI is the physical interface or port that is the demarcation
between the customer and the service provider/Cable Operator/Carrier/MSO. It is ALWAYS
provided by the Service Provider. In Carrier Ethernet, a UNI is a PHYSICAL INTERFACE
33620 Rev. A www.transition.com Page 6 of 120
Transition Networks ConvergeTM EMS API Guide for Service Activation

that carries traffic at the operational speed of 10Mbs, 100Mbps, 1Gbps or 10Gbps. UNIs can
be further divided into UNI-C and UNI-N, i.e. customer-facing UNI, and network-facing
UNI, respectively.
URI
Uniform Resource Identifier
VLAN
Virtual Local Area Network
33620 Rev. A www.transition.com Page 7 of 120
Transition Networks ConvergeTM EMS API Guide for Service Activation

Overview
Converge EMS API – Application Programming Interface, makes it possible for third- party
developers to integrate applications with Converge EMS. Converge’s 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

Note: 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 API service activation is provided in Service
Activation over API.
33620 Rev. A www.transition.com Page 8 of 120
Transition Networks ConvergeTM EMS API Guide for Service Activation

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
33620 Rev. A www.transition.com Page 9 of 120
Transition Networks ConvergeTM EMS API Guide for Service Activation

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
33620 Rev. A www.transition.com Page 10 of 120