NBI GUIDE

5529 Access Provisioning Center

Release 9.2.30
Preconfiguration Northbound Interface Guide
3JL-02001-BDAB-RKZZA Edition 02
IMPORTANT NOTICE: This document contains confidential information that is proprietary to
Alcatel-Lucent. No part of its contents may be used, copied, disclosed or conveyed to any party
in any manner whatsoever without prior written permission from Alcatel-Lucent.

www.alcatel-lucent.com

Alcatel, Lucent, Alcatel-Lucent, and the Alcatel-Lucent logo are registered trademarks of
Alcatel-Lucent. All other trademarks are the property of their respective owners. The
information presented is subject to change without notice. Alcatel-Lucent assumes no
responsibility for inaccuracies contained herein. © 2015 Alcatel-Lucent. All rights reserved.
5529 APC Release 9.2.30 Preconfiguration Northbound Interface Guide

Notice

The product specification and/or performance levels contained in this document are for
information purposes only and are subject to change without notice. They do not represent any
obligation on the part of Alcatel-Lucent. Such obligations will only be committed to in a
written sales agreement signed by Alcatel-Lucent.

Alcatel-Lucent 3JL-02001-BDAB-RKZZA Edition 02 July 2015 | 2

5529 APC Release 9.2.30 Preconfiguration Northbound Interface Guide

Contents
1 What’s new................................................................................ 5
1.1 What’s new in Release 9.2.30 Patch 07 ..................................................5
1.2 What’s new in Release 9.2.30 Patch 05 ..................................................5
1.3 What’s new in Release 9.1.10 .............................................................5
2 Introduction ............................................................................... 6
2.1 WSDL file ......................................................................................7
2.2 Northbound interface security.............................................................8
MSAI services..................................................................................8
2.3 Web services ..................................................................................8
3 Operations for preconfiguration management ..................................... 9
3.1 preConfigure operation .....................................................................9
3.2 preUnconfigure operation ................................................................ 11
3.3 preModify operation ....................................................................... 11
3.4 preModifyTemplateInstance operation................................................. 11
3.5 setPreConfigureFlags operation ......................................................... 12
3.6 preDbclean operation ..................................................................... 13
3.7 switchToPreconfigure operation ........................................................ 13
4 Service inventory ...................................................................... 13
4.1 getPreConfiguredTemplates operation................................................. 13
4.2 getPreConfiguredTemplate operation .................................................. 14
4.3 getPreconfiguredLogicalPorts operation ............................................... 14
4.4 getPreConfigureFlags operation ......................................................... 14
5 Error management ..................................................................... 14
6 Configuration change notifications ................................................. 15

Alcatel-Lucent 3JL-02001-BDAB-RKZZA Edition 02 July 2015 | 3

5529 APC Release 9.2.30 Preconfiguration Northbound Interface Guide

List of tables
Table 1: What’s new in Release 9.1.10 ................................................................................5
Table 2: Web services, operations, and parameters.................................................................8
Table 3: objectName parameter description .........................................................................9
Table 4: preConfigure operation parameters ....................................................................... 10
Table 5: preModifyTemplateInstance operation parameters ..................................................... 12
Table 6: setPreConfigureFlags operation parameters ............................................................. 12
Table 7: Error codes in preconfiguration interface ................................................................ 15

Alcatel-Lucent 3JL-02001-BDAB-RKZZA Edition 02 July 2015 | 4

5529 APC Release 9.2.30 Preconfiguration Northbound Interface Guide

1 What’s new

1.1 What’s new in Release 9.2.30 Patch 07

For preconfiguration and configuration change notifications, Alcatel-Lucent

recommends that you use the 9.1 service access point, which is valid for 5529 APC
Release 9.2.30 Patch 07.
For regular service provisioning, Alcatel-Lucent recommends that you use the 9.2
service access point.
The 5529 APC Release 9.2.30 Patch 07 aligns with the 5520 AMS Release 9.2.30 Patch
07.

1.2 What’s new in Release 9.2.30 Patch 05

For preconfiguration and configuration change notifications, Alcatel-Lucent

recommends that you use the 9.1 service access point, which is valid for 5529 APC
Release 9.2.30 Patch 05.
For regular service provisioning, Alcatel-Lucent recommends that you use the 9.2
service access point.
The 5529 APC Release 9.2.30 Patch 05 aligns with the 5520 AMS Release 9.2.30 Patch
05.

1.3 What’s new in Release 9.1.10

The following table describes the new features and enhancements documented in the
5529 APC Preconfiguration Northbound Interface Guide for Release 9.1.10.
The 5529 APC Release 9.1.10 aligns with the 5520 AMS Release 9.1.10.

Table 1: What’s new in Release 9.1.10

Feature Description See

New service access point in R9.1.10
preConfigure operation
preUnconfigure operation
A new service access point is available to allow WSDL file
the preconfiguration of ports
The preConfigure operation preconfigures a preConfigure
service template on a target object in the operation
5529 APC
The preUnconfigure operation removes the preUnconfigure
retained preconfigured template from the operation
target object in the APC 5529

Alcatel-Lucent 3JL-02001-BDAB-RKZZA Edition 02 July 2015 | 5

5529 APC Release 9.2.30 Preconfiguration Northbound Interface Guide

Feature Description See

preModify operation The preModify operation modifies the preModify operation

preModifyTemplateInstance operation
setPreConfigureFlags operation
preDbclean operation
switchToPreconfigure operation
getPreconfiguredTemplates operation
getPreconfiguredTemplate operation
getPreLogicalPorts operation
getPreConfigureFlags operation
argument values of a preconfigured template
on a port in the 5529 APC
The preModifyTemplateInstance operation preModifyTemplateIns
modifies the instance label of the already tance operation
preconfigured template on a given target
object or port
The setPreConfigureFlags operation sets the setPreConfigureFlags
values for the preconfiguration flags at the operation
physical port
The preDbclean operation removes all the preDbclean operation
preconfiguration for the user port or target
object in 5529 APC
The switchToPreconfigure operation forces the switchToPreconfigure
switch to the preconfiguration service operation
templates for the selected physical port
The getPreconfiguredTemplates operation getPreConfiguredTem
retrieves all the retained pre-configured plates operation
template details for the given port or target
object
The getPreconfiguredTemplate operation getPreConfiguredTem
retrieves the retained pre-configured template plate operation
details for the given port or target object
The getPreLogicalPorts operation retrieves all getPreconfiguredLogic
the logical ports for a given target object. alPorts operation
The getPreConfigureFlags operation retrieves getPreConfigureFlags
the values for the preconfiguration flags at the operation
physical port

2 Introduction
The northbound interface Web services allow an OSS client application to preconfigure
service templates for a port as a set of alternate services. The Web services interface supports
operations that allow the management of these preconfigured service templates. Based on a
trigger, the 5529 APC switches the port to the preconfigured service templates, and switches
the configured service templates to preconfiguration; in the 5529 APC R9.2.30, the trigger is
a mode mismatch trap.
The Web services interface for preconfiguration also supports an operation that forces the
switch. Two additional operations allow authorizing a port to switch or not, and a port to
switch back or not. There are also operations to retrieve the inventory of preconfigured
templates. The Web services interface can be combined with the 5529 APC native Web
services interface to retrieve details of the services templates, as well as service template
metadata due to the fact that the service templates for actual configuration and
preconfiguration are common.

Alcatel-Lucent 3JL-02001-BDAB-RKZZA Edition 02 July 2015 | 6

5529 APC Release 9.2.30 Preconfiguration Northbound Interface Guide

In an auto-moding solution, the OSS client which acts as client of 5529 APC takes care of the
following:
> Regular provisioning of all services on ISAM ports using 5529 APC service templates
by way of the 5529 APC XML/SOAP NBI (described in the 5529 APC Northbound
Interface Specification Guide (3JL-02001-BDAA-RKZZA)). This includes the
provisioning of the subscriber specific attributes and variables of the services that
may vary according to the definition of these services (typically arguments of the
defined service templates).
> Pre-provisioning services for auto-moding on ISAM ports using the
pre-configuration 5529 APC XML/SOAP NBI (described in this guide). This includes
provisioning of the subscriber specific attributes and variables of the preconfigured
services that may vary according to the definition of these services (typically
arguments of the defined service templates).
> Optionally, the OSS client or other OSS clients can receive notifications on
success/failure of auto-moding switches using JMS (see section 6 for details).
The prequalification of the lines, as well as the desired QoS configuration, is in responsibility
of the OSS client. The QoS configuration of the lines can be done by provisioning service
templates and their arguments.

2.1 WSDL file

The Northbound interface and all Web services are published using the associated
WSDL file that is located in the 5529 APC Open Interfaces Developer Kit. Contact your
Alcatel-Lucent technical representative to request the WSDL file.
The WSDL file contains the following:
> The operations that are available over the Northbound interface for each 5529 APC
operation.
> The arguments and return types for each operation.
> The binding information that describes how the service is implemented; for the NBI,
SOAP is used as the messaging protocol and document/literal is used as the data
encoding style. The URL that must be used to invoke the services is:
http://apcHost:8080/soap/services/ApcRemotePort/preconfig/9.1
where apcHost is the hostname or the IP address of the 5529 APC server. The default
TCP port is 8080.
The WSDL file can be used to generate the client stub code. There are converters from
WSDL to different programming languages.
For more information about the WSDL, see http://www.w3c.org/TR/wsdl.

Alcatel-Lucent 3JL-02001-BDAB-RKZZA Edition 02 July 2015 | 7

5529 APC Release 9.2.30 Preconfiguration Northbound Interface Guide

2.2 Northbound interface security

The northbound interface uses the HTTP Basic Authentication mechanism (RFC 2617).
Web service clients must add a username and password to the Authorization Header of
the HTTP message in the Web service requests. The username and password must
match the username and password for the account with a northbound profile, as
configured on the 5529 APC GUI by the system administrator.
If required, contact your 5529 APC application administrator to enable HTTPS by
configuring SSL for OSS clients.

MSAI services

When HTTPS is enabled, the URL to invoke the MSAI services is:
https://apcHost:8443/soap/services/ApcRemotePort/preconfig/9.1
where apcHost is the host name or IP address of the 5529 APC server. The default TCP
port is 8443.

2.3 Web services

The 5529 APC displays the functions of the northbound interface as Web services.
The Web services are grouped in the following categories:
> Service provisioning (preconfiguration operations)
> Service inventory (inventory operation)
The following table describes the 5529 APC Web services, operations, and associated
parameters.

Table 2: Web services, operations, and parameters

Web services Operation Parameters

Service provisioning preConfigure objectName

preUnconfigure templateName
preModify operationInitiator
instanceLabel
version
arguments
preModifyTemplateInstance objectName
templateName
templateVersion
instanceLabel
argument

Alcatel-Lucent 3JL-02001-BDAB-RKZZA Edition 02 July 2015 | 8

5529 APC Release 9.2.30 Preconfiguration Northbound Interface Guide

Web services Operation Parameters

operationInitiator
setPreConfigureFlags objectName
arguments
switchToPreconfigure objectName
checkAlarmPresence
operationInitiator
preDbclean objectName
Service inventory getPreconfiguredTemplates objectName
getPreconfiguredTemplate objectName
templateName
templateVersion
instanceLabel
getPreLogicalPorts objectName
getPreConfigureFlags objectName

See section 5 for information about Web services operation errors.

All supported web services operations use the objectName parameter. Table 3 describes
the supported format of the objectName parameter.

Table 3: objectName parameter description

objectName description Identification format

xDSL port on a DSLAM DSLAM:rack-shelf-slot-port

where
DSLAM is the name of the NE
rack is the rack number of the port
shelf is the shelf number of the port
slot is the slot number of the port
port is the port number
Example: ISAM25:1-1-3-2

3 Operations for preconfiguration management

This section describes the operations that allow the OSS client to manage the life cycle of the
preconfiguration of the port.

3.1 preConfigure operation

The preConfigure operation preconfigures the port or object specified by the

objectName parameter with the selected service template. The selected service template

Alcatel-Lucent 3JL-02001-BDAB-RKZZA Edition 02 July 2015 | 9

5529 APC Release 9.2.30 Preconfiguration Northbound Interface Guide

is determined by the template name, the template version and, optionally, the
instanceLabel parameters; for details about the instanceLabel parameter, see the 5529
APC Northbound Interface Specification Guide.
A successful preConfigure operation updates the 5529 APC with the service
preconfiguration for the specified object name. The preConfigure operation has no effect
on the corresponding object in the NE when operation is applied.
The preConfigure operation can be used more than once to configure specific services on
a port if the service templates that are being used are compatible for configuration; the
template compatibility is determined by the 5529 APC service template designer at the
service provider. The preConfigure operation behaves atomically. If an error occurs
during the execution of the operation, the 5529 APC performs a rollback for the port.
For auto-moding, all the service templates that are being preconfigured on a port need to
have the same service type: either ATM or PTM. All service templates actually applied on
the port need to also have the same service type; typically, this service type is the reverse
of the service type of service templates used for preconfiguration: PTM or ATM. The
service type of a service template can be retrieved by using the getTemplateMetaData
operation from the 5529 APC NBI.
In an auto-moding solution, only the service templates that are in the RELEASED state
need to be used for preconfiguration, as well as for configuration. Template state can be
obtained by using the getTemplate operation from the 5529 APC NBI.
For information about error handling, see section Error management.
The following table describes the operation parameters for the preConfigure operation.
There are no parameters for the response unless there is an error.

Table 4: preConfigure operation parameters

Parameter Description

objectName The name of the port or object that is the operation target
templateName The name of the service template for the operation
operationInitiator The system and user ID of the user who is initiating the change to the
preconfiguration of a port or object. This parameter is optional.
instanceLabel This parameter is applicable only to multi-instance templates. It is not
applicable to regular templates. The use of regular templates is
recommended. To distinguish multiple-instance templates from regular
templates, see the getTemplateMetaData operation in the 5529 APC
Northbound Interface Specification Guide.
version This parameter specifies the template version. It is recommended to always
use the latest template version. This can be done by not specifying the
template version in the operation.
arguments This is a list of template argument values. The mandatory arguments need
to be specified if they do not have default values in the template. Optional
arguments can also be specified. An argument value specified in the

Alcatel-Lucent 3JL-02001-BDAB-RKZZA Edition 02 July 2015 | 10

5529 APC Release 9.2.30 Preconfiguration Northbound Interface Guide

Parameter Description
operation has precedence over the default template argument value.

3.2 preUnconfigure operation

The preUnconfigure operation unconfigures the specified service template instance from
the port specified by the objectName parameter (representing the physical port or an
object created on top of the physical port in the 5529 APC, depending on the service
template). For the operation to be successful, the selected service template instance
needs to be preconfigured on the object before the operation is performed. The
objectName parameter and the templateName parameter determine the configuration to
be unconfigured.
A successful preUnconfigure operation updates the 5529 APC, and has no effect on the
port in the NE.
The preUnconfigure operation can be used more than once to unconfigure specific
services. This operation behaves atomically. If an error occurs, the 5529 APC performs a
rollback on the port.
The preUnconfigure operation parameters are the same as the preConfigure operation
parameters; see Table 4. There are no parameters for the response unless there is an
error.

3.3 preModify operation

The preModify operation changes the specified preconfigured service template instance
at the specified target object, which can be a physical port or a logical port where the
service template can be configured. The objectName parameter, the templateName
parameter, the instance label parameter (in case of a multiple-instance template) and
the template arguments determine the object to be modified. The preModify operation
can modify both the modifiable and non modifiable template arguments of the service
template instance.
This operation behaves atomically. If an error occurs, the 5529 APC performs a rollback
for the port. The preModify operation parameters are the same as the preconfigure
operation parameters; see Table 4. There are no parameters for the response unless
there is an error.

3.4 preModifyTemplateInstance operation

The preModifyTemplateInstance operation modifies the instance label parameter for a

service template instance that has been preconfigured on an object. The operation
applies only to clients that use multiple-instance templates. If the new instance label is

Alcatel-Lucent 3JL-02001-BDAB-RKZZA Edition 02 July 2015 | 11

5529 APC Release 9.2.30 Preconfiguration Northbound Interface Guide

provided, the format must conform to the instance label naming convention for the
template. This operation behaves atomically.
Contact your template designer to be aware of the instance label naming rules for multi-
instance templates.
Table 5 describes the parameters for the preModifyTemplateInstance operation. There
are no parameters for the response unless there is an error.

Table 5: preModifyTemplateInstance operation parameters

Parameter Description

objectName The name of the port or object that is the operation target
templateName The name of the service template for the operation
operationInitiator The system and user ID of the user who is initiating the change to the
preconfiguration of a port or object. This parameter is optional.
instanceLabel This parameter is applicable only to multi-instance templates. It is not
applicable to regular templates. The use of regular templates is
recommended. To distinguish multiple-instance templates from regular
templates, see the getTemplateMetaData operation in the 5529 APC
Northbound Interface Specification Guide.
version This parameter specifies the template version. It is recommended to always
use the latest template version. This can be done by not specifying the
template version in the operation.
arguments This is a list of template argument values. The mandatory arguments need
to be specified if they do not have default values in the template. Optional
arguments can also be specified. An argument value specified in the
operation has precedence over the default template argument value.
The argument name is always instanceLabel. The argument value is the new
instance label.

3.5 setPreConfigureFlags operation

The setPreConfigureFlags operation controls the auto-mode switch and switchback by

setting the appropriate flags on a port. This operation behaves atomically. If this
operation is not applied or used on ports, in general, all ports get the default value for
the preconfiguration flags, as specified at the 5529 APC system level. If the default values
are chosen well, there is no need to use these flags unless there are business events that
justify changing the value of a preconfiguration flag for a specific port.
The following table describes the parameters for the setPrecConfigureFlags operation.
There are no parameters for the response unless there is an error.

Table 6: setPreConfigureFlags operation parameters

Parameter Description

objectName The name of the port or object that is the operation target
arguments This is a list of template argument names and values. The argument name

Alcatel-Lucent 3JL-02001-BDAB-RKZZA Edition 02 July 2015 | 12

5529 APC Release 9.2.30 Preconfiguration Northbound Interface Guide

Parameter Description
can be IS_AUTHORIZED or IS_SWITCHBACK_ALLOWED. The argument value
can be true or false.

3.6 preDbclean operation

The preDbclean operation allows the OSS client application to remove all the
preconfiguration that is associated with the port identified by the objectName parameter
at the 5529 APC level. For details about the objectName parameter, see the 5529 APC
Northbound Interface Specification Guide.
The port configuration in the NE is not affected. There are no parameters for the
response unless there is an error. The preDbClean operation also removes all instances
of multiple-instance templates, if applicable.

3.7 switchToPreconfigure operation

The switchToPreconfigure operation allows the OSS client application to trigger the
switch to the preconfigured services on the port or object defined by the objectName
parameter. This operation behaves atomically. For details about the objectName
parameter, see the 5529 APC Northbound Interface Specification Guide.
If the switch fails, the operation attempts to roll back to the previous state of the port.
There are no parameters for the response unless there is an error.

4 Service inventory
The service inventory Web services allow the OSS client application to retrieve information
about the templates preconfigured on the port.

4.1 getPreConfiguredTemplates operation

The getPreConfiguredTemplates operation provides information about the service

templates that have been
> preconfigured on an object (typically, a physical port) as retained by the 5529 APC as
result of all the preconfiguration operations called on the object
OR
> turned into preconfiguration templates as a result of an auto-mode switch or a
switchback

Alcatel-Lucent 3JL-02001-BDAB-RKZZA Edition 02 July 2015 | 13

5529 APC Release 9.2.30 Preconfiguration Northbound Interface Guide

The list of templates can refer to any valid combination of template instances that were
configured for the object. The getPreConfiguredTemplates operation also provides the
template arguments and their associated values. The instanceLabel parameter for a
template can be provided, if applicable.

4.2 getPreConfiguredTemplate operation

The getPreConfiguredTemplate operation provides the details of the specified service

template instance that was preconfigured on the specified object; typically, the object is
a physical port or a logical port that the template has been preconfigured on.
The getPreConfiguredTemplate operation also returns the template arguments and their
values. The instanceLabel for a template can be provided, if applicable. See Table 2 for
information about the objectName, templateName, version, and instanceLabel (if
applicable) parameters.

4.3 getPreconfiguredLogicalPorts operation

The getPreconfiguredLogicalPorts operation provides a list of all of the logical ports that
are in the scope of the port that is preconfigured, as indicated by the objectName
parameter. Logical ports start to exist as a result of the preconfiguring of service
templates on a physical port. Logical ports stop to exist as a result of the pre-
unconfiguring of service templates on a port or an object; the logical port name can be
used as the target object name in subsequent operations.

4.4 getPreConfigureFlags operation

The getPreConfigureFlags operation retrieves the state of the flags on the preconfigured
port. If the flags are not set by the setPreConfigureFlags operation, then the operation
retrieves the default values of the PreConfiguredFlags. The objectName parameter
specifies the preconfigured port.

5 Error management
The following table describes the possible error codes for the preconfiguration interface. For
details about error management, see the 5529 APC Northbound Interface Specification
Guide.

Alcatel-Lucent 3JL-02001-BDAB-RKZZA Edition 02 July 2015 | 14

5529 APC Release 9.2.30 Preconfiguration Northbound Interface Guide

Table 7: Error codes in preconfiguration interface

Error code Description

ATTRIBUTE_VALUE_GENERATION_ALGORITHM_MISSING The required Attribute Value Generation plug-in is

missing or not active. See NBI guide for details on
Argument Value Generation
ATTRIBUTE_VALUE_GENERATION_FAILED The plug-in that contains the attribute value generation
formula encountered a problem while generating a value
for an attribute. See NBI guide for details on Argument
Value Generation.
DSLAM_NOT_FOUND The NE specified in the request is not present in the
5529 APC
GENERIC Error conditions that cannot be categorized by other
error codes
HIGHER_LAYER_CONFIGURED The requested template for unconfiguration is associated
with a higher-layer template that needs to be
unconfigured first
ILLEGAL_TEMPLATE_STATE The template name and version specified in the request
cannot be used because of the associated state; for
example, draft.
INVALID_ARGUMENT An unexpected argument was provided for the request
INVALID_PORT_ADDRESS The port address that is specified in the request does not
contain the correct syntax
INVALID_TEMPLATE_VERSION The template version for the request does not exist
LICENSE_PROBLEM There is a problem with the 5529 APC license
LOWER_LAYER_NOT CONFIGURED The template for a configure request requires a lower
layer template to be configured first
MISSING_ARGUMENT A mandatory template attribute that was defined as an
argument without a default value is not present in the
request
TEMPLATE_ALREADY_CONFIGURED A template is being applied to the port and cannot be
reapplied
TEMPLATE_NOT_CONFIGURED A template is used in an operation for a port, but the
template is not configured for the port
TEMPLATE_UNKNOWN The template does not exist or is unknown by the 5529
APC
UNSUCCESSFUL_OPERATION No pre-configured templates on the port. Skipping the
auto mode switching.
Port is not authorized for auto mode switching.
TPS-TC mismatch alarm is not active.

6 Configuration change notifications

Configuration change notifications are sent on notification topics, which are JMS topics. An
OSS client retrieves its applicable JMS topic by querying the notification interface using the
getNotificationTopic operation; for details, see the 5529 APC Northbound Interface

Alcatel-Lucent 3JL-02001-BDAB-RKZZA Edition 02 July 2015 | 15

5529 APC Release 9.2.30 Preconfiguration Northbound Interface Guide

Specification Guide. The OSS client application needs to subscribe (or unsubscribe, if
required) using the JMS subscription API.
Configuration change notifications (JMS message) are also sent after completion of the
auto-mode switch or switchback. The OSS client applications that have subscribed to
notifications receive the full service provisioning request, as well as its response in the
configuration change notification. A configuration change notification is sent for each
configuration step that is needed to establish the auto-moding switch or auto-moding
switchback. As a result, the subscribed OSS clients can judge what has occurred on the port
while the auto-mode switch or switchback was performed.
The configuration change notification that is specific to the auto-mode switch and switchback
carries a predefined operationInitiator value of “auto-moding-agent”.
See the 5529 APC Northbound Interface Specification Guide for details about the content of
a configuration change notification message. The message is formatted according to the
MTOSI 1.1 standard requirements.

End of document

Alcatel-Lucent 3JL-02001-BDAB-RKZZA Edition 02 July 2015 | 16