NX Soap v2b1

Integration Guide

NX SOAP API Guide

NX SOAP API Guide

© 2010 Allot Communications. All rights reserved. 2

Important Notice Allot Communications Ltd. ("Allot") is not a party to the purchase agreement under which NetEnforcer was purchased,

and will not be liable for any damages of any kind whatsoever caused to the end users using this manual, regardless of

the form of action, whether in contract, tort (including negligence), strict liability or otherwise.

SPECIFICATIONS AND INFORMATION CONTAINED IN THIS MANUAL ARE FURNISHED FOR

INFORMATIONAL USE ONLY, AND ARE SUBJECT TO CHANGE AT ANY TIME WITHOUT NOTICE, AND

SHOULD NOT BE CONSTRUED AS A COMMITMENT BY ALLOT OR ANY OF ITS SUBSIDIARIES. ALLOT ASSUMES NO RESPONSIBILITY OR LIABILITY FOR ANY ERRORS OR INACCURACIES THAT MAY

APPEAR IN THIS MANUAL, INCLUDING THE PRODUCTS AND SOFTWARE DESCRIBED IN IT.

Please read the End User License Agreement and Warranty Certificate provided with this product before using the product. Please note that using the products indicates that you accept the terms of the End User License Agreement and

Warranty Certificate.

WITHOUT DEROGATING IN ANY WAY FROM THE AFORESAID, ALLOT WILL NOT BE LIABLE FOR ANY SPECIAL, EXEMPLARY, INDIRECT, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND,

REGARDLESS OF THE FORM OF ACTION WHETHER IN CONTRACT, TORT (INCLUDING NEGLIGENCE),

STRICT LIABILITY OR OTHERWISE, INCLUDING, BUT NOT LIMITED TO, LOSS OF REVENUE OR ANTICIPATED PROFITS, OR LOST BUSINESS, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH

DAMAGES.

Copyright Copyright © 1997-2010 Allot Communications. All rights reserved. No part of this document may be reproduced, photocopied, stored on a retrieval system, transmitted, or translated into any other language without a written permission

and specific authorization from Allot Communications Ltd.

Trademarks Products and corporate names appearing in this manual may or may not be registered trademarks or copyrights of their

respective companies, and are used only for identification or explanation and to the owners' benefit, without intent to infringe.

Allot and the Allot Communications logo are registered trademarks of Allot Communications Ltd.

NOTE: This equipment has been tested and found to comply with the limits for a Class A digital device, pursuant to Part 15 of the FCC Rules. These limits are designed to provide reasonable protection against harmful interference when the

equipment is operated in a commercial environment. This equipment generates, uses, and can radiate radio frequency

energy and, if not installed and used in accordance with the instruction manual, may cause harmful interference to radio communications. Operation of this equipment in a residential area is likely to cause harmful interference in which case

the user will be required to correct the interference at his own expense.

Changes or modifications not expressly approved by Allot Communication Ltd. could void the user's authority to operate the equipment.

NX SOAP API Guide


Version History

Document Version Date NX Version

v1b1 4.11.09 NX10.1.1

v2b1 15.4.10 NX10.2.1

NX SOAP API Guide


Table of Contents

1. Introduction ............................................................................................................ 6

1.1. Allot’s NetXplorer System .............................................................................. 6

1.2. Terms and Concepts ........................................................................................ 6

1.2.1 Catalog ..................................................................................................... 6

1.2.2 Line .......................................................................................................... 6

1.2.3 Pipe .......................................................................................................... 6

1.2.4 Virtual Channel ........................................................................................ 7

1.2.5 Tube ......................................................................................................... 7

1.2.6 NetEnforcer .............................................................................................. 7

1.2.7 Service Gateway ...................................................................................... 7

1.3. Acronyms ........................................................................................................ 8

1.4. Web Services ................................................................................................... 8

2. Typical NX Data Flow ........................................................................................... 9

3. NX WSDL Overview ........................................................................................... 10

3.1. WSDL Files ................................................................................................... 10

3.2. Operations ..................................................................................................... 10

3.3.1 Policy Operations ................................................................................... 10

3.3.2 Catalog Operations................................................................................. 10

3.3.3 Topology Operations ............................................................................. 10

3.3.4 Web Update Operations ......................................................................... 10

3.3. Typical Work-Flow ....................................................................................... 11

4. WSDL Methods ................................................................................................... 11

4.1. Policy Methods .............................................................................................. 11

4.1.1 Policy ..................................................................................................... 11

4.1.2 TCAs ...................................................................................................... 12

4.1.3 TubeGroups............................................................................................ 12

4.1.4 Pipe ........................................................................................................ 13

4.1.5 VC .......................................................................................................... 13

4.2. Catalog Methods ........................................................................................... 14

NX SOAP API Guide


4.2.1. Resolving Catalog Names ...................................................................... 14

4.2.2. TOS Catalogs ......................................................................................... 14

4.2.3. QOS Catalogs......................................................................................... 14

4.2.4. DOS Catalogs......................................................................................... 15

4.2.5. VLAN Catalogs ..................................................................................... 15

4.2.6. Alert Catalogs ........................................................................................ 16

4.2.7. Application Catalogs .............................................................................. 17

4.2.8. Integrated Service Catalogs (Previously known as CoC Catalogs) ....... 17

4.2.9. Service Chains (Also known as CoCGroup) ......................................... 18

4.2.10. Host .................................................................................................... 18

4.2.11. Host Group ......................................................................................... 19

4.2.12. Service ................................................................................................ 19

4.2.13. Service Groups ................................................................................... 20

4.2.14. Time ................................................................................................... 20

4.2.15. Service Plan ........................................................................................ 21

4.3. Topology Methods ........................................................................................ 21

4.3.1. Devices ................................................................................................... 21

4.4. WebUpdates Methods ................................................................................... 22

4.4.1. Device .................................................................................................... 22

4.4.2. Server ..................................................................................................... 22

NX SOAP API Guide


1. Introduction

1.1. Allot’s NetXplorer System

Allot’s NetXplorer system provides essential functions to manage IP/broadband

services efficiently and profitably. NetXplorer is a highly scalable centralized

management platform providing a single access point for Allot NetEnforcer® or

Service Gateway deployments of any size, delivering unsurpassed network visibility.

Managers can monitor, provision and consolidate information simultaneously across

multiple Allot Network elements.

1.2. Terms and Concepts

This section introduces some of the basic terms and concepts used in the Allot’s

NetXplorer management system.

1.2.1 Catalog

Catalog entries, which are defined in the catalog editor, serve as conditions or actions

in the rules which make up a policy. In this way, they can be seen as the building

blocks of your policy. Once a catalog has been defined in the catalog editor, it can be

reused in different rules.

1.2.2 Line

A line is a logical entity within a policy and represents the highest level of hierarchy.

The total bandwidth running through the NetEnforcer or Service Gateway can be

divided into lines and each line can then be managed as if it were an independent link.

A line consists of a rule based on one or more sets of conditions and a set of actions

that apply when all of the conditions are met. The default fallback line exists in every

policy. Additional lines can then be added above the fallback line in the policy table.

The fallback line consists of a filter which cannot be modified or deleted. Traffic

which is not classified in any of the lines above it in the hierarchy, will be classified in

the fallback line. Every line, including the fallback line, contains one or more pipes.

1.2.3 Pipe

A pipe is a logical entity within a policy. The total bandwidth running through each

line can be divided into pipes, and each pipe can then be managed independently.

Each pipe consists of a rule based on one or more sets of conditions and a set of

actions that apply when all of the conditions are met. By default, every line contains

at least one pipe – the fallback pipe. Additional pipes can then be added above the

fallback pipe in the policy table. The filter of the fallback pipe cannot be modified or

deleted, and traffic that is not classified into any other pipes within a given line will

be classified in the fallback pipe. Every pipe, including the fallback pipe, contains one

or more virtual channels.

NX SOAP API Guide


1.2.4 Virtual Channel

A Virtual Channel (VC) is a logical entity within a policy and represents the most

granular level of policy hierarchy. The total bandwidth running through each pipe can

be divided into VCs, and each VC can then be managed independently. Each VC

consists of a rule based on one or more sets of conditions and a set of actions that

apply when all of the conditions are met. By default, every pipe contains at least one

VC – the fallback VC. Additional VCs can then be added above the fallback VC in

the policy table. The filter of the fallback VC cannot be modified or deleted, and

traffic that is not classified into any other VCs within a given pipe will be classified in

the fallback VC.

1.2.5 Tube

A generic term, used to designate a line, pipe or VC

1.2.6 NetEnforcer

The NetEnforcer is a broadband optimization device which collects traffic statistics

from the network and can implement quality of service per application and per

subscriber. Traffic statistics are collected in order to provide both real-time and long-

term data about the network. As well as collecting detailed information about the

traffic passing through, it, the NetEnforcer can also shape that traffic, applying quality

of service parameters which have been pre-defined by the user.

1.2.7 Service Gateway

The Service Gateway is a platform for enhancing service optimization and service

deployment. The Service Gateway provides an open, carrier-grade solution for

broadband service providers to manage multiple 10 or 1 Gigabit lines and deploy

value added services in one integrated platform. Application and subscriber

information within the Service gateway is identified for each traffic flow and

subsequently the flow is dispatched to an array of additional services and actions

using a single DPI process.

NX SOAP API Guide


1.3. Acronyms

DPI Deep Packet Inspection

NX NetXplorer

NE NetEnforcer

VC Virtual Channels

P2P Peer to Peer

SG Service Gateway

SMP Subscriber Management Platform.

ToS Type of Service

QoS Quality of Service

SOAP Simple Object Access Protocol

WSDL Web Services Data Language

1.4. Web Services

Allot has opened the NetXplorer server application to enable access by external

programs and system components. This enables other components to communicate

with the NX server via WSDL (web services data language). The common language

for doing this is SOAP. Third party applications can therefore be written in any

language that enables that application to view and update the XML files used in the

NetXplorer application server.

To activate the WS interface a WSDL file must be used to generate a code artifact.

This artifact may then be used to establish interaction with the NX Server via the WS

interface. The full WSDL file can be accessed from the NX Server as shown in

section ‎3.1 below.

NX SOAP API Guide


2. Typical NX Data Flow The diagram below illustrates the typical management data flow through the Allot

solution

The NetXplorer architecture consists of three layers:

The DPI & QoS layer. This layer can include several NetEnforcer or Service

Gateway devices that implement the network management policies and collect

network usage data.

The NetXplorer Server Layer. This incorporates the actual NetXplorer application,

including the databases. Managing and communicating with the different clients that

access the system, it facilitates NetEnforcer or Service Gateway configuration, policy

provisioning, alarms, monitoring and reporting. The NetXplorer also includes an

integrated data collector, that streamlines the required collection of data from the

managed NetEnforcer or SG devices. In larger NetEnforcer deployments, and

deployments involving Service Gateways an external data collector is deployed

User Interface Layer. The user interface client can be installed on any computer on

the network that can connect to the NetXplorer server. It gives the operator access to a

graphic user interface to manage the solution. Alternatively, the NetXplorer server

can be accessed directly through an open SOAP interface which is described in this

document.

NX SOAP API Guide


3. NX WSDL Overview

3.1. WSDL Files

Each NetXplorer server includes a webservices interface. The WSDL file can be

accessed from the link below, with the IP address of the relevant NX server inserted

accordingly.

http://<NX-SERVER-IP>/nx/services/WsNxServices?wsdl

3.2. Operations

There are 4 different NX Web Service operations:

3.3.1 Policy Operations

Policy operations relate to the rules which make up the policy. The policy rules fit

into a 3-level hierarchy which consists of lines, pipes and virtual channels. Policy

operations are required to add, modify or delete lines, pipes and virtual channels.

3.3.2 Catalog Operations

Catalog operations relate to the building blocks of the rules – the condition and action

catalog entries. Once defined, these catalog entries are used to make up line, pipe or

VC rules. Catalog operations are required to add, get, delete or update catalogs

3.3.3 Topology Operations

Topology operations relate to the devices (Allot Service Gateways and NetEnforcers)

that make up the Allot system topology. Topology operations are used to add, get,

import or delete devices to be managed by the NetXplorer Server.

3.3.4 Web Update Operations

Web update operations refer to Allot’s Protocol update mechanism (APU), which

enables the administrator to regularly update the Service Catalog with signatures for

the latest applications and protocols, without any system downtime. Web Update

Operations enable the operator to update an NX server or a device (NetEnforcer or

Service Gateway) with the latest protocol pack, or alternatively to roll back to the

previous protocol pack.

NX SOAP API Guide


3.3. Typical Work-Flow

A typical work flow is represented in the table below. In this example the administrator wishes to add a NetEnforcer to the network and create a pipe on the NetEnforcer to apply QoS for traffic generated by a specified user at a specified time of day:

Stage Task Operation Method

1 Add a NetEnforcer device to the network tree

Topology Operation addDevice

2 Create the condition and action catalogs required

Catalog Operation addHostCatalogEntries

addTimeCatalogEntries

addQosCatalogEntries

3 Create a new pipe with the catalogs defined

Policy Operation updatePolicy

4. WSDL Methods

4.1. Policy Methods

4.1.1 Policy

Method Description Parameters Return Value

getPolicy Used to view the current policy on a given NE or SG

Integer – deviceID

Integer – PolicyID

Boolean – skeleton (alerts)

Array (TubeDTO)

updatePolicy Used to update your policy (e.g: to add, update or delete lines, pipes and VCs in a policy)

Integer – deviceID


Array (TubeDTO)

Boolean - local

Boolean – isEventSource

void

exportPolicy Used to export the policy of one device to another

Integer - deviceId Void

exportDefaultPolicy Used to roll a device’s policy back to the default policy

DeviceTopology

DTO

Void

NX SOAP API Guide


4.1.2 TCAs


getTubeTCAs Used to view the threshold

crossing alarms currently

assigned to a line, pipe or

VC

Integer - tubeId Array - (Tube2Alert2ActionDTO)

updateTubeTCA Used to change the

assignment of threshold

crossing alarms to a line,

pipe or VC

Tube2Alert2A

ctionDTO

Void

getDeviceTCAs Used to view the threshold

crossing alarms currently

assigned to a NE or SG

Integer -

deviceId

Array -

(Device2Alert2

ActionDTO)

updateDeviceTCAs Used to change the

assignment of threshold

crossing alarms to a NE or

SG

Device2Alert2

ActionDTO

Void

4.1.3 TubeGroups


getTubeGroups Used to view the groups of lines, pipes or VCs that have been defined

Void Array (TubeGroupDTO)

getTubeGroupsByUser Used to view the groups of lines, pipes or VCs per specified user

Integer Array (TubeGroupDTO)

getTubeGroupsByIds Used to view the groups of lines, pipes or VCs specified by ID

Array (Integer) Array (TubeGroupDTO)

deleteTubeGroups Used to delete specified Line, pipe or VC groups

Array (Integer) Void

addTubeGroups Used to add specified Line, pipe or VC groups

Array (TubeGroupDTO)


updateTubeGrops Used to update specified Line, pipe or VC groups


Void

NX SOAP API Guide


4.1.4 Pipe


getPipes Integer – deviceID


Integer - lineId


Array (TubeDTO)

4.1.5 VC


getVcs Integer – deviceID


Integer – lineId

Integer - pipeId


Array (TubeDTO)

NX SOAP API Guide


4.2. Catalog Methods

4.2.1. Resolving Catalog Names


resolveCatalogNames Used to resolve the

names of specified

catalogs

Array

(CatalogIdentifier)

Array

(CatalogIdentifier)

4.2.2. TOS Catalogs


getTosCatalogEntries Used to get a list of

currently defined

ToS catalog entries

void Array(TosDTO)

deleteTosCatalogEntries Used to delete an

array of ToS

catalog entries

Array(TosDTO) void

addTosCatalogEntries Used to define new

ToS catalog entries

Array(TosDTO) void

updateTosCatalogEntries Used to update

existing ToS

catalog entries

Array(TosDTO) void

getTosEntriesByIds Used to retrieve a

list of ToS catalog

entries by ID

Array(Integer) Array(TosDTO)

4.2.3. QOS Catalogs


getQoSCatalogEntries Used to get a list of

currently defined

QoS catalog entries

void Array(QosDTO)

deleteQoSCatalogEntries Used to delete an

array of QoS

catalog entries

Array(QoSDTO) void

addQoSCatalogEntries Used to define new

QoS catalog entries

Array(QoSDTO) void

updateQoSCatalogEntries Used to update Array(QoSDTO) void

NX SOAP API Guide


existing QoS

catalog entries

getQoSEntriesByIds Used to retrieve a

list of QoS catalog

entries by ID

Array(Integer) Array(QosDTO)

4.2.4. DOS Catalogs


getDoSCatalogEntries Used to get a list of

currently defined

DoS catalog entries

void Array(DosDTO)

deleteDoSCatalogEntries Used to delete an

array of DoS

catalog entries

Array(DoSDTO) Void

addDoSCatalogEntries Used to define new

DoS catalog entries

Array(DoSDTO) Void

updateDoSCatalogEntries Used to update

existing DoS

catalog entries

Array(DoSDTO) Void

getDoSEntriesByIds Used to retrieve a

list of DoS catalog

entries by ID

Array(Integer) Array(DosDTO)

4.2.5. VLAN Catalogs


getVlanCatalogEntries Used to get a list of

currently defined

VLAN catalog

entries

void Array(VlanDTO)

deleteVlanCatalogEntries Used to delete an

array of VLAN

catalog entries

Array(VlanDTO) void

addVlanCatalogEntries Used to define new

VLAN catalog

Array(VlanDTO) void

NX SOAP API Guide


entries

updateVlanCatalogEntries Used to update

existing VLAN

catalog entries

Array(VlanDTO) void

getVlanEntriesByIds Used to retrieve a

list of VLAN

catalog entries by

ID

Array(Integer) Array(VlanDTO)

4.2.6. Alert Catalogs


getAlertCatalogEntries Used to get a list of

currently defined

Alert catalog

entries

void Array(AlertDTO)

deleteAlertCatalogEntries Used to delete an

array of Alert

catalog entries

Array(AlertDTO) void

addAlertCatalogEntries Used to define new

Alert catalog

entries


updateAlertCatalogEntries Used to update

existing Alert

catalog entries


getAlertEntriesByIds Used to retrieve a

list of Alert catalog

entries by ID

Array(Integer) Array(AlertDTO)

getAlertCounterEntriesBy

OIds

Used to get a list of

currently defined

Alert catalog

entries

(Array(String) Array(AlertCounter

DTO)

NX SOAP API Guide


4.2.7. Application Catalogs


getApplicationCatalogEntries Used to get a list of

currently defined

Application catalog

entries

void Array(Application

DTO)

deleteApplicationCatalogEntries Used to delete an

array of Application

catalog entries

Array(Appli

cationDTO)

void

addApplicationCatalogEntries Used to define new

Application catalog

entries

Array(Appli

cationDTO)

void

updateApplicationCatalogEntries Used to update

existing Application

catalog entries

Array(Appli

cationDTO)

void

getApplicationEntriesByIds Used to retrieve a list

of Application

catalog entries by ID

Array(Intege

r)

Array(Application

DTO)

4.2.8. Integrated Service Catalogs (Previously known as CoC Catalogs)


getCocCatalogEntries Used to get a list of

currently defined

Integrated Service catalog

entries

void Array(CocDTO)

deleteCocCatalogEntries Used to delete an array of


entries

Array(CocDTO) void

addCocCatalogEntries Used to define new


entries

Array(CocDTO) void

updateCocCatalogEntries Used to update existing


entries

Array(CocDTO) void

NX SOAP API Guide


getCocEntriesByIds Used to retrieve a list of


entries by ID

Array(Integer) Array(CocDTO)

4.2.9. Service Chains (Also known as CoCGroup)


getCocGroupCatalogEntries Used to get a list of

currently defined Service

Chain catalog entries

void Array(CocGroup

DTO)

deleteCocGroupCatalogEntries Used to delete an array of

Service Chain catalog

entries

Array(CocGrou

pDTO)

void

addCocGroupCatalogEntries Used to define new Service

Chain catalog entries

Array(CocGrou

pDTO)

void

updateCocGroupCatalogEntries Used to update existing


entries

Array(CocGrou

pDTO)

void

getCocGroupEntriesByIds Used to retrieve a list of


entries by ID

Array(Integer) Array(CocGroup

DTO)

4.2.10. Host


getHostCatalogEntries Used to get a list of

currently defined Host

catalog entries

void Array(HostDTO)

deleteHostCatalogEntries Used to delete an array of

Host catalog entries

Array(HostDT

O)

void

addHostCatalogEntries Used to define new Host

catalog entries

Array(HostDT

O)

void

updateHostCatalogEntries Used to update existing

Host catalog entries

Array(HostDT

O)

void

NX SOAP API Guide


getHostEntriesByIds Used to retrieve a list of

Host catalog entries by ID

Array(Integer) Array(HostDTO)

4.2.11. Host Group


getHostGroups Used to get a list of

currently defined Host

Group catalog entries

void Array(HostGrou

pDTO)

deleteHostGroups Used to delete an array of

Host Group catalog entries

Array(HostGro

upDTO)

void

addHostGroups Used to define new Host


Array(HostGro

upDTO)

void

updateHostGroups Used to update existing


Array(HostGro

upDTO)

void

getHostGroupByIds Used to retrieve a list of


by ID

Array(Integer) Array(HostGrou

pDTO)

4.2.12. Service


getServiceCatalogEntries Used to get a list of


catalog entries

void Array(ServiceDT

O)

deleteServiceCatalogEntries Used to delete an array of

Service catalog entries

Array(ServiceD

TO)

void

addServiceCatalogEntries Used to define new Service

catalog entries

Array(ServiceD

TO)

void

updateServiceCatalogEntries Used to update existing

Service catalog entries

Array(ServiceD

TO)

void

getServiceEntriesByIds Used to retrieve a list of

Service catalog entries by

ID

Array(Integer) Array(ServiceDT

O)

NX SOAP API Guide


4.2.13. Service Groups


getServiceGroups Used to get a list of



void Array(ServiceGr

oupDTO)

deleteServiceGroups Used to delete an array of

Service Group catalog

entries

Array(ServiceG

roupDTO)

void

addServiceGroups Used to define new Service


Array(ServiceG

roupDTO)

void

updateServiceGroups Used to update existing


entries

Array(ServiceG

roupDTO)

void

getServiceGroupByIds Used to retrieve a list of


entries by ID

Array(Integer) Array(ServiceGr

oupDTO)

4.2.14. Time


getTimeCatalogEntries Used to get a list of

currently defined Time

catalog entries

void Array(TimeDTO

)

deleteTimeCatalogEntries Used to delete an array of

Time catalog entries

Array(TimeDT

O)

void

addTimeCatalogEntries Used to define new Time

catalog entries

Array(TimeDT

O)

void

updateTimeCatalogEntries Used to update existing

Time catalog entries

Array(TimeDT

O)

void

getTimeEntriesByIds Used to retrieve a list of

Time catalog entries by ID

Array(Integer) Array(TimeDTO

)

NX SOAP API Guide


4.2.15. Service Plan


getServicePlans() Used to get a list of


Plan catalog entries

void Array(ServicePla

nDTO[])

getServicePlansByIds() Used to delete an array of

Service Plan catalog entries

Array(Integer[]

ids)

void

addServicePlans() Used to define new Service

Plan catalog entries

Array(ServicePl

anDTO[])

void

updateServicePlans() Used to update existing


Array(ServicePl

anDTO[])

void

getServicePlanIdByName() Used to retrieve a list of


by ID

String name Integer

4.3. Topology Methods

4.3.1. Devices


getDeviceById Used to view the NEs or

SGs currently in the

network by ID

Integer -

deviceId

DeviceTopology

DTO

getDeviceByName Used to view the NEs or

SGs currently in the

network by name

String- uiName DeviceTopology

DTO

addDevice Used to add an NE or SG

to the network

DeviceTopolog

yDTO

DeviceTopology

DTO

ImportDevice Used to import an NE or

SG into the network

DeviceTopolog

yDTO

void

deleteDevice Used to delete an NE or

SG from the network

DeviceTopolog

yDTO

void

NX SOAP API Guide


4.4. WebUpdates Methods

4.4.1. Device


updateWuDevice Used to update the NE or

SG to the latest protocol

pack

Integer deviceId

Integer updateNumber

Void

rollbackWuDevice Used to roll back the NE or

SG to the last protocol

pack

Integer deviceId

Void

4.4.2. Server


updateWuServer Used to update the NX

server to the latest protocol

pack

Void Void

rollbackWuServer Used to roll back the NX

server to the last protocol

pack

void void

Documents

NX Soap v2b1