Service Controller

Provisioning API Guide

Release 9.6.1-AAA

Document version 1.2 October 26, 2012

The manufacturer (MFR) reserves the right to make changes to this document and the products which it describes without notice.
The MFR shall not be liable for technical or editorial errors or omissions made herein; nor for incidental or consequential damages
resulting from the furnishing, performance, or use of this material or of the accompanying Software or any files derived from the
Software.

Bridgewater Systems Corporation

303 Terry Fox Dr.
Suite 500
Ottawa, Ontario
Canada K2K 3J1
Phone: +1 613 591-6655
Fax: +1 613 591-6656
http://www.bridgewatersystems.com

Bridgewater Customer Support

North America and Puerto Rico: 1-877 943-3772
Mexico (Avantel, Telmex): 00-1-800-514-3772
International: 1-800 943-37726
support@bridgewatersystems.com

Bridgewater, Bridgewater Systems, Widespan and the Bridgewater Systems Logo are the trademarks of Bridgewater Systems
Corporation. Other company or product names referenced may be the trademark or registered trademark of their respective
companies. ©1997-2012 Bridgewater Systems Corporation. All rights reserved.
About this guide
This guide describes the API operations and command line utilities for the
Provisioning Server XML interface.

Audience
The intended audience for this document is:
• application developers
• test developers

Installation
For AAA RPM and package installation procedures, see the Bridgewater
Installation Reference Guide.
For SDB RPM and package installation procedures, see the HSS: Installation and
Configuration Guide.
For Policy Controller RPM and package installation procedures, see the Policy
Controller: Installation and Configuration Guide.

Text conventions

Font or convention Used for Example

Courier System responses and The buffer

messages, sample text files, configuration
and other screen text file:
/opt/aaasc/
config/
buffer_config.xml
is valid

Courier bold Commands entered by the user cd /opt/aaasc/

buffer

Courier bold A variable name that should be .bcvalid -c

italics replaced with an appropriate configfile
value.

Arial Italics Book or document title. Bridgewater Installation

Reference Guide

[...] Sections of an example that <ARTLSndr ID="Send1">

have been omitted for clarity. [...]
</ARTLSndr>

Service Controller 9.6.1-AAA October 26, 2012 Page iii

About this guide Provisioning API Guide

Document history

Date Release Version Comments

July 2012 9.6-AAA 1.0 New for Release 9.6-AAA.

August 2012 9.6-AAA 1.1 Minor updates.

October 2012 9.6.1-AAA 1.2 Removed unsupported VIP

commands.

Related documents
The Release 9.6-AAA documentation consists of the following guides:
• 3G/WLAN Interworking Guide
Describes 3G/WLAN interworking environments. Covers the deployment
options and configuration procedures for 3G/WLAN interworking in a
Bridgewater deployment.
• Accounting Framework Guide
Describes how to configure, operate, and maintain the Accounting Framework,
and how to use the accounting records, and the usage and revenue reports.
• Bridgewater Installation Reference Guide
Describes the deployment options, installation procedures, installation
packages, engineering requirements, and security considerations for
Bridgewater Systems products.
• Bridgewater Master Glossary
Describes the terms and acronyms used in Bridgewater Systems software and
documentation.
• Bridgewater SNMP Guide
Describes how to configure SNMP support for the Bridgewater Systems
software components, and provides reference information about Bridgewater
MIBs. It also describes how to use Key Performance Indicator (KPI) scripts to
obtain SNMP metrics for reporting performance and capacity data. KPI scripts
gather time-based loading level statistics from Bridgewater components.
• CALEA Controller with SS8 Guide
Describes how to install, configure, and operate the CALEA (Communications
Assistance for Law Enforcement Agencies) Controller.
• CALEA Controller with Verint Guide
Describes how to install, configure, and operate the CALEA (Communications
Assistance for Law Enforcement Agencies) Controller.

Page iv October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide About this guide

• Data Streaming Server Guide

Describes how to configure, operate, and troubleshoot the Data Streaming
Server, and lists the DSS log messages.
• Extensible Authentication Protocol Guide
Describes the Extensible Authentication Protocol (EAP) supported by
Bridgewater Systems, including configuration examples and message flows for
the supported EAP methods.
• Prepaid Integrator Guide
Describes how to use the Prepaid Integrator to support customers with prepaid
or volume accounts. Covers CDMA, ECS, DCCA, and WiMAX deployments, as
well as logging, XML file parameters, plugin parameters, and command line
utilities.
• Provisioning Gateway Guide
Describes the Provisioning Gateway, which maps a single provisioning request
from a client to multiple outgoing requests for different target applications. The
guide describes how to use Provisioning Gateway to send provisioning
requests.
• Service Controller: Getting Started Guide
Describes the components of the Bridgewater Service Controller, including the
Resource Management Server. Also describes how to operate and maintain the
deployment.
• Service Controller: Log Messages Guide
Describes the log messages for the RADIUS Server, Diameter Server, the
Provisioning Server, the Accounting Framework, the Prepaid server, the DSS
server, the Provisioning Gateway, and the MAP Gateway.
• Service Controller: Mobile Services Guide
Describes how to configure mobile services such as Simple IP, Mobile IP, A12
Authentication, or WiFi Roaming for the Bridgewater Service Controller.
• Service Controller: Monitoring and Logging Guide
Describes how to operate the monitoring utility, and how to configure, operate,
and maintain the Logging Framework. Also provides an overview of the test
tools.
• Service Controller: Network Access Guide
Describes how to configure the RADIUS Server and the Diameter Server.
• Service Controller: Provisioning API Guide
Describes the Provisioning Server XML interface, operations, client application
design criteria, and the command line utilities for provisioning operations.
• Service Controller: Resource Management Server Guide
Describes how to configure and operate the RMS and its product logs, as well
as the modules dependent on the RMS: the IP Address Manager, User Session
Controller, and Port Quota Controller.

Service Controller 9.6.1-AAA October 26, 2012 Page v

About this guide Provisioning API Guide

• Service Controller: Subscriber and Database Management Guide

Describes how to configure the Provisioning Server and the Profile Database.
• Service Controller: WiMAX Guide
Describes WiMAX networks and how to configure the Service Controller for
WiMAX.

Service Manager documents

The Service Manager documentation consists of the following guides:
• Service Manager: Getting Started Guide for AAA
Describes how to configure, log in, navigate, and use the Service Manager
graphical interface to your Bridgewater deployment. Also describes how to
create and provision the administrators who manage your deployment.
• Service Manager: Network Access Guide for AAA
Describes how to model, and manage network entities, such as PDSNs, and
GGSNs, in a Bridgewater deployment using the Bridgewater Service Manager.
• Service Manager: Services Provisioning Guide for AAA
Describes how to create and provision services, such as a RADIUS connection
service, that are part of a complete service offering to subscribers.
• Service Manager: Subscriber Provisioning Guide for AAA
Describes how to provision subscribers, organizations, profile sets, and service
profiles.

Policy Controller documents

The Policy Controller documentation consists of the following guides:
• Policy Controller: Getting Started Guide
Describes the Bridgewater Policy Controller and PCRF solutions.
• Policy Controller: Installation and Configuration Guide
Describes how to install and configure the Bridgewater Policy Controller and
PCRF products. Also describes the packages and package prompts used to
install the Bridgewater Policy Controller and PCRF.
• Policy Controller: Provisioning Guide
Describes how to create and provision services, subscribers, and network
entities in a Bridgewater Policy Controller or PCRF deployment.
• Policy Controller: API Guide
Describes the APIs and WSDLs supported by the Bridgewater Policy Controller
and PCRF. Also describes how to use APIs and WSDLs to provision the Policy
Controller and PCRF, and to integrate with third party applications.

Page vi October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide About this guide

HSS documents
The HSS documentation consists of the following guides:
• HSS: API Guide
Describes the Provisioning Server XML interface, operations, client application
design criteria, and the command line utilities for provisioning operations.
• HSS: Deployment Planning Guide
Describes how to plan an HSS deployment. Provides information about
servers, the software environment, and troubleshooting logs.
• HSS: Getting Started Guide
Describes the 3GPP (3rd Generation Partnership Project) network specification
for Long Term Evolution (LTE). Also describes the HSS and related products
such as the 3GPP-AAA.
• HSS: Installation and Configuration Guide
Describes the deployment options, installation procedures, and installation
packages for the HSS and related products such as the 3GPP-AAA.
• HSS: IPv6 Implementation Guide
Describes the IPv6 protocol. Also describes how to configure IPv6 for Solaris
and the HSS.
• HSS: Operations and Maintenance Guide
Describes procedures for operating and maintaining an HSS deployment, such
as how to configure HSS policy rules or use HSS test tools.
• HSS: Provisioning Guide
Describes how to provision HSS components in the Profile database using the
Service Manager.

Service Controller 9.6.1-AAA October 26, 2012 Page vii

About this guide Provisioning API Guide

Page viii October 26, 2012 Service Controller 9.6.1-AAA

Contents
About this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii
Text conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii
Document history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iv
Related documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iv
Service Manager documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi
Policy Controller documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi
HSS documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Chapter 1 Provisioning API overview . . . . . . . . . . . . . . . . . . . . . . . . 1

Client application environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
XML interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Using the Service Manager to configure elements . . . . . . . . . . . 3
Programming environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Development tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Command line utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Chapter 2 Data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Service contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Service entity modelling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Service attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Attribute descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Subscriber entity modelling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Profile sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Network entity modelling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Subnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
IP address pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
RMS cluster ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Access node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Access node group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Service Controller 9.6.1-AAA October 26, 2012 Page ix

Contents Provisioning API Guide

WiMAX entity modelling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Access node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
WiMAX device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
WiMAX node group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
WiMAX HA group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Chapter 3 Using the XML interface . . . . . . . . . . . . . . . . . . . . . . . . . 15

Interface access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Communication mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Message structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
XML API version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Sample PERL application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Sample application input files . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Running the sample application . . . . . . . . . . . . . . . . . . . . . . . . . 23
Creating a custom application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Building and sending a request message . . . . . . . . . . . . . . . . . 25
Receiving and parsing the response message . . . . . . . . . . . . . 25
Error responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Application design considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Resource management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Efficiency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Forward compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Error categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
XML provisioning details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Identifying provisionable entities . . . . . . . . . . . . . . . . . . . . . . . . 29
Attribute types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Attribute properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Processing attribute operations . . . . . . . . . . . . . . . . . . . . . . . . . 31
Adding an attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Adding or updating an attribute value . . . . . . . . . . . . . . . . . . . . 33
Deleting an attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Deleting values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Example error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Example error condition #1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Example error condition #2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Example error condition #3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Application Authorization Server specific example . . . . . . . . . . . . . . . . . 37
Provision Application Authorization Server services . . . . . . . . . 37
Provisioning Server logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Page x October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Contents

Chapter 4 Provisioning APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

API libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
AccessNodeAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
AccountAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
DAEAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
DomainAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
HotlineAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
OrganizationAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
ProfileAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Proxy Deployment APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
ServiceAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
SessionAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
SystemAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
TrunkGroupAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
UserAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
WiMAXAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
XML provisioning examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
AccessNodeAPI operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
createAccessNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
deleteAccessNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
getAccessNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
updateAccessNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
AccountAPI operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
createAccount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
createAccountProfileSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
deleteAccount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
findAccounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
getAccount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
getAccountProfileSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
updateAccount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
updateAccountProfileSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
DAEAPI operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
clearHotline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
sendCoA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
sendDisconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Service Controller 9.6.1-AAA October 26, 2012 Page xi

Contents Provisioning API Guide

DomainAPI operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
createDomain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
createDomainProfileSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
getDomain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
getDomainProfileSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
updateDomain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
updateDomainProfileSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
HotlineAPI operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
createUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
deleteUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
deleteAccount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
updateUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
getCoAMetrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
getDMMetrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
getCoADMMetrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
clearCoADMFailureMetrics . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
NetworkAPI operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
createDHCPServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
findDPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
createDPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
createIPAddressPool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
createNetwork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
deleteDHCPServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
deleteDPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
deleteIPAddressPool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
deleteNetwork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
getDHCPServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
getDPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
getIPAddressPool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
getNetwork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
updateDHCPServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
updateDPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
updateIPAddressPool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
updateNetwork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Page xii October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Contents

OrganizationAPI operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

createOrganization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
deleteOrganization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
createOrganizationProfileSet . . . . . . . . . . . . . . . . . . . . . . . . . . 147
getOrganization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
getOrganizationProfileSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
updateOrganization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
updateOrganizationProfileSet . . . . . . . . . . . . . . . . . . . . . . . . . 154
ProfileAPI operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
createProfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
deleteProfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
getProfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
updateProfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
findProfiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Proxy deployment APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
ProxyFilter APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Proxy Override Attribute Group API . . . . . . . . . . . . . . . . . . . . . 181
Proxy Required Attribute Group API . . . . . . . . . . . . . . . . . . . . 191
RADIUS Server (proxy target) API . . . . . . . . . . . . . . . . . . . . . . 195
RADIUS Server Group API . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
RADIUS proxy service API . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
ServiceAPI operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
getService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
createUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
deleteUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
updateUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
SessionAPI operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
getSessionStatusByLoginName . . . . . . . . . . . . . . . . . . . . . . . 217
getSessionStatusByIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
SystemAPI operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
applyChanges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
TrunkGroupAPI operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
createTrunkGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
deleteTrunkGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
getTrunkGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
updateTrunkGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
updateTrunkGroups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

Service Controller 9.6.1-AAA October 26, 2012 Page xiii

Contents Provisioning API Guide

UserAPI operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

createUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
createUserProfileSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
deleteUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
findUsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
getUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
getUserWithActiveServices . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
getUserProfileSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
updateUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
updateUserProfileSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
WiMAXAPI operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
createWiMAXDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
createWiMAXHAGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
createWiMAXNodeGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
deleteWiMAXDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
deleteWiMAXHAGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
deleteWiMAXNodeGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
getWiMAXDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
getWiMAXHAGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
getWiMAXNodeGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
updateWiMAXDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
updateWiMAXHAGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
updateWiMAXNodeGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

Chapter 5 WSDLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

WSDLs overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Obtaining WSDLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
To obtain a WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Sending SOAP requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
To send a SOAP request . . . . . . . . . . . . . . . . . . . . . . . . . 288
WSDL examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
DAEAPI WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
provisionComplete API and WSDL . . . . . . . . . . . . . . . . . . . . . 295
abortsession.wsdl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Page xiv October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Contents

Chapter 6 Command line utilities. . . . . . . . . . . . . . . . . . . . . . . . . . 305

About the utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Running the utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Determining CLU version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Determining usage information . . . . . . . . . . . . . . . . . . . . . . . . 308
Utility details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
changeprofile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
deluser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
insuser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
listuser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
moveuser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
reactivateuser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
readuser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
setpassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
suspenduser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
unsuspenduser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
updattribs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

Service Controller 9.6.1-AAA October 26, 2012 Page xv

Contents Provisioning API Guide

Page xvi October 26, 2012 Service Controller 9.6.1-AAA

 Provisioning API overview

1
Chapter 1
Chapter

The Provisioning API provides client applications with programming interfaces to

the Profile Database for authentication, authorization, and accounting services.
This chapter gives an overview of client application development requirements and
the available programming interfaces.
The topics are:
• Client application environment
• XML interface
• Command line utilities

Service Controller 9.6.1-AAA October 26, 2012 Page 1

Chapter 1 Provisioning API overview Provisioning API Guide

Client application environment

Integration of services into existing networks requires communication between the
Profile Database and the existing service database.
To provide services, information in the existing service database must be migrated
into the Profile Database dynamically. Every change in data – for example, if a
subscriber cancels a service – must be reflected in the Profile Database.
The Provisioning Server is the access point for communicating with the Profile
Database. There are two mechanisms for interfacing with the Provisioning Server:
• the Service Manager GUI
• the Provisioning API
The Service Manager allows experienced users to perform manual provisioning of
the Profile Database. For more information about Service Manager operation, see
the Service Manager: Getting Started Guide for AAA, Service Manager: Network
Access Guide for AAA, Service Manager: Subscriber Provisioning Guide for AAA,
and Service Manager Online Help.
The Provisioning API is used to automate provisioning operations, and provides the
flexibility for application developers to design applications that interface directly with
the Profile Database.
Typical client applications include:
• bulk loading of data
• data synchronization between the Profile Database and the service database
• custom interfaces for specialized users – for example, call center
representatives
Several entity models are used to interact with the Profile Database through the
Provisioning Server. An important aspect of provisioning is determining which entity
models are required to map the existing service data environment to the Profile
Database.

XML interface
The XML interface to the Provisioning Server is the main interface for provisioning
the Profile Database. Client applications can be written in any language that can
support XML data exchange over HTTP using TCP/IP.
For information about using the XML interface, see Chapter 3, "Using the XML
interface".
The XML interface operations are documented in Chapter 4, "Provisioning APIs".

Page 2 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 1 Provisioning API overview

Using the Service Manager to configure elements

Some system/network elements are easier to configure using the Service Manager.
See the Service Manager: Network Access Guide for AAA for details about using
the GUI interface to configure RADIUS clients, NAS groups, DHCP servers, IP
address pools, networks and subnets, system elements (such as NASs, PDSNs,
and GGSNs), and WiMAX elements.

Programming environments
There are three requirements for using the Provisioning API XML interface:
• transport layer communication must use TCP/IP socket connections
• application layer communication must use HTTP byte-oriented messaging
protocol
• the data exchange format within the message must be XML
Suitable programming languages for application development include:
• compiled languages : Java, C++, and C
• interpreted languages : Perl, Tcl, Python, Php, Ruby, and Ajax

Development tools
This section provides information about development tools.

HTTP support An HTTP support package can be used to simplify and automate the generation of
package HTTP POST messages for API operation requests.

XML support package An XML support package can be used to simplify and manage the building and
parsing of XML data within API operation requests and responses.

Internet browser An Internet browser can be used to examine and validate the XML request and
response for an API call. Connect to the Provisioning Server by typing in the same
URL that would be used by the client application (for example, http://
localhost:32000/api/).

Command line utilities

Multiple command line utilities can be used to view or change Profile Database
records.
Run these utilities manually at the console, or call them through scripts on any host
machine that can connect to the Service Controller.
For detailed information about using the command line utilities, see Chapter 6,
"Command line utilities".

Service Controller 9.6.1-AAA October 26, 2012 Page 3

Chapter 1 Provisioning API overview Provisioning API Guide

Page 4 October 26, 2012 Service Controller 9.6.1-AAA

 Data model

2
Chapter 2
Chapter

This chapter describes the data model for entities that may be provisioned by the
Provisioning API operations.
The topics are:
• Service contexts
• Service entity modelling
• Subscriber entity modelling
• Network entity modelling
• WiMAX entity modelling

Service Controller 9.6.1-AAA October 26, 2012 Page 5

Chapter 2 Data model Provisioning API Guide

Service contexts
The service and subscriber entities form a hierarchy of service context levels, as
described in Table 1. Entries in the table are listed in order of value inheritance,
from the service class (SC) context level down to the user (U) context level. Service
attributes defined at a higher context level are inherited from the top level
downwards, until overridden.
For example, a service attribute defined at the organization group (OG) level is
inherited by all organizations, account groups, accounts, user groups, and users.
An attribute defined at the user (U) level will apply only to that specific user.

Table 1: Hierarchy of service contexts

Associated entity in
Context name Description
data model

Service class SC Service Default attribute value defined within

the service class and reserved for
global behavior.

Default DEF Profile Explicitly defined root attribute value.

Domain Group DG DomainProfileSet Attribute value defined at the domain

group level.

Domain D Domain Attribute value defined at the domain

level.

Organization OG OrganizationProfileSet Attribute value defined at the

group organization group level.

Organization O Organization Attribute value defined at the

organization level.

Account Group AG AccountProfileSet Attribute value defined at the account

group level.

Account A Account Attribute value defined at the account

level.

User Group UG UserProfileSet Attribute value defined at the user

group level.

User U User Attribute value defined at the user

level.

Page 6 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 2 Data model

Service entity modelling

The service entities are:
• Service
• Service attribute
• Attribute descriptor
• Profile
Figure 1 shows the service entity model and the relationships between service
entities.
Figure 1: Service entity model

RZQLQJ2UJDQL]DWLRQ
2UJDQL]DWLRQ

RZQLQJ2UJDQL]DWLRQ

 

3URILOH6HW
   
$FFRXQW3URILOH6HW
3URILOH 6HUYLFH$WWULEXWH
'RPDLQ3URILOH6HW
2UJDQL]DWLRQ3URILOH6HW SURILOHV DWWULEXWHV
8VHU3URILOH6HW

VHUYLFH

 
6HUYLFH 6HUYLFH$WWULEXWH
DWWULEXWHV


$WWULEXWH
'HVFULSWRU
DWWULEXWH'HVFULSWRUV

Service
The service entity models the data that describes a class of service offering to a
subscriber. A service class will contain a defined set of service attributes and may
also contain associated attribute descriptors. The ServiceAPI library provides
operations that function on the service entity.

Service Controller 9.6.1-AAA October 26, 2012 Page 7

Chapter 2 Data model Provisioning API Guide

Service attribute
The service attribute entity models the basic unit of service provisioning.
Service data is stored as named attribute/value pairs (AVPs). Service attributes are
defined at a specified context level, as described in Table 1 on page 6. The service
class (SC) context is the highest context level, and attributes defined at this level
are inherited by all other contexts unless overridden at a lower level.
There are three types of service attribute:
• Singleton attributes
A singleton attribute has a single value instance. For example, a user name
string.
• Vector attributes
A vector attribute has multiple value instances, identified by subscripts. Each
value instance can be accessed separately. For example, a list of telephone
numbers.
• Segmented vector attributes
Segmented vector attributes are used for RADIUS connection services and are
associated with a specific vendor dictionary.
A segmented vector attribute can contain either a singleton or vector attribute.
Each segment is a storage area defined by the (segmentStart  segmentSize)
value defined in the vendor dictionary. All segmented attribute values are
identified by subscripts. For a singleton attribute, this is the segment address.
For a vector attribute, this is the segment address plus the vector subscript.
For information about provisioning rules for attributes, see "XML provisioning
details" on page 29.
The ProfileAPI, UserApi, AccountAPI, DomainAPI, and OrganizationAPI libraries
provide operations that function on the service attribute entity.

Attribute descriptor
An attribute descriptor is a file of metadata describing a specified service attribute
and any constraints that apply to it. The attribute metadata is used for validation of
attribute specifications in API operation calls.

Profile
The service profile entity models a specific instance of a configured service, and
represents the default (DEF) context for that service instance. Attributes defined in
the service profile override or supplement those defined for the service class.
The ProfileAPI library provides operations that function on the service profile entity.

Page 8 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 2 Data model

Subscriber entity modelling

A subscriber is an end customer who receives provisioned services. There are four
subscriber-related entity types, and four associated profile set entity types:
• Domain
• Organization
• Account
• User
• Profile sets
Figure 2 shows the subscriber entity model and relationships between the
subscriber entities and associated profile sets.
Figure 2: Subscriber entity model

SDUHQW

 

RZQLQJ2UJDQL]DWLRQ 
 2UJDQL]DWLRQ 'RPDLQ
 

RUJDQL]DWLRQERXQG GRPDLQ

SURILOH6HW SURILOH6HW
RUJDQL]DWLRQ SDUHQW GRPDLQ

2UJDQL]DWLRQ 'RPDLQ

3URILOH6HW   3URILOH6HW

 
 $FFRXQW 8VHU 
DFFRXQW XVHUV

SURILOH6HW SURILOH6HW

$FFRXQW 8VHU
3URILOH6HW 3URILOH6HW

Domain
The domain entity models an internet domain, and is used for authentication. Each
domain is owned by a single organization; however, multiple organizations or
sub-organizations may be associated with a particular domain.
The DomainAPI library provides operations that function on the domain entity.

Service Controller 9.6.1-AAA October 26, 2012 Page 9

Chapter 2 Data model Provisioning API Guide

Organization
The organization entity models a conventional organization tree structure (for
example, a company with departments). This entity is used to associate configured
services with an organization or part of an organization.
Multiple organization entity instances may be linked into a hierarchical organization
tree structure. The organization is the only entity type that allows the linking of other
entities into a tree structure. The fully qualified name for any subscriber entity
includes the path information to that entity within the organization tree structure.
Each organization is associated with (bound to) a single domain. Sub organizations
and other entities within an organization hierarchy do not need to be associated
with the same domain as the parent organization.
The OrganizationAPI library provides operations that function on the organization
entity.

Account
The account entity models a billable unit. It aggregates user entities for billing
purposes.
The AccountAPI library provides operations that function on the account entity.

User
The user entity models the point of service delivery. This entity associates service
configurations with a subscriber. The user is not necessarily a person, but is a
delivery point that requires authentication before system access is permitted. The
user is the only entity type that requires authentication.
The UserAPI library provides operations that function on the user entity.

Profile sets
Each of the four subscriber entity types has an associated profile set that bundles
together service profiles to define the service capabilities available to a subscriber.
Each of these profile sets can be associated with multiple subscriber entities of the
appropriate type. Each profile set represents the group context for that subscriber
entity type. Attributes defined for a profile set apply to all profiles of that type, unless
overridden by a specific profile.
The UserAPI, AccountAPI, OrganizationAPI, and DomainAPI libraries provide
operations that function on the associated profile set.

Page 10 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 2 Data model

Network entity modelling

There are six network entity types:
• Network
• Subnet
• IP address pool
• RMS cluster ID
• Access node
• Access node group
Users and devices are identified by IP addresses. Both IPv4 and IPv6 address
formats are supported.
IP addresses can be allocated in one of two ways:
• Static allocation : an address that has been dedicated to a particular device for
an indefinite period of time.
• Dynamic allocation : an address that is issued to a device on demand for some
temporary period, for example, a temporary network access session.
A device requesting a dynamic IP address can, and probably will, receive a different
address each time it makes a request. Dynamic IP addresses are recovered for
reuse when the device disconnects from the network.
Figure 3 shows the network addressing model and the relationships between the
network entities.
Figure 3: Network addressing model

506&OXVWHU  Q  Q
1RGH*URXS $FFHVV1RGH
,'


Q
1HWZRUN Q 

,3$GGUHVV 7KH506&OXVWHU,'LVDQ06(
3RRO $WWURI,3$GGUHVV3RRODQG
1RGH*URXS
6XEQHW Q 

([FOXGHG,3
5DQJHV

Service Controller 9.6.1-AAA October 26, 2012 Page 11

Chapter 2 Data model Provisioning API Guide

Network
The network entity models a conventional IP network, made up of subnets. The
network is a parent entity, with multiple child subnets.
The NetworkAPI library provides operations that function on the network entity.

Subnet
The subnet entity models a set of contiguous IP addresses, comprising part of a
parent network.
The NetworkAPI library provides operations that function on the subnet entity.

IP address pool
The IP address pool entity models the IP addressing mechanism and provides a
single access point for IP address allocation.
The NetworkAPI library provides operations that function on the IP address pool
entity.

RMS cluster ID
The RMS cluster ID entity models the operations of the Resource Management
Server. It handles the translation mechanism between IP addresses and associated
user sessions.

Access node
Configure the following access node roles:
• GGSN
• GSM node
• Hotlining Application
• NAS
• PDSN
• WiMAX HA
• WiMAX ASN Gateway

Access node group

Configure the following access node groups:
• GGSN group
• GSM node group
• HA group
• NAS group
• PDSN group

Page 12 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 2 Data model

• WiMAX Home Agent group

• WiMAX node group
• Trunk group

WiMAX entity modelling

There are four WiMAX entity types:
• Access node
• WiMAX device
• WiMAX node group
• WiMAX HA group
Figure 4 shows the WiMAX entity model.
Figure 4: WiMAX entity model

:L0$;1RGH
*URXS


:L0$;'HYLFH $FFHVV1RGH

 :L0$;+RPH
$JHQW*URXS

5ROH

:L0$;+$ :L0$;$61
5ROH *DWHZD\5ROH

Access node
The access node entity models the main access point to a WiMAX-accessible
network. The access node is associated with a role which can either be a WiMAX
Home Agent (WiMAX HA) or a WiMAX Access Service Network Gateway (WiMAX
ASN Gateway). A WiMAX ASN Gateway provides network access to WiMAX
subscribers.
An access node with one or both of these roles may belong to one WiMAX Node
group and any number of WiMAX Home Agent groups.
The AccessNodeAPI library provides operations that function on the access node
entity.

Service Controller 9.6.1-AAA October 26, 2012 Page 13

Chapter 2 Data model Provisioning API Guide

WiMAX device
The WiMAX device entity models a wired or wireless device connecting to the
WiMAX network.
The WiMAXAPI library provides operations that function on the WiMAX device
entity.

WiMAX node group

The WiMAX node group entity models a set of WiMAX nodes. A WiMAX node may
not belong to more than one WiMAX node group.
The WiMAXAPI library provides operations that function on the WiMAX node group
entity.

WiMAX HA group
The WiMAX HA group entity models a set of WiMAX nodes. Only WiMAX nodes
with the home agent role may be assigned to a WiMAX HA group. A WiMAX node
may belong to more than one WiMAX HA group.
The WiMAXAPI library provides operations that function on the WiMAX HA group
entity.

Page 14 October 26, 2012 Service Controller 9.6.1-AAA

 Using the XML interface

3
Chapter 3
Chapter

This chapter describes the Provisioning Server XML interface between user
applications and the Profile Database.
The topics are:
• Interface access
• Communication mechanism
• Sample PERL application
• Creating a custom application
• Application design considerations
• XML provisioning details
• Example error messages
• Application Authorization Server specific example
• Provisioning Server logs

Service Controller 9.6.1-AAA October 26, 2012 Page 15

Chapter 3 Using the XML interface Provisioning API Guide

Interface access
The Provisioning Server provides client applications with API access to the Profile
Database using a standard client/server communications model. Client applications
written in any suitable language send requests to the Provisioning Server through
XML messages sent over HTTP or HTTPS. The Provisioning Server performs the
required actions specified in the XML request, and sends a response back to the
client application.
Figure 5 illustrates sending a properly formatted XML message over HTTP to the
Provisioning Server.
For secure communication you can:
• use SSL or ARC4 encryption
• configure the Provisioning Server to allow only specified hosts to send XML
messages to the XML interface
Figure 5: Provisioning Server XML interface

$SSOLFDWLRQV

;0/

;0/RYHU+7736

;0/LQWHUIDFH

3URYLVLRQLQJ6HUYHU

3URILOH
'DWDEDVH

Page 16 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 3 Using the XML interface

Communication mechanism
The message protocol used to access the API over the network is HTTP, or HTTPS
for secure communication.
Communication using HTTP involves pairs of messages – a request message from
the client to the server followed by a response message from the server to the
client.
API request and response messages always use the HTTP POST mechanism.

Message structure
A properly formatted HTTP POST message includes these components:
• header portion: identifies a network destination and controls protocol-related
aspects of the communication
• empty line
• data portion: exchange of API-related information
There are a variety of support packages available to handle the details of HTTP
message construction and message passing. Application developers need only
deal with the data portion of the message and use a support package to handle
sending and receiving messages.

Header portion The message header conforms to standard HTTP protocol requirements.
An example of a valid HTTP POST message header is:
POST 192.168.157.50:32000/api/ HTTP1.1
Host: 192.168.157.50
Content-Length: 2373
Content-type: text/xml
Connection: Close

Service Controller 9.6.1-AAA October 26, 2012 Page 17

Chapter 3 Using the XML interface Provisioning API Guide

Table 2 describes the header fields.

Table 2: Message header fields

Field Value Description

POST URL HTTP1.1 Specifies the location of the interface on the

Provisioning Server. It identifies the message as an
API request.
In a manually-generated HTTP header, URL is /api/.
If using a third-party HTTP support package, a
fully-formed URL may be used, including the host
name or IP address of the server, the port number,
and the location on the server. For example:
http://192.168.157.50:32000/api/
https://MyProvServer.MyCompany.com:32001/api/
The application can be configured for communication
over a secure port (default 320001) using an HTTPS
prefix, or a non-secure port (default 32000) using an
HTTP prefix.
HTTP1.1 is the HTTP version number. The
Provisioning Server requires HTTP version 1.1.

Host IP address The IP address of the Provisioning Server

Content-Length Integer The number of bytes in the data portion of the request

Content-type text/xml Specifies that the data portion is in plain text, in XML
format. (Mime type)

Connection Close Specifies that the connection can be closed when the
request has been completed (a response has been
received). The default connection type is persistent; if
this header is omitted, a persistent connection is
established.

The message header is followed by an empty line, and the data portion of the
request.
After the server processes a provisioning request, a response message is returned
to the client. A response message is preceded by an HTTP status code, and
contains a result or an error.

Data portion The Provisioning Server provides access to several API libraries. Each library
includes a set of related operations. For details of library operations, see "API
libraries" on page 42.
A complete API call consists of a request message from the client application to the
Provisioning Server and a response message from the Provisioning Server to the
client application.
The data portion of an API request message contains:

Page 18 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 3 Using the XML interface

• the API library name

• the name of the operation being invoked
• required input data
Note If the data portion of the request message begins with an XML declaration,
such as <?xml version=”2.0”?>, make sure there are no spaces, returns, or
other non-text characters before the declaration. Non-text characters
preceding the XML declaration result in a COM-00005 communication
exception error, such as: "request failed: XML-00001 processing instruction
cannot have PITarget with reserved xml name".
Note XML comments using the “<!--... -->” syntax are not allowed in the data or
header portion of the XML message. The request will fail.
The data portion of an API response message contains the result being returned,
which may include information retrieved from the Profile Database.

Message data example

An example of the data portion of a pair of request and response messages is:
<request version=”2.0” principal=”userName” credentials=”password”>
<target name=”UserAPI” operation=”getUser”>
<parameter>
...
</parameter>
</request>

<response version=”2.0”>
<target name=”UserAPI” operation=”getUser”>
<result>
...
</result>
</target>
</response>

Message data format

Both messages consist of a series of three nested XML elements wrapping the
encapsulated information.
A <request> tag encloses the data portion of a request message.
A <response> tag encloses the data portion of a response message.

Service Controller 9.6.1-AAA October 26, 2012 Page 19

Chapter 3 Using the XML interface Provisioning API Guide

Table 3 describes the attributes of the <request> and <response> tags.

Table 3: <request> and <response> attributes

Attribute Applies to tag Description

version <request> The Bridgewater XML API version number. For

<response> more information, see "XML API version" on page
21.

principal <request> The username configured in the server.xml file to

allow access to the Provisioning Server.

credentials <request> The password configured in the server.xml file to

allow access to the Provisioning Server.

Note The XML <request> wrapper is not required when using the vip.pl PERL
script described in "Sample PERL application" on page 21.
The <request> and <response> tags enclose a <target> tag. The attributes of the
<target> tag are given in Table 4.

Table 4: <target> attributes

Attribute Description

name The target API library, for example, UserAPI.

operation The target operation to be invoked, for example, getUser.

The <target> tag for a request message encloses a <parameter> tag.

The <target> tag for a response message encloses a <result> tag or an <error> tag.
The XML content within each of these elements is specific to the particular API
operation that was invoked. For XML details of specific API operations, see "API
libraries" on page 42.
Error handling (including IO related errors), client-side timeouts, and failover are the
responsibility of the client application software. For more information, see "Error
categories" on page 28.

Page 20 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 3 Using the XML interface

XML API version

The XML API version level determines the compatibility of API operations.
All API operations within a client application must use the same API version. This
will ensure consistent behavior between operations.
Bridgewater Systems supports a given XML API version level for at least two major
releases: Release 9.6.1-AAA supports XML API versions 1.0, 1.2, 1.3, and 2.0.
For a Policy Controller Provisioning Service (BWSnpcs) installation, the
Provisioning Client request version must support at least version 2.0.
If static IP address pool support is enabled, XML API version 1.2 or higher must be
used.
Within a given XML API version level, Bridgewater Systems:
• maintains the syntax and functionality of all API operations, elements, and
attributes in request and response messages
• maintains the error code values and functionality of all errors that may be
generated by the XML API
New operations, elements, or attributes may be added to the XML request or
response for any API operation, and new error messages or error message text
may be added. These changes are considered compatible within an XML API
version level, and does not affect client application functioning if ignored.
Well-designed applications of a given XML API version level continue to function in
any future release that supports that XML version. For information about designing
applications for forward compatibility, see "Forward compatibility" on page 28.

Sample PERL application

Create a custom application to send XML requests over HTTP or HTTPS to the
XML interface on the Provisioning Server, as shown in Figure 5 on page 16. The
Provisioning Server provides a sample PERL application to show how an
application is constructed. The sample application is installed with the BWSaaaco
package and the PERL script, vip.pl, sends an XML message to the Provisioning
Server.
Note The XML <request> wrapper described in "Message data format" on page
19 and used throughout the API libraries is not required when using the
vip.pl PERL script.

Sample application input files

The sample application requires the following two input files:
• vipclient.conf, a configuration file which defines the connection details for
communicating with the Provisioning Server
• input.xml, a file which includes the XML input required by the Provisioning
Server

Service Controller 9.6.1-AAA October 26, 2012 Page 21

Chapter 3 Using the XML interface Provisioning API Guide

A preconfigured sample of each file is installed in the /WideSpan/utilities/bpapi/

examples/ directory.

Sample vipclient.conf The sample configuration file, vipclient.conf, contains:

file # Valid values for encryption method are: TEXT, ARC4, SSL3
CMETHOD=ARC4
#
# Shared secret required to encrypt ARC4 requests sent via
HTTP and decrypt responses.
# For ARC4 over HTTP, the server MUST be configured with the
same shared secret in the server.xml file
SECRET=rds32k2894l1k
#
# Timeout is a numeric value in seconds
TIMEOUT=30
#
# Port number must match one of the ports specified in
server.xml
# If using SSL3, this value must match with the secure port.
PORT=32000
#
# Servers is a comma delimited list of hostnames or IPv4
addresses
SERVERS=localhost
This vipclient.conf file uses ARC4 encryption with the specified secret to make sure
secure communication. The secret must match the secret defined in the
/WideSpan/config/provserver/server.xml file on the Provisioning Server.
The timeout value specifies the amount of time to wait for a response from the
defined server (localhost). To add failover to this example, define an additional host
in the SERVERS section. When the timeout value expires for the first host, the
application attempts to reach the second host. If the host is unreachable, failover
occurs immediately.
The example vipclient.conf file is installed with the BWSwsco package and enables
clients to communicate with the Provisioning Server.

Sample input.xml file The sample input file, user.xml, contains the following code:
<target name="UserAPI" operation="getUser">
<parameter>
<user>
<id>1</id>
</user>
</parameter>
</target>
This example retrieves user information for a user with the ID of 1.

Page 22 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 3 Using the XML interface

Running the sample application

The sample application, vip.pl, is a PERL script run from the command line. The
vip.pl script is available from the /WideSpan/utilities/bpapi directory.
Before running the sample application, the following two conditions must be met on
the host server:
• the BWSperl package must be installed
• the BWSaaapr package must be installed: the default configuration specifies
the server as localhost
As the aaasc user, type:
./vip.pl -c examples/vipclient.conf -i examples/user.xml
where:
examples/vipclients.conf is the sample vipclient.conf file
examples/user.xml is the sample user.xml file
Use the -x option with the vip.pl script to send the script output to a specified file.
As specified in the user.xml file, the sample application returns all the user
information for the user with an ID of 1.

Example <response version="2.0">

<target name="UserAPI" operation="getUser">
<result>
<user>
<id>1</id>
<name>root</name>
<login-name>root</login-name>
<organization>
<id>1</id>
<name>Root Organization</name>
<status><value>active</value></status>
<implicit-status><value>active</value>
</implicit-status>
</organization>
<domain>
<id>1</id>
<name>null</name>
<status><value>active</value></status>
</domain>
<password>
<type>cleartext</type>
<value>xyz123</value>
<learn-password>false</learn-password>
</password>

Service Controller 9.6.1-AAA October 26, 2012 Page 23

Chapter 3 Using the XML interface Provisioning API Guide

<status><value>active</value></status>
<creation-date>2003-11-25 23:33:42
</creation-date>
<last-modified>2003-11-25 23:33:42
</last-modified>
<modified-by>creroot.sql</modified-by>
<billing>
<id>3</id>
<senior-billing-id>3</senior-billing-id>
</billing>
<profile-set>
<id>3</id>
<name>Root User Profile Set</name>
<type>user</type>
</profile-set>
</user>
</result>
</target>
</response>

Creating a custom application

Custom applications are built around well-formed API operation calls.
Invoking an API call is a two-step process:
1 Build and send a request message to the Provisioning Server:
– Build the data portion of the request message in XML format.
– Assemble the HTTP request message.
– Connect to the server and send the request message.
2 Receive and parse the response message from the Provisioning Server:
– Receive the response message from the server
– Extract the data portion out of the response message
– Parse the information in the XML-formatted data portion
There are many ways to implement this process. Many third-party support
packages are available to simplify development and reduce maintenance effort.

Page 24 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 3 Using the XML interface

Building and sending a request message

The request message consists of these components:
• header portion: this includes the length of the data portion, and cannot be build
until the data portion is complete
• empty line
• data portion: this includes the following nested components:
– <request> element
– <target> element
– <parameter> element
– XML data structure containing the argument list
To build a request message:
1 Build the data portion of the message. This is an XML-oriented process, and
would benefit from the use of a third-party XML support package.
For information about the <request> and <target> attributes, see "Data portion"
on page 18.
The XML data structure is specific to the API operation used. For information
about specific API operations, see "API libraries" on page 42.
2 Build the header portion of the message, either manually or with a third-party
HTTP support package.
For information about the structure of the header portion, see "Header portion"
on page 17.
3 Open a connection to the Provisioning Server and send the request message.
If doing this manually, use an Internet browser to navigate to the URL specified
in the request header (for example http://192.168.157.50:32000/api/). The
browser will present a text entry area that accepts the request XML, and a
button to submit the request to the Provisioning Server. When the request has
been submitted, another browser window opens to show the response XML
from the Provisioning Server. Remember to send an empty line between the
header and data portions of the message.

Receiving and parsing the response message

The response message consists of these components:
• header portion
• empty line
• data portion. which includes these nested components:
– <response> element
– <target> element
– <result> element
– XML data structure containing the return data

Service Controller 9.6.1-AAA October 26, 2012 Page 25

Chapter 3 Using the XML interface Provisioning API Guide

Regardless of whether or not the HTTP connection was specified to be persistent,

the connection remains open at least until the response message (or an error
message) is sent to the client application.
Receiving and extracting the data portion of an XML response message is an
HTTP-oriented process, and would benefit from the use of a third-party HTTP
support package.
Parsing the data portion of the message is an XML-oriented process, and would
benefit from the use of a third-party XML support package.
For information about the structure of the XML data portion of the message,
including the <response> and <target> attributes, see "Data portion" on page 18.
The XML data structure is specific to the API operation used. For information about
specific API operations, see "API libraries" on page 42.

Error responses
The following types of errors may occur:
• Non-compliant HTTP. This type of error is indicated by the HTTP status code
returned before the HTTP header of the response message. Any HTTP status
code other than 200 OK indicates a malformed HTTP request message. The
response message does not contain a data portion. Look for programming
errors within the client application.
• API call failure. The HTTP status code returned is 200 OK, but the response
message data portion contains an <error> element instead of a <result>
element.
The XML structure within the <error> element contains a Bridgewater Systems
error code and a user-readable error message.
For more information, see "Error categories" on page 28.

Error response <response version=”2.0”>

message example <target name=”UserAPI” operation=”getUser”>
<error>
<code>USR-00001</code>
<message>User ‘Mr T’ not found</message>
</error>
</target>
</response>

Error message The error code consists of:

format • a mnemonic prefix, identifying an error code family
• an error number, identifying the specific error within that error family group
The error message is a text string providing additional information.
For detailed descriptions of all error messages, see "Provisioning Server logs" on
page 40.

Page 26 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 3 Using the XML interface

Application design considerations

This section discusses important considerations when designing client applications
that use the Provisioning API.
The topics are:
• Resource management
• Efficiency
• Forward compatibility
• Error categories

Resource management
HTTP connections are used by the XML interface for sending Provisioning API
operation calls to the Provisioning Server. For information about how HTTP
connections are specified in an HTTP request message, see "Header portion" on
page 17.
HTTP connections are a limited system resource. If the HTTP header does not
specify a value of ‘Close’ for the connection, then the HTTP connection is
persistent.
If the HTTP message object is reused for subsequent API calls, this may decrease
object initialization time, and could improve performance.
If the HTTP message object is discarded after the operation, the resource is
orphaned until such time as it can be recovered by the system. This can cause
resource contention for subsequent requests or other processes, and can decrease
performance.
A ‘Close’ connection header value should always be specified if the connection is
not required for a subsequent API call.

Efficiency
There are two ways of uniquely identifying Profile Database objects in most XML
requests:
• ID number: for example, <id>6413</id>
• name, in the qualified name format that includes organizational hierarchy
information: for example, <qualified-name>/BWS/test/user43</qualified-name>
Using an ID number is more efficient than using a qualified name, as it avoids a
lookup operation for every access.
State-full applications that cache object ID information can achieve higher
performance, particularly in large Profile Databases, by using ID values instead of
qualified name values.

Service Controller 9.6.1-AAA October 26, 2012 Page 27

Chapter 3 Using the XML interface Provisioning API Guide

Forward compatibility
Defect fixes or feature changes in future Service Controller releases may require
changes to API operations. The XML API version level determines the compatibility
of API operations. Well-designed applications of a given XML version level will
continue to function in any future release that supports that XML version.
The following API changes are considered compatible, and may be introduced
without a change in XML version number.

Requests • new API operations

• new XML elements or attributes that are optional (a default is not required)
• new XML elements or attributes, where an applicable default value is provided
automatically for backwards compatibility

Responses • new XML elements or attributes

Errors • changes to the text string of an error message (the error code and error
function are not be changed)
• new error codes (which may appear at any point in the request processing
order)

Designing for To ensure that an application will continue to work as intended with future Service
forward Controller releases, follow these design rules:
compatibility • applications must ignore unrecognized elements or attributes in XML
responses
• applications must identify errors by the error code, and not the content of the
message text string
• applications must include a default trap condition for unrecognized errors

Error categories
There are two kinds of errors to consider in a client application:
• run-time errors
• API errors

Run-time errors Run-time errors are caused by programming errors, or unanticipated data errors. In
either case, run-time errors must be trapped and handled gracefully. Although the
operation that encounters a run-time error cannot be completed, proper error
handling keeps the application running so that subsequent operations may be
attempted.
Diagnostic logs should be maintained as part of the error-handling routine to identify
and characterize the failure situation for development team analysis and
debugging.

Page 28 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 3 Using the XML interface

API errors API errors occur when the Provisioning Server cannot complete the requested
operation. For information about the format of error return messages, see "Example
error messages" on page 34.
The Provisioning Server stops processing and returns an error at the first error
condition found.
A client application should use error responses to determine an appropriate error
recovery path. This normally includes a notification to the user and, depending on
the client application logging strategy, an error message may also be logged.
For detailed descriptions of all error messages, see "Provisioning Server logs" on
page 40.

XML provisioning details

This section describes the rules that apply to XML provisioning. The topics are:
• Identifying provisionable entities
• Attribute types
• Attribute properties
• Processing attribute operations
• Adding an attribute
• Adding or updating an attribute value
• Deleting an attribute
• Deleting values
Note To minimize the risk of running out of resources when retrieving large
datasets, limit the number of results returned from API request for service
objects. Set the <max-results> and <max-allowed-results> parameters in /
WideSpan/config/provserver/subscriber-service.xml.

Identifying provisionable entities

All “get”, “update”, and “delete” operations can identify the target object using either
of the following fields:
• id: the unique identifier assigned to the entity by the system
• qualified-name: a non-persistent value that uniquely identifies an object
Typically, qualified-name is set to the “name” of the object that is to be retrieved,
updated, or deleted.
Using the qualified-name instead of the name field provides a way of updating the
name value of an object even if the id value is not known.
Either the id or the qualified-name value must be provided when doing a get,
update, or delete operation. If both are provided, only the id value is used to identify
the object.

Service Controller 9.6.1-AAA October 26, 2012 Page 29

Chapter 3 Using the XML interface Provisioning API Guide

Attribute types
There are three types of attributes:
• Singleton attributes
• Vector attributes
• Segmented vector attributes

Singleton attributes A singleton attribute has a single value instance. For example, a user name string:
<attribute name=”UserNameAttr”>
<value>”Bob Smith”</value>
</attribute>

Vector attributes A vector attribute has multiple value instances, identified by subscripts. Each value
instance can be accessed separately. For example, an attribute “IDNumberAttr” can
contain a list of identification numbers. Each value (identification number) has a
unique subscript. For example:
<attribute name=”IDNumberAttr”>
<value subscript=”0”>5555551212</value>
<value subscript=”1”>5555553434</value>
<value subscript=”2”>5555555656</value>
</attribute>
Subscripts are always in continuous sequence. Values are resequenced if deletions
or additions leave gaps in the sequence. Retrieve attribute information to check
subscript identifiers before modifying specific values by subscript number.
Some entities do not support vector attributes. For example, DPIs only support
singleton attributes.

Segmented vector Segmented vector attributes are only used for RADIUS connection services and are
attributes associated with a specific vendor dictionary.
A segmented vector attribute can contain either a singleton or vector attribute. Each
segment is a storage area defined by the (segmentStart  segmentSize) value
defined in the vendor dictionary. All segmented attribute values are identified by
subscripts. For a singleton attribute, this is the segment address. For a vector
attribute, this is the segment address plus the vector subscript.
For example:
<attribute name=”NAS-IP-Address>
<value segment=”NORTEL”>192.1.2.3</value>
<value segment=”CISCO”>192.4.5.6</value>
</attribute>

Page 30 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 3 Using the XML interface

Attribute properties
Attributes can be added or deleted. The properties of an attribute element are:
• name: required
• delete: a flag that indicates whether or not the attribute and all of its values are
to be deleted
Attribute values can be added, updated, or deleted. The properties of an attribute
value are:
• subscript: null for a singleton attribute value; integer for a vector attribute value
• segment: identifier for the segment subscript in a segment attribute
• delete: a flag that indicates whether or not the value is to be deleted
Note A null and an empty string subscript are different. The null subscript
indicates a singleton. An empty string indicates a vector attribute that
has not yet been assigned a subscript.

Processing attribute operations

The order of processing for attribute operations is:
1 Attribute deletions are processed in the order they are submitted.
2 Other attribute operations are processed in the order they are submitted.
The order of processing for values in a vector attributes is:
1 Value deletions are processed in the order they were submitted.
2 Other value operations are processed in the order they were submitted.
For example, the following update request operates on four different attributes:
<attribute name=”attr1” delete=”false”>
<attribute name=”attr2” delete=”true”>
<attribute name=”attr3” delete=”false”>
<attribute name=”attr4” delete=”true”>
The attribute operations are processed in this order:
• attr2 (deleted)
• attr4 (deleted)
• attr1 (added or updated)
• attr3 (added or updated)
The following request, where attr1 does not yet exist in the Profile Database, first
creates and then modifies attr1:
<attribute name=”attr1” delete=”false”>
<attribute name=”attr1” delete=”false”>
The following update request operates on four different value instances within a
vector attribute:

Service Controller 9.6.1-AAA October 26, 2012 Page 31

Chapter 3 Using the XML interface Provisioning API Guide

<attribute name=”attr1” delete=”false”>

<value delete=”false”>v1</value>
<value delete=”true”>v2</value>
<value delete=”false”>v3</value>
<value delete=”true”>v4</value>
</attribute>
The values are processed in this order:
• v2 (deleted)
• v4 (deleted)
• v1 (added or updated)
• v3 (added or updated)

Adding an attribute
To add an attribute, specify an attribute with the name field set to the new attribute
name, and the delete flag set to “false” (default). When provisioning one or more
values, the value delete flag must also be false, or not specified.
For example, to create a new vector attribute with two values provisioned:
<attribute name=”NewAttr”>
<value subscript=”0”>value1</value>
<value subscript=”1”>value2</value>
</attribute>
Do not specify a value with an empty string. An empty string causes the value to be
deleted. If the attribute containing the empty string (deleted) value is a singleton, or
if the value deletion results in an empty vector, the attribute is also be deleted.
To create a vector attribute, specify a value with a subscript. The subscript may be
an empty string for initial provisioning. If no subscript is specified, the attribute is
created as a singleton type attribute.
Note The system may assign a subscript a value that is different from the one
supplied if gaps in sequence are detected. Subscripts start at the lowest
non-empty subscript that is supplied and are incremented. Subscripts start
at 0 if all the provided subscripts are empty strings.
For example, this new attribute is a singleton, and cannot have additional values
provisioned in subsequent operations:
<attribute name=”NewAttr”>
<value>NewValue</value>
</attribute>
This new attribute is a vector, and can have further values added later:
<attribute name=”NewAttr”>
<value subscript=””>NewValue</value>
</attribute>

Page 32 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 3 Using the XML interface

Adding or updating an attribute value

To add or modify a value for an attribute, specify an attribute and value where:
• the attribute name matches an attribute already in the Profile Database
• both the attribute and value delete flags are false (or not specified)
• the value is not an empty string (an empty string causes the value to be
deleted)
If the attribute is a singleton, the current value is updated with the new value
supplied.
If the attribute is a vector, and no subscript has been provided, the new value is
added to the vector.
If the attribute is a vector and a subscript is provided, the value that corresponds to
that subscript is updated. If the subscript does not correspond to any existing value,
the new value is added to the vector at the next consecutive subscript.
For example, to update the value instance at subscript 3 of attr1:
<attribute name=”attr1”>
<value subscript=”3”>NewValue</value>
</attribute>
If there is no value instance at subscript 3, but attr1 contains value instances at
subscripts 0, 1, and 2, then NewValue is added at subscript 3. If there are value
instances only at subscripts 0 and 1, then NewValue is added at subscript 2.

Deleting an attribute
To delete an attribute and all of its values, specify the attribute by name with the
delete flag set to “true”.
For example, to delete the attribute attr1:
<attribute name=”attr1” delete=”true”>

Deleting values
To delete a value, specify:
• the attribute containing the value (attribute name)
• the value to be deleted (value instance or vector subscript)
• the value delete flag set to “true”, or an empty string value
For example, the vector attribute attr2 contains four value instances:
<attribute name=”attr2>
<value subscript=”0”>value1</value>
<value subscript=”1”>value2</value>
<value subscript=”2”>value3</value>
<value subscript=”3”>value4</value>
</attribute>

Service Controller 9.6.1-AAA October 26, 2012 Page 33

Chapter 3 Using the XML interface Provisioning API Guide

To delete value3, use any of these methods:

<attribute name=”attr2”>
<value delete=”true”>value3</value>
</attribute>

<attribute name=”attr2”>
<value subscript=”2” delete=”true/>
</attribute>

<attribute name=”attr2”>
<value subscript=”2”>””</value>
</attribute>
If both subscript and value are specified, subscript takes precedence and the value
is ignored.
When deleting the value for a singleton attribute, or deleting the only value instance
in a vector attribute, the attribute is also deleted.
When deleting by subscript, it is important to remember that values in a vector
attribute may not have the same subscript that they were assigned originally. To
verify subscript numbers, first retrieve current attribute information with the
appropriate get operation.
Delete attribute actions are processed before adds and updates. This enables
updates for entire vector attributes when subscripts are not known. Send a call that
includes both a delete of the attribute and an update of the same attribute name
with the list of new values the attribute needs to take. This first deletes the attribute,
then recreates it with the new values.

Example error messages

This examples illustrate how the Provisioning Server handles error conditions.

Example error condition #1

This example shows an error condition where an XML request is sent, but the
Provisioning Server is not running.

Request
In this request, the organization id is 1 (which is always the root organization), and
the profile set id is 3 (the root user profile set):
<user>
<name>user1083680097</name>
<login-name>login1083680097</login-name>
<password>
<value>pwd1083680097</value>

Page 34 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 3 Using the XML interface

</password>
<organization><id>1</id></organization>
<profile-set><id>3</id></profile-set>
</user>

Response
Since the Provisioning Server is not running, the following XML output is returned:
<response version=”2.0”>
<target name="UserAPI" operation="createUser">
<error>
<code>CLU-00005</code>
<message>No response from server</message>
</error>
</target>
</response>

Example error condition #2

This example shows an error condition where the XML input is trying to retrieve
user information for a user that does not exist.

Request
An XML request is sent to the Provisioning Server for a user that does not exist:
<user>
<id>1150000081</id>
</user>

Response
<response version="2.0">
<target name="UserAPI" operation="getUser">
<error>
<code>USR-00001</code>
<message>User `1150000081` not found</message>
</error>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 35

Chapter 3 Using the XML interface Provisioning API Guide

Example error condition #3

This example shows an error condition where the XML input is trying to retrieve
user information for an unknown organization.

Request
<user>
<name>user1084375763</name>
<login-name>login1084375763</login-name>
<password>
<value>pwd1084375763</value>
</password>
<organization>
<qualified-name>Route Organization</qualified-name>
</organization>
<profile-set>
<name>Root User Profile Set</name>
</profile-set>
</user>

Response
<response version="2.0">
<target name="UserAPI" operation="createUser">
<error>
<code>USR-00012</code>
<message>
User cannot be created in organization `Route
Organization`. Organization not found
</message>
</error>
</target>
</response>

Page 36 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 3 Using the XML interface

Application Authorization Server specific example

This section describes how to set attribute value pairs in an Application
Authorization service profile against a user.

Provision Application Authorization Server services

The following steps describe how to retrieve the Application Authorization Server
specific attributes from the Profile Database.
1 To retrieve the User Authorized Service Profile's DEF level attributes, send the
Provisioning Server the following request:
<request version="2.0" principal="admin" credentials="admin">
<target name="ProfileAPI" operation="getProfile">
<parameter>
<profile>
<qualified-name>
User Authorized Services
</qualified-name>
</profile>
</parameter>
</target>
</request>
2 If the input XML is successful, the Provisioning Server returns the following:
<response version="2.0">
<target name="ProfileAPI" operation="getProfile">
<result>
<user-authorized-profile>
<id>11</id>
<name>User Authorized Services</name>
<organization>
<id>1</id>
</organization>
<service>
<id>18</id>
<name>UserAuthorizedServices</name>
<status>
<value>active</value>
</status>
<version>2</version>
</service>
<inheritance>yes</inheritance>
<status>
<value>active</value>

Service Controller 9.6.1-AAA October 26, 2012 Page 37

Chapter 3 Using the XML interface Provisioning API Guide

</status>
<context-mask>
<user/>
<user-group/>
<default/>
</context-mask>
<application>
<name>PTT</name>
<authentication-required
is-inherited="false">
false
</authentication-required>
<subscribed is-inherited="false">
false
</subscribed>
</application>
<application>
<name>MMS</name>
<authentication-required
is-inherited="false">
false
</authentication-required>
<subscribed is-inherited="false">
false
</subscribed>
</application>
<available-content-categories/>
</user-authorized-profile>
</result>
</target>
</response>
3 Pull out all of the <Application> entities from the response:
<application>
<name>PTT</name>
<authentication-required is-inherited="false">
false
</authentication-required>
<subscribed is-inherited="false">
false
</subscribed>
</application>
<application>
<name>MMS</name>

Page 38 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 3 Using the XML interface

<authentication-required is-inherited="false">
false
</authentication-required>
<subscribed is-inherited="false">
false
</subscribed>
</application>
These are the "services".The <name> field identifies the service:
– MMS
– PTT
4 To subscribe a user to a particular service and provision generic attributes
against that service:
<request version="2.0" principal="admin" credentials="admin">
<target name="UserAPI" operation="updateUser">
<parameter>
<user>
<login-name>userauthuser</login-name>
<domain><name>null</name></domain>
<profile-set>
<user-authorized-profile>
<qualified-name>
User Authorized Services
</qualified-name>
<application>
<name>MMS</name>
<subscribed>true</subscribed>
<authentication-required>
true
</authentication-required>
<attribute name="Attribute1">
<value>arbitrary</value>
</attribute>
</application>
<application>
<name>PTT</name>
<subscribed>true</subscribed>
<authentication-required>
true
</authentication-required>
<attribute name="Attribute1">
<value>arbitrary</value>
</attribute>
</application>

Service Controller 9.6.1-AAA October 26, 2012 Page 39

Chapter 3 Using the XML interface Provisioning API Guide

</user-authorized-profile>
</profile-set>
</user>
</parameter>
</target>
</request>
This example provisions data for the MMS and PTT services. For each service,
<subscribed> and <authentication-required> are set to ‘true’. Each service also
has a generic attribute set to an arbitrary value.

Provisioning Server logs

The Provisioning Server generates syslog messages. By default these messages
are recorded in /var/adm/messages.
To display online help for an error code returned by Oracle, log in as the oracle user
and type:
oerr ora error_code
For details of Provisioning Server error logs, see the chapter “Provisioning Server
log messages” in the Service Controller: Log Messages Guide.
Performance information for Provisioning API request handling is reported as INFO
level log messages through the Logging Framework.

Page 40 October 26, 2012 Service Controller 9.6.1-AAA

 Provisioning APIs

4
Chapter 4
Chapter

This chapter describes the XML interface that the Provisioning Server provides
between user applications and the Profile Database.
The topics are:
• API libraries
• XML provisioning examples
• AccessNodeAPI operations
• AccountAPI operations
• DAEAPI operations
• Send a CDMA-based DM
• HotlineAPI operations
• NetworkAPI operations
• OrganizationAPI operations
• ProfileAPI operations
• Proxy deployment APIs
• ServiceAPI operations
• SessionAPI operations
• SystemAPI operations
• TrunkGroupAPI operations
• UserAPI operations
• WiMAXAPI operations
For more information about provisioning requirements and dependencies, see:
• Service Manager: Network Access Guide for AAA
• Service Manager: Subscriber Provisioning Guide for AAA
• Service Manager Online Help

Service Controller 9.6.1-AAA October 26, 2012 Page 41

Chapter 4 Provisioning APIs Provisioning API Guide

API libraries
The XML interface enables provisioning operations on the Provisioning Server.
Operations are grouped into the following XML API libraries:
• AccessNodeAPI
• AccountAPI
• DAEAPI
• DomainAPI
• HotlineAPI
• OrganizationAPI
• ProfileAPI
• Proxy Deployment APIs
• ServiceAPI
• SessionAPI
• SystemAPI
• TrunkGroupAPI
• UserAPI
• WiMAXAPI

AccessNodeAPI
The AccessNodeAPI library operations operate on the access node entity
described in "Network entity modelling" on page 11.
Supported operations are listed in Table 5.

Table 5: AccessNodeAPI operations

Operation Example

createAccessNode "Create access node" on page 54

"Create access node with NAS role and session expiry time" on
page 56

"Create access node, associate HA to multiple RMS clusters" on

page 57

"Create access node to enable CoA/DM failover" on page 57

"Create access node to enable CoA/DM cloning" on page 59

deleteAccessNode "deleteAccessNode" on page 60

getAccessNode "Retrieve access node information" on page 61

Page 42 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Table 5: AccessNodeAPI operations (continued)

Operation Example

updateAccessNode "Update access node" on page 64

"Update access node NAS role to limit session expiry time" on

page 65

"Update DAE settings" on page 66

"Update access node, associate HA to multiple RMS clusters" on

page 66

"Update DAE settings, enable CoA/DM failover" on page 67

"Update DAE settings, enable CoA/DM cloning" on page 68

AccountAPI
The AccountAPI library operations operate on the account and account profile set
entities described in "Subscriber entity modelling" on page 9.
Supported operations are listed in Table 6.

Table 6: AccountAPI operations

Operation Example

createAccount "Provisioned RADIUS connection service profile attributes" on

page 70

deleteAccount "Specified account" on page 73

findAccounts "Specified account name" on page 74

getAccount "Get RADIUS connection service profile attributes" on page

75

updateAccount "Update RADIUS connection service profile attributes" on

page 78

"Delete RADIUS connection service profile attributes" on

page 79

createAccountProfileSet "Provisioned RADIUS connection service profile attributes" on

page 72

getAccountProfileSet "Get RADIUS connection service profile attributes" on page

76

updateAccountProfileSet "Add or update RADIUS connection service profile attributes"

on page 80

"Delete RADIUS connection service profile attributes" on

page 80

Service Controller 9.6.1-AAA October 26, 2012 Page 43

Chapter 4 Provisioning APIs Provisioning API Guide

DAEAPI
The DAEAPI library operations operate on the user and user profile set entities
described in "Subscriber entity modelling" on page 9.
Supported operations are listed in Table 7.

Table 7: DAEAPI operations

Operation Example

clearHotline "Clear hotline session" on page 82

sendCoA "Send a CoA request" on page 85

sendDisconnect "Send a WiMAX-based DM request" on page 88

DomainAPI
The DomainAPI library operations operate on the domain and domain profile set
entities described in "Subscriber entity modelling" on page 9.
Supported operations are listed in Table 8.

Table 8: DomainAPI operations

Operation Example

createDomain "Provisioned RADIUS connection service profile attributes"

on page 92

getDomain "Get RADIUS connection service profile attributes" on page

94

updateDomain "Add or update RADIUS connection service profile attributes"

on page 97

"Delete RADIUS connection service profile attributes" on

page 98

createDomainProfileSet "Create RADIUS connection service profile attributes" on

page 93

getDomainProfileSet "Get RADIUS connection service profile attributes" on page

96

updateDomainProfileSet "Update RADIUS connection service profile attributes" on

page 99

"Delete RADIUS connection service profile attributes" on

page 99

Page 44 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

HotlineAPI
The HotlineAPI library operations create and update user profiles and delete users
and accounts.
Supported operations are listed in Table 7.

Table 9: HotlineAPI operations

Operation Example

createUser "Create a WiMAX user" on page 101

updateUser "Update WiMAX user attribute" on page 108

deleteUser "Delete a user" on page 104

"Delete a user and specify RADIUS attributes" on page

105

deleteAccount "Delete an account" on page 106

"Delete an account and specify RADIUS attributes" on

page 106

getCoAMetrics "Get CoA metrics" on page 111.

getDMMetrics "Get DM metrics" on page 111.

getCoADMMetrics "Get CoA and DM metrics" on page 112.

clearCoADMFailureMetrics "Clear CoA and DM metrics" on page 113.

OrganizationAPI
The OrganizationAPI library operations operate on the organization and
organization profile set entities described in "Subscriber entity modelling" on page
9.
Supported operations are listed in Table 10.

Table 10: OrganizationAPI operations

Operation Example

createOrganization "Provision RADIUS connection service profile attributes"

on page 146

getOrganization "Get RADIUS connection service profile attributes" on

page 149

updateOrganization "Update RADIUS connection service profile attributes"

on page 152

"Delete RADIUS connection service profile attributes" on

page 154

Service Controller 9.6.1-AAA October 26, 2012 Page 45

Chapter 4 Provisioning APIs Provisioning API Guide

Table 10: OrganizationAPI operations (continued)

Operation Example

createOrganizationProfileSet "Provision RADIUS connection service profile attributes"

on page 148

getOrganizationProfileSet "Get RADIUS connection service profile attributes" on

page 150

updateOrganizationProfileSet "Update RADIUS connection service profile attributes"

on page 155

"Delete RADIUS connection service profile attributes" on

page 156

ProfileAPI
The ProfileAPI library operations operate on the profile and service attribute entities
described in "Service entity modelling" on page 7.
Supported operations are listed in Table 11.

Table 11: ProfileAPI operations

Operation Example

createProfile "Create RADIUS QoS selection policy service profile" on page 158

"Create RADIUS connection service profile" on page 159

"Create a Diameter connection service profile" on page 161

deleteProfile "Delete RADIUS QoS selection policy service profile" on page 162

"Delete RADIUS connection service profile" on page 163

"Delete a Diameter connection service profile" on page 163

getProfile "Get RADIUS QoS selection policy service profile" on page 164

"Get RADIUS connection service profile" on page 165

"Get a Diameter connection service profile" on page 166

updateProfile "Update RADIUS connection service profile" on page 168

"Modify values of a Diameter attribute" on page 169

findProfiles "Find all profiles in the Root organization" on page 170

Page 46 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Proxy Deployment APIs

The Proxy Deployment APIs include:
• ProxyFilterAPI
• ProxyOverride AttributeGroupAPI
• ProxyRequired AttributeGroupAPI
• RADIUSServerAPI
• RADIUSServer GroupAPI

ProxyFilterAPI ProxyFilterAPI operations are listed in Table 11.

Table 12: ProxyFilterAPI operations

Operation Example

createProxyFilter —

getProxyFilterBy Name —

deleteProxyFilterBy Name —

ProxyOverride ProxyOverrideAttributeGroupAPI operations are listed in Table 11.

AttributeGroupAPI
Table 13: ProxyOverrideAttributeGroupAPI operations

Operation Example

createProxyOverrideAttributeGroup —

updateProxyOverrideAttributeGroup —

getProxyOverride AttributeGroupBy Name —

deleteProxyOverrideAttributeGroupBy Name —

ProxyRequired ProxyRequiredAttributeGroupAPI operations are listed in Table 11.

AttributeGroupAPI
Table 14: ProxyRequiredAttributeGroupAPI operations

Operation Example

createProxyRequiredAttributeGroup —

updateProxyRequiredAttributeGroup —

getProxyRequired AttributeGroupBy Name —

deleteProxyRequiredAttributeGroupBy Name —

Service Controller 9.6.1-AAA October 26, 2012 Page 47

Chapter 4 Provisioning APIs Provisioning API Guide

RADIUSServerAPI RADIUSServerAPI operations are listed in Table 11.

Table 15: RADIUSServerAPI operations

Operation Example

createRADIUSServer —

updateRADIUSServer —

getRADIUSServerByName —

deleteRADIUSServerByName —

RADIUSServer RADIUSServerGroupAPI operations are listed in Table 11.

GroupAPI
Table 16: RADIUSServerGroupAPI operations

Operation Example

createRADIUSServerGroup —

updateRADIUSServerGroup —

getRADIUSServer GroupByName —

deleteRADIUSServerGroupByName —

ServiceAPI
The ServiceAPI library operations may be used to retrieve information about the
service entity described in "Service entity modelling" on page 7.
Supported operations are listed in Table 17.

Table 17: ServiceAPI operations

Operation Example

getService "Get RADIUS QoS selection policy service attributes" on page 212

Page 48 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

SessionAPI
The SessionAPI library operations retrieve session information and device records.
Supported operations are listed in Table 18.

Table 18: SessionAPI operations

Operation Example

getSessionStatusByLoginName "Get session status by login name" on page 217

getSessionStatusByIP "Get session status by IP" on page 220

SystemAPI
The SystemAPI library operations may be used to update the current system
configuration and HUP processes like the Service Controller.
Supported operations are listed in Table 19.

Table 19: SystemAPI operations

Operation Example

applyChanges "Update system configuration" on page 222

TrunkGroupAPI
The TrunkGroupAPI library operations may be used to create, delete, update, or
retrieve Trunk group entities.
Supported operations are listed in Table 20.

Table 20: TrunkGroupAPI operations

Operation Example

createTrunkGroup "Trunk group" on page 223

deleteTrunkGroup "Trunk group" on page 224

getTrunkGroup "Retrieve Trunk group information" on page 225

updateTrunkGroup "Change name" on page 226

"Change RMS cluster" on page 227

updateTrunkGroups "Change DNs and DN ranges" on page 228

Service Controller 9.6.1-AAA October 26, 2012 Page 49

Chapter 4 Provisioning APIs Provisioning API Guide

UserAPI
The UserAPI library operations operate on the user and user profile set entities
described in "Subscriber entity modelling" on page 9.
Supported operations are listed in Table 21.

Table 21: UserAPI operations

Operation Example

createUser "Specified domain and organization" on page 233

"Generate a random password" on page 233

"Provisioned RADIUS connection service profile attributes" on

page 234

"Add WiMAX user attributes" on page 236

getUser "Specified user name and domain" on page 242

"Specified login name and password" on page 244

"RADIUS connection service profile attributes" on page 246

findUsers "Find specified subscriber" on page 240

updateUser "Change password" on page 253

"Change attributes" on page 254

"Change user status" on page 258

"Change login name" on page 259

"Update RADIUS connection service profile attributes" on page

259

"Delete RADIUS connection service profile attributes" on page

260

deleteUser "Specified user" on page 239

createUserProfileSet "Provisioned RADIUS connection service profile attributes" on

page 238

getUserProfileSet "Get RADIUS QoS Selection Policy Profile attributes" on page

250

"Get RADIUS connection service profile attributes" on page 252

getUserWithActiveSer "Get list of active RADIUS connection service profiles" on page

vices 248

Page 50 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Table 21: UserAPI operations (continued)

Operation Example

updateUserProfileSet "Create RADIUS QoS Selection Policy Profile attributes" on

page 261

"Update RADIUS QoS Selection Policy Profile attributes" on

page 262

"Delete RADIUS QoS Selection Policy Profile attributes" on

page 263

"Update RADIUS connection service profile attributes" on page

264

"Delete RADIUS connection service profile attributes" on page

264

WiMAXAPI
The WiMAXAPI library operations operate on the WiMAX node,
WiMAXNodeGroup, WiMAXHAGroup, and WiMAXDevice entities described in
"WiMAX entity modelling" on page 13.
Supported operations are listed in Table 22.

Table 22: WiMAXAPI operations

Operation Example

createWiMAXDevice "WiMAX device" on page 266

updateWiMAXDevice "Suspend service for a device" on page 281

createWiMAXNodeGroup "Empty WiMAX node group" on page 269

"Node group with two WiMAX nodes" on page 269

getWiMAXNodeGroup "Retrieve WiMAX node group information only" on page 277

"Retrieve WiMAX group, nodes, and attribute information"

on page 278

"Retrieve information about Diameter-enabled WiMAX node

groups" on page 277

updateWiMAXNodeGroup "Change name and caption" on page 284

"Add nodes to a WiMAX node group" on page 284

"Remove nodes from a WiMAX node group" on page 285

deleteWiMAXNodeGroup "Specified node group" on page 271

Service Controller 9.6.1-AAA October 26, 2012 Page 51

Chapter 4 Provisioning APIs Provisioning API Guide

Table 22: WiMAXAPI operations (continued)

Operation Example

createWiMAXHAGroup "Empty WiMAX HA group" on page 267

"HA group with two WiMAX nodes" on page 267

getWiMAXHAGroup "Retrieve WiMAX HA group information only" on page 273

"Retrieve WiMAX HA group, nodes, and attribute

information" on page 274

updateWiMAXHAGroup "Change name and caption" on page 282

"Add nodes to a WiMAX HA group" on page 282

"Remove nodes from a WiMAX HA group" on page 283

deleteWiMAXHAGroup "Specified HA group" on page 271

createWiMAXDevice "WiMAX device" on page 266

getWiMAXDevice "Retrieve WiMAX device information only" on page 272

updateWiMAXDevice "Suspend service for a device" on page 281

deleteWiMAXDevice "Specified device" on page 270

XML provisioning examples

Sample API calls are provided in the following sections for each of the supported
API operations.
Each example includes a sample request that is sent to the Provisioning Server,
and a sample response that is returned by the Provisioning Server if the input XML
is successful.
For information about the structure of a request or response message, see
"Message structure" on page 17.
Examples use the syntax and functionality defined for Release 9.6.1-AAA. Future
releases may contain additional attributes and elements in XML responses for any
operation. Client applications should be designed to ignore unrecognized attributes
or elements. For more information, see "Forward compatibility" on page 28.
Examples are grouped by API library.

Page 52 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

AccessNodeAPI operations
This section describes the following AccessNodeAPI operations:
• createAccessNode
• deleteAccessNode
• getAccessNode
• updateAccessNode
Note Changes to the system configuration are committed to the Profile Database
when the API operation completes. To notify other BWS components about
any changes to the current system configuration, execute the
applyChanges operation. For details, see "applyChanges" on page 222.

createAccessNode
Use the createAccessNode operation to create an access node. Specify a
populated access node element, including:
• the valid IP address of the access node
• at least one available protocol (RADIUS or Diameter)
• a shared secret for RADIUS (if appropriate)
• a hostname, realm, port, and transfer protocol for Diameter (if appropriate)
• at least one role (NAS, PDSN, GGSN, GSM Node, WiMAX ASN Gateway,
WiMAX HA, or Hotlining Application)
• the number of sessions for a PDSN role
• the number of sessions for a NAS role
• the protocol enable status for a WiMAX ASN role
• the skip count for a WiMAX HA role
These elements are optional:
• the caption under which the access node displays in Service Manager
• a description of the access node
• the time zone where the access node is located
• The CoA shared secret for RADIUS
• one or more node groups to which the access node belongs
• the DAE settings for the access node:
Configure:
– a primary and failover access node for CoA messages and a primary and
failover access node for DM messages, so that if a CoA/DM message times
out, the RADIUS Server can send the message to the failover node.
Note The Provisioning Server has a fixed time out. Setting up a DAE timeout
and retry, defining in aggregate the time radius takes to try the DAE
transaction, that exceeds the timeout configured in the Provisioning
Server, (and it may max at 15 or 20 seconds TOTAL), then the DAE
transactions can succeed. However, the Provisioning Server still

Service Controller 9.6.1-AAA October 26, 2012 Page 53

Chapter 4 Provisioning APIs Provisioning API Guide

reports the transactions as a failure. The Provisioning Server may

attempt to transmit them to a secondary radius if that is configured in
the deployment. For example, a configured 15 second retry interval
and 5 retries (which means a total of 90 seconds could be consumed
before radius reports failure), the Provisioning Server considers the
transaction failed before radius is done. Bridgewater Systems
recommends keeping these values relatively small.
• the session expiry time (NAS role only)

Create access node This example illustrates required and optional elements for the createAccessNode
operation.
Modify the example to suit the network, or see these specific examples:
• Create access node with NAS role and session expiry time
• Create access node, associate HA to multiple RMS clusters
• Create access node to enable CoA/DM failover
• Create access node to enable CoA/DM cloning

Request
<request credentials="root" principal="root" version="2.0">
<target name="AccessNodeAPI" operation="createAccessNode">
<parameter>
<access-node>
<ip>192.100.125.107</ip>
<caption>accessNodeCaption6</caption>
<description>accessNodeDescription</description>
<time-zone>GMT</time-zone>
<dae-enabled>true</dae-enabled>
<dae-ip-address>192.100.125.107</dae-ip-address>
<dae-port>1065</dae-port>
<dae-shared-secret>daeSecret</dae-shared-secret>
<dae-failover-ip-address>192.100.125.108</dae-failover-ip-address>
<dae-failover-port>1066</dae-failover-port>
<dae-failover-shared-secret>daeSecret2
</dae-failover-shared-secret>
<dae-dm-ip-address>1.1.1.3</dae-dm-ip-address>
<dae-dm-port>3799</dae-dm-port>
<dae-dm-shared-secret>MYSECRET
</dae-dm-shared-secret>
<dae-dm-failover-ip-address>1.1.1.4</dae-dm-failover-ip-address>
<dae-dm-failover-port>3800</dae-dm-failover-port>
<dae-dm-failover-shared-secret>MYSECRET2
</dae-dm-failover-shared-secret>
<dae-timeout>10</dae-timeout>

Page 54 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<dae-retries>3</dae-retries>
<dae-failover-timeout>10</dae-failover-timeout>
<dae-failover-retries>3</dae-failover-retries>
<radius-protocol>
<shared-secret>sharedSecret</shared-secret>
<coa-shared-secret>COASECRET
</coa-shared-secret>
</radius-protocol>
<diameter-protocol>
<host-name>localhost</host-name>
<realm-name>realm</realm-name>
<port>163</port>
<transport-protocol>UDP</transport-protocol>
</diameter-protocol>
<wimax-ha-role>
<skip-count>10</skip-count>
</wimax-ha-role>
<asn-gateway-role>
<enable-radius>true</enable-radius>
</asn-gateway-role>
<pdsn-role>
<sessions>10</sessions>
</pdsn-role>
<nas-role/>
<ggsn-role>
<ip-address-range>
<start-ip>10.10.10.10</start-ip>
<end-ip>10.10.10.20</end-ip>
</ip-address-range>
</ggsn-role>
<gsm-node-role/>
<hotlining-application-role/>
</access-node>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccessNodeAPI" operation="createAccessNode">
<result/>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 55

Chapter 4 Provisioning APIs Provisioning API Guide

Create access node This example shows how to create an access node with a NAS role, and how to
with NAS role and limit a user’s session by defining a session expiry time. The <expiry-time> element
session expiry time is optional.

Request
<request credentials="root" principal="root" version="2.0">
<target name="AccessNodeAPI" operation="createAccessNode">
<parameter>
<access-node>
<ip>192.100.125.107</ip>
<caption>accessNodeCaption6</caption>
<description>accessNodeDescription</description>
<radius-protocol>
<shared-secret>TESTSECRET</shared-secret>
</radius-protocol>
<time-zone>GMT</time-zone>
<nas-role>
<expiry-time>3600</expiry-time>
</nas-role>
</access-node>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccessNodeAPI" operation="createAccessNode">
<result/>
</target>
</response>

Page 56 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Create access node, For custom WiMAX deployments in which HAs are associated to multiple RMS
associate HA to clusters, the HA role must specify which RMS cluster holds HA keying information.
multiple RMS To do this, modify the <wimax-ha-role> parent element with the <rms-cluster-id>
clusters child element to specify the cluster in which HA keying information is stored.
In this example, the bold text represents the <rms-cluster-id> element and its
corresponding value.

Request
<request credentials="root" principal="root" version="2.0">
<target name="AccessNodeAPI" operation="createAccessNode">
<parameter>
<access-node>
…
<wimax-ha-role>
<skip-count>10</skip-count>
<rms-cluster-id>0</rms-cluster-id>
</wimax-ha-role>
…
</access-node>
</parameter>
</target>
</request>

Create access node This example shows how to create an access node to enable CoA/DM failover.
to enable CoA/DM Configure a primary and failover access node for CoA messages and a primary and
failover failover access node for DM messages, so that if a CoA or DM message times out,
the RADIUS Server can send the message to the failover node.

Request
<request credentials="root" principal="root" version="2.0">
<target name="AccessNodeAPI" operation="createAccessNode">
<parameter>
<access-node>
<ip>192.100.125.107</ip>
<dae-enabled>true</dae-enabled>
<dae-clone-dm>false</dae-clone-dm>
<dae-clone-coa>false</dae-clone-coa>
<dae-ip-address>192.100.125.107</dae-ip-address>
<dae-port>1065</dae-port>
<dae-shared-secret>daeSecret</dae-shared-secret>
<dae-failover-ip-address>192.100.125.108</dae-failover-ip-address>
<dae-failover-port>1066</dae-failover-port>
<dae-failover-shared-secret>daeSecret2

Service Controller 9.6.1-AAA October 26, 2012 Page 57

Chapter 4 Provisioning APIs Provisioning API Guide

</dae-failover-shared-secret>
<dae-dm-ip-address>1.1.1.3</dae-dm-ip-address>
<dae-dm-port>3799</dae-dm-port>
<dae-dm-shared-secret>MYSECRET
</dae-dm-shared-secret>
<dae-dm-failover-ip-address>1.1.1.4</dae-dm-failover-ip-address>
<dae-dm-failover-port>3800</dae-dm-failover-port>
<dae-dm-failover-shared-secret>MYSECRET2
</dae-dm-failover-shared-secret>
<dae-timeout>10</dae-timeout>
<dae-retries>3</dae-retries>
<dae-failover-timeout>10</dae-failover-timeout>
<dae-failover-retries>3</dae-failover-retries>
<radius-protocol>
<shared-secret>sharedSecret</shared-secret>
<coa-shared-secret>COASECRET
</coa-shared-secret>
</radius-protocol>
<diameter-protocol>
<host-name>localhost</host-name>
<realm-name>realm</realm-name>
<port>163</port>
<transport-protocol>UDP</transport-protocol>
</diameter-protocol>
<asn-gateway-role>
<enable-radius>true</enable-radius>
</asn-gateway-role>
</access-node>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccessNodeAPI" operation="createAccessNode">
<result/>
</target>
</response>

Page 58 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Create access node This example shows how to create an access node to enable CoA/DM cloning.
to enable CoA/DM Configure cloning so that the Provisioning Server clones a CoA/DM message,
cloning sends the request to the RADIUS Server, and the RADIUS Server sends the
original and cloned message in parallel to two different targets.
If CoA/DM cloning is enabled, configure primary and alternate primary CoA/DM
targets. The alternate primary target is configured in the following fields:
• for CoA:
– dae-failover-ip-address
– dae-failover-port
– dae-failover-shared-secret
• for DM:
– dae-dm-failover-ip-address
– dae-dm-failover-port
– dae-dm-failover-shared-secret

Request
<request credentials="root" principal="root" version="2.0">
<target name="AccessNodeAPI" operation="createAccessNode">
<parameter>
<access-node>
<ip>192.100.125.107</ip>
<dae-enabled>true</dae-enabled>
<dae-clone-dm>true</dae-clone-dm>
<dae-clone-coa>true</dae-clone-coa>
<dae-ip-address>192.100.125.107</dae-ip-address>
<dae-port>1065</dae-port>
<dae-shared-secret>daeSecret</dae-shared-secret>
<dae-failover-ip-address>192.100.125.108</dae-failover-ip-address>
<dae-failover-port>1066</dae-failover-port>
<dae-failover-shared-secret>daeSecret2
</dae-failover-shared-secret>
<dae-dm-ip-address>1.1.1.3</dae-dm-ip-address>
<dae-dm-port>3799</dae-dm-port>
<dae-dm-shared-secret>MYSECRET
</dae-dm-shared-secret>
<dae-dm-failover-ip-address>1.1.1.4</dae-dm-failover-ip-address>
<dae-dm-failover-port>3800</dae-dm-failover-port>
<dae-dm-failover-shared-secret>MYSECRET2
</dae-dm-failover-shared-secret>
<dae-timeout>10</dae-timeout>
<dae-retries>3</dae-retries>
<dae-failover-timeout>10</dae-failover-timeout>

Service Controller 9.6.1-AAA October 26, 2012 Page 59

Chapter 4 Provisioning APIs Provisioning API Guide

<dae-failover-retries>3</dae-failover-retries>
<radius-protocol>
<shared-secret>sharedSecret</shared-secret>
<coa-shared-secret>COASECRET
</coa-shared-secret>
</radius-protocol>
<diameter-protocol>
<host-name>localhost</host-name>
<realm-name>realm</realm-name>
<port>163</port>
<transport-protocol>UDP</transport-protocol>
</diameter-protocol>
<asn-gateway-role>
<enable-radius>true</enable-radius>
</asn-gateway-role>
</access-node>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccessNodeAPI" operation="createAccessNode">
<result/>
</target>
</response>

deleteAccessNode
Use the deleteAccessNode operation to delete an access node.These elemenst
are required:
• the name or ID (for example, IP address) of the access node

Delete access node This example shows how to delete an access node.

Request
<request credentials="root" principal="root" version="2.0">
<target name="AccessNodeAPI" operation="deleteAccessNode">
<parameter>
<access-node>
<ip>192.100.125.107</ip>
</access-node>
</parameter>

Page 60 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</target>
</request>

Response
<response version="2.0">
<target name="AccessNodeAPI" operation="deleteAccessNode">
<result/>
</target>
</response>

getAccessNode
Use the getAccessNode operation to retrieve a fully-populated access node. These
elements are required:
• the name or ID (for example, IP address) of the access node
The response returns a fully-populated access node.

Retrieve access node This example shows how to retrieve information about an access node.
information
Request
<request credentials="root" principal="root" version="2.0">
<target name="AccessNodeAPI" operation="getAccessNode">
<parameter>
<access-node>
<ip>192.100.125.107</ip>
</access-node>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccessNodeAPI" operation="getAccessNode">
<result>
<access-node>
<configuration-id>1</configuration-id>
<ip>192.100.125.106</ip>
<caption>accessNodeCaption6</caption>
<description>accessNodeDescription</description>
<pdsn-role>
<sessions>10</sessions>
<delete>false</delete>
</pdsn-role>

Service Controller 9.6.1-AAA October 26, 2012 Page 61

Chapter 4 Provisioning APIs Provisioning API Guide

<nas-role>
<sessions>100</sessions>
<expiry-time>3600</expiry-time>
<time-zone>GMT</time-zone>
<managed>false</managed>
<delete>false</delete>
</nas-role>
<lns-role>
<delete>false</delete>
</lns-role>
<gsm-node-role>
<delete>false</delete>
</gsm-node-role>
<ggsn-role>
<ip-address-range>
<start-ip>0.10.10.10</start-ip>
<end-ip>10.10.10.20</end-ip>
</ip-address-range>
<delete>false</delete>
</ggsn-role>
<wimax-ha-role>
<skip-count>10</skip-count>
<root-key-lifetime>86400</root-key-lifetime>
<delete>false</delete>
</wimax-ha-role>
<asn-gateway-role>
<enable-radius>true</enable-radius>
<enable-diameter>false</enable-diameter>
<delete>false</delete>
</asn-gateway-role>
<hotlining-application-role>
<delete>false</delete>
</hotlining-application-role>
<vendor>RFC2138</vendor>
<time-zone>GMT</time-zone>
<dae-enabled>true</dae-enabled>
<dae-ip-address>192.100.125.107</dae-ip-address>
<dae-port>1065</dae-port>
<dae-shared-secret>daeSecret</dae-shared-secret>
<dae-dm-ip-address>1.1.1.3</dae-dm-ip-address>
<dae-dm-port>3799</dae-dm-port>
<dae-dm-shared-secret>MYSECRET
</dae-dm-shared-secret>

Page 62 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<dae-timeout>10</dae-timeout>
<dae-retries>3</dae-retries>
<diameter-protocol>
<host-name>localhost</host-name>
<realm-name>bridgewater</realm-name>
<port>163</port>
<transport-protocol>UDP</transport-protocol>
</diameter-protocol>
<radius-protocol>
<shared-secret>sharedSecret</shared-secret>
<coa-shared-secret>COASECRET
</coa-shared-secret>
</radius-protocol>
</access-node>
</result>
</target>
</response>

updateAccessNode
Use the updateAccessNode operation to modify an access node. These elements
are required:
• the name or ID (for example, IP address) of the access node
These elements are optional:
• a new name, caption, or description for the access node
• a new shared secret or CoA shared secret for the RADIUS protocol
• a role to add
• a role delete flag to indicate that the role should be deleted
• a node group to which the node should be added
• a node group delete flag to indicate that the node should be removed from the
node group
• the time zone where the access node is located
• a protocol (RADIUS or Diameter) to add
• a protocol (RADIUS or Diameter) to modify
• a protocol (RADIUS or Diameter) delete flag to indicate that the protocol should
be removed from the node
• DAE settings to change or add:
Configure:

Service Controller 9.6.1-AAA October 26, 2012 Page 63

Chapter 4 Provisioning APIs Provisioning API Guide

– a primary and failover access node for CoA messages and a primary and
failover access node for DM messages, so that if a CoA/DM message times
out, the RADIUS Server can send the message to the failover node.
Note The Provisioning Server has a fixed time out.Setting up a DAE timeout
and retry, defining in aggregate the time radius takes to try the DAE
transaction, that exceeds the timeout configured in the Provisioning
Server, (and it may max at 15 or 20 seconds TOTAL), then the DAE
transactions can succeed. However, the Provisioning Serverbut still
reports the transactions as a failure. The Provisioning Server may
attempt to transmit them to a secondary radius if that is configured in
the deployment. For example, a configured 15 second retry interval
and 5 retries (which means a total of 90 seconds could be consumed
before radius reports failure),the Provisioning Server considers the
transaction failed before radius is done. Bridgewater Systems
recommends keeping these values relatively small.
• the session expiry time (NAS role only)

Update access node This example shows how to modify an access node. This example changes the:
• shared secret used by the RADIUS Server
• skip count used for the WiMAX HA role
• numbers of sessions used for the PDSN role
This example also deletes a previously configured ASN Gateway role.

Request
<request credentials="root" principal="root" version="2.0">
<target name="AccessNodeAPI" operation="updateAccessNode">
<parameter>
<access-node>
<ip>192.100.125.107</ip>
<radius-protocol>
<shared-secret>sharedSecret</shared-secret>
<coa-shared-secret>COASECRET
</coa-shared-secret>
</radius-protocol>
<wimax-ha-role>
<skip-count>10</skip-count>
</wimax-ha-role>
<asn-gateway-role>
<delete>true</delete>
</asn-gateway-role>
<pdsn-role>
<sessions>10</sessions>
</pdsn-role>
<gsm-node-role/>

Page 64 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</access-node>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccessNodeAPI" operation="updateAccessNode">
<result/>
</target>
</response>

Update access node This example shows how to update an access node with a NAS role to limit users’
NAS role to limit session. Limit users’ sessions by defining a session expiry time. The <expiry-time>
session expiry time element is optional and can only be used for access nodes with a NAS role.

Request
<request credentials="root" principal="root" version="2.0">
<target name="AccessNodeAPI" operation="updateAccessNode">
<parameter>
<access-node>
<ip>192.100.125.107</ip>
<radius-protocol>
<shared-secret>TESTSECRET</shared-secret>
</radius-protocol>
<nas-role>
<expiry-time>10000</expiry-time>
</nas-role>
</access-node>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccessNodeAPI" operation="updateAccessNode">
<result/>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 65

Chapter 4 Provisioning APIs Provisioning API Guide

Update access node, For custom WiMAX deployments in which HAs are associated to multiple RMS
associate HA to clusters, the HA role must specify which RMS cluster holds HA keying information.
multiple RMS To update such an HA, modify the <wimax-ha-role> parent element with the
clusters <rms-cluster-id> child element to specify the cluster in which HA keying information
is stored.
Note Bridgewater Systems does not recommend changing the value of the
<rms-cluster-id>. However, to modify this value, restart the RADIUS Server,
which enables the RADIUS Server to re-create HA keys in the new RMS
cluster.
Note Bridgewater Systems recommends restarting the RADIUS Server when
network traffic is minimal and when the HA key nears its expiration date.
In This example, the bold text represents the <rms-cluster-id> element and its
corresponding value.

Request
<request credentials="root" principal="root" version="2.0">
<target name="AccessNodeAPI" operation="updateAccessNode">
<parameter>
<access-node>
…
<wimax-ha-role>
<skip-count>10</skip-count>
<rms-cluster-id>0</rms-cluster-id>
</wimax-ha-role>
…
</access-node>
</parameter>
</target>
</request>

Update DAE settings This example shows how to update the DAE settings for an access node.

Request
<request credentials="root" principal="root" version="2.0">
<target name="AccessNodeAPI" operation="updateAccessNode">
<parameter>
<access-node>
<ip>192.100.125.107</ip>
<dae-enabled>true</dae-enabled>
<dae-ip-address>192.100.125.107</dae-ip-address>
<dae-port>1065</dae-port>
<dae-shared-secret>daeSecret</dae-shared-secret>
<dae-failover-ip-address>192.100.125.108</dae-failover-ip-address>
<dae-failover-port>1066</dae-failover-port>

Page 66 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<dae-failover-shared-secret>daeSecret2
</dae-failover-shared-secret>
<dae-dm-ip-address>1.1.1.3</dae-dm-ip-address>
<dae-dm-port>3799</dae-dm-port>
<dae-dm-shared-secret>MYSECRET
</dae-dm-shared-secret>
<dae-dm-failover-ip-address>1.1.1.4</dae-dm-failover-ip-address>
<dae-dm-failover-port>3800</dae-dm-failover-port>
<dae-dm-failover-shared-secret>MYSECRET2
</dae-dm-failover-shared-secret>
<dae-timeout>10</dae-timeout>
<dae-retries>3</dae-retries>
<dae-failover-timeout>10</dae-failover-timeout>
<dae-failover-retries>3</dae-failover-retries>
</access-node>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccessNodeAPI" operation="updateAccessNode">
<result/>
</target>
</response>

Update DAE settings, This example shows how to update the DAE settings for an access node to enable
enable CoA/DM CoA/DM failover.
failover Configure a primary and failover access node for CoA messages and a primary and
failover access node for DM messages, so that if a CoA or DM message times out,
the RADIUS Server can send the message to the failover node.

Request
<request credentials="root" principal="root" version="2.0">
<target name="AccessNodeAPI" operation="updateAccessNode">
<parameter>
<access-node>
<ip>192.100.125.107</ip>
<dae-enabled>true</dae-enabled>
<dae-clone-dm>true</dae-clone-dm>
<dae-clone-coa>true</dae-clone-coa>
<dae-ip-address>192.100.125.107</dae-ip-address>
<dae-port>1065</dae-port>

Service Controller 9.6.1-AAA October 26, 2012 Page 67

Chapter 4 Provisioning APIs Provisioning API Guide

<dae-shared-secret>daeSecret</dae-shared-secret>
<dae-failover-ip-address>192.100.125.108</dae-failover-ip-address>
<dae-failover-port>1066</dae-failover-port>
<dae-failover-shared-secret>daeSecret2
</dae-failover-shared-secret>
<dae-dm-ip-address>1.1.1.3</dae-dm-ip-address>
<dae-dm-port>3799</dae-dm-port>
<dae-dm-shared-secret>MYSECRET
</dae-dm-shared-secret>
<dae-dm-failover-ip-address>1.1.1.4</dae-dm-failover-ip-address>
<dae-dm-failover-port>3800</dae-dm-failover-port>
<dae-dm-failover-shared-secret>MYSECRET2
</dae-dm-failover-shared-secret>
<dae-timeout>10</dae-timeout>
<dae-retries>3</dae-retries>
<dae-failover-timeout>10</dae-failover-timeout>
<dae-failover-retries>3</dae-failover-retries>
</access-node>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccessNodeAPI" operation="updateAccessNode">
<result/>
</target>
</response>

Update DAE settings, This example shows how to update the DAE settings for an access node to enable
enable CoA/DM CoA/DM cloning.
cloning Configure cloning so that the Provisioning Server clones a CoA/DM message,
sends the request to the RADIUS Server, and the RADIUS Server sends the
original and cloned message in parallel to two different targets.
If CoA/DM cloning is enabled, configure primary and alternate primary CoA/DM
targets. The alternate primary target is configured in the following fields:
• for CoA:
– dae-failover-ip-address
– dae-failover-port
– dae-failover-shared-secret
• for DM:
– dae-dm-failover-ip-address

Page 68 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

– dae-dm-failover-port
– dae-dm-failover-shared-secret

Request
<request credentials="root" principal="root" version="2.0">
<target name="AccessNodeAPI" operation="updateAccessNode">
<parameter>
<access-node>
<ip>192.100.125.107</ip>
<dae-enabled>true</dae-enabled>
<dae-clone-dm>true</dae-clone-dm>
<dae-clone-coa>true</dae-clone-coa>
<dae-ip-address>192.100.125.107</dae-ip-address>
<dae-port>1065</dae-port>
<dae-shared-secret>daeSecret</dae-shared-secret>
<dae-failover-ip-address>192.100.125.108</dae-failover-ip-address>
<dae-failover-port>1066</dae-failover-port>
<dae-failover-shared-secret>daeSecret2
</dae-failover-shared-secret>
<dae-dm-ip-address>1.1.1.3</dae-dm-ip-address>
<dae-dm-port>3799</dae-dm-port>
<dae-dm-shared-secret>MYSECRET
</dae-dm-shared-secret>
<dae-dm-failover-ip-address>1.1.1.4</dae-dm-failover-ip-address>
<dae-dm-failover-port>3800</dae-dm-failover-port>
<dae-dm-failover-shared-secret>MYSECRET2
</dae-dm-failover-shared-secret>
<dae-timeout>10</dae-timeout>
<dae-retries>3</dae-retries>
<dae-failover-timeout>10</dae-failover-timeout>
<dae-failover-retries>3</dae-failover-retries>
</access-node>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccessNodeAPI" operation="updateAccessNode">
<result/>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 69

Chapter 4 Provisioning APIs Provisioning API Guide

AccountAPI operations
This section describes the following AccountAPI operations:
• createAccount
• createAccountProfileSet
• deleteAccount
• findAccounts
• getAccount
• getAccountProfileSet
• updateAccount
• updateAccountProfileSet

createAccount
Use the createAccount operation ito create a user account.
These elements are required:
• the account name (unless the NAME_SAME_AS_ID provisioning flag is
specified)
– string, 1 to 64 characters
– cannot contain “/”, “.”, “*”, or “%”
• the organization in which the account is to be created (must already be present)
– specify either the organization qualified name or ID
• an account profile set or service package (must already be present)
– specify either the account profile set or service package qualified name or
ID
– service package qualified name must begin with “/” or the name of the root
organization, in the format RootOrganization/OrganizationName/
CatalogName/ServicePackageName
– service package qualified name cannot end with “/”, and cannot contain two
or more consecutive “/”
These elements are optional:
• account context (A) profile attributes
• account status
– either active or pending

Provisioned RADIUS This example shows how to create an account with provisioned account context
connection service RADIUS connection service profile attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="AccountAPI" operation="createAccount">
<parameter>

Page 70 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<account>
<name>BWS Account</name>
<organization>
<qualified-name>/BWS</qualified-name>
</organization>
<profile-set>
<qualified-name>
BWS Account Profile Set
</qualified-name>
<profile>
<id>15</id>
<attribute name="name1">
<value segment="seg1">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
</profile>
</profile-set>
</account>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccountAPI" operation="createAccount">
<result/>
</target>
</response>

createAccountProfileSet
Use the createAccountProfileSet operation to create an account profile set. These
elements are required:
• the profile set name
• the organization in which the profile set is to be created (must already be
present)
These elements are optional:
• a description of the profile set
• an inheritance flag to determine whether the profile set is available to
sub-organizations (default is yes)
• account group (AG) context profile attributes

Service Controller 9.6.1-AAA October 26, 2012 Page 71

Chapter 4 Provisioning APIs Provisioning API Guide

Provisioned RADIUS This example shows how to create an account profile set, with provisioned settings
connection service for account group context RADIUS connection service profile attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="AccountAPI"
operation="createAccountProfileSet">
<parameter>
<account-profile-set>
<name>BWS Account Profile Set</name>
<organization><id>4</id></organization>
<profile>
<id>5</id>
<attribute name="name1">
<value segment="seg1">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
</profile>
</account-profile-set>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccountAPI" operation="createAccountProfileSet">
<result/>
</target>
</response>

Page 72 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

deleteAccount
Use the deleteAccount operation to delete a user account. Specify:
• the account name or ID

Specified account This example shows how to delete an account with a specified name (BWS
Account).

Request
<request version="2.0" principal="User1" credentials="password">
<target name="AccountAPI" operation="deleteAccount">
<parameter>
<account>
<name>BWS Account</name>
</account>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccountAPI" operation="deleteAccount">
<result/>
</target>
</response>

findAccounts
Use the findAccounts operation to find information about specified accounts.
Search on the following fields:
• account name <name>
• first and last name <first-name last-name>
• postal code <postal-code>
• first line of an address <address>
• phone number <phone-number>
Specify one criteria per search. All records that match the search criteria are
returned.

Service Controller 9.6.1-AAA October 26, 2012 Page 73

Chapter 4 Provisioning APIs Provisioning API Guide

Specified account This example shows how to find information about accounts with the name ‘Smith’.
name
Request
<request version="2.0" principal="User1" credentials="password">
<target name="AccountAPI" operation="findAccounts">
<parameter>
<account-search>
<user>
<name>
<first-name>*</first-name>
<last-name>*Smith<last-name>
</name>
</user>
</account-search>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccountAPI" operation="findAccounts">
<result>
<account>
<account-name>Bob Smith</account-name>
<account-name>Jane Smith</account-name>
<account-name>Steve Smith</account-name>
<account-name>Tracey Smith</account-name>
</account>
</result>
</target>
</response>

Page 74 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

getAccount
Use the getAccount operation to retrieve account information, including the account
name, ID, status, profile information, and account context (A) profile attributes.
These elements are required:
• the account name or account ID within the account
These elements are optional:
• an empty <profile-set> element to be populated with retrieved information. All
account profiles and attributes are returned. For example:
<profile-set></profile-set>
• the profile ID or qualified name that identifies a specific profile for which
attribution information is requested. Only information for that profile are
returned. For example:
<profile-set><profile><id>2</id></profile><profile-set>

Get RADIUS This example shows how to get all profile information for an account, including the
connection service account context RADIUS connection service profile attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="AccountAPI" operation="getAccount">
<parameter>
<account>
<id>5</id>
<profile-set>
</profile-set>
</account>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccountAPI" operation="getAccount">
<result>
<id>5</id>
<name>BWS Account</name>
<status>active</status>
<profile-set>
<profile><id>5</id>
<name>RadiusQoSConnectionService</name>
<service>
<name>RadiusQoSConnectionService</name>

Service Controller 9.6.1-AAA October 26, 2012 Page 75

Chapter 4 Provisioning APIs Provisioning API Guide

<version>1</version>
</service>
<attribute name="name1">
<value segment="segment">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
</profile>
</profile-set>
</result>
</target>
</response>

getAccountProfileSet
Use the getAccountProfileSet operation to retrieve account profile set information,
including the profile set name, ID, associated accounts and profiles, and account
group context (AG) profile attributes. Specify:
• the profile set qualified name or ID
These elements are optional:
• an empty <profile> element to be populated with retrieved information. All
account profiles and attributes are returned. For example:
<profile></profile>
• the profile ID or qualified name that identifies a specific profile for which
attribution information is requested. Only information for that profile are
returned. For example:
<profile><id>2</id></profile>
• the service name that identifies a service for which all associated profiles
should be returned. For example:
<profile>
<service-name>RadiusQoSConnectionService</service-name>
</profile>

Get RADIUS This example shows how to get account group (AG) context RADIUS connection
connection service service profile attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="AccountAPI" operation="getAccountProfileSet">
<parameter>
<account-profile-set>
<qualified-name>BWS Account Profile Set</qualified-name>

Page 76 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<profile>
</profile>
</account-profile-set>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccountAPI" operation="getAccountProfileSet">
<result>
<account-profile-set>
<name>BWS Account Profile Set</name>
<Account><id>5</id></Account>
<profile>
<id>5</id>
<name>RadiusQoSConnectionService</name>
<service>
<name>RadiusQoSConnectionService</name>
<version>1</version>
</service>
<attribute name="name1">
<value segment="segment">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
</profile>
</account-profile-set>
</result>
</target>
</response>

updateAccount
Use the updateAccount operation to modify a user account.
These elements are required:
• the account
– specify the name, qualified name, or ID
These elements are optional:
• an account profile set, to which this profile should be added or deleted

Service Controller 9.6.1-AAA October 26, 2012 Page 77

Chapter 4 Provisioning APIs Provisioning API Guide

• account context (A) profile attributes to be added, modified, or deleted from the
account profile
• a new account status (active, suspended, deleted)
– to change the account status to suspended, you must provide a suspension
reason between 1 and 255 characters long
– cannot change account status to pending
– cannot change the status of a deleted account

Update RADIUS This example shows how to update account context RADIUS connection service
connection service profile attributes.
profile attributes The update-only flag indicates that the value should only be updated if it is already
in the profile. Default action is to add the attribute if it is not present.

Request
<request version="2.0" principal="User1" credentials="password">
<target name="AccountAPI" operation="updateAccount">
<parameter>
<account>
<id>5</id>
<profile-set>
<id>15</id>
<profile>
<id>25</id>
<attribute name="name1">
<value segment="seg1"
update-only="true">value1</value>
</attribute>
</profile>
</profile-set>
</account>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccountAPI" operation="updateAccount">
<result/>
</target>
</response>

Page 78 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Delete RADIUS This example shows how to delete account context RADIUS connection service
connection service profile attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="AccountAPI" operation="updateAccount">
<parameter>
<account>
<id>5</id>
<profile-set>
<id>15</id>
<profile>
<id>25</id>
<attribute name="name1" delete="true"></attribute>
</profile>
</profile-set>
</account>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccountAPI" operation="updateAccount">
<result/>
</target>
</response>

updateAccountProfileSet
Use the updateAccountProfileSet operation to modify an account profile set.
These elements are required:
• the profile set ID or qualified name
These elements are optional:
• a new profile set description
• a new profile set inheritance flag setting
• a new profile set status (active or deleted)
• a profile to be added to, modified, or deleted from the profile set
• account group context (AG) profile attributes to be added to, modified, or
deleted from an account profile

Service Controller 9.6.1-AAA October 26, 2012 Page 79

Chapter 4 Provisioning APIs Provisioning API Guide

Add or update This example shows how to add or update account group context RADIUS
RADIUS connection connection service profile attributes.
service profile
attributes Request
<request version="2.0" principal="User1" credentials="password">
<target name="AccountAPI" operation="updateAccountProfileSet">
<parameter>
<account-profile-set>
<id>15</id>
<profile>
<id>5</id>
<attribute name="name1">
<value segment="seg2">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
</profile>
</account-profile-set>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccountAPI" operation="updateAccountProfileSet">
<result/>
</target>
</response>

Delete RADIUS This example shows how to delete account group context RADIUS connection
connection service service profile attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="AccountAPI"operation="updateAccountProfileSet">
<parameter>
<account-profile-set>
<id>15</id>
<profile>
<id>5</id>
<attribute name="name1" delete="true">
<value segment="segment">value1</value>

Page 80 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</attribute>
<attribute name="name2">
<value delete="true" subscript="3">value2
</value>
</attribute>
</profile>
</account-profile-set>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="AccountAPI" operation="updateAccountProfileSet ">
<result/>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 81

Chapter 4 Provisioning APIs Provisioning API Guide

DAEAPI operations
This section describes the following DAEAPI xml operations:
• clearHotline
• sendCoA
• sendDisconnect
For SOAP interfaces, sendCoA, clearHotline, and sendDisconnect all use the same
wsdl. For information, see "DAEAPI WSDL" on page 290.
Note The sendCoA and sendDisconnect operations do not provide SNMP
statistics.

clearHotline
Use the clearHotline operation to clear a hotline session that is no longer required,
for example, after a user has completed an account action and no longer needs to
be directed to a gateway portal. This operation sends a CoA message from the
Provisioning Server to RADIUS, without including the Hotline-Indication attribute,
Filter IDs and Hotline Attributes. To send a CoA with the Hotline-Indication attribute,
see "sendCoA" on page 84. This operation is used for WiMAX RADIUS CoA
hotlining feature.
These elements are required:
• the subscriber name (contains domain for Profile Database, does not contain
domain for LDAP deployments)
These elemenst are optional:
• whether to send request information to the Home Agent
• whether to send the request information to the Foreign Agent
Note <send-ha-info> has a default value of false if not specified in the xml
request. <send-fa-info> has a default value of true if not specified in the xml
request.

Clear hotline session This example shows how to clear a user hotline session.

Request
<request version="2.0" principal="user" credentials="password">
<target name="DAEAPI" operation="clearHotline">
<parameter>
<wimax-hotlining>
<subscriber-name>test@dss-test.com</subscriber-name>
<send-ha-info>true</send-ha-info>
<send-fa-info>true</send-fa-info>
</wimax-hotlining>
</parameter>
</target>

Page 82 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</request>

Response with error

<response version="2.0">
<target name="DAEAPI" operation="clearHotline">
<error>
<code>DAE-00500</code>
<message>The LDAP datastore does not support
subscriber name with a domain
</message>
</error>
</target>
</response>

Response with error

<response version="2.0">
<target name="DAEAPI" operation="clearHotline">
<result>
<wimax-hotlining>
<ha-node>
<sent>true</sent>
</ha-node>
<fa-node>
<sent>false</sent>
<error>
<code> DAE-00416 </code>
<message>The WiMAX RMS session does not
have hotline capabilities for user:
`bob@d.com`.`
</message>
</error>
</fa-node>
</wimax-hotlining>
</result>
</target>
</response>

Successful response
<response version="2.0">
<target name="DAEAPI" operation="clearHotline">
<result>
<wimax-hotlining>
<ha-node>

Service Controller 9.6.1-AAA October 26, 2012 Page 83

Chapter 4 Provisioning APIs Provisioning API Guide

<sent>true</sent>
<pseudo-identifier>YTI4J2AYO2
</pseudo-identifier>
<rms-cluster-id>0</rms-cluster-id>
</ha-node>
<fa-node>
<sent>true</sent>
<user-identifier>YTI4J2AYO2
</user-identifier>
<rms-cluster-id>0</rms-cluster-id>
</fa-node>
</wimax-hotlining>
</result>
</target>
</response>

sendCoA
Use the sendCoA operation to hotline a user by sending a CoA message from the
Provisioning Server to RADIUS.
Optionally use the sendCoA operation to specify which RADIUS attributes to
include in the CoA message.
Considerations:
• If a user has multiple active sessions a CoA is sent for each active session.
• To clear a hotline session, see "clearHotline" on page 82. This operation is used
for RADIUS CoA hotlining.
• To send an empty attribute value, specify #Null as the value. The #Null value is
case-sensitive. For example:
<attribute name="RB-Forward-Policy">
<value context="default"
segment="REDBACK">#Null</value>
These elements are required:
• the subscriber name (contains domain for Profile Database, does not contain
domain for LDAP deployments)
These elements are optional:
• whether to send request information to the Home Agent
• whether to send the request information to the Foreign Agent
Note <send-ha-info> has a default value of false if not specified in the xml
request. <send-fa-info> has a default value of true if not specified in the xml
request.

Page 84 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Send a CoA request This example shows how to create a WiMAX hotlining profile for sending CoA
requests.
Note sendCoA requests are also supported in CDMA and GSM environments.

Request
<request version="2.0" principal="user" credentials="password">
<target name="DAEAPI" operation="sendCoA">
<parameter>
<wimax-hotlining>
<subscriber-name>test@dss-test.com</subscriber-name>
<send-ha-info>true</send-ha-info>
<send-fa-info>true</send-fa-info>
</wimax-hotlining>
</parameter>
</target>
</request>

Response with error

<response version="2.0">
<target name="DAEAPI" operation="sendCoA">
<error>
<code>DAE-00500</code>
<message>The LDAP datastore does not support
subscriber name with a domain
</message>
</error>
</target>
</response>

Response with error

<response version="2.0">
<target name="DAEAPI" operation="sendCoA">
<result>
<wimax-hotlining>
<ha-node>
<sent>true</sent>
</ha-node>
<fa-node>
<sent>false</sent>
<error>
<code> DAE-00416 </code>
<message>The WiMAX RMS session does not
have hotline capabilities for user:

Service Controller 9.6.1-AAA October 26, 2012 Page 85

Chapter 4 Provisioning APIs Provisioning API Guide

`bob@d.com`.`
</message>
</error>
</fa-node>
</wimax-hotlining>
</result>
</target>
</response>

Successful response
<response version="2.0">
<target name="DAEAPI" operation="sendCoA">
<result>
<wimax-hotlining>
<ha-node>
<sent>true</sent>
<user-identifier>YTI4J2AYO2
</user-identifier>
<rms-cluster-id>0</rms-cluster-id>
</ha-node>
<fa-node>
<sent>true</sent>
<user-identifier>YTI4J2AYO2
</user-identifier>
<rms-cluster-id>0</rms-cluster-id>
</fa-node>
</wimax-hotlining>
</result>
</target>
</response>

Send a CoA request This example shows a CoA request and response, with RADIUS attributes
with RADIUS specified.
attributes
Request
<request version="2.0" principal="user" credentials="password">
<target name="DAEAPI" operation="sendCoA">
<parameter>
<wimax-hotlining>
<subscriber-name>test@dss-test.com</subscriber-name>
<radius-attribute-list>
<attribute name="Filter-Id">
<value>id1</value>

Page 86 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<value>id2</value>
</attribute>
</radius-attribute-list>
</wimax-hotlining>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="DAEAPI" operation="sendCoA">
<result>
<wimax-hotlining>
<subscriber-name>
0000000000A0@domain.net
</subscriber-name>
<send-ha-info>false</send-ha-info>
<send-fa-info>true</send-fa-info>
<fa-node>
<sent>true</sent>
<user-identifier>YTI4J2AYO2
</user-identifier>
<rms-cluster-id>0</rms-cluster-id>
</fa-node>
</wimax-hotlining>
</result>
</target>
</response>

sendDisconnect
Use the sendDisconnect (DM) operation to disconnect a user by providing an
interface for an external application, such as an HLA to send a DM message to the
Provisioning Server, which sends the message to RADIUS. RADIUS proxies the
DM message to a third party such as an HLD.
If the Provisioning Server detects that the HLD protocol is Diameter, it complies with
the DM message by sending an ASR message to disconnect the subscriber.
Also specify RADIUS attributes to include in the Disconnect message. Specify the
attributes in the dae-service.xml file and in the sendDisconnect message.
Note If attributes are specified in dae-service.xml and in the sendDisconnect
message, the values specified in the sendDisconnect message override
the values specified in dae-service.xml.
These elements are required:

Service Controller 9.6.1-AAA October 26, 2012 Page 87

Chapter 4 Provisioning APIs Provisioning API Guide

• the subscriber name (contains domain for Profile Database, does not contain
domain for LDAP deployments)
Note <send-ha-info> has a default value of false if not specified in the xml
request. <send-fa-info> has a default value of true if not specified in the xml
request.

Send a WiMAX-based This example shows a WiMAX-based DM request and response.

DM request Note sendDisconnect requests are also supported in CDMA and GSM
environments.

Request
<request version="2.0" principal="user" credentials="password">
<target name="DAEAPI" operation="sendDisconnect">
<parameter>
<wimax-hotlining>
<subscriber-name>test@dss-test.com</subscriber-name>
<send-ha-info>true</send-ha-info>
<send-fa-info>true</send-fa-info>
</wimax-hotlining>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="DAEAPI" operation="sendDisconnect">
<result>
<wimax-hotlining>
<fa-node>
<sent>true</sent>
<user-identifier>YTI4J2AYO2
</user-identifier>
<rms-cluster-id>0</rms-cluster-id>
</fa-node>
</wimax-hotlining>
</result>
</target>
</response>

Page 88 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Send a WiMAX-based This example shows a WiMAX-based DM request and response, with RADIUS
DM request with attributes specified.
RADIUS attributes
Request
<request version="2.0" principal="user" credentials="password">
<target name="DAEAPI" operation="sendDisconnect">
<parameter>
<wimax-hotlining>
<subscriber-name>test@dss-test.com</subscriber-name>
<radius-attribute-list>
<attribute name="Filter-Id">
<value>000000000003</value>
</attribute>
</radius-attribute-list>
</wimax-hotlining>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="DAEAPI" operation="sendDisconnect">
<result>
<wimax-hotlining>
<subscriber-name>
0000000000A0@domain.net
</subscriber-name>
<send-ha-info>false</send-ha-info>
<send-fa-info>true</send-fa-info>
<fa-node>
<sent>true</sent>
<user-identifier>YTI4J2AYO2
</user-identifier>
<rms-cluster-id>0</rms-cluster-id>
</fa-node>
</wimax-hotlining>
</result>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 89

Chapter 4 Provisioning APIs Provisioning API Guide

Send a CDMA-based This example shows a DM request for a CDMA deployment.

DM Note Make sure to configure the RADIUS server as a DAE Server target in the
dae-service.xml file, which is located in /WideSpan/config/provserver
directory. Also, make sure to enable DAE on all PDSNs modeled in the
Service Manager.

Request
<request version="2.0" principal="root" credentials="root">
<target name="DAEAPI" operation="sendDisconnect">
<parameter>
<cdma-hotlining>
<subscriber-name>login-name@domain</subscriber-name>
</cdma-hotlining>
</parameter>
</target>
</request>

Send a synchronous Set the value of the <send-asynchronously> element to “false” to process the
CDMA-based DM disconnect request and include the processing results in the response.
By default, the value of <send-asynchronously> is set to “true”, which only validates
the <subscriber-name> value and does not include the processing results in the
response.
Note Make sure to configure the RADIUS server as a DAE Server target in the
dae-service.xml file, which is located in /WideSpan/config/provserver
directory. Also, make sure to enable DAE on all PDSNs modeled in the
Service Manager.

Request
<request version="2.0" principal="root" credentials="root">
<target name="DAEAPI" operation="sendDisconnect">
<parameter>
<cdma-hotlining>
<subscriber-name>login-name@domain</subscriber-name>
<send-asynchronously>false</send-asynchronously>
</cdma-hotlining>
</parameter>
</target>
</request>

Response for a successful operation

<response version="2.0">
<target name="DAEAPI" operation="sendDisconnect">
<result>
<cdma-hotlining>

Page 90 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<subscriber-name>1123456666@aptg.com.tw</subscriber-name>
<send-ha-info>false</send-ha-info>
<send-pdsn-info>true</send-pdsn-info>
<send-asynchronously>false</send-asynchronously>
<pdsn-node>
<sent>true</sent>
<user-identifier>1123456666</user-identifier>
<rms-cluster-id>0</rms-cluster-id>
</pdsn-node>
</cdma-hotlining>
</result>
</target>
</response>

Response for an unsuccessful operation

<response version="2.0">
<target name="DAEAPI" operation="sendDisconnect">
<result>
<cdma-hotlining>
<subscriber-name>1123456666@aptg.com.tw</subscriber-name>
<send-ha-info>false</send-ha-info>
<send-pdsn-info>true</send-pdsn-info>
<send-asynchronously>false</send-asynchronously>
<pdsn-node>
<sent>false</sent>
<user-identifier>1123456666</user-identifier>
<rms-cluster-id>0</rms-cluster-id>
<error>
<id>DAE-00409</id>
<message>DAE-00409 Unknown `PDSN` Target -- Unable to
get node information for IP Address `192.168.180.12`.
</message>
</error>
</pdsn-node>
</cdma-hotlining>
</result>
</target>
</response>

DomainAPI operations
This section describes the following DomainAPI operations:
• createDomain

Service Controller 9.6.1-AAA October 26, 2012 Page 91

Chapter 4 Provisioning APIs Provisioning API Guide

• createDomainProfileSet
• getDomain
• getDomainProfileSet
• updateDomain
• updateDomainProfileSet

createDomain
Use the createDomain operation to create a domain.
These elements are required:
• the domain name, which must be unique within the system (1 to 80 characters)
• the organization that owns this domain (must already be present)
• a domain profile set (must already be present)
These elements are optional:
• domain context (D) profile attributes
• one or more aliases for the domain

Provisioned RADIUS This example shows how to create a domain with provisioned domain context
connection service RADIUS connection service profile attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="DomainAPI" operation="createDomain">
<parameter>
<domain>
<name>bws.com</name>
<owning-organization>
<id>4</id>
</owning-organization>
<profile-set>
<id>5</id>
<profile>
<id>5</id>
<attribute name="name1">
<value segment="segment">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
</profile>
</profile-set>
</domain>

Page 92 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="DomainAPI" operation="createDomain">
<result/>
</target>
</response>

createDomainProfileSet
Use the createDomainProfileSet operation to create a domain profile set.
These elements are required:
• the profile set name
• the organization in which the profile set is to be created (must already be
present)
These elements are optional:
• a description of the profile set
• an inheritance flag to determine whether the profile set is available to
sub-organizations (default is yes)
• domain group context (DG) profile attributes

Create RADIUS This example shows how to create domain group context RADIUS connection
connection service service profile attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="DomainAPI" operation="createDomainProfileSet">
<parameter>
<domain-profile-set>
<name>BWS Domain Profile Set</name>
<organization><id>4</id></organization>
<profile>
<id>5</id>
<attribute name="name1">
<value segment="segment">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
</profile>

Service Controller 9.6.1-AAA October 26, 2012 Page 93

Chapter 4 Provisioning APIs Provisioning API Guide

</domain-profile-set>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="DomainAPI" operation="createDomainProfileSet">
<result/>
</target>
</response>

getDomain
Use the getDomain operation used to retrieve domain information and, optionally,
domain context (D) profile attributes.
These elements are required:
• the domain name or ID
These elements are optional:
• an empty <profile-set> element to be populated with retrieved profile
information. All account profiles and attributes are returned. For example:
<profile-set></profile-set>
• the profile ID or qualified name that identifies a specific profile for which
attribution information is requested. Only information for that profile is returned.
For example:
<profile-set><profile><id>2</id></profile><profile-set>
• an empty <alias> element to be populated with retrieved alias information. All of
the aliases for the domain are returned.

Get RADIUS This example shows how to get domain context RADIUS connection service profile
connection service attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="DomainAPI" operation="getDomain">
<parameter>
<domain>
<id>5</id>
<profile-set>
</profile-set>
</domain>
</parameter>
</target>

Page 94 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</request>

Response
<response version="2.0">
<target name="DomainAPI" operation="getDomain">
<result>
<id>5</id>
<name>bws.com</name>
<status>active</status>
<profile-set>
<profile>
<id>6</id>
<name>RadiusQoSConnectionService</name>
<service>
<name>RadiusQoSConnectionService</name>
<version>1</version>
</service>
<attribute name="name1">
<value segment="segment">value1</value>
</attribute>
</profile>
</profile-set>
</result>
</target>
</response>

getDomainProfileSet
Use the getDomainProfileSet operation to retrieve domain profile set information
and, optionally, domain group context (DG) profile attributes.
These elements are required:
• the profile set qualified name or ID
These elements are optional:
• an empty <profile-set> element to be populated with domain group context
(DG) RADIUS connection services profile information. All user profiles and
attributes are returned. For example:
<profile></profile>
• a <profile-set> element with the profile ID or qualified name that identifies a
specific profile for which RADIUS connection services attribution information is
requested. Only information for that profile is returned. For example:
<profile><id>2</id></profile>

Service Controller 9.6.1-AAA October 26, 2012 Page 95

Chapter 4 Provisioning APIs Provisioning API Guide

Get RADIUS This example shows how to get the domain group context RADIUS connection
connection service service profile attributes.
profile attributes
Request
<request version="2.0" principal="user" credentials="password">
<target name="DomainAPI" operation="getDomainProfileSet ">
<parameter>
<domain-profile-set>
<id>5</id>
<profile>
</profile>
<domain-profile-set>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="DomainAPI" operation="getDomainProfileSet">
<result>
<domain-profile-set>
<name>BWS Domain Profile Set</name>
<organization><id>4</id></organization>
<profile>
<id>5</id>
<name>RadiusQoSConnectionService</name>
<service>
<name>RadiusQoSConnectionService</name>
<version>1</version>
</service>
<attribute name="name1">
<value segment="segment">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
</profile>
</domain-profile-set>
</result>
</target>
</response>

Page 96 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

updateDomain
Use the updateDomain operation to modify a domain.
These elements are required:
• the domain name or ID
These elements are optional:
• a domain profile set, to which this profile should be added or deleted
• domain context (D) profile attributes to be added, modified, or deleted from the
domain profile
• a new domain status (active, suspended, deleted)
• one or more aliases, to be added or updated

Add or update This example shows how to add or update domain context RADIUS connection
RADIUS connection service profile attributes.
service profile
attributes Request
<request version="2.0" principal="User1" credentials="password">
<target name="DomainAPI" operation="updateDomain">
<parameter>
<domain>
<id>5</id>
<profile-set>
<id>5</id>
<profile>
<id>5</id>
<attribute name="name1">
<value segment="segment">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
</profile>
</profile-set>
</domain>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="DomainAPI" operation="updateDomain">
<result/>
</target>

Service Controller 9.6.1-AAA October 26, 2012 Page 97

Chapter 4 Provisioning APIs Provisioning API Guide

</response>

Delete RADIUS This example shows how to delete domain context RADIUS connection service
connection service profile attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="DomainAPI" operation="updateDomain">
<parameter>
<domain>
<id>5</id>
<profile-set>
<id>5</id>
<profile>
<id>5</id>
<attribute name="name1" delete="true">
<value segment="segment">value1</value>
</attribute>
</profile>
</profile-set>
</domain>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="DomainAPI" operation="updateDomain">
<result/>
</target>
</response>

updateDomainProfileSet
Use the updateDomainProfileSet operation to modify a domain profile set.
These elements are required:
• the profile set ID or qualified name
These elements are optional:
• a new profile set description
• a new profile set inheritance flag setting
• a new profile set status (active or deleted)
• a profile to be added to, modified, or deleted from the profile set

Page 98 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

• domain group context (DG) profile attributes to be added to, modified, or

deleted from an account profile

Update RADIUS This example shows how to update the domain group context RADIUS connection
connection service service profile attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="DomainAPI" operation="updateDomainProfileSet">
<parameter>
<domain-profile-set>
<id>15</id>
<profile>
<id>5</id>
<attribute name="name1">
<value segment="segment">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
</profile>
</domain-profile-set>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="DomainAPI" operation="updateDomainProfileSet">
<result/>
</target>
</response>

Delete RADIUS This example shows how to delete the domain group context RADIUS connection
connection service service profile attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="DomainAPI" operation="updateDomainProfileSet">
<parameter>
<domain-profile-set>
<id>15</id>
<profile>
<id>5</id>

Service Controller 9.6.1-AAA October 26, 2012 Page 99

Chapter 4 Provisioning APIs Provisioning API Guide

<attribute name="name1" delete="true">

<value segment="segment">value1</value>
</attribute>
</profile>
</domain-profile-set>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="DomainAPI" operation="updateDomainProfileSet">
<result/>
</target>
</response>

Page 100 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

HotlineAPI operations
Use the following HotlineAPI operations to create, delete, and update a user:
• createUser
• deleteUser
• deleteAccount
• updateUser
You can also get metrics for CoA and/or DM messages using the following
operations:
• getCoAMetrics
• getDMMetrics
• getCoADMMetrics
• clearCoADMFailureMetrics

createUser
Use the createUser operation to create a user with a hotlineReason, and when the
user is created, to trigger a sendCoA API. For details about the sendCoA API, see
"sendCoA" on page 84.
createUser includes an optional operation attribute which you can use to specify the
hotlineReason. The operation attribute can have one of the following values:
• bitmaskSet:
– changes the hotlineReason attribute by changing specified bits to a value
of “1”.
– accepts a string of “0” and “1” values. For example:
hotlineReason=00000001
<value operation=”bitmaskSet”>00000010</value>
new hotlineReason=00000011
• bitmaskClear:
– changes the hotlineReason attribute by changing specified bits to a value
of “0”.
– accepts a string of “0” and “1” values.For example:
hotlineReason=00000011
<value operation=”bitmaskClear”>00000010</value>
new hotlineReason=00000001
Note The Provisioning Server applies bitmaskSet and bitmaskClear operations
from right to left when updating the hotlineReason.
Note If the bitmaskSet or bitmaskClear value is longer than the hotlineReason
being modified, the Provisioning Server ignores the bitmask for the extra
bits.

Create a WiMAX user This examples create a user with a hotlineReason and trigger the sendCoA.

Service Controller 9.6.1-AAA October 26, 2012 Page 101

Chapter 4 Provisioning APIs Provisioning API Guide

Request to create a user with a hotlineReason using bitmaskSet

<request version="2.0" principal="user" credentials="password">
<target name="HotlineAPI" operation="createUser">
<parameter>
<user>
<login-name>001122AABBCC</login-name>
<password>1234567</password>
<domain>
<name>NAME.net</name>
</domain>
<organization>2</organization>
<profile-set>
<qualified-name>NAME.net</qualified-name>
<profile>
<qualified-name>Wimax71</qualified-name>
<attribute name="#ActiveStateFlag">
<value>ON</value>
</attribute>
</profile>
</profile-set>
<user-attributes>
<user-attribute name="hotlineReason" type="string">
<value operation="bitmaskSet">0000000000001000</value>
</user-attribute>
</user-attributes>
</user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="HotlineAPI" operation="createUser">
<result/>
</target>
</response>

Request to create a user with a hotlineReason using bitmaskClear

<request version="2.0" principal="user" credentials="password">
<target name="HotlineAPI" operation="createUser">
<parameter>
<user>
<login-name>001122AABBCC</login-name>

Page 102 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<password>1234567</password>
<domain>
<name>NAME.net</name>
</domain>
<organization>2</organization>
<profile-set>
<qualified-name>NAME.net</qualified-name>
<profile>
<qualified-name>Wimax71</qualified-name>
<attribute name="#ActiveStateFlag">
<value>ON</value>
</attribute>
</profile>
</profile-set>
<user-attributes>
<user-attribute name="hotlineReason" type="string">
<value operation="bitmaskClear">0000000000001000
</value>
</user-attribute>
</user-attributes>
</user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="HotlineAPI" operation="createUser">
<result/>
</target>
</response>

deleteUser
Use the deleteUser operation to delete a user from the Profile Database, and
optionally to send a CoA or DM message for the user. For information about the
sendCoA API, see "sendCoA" on page 84. For information about the
sendDisconnect API, see "sendDisconnect" on page 87.
The CoA and DM message are specified using the following elements:
• send-coa: when set to true a CoA message is sent for the deleted user. The
default is false.
• send-disconnect: when set to true a DM message is sent for the deleted user.
The default is false

Service Controller 9.6.1-AAA October 26, 2012 Page 103

Chapter 4 Provisioning APIs Provisioning API Guide

Provisioning Server configuration for CoA/DM:

• specify RADIUS attributes to include in the Disconnect message. Specify the
attributes in the dae-service.xml file and in the deleteUser message.
Note If attributes are specified in dae-service.xml and in the deleteUser
message, the values specified in the deleteUser message override the
values specified in dae-service.xml.
• configure the Provisioning Server to wait before sending a Disconnect message
after the deleteUser operation completes. Configure the
dm-delay-after-delete-user element in dae-service.xml.

Delete a user This example requests to delete a user. A CoA or DM message is not triggered
because send-coa and send-disconnect are both set to false.

Request
<request version="2.0" principal="user" credentials="password">
<target name="HotlineAPI" operation="deleteUser">
<parameter>
<hotline-user>
<login-name>111111111111</login-name>
<domain>
<name>testdomain</name>
</domain>
<send-coa>false</send-coa>
<send-disconnect>false</send-disconnect>
</hotline-user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="HotlineAPI" operation="deleteUser">
<result/>
</target>
</response>

Page 104 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Delete a user and This example requests to delete a user and trigger a DM message, which includes
specify RADIUS the specified RADIUS attributes.
attributes
Request
<request version="2.0" principal="user" credentials="password">
<target name="HotlineAPI" operation="deleteUser">
<parameter>
<hotline-user>
<login-name>111111111111</login-name>
<domain>
<name>testdomain</name>
</domain>
<send-coa>true</send-coa>
<send-disconnect>true</send-disconnect>
<radius-attribute-list>
<attribute name="Filter-Id">
<value>000000000003</value>
</attribute>
</radius-attribute-list>
</hotline-user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="HotlineAPI" operation="deleteUser">
<result/>
</target>
</response>

deleteAccount
Use the deleteAccount operation to delete an account from the Profile Database,
and optionally to send a CoA or DM message for users associated with the account.
For information about the sendCoA API, see "sendCoA" on page 84. For
information about the sendDisconnect API, see "sendDisconnect" on page 87.
Also specify RADIUS attributes to include in the Disconnect message. Specify the
attributes in the dae-service.xml file and in the deleteAccount message.
Note If attributes are specified in dae-service.xml and in the deleteAccount
message, the values specified in the deleteAccount message override the
values specified in dae-service.xml.
The CoA and DM message are specified using the following elements:

Service Controller 9.6.1-AAA October 26, 2012 Page 105

Chapter 4 Provisioning APIs Provisioning API Guide

• send-coa: when set to true a CoA message is sent for users associated with the
deleted account. The default is false.
• send-disconnect: when set to true a DM message is sent for users associated
with the deleted account. The default is false.

Delete an account This example requests to delete an account. A CoA or DM message is not triggered
because send-coa and send-disconnect are both set to false.

Request
<request version="2.0" principal="user" credentials="password">
<target name="HotlineAPI" operation="deleteAccount">
<parameter>
<hotline-account>
<name>account1</name>
<send-coa>false</send-coa>
<send-disconnect>false</send-disconnect>
</hotline-account>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="HotlineAPI" operation="deleteAccount">
<result/>
</target>
</response>

Delete an account This example requests to delete an account and trigger a DM message, which
and specify RADIUS includes the specified RADIUS attributes.
attributes
Request
<request version="2.0" principal="user" credentials="password">
<target name="HotlineAPI" operation="deleteAccount">
<parameter>
<hotline-account>
<name>account1</name>
<send-coa>true</send-coa>
<send-disconnect>true</send-disconnect>
<radius-attribute-list>
<attribute name="Filter-Id">
<value>000000000003</value>
</attribute>
</radius-attribute-list>

Page 106 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</hotline-account>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="HotlineAPI" operation="deleteAccount">
<result/>
</target>
</response>

updateUser
Use the updateUser operation to update a hotlineReason, and when the
hotlineReason is updated, to trigger a CoA and/or DM. For details about the
sendCoA and sendDisconnect APIs, see "sendCoA" on page 84, and
"sendDisconnect" on page 87.

Sending COA/DM messages

Use the optional send-coa and send-disconnect elements (set to true), to send a
CoA and/or DM.
Note By default the updateUser operation triggers a CoA.

Updating hotlineReason
updateUser includes an optional operation attribute used to modify the
hotlineReason. The operation attribute can have one of the following values:
• bitmaskSet:
– changes the hotlineReason attribute by changing specified bits to a value
of “1”.
– accepts a string of “0” and “1” values. For example:
hotlineReason=00000001
<value operation=”bitmaskSet”>00000010</value>
new hotlineReason=00000011
• bitmaskClear:
– changes the hotlineReason attribute by changing specified bits to a value
of “0”.

Service Controller 9.6.1-AAA October 26, 2012 Page 107

Chapter 4 Provisioning APIs Provisioning API Guide

– accepts a string of “0” and “1” values.For example:

hotlineReason=00000011
<value operation=”bitmaskClear”>00000010</value>
new hotlineReason=00000001
Note The Provisioning Server applies bitmaskSet and bitmaskClear operations
from right to left when updating the hotlineReason.
Note If the bitmaskSet or bitmaskClear value is longer than the hotlineReason
being modified, the Provisioning Server ignores the bitmask for the extra
bits.

Update WiMAX user The first two examples update the hotlineReason to update a specified bit and
attribute trigger the sendCoA.
The third example updates the hotlineReason and is configured to send a CoA and
DM.

Request to update a specified bit in the hotlineReason

<request version="2.0" principal="user" credentials="password">
<target name="HotlineAPI" operation="updateUser">
<parameter>
<hotline-user>
<login-name>001122AABBCC</login-name>
<domain>
<name>NAME.net</name>
</domain>
<profile-set>
<qualified-name>NAME.net</qualified-name>
<profile>
<qualified-name>Wimax71</qualified-name>
<attribute name="#ActiveStateFlag">
<value>ON</value>
</attribute>
</profile>
</profile-set>
<user-attributes>
<user-attribute name="hotlineReason" type="string">
<value operation="bitmaskSet">0000000000001000</value>
</user-attribute>
</user-attributes>
</hotline-user>
</parameter>
</target>
</request>

Page 108 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Response
<response version="2.0">
<target name="HotlineAPI" operation="updateUser">
<result/>
</target>
</response>
This example updates the hotlineReason to clear a specified bit and triggers the
sendCoA.

Request to clear a specified bit in the hotlineReason

<request version="2.0" principal="user" credentials="password">
<target name="HotlineAPI" operation="updateUser">
<parameter>
<hotline-user>
<login-name>001122AABBCC</login-name>
<domain>
<name>NAME.net</name>
</domain>
<profile-set>
<qualified-name>NAME.net</qualified-name>
<profile>
<qualified-name>Wimax71</qualified-name>
<attribute name="#ActiveStateFlag">
<value>ON</value>
</attribute>
</profile>
</profile-set>
<user-attributes>
<user-attribute name="hotlineReason" type="string">
<value operation="bitmaskClear">0000000000001000
</value>
</user-attribute>
</user-attributes>
</hotline-user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="HotlineAPI" operation="updateUser">
<result/>
</target>

Service Controller 9.6.1-AAA October 26, 2012 Page 109

Chapter 4 Provisioning APIs Provisioning API Guide

</response>

Request to update a bit in the hotlineReason and send a CoA and DM:
<request version="2.0" principal="APIUSER" credentials="APIPASSWORD">
<target name="HotlineAPI" operation="updateUser">
<parameter>
<hotline-user>
<login-name>001122AABBCC</login-name>
<domain>
<name>NAME.net</name>
</domain>
<profile-set>
<qualified-name>NAME.net</qualified-name>
<profile>
<qualified-name>Wimax71</qualified-name>
<attribute name="#ActiveStateFlag">
<value>ON</value>
</attribute>
</profile>
<profile>
<qualified-name>Wimax70</qualified-name>
<attribute delete="true" name="#ActiveStateFlag"/>
</profile>
</profile-set>
<user-attributes>
<user-attribute name="hotlineReason" type="string">
<value operation="bitmaskSet">0000000000010000
</value>
</user-attribute>
</user-attributes>
<send-coa>true</send-coa>
<send-disconnect>true</send-disconnect>
</hotline-user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="HotlineAPI" operation="updateUser">
<result/>
</target>
</response>

Page 110 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

getCoAMetrics
Use the getCoAMetrics operation to track the number of queued and failed CoA
messages for HotlineAPI operations where the CoA occurs after the operation
completes.
Use getCoAMetrics to track CoA metrics for the following HotlineAPI operations:
• createUser
• updateUser
• deleteUser

Get CoA metrics This example requests to retrieve the number of queued and failed CoA requests.

Request
<request version="2.0" principal="admin" credentials="password">
<target name="HotlineAPI" operation="getCoAMetrics">
</target>
</request>

Response
<response version="2.0">
<target name="HotlineAPI" operation="getCoAMetrics">
<result class="com.bridgewatersystems.dae.entity.HotlineCoaMetrics">
<hotline-coa-metrics>
<queued-coa>0</queued-coa>
<failed-coa>0</failed-coa>
</hotline-coa-metrics>
</result>
</target>
</response>

getDMMetrics
Use the getDMMetrics operation to track the number of queued and failed DM
messages for HotlineAPI operations where the DM occurs after the operation
completes.
Use getDMMetrics to track DM metrics for the following HotlineAPI operations:
• createUser
• updateUser
• deleteUser

Get DM metrics This example requests to retrieve the number of queued and failed DM requests.

Service Controller 9.6.1-AAA October 26, 2012 Page 111

Chapter 4 Provisioning APIs Provisioning API Guide

Request
<request version="2.0" principal="admin" credentials="password">
<target name="HotlineAPI" operation="getDMMetrics">
</target>
</request>

Response
<response version="2.0">
<target name="HotlineAPI" operation="getDMMetrics">
<result class="com.bridgewatersystems.dae.entity.HotlineDmMetrics">
<hotline-dm-metrics>
<queued-dm>1</queued-dm>
<failed-dm>1</failed-dm>
</hotline-dm-metrics>
</result>
</target>
</response>

getCoADMMetrics
Use the getCoADMMetrics operation to track the number of queued and failed CoA
and DM messages for HotlineAPI operations where the CoA and/or DM occur after
the operation completes.
Use getCoADMMetrics to track CoA and DM metrics for the following HotlineAPI
operations:
• createUser
• updateUser
• deleteUser

Get CoA and DM This example requests to retrieve the number of queued and failed CoA and DM
metrics requests.

Request
<request version="2.0" principal="admin" credentials="password">
<target name="HotlineAPI" operation="getCoADMMetrics">
</target>
</request>

Response
<response version="2.0">
<target name="HotlineAPI" operation="getCoADMMetrics">
<result class="com.bridgewatersystems.dae.entity.HotlineCoaDmMetrics">
<hotline-coa-dm-metrics>

Page 112 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<queued-coa>0</queued-coa>
<failed-coa>0</failed-coa>
<queued-dm>1</queued-dm>
<failed-dm>1</failed-dm>
</hotline-coa-dm-metrics>
</result>
</target>
</response>

clearCoADMFailureMetrics
Use the clearCoADMFailureMetrics operation to clear CoA and DM metrics for the
following HotlineAPI operations:
• createUser
• updateUser
• deleteUser

Clear CoA and DM This example requests to clear the metrics for CoA and DM requests.
metrics
Request
<request version="2.0" principal="admin" credentials="password">
<target name="HotlineAPI" operation="clearCoADMFailureMetrics">
</target>
</request>

Response
<response version="2.0">
<target name="HotlineAPI" operation="clearCoADMFailureMetrics">
<result />
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 113

Chapter 4 Provisioning APIs Provisioning API Guide

NetworkAPI operations
This section describes the following NetworkAPI operations:
• createDHCPServer
• findDPI
• createDPI
• createIPAddressPool
• createNetwork
• deleteDHCPServer
• deleteDPI
• deleteIPAddressPool
• deleteNetwork
• getDHCPServer
• getDPI
• getIPAddressPool
• getNetwork
• updateDPI
• updateIPAddressPool
• updateNetwork

createDHCPServer

Specified name and This example shows how to create a DHCP Server with a specified name and
description description.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="createDHCPServer">
<parameter>
<dhcp-server>
<name>P301_TestDHCPServer1</name>
<description>
P301_TestDHCPServerdescription 1
</description>
</dhcp-server>
</parameter>
</target>
</request>

Response
<response version="2.0">

Page 114 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<target name="NetworkAPI" operation="createDHCPServer">

<result>
<string>303415</string>
</result>
</target>
</response>
The number contained within the <string></string> tags is the ID of the created
object.

findDPI

Specified login name This example shows how to find information about a DPI with a specified login
name. All records that match the specified login name arereturned.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="findDPI">
<parameter>
<dpi-search>
<user>
<login-name>00:20:40:dc:80:03</login-name>
</user>
<rms-cluster-id>1</rms-cluster-id>
</dpi-search>
</parameter>
</target>
</request>

Specified MAC This example shows how to find information about a DPI with a MAC address. You
address can search by MAC address or by user name in the form of a MAC address.
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="findDPI">
<parameter>
<dpi-search>
<mac-address>00:20:40:dc:80:03</mac-address>
<rms-cluster-id>1</rms-cluster-id>
</dpi-search>
</parameter>
</target>
</request>

Service Controller 9.6.1-AAA October 26, 2012 Page 115

Chapter 4 Provisioning APIs Provisioning API Guide

The rms-cluster-id element is optional. If it is not provided, all RMS clusters are
queried to perform MAC Address to IP Address translation.

Response
<response version="2.0">
<target name="NetworkAPI" operation="findDPI">
<result>
<dpi>
<id>1545</id>
<configuration-id>1</configuration-id>
<name>test_DPI</name>
<hostname>dpiHost</hostname>
<port>7890</port>
<timeout>50</timeout>
<login-name>dpiLogin</login-name>
<password>dpiPasswd</password>
</dpi>
</result>
</target>
</response>

createDPI

Specified name and This example shows how to create a DPI with a specified name and description.
description The request does not include DPI attributes or IP Address Pools.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="createDPI">
<parameter>
<dpi>
<name>DPI Name</name>
<description>DPI Description</description>
</dpi>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="createDPI">
<result>

Page 116 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<string>303418</string>
</result>
</target>
</response>
The number contained within the <string></string> tags is the ID of the created
object.

IP Address Pools This example shows how to create a DPI using IP Address Pools. The request
includes no DPI attributes but includes some IP Address Pools. The IP Address
Pools are created by the system if they are not present since
create-ip-address-pools="true" is provided.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="createDPI">
<parameter>
<dpi create-ip-address-pools="true">
<name>DPI Name</name>
<description>DPI Description</description>
<ip-address-pool>
<qualified-name>
IP Pool Name 1
</qualified-name>
</ip-address-pool>
<ip-address-pool>
<qualified-name>
IP Pool Name 2
</qualified-name>
</ip-address-pool>
</dpi>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="createDPI">
<result>
<string>303419</string>
</result>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 117

Chapter 4 Provisioning APIs Provisioning API Guide

The number contained within the <string></string> tags is the ID of the created
object.

IP Address Pools and This example shows how to create a DPI using IP Address Pools and DPI
DPI attributes attributes. The IP Address Pools are created by the system if they are not present
since create-ip-address-pools="true" is provided.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="createDPI">
<parameter>
<dpi create-ip-address-pools="true">
<name>DPI Name</name>
<description>DPI Description</description>
<attribute name="Attribute1">
<value segment="segment">value1</value>
</attribute>
<attribute name="Another Attribute">
<value>Another Value</value>
</attribute>
<ip-address-pool>
<qualified-name>
IP Pool Name 1
</qualified-name>
</ip-address-pool>
<ip-address-pool>
<qualified-name>
IP Pool Name 2
</qualified-name>
</ip-address-pool>
</dpi>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="createDPI">
<result>
<string>303422</string>
</result>
</target>
</response>

Page 118 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

The number contained within the <string></string> tags is the ID of the created
object.

createIPAddressPool

Specified name and This example shows how to create an IP Address Pool.
description
Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="createIPAddressPool">
<parameter>
<ip-address-pool>
<name>IP Pool Name</name>
<description>IP Pool Description</description>
</ip-address-pool>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="createIPAddressPool">
<result>
<string>303417</string>
</result>
</target>
</response>
The number contained within the <string></string> tags is the ID of the created
object.

createNetwork

Network with This example shows how to create a network with subnets. Four subnets are
subnets specified by using number-of-subnets="4". An IP Address Pool is also specified.
The IP Address Pool is created by the system if it is not present since
create-ip-address-pools="true". DHCP options are defined.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="createNetwork">
<parameter>

Service Controller 9.6.1-AAA October 26, 2012 Page 119

Chapter 4 Provisioning APIs Provisioning API Guide

<network create-ip-address-pools="true"
number-of-subnets="4">
<name>P301_TestNet</name>
<public>true</public>
<starting-address>192.167.1.0</starting-address>
<network-mask>255.255.255.0</network-mask>
<rms-cluster-id>10</rms-cluster-id>
<ip-address-pool>
<qualified-name>IP Pool 1</qualified-name>
</ip-address-pool>
<dhcp-option name="option1">
<value>1.1.1.1</value>
</dhcp-option>
<dhcp-option name="option2">
<value>2.2.2.1</value>
<value>2.2.2.2</value>
</dhcp-option>
</network>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="createNetwork">
<result>
<string>303426</string>
</result>
</target>
</response>
The number contained within the <string></string> tags is the ID of the created
object.

IP Address Pools for This example shows how to create IP Address Pools for a subnet. Subnets are
subnets created based on the supplied subnet with the template="true" attribute. The
template subnet specifies an IP Address Pool which is created by the system if it is
not present (create-ip-address-pools="true"). The template subnet specifies four IP
Address ranges. The DHCP Server used by the dynamic address range is created
by the system if it is not present (create-ip-address-pools="true"). DHCP options
are defined for the subnet and network.

Request
<request version="2.0" principal="User1"
credentials="password">

Page 120 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<target name="NetworkAPI" operation="createNetwork">

<parameter>
<network>
<name>P301_TestNet_existing</name>
<public>false</public>
<starting-address>192.168.1.0</starting-address>
<network-mask>255.255.255.0</network-mask>
<rms-cluster-id>10</rms-cluster-id>
<dhcp-option name="option1">
<value>1.1.1.1</value>
</dhcp-option>
<dhcp-option name="option2">
<value>2.2.2.1</value>
<value>2.2.2.2</value>
</dhcp-option>
<subnet create-dhcp-servers="true"
create-ip-address-pools="true"
template="true">
<starting-address>192.168.1.0
</starting-address>
<subnet-mask>255.255.255.128</subnet-mask>
<rms-cluster-id>20</rms-cluster-id>
<ip-address-pool>
<qualified-name>
IPAddressPool1
</qualified-name>
</ip-address-pool>
<dhcp-option name="option1">
<value>3.3.3.3</value>
</dhcp-option>
<dhcp-option name="option2">
<value>2.2.2.1</value>
<value>2.2.2.2</value>
</dhcp-option>
<ip-address-range>
<start-ip>192.168.1.0</start-ip>
<end-ip>192.168.1.28</end-ip>
<range-type>RESERVED</range-type>
</ip-address-range>
<ip-address-range>
<start-ip>192.168.1.29</start-ip>
<end-ip>192.168.1.57</end-ip>
<range-type>STATIC</range-type>

Service Controller 9.6.1-AAA October 26, 2012 Page 121

Chapter 4 Provisioning APIs Provisioning API Guide

</ip-address-range>
<ip-address-range>
<start-ip>192.168.1.58</start-ip>
<end-ip>192.168.1.86</end-ip>
<range-type>DYNAMIC</range-type>
<dhcp-server>
<qualified-name>
DHCPServer1
</qualified-name>
</dhcp-server>
</ip-address-range>
<ip-address-range>
<start-ip>192.168.1.87</start-ip>
<end-ip>192.168.1.115</end-ip>
<range-type>RESERVED</range-type>
</ip-address-range>
</subnet>
</network>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="createNetwork">
<result>
<string>303437</string>
</result>
</target>
</response>
The number contained within the <string></string> tags is the ID of the created
object.

Two subnets This example shows how to create a network with two subnets. Subnets are
individually defined. The subnet specifies an IP Address Pool. The IP Address Pool
is created by the system if it is not present (create-ip-address-pools="true"). The
subnet specifies four IP Address ranges. The DHCP Server used by the dynamic
address range is created by the system if it is not present
(create-ip-address-pools="true"). DHCP options are defined for the subnet.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="createNetwork">

Page 122 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<parameter>
<network>
<name>Network name</name>
<public>false</public>
<starting-address>192.168.1.0</starting-address>
<network-mask>255.255.255.0</network-mask>
<rms-cluster-id>10</rms-cluster-id>
<subnet create-dhcp-servers="true"
create-ip-address-pools="true">
<starting-address>
192.168.1.0
</starting-address>
<subnet-mask>255.255.255.128</subnet-mask>
<rms-cluster-id>20</rms-cluster-id>
<ip-address-pool>
<qualified-name>
IPAddressPool1
</qualified-name>
</ip-address-pool>
<dhcp-option name="option1">
<value>3.3.3.3</value>
</dhcp-option>
<dhcp-option name="option2">
<value>2.2.2.1</value>
<value>2.2.2.2</value>
</dhcp-option>
<ip-address-range>
<start-ip>192.168.1.0</start-ip>
<end-ip>192.168.1.31</end-ip>
<range-type>RESERVED</range-type>
</ip-address-range>
<ip-address-range>
<start-ip>192.168.1.32</start-ip>
<end-ip>192.168.1.63</end-ip>
<range-type>STATIC</range-type>
</ip-address-range>
<ip-address-range>
<start-ip>192.168.1.64</start-ip>
<end-ip>192.168.1.95</end-ip>
<range-type>DYNAMIC</range-type>
<dhcp-server>
<qualified-name>
DHCPServer1

Service Controller 9.6.1-AAA October 26, 2012 Page 123

Chapter 4 Provisioning APIs Provisioning API Guide

</qualified-name>
</dhcp-server>
</ip-address-range>
<ip-address-range>
<start-ip>192.168.1.96</start-ip>
<end-ip>192.168.1.127</end-ip>
<range-type>RESERVED</range-type>
</ip-address-range>
</subnet>
<subnet create-dhcp-servers="true"
create-ip-address-pools="true">
<starting-address>
192.168.1.128
</starting-address>
<subnet-mask>255.255.255.128</subnet-mask>
<rms-cluster-id>20</rms-cluster-id>
<ip-address-pool>
<qualified-name>
IPAddressPool1
</qualified-name>
</ip-address-pool>
<dhcp-option name="option1">
<value>3.3.3.3</value>
</dhcp-option>
<dhcp-option name="option2">
<value>2.2.2.1</value>
<value>2.2.2.2</value>
</dhcp-option>
<ip-address-range>
<start-ip>192.168.1.128</start-ip>
<end-ip>192.168.1.159</end-ip>
<range-type>RESERVED</range-type>
</ip-address-range>
<ip-address-range>
<start-ip>192.168.1.160</start-ip>
<end-ip>192.168.1.191</end-ip>
<range-type>STATIC</range-type>
</ip-address-range>
<ip-address-range>
<start-ip>192.168.1.192</start-ip>
<end-ip>192.168.1.223</end-ip>
<range-type>DYNAMIC</range-type>
<dhcp-server>

Page 124 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<qualified-name>
DHCPServer1
</qualified-name>
</dhcp-server>
</ip-address-range>
<ip-address-range>
<start-ip>192.168.1.224</start-ip>
<end-ip>192.168.1.255</end-ip>
<range-type>RESERVED</range-type>
</ip-address-range>
</subnet>
</network>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="createNetwork">
<result>
<string>303445</string>
</result>
</target>
</response>
The number contained within the <string></string> tags is the ID of the created
object.

deleteDHCPServer

Specified name This example shows how to delete a DHCP Server by specifying its name.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="deleteDHCPServer">
<parameter>
<dhcp-server>
<qualified-name>P301_TestDHCPServer2
</qualified-name>
</dhcp-server>
</parameter>
</target>
</request>

Service Controller 9.6.1-AAA October 26, 2012 Page 125

Chapter 4 Provisioning APIs Provisioning API Guide

Response
<response version="2.0">
<target name="NetworkAPI" operation="deleteDHCPServer">
<result/>
</target>
</response>

deleteDPI

Specified name This example shows how to delete a DPI. The DPI to delete is identified by
providing its name in the "qualified-name" element.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="deleteDPI">
<parameter>
<dpi>
<qualified-name>DPI Name2</qualified-name>
</dpi>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="deleteDPI">
<result/>
</target>
</response>

deleteIPAddressPool

Specified ID This example shows how to delete an IP Address Pool by ID.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="deleteIPAddressPool">
<parameter>
<ip-address-pool>
<id>1234</id>
</ip-address-pool>

Page 126 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="deleteIPAddressPool">
<result/>
</target>
</response>

Specified name This example shows how to delete an IP Address Pool by name.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="deleteIPAddressPool">
<parameter>
<ip-address-pool>
<qualified-name>IP Pool Name</qualified-name>
</ip-address-pool>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="deleteIPAddressPool">
<result/>
</target>
</response>

deleteNetwork

Specified name This example shows how to delete a network by name.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="deleteNetwork">
<parameter>
<network>
<qualified-name>new name</qualified-name>

Service Controller 9.6.1-AAA October 26, 2012 Page 127

Chapter 4 Provisioning APIs Provisioning API Guide

</network>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="deleteNetwork">
<result/>
</target>
</response>

getDHCPServer

Specified name This example shows how to get a DHCP Server by name.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="getDHCPServer">
<parameter>
<dhcp-server>
<qualified-name>P301_TestDHCPServer1
</qualified-name>
</dhcp-server>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="getDHCPServer">
<result>
<dhcp-server>
<id>303416</id>
<configuration-id>1</configuration-id>
<name>P301_TestDHCPServer1</name>
<description>P301_TestDHCPServerdescription 1
</description>
<last-modified>2005-12-12 11:39:49
</last-modified>
<modified-by>admin</modified-by>
</dhcp-server>

Page 128 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</result>
</target>
</response>

getDPI

Specified name This example shows how to get a DPI by name. The returned DPI includes its basic
properties only. The DPI's attributes and IP Address Pools are not included
because include-attributes="false" and include-ip-address-pools="false".

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="getDPI">
<parameter>
<dpi include-attributes="false"
include-ip-address-pools="false">
<qualified-name>DPI Name3</qualified-name>
</dpi>
</parameter>
</target>
</request>
Response
<response version="2.0">
<target name="NetworkAPI" operation="getDPI">
<result>
<dpi include-ip-address-pools="false"
include-attributes="false">
<id>303422</id>
<configuration-id>1</configuration-id>
<name>DPI Name3</name>
<caption>DPI Name3</caption>
<description>DPI Description</description>
<hostname>DPI Name3</hostname>
<last-modified>2005-12-12 12:07:57
</last-modified>
<modified-by>admin</modified-by>
</dpi>
</result>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 129

Chapter 4 Provisioning APIs Provisioning API Guide

Basic properties and This example shows how to get a DPI by name and also retrieve it’s basic
IP Address Pools properties and associated IP Address Pools. The IP Address Pools are included
because include-ip-address-pools="true".

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="getDPI">
<parameter>
<dpi include-ip-address-pools="true">
<qualified-name>DPI Name3</qualified-name>
</dpi>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="getDPI">
<result>
<dpi include-ip-address-pools="true"
include-attributes="false">
<id>303422</id>
<configuration-id>1</configuration-id>
<name>DPI Name3</name>
<caption>DPI Name3</caption>
<description>DPI Description</description>
<hostname>DPI Name3</hostname>
<last-modified>2005-12-12 12:07:57
</last-modified>
<modified-by>admin</modified-by>
<ip-address-pool>
<id>303420</id>
<configuration-id>1</configuration-id>
<name>IP Pool Name 1</name>
<last-modified>2005-12-12 12:05:02
</last-modified>
<modified-by>admin</modified-by>
</ip-address-pool>
<ip-address-pool>
<id>303421</id>
<configuration-id>1</configuration-id>
<name>IP Pool Name 2</name>

Page 130 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<last-modified>2005-12-12 12:05:02
</last-modified>
<modified-by>admin</modified-by>
</ip-address-pool>
</dpi>
</result>
</target>
</response>

Basic properties, This example shows how to get a DPI by name and also retrieve it’s basic
attributes, and IP properties, attributes, and associated IP Address Pools. The DPI's Attributes and IP
Address Pools Address Pools are included because include-attributes="true" and
include-ip-address-pools="true".

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="getDPI">
<parameter>
<dpi include-attributes="true"
include-ip-address-pools="true">
<qualified-name>DPI Name3</qualified-name>
</dpi>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="getDPI">
<result>
<dpi include-ip-address-pools="true"
include-attributes="true">
<id>303422</id>
<configuration-id>1</configuration-id>
<name>DPI Name3</name>
<caption>DPI Name3</caption>
<description>DPI Description</description>
<hostname>DPI Name3</hostname>
<last-modified>2005-12-12 12:07:57
</last-modified>
<modified-by>admin</modified-by>
<attribute name="Another Attribute">
<value id="1058947">Another Value</value>

Service Controller 9.6.1-AAA October 26, 2012 Page 131

Chapter 4 Provisioning APIs Provisioning API Guide

</attribute>
<attribute name="Attribute1">
<value id="1058946">value1</value>
</attribute>
<ip-address-pool>
<id>303420</id>
<configuration-id>1</configuration-id>
<name>IP Pool Name 1</name>
<last-modified>2005-12-12 12:05:02
</last-modified>
<modified-by>admin</modified-by>
</ip-address-pool>
<ip-address-pool>
<id>303421</id>
<configuration-id>1</configuration-id>
<name>IP Pool Name 2</name>
<last-modified>2005-12-12 12:05:02
</last-modified>
<modified-by>admin</modified-by>
</ip-address-pool>
</dpi>
</result>
</target>
</response>

getIPAddressPool

Specified name This example shows how to get an IP Address Pool.

Request
To get an IP Address Pool, send the Provisioning Server the following request:
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="getIPAddressPool">
<parameter>
<ip-address-pool>
<qualified-name>IP Pool Name</qualified-name>
</ip-address-pool>
</parameter>
</target>
</request>

Page 132 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Response
<response version="2.0">
<target name="NetworkAPI" operation="getIPAddressPool">
<result>
<ip-address-pool>
<id>303417</id>
<configuration-id>1</configuration-id>
<name>IP Pool Name</name>
<description>IP Pool Description</description>
<last-modified>2005-12-12 11:47:56
</last-modified>
<modified-by>admin</modified-by>
</ip-address-pool>
</result>
</target>
</response>

getNetwork

Basic information This example shows how to get basic information about a network. Only the basic
network information is retrieved since none of the "include-" attributes are supplied.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="getNetwork">
<parameter>
<network>
<qualified-name>Network name</qualified-name>
</network>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="getNetwork">
<result>
<network include-dhcp-servers="false"
include-ip-address-pools="false"
include-dhcp-options="false"
include-ip-address-ranges="false"
include-subnets="false">

Service Controller 9.6.1-AAA October 26, 2012 Page 133

Chapter 4 Provisioning APIs Provisioning API Guide

<id>303445</id>
<configuration-id>1</configuration-id>
<name>Network name</name>
<public>false</public>
<subnets-equal-size>true</subnets-equal-size>
<starting-address>192.168.1.0</starting-address>
<network-mask>255.255.255.0</network-mask>
<rms-cluster-id>10</rms-cluster-id>
<last-modified>2005-12-12 13:20:44
</last-modified>
<modified-by>admin</modified-by>
</network>
</result>
</target>
</response>

Full information This example shows how to get full information about a network, including all DHCP
options and Servers, IP address ranges, subnets and IP Address Pools. The
network components to include is controlled by setting the appropriate "include-"
attributes.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="getNetwork">
<parameter>
<network include-dhcp-options="true"
include-dhcp-servers="true"
include-ip-address-pools="true"
include-ip-address-ranges="true"
include-subnets="true">
<qualified-name>Network name</qualified-name>
</network>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="getNetwork">
<result>
<network include-dhcp-servers="true"
include-ip-address-pools="true"
include-dhcp-options="true"

Page 134 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

include-ip-address-ranges="true"
include-subnets="true">
<id>303445</id>
<configuration-id>1</configuration-id>
<name>Network name</name>
<public>false</public>
<subnets-equal-size>true</subnets-equal-size>
<starting-address>192.168.1.0</starting-address>
<network-mask>255.255.255.0</network-mask>
<rms-cluster-id>10</rms-cluster-id>
<last-modified>2005-12-12 13:20:44
</last-modified>
<modified-by>admin</modified-by>
<subnet>
<id>303446</id>
<configuration-id>1</configuration-id>
<caption>Subnet 0 (192.168.1.0/25)</caption>
<name>Subnet 0 (192.168.1.0/25):303446-1
</name>
<starting-address>192.168.1.0
</starting-address>
<subnet-mask>255.255.255.128</subnet-mask>
<rms-cluster-id>20</rms-cluster-id>
<subnet-boundary>25</subnet-boundary>
<last-modified>2005-12-12 13:20:44
</last-modified>
<modified-by>admin</modified-by>
<ip-address-pool>
<id>303441</id>
<configuration-id>1</configuration-id>
<name>IPAddressPool1</name>
<last-modified>2005-12-12 13:18:55
</last-modified>
<modified-by>admin</modified-by>
</ip-address-pool>
<dhcp-option name="option1">
<value id="1059007"
subscript="393216">3.3.3.3</value>
</dhcp-option>
<dhcp-option name="option2">
<value id="1059008"
subscript="393216">2.2.2.1</value>
<value id="1059009"

Service Controller 9.6.1-AAA October 26, 2012 Page 135

Chapter 4 Provisioning APIs Provisioning API Guide

subscript="393217">2.2.2.2</value>
</dhcp-option>
<ip-address-range>
<start-ip>192.168.1.0</start-ip>
<end-ip>192.168.1.31</end-ip>
<range-type>RESERVED</range-type>
</ip-address-range>
<ip-address-range>
<start-ip>192.168.1.96</start-ip>
<end-ip>192.168.1.127</end-ip>
<range-type>RESERVED</range-type>
</ip-address-range>
<ip-address-range>
<start-ip>192.168.1.32</start-ip>
<end-ip>192.168.1.63</end-ip>
<range-type>STATIC</range-type>
</ip-address-range>
<ip-address-range>
<start-ip>192.168.1.64</start-ip>
<end-ip>192.168.1.95</end-ip>
<range-type>DYNAMIC</range-type>
<dhcp-server>
<id>303439</id>
<configuration-id>1</configuration-id>
<name>DHCPServer1</name>
<last-modified>2005-12-12 13:18:55
</last-modified>
<modified-by>admin</modified-by>
</dhcp-server>
</ip-address-range>
</subnet>
<subnet>
<id>303448</id>
<configuration-id>1</configuration-id>
<caption>Subnet 1 (192.168.1.128/25)</caption>
<name>Subnet 1 (192.168.1.128/25):303448-1
</name>
<starting-address>192.168.1.128
</starting-address>
<subnet-mask>255.255.255.128</subnet-mask>
<rms-cluster-id>20</rms-cluster-id>
<subnet-boundary>25</subnet-boundary>
<last-modified>2005-12-12 13:20:44

Page 136 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</last-modified>
<modified-by>admin</modified-by>
<ip-address-pool>
<id>303441</id>
<configuration-id>1</configuration-id>
<name>IPAddressPool1</name>
<last-modified>2005-12-12 13:18:55
</last-modified>
<modified-by>admin</modified-by>
</ip-address-pool>
<dhcp-option name="option1">
<value id="1059016"
subscript="393216">3.3.3.3</value>
</dhcp-option>
<dhcp-option name="option2">
<value id="1059017"
subscript="393216">2.2.2.1</value>
<value id="1059018"
subscript="393217">2.2.2.2</value>
</dhcp-option>
<ip-address-range>
<start-ip>192.168.1.128</start-ip>
<end-ip>192.168.1.159</end-ip>
<range-type>RESERVED</range-type>
</ip-address-range>
<ip-address-range>
<start-ip>192.168.1.224</start-ip>
<end-ip>192.168.1.255</end-ip>
<range-type>RESERVED</range-type>
</ip-address-range>
<ip-address-range>
<start-ip>192.168.1.160</start-ip>
<end-ip>192.168.1.191</end-ip>
<range-type>STATIC</range-type>
</ip-address-range>
<ip-address-range>
<start-ip>192.168.1.192</start-ip>
<end-ip>192.168.1.223</end-ip>
<range-type>DYNAMIC</range-type>
<dhcp-server>
<id>303439</id>
<configuration-id>1</configuration-id>
<name>DHCPServer1</name>

Service Controller 9.6.1-AAA October 26, 2012 Page 137

Chapter 4 Provisioning APIs Provisioning API Guide

<last-modified>2005-12-12 13:18:55
</last-modified>
<modified-by>admin</modified-by>
</dhcp-server>
</ip-address-range>
</subnet>
</network>
</result>
</target>
</response>

updateDHCPServer

Name and This example shows how to update a DHCP Server name and description.
description
Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="updateDHCPServer">
<parameter>
<dhcp-server>
<qualified-name>
P301_TestDHCPServer1
</qualified-name>
<name>P301_TestDHCPServer2</name>
<description>P301_TestDHCPServerdescription 2
</description>
</dhcp-server>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="updateDHCPServer">
<result/>
</target>
</response>

updateDPI

Name and This example shows how to update a DPI name and description. The DPI to update
description is identified by providing its current name in the "qualified-name" element.

Page 138 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="updateDPI">
<parameter>
<dpi>
<qualified-name>DPI Name</qualified-name>
<name>New DPI Name</name>
<description>New DPI Description</description>
</dpi>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="updateDPI">
<result/>
</target>
</response>

Name, description, This example shows how to update a DPI name, description, and IP Address Pools.
and IP Address Pools The DPI to update is identified by providing its name in the "qualified-name"
element. "IP Pool 3" and "IP Pool 4" are added to the DPI. "IP Pool 1" is removed
from the DPI since "delete=true" is provided.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="updateDPI">
<parameter>
<dpi create-ip-address-pools="true">
<qualified-name>DPI Name2</qualified-name>
<ip-address-pool>
<qualified-name>Name of IP Pool 3
</qualified-name>
</ip-address-pool>
<ip-address-pool>
<qualified-name>Name of IP Pool 4
</qualified-name>
</ip-address-pool>
<ip-address-pool delete="true">
<qualified-name>Name of IP Pool 1

Service Controller 9.6.1-AAA October 26, 2012 Page 139

Chapter 4 Provisioning APIs Provisioning API Guide

</qualified-name>
</ip-address-pool>
</dpi>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="updateDPI">
<result/>
</target>
</response>

Attributes This example shows how to update a DPI’s attributes. The DPI to update is
identified by providing its name in the "qualified-name" element. Attribute 3 is
added. Attribute 1 is deleted.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="updateDPI">
<parameter>
<dpi include-attributes="false"
include-ip-address-pools="false">
<qualified-name>DPI Name2</qualified-name>
<attribute name="Attribute3">
<value segment="segment">value1</value>
</attribute>
<attribute delete="true" name="Attribute1"/>
</dpi>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="updateDPI">
<result/>
</target>
</response>

Page 140 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

updateIPAddressPool

Specified name This example shows how to update an IP Address Pool by name.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="updateIPAddressPool">
<parameter>
<ip-address-pool>
<qualified-name>IP Pool Name</qualified-name>
<name>New IP Pool Name</name>
<description>New IP Pool Description
</description>
</ip-address-pool>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="updateIPAddressPool">
<result/>
</target>
</response>

updateNetwork

Name, RMS cluster This example shows how to update a network name, RMS cluster ID, and add a
ID, and DHCP option DHCP option.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="updateNetwork">
<parameter>
<network>
<qualified-name>Network name</qualified-name>
<name>new name</name>
<rms-cluster-id>31</rms-cluster-id>
<dhcp-option name="new option">
<value>2344</value>
</dhcp-option>

Service Controller 9.6.1-AAA October 26, 2012 Page 141

Chapter 4 Provisioning APIs Provisioning API Guide

</network>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="updateNetwork">
<result/>
</target>
</response>

IP Address Pool This example shows how to update a network IP Address Pool assignment. IP
assignment 192.168.1.0 to 192.168.1.4 are unassigned. IP 192.168.1.5 to 192.168.1.15 are
configured as dynamic
Note The DHCP Server assigned to the dynamic range must alreay be present
since the create dhcp server option is not enabled (the
create-dhcp-servers="true" attribute is not present).

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="updateNetwork">
<parameter>
<network>
<qualified-name>new name</qualified-name>
<subnet>
<starting-address>192.168.1.0
</starting-address>
<ip-address-range>
<start-ip>192.168.1.0</start-ip>
<end-ip>192.168.1.4</end-ip>
<range-type>UNASSIGNED</range-type>
</ip-address-range>
<ip-address-range>
<start-ip>192.168.1.5</start-ip>
<end-ip>192.168.1.15</end-ip>
<range-type>DYNAMIC</range-type>
<dhcp-server>
<qualified-name>DHCPServer1
</qualified-name>
</dhcp-server>
</ip-address-range>

Page 142 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</subnet>
</network>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="updateNetwork">
<result/>
</target>
</response>

Subnet split This example shows how to split a subnet. The network to update is identified in the
qualified-name element. The affected subnet is identified by matching the
starting-address of the subnets provided in the update with the starting-address of
the subnets already in the database.
A subnet split occurs if the subnet with start address 192.168.1.0 has a mask of
255.255.255.128. A split is assumed because the subnet mask included in the
update is narrower then the subnet's mask.
The subnet split requires that all addresses covered by the subnet are valid. As
such, two subnets are included in the update: the first subnet covers addresses
0-63, the second covers address 64-127. The subnet update also configures some
addresses of each subnet.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="updateNetwork">
<parameter>
<network>
<qualified-name>new name</qualified-name>
<subnet>
<starting-address>192.168.1.0
</starting-address>
<subnet-mask>255.255.255.192</subnet-mask>
<ip-address-range>
<start-ip>192.168.1.0</start-ip>
<end-ip>192.168.1.20</end-ip>
<range-type>DYNAMIC</range-type>
<dhcp-server><qualified-name>DHCPServer1
</qualified-name>
</dhcp-server>
</ip-address-range>

Service Controller 9.6.1-AAA October 26, 2012 Page 143

Chapter 4 Provisioning APIs Provisioning API Guide

</subnet>
<subnet>
<starting-address>192.168.1.64
</starting-address>
<subnet-mask>255.255.255.192</subnet-mask>
<ip-address-range>
<start-ip>192.168.1.80</start-ip>
<end-ip>192.168.1.100</end-ip>
<range-type>DYNAMIC</range-type>
<dhcp-server>
<qualified-name>DHCPServer1
</qualified-name>
</dhcp-server>
</ip-address-range>
</subnet>
</network>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="updateNetwork">
<result/>
</target>
</response>

Combining subnets This example shows how to combine subnets. The network to update is identified in
the qualified-name element. The affected subnet is identified by matching the
starting-address of the subnets provided in the update with the starting-address of
the subnets already in the database. A subnet combine occurs if the subnet with
start address 192.168.1.0 has a mask narrower than 255.255.255.0. A combine is
assumed because the subnet mask included in the update covers more addresses
than the subnet's mask. The subnet update also configures some of the addresses
of each subnet.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="NetworkAPI" operation="updateNetwork">
<parameter>
<network>
<qualified-name>new name</qualified-name>
<subnet>

Page 144 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<starting-address>192.168.1.0
</starting-address>
<subnet-mask>255.255.255.0</subnet-mask>
<ip-address-range>
<start-ip>192.168.1.0</start-ip>
<end-ip>192.168.1.130</end-ip>
<range-type>RESERVED</range-type>
</ip-address-range>
</subnet>
</network>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="NetworkAPI" operation="updateNetwork">
<result/>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 145

Chapter 4 Provisioning APIs Provisioning API Guide

OrganizationAPI operations
This section describes the following OrganizationAPI operations:
• createOrganization
• deleteOrganization
• createOrganizationProfileSet
• getOrganization
• getOrganizationProfileSet
• updateOrganization
• updateOrganizationProfileSet

createOrganization
Use the createOrganization operation to create an organization. Organizations may
be created at any level in the organization hierarchy.
These elements are required:
• the fully qualified organization name, which must be unique within the parent
organization (1 to 80 characters)
• an organization profile set (must already be present)
These elements are optional:
• an unbound domain to bind to this organization (if not specified, the domain is
inherited from the parent organization)
• organization context (O) profile attributes

Provision RADIUS This example shows how to create an organization with provisioned organization
connection service context RADIUS connection service profile attributes.
profile attributes
Request
<request version="2.0" principal="user" credentials="password">
<target name="OrganizationAPI" operation="createOrganization">
<parameter>
<organization>
<qualified-name>/BWS</qualified-name>
<profile-set>
<id>5</id>
<profile>
<id>15</id>
<attribute name="name1">
<value segment="seg1">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>

Page 146 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</attribute>
</profile>
</profile-set>
</organization>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="OrganizationAPI" operation="createOrganization">
<result/>
</target>
</response>

deleteOrganization
Use the deleteOrganization operation to delete an organization.

Request
<request credentials="root" principal="root" version="2.0">
<target name="OrganizationAPI" operation="deleteOrganization">
<parameter>
<organization>
<qualified-name>/BWS</qualified-name>
</organization>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="OrganizationAPI" operation="deleteOrganization">
<result/>
</target>
</response>

createOrganizationProfileSet
Use the createOrganizationProfileSet operation to create an organization profile
set.
These elements are required:
• the profile set name

Service Controller 9.6.1-AAA October 26, 2012 Page 147

Chapter 4 Provisioning APIs Provisioning API Guide

• the organization in which the profile set is to be created (must already be

present)
These elements are optional:
• a description of the profile set
• an inheritance flag to determine whether the profile set is available to
sub-organizations (default is yes)
• organization group context (OG) profile attributes

Provision RADIUS This example shows how to create an organization profile set with organization
connection service group context RADIUS connection service profile attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="OrganizationAPI"
operation="createOrganizationProfileSet">
<parameter>
<organization-profile-set>
<name>BWS Organization Profile Set</name>
<organization>
<id>4</id>
</organization>
<profile>
<id>5</id>
<attribute name="name1">
<value segment="seg1">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
</profile>
</organization-profile-set>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="OrganizationAPI" operation="createOrganizationProfileSet">
<result/>
</target>
</response>

Page 148 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

getOrganization
Use the getOrganization operation to retrieve organization information and,
optionally, organization context (O) profile attributes.
These elements are required:
• the organization ID or qualified name
These elements are optional:
• an empty <profile> element to be populated with organization context (O)
RADIUS connection services attribute information. All user profiles and
attributes are returned. For example:
<profile-set></profile-set>
• a <profile> element with the profile ID or qualified name that identifies a specific
profile for which RADIUS connection services attribution information is
requested. Only information for that profileare returned. For example:
<profile-set><profile><id>2</id></profile></profile-set>

Get RADIUS This example shows how to get organization context RADIUS connection service
connection service profile attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="OrganizationAPI" operation="getOrganization">
<parameter>
<organization>
<id>5</id>
<profile-set>
</profile-set>
</organization>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="OrganizationAPI" operation="getOrganization">
<result>
<id>5</id>
<name>/BWS</name>
<status>active</status>
<profile-set>
<profile>
<id>6</id>
<name>RadiusQoSConnectionService</name>

Service Controller 9.6.1-AAA October 26, 2012 Page 149

Chapter 4 Provisioning APIs Provisioning API Guide

<service>
<name>RadiusQoSConnectionService</name>
<version>1</version>
</service>
<attribute name="name1">
<value segment="segment">value1</value>
</attribute>
</profile>
</profile-set>
</result>
</target>
</response>

getOrganizationProfileSet
Use the getOrganizationProfileSet operation to retrieve organization profile set
information and, optionally, organization group context (OG) profile attributes.
These elements are required:
• the profile set qualified name or ID
These elements are optional:
• an empty <profile-set> element to be populated with organization group context
(OG) RADIUS connection services profile information. All user profiles and
attributes are returned. For example:
<profile-set></profile-set>
• a <profile-set> element with the profile ID or qualified name that identifies a
specific profile for which RADIUS connection services attribution information is
requested. Only information for that profile is returned. For example:
<profile-set><profile><id>2</id></profile><profile-set>

Get RADIUS This example shows how to get organization group context RADIUS connection
connection service service profile attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="OrganizationAPI" operation="getOrganizationProfileSet ">
<parameter>
<organization-profile-set>
<id>5</id>
<profile>
</profile>
</organization-profile-set>
</parameter>
</target>

Page 150 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</request>

Response
<response version="2.0">
<target name="OrganizationAPI" operation="getOrganizationProfileSet">
<result>
<organization-profile-set>
<name>BWS Organization Profile Set</name>
<organization><id>5</id></organization>
<profile>
<id>5</id>
<name>RadiusQoSConnectionService</name>
<service>
<name>RadiusQoSConnectionService</name>
<version>1</version>
</service>
<attribute name="name1">
<value segment="segment">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
</profile>
</organization-profile-set>
</result>
</target>
</response>

updateOrganization
Use the updateOrganization operation to modify an organization.
These elements are required:
• the qualified name or ID of the organization
These elements are optional:
• an organization profile set, to which this profile should be added or deleted
• organization context (O) profile attributes to be added, modified, or deleted from
the domain profile
• a new organization status (active or deleted)
• multiple IP address pools to associate with a single access node group, such as
a GGSN group

Service Controller 9.6.1-AAA October 26, 2012 Page 151

Chapter 4 Provisioning APIs Provisioning API Guide

Update RADIUS This example shows how to update organization context RADIUS connection
connection service service profile attributes.
profile attributes The update-only flag indicates that the value should only be updated if it is already
present in the profile. Default action is to add the attribute if itis not already present.

Request
<request version="2.0" principal="User1" credentials="password">
<target name="OrganizationAPI"
operation="updateOrganization">
<parameter>
<organization>
<id>5</id>
<profile-set>
<id>5</id>
<profile>
<id>5</id>
<attribute name="name1">
<value segment="seg1"
update-only="true">value1</value>
</attribute>
</profile>
</profile-set>
</organization>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="OrganizationAPI" operation="updateOrganization">
<result/>
</target>
</response>

Update Access This example shows how to update the Access Control service profile to associate
Control service multiple IP address pools with a single GGSN node group.
This association is necessary for IP Address Management deployments that
configure the Service Controller to choose from multiple IP address pools when
allocating IP addresses.
For more information, see the appendix “IP Address Manager” in the Service
Controller: Resource Management Server Guide.

Page 152 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Request
<request version="2.0" principal="provclient" credentials="rds32k2894l1k">
<target name="OrganizationAPI"
operation="updateOrganization">
<parameter>
<organization>
<id>2123</id>
<profile-set>
<id>165</id>
<access-control-profile>
<id>151</id>
<ggsn-groups>
<ggsn-group>
<group><id>245</id></group>
<association-type>RMS_IP_POOL
</ association-type>
<session-duration>1800</session-duration>
<failure-action>REJECT</failure-action>
<ip-pool-name>DefaultIPPool</ip-pool-name>
<ip-pool-association>
<assigned-ip-pools>
<name>IPPool1</name>
</assigned-ip-pools>
<assigned-ip-pools>
<name>IPPool02</name>
</assigned-ip-pools>
</ip-pool-association>
</ggsn-group>
</ggsn-groups>
</access-control-profile>
</profile-set>
</organization>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="OrganizationAPI" operation="updateOrganization">
<result/>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 153

Chapter 4 Provisioning APIs Provisioning API Guide

Delete RADIUS This example shows how to delete organization context RADIUS connection
connection service service profile attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="OrganizationAPI" operation="updateOrganization">
<parameter>
<organization>
<id>5</id>
<profile-set>
<id>5</id>
<profile>
<id>5</id>
<attribute name="name1" delete="true">
<value segment="segment">value1</value>
</attribute>
</profile>
</profile-set>
</organization>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="OrganizationAPI"
operation="updateOrganization">
<result/>
</target>
</response>

updateOrganizationProfileSet
Use the updateOrganizationProfileSet operation to modify an organization profile
set.
These elements are required:
• the profile set ID or qualified name
These elements are optional:
• a new profile set description
• a new profile set inheritance flag setting
• a new profile set status (active or deleted)
• a profile to be added to, modified, or deleted from the profile set

Page 154 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

• organization group context (OG) profile attributes to be added to, modified, or

deleted from an account profile
• multiple IP address pools to associate with a single access node group, such as
a GGSN group

Update RADIUS This example shows how to update organization group context RADIUS connection
connection service service profile attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="OrganizationAPI"
operation="updateOrganizationProfileSet">
<parameter>
<organization-profile-set>
<id>15</id>
<profile>
<id>5</id>
<attribute name="name1">
<value segment="seg2">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
</profile>
</organization-profile-set>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="OrganizationAPI" operation="updateOrganizationProfileSet">
<result/>
</target>
</response>

Update Access This example shows how to update the Access Control service profile to associate
Control service multiple IP address pools with a single GGSN node group.
This association is necessary for IP Address Management deployments that
configure the Service Controller to choose from multiple IP address pools when
allocating IP addresses.
For more information, see the appendix “IP Address Manager” in the Service
Controller: Resource Management Server Guide.

Service Controller 9.6.1-AAA October 26, 2012 Page 155

Chapter 4 Provisioning APIs Provisioning API Guide

Request
<request version="2.0" principal="provclient" credentials="rds32k2894l1k">
<target name="OrganizationAPI"
operation="updateOrganizationProfileSet">
<parameter>
<organization-profile-set>
<id>165</id>
<access-control-profile>
<id>151</id>
<ggsn-groups>
<ggsn-group>
<group><id>44</id></group>
<association-type>RMS_IP_POOL</association-type>
<session-duration>1800</session-duration>
<failure-action>REJECT</failure-action>
<ip-pool-name>DefaultIPPool</ip-pool-name>
<ip-pool-association>
<assigned-ip-pools>
<name>IPPool1</name>
</assigned-ip-pools>
<assigned-ip-pools>
<name>IPPool02</name>
</assigned-ip-pools>
</ip-pool-association>
</ggsn-group>
</ggsn-groups>
</access-control-profile>
</organization-profile-set>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="OrganizationAPI" operation="updateOrganizationProfileSet">
<result/>
</target>
</response>

Delete RADIUS This example shows how to delete organization group context RADIUS connection
connection service service profile attributes.
profile attributes

Page 156 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Request
<request version="2.0" principal="User1" credentials="password">
<target name="OrganizationAPI"
operation="updateOrganizationProfileSet">
<parameter>
<organization-profile-set>
<id>15</id>
<profile>
<id>5</id>
<attribute name="name1" delete="true">
<value segment="segment">value1</value>
</attribute>
<attribute name="name2">
<value delete="true" subscript="3">
value2
</value>
</attribute>
</profile>
</organization-profile-set>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="OrganizationAPI" operation="updateOrganizationProfileSet">
<result/>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 157

Chapter 4 Provisioning APIs Provisioning API Guide

ProfileAPI operations
This section describes the following ProfileAPI operations:
• createProfile
• deleteProfile
• getProfile
• updateProfile
• findProfiles

createProfile
Use the createProfile operation to create a service profile.
These elements are required:
• the profile name, which must be unique within the owning organization (1 to 40
characters)
• the service associated with the profile (must already be present)
• the organization that owns the profile (must already be present)
• an organization profile set (must already be present)
These elements are optional:
• a description of the profile (1 to 80 characters)
• an inheritance flag to determine whether the profile is available to
sub-organizations (default is yes)
• the status of the profile at the time of creation (active or pending)
• profile attributes
• For a RADIUS DAE Service profile, to send an empty attribute value, specify
#Null as the value. The #Null value is case-sensitive. For example:
<attribute name="RB-Forward-Policy">
<value context="default"
segment="REDBACK">#Null</value>

Create RADIUS QoS This example shows how to create a RADIUS QoS selection policy service profile.
selection policy Possible values for QoS selection policy are:
service profile • access
• static

Request
<request version="2.0" principal="User1" credentials="password">
<target name="ProfileAPI" operation="createProfile">
<parameter>
<radius-qos-selection-profile>
<name>Radius QoS Selection Policy Profile</name>
<service>

Page 158 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<name>RADIUS QoS Selection Policy</name>

</service>
<organization>
<qualified-name>/BWS</qualified-name>
</organization>
<description>Radius QoS Selection Policy Profile
describes the selected policy
</description>
<inheritance>yes</inheritance>
<status>active</status>
<qos-selection-policy>access
</qos-selection-policy>
</radius-qos-selection-profile>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="ProfileAPI" operation="createProfile">
<result>
<profile>
<id>1198</id>
</profile>
</result>
</target>
</response>

Create RADIUS This example shows how to create a RADIUS connection service profile (Radius
connection service QoS Profile) with specified QoS attributes.
profile
Request
<request version="2.0" principal="User1"
credentials="password">
<target name="ProfileAPI" operation="createProfile">
<parameter>
<profile>
<name>Radius QoS Profile</name>
<service>
<name>RADIUS ConnectionService</name>
</service>
<organization>
<qualified-name>/BWS</qualified-name>

Service Controller 9.6.1-AAA October 26, 2012 Page 159

Chapter 4 Provisioning APIs Provisioning API Guide

</organization>
<description>Radius QoS Profile</description>
<inheritance>yes</inheritance>
<status>active</status>
<attribute name="name1">
<value segment="segment">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
<attribute name="#ActiveStateFlag">
<value>on</value>
</attribute>
</profile>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="ProfileAPI" operation="createProfile">
<result/>
</target>
</response>

.Create a RADIUS In some deployments, define RADIUS grouped or nested attributes within a
Connection service RADIUS Connection service profile. This example shows how to define a RADIUS
profile with grouped grouped attribute.
attributes
Request
<target name="ProfileAPI" operation="createProfile"...>
......
<attribute name="WiMAX-Packet-Flow-Descriptor">
<value segment="COMMON">
<attribute name="Packet-Data-Flow-ID">
<value segment="COMMON">362</value>
</attribute>
<attribute name="Service-Profile-ID">
<value segment="COMMON">123</value>
</attribute>
</value>
</attribute>
.......

Page 160 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</target>

Create a Diameter This example shows how to create a Diameter connection service profile.
connection service Note Use at least API version 2.0 or greater when provisioning a Diameter
profile connection service profile. Versions prior to version 2.0 may not be
compatible with Diameter group attributes.

Request
<request credentials="password" principal="username" version="2.0">
<target name="ProfileAPI" operation="createProfile">
<parameter>
<diameter-connection-profile>
<name>Diameter Connection Service Profile</name>
<organization>
<qualified-name>/BWS</qualified-name>
</organization>
<segment>
<name>COMMON</name>
<enabled>true</enabled>
</segment>
<segment>
<name>RFC3588</name>
<enabled>true</enabled>
</segment>
<attribute name="Session-Timeout">
<value segment="COMMON">60</value>
</attribute>
<attribute name="QoS-Descriptor">
<value segment="COMMON">
<attribute name="QoS-ID">
<value segment="COMMON">120</value>
</attribute>
<attribute name="Service-Class-Name">
<value segment="COMMON">bronze</value>
</attribute>
</value>
</attribute>
<attribute name="User-Name">
<value segment="RFC3588">user@domain</value>
</attribute>
</diameter-connection-profile>
</parameter>
</target>

Service Controller 9.6.1-AAA October 26, 2012 Page 161

Chapter 4 Provisioning APIs Provisioning API Guide

</request>

Response
<response version="2.0">
<target name="ProfileAPI" operation="createProfile">
<result>
<diameter-connection-profile>
<id>2404</id>
</diameter-connection-profile>
</result>
</target>
</response>

deleteProfile
This section provides examples for the deleteProfile operation.

Delete RADIUS QoS This example shows how to delete a RADIUS QoS selection policy profile.
selection policy
service profile Request
<request version="2.0" principal="User1" credentials="password">
<target name="ProfileAPI" operation="deleteProfile">
<parameter>
<radius-qos-selection-profile>
<qualified-name>
/Radius QoS Selection Policy Profile
</qualified-name>
</radius-qos-selection-profile>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="ProfileAPI" operation="deleteProfile">
<result/>
</target>
</response>

Page 162 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Delete RADIUS This example shows how to delete a RADIUS connection service profile (/Radius
connection service QoS Profile).
profile
Request
<request version="2.0" principal="User1" credentials="password">
<target name="ProfileAPI" operation="deleteProfile">
<parameter>
<profile>
<qualified-name>
/Radius QoS Profile
</qualified-name>
</profile>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="ProfileAPI" operation="deleteProfile">
<result/>
</target>
</response>

Delete a Diameter This example shows how to delete a Diameter connection service profile.
connection service Note Use API version 2.0 or greater when provisioning a Diameter connection
profile service profile. Versions prior to version 2.0 may not be compatible with
Diameter group attributes.

Request
<request version="2.0" principal="user" credentials="password">
<target name="ProfileAPI" operation="deleteProfile">
<parameter>
<diameter-connection-profile>
<qualified-name>
/Diameter Connection Service Profile
</qualified-name>
</ diameter-connection-profile>
</parameter>
</target>
</request>

Service Controller 9.6.1-AAA October 26, 2012 Page 163

Chapter 4 Provisioning APIs Provisioning API Guide

Response
<response version="2.0">
<target name="ProfileAPI" operation="deleteProfile">
<result />
</target>
</response>

getProfile
Use the getProfile operation to retrieve profile information and default (DEF) context
service attributes. These elements are required:
• the profile ID or qualified name

Get RADIUS QoS This example shows how to get a RADIUS QoS selection policy service profile.
selection policy
service profile Request
<request version="2.0" principal="User1" credentials="password">
<target name="ProfileAPI" operation="getProfile">
<parameter>
<radius-qos-selection-profile>
<qualified-name>/Radius QoS Selection Policy
Profile</qualified-name>
</radius-qos-selection-profile>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="ProfileAPI" operation="getProfile">
<result>
<radius-qos-selection-profile>
<id>1198</id>
<name>Radius QoS Selection Policy Profile</name>
<organization>
<id>1</id>
</organization>
<service>
<id>18</id>
<name>RADIUS QoS Selection Policy</name>
<status><value>active</value></status>
<version>1</version>
</service>

Page 164 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<inheritance>yes</inheritance>
<description>Radius QoS Selection Policy Profile
describes the selected policy</description>
<qualified-name>/Radius QoS Selection Policy
Service</qualified-name>
<status><value>active</value></status>
<qos-selection-policy>access
</qos-selection-policy>
</radius-qos-selection-profile>
</result>
</target>
</response>

Get RADIUS This example shows how to get a RADIUS connection service profile
connection service (/Radius QoS Profile).
profile
Request
<request version="2.0" principal="User1"
credentials="password">
<target name="ProfileAPI" operation="getProfile">
<parameter>
<profile>
<qualified-name>/Radius QoS Profile</qualified-name>
</profile>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="ProfileAPI" operation=" getProfile">
<result>
<profile>
<id>5</id>
<name>Radius QoS Profile</name>
<service>
<name>RADIUS ConnectionService</name>
<version>1</version>
</service>
<attribute name="name1">
<value segment="segment">value1</value>
</attribute>
<attribute name="name2">

Service Controller 9.6.1-AAA October 26, 2012 Page 165

Chapter 4 Provisioning APIs Provisioning API Guide

<value segment="segment">value2</value>
</attribute>
</profile>
</result>
</target>
</response>

Get a Diameter This example shows how to retrieve a Diameter connection service profile.
connection service Note Use API version 2.0 or greater when provisioning a Diameter connection
profile service profile. Versions prior to version 2.0 may not be compatible with
Diameter group attributes.

Request
<request credentials="password" principal="username" version="2.0">
<target name="ProfileAPI" operation="getProfile">
<parameter>
<diameter-connection-profile>
<qualified-name>
/BWS/Diameter Connection Service Profile
</qualified-name>
</diameter-connection-profile>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="ProfileAPI" operation="getProfile">
<result>
<diameter-connection-profile>
<id>2404</id>
<name>Diameter Connection Service Profile</name>
<organization>
<id>1436</id>
</organization>
<service>
<id>1000</id>
<name>DIAMETER ConnectionService</name>
<status>
<value>active</value>
</status>
<version>2</version>
</service>

Page 166 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<inheritance>yes</inheritance>
<status>
<value>active</value>
</status>
<context-mask>
<user/>
<user-group/>
<account/>
<account-group/>
<organization/>
<organization-group/>
<domain/>
<domain-group/>
<default/>
</context-mask>
<last-modified>2008-10-27 18:41:39</last-modified>
<modified-by>admin</modified-by>
<segment>
<name>RFC3588</name>
<enabled>true</enabled>
</segment>
<segment>
<name>COMMON</name>
<enabled>true</enabled>
</segment>
<attribute name="Session-Timeout">
<value context="default" segment="COMMON"
subscript="2147418112">60</value>
</attribute>
<attribute name="QoS-Descriptor">
<value context="default" segment="COMMON"
subscript="2147418112">
<attribute name="QoS-ID">
<value context="default" segment="COMMON"
subscript="2147418112">120</value>
</attribute>
<attribute name="Service-Class-Name">
<value context="default" segment="COMMON"
subscript="2147418112">bronze</value>
</attribute>
</value>
</attribute>
<attribute name="User-Name">

Service Controller 9.6.1-AAA October 26, 2012 Page 167

Chapter 4 Provisioning APIs Provisioning API Guide

<value context="default" segment="RFC3588"

subscript="196608">user@domain</value>
</attribute>
</diameter-connection-profile>
</result>
</target>
</response>

updateProfile
Use the updateProfile operation to modify an organization.
These elements are required:
• the qualified name or ID of the service profile
These elements are optional:
• a new profile description
• a new profile inheritance flag setting
• a new profile status (active or deleted)
• default context (DEF) profile attributes to be modified, added to, or deleted from
the service profile

Update RADIUS This example shows how to update a RADIUS connection service profile.
connection service
profile Request
<request version="2.0" principal="user" credentials="password">
<target name="ProfileAPI" operation="updateProfile">
<parameter>
<profile>
<id>5</id>
<description>Radius QoS Profile</description>
<status>active</status>
<attribute name="name1">
<value segment="segment">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
<attribute name="#ActiveStateFlag">
<value>ON</value>
</attribute>
</profile>
</parameter>
</target>

Page 168 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</request>

Response
<response version="2.0">
<target name="ProfileAPI" operation=" updateProfile">
<result/>
</target>
</response>

Modify values of a To modify an attribute value, specify the attribute name and segment, and a delete
Diameter attribute flag to delete the old value. Then, specify the new attribute, segment, and values.
Note Use API version 2.0 or greater when provisioning a Diameter connection
service profile. Versions prior to version 2.0 may not be compatible with
Diameter group attributes.

Request
<request version="2.0" principal="user" credentials="password">
<target name="ProfileAPI" operation="updateProfile">
<parameter>
<diameter-connection-profile>
<qualified-name>
/BWS/Diameter Connection Service Profile
</qualified-name>
<segment>
<name>COMMON</name>
<enabled>true</enabled>
</segment>
<segment>
<name>RFC3588</name>
<enabled>true</enabled>
</segment>
<!-- Update Session-Timeout to 120 seconds -->
<attribute delete="true" name="Session-Timeout"/>
<attribute name="Session-Timeout">
<value segment="COMMON">120</value>
</attribute>
<!-- update Add a group attribute -->
<attribute delete="true" name="QoS-Descriptor"/>
<attribute name="QoS-Descriptor">
<value segment="COMMON">
<attribute name="QoS-ID">
<value segment="COMMON">123</value>
</attribute>

Service Controller 9.6.1-AAA October 26, 2012 Page 169

Chapter 4 Provisioning APIs Provisioning API Guide

<attribute name="Service-Class-Name">
<value segment="COMMON">bronze</value>
</attribute>
</value>
</attribute>
<attribute name="User-Name">
<value segment="RFC3588">user@domain</value>
</attribute>
</diameter-connection-profile>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="ProfileAPI" operation="updateProfile">
<result/>
</target>
</response>

findProfiles
Use the findProfiles operation to find service profiles.
One of these elemenst is required:
• the service profile name
• the qualified name or ID of the organization that owns the service profile(s)
• the name or ID of the service class associated with the service profile(s)
These elements are optional:
• a flag to search sub-organizations

Find all profiles in the To find all profiles in the Root organization, specify "/" as the organization qualified
Root organization name.

Request
<request version="2.0" principal="user" credentials="password">
<target name="ProfileAPI" operation="findProfiles">
<parameter>
<profile-search>
<organization>
<qualified-name>/</qualified-name>
</organization>
<include-sub-organizations>true</include-sub-organizations>

Page 170 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</profile-search>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="ProfileAPI" operation="findProfiles">
<result>
<profile-search-result>
<next-index>-1</next-index>
<results>
<id>1</id>
<name>Root Privileges</name>
<organization>
<id>1</id>
</organization>
<service>
<id>1</id>
<name>Privileges</name>
<status>
<value>active</value>
</status>
<version>1</version>
</service>
<inheritance>no</inheritance>
<description>Service profile for root privileges</description>
<qualified-name>/Privileges</qualified-name>
<status>
<value>active</value>
</status>
<last-modified>2009-09-22 19:50:14</last-modified>
<modified-by>creroot.sql</modified-by>
<context-mask>
<user/>
<user-group/>
<default/>
</context-mask>
</results>
<results>
<id>2</id>
<name>User Information</name>
<organization>

Service Controller 9.6.1-AAA October 26, 2012 Page 171

Chapter 4 Provisioning APIs Provisioning API Guide

<id>1</id>
</organization>
<service>
<id>2</id>
<name>UserInformation</name>
<status>
<value>active</value>
</status>
<version>1</version>
</service>
<inheritance>yes</inheritance>
<qualified-name>/User Information</qualified-name>
<status>
<value>active</value>
</status>
<last-modified>2009-09-22 19:50:14</last-modified>
<modified-by>root</modified-by>
<context-mask>
<user/>
<user-group/>
<organization/>
<organization-group/>
<default/>
</context-mask>
</results>
<results>
<id>3</id>
<name>Organization Information</name>
<organization>
<id>1</id>
</organization>
<service>
<id>3</id>
<name>OrganizationInformation</name>
<status>
<value>active</value>
</status>
<version>1</version>
</service>
<inheritance>yes</inheritance>
<qualified-name>/Organization Information</qualified-name>
<status>
<value>active</value>

Page 172 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</status>
<last-modified>2009-09-22 19:50:14</last-modified>
<modified-by>root</modified-by>
<context-mask>
<organization/>
<organization-group/>
</context-mask>
</results>
<results>
<id>4</id>
<name>Domain Information</name>
<organization>
<id>1</id>
</organization>
<service>
<id>4</id>
<name>DomainInformation</name>
<status>
<value>active</value>
</status>
<version>1</version>
</service>
<inheritance>yes</inheritance>
<status>
<value>active</value>
</status>
<last-modified>2009-09-22 19:50:14</last-modified>
<modified-by>root</modified-by>
<context-mask>
<domain/>
<domain-group/>
</context-mask>
</results>
<results>
<id>5</id>
<name>Privileges</name>
<organization>
<id>1</id>
</organization>
<service>
<id>1</id>
<name>Privileges</name>
<status>

Service Controller 9.6.1-AAA October 26, 2012 Page 173

Chapter 4 Provisioning APIs Provisioning API Guide

<value>active</value>
</status>
<version>1</version>
</service>
<inheritance>yes</inheritance>
<qualified-name>/Privileges</qualified-name>
<status>
<value>active</value>
</status>
<last-modified>2009-09-22 19:50:14</last-modified>
<modified-by>root</modified-by>
<context-mask>
<user/>
<user-group/>
<default/>
</context-mask>
</results>
<results>
<id>6</id>
<name>IP Reachability Profile</name>
<organization>
<id>1</id>
</organization>
<service>
<id>5</id>
<name>IPReachabilityService</name>
<status>
<value>active</value>
</status>
<version>1</version>
</service>
<inheritance>yes</inheritance>
<qualified-name>/IP Reachability Profile</qualified-name>
<status>
<value>active</value>
</status>
<last-modified>2009-09-22 19:50:14</last-modified>
<modified-by>root</modified-by>
<context-mask>
<user/>
<user-group/>
<account/>
<account-group/>

Page 174 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<organization/>
<organization-group/>
<domain/>
<domain-group/>
<default/>
</context-mask>
</results>
<results>
<id>7</id>
<name>Account Information</name>
<organization>
<id>1</id>
</organization>
<service>
<id>6</id>
<name>AccountInformation</name>
<status>
<value>active</value>
</status>
<version>1</version>
</service>
<inheritance>yes</inheritance>
<qualified-name>/Account Information</qualified-name>
<status>
<value>active</value>
</status>
<last-modified>2009-09-22 19:50:14</last-modified>
<modified-by>root</modified-by>
<context-mask>
<user/>
<user-group/>
<account/>
<account-group/>
<default/>
</context-mask>
</results>
<results>
<id>8</id>
<name>DEFAULTDHCP</name>
<organization>
<id>1</id>
</organization>
<service>

Service Controller 9.6.1-AAA October 26, 2012 Page 175

Chapter 4 Provisioning APIs Provisioning API Guide

<id>8</id>
<name>DHCP</name>
<status>
<value>active</value>
</status>
<version>2</version>
</service>
<inheritance>yes</inheritance>
<status>
<value>active</value>
</status>
<last-modified>2009-09-22 19:50:16</last-modified>
<modified-by>cresvc.sql</modified-by>
<context-mask>
<user/>
<user-group/>
<organization/>
<organization-group/>
<domain/>
<domain-group/>
<default/>
</context-mask>
</results>
</profile-search-result>
</result>
</target>
</response>

Page 176 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Proxy deployment APIs

Note These APIs are available only to customers with the BWSoaaapdb Proxy
Database Configuration optionality package. Before configuring proxy
deployments using APIs,set the ReadProxyConfigFromDB attribute in the
proxies.xml file to ‘Y’.
This section describes the following APIs:
• ProxyFilter APIs
• Proxy Override Attribute Group API
• Proxy Required Attribute Group API
• RADIUS Server (proxy target) API
• RADIUS Server Group API
• RADIUS proxy service API

ProxyFilter APIs
This section describes the following ProxyFilter operations:
• createProxyFilter
• getProxyFilterBy Name
• deleteProxyFilterBy Name

createProxyFilter Use the createProxyFilter operation to create proxy filters.

Note Only use this API operation after installing the Proxy Database
Configuration optionality package.
These elements are required:
• name of the proxy filter <name>
• action for the proxy filter, such as Allow <action>
• parent element for a list of required proxy filter AVPs <proxy-filter-avps>
• element inside which you define a required proxy filter AVP <proxy-filter-avp>
• attribute name for each proxy filter AVP <attribute-name>
• action for each required proxy filter AVP, such as Deny <action>
• parent element inside which you list a proxy filter AVP ‘s exception values
<exception-values>
• parent element inside which you list a proxy filter AVP ‘s regular expression
values <exception-reg-exes>
• parent element inside which you list a proxy filter AVP ‘s exception ranges
<exception-ranges>
These elements are optional:
• a description of the proxy filter <description>
• vendor name for the required VSA <vendor-name>
• parent element for a list of exception values <exception-val>

Service Controller 9.6.1-AAA October 26, 2012 Page 177

Chapter 4 Provisioning APIs Provisioning API Guide

• exception value <value>

• parent element for a list of exception regular expressions <exception-reg-exp>
• exception regular expression value <value>
• parent element for a list of exception ranges <exception-range>
• exception range separated by a hyphen <value>

Request
<request version="2.0" principal="<principal>" credentials="<credentials>">
<target name="ProxyFilterAPI" operation="createProxyFilter">
<parameter>
<proxy-filter>
<name>Proxy Filter 1</name>
<action>Allow</action>
<proxy-filter-avps>
<proxy-filter-avp>
<attribute-name>Frame-Id</attribute-name>
<action>Deny</action>
<exception-values>
<exception-val>
<value>123</value>
</exception-val>
</exception-values>
<exception-ranges>
<exception-range>
<value>1-10</value>
</exception-range>
</exception-ranges>
</proxy-filter-avp>
<proxy-filter-avp>
<attribute-name>User-Name</attribute-name>
<action>Allow</action>
<vendor-name>STARENT</vendor-name>
<exception-reg-exes>
<exception-reg-exp>
<value>^123</value>
</exception-reg-exp>
</exception-reg-exes>
</proxy-filter-avp>
</proxy-filter-avps>
</proxy-filter>
</parameter>
</target>
</request>

Page 178 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Response
<response version="2.0">
<target name="ProxyFilterAPI" operation="updateProxyFilter">
<result/>
</target>
</response>

getProxyFilterBy Use the getProxyFilterByName operation to retrieve proxy filters. Only use this API
Name operation after installing the Proxy Database Configuration optionality package.
These elements are required:
• parent element for the proxy filter name <proxy-filter>
• name of the proxy filter <name>

Request
<request version="2.0" principal="<principal>" credentials="<credentials>">
<target name="ProxyFilterAPI" operation="getProxyFilterByName">
<parameter>
<proxy-filter>
<name>Proxy Filter 1</name>
</proxy-filter>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="ProxyFilterAPI" operation="getProxyFilterByName">
<result>
<proxy-filter>
<id>1067</id>
<configuration-id>1</configuration-id>
<name>Proxy Filter 1</name>
<action>Allow</action>
<proxy-filter-avps>
<proxy-filter-avp>
<id>1068</id>
<configuration-id>1</configuration-id>
<name>1067|RFC2138|Frame-Id</name>
<attribute-name>Frame-Id</attribute-name>
<action>Allow</action>
<vendor-name>RFC2138</vendor-name>
<exception-values>

Service Controller 9.6.1-AAA October 26, 2012 Page 179

Chapter 4 Provisioning APIs Provisioning API Guide

<exception-val>
<value>456</value>
</exception-val>
</exception-values>
<exception-ranges>
<exception-range>
<value>1-10</value>
</exception-range>
</exception-ranges>
<last-modified>2009-03-23 21:01:34</last-modified>
<modified-by>admin</modified-by>
</proxy-filter-avp>
<proxy-filter-avp>
<id>1069</id>
<configuration-id>1</configuration-id>
<name>1067|STARENT|User-Id</name>
<attribute-name>User-Id</attribute-name>
<action>Allow</action>
<vendor-name>STARENT</vendor-name>
<exception-reg-exes>
<exception-reg-exp>
<value>^123</value>
</exception-reg-exp>
</exception-reg-exes>
<last-modified>2009-03-23 23:03:41</last-modified>
<modified-by>admin</modified-by>
</proxy-filter-avp>
</proxy-filter-avps>
<last-modified>2009-03-23 23:03:39</last-modified>
<modified-by>admin</modified-by>
</proxy-filter>
</result>
</target>
</response>

deleteProxyFilterBy Use the deleteProxyFilterByName operation to delete proxy filters. Only use this
Name API operatioafter installing the Proxy Database Configuration optionality package.
These elements are required:
• <proxy-filter>Parent element for the proxy filter name
• <name>Name of the proxy filter</name>

Request
<request version="2.0" principal="<principal>" credentials="<credentials>">

Page 180 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<target name="ProxyFilterAPI" operation="deleteProxyFilterByName">

<parameter>
<proxy-filter>
<name>Proxy Filter 1</name>
</proxy-filter>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="ProxyFilterAPI" operation="deleteProxyFilterByName">
<result/>
</target>
</response>

Proxy Override Attribute Group API

This section describes the following Proxy Override Attribute Group operations:
• createProxyOverrideAttributeGroup
• updateProxyOverrideAttributeGroup
• getProxyOverrideAttributeGroupByName
• deleteProxyOverrideAttributeGroupByName
Considerations:
• If the Class or Proxy-State attributes are specified as Override Attribute entries
in a proxy filter, the RADIUS Server adds their values to the reply packet even if
the attributes are already present with different values.
This allows the RADIUS Server to inject a new value but maintain the values
sent by the proxy target in accordance with RFC 2865.
• If the RADIUS Server injects the Class or Proxy-State attributes in the reply
packet, the RADIUS Server marks these attributes as local data so that they
are not proxied to remote servers in subsequent messages.
• If you specify the State attribute as an Override Attribute in a proxy filter, the
RADIUS Server only adds its value to the reply packet if there is no State
attribute already present.

Service Controller 9.6.1-AAA October 26, 2012 Page 181

Chapter 4 Provisioning APIs Provisioning API Guide

createProxyOverride Use the createProxyOverrideAttributeGroup operation to create groups of proxy

AttributeGroup override attributes.Only use this API operation after installing the Proxy Database
Configuration optionality package. Before using proxy APIs, set the
ReadProxyConfigFromDB attribute in the proxies.xml file to ‘Y’.

Table 23: Required/optional elements for createProxyOverrideAttributeGroup operation

XML element Element description

<proxy-override-attribute-group> Group name.

<name>name of group</name> Required.

<description> description of this group</description> Group description.

Optional.

<proxy-override-attributes> List of proxy override attributes.

Required.

<proxy-override-attribute> Proxy override attribute for the proxy override attribute group.
Required.

<attribute-name>name of attribute</attribute-name> Name for the proxy override attribute.

Required.

<vendor-name>name of the vendor</vendor-name> Vendor name defining the <proxy-override-attribute>

element.
Optional.

<precedence>Filter</precedence> Whether the proxy override attribute should replace the

original value sent in the request (Filter), or leave the
attribute unchanged (packet).
• Filter (default)
• Packet
Optional.

<mandatory>Y</mandatory> Whether or not the RADIUS Server should insert the override
attribute described in <proxy-override-attribute> into the
message.
• Y ( default)
• N
Optional.

<proxy-override-attribute-components> List of proxy override attribute components.

Required.

<proxy-override-attribute-value> Define a proxy override attribute value.

<attribute-name>name of attribute, such as Framed-IP</ Required: if proxy override attribute value is provided.
attribute-name>
</proxy-override-attribute-value>

<vendor-name>STARENT</vendor-name> Vendor name defining the <proxy-override-attribute-value>.

Optional.

Page 182 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Table 23: Required/optional elements for createProxyOverrideAttributeGroup operation (continued)

XML element Element description

<from>ProxyResponse</from> Define whether the attribute to be overriden is in the Proxy

Request or Proxy Response.
• ProxyRequest
• ProxyResponse (default)
Optional.

<type>type of attribute, such as Integer</type> Define the attribute type for the proxy override attribute
value.
• Integer
• String
• IPv4
• IPv6
• Binary
Optional.

<proxy-override-data-value> Child of <proxy-override-attribute-components>.

Defines a data value.
Optional.

<type>type of attribute, such as Integer</type> Attribute type defining the <proxy-override-data-value>

element.
• Integer
• String
• IPv4
• IPv6
• Binary.
Required: if proxy override data value is provided.

<value>value of the parent element</value> Value of the <proxy-override-data-value> element.

Required: if proxy override data value is provided.

<proxy-override-reg-ex-value> Child of <proxy-override-attribute-components>.

Defines a regular expression value.
Optional.

<attribute-name>User-Name</attribute-name> Attribute name for the <proxy-override-reg-ex-value>

element.
Required: if proxy override reg ex value is provided.

<type>String</type> String format of the proxy override reg ex value.

• Integer
• String
• IPv4
• IPv6
• BinaryHex
Required: if proxy override reg ex value is provided).

Service Controller 9.6.1-AAA October 26, 2012 Page 183

Chapter 4 Provisioning APIs Provisioning API Guide

Table 23: Required/optional elements for createProxyOverrideAttributeGroup operation (continued)

XML element Element description

<pattern>pattern for proxy override reg ex value</pattern> Pattern for the proxy override reg ex value.
Required.

<value>value for the proxy override reg ex </value> Value for the proxy override reg ex value.
Required.

<proxy-override-condition-group> Proxy override match condition group is a child of

<proxy-override-attribute>.
Optional.

<proxy-override-match-condition> Defines a match condition within the condition group.

Required: if proxy override condition group is provided.

<attribute-name>name </attribute-name> Attribute name for <proxy-override-match-condition>.

Required: if proxy override match condition is provided.

<vendor-name>STARENT</vendor-name> Vendor name defining <proxy-override-match-condition>.

Optional.

<string format> String format for the proxy override match condition.
• Integer
• String
• IPv4
• IPv6
• BinaryHex.
Required: if proxy override match condition is provided).

<from>ProxyResponse</from> Define whether the attribute to be overriden is in the Proxy

Request or Proxy Response.
• ProxyRequest
• ProxyResponse (default)
Optional.

<pattern>(\d)+.(\d)+.(\d)+.(\d)+</pattern> Pattern for the proxy override match condition.

Required.

<proxy-override-attribute-components> Proxy override attribute components for proxy override

<proxy-override-data-value> match condition. Can be:
• proxy override attribute value
• proxy override data value
• proxy override reg ex value
Required: if proxy override match condition is provided.

<type>Integer</type> See "<type>type of attribute, such as Integer</type>" on

page 183.

<value>100</value> "<value>value of the parent element</value>" on page 183.

Page 184 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Request
<request version="2.0" principal="<principal>" credentials="<credentials>">
<target name="ProxyOverrideAttributeGroupAPI"
operation="createProxyOverrideAttributeGroup">
<parameter>
<proxy-override-attribute-group>
<name>POAG1</name>
<proxy-override-attributes>
<proxy-override-attribute>
<attribute-name>Idle-Timeout</attribute-name>
<proxy-override-attribute-components>
<proxy-override-attribute-value>
<attribute-name>Framed-IP</attribute-name>
</proxy-override-attribute-value>
<proxy-override-data-value>
<type>Integer</type>
<value>1</value>
</proxy-override-data-value>
<proxy-override-reg-ex-value>
<attribute-name>User-Name</attribute-name>
<type>String</type>
<pattern>^abc</pattern>
<value>testing</value>
</proxy-override-reg-ex-value>
<proxy-override-condition-group>
<proxy-override-match-condition>
<attribute-name>3GPP2-IP</attribute-name>
<type>IPv4</type>
<pattern>(\d)+.(\d)+.(\d)+.(\d)+</pattern>
<proxy-override-attribute-components>
<proxy-override-data-value>
<type>Integer</type>
<value>100</value>
</proxy-override-data-value>
<proxy-override-attribute-value>
<attribute-name>Framed-IP
</attribute-name>
<vendor-name>STARENT</vendor-name>
</proxy-override-attribute-value>
</proxy-override-attribute-components>
</proxy-override-match-condition>
<proxy-override-match-condition>
<attribute-name>Reply-Message

Service Controller 9.6.1-AAA October 26, 2012 Page 185

Chapter 4 Provisioning APIs Provisioning API Guide

</attribute-name>
<type>String</type>
<pattern>^test$</pattern>
<proxy-override-attribute-components>
<proxy-override-reg-ex-value>
<attribute-name>Calling-Station-Id
</attribute-name>
<type>Integer</type>
<pattern>(\d)+</pattern>
<value>testagain</value>
</proxy-override-reg-ex-value>
</proxy-override-attribute-components>
</proxy-override-match-condition>
</proxy-override-condition-group>
</proxy-override-attribute-components>
</proxy-override-attribute>
</proxy-override-attributes>
</proxy-override-attribute-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="ProxyOverrideAttributeGroupAPI"
operation="createProxyOverrideAttributeGroup">
<result>
<proxy-override-attribute-group>
<id>1074</id>
</proxy-override-attribute-group>
</result>
</target>
</response>

updateProxyOverride Use the updateProxyOverrideAttributeGroup operation to update proxy override

AttributeGroup attribute groups. Only use this API operation after installing the Proxy Database
Configuration optionality package. Before using proxy APIs, set the
ReadProxyConfigFromDB attribute in the proxies.xml file to ‘Y’.
For information about the elements to specify, see Table 23 on page 182.

Page 186 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Request
<request version="2.0" principal="<principal>" credentials="<credentials>">
<target name="ProxyOverrideAttributeGroupAPI"
operation="updateProxyOverrideAttributeGroup">
<parameter>
<proxy-override-attribute-group>
<qualified-name>POAG50</qualified-name>
<proxy-override-attributes>
<proxy-override-attribute>
<qualified-name>RFC2138|Idle-Timeout</qualified-name>
<mandatory>true</mandatory>
<proxy-override-attribute-components>
<proxy-override-data-value delete="true">
<id>1182</id>
</proxy-override-data-value>
<proxy-override-attribute-value>
<attribute-name>User-Name</attribute-name>
</proxy-override-attribute-value>
</proxy-override-attribute-components>
</proxy-override-attribute>
</proxy-override-attributes>
</proxy-override-attribute-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="ProxyOverrideAttributeGroupAPI"
operation="updateProxyOverrideAttributeGroup">
<result/>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 187

Chapter 4 Provisioning APIs Provisioning API Guide

getProxyOverride Use the getProxyOverrideAttributeGroup operation to retrieve proxy override

AttributeGroupBy attribute groups. Only use this API operation after installing the Proxy Database
Name Configuration optionality package. Before using proxy APIs, set the
ReadProxyConfigFromDB attribute in the proxies.xml file to ‘Y’.
These elements are required:
• the proxy override attribute group name <name>

Request
<request version="2.0" principal="<principal>" credentials="<credentials>">
<target name="ProxyOverrideAttributeGroupAPI"
operation="getProxyOverrideAttributeGroupByName">
<parameter>
<proxy-override-attribute-group>
<name>POAG1</name>
</proxy-override-attribute-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="ProxyOverrideAttributeGroupAPI"
operation="getProxyOverrideAttributeGroupByName">
<result>
<proxy-override-attribute-group>
<id>1074</id>
<configuration-id>1</configuration-id>
<name>POAG1</name>
<proxy-override-attributes>
<proxy-override-attribute>
<id>1075</id>
<configuration-id>1</configuration-id>
<name>1075|RFC2138|Idle-Timeout</name>
<attribute-name>Idle-Timeout</attribute-name>
<vendor-name>RFC2138</vendor-name>
<precedence>Packet</precedence>
<mandatory>true</mandatory>
<proxy-override-attribute-components>
<proxy-override-attribute-value order="3">
<id>1195</id>
<configuration-id>1</configuration-id>
<name>1195|attribute_value|RFC2138
|User-Name </name>

Page 188 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<attribute-name>User-Name</attribute-name>
</proxy-override-attribute-value>
<proxy-override-data-value order="0">
<id>1189</id>
<configuration-id>1</configuration-id>
<name>1189|data_value|Integer</name>
<type>Integer</type>
<value>1</value>
</proxy-override-data-value>
<proxy-override-reg-ex-value order="1">
<id>1190</id>
<configuration-id>1</configuration-id>
<name>1190|regex_value|RFC2138|User-Name
</name>
<attribute-name>User-Name</attribute-name>
<vendor-name>RFC2138</vendor-name>
<type>String</type>
<pattern>^abc</pattern>
<value>testing</value>
</proxy-override-reg-ex-value>
<proxy-override-condition-group order="2">
<id>1191</id>
<configuration-id>1</configuration-id>
<name>1191|condition_group</name>
<proxy-override-match-condition order="0">
<id>1192</id>
<configuration-id>1</configuration-id>
<name>1192|match_condition|RFC2138|
3GPP2-IP</name>
<attribute-name>3GPP2-IP</attribute-name>
<vendor-name>RFC2138</vendor-name>
<type>IPv4</type>
<pattern>(\d)+.(\d)+.(\d)+.(\d)+</pattern>
<proxy-override-attribute-components>
<proxy-override-attribute-value order="0">
<id>1193</id>
<configuration-id>1</configuration-id>
<name>1193|attribute_value|STARENT|
Framed-IP</name>
<attribute-name>Framed-IP
</attribute-name>
<vendor-name>STARENT
</vendor-name>

Service Controller 9.6.1-AAA October 26, 2012 Page 189

Chapter 4 Provisioning APIs Provisioning API Guide

</proxy-override-attribute-value>
<proxy-override-data-value order="1">
<id>1194</id>
<configuration-id>1</configuration-id>
<name>1194|data_value|Integer
</name>
<type>Integer</type>
<value>100</value>
</proxy-override-data-value>
</proxy-override-attribute-components>
</proxy-override-match-condition>
</proxy-override-condition-group>
</proxy-override-attribute-components>
</proxy-override-attribute>
</proxy-override-attributes>
<last-modified>2009-03-24 15:27:38</last-modified>
<modified-by>dbmportal</modified-by>
</proxy-override-attribute-group>
</result>
</target>
</response>

deleteProxyOverride Use the deleteProxyOverrideAttributeGroup operation to delete proxy override

AttributeGroupBy attribute groups. Only use this API operation after installing the Proxy Database
Name Configuration optionality package. Before using proxy APIs, set the
ReadProxyConfigFromDB attribute in the proxies.xml file to ‘Y’.
These elements are required:
• proxy override attribute group name to delete <name>

Request
<request version="2.0" principal="<principal>" credentials="<credentials>">
<target name="ProxyOverrideAttributeGroupAPI"
operation="deleteProxyOverrideAttributeGroupByName">
<parameter>
<proxy-override-attribute-group>
<name>POAG1</name>
</proxy-override-attribute-group>
</parameter>
</target>
</request>

Page 190 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Response
<response version="2.0">
<target name="ProxyOverrideAttributeGroupAPI"
operation="deleteProxyOverrideAttributeGroupByName">
<result/>
</target>
</response>

Proxy Required Attribute Group API

This section describes the following Proxy Required Attribute Group operations:
• createProxyRequiredAttributeGroup
• updateProxyRequiredAttributeGroup
• getProxyRequiredAttributeGroupByName
• deleteProxyRequiredAttributeGroupByName

createProxyRequired Use the createProxyRequiredAttributeGroup operation to create proxy required

AttributeGroup attribute groups. Only use this API operation after installing the Proxy Database
Configuration optionality package. Before using proxy APIs, set the
ReadProxyConfigFromDB attribute in the proxies.xml file to ‘Y’.
These elements are required:
• group name <proxy-required-attribute-group>
• attribute for the required attribute <attribute-name>

Request
<request version="2.0" principal="dbmportal" credentials="dbmportal">
<target name="ProxyRequiredAttributeGroupAPI"
operation="createProxyRequiredAttributeGroup">
<parameter>
<proxy-required-attribute-group>
<name>PRAG1</name>
<description>prag1</description>
<proxy-required-attributes>
<proxy-required-attribute>
<attribute-name>Class</attribute-name>
<vendor-name>RFC2138</vendor-name>
</proxy-required-attribute>
<proxy-required-attribute>
<attribute-name>AAA</attribute-name>
<vendor-name>STARENT</vendor-name>
</proxy-required-attribute>
</proxy-required-attributes>
</proxy-required-attribute-group>

Service Controller 9.6.1-AAA October 26, 2012 Page 191

Chapter 4 Provisioning APIs Provisioning API Guide

</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="ProxyRequiredAttributeGroupAPI"
operation="createProxyRequiredAttributeGroup">
<result>
<proxy-required-attribute-group>
<id>781</id>
</proxy-required-attribute-group>
</result>
</target>
</response>

updateProxyRequire Use the updateProxyRequiredAttributeGroup operation to update information about

dAttributeGroup a proxy required attribute group. Only use this API operation after installing the
Proxy Database Configuration optionality package. Before using proxy APIs, set the
ReadProxyConfigFromDB attribute in the proxies.xml file to ‘Y’.
These elements are required:
• current group name <qualified-name>
• name for required attribute <attribute-name>
These elements are optional:
• new group name <name>
• group description <description>
• list of proxy required attributes for the group <proxy required attributes>
• vendor name for required attribute (default = RFC2138) <vendor name>
• delete a required attribute from the group <proxy-required-attribute
delete="true">

Request
<request version="2.0" principal="dbmportal" credentials="dbmportal">
<target name="ProxyRequiredAttributeGroupAPI"
operation="updateProxyRequiredAttributeGroup">
<parameter>
<proxy-required-attribute-group>
<qualified-name>PRAG1</qualified-name>
<name>PRAG1new</name>
<description>prag1new</description>
<proxy-required-attributes>
<proxy-required-attribute delete="true">

Page 192 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<attribute-name>Class</attribute-name>
</proxy-required-attribute>
<proxy-required-attribute delete="true">
<attribute-name>AAA</attribute-name>
<vendor-name>STARENT</vendor-name>
</proxy-required-attribute>
<proxy-required-attribute>
<attribute-name>Framed-Id</attribute-name>
</proxy-required-attribute>
<proxy-required-attribute>
<attribute-name>Framed-IP-Address</attribute-name>
<vendor-name>ACC</vendor-name>
</proxy-required-attribute>
</proxy-required-attributes>
</proxy-required-attribute-group>
</parameter>
</target>
</request>

getProxyRequired Use the getProxyRequiredAttributeGroup operation to retrieve information about a

AttributeGroupBy proxy required attribute group. Only use this API operation after installing the Proxy
Name Database Configuration optionality package. Before using proxy APIs, set the
ReadProxyConfigFromDB attribute in the proxies.xml file to ‘Y’.
These elements are required:
• name of the group to retrieve <name>

Request
<request version="2.0" principal="dbmportal" credentials="dbmportal">
<target name="ProxyRequiredAttributeGroupAPI"
operation="getProxyRequiredAttributeGroupByName">
<parameter>
<proxy-required-attribute-group>
<name>PRAG1new</name>
</proxy-required-attribute-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="ProxyRequiredAttributeGroupAPI"
operation="getProxyRequiredAttributeGroupByName">
<result>

Service Controller 9.6.1-AAA October 26, 2012 Page 193

Chapter 4 Provisioning APIs Provisioning API Guide

<proxy-required-attribute-group>
<id>781</id>
<configuration-id>1</configuration-id>
<name>PRAG1new</name>
<description>prag1new</description>
<proxy-required-attributes>
<proxy-required-attribute>
<attribute-name>Framed-Id</attribute-name>
<vendor-name>RFC2138</vendor-name>
</proxy-required-attribute>
<proxy-required-attribute>
<attribute-name>Framed-IP-Address</attribute-name>
<vendor-name> ACC </vendor-name>
</proxy-required-attribute>
</proxy-required-attributes>
<last-modified>2009-03-17 15:03:52</last-modified>
<modified-by>dbmportal</modified-by>
</proxy-required-attribute-group>
</result>
</target>
</response>

deleteProxyRequired Use the deleteProxyRequiredAttributeGroup operation to retrieve information about

AttributeGroupBy a proxy required attribute group. Only use this API operation after installing the
Name Proxy Database Configuration optionality package. Before using proxy APIs, set the
ReadProxyConfigFromDB attribute in the proxies.xml file to ‘Y’.
These elements are required:
• name of the group to delete <name>

Request
<request version="2.0" principal="dbmportal" credentials="dbmportal">
<target name="ProxyRequiredAttributeGroupAPI"
operation="deleteProxyRequiredAttributeGroupByName">
<parameter>
<proxy-required-attribute-group>
<name>PRAG1new</name>
</proxy-required-attribute-group>
</parameter>
</target>
</request>

Response
<response version="2.0">

Page 194 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<target name="ProxyRequiredAttributeGroupAPI"
operation="deleteProxyRequiredAttributeGroupByName">
<result/>
</target>
</response>

RADIUS Server (proxy target) API

This section describes the following RADIUS Server (proxy target) operations:
• createRADIUSServer
• updateRADIUSServer
• getRADIUSServerByName
• deleteRADIUSServerByName
Table 24 lists the required and optional attributes for RADIUS Server operations.
Table 24: Elements used in the create, update, get, and delete RADIUSServer operations

XML elements Description

<radius-server> Name of the RADIUS server (proxy target).

<name>RADIUS Server 1</name> Required.

<host>RADIUSServer1</host> Hostname of the RADIUS server.

Required.

<secret>mysecret</secret> Shared secret used when communicating with the target server.
Required.

<request-timeout>10</request-timeout> The number of seconds before retrying, failing over, or rejecting a

request.
Required.

<authentication-port>1234</authentication-port> The UDP port that the RADIUS proxy target listens on for RADIUS
authentication messages.
Default = 1812
Optional.

<accounting-port>2345</accounting-port> The UDP port that the RADIUS proxy target listens on for RADIUS
accounting messages.
Default = 1813
Optional.

<dae-port> The UDP port that the RADIUS proxy target listens on for DAE
messages.
Optional.

Service Controller 9.6.1-AAA October 26, 2012 Page 195

Chapter 4 Provisioning APIs Provisioning API Guide

Table 24: Elements used in the create, update, get, and delete RADIUSServer operations (continued)

XML elements Description

<overwrite-ip> Y — replace a static IP address in a proxy authentication reply by an IP

address assigned by the RADIUS Server (default).
N — do not overwrite the IP address.
Optional.

<strip-domain> Y — the RADIUS Server removes the domain from the login name when
forwarding an Access-Request.
This removes any domain, including a domain appended or replaced by
a RADIUS policy rule.
The domain is still used for local authorization and is stored in local
accounting records.
N — do not strip the domain (default).
Optional.

<digitize-acct-session-id> Y — convert characters to digits in the Accounting Session ID attribute

when forwarding to the proxy target.
N — do not convert characters in the Accounting Session ID attribute
(default).
Optional.

<max-retries> Maximum number of times the RADIUS Server attempts to contact the
proxy target before the request is dropped.
Default = 0
Optional.

<consecutive-lockout-enabled> Y — enable consecutive lockout.

N — disable consecutive lockout (default).
Optional.

<consecutive-retry-cycles> Y — enable consecutive lockout.

N — disable consecutive lockout (default).
Optional.

<consecutive-failure-lockout-duration> The length of time, in seconds, that a proxy target is locked out due to
consecutive retry cycle failures.
Default = 900.
Optional.

<intermittent-failure-lockout-enabled> Y — lockout a server that is partially failing, possibly due to an unreliable

network or a failure in a proxy chaining scenario.
N — Do not lock out the server (default).
Optional.

<intermittent-failure-lockout-duration> The time, in seconds, during which the proxy is not available due to
consecutive retry failures.
Default = 900.
Optional.

Page 196 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Table 24: Elements used in the create, update, get, and delete RADIUSServer operations (continued)

XML elements Description

<intermittent-failure-interval-length The time, in seconds, during which intermittent failure is tracked on an

unresponsive proxy target.
Default = 900.
Optional.

<intermittent-failure-minimum-requests> The number of failed requests, specified as a percentage, required for

the interval to be considered ‘failed’.
Default = 1.
Optional.

<intermittent-failure-percentage-failure-threshold> The number of failed requests, specified as a percentage, required for

the interval to be considered ‘failed’.
Default = 100.
Optional.

<intermittent-failure-successive-failed-intervals> The number of successive failed intervals before a proxy target lockout
occurs.
Default = 1.
Optional.

<add-message-authenticator> Y — insert the RADIUS Message-Authenticator attribute into requests

sent to this target.
N — do not insert the RADIUS message-authenticator attribute into
requests.
Optional.

<attribute-encryption> Y — all RADIUS attributes in the messages sent to the proxy target are
encrypted.
N — encryption is disabled.
Optional.

<proxy-in-action> The proxy filters defined by the child elements <proxy-filter>,

<proxy-required-attribute-group>, and <proxy-override-attribute-group>
are applied to incoming requests.
Optional.

<proxy-filter> Child of <proxy-in-action>.

Defines a proxy filter that is applied to all incoming requests.
Optional.

<proxy-required-attribute-group> Child of <proxy-in-action>.

Defines the attributes required for incoming requests.
Optional.

<proxy-override-attribute-group> Child of <proxy-in-action>.

Defines the override attributes for incoming requests.
Optional.

Service Controller 9.6.1-AAA October 26, 2012 Page 197

Chapter 4 Provisioning APIs Provisioning API Guide

Table 24: Elements used in the create, update, get, and delete RADIUSServer operations (continued)

XML elements Description

<proxy-out-actions> The proxy filters defined by the child elements <proxy-filter>,

<proxy-required-attribute-group>, and <proxy-override-attribute-group>
are applied to outgoing requests.
Optional.

<proxy-out-action> Child element of <proxy-out-actions>.

Use this element to individually define the <proxy-filter>,
<proxy-required-attribute-group>, and <proxy-override-attribute-group>
elements.
Optional.

<type> Child element of <proxy-out-action>.

Defines the type of out action for the <proxy-out-action> element.
Values are:
• All
• Auth
• Acct
• DAE
Required: if using a proxy out action.

<proxy-filter> Child element of <proxy-out-action>.

Assign a proxy filter to the out action.
Optional.

<proxy-required-attribute-group> Child element of <proxy-out-action>.

Assign a proxy required attribute group to the out action.
Optional.

<proxy-override-attribute-group> Child element of <proxy-out-action>.

Assign a proxy override attribute group to the out action.
Optional.

createRADIUSServer Use the createRADIUSServer operation to create a RADIUS Server (proxy target).
Only use this API operation after installing the Proxy Database Configuration
optionality package. Before using proxy APIs, set the ReadProxyConfigFromDB
attribute in the proxies.xml file to ‘Y’.
For required and optional attributes that can be used in this operation, see Table 24
on page 195.

Request
<request version="2.0" principal="<principal>" credentials="<credentials>">
<target name="RADIUSServerAPI" operation="createRADIUSServer">
<parameter>
<radius-server>
<name>RADIUS Server 1</name>

Page 198 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<host>RADIUSServer1</host>
<secret>mysecret</secret>
<authentication-port>1234</authentication-port>
<accounting-port>2345</accounting-port>
<request-timeout>10</request-timeout>
</radius-server>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="RADIUSServerAPI" operation="createRADIUSServer">
<result>
<radius-server>
<id>1070</id>
</radius-server>
</result>
</target>
</response>

updateRADIUSServer Use the deleteProxyRequiredAttributeGroup operation to retrieve information about

a proxy required attribute group. Only use this API operation after installing the
Proxy Database Configuration optionality package. Before using proxy APIs, set the
ReadProxyConfigFromDB attribute in the proxies.xml file to ‘Y’.
These elements are required:
• qualified name for the RADIUS server to be updated <qualified-name>
For required and optional attributes that can be used in this operation, see Table 24
on page 195.

Request
<request version="2.0" principal="<principal>" credentials="<credentials>">
<target name="RADIUSServerAPI" operation="updateRADIUSServer">
<parameter>
<radius-server>
<qualified-name>RADIUS Server 1</qualified-name>
<proxy-in-action>
<proxy-filter>
<name>Proxy Filter 1</name>
</proxy-filter>
</proxy-in-action>
</radius-server>
</parameter>

Service Controller 9.6.1-AAA October 26, 2012 Page 199

Chapter 4 Provisioning APIs Provisioning API Guide

</target>
</request>

Response
<response version="2.0">
<target name="RADIUSServerAPI" operation="updateRADIUSServer">
<result/>
</target>
</response>

getRADIUSServerBy Use the deleteProxyRequiredAttributeGroup operation to retrieve information about

Name a proxy required attribute group. Only use this API operation after installing the
Proxy Database Configuration optionality package. Before using proxy APIs, set the
ReadProxyConfigFromDB attribute in the proxies.xml file to ‘Y’.
These elements are required:
• RADIUS server name to retrieve
For information about all elements that can be used in this operation, see Table 24
on page 195.

Request
<request version="2.0" principal="<principal>" credentials="<credentials>">
<target name="RADIUSServerAPI" operation="getRADIUSServerByName">
<parameter>
<radius-server include-actions="true">
<name>RADIUS Server 1</name>
</radius-server>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="RADIUSServerAPI" operation="getRADIUSServerByName">
<result>
<radius-server>
<id>1070</id>
<configuration-id>1</configuration-id>
<name>RADIUS Server 1</name>
<host>RADIUSServer1</host>
<secret>mysecret</secret>
<authentication-port>1234</authentication-port>
<accounting-port>2345</accounting-port>
<request-timeout>10</request-timeout>

Page 200 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<proxy-in-action>
<id>1071</id>
<configuration-id>1</configuration-id>
<proxy-filter>
<id>847</id>
<configuration-id>1</configuration-id>
<name>Proxy Filter 1</name>
<description>testing</description>
<last-modified>2009-03-23 22:51:44</last-modified>
<modified-by>admin</modified-by>
</proxy-filter>
</proxy-in-action>
<last-modified>2009-03-24 10:16:40</last-modified>
<modified-by>admin</modified-by>
</radius-server>
</result>
</target>
</response>

deleteRADIUSServer Use the deleteProxyRequiredAttributeGroup operation to retrieve information about

ByName a proxy required attribute group. Only use this API operation after installing the
Proxy Database Configuration optionality package. Before using proxy APIs, set the
ReadProxyConfigFromDB attribute in the proxies.xml file to ‘Y’.
These elements are required:
• RADIUS server name to delete
For information about all elements that can be used in this operation, see Table 24
on page 195.
Request
<request version="2.0" principal="<principal>" credentials="<credentials>">
<target name="RADIUSServerAPI"
operation="deleteRADIUSServerByName">
<parameter>
<radius-server>
<name>RADIUS Server 1</name>
</radius-server>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="RADIUSServerAPI"

Service Controller 9.6.1-AAA October 26, 2012 Page 201

Chapter 4 Provisioning APIs Provisioning API Guide

operation="deleteRADIUSServerByName">
<result/>
</target>
</response>

RADIUS Server Group API

This section describes the following RADIUS Server (proxy target) operations:
• createRADIUSServerGroup
• updateRADIUSServerGroup
• getRADIUSServerGroupByName
• deleteRADIUSServerGroupByName
Table 25 lists the required and optional attributes for RADIUS Server Group
operations
Table 25: Elements used in the create, update, get, and delete RADIUSServerGroup operations

XML elements Description

<radius-server-group> Name of the RADIUS Server group (proxy target group).

<name>RADIUS Server group</name> Required.

<description> Child of <radius-server-group>.

Description of the RADIUS Server group.
Optional.

<failover> Y (default) — the RADIUS Server fails over to an ordered list of

alternative proxy targets, which is defined in the proxy target group.
Example: if no response is received from the first target within the
"RequestTimeout" duration, the message is sent to the second target.
N — The RADIUS Server does not failover.
Optional.

<max-concurrent-lockout> The number of proxy targets that can be locked out per proxy group.
If this parameter is set to less than the number of proxy targets in the
group, when the network reaches the assigned maximum, any proxy
targets that are candidates for lockout remain unlocked.
Optional.

<dynamic-unlock> Y (default) — the RADIUS Server dynamically unlocks a proxy target if all
proxy targets within a proxy target group are locked.
When all targets are locked, a single thread sends a message to the next
RADIUS target following the standard loadshare and failover rules for the
group. If a target is responsive, it is unlocked and used by all threads.
N — the proxy target is unlocked when the Consecutive Failure Lockout
Duration and/or Intermittent Failure Lockout Duration interval expires.
Proxy targets can also be manually unlocked.
Optional.

Page 202 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Table 25: Elements used in the create, update, get, and delete RADIUSServerGroup operations (continued)

XML elements Description

<max-failover-limit> When Failover is enabled, configure the maximum number of targets to

attempt in the group.
This parameter is ignored when Failover is disabled.
Optional.

<load-sharing> Y — the RADIUS Server distributes requests to an ordered list of

alternative proxy targets as defined in the proxy target group.
Example: one request is sent to the first proxy target, the next request is
sent to the next listed target.
N — loadsharing is disabled.
Optional.

<radius-servers> List of RADIUS Servers.

Required.

<radius-server> Specify a RADIUS Server.

Required.

<name> The name of the specified RADIUS Server.

Required.

<add-message-authenticator> Y — insert the RADIUS Message-Authenticator attribute into requests

sent to this target.
N — do not insert the RADIUS message-authenticator attribute into
requests.
Optional.

<proxy-in-action> The proxy filters defined by the child elements <proxy-filter>,

<proxy-required-attribute-group>, and <proxy-override-attribute-group>
are applied to incoming requests.
Optional.

<proxy-filter> Child of <proxy-in-action>.

Defines a proxy filter that is applied to all incoming requests in the group.
Optional.

<proxy-required-attribute-group> Child of <proxy-in-action>.

Defines the attributes required for incoming requests to the group.
Optional.

<proxy-override-attribute-group> Child of <proxy-in-action>.

Defines the override attributes for incoming requests to the group.
Optional.

<proxy-out-actions> The proxy filters defined by the child elements <proxy-filter>,

<proxy-required-attribute-group>, and <proxy-override-attribute-group>
are applied to outgoing requests from the group.
Optional.

Service Controller 9.6.1-AAA October 26, 2012 Page 203

Chapter 4 Provisioning APIs Provisioning API Guide

Table 25: Elements used in the create, update, get, and delete RADIUSServerGroup operations (continued)

XML elements Description

<proxy-out-action> Child element of <proxy-out-actions>.

Use this element to individually define the <proxy-filter>,
<proxy-required-attribute-group>, and <proxy-override-attribute-group>
elements.
Optional.

<type> Child element of <proxy-out-action>.

Defines the type of out action for the <proxy-out-action> element.
Values are:
• All
• Auth
• Acct
• DAE
Required: if using a proxy out action.

<proxy-filter> Child element of <proxy-out-action>.

Assign a proxy filter to the out action for the group.
Optional.

<proxy-required-attribute-group> Child element of <proxy-out-action>.

Assign a proxy required attribute group to the out action.
Optional.

<proxy-override-attribute-group> Child element of <proxy-out-action>.

Assign a proxy override attribute group to the out action.
Optional.

Page 204 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

createRADIUSServer Use the createRADIUSServerGroup operation to create a group of proxy targets.

Group Only use this API operation after installing the Proxy Database Configuration
optionality package. Before using proxy APIs, set the ReadProxyConfigFromDB
attribute in the proxies.xml file to ‘Y’.
These elements are required:
• RADIUS server group name <name>
• list of RADIUS servers <radius-servers>
• RADIUS server <radius-server>
• RADIUS server name <name>
For information about all elements that can be used in this operation, see Table 25
on page 202.

Request
<request version="2.0" principal="<principal>" credentials="<credentials>">
<target name="RADIUSServerGroupAPI"
operation="createRADIUSServerGroup">
<parameter>
<radius-server-group>
<name>RADIUS Server Group 1</name>
<radius-servers>
<radius-server>
<name>RADIUS Server 1</name>
</radius-server>
</radius-servers>
</radius-server-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="RADIUSServerGroupAPI"
operation="createRADIUSServerGroup">
<result>
<radius-server-group>
<id>1072</id>
</radius-server-group>
</result>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 205

Chapter 4 Provisioning APIs Provisioning API Guide

updateRADIUSServer Use the updateRADIUSServerGroup operation to modify a group of proxy targets.

Group Only use this API operation after installing the Proxy Database Configuration
optionality package. Before using proxy APIs, set the ReadProxyConfigFromDB
attribute in the proxies.xml file to ‘Y’.
These elements are required:
• qualified name of the RADIUS server group to update <qualified-name>
For information about all elements that can be used in this operation, see Table 25
on page 202.

Request
<request version="2.0" principal="<principal>" credentials="<credentials>">
<target name="RADIUSServerGroupAPI"
operation="updateRADIUSServerGroup">
<parameter>
<radius-server-group>
<qualified-name>RADIUS Server Group 1</qualified-name>
<radius-servers>
<radius-server>
<name>RADIUS Server 2</name>
</radius-server>
</radius-servers>
<proxy-out-actions>
<proxy-out-action>
<type>Auth</type>
<proxy-filter>
<name>Proxy Filter 1</name>
</proxy-filter>
</proxy-out-action>
</proxy-out-actions>
</radius-server-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="RADIUSServerGroupAPI"
operation="updateRADIUSServerGroup">
<result/>
</target>
</response>

Page 206 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

getRADIUSServer Use the getRADIUSServerGroupByName operation to retrieve a group of proxy

GroupByName targets. Only use this API operation after installing the Proxy Database
Configuration optionality package. Before using proxy APIs, set the
ReadProxyConfigFromDB attribute in the proxies.xml file to ‘Y’.
These elements are required:
• RADIUS server group name to retrieve <name>
For information about all elements that can be used in this operation, see Table 25
on page 202.

Request
<request version="2.0" principal="<principal>" credentials="<credentials>">
<target name="RADIUSServerGroupAPI"
operation="getRADIUSServerGroupByName">
<parameter>
<radius-server-group include-radius-servers="true"
include-actions="true">
<name>RADIUS Server Group 1</name>
</radius-server-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="RADIUSServerGroupAPI"
operation="getRADIUSServerGroupByName">
<result>
<radius-server-group>
<id>1072</id>
<configuration-id>1</configuration-id>
<name>RADIUS Server Group 50</name>
<radius-servers>
<radius-server order="0">
<id>104</id>
<configuration-id>1</configuration-id>
<name>RADIUS Server 1</name>
<description>RADIUS Server 1</description>
<last-modified>2009-02-06 13:23:28</last-modified>
<modified-by>admin</modified-by>
</radius-server>
<radius-server order="1">
<id>105</id>
<configuration-id>1</configuration-id>

Service Controller 9.6.1-AAA October 26, 2012 Page 207

Chapter 4 Provisioning APIs Provisioning API Guide

<name>RADIUS Server 2</name>

<description>RADIUS Server 2</description>
<last-modified>2009-02-06 13:23:55</last-modified>
<modified-by>admin</modified-by>
</radius-server>
</radius-servers>
<proxy-out-actions>
<proxy-out-action>
<id>1073</id>
<configuration-id>1</configuration-id>
<proxy-filter>
<id>847</id>
<configuration-id>1</configuration-id>
<name>Proxy Filter 1</name>
<description>testing</description>
<last-modified>2009-03-23 22:51:44</last-modified>
<modified-by>admin</modified-by>
</proxy-filter>
<type>Auth</type>
</proxy-out-action>
</proxy-out-actions>
<last-modified>2009-03-24 10:49:37</last-modified>
<modified-by>admin</modified-by>
</radius-server-group>
</result>
</target>
</response>

deleteRADIUSServer Use the deleteRADIUSServerGroupByName operation to delete a group of proxy

GroupByName targets. Only use this API operation after installing the Proxy Database
Configuration optionality package. Before using proxy APIs, set the
ReadProxyConfigFromDB attribute in the proxies.xml file to ‘Y’.
These elements are required:
• RADIUS server group name to delete <name>
For information about all elements that can be used in this operation, see Table 25
on page 202.

Request
<request version="2.0" principal="<principal>" credentials="<credentials>">
<target name="RADIUSServerGroupAPI"
operation="deleteRADIUSServerGroupByName">
<parameter>
<radius-server-group>

Page 208 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<name>RADIUS Server Group 1</name>

</radius-server-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="RADIUSServerGroupAPI"
operation="deleteRADIUSServerGroupByName">
<result/>
</target>
</response>

RADIUS proxy service API

Use the RADIUS proxy service enables administrators to assign proxy target
groups to a service entity, such as a user, profile set, or organization.
Insert elements, defined by the following XML example, into operations, such as
updateUser, in order to assign a proxy service to that entity.
The following table describes the required and optional elements used to assign a
RADIUS proxy service to a service entity, such as a user.

Table 26: Elements used to assign a RADIUS proxy service to a service entity

XML element Description

<qualified-name> Child element of <radius-proxy-service>.

Name of the RADIUS Proxy Service service profile.
Required.

<default-proxy-target-group> Child element of <radius-proxy-profile>.

Container tag for specifying the default proxy target group.
Optionally, use the delete flag to remove a default proxy target group.
Optional.

<proxy-target-group> Child element of <default-proxy-target-group>.

Specify a default proxy target group to filter all RADIUS messages.
Optional.

Service Controller 9.6.1-AAA October 26, 2012 Page 209

Chapter 4 Provisioning APIs Provisioning API Guide

Table 26: Elements used to assign a RADIUS proxy service to a service entity (continued)

XML element Description

<proxy-target-level> Child element of <default-proxy-target-group>.

Specify the authorization level to define whether the remote or local
server supplies the RADIUS attributes.
Values are:
• <empty> — delete the proxy target level
• full local — service RADIUS attributes returned from the proxy
target are ignored; the RADIUS Server uses the attributes defined
locally
• local override remote — merge RADIUS attributes from local and
remote servers, but, in the case of identical attributes, give
precedence to local attributes
• remote override local — merge RADIUS attributes from local and
remote servers, but, in the case of identical attributes, give
precedence to remote attributes

<access-proxy-target-group> Child element of <radius-proxy-service>.

Container tag for specifying the proxy target group used for RADIUS
Access-Request messages.
Optional.

<proxy-target-group> Child element of <access-proxy-target-group>.

Specify a proxy target group used for RADIUS Access-Request
messages.
Optional.

<proxy-target-level> Child element of <access-proxy-target-group>.

Specify the authorization level to define whether the remote or local
server supplies the RADIUS attributes.
Values are:
• <empty> — delete the proxy target level
• full local — RADIUS service attributes returned from the proxy
target are ignored; the RADIUS Server uses the attributes defined
locally
• local override remote — merge RADIUS attributes from local and
remote servers, but, in the case of identical attributes, give
precedence to local attributes
• remote override local — merge RADIUS attributes from local and
remote servers, but, in the case of identical attributes, give
precedence to remote attributes

<accounting-proxy-target-group> Child element of <radius-proxy-service>.

Container tag for specifying the proxy target group used for RADIUS
Accounting-Request messages.
Optional.

Page 210 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Table 26: Elements used to assign a RADIUS proxy service to a service entity (continued)

XML element Description

<proxy-target-group> Child element of <accounting-proxy-target-group>.

Specify a proxy target group used for RADIUS Accounting-Request
messages.
Optional.

Add RADIUS proxy This example inserts RADIUS proxy service XML elements into the operation
service using updateUser. The RADIUS proxy service XML is in bold.
updateUser Only use this API operation after installing the Proxy Database Configuration
operation optionality package. Before using proxy APIs, set the ReadProxyConfigFromDB
attribute in the proxies.xml file to ‘Y’.

Request
<request version="2.0" principal="dbmportal" credentials="dbmportal">
<target name="UserAPI" operation="updateUser">
<parameter>
<user>
<login-name>user1</login-name>
<name>user1</name>
<password><value>user1</value></password>
<organization><qualified-name>/</qualified-name></organization>
<domain><name>null</name></domain>
<profile-set>
<qualified-name>/UPS1</qualified-name>
<radius-proxy-profile>
<qualified-name>/RPSP1</qualified-name>
<default-proxy-target-group>
<proxy-target-group>RadiusServerGroup1
</proxy-target-group>
<proxy-target-level>full local</proxy-target-level>
</default-proxy-target-group>
<access-proxy-target-group>
<proxy-target-group>RadiusServerGroup3
</proxy-target-group>
</access-proxy-target-group>
<accounting-proxy-target-group delete="true">
</accounting-proxy-target-group>
</radius-proxy-profile>
</profile-set>
</user>
</parameter>

Service Controller 9.6.1-AAA October 26, 2012 Page 211

Chapter 4 Provisioning APIs Provisioning API Guide

</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="updateUser">
<result/>
</target>
</response>

ServiceAPI operations
This section describes the getService ServiceAPI operation.

getService
Use the getService operation to retrieve service information and, optionally, service
class context (SC) profile attributes.
These elements are required:
• the service id or service name to identify the service
These elements are optional:
• a get-attributes flag to indicate that profile attributes should be returned

Get RADIUS QoS This example shows how to get service class context profile attributes for the
selection policy RADIUS QoS selection policy service class.
service attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="ServiceAPI" operation="getService">
<parameter>
<service get-attributes="true">
<name>RADIUS QoS Selection Policy</name>
</service>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="ServiceAPI" operation="getService">
<result>
<service>
<id>18</id>

Page 212 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<name>RADIUS QoS Selection Policy</name>

<description>
RADIUS QoS Selection Policy Service Class
</description>
<category>Connection Services</category>
<status><value>active</value></status>
<version>1</version>
<attribute name="QoSPolicyType">
<value context="service"
subscript="0">static</value>
<value context="service"
subscript="1">access</value>
</attribute>
<attribute name="QoSPolicyType:access">
<value context="service" subscript="0">
local
</value>
<value context="service" subscript="1">
roaming
</value>
</attribute>
</service>
</result>
</target>
</response>

createUser

Request
<request version="1.0" principal="root" credentials="nirav">
<target name="ServiceAPI" operation="createUser">
<parameter>
<user>
<name>abcdef</name>
<login-name>abcdef</login-name>
<organization>
<qualified-name>Root Organization</qualified-name>
</organization>
<password>
<value>cricket</value>
</password>
<mobile>
<id-number>9899101267</id-number>

Service Controller 9.6.1-AAA October 26, 2012 Page 213

Chapter 4 Provisioning APIs Provisioning API Guide

</mobile>
<status>
<value>active</value>
</status>
<profile-set>
<qualified-name>/niravtest</qualified-name>
<profile>
<qualified-name>/niravtest</qualified-name>
<service>
<name>RADIUS ConnectionService</name>
</service>
<user-authorized-profile>
<application>
<name>SMS</name>
<authentication-required>
false
</authentication-required>
<subscribed>true</subscribed>
<attribute name="CoS">
<value>21</value>
</attribute>
<attribute name="Unlimited">
<value>No</value>
</attribute>
</application>
</user-authorized-profile>
</profile>
</profile-set>
</user>
</parameter>
</target>
</request>

deleteUser

Request
<request version="1.0" principal="root" credentials="nirav">
<target name="ServiceAPI" operation="deleteUser">
<parameter>
<user>
<name>abcdef</name>
<login-name>abcdef</login-name>
<organization>

Page 214 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<qualified-name>Root Organization</qualified-name>
</organization>
<mobile>
<id-number>9899101277</id-number>
</mobile>
<status>
<value>active</value>
</status>
<profile-set>
<qualified-name>/niravtest</qualified-name>
<profile>
<qualified-name>/niravtest</qualified-name>
<service>
<name>RADIUS ConnectionService</name>
</service>
<user-authorized-profile>
<application>
<name>SMS</name>
<authentication-required>
false
</authentication-required>
<subscribed>true</subscribed>
<attribute name="CoS">
<value>21</value>
</attribute>
<attribute name="Unlimited">
<value>No</value>
</attribute>
</application>
</user-authorized-profile>
</profile>
</profile-set>
</user>
</parameter>
</target>
</request>

updateUser

Request
<request version="1.0" principal="root" credentials="nirav">
<target name="ServiceAPI" operation="updateUser">
<parameter>

Service Controller 9.6.1-AAA October 26, 2012 Page 215

Chapter 4 Provisioning APIs Provisioning API Guide

<user>
<name>abcdef</name>
<login-name>abcdef</login-name>
<organization>
<qualified-name>Root Organization</qualified-name>
</organization>
<mobile>
<id-number>9899101277</id-number>
</mobile>
<status>
<value>active</value>
</status>
<profile-set>
<qualified-name>/niravtest</qualified-name>
<profile>
<qualified-name>/niravtest</qualified-name>
<service>
<name>RADIUS ConnectionService</name>
</service>
<user-authorized-profile>
<application>
<name>SMS</name>
<authentication-required>
false
</authentication-required>
<subscribed>true</subscribed>
<attribute name="CoS">
<value>21</value>
</attribute>
<attribute name="Unlimited">
<value>No</value>
</attribute>
</application>
</user-authorized-profile>
</profile>
</profile-set>
</user>
</parameter>
</target>
</request>

Page 216 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

SessionAPI operations
The SessionAPI operations enable the Provisioning Server to retrieve a device’s
session information from RMS and a device’s record from the Profile Database.
This section describes the following SessionAPI operations:
• getSessionStatusByLoginName
• getSessionStatusByIP
The SessionAPI operations can return the following elements:
• mac-address: the device's MAC address as specified in the CreateDevice
operation. The MAC address is always returned in upper case.
• domain: the realm value the device used for network entry.
• address: if a device is online, this element returns the device’s current IP
address.
• nas-ip-address: if a device is online, this element returns the IP address of the
access node the device is connected to.
• nas-id: the NAS-ID attribute from the access node.
• calling-station-id: the Calling-Station-ID attribute from the access node.
• ems-service-ip: if a device is online, this element returns the IP address of the
EMS server the access node is assigned to.
If the EMS Server IP is not provisioned against a NAS-Group or WiMAX Node
Group the ems-service-ip element is returned empty.
• bsid: the BSID attribute from the access node. If the BSID attribute is not found
in RMS, the Provisioning Server uses the value of the Called-Station-ID in
RMS. If Called-Station-ID is not present, the BSID is returned empty.

getSessionStatusByLoginName
The getSessionStatusByLoginName operation enables the Provisioning Server to
retrieve a device’s session information from RMS and a device’s record from the
Profile Database.
The getSessionStatusByLoginName uses the login-name and domain to query for
session information and a device record.

Get session status by This example shows a request for session information and a device record using
login name the login-name and domain.
This example also provides a successful response for a device online, a device not
online, and an error response when a device is not found.

Request
<request version="2.0" principal="APIUSER" credentials="APIPASSWORD">
<target name="SessionAPI" operation="getSessionStatusByLoginName">
<parameter>
<device>
<mac-address>001122AABBCC</mac-address>

Service Controller 9.6.1-AAA October 26, 2012 Page 217

Chapter 4 Provisioning APIs Provisioning API Guide

<domain>
<name>DOMAIN</name>
</domain>
</device>
</parameter>
</target>
</request>

Success response - device online

<response version="2.0">
<target name="SessionAPI" operation="getSessionStatusByLoginName">
<result>
<device>
<mac-address>001122AABBCC</mac-address>
<domain>
<name>DOMAIN</name>
</domain>
<address>
<value>192.168.150.1</value>
</address>
<nas-ip-address>10.0.0.33</nas-ip-address>
<nas-id>CAPC-1</nas-id>
<calling-station-id>001122AABBCC</calling-station-id>
<ems-service-ip>10.0.0.1</ems-service-ip>
<bsid>01abf1</bsid>
</device>
</result>
</target>
</response>

Success response - Device online, EMS Server IP not provisioned

<response version="2.0">
<target name="SessionAPI" operation="getSessionStatusByLoginName">
<result>
<device>
<mac-address>001122AABBCC</mac-address>
<domain>
<name>NAME</name>
</domain>
<address>
<value>192.168.150.1</value>
</address>
<nas-ip-address>10.0.0.33</nas-ip-address>

Page 218 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<nas-id>CAPC-1</nas-id>
<calling-station-id>001122AABBCC</calling-station-id>
<ems-service-ip></ems-service-ip>
<bsid>01abf1</bsid>
</device>
</result>
</target>
</response>

Error response - LoginName not found

<response version="2.0">
<target name="SessionAPI" operation="getSessionStatusByLoginName">
<error>
<code>SES-00013</code>
<message>Account user `invalid@example.net` not found</message>
</error>
</target>
</response>

Error response - LoginName exists but device is offline

<response version="2.0">
<target name="SessionAPI" operation="getSessionStatusByLoginName">
<error>
<code>SES-00014</code>
<message>Account user `000000000011@example.net` not online
</message>
</error>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 219

Chapter 4 Provisioning APIs Provisioning API Guide

getSessionStatusByIP
The getSessionStatusByIP operation enables the Provisioning Server to retrieve a
device’s session information from RMS and a device’s record from the Profile
Database.
The getSessionStatusByIP uses a device’s IP address to query for session
information and a device record.

Get session status by This example shows a request for session information and a device record using
IP the device’s IP address.
This example also provides a successful response for a device online, a device not
online, and an error response when a device is not found.

Request
<request version="2.0" principal="APIUSER" credentials="APIPASSWORD">
<target name="SessionAPI" operation="getSessionStatusByIP">
<parameter>
<device>
<ip-address>IPADDRESS</ip-address>
</device>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="SessionAPI" operation="getSessionStatusByIP">
<result>
<device>
<mac-address>MAC</mac-address>
<domain>
<name>DOMAIN</name>
</domain>
<address>
<value>IPADDRESS</value>
</address>
<nas-ip-address>NASIPADDRESS</nas-ip-address>
<nas-id>NASID</nas-id>
<calling-station-id>CALLINGSTATIONID</calling-station-id>
<ems-service-ip>EMSIPADDRESS</ems-service-ip>
<bsid>BSID</bsid>
</device>
</result>
</target>

Page 220 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</response>

Success response - Device online, EMS Server IP not provisioned

<response version="2.0">
<target name="SessionAPI" operation="getSessionStatusByIP">
<result>
<device>
<mac-address>001122AABBCC</mac-address>
<domain>
<name>NAME</name>
</domain>
<address>
<value>192.168.150.1</value>
</address>
<nas-ip-address>10.0.0.33</nas-ip-address>
<nas-id>CAPC-1</nas-id>
<calling-station-id>001122AABBCC</calling-station-id>
<ems-service-ip></ems-service-ip>
<bsid>01abf1</bsid>
</device>
</result>
</target>
</response>

Error response - device not found

<response version="2.0">
<target name="SessionAPI" operation="getSessionStatusByIP">
<error>
<code>SES-00014</code>
<message>Account user `31.22.33.41` not online</message>
</error>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 221

Chapter 4 Provisioning APIs Provisioning API Guide

SystemAPI operations
This section describes the applyChanges SystemAPI operation.

applyChanges
Use the applyChanges operation to notify other BWS components about changes
to the system configuration by signalling the network to reload the configuration.
Note Append the applyChanges operation after a system operation in the same
API request.

Update system This example shows how to commit the session changes to the system
configuration configuration.

Request
<request version="2.0" principal="user" credentials="password">
<target name="SystemAPI" operation="applyChanges">
<parameter>
<system-configuration/>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="SystemAPI" operation="applyChanges">
<result/>
</target>
</response>

Page 222 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

TrunkGroupAPI operations
This section describes the following TrunkGroupAPI operations:
• createTrunkGroup
• deleteTrunkGroup
• getTrunkGroup
• updateTrunkGroup
• updateTrunkGroups
Note Changes to the system configuration are committed to the Profile Database
when the API operation completes. To notify other BWS components about
any changes to the current system configuration, execute the
applyChanges operation. For details, see "applyChanges" on page 222.

createTrunkGroup
Use the createTrunkGroup operation to create a Trunk group.
These elements are required:
• the name of the Trunk group (1 to 50 characters)
• the total number of circuits, or capacity, that is available on the Trunk group
These elements are optional:
• the ID of the RMS that tracks login sessions on the Trunk group
• directory numbers for the Trunk group
• a range of directory numbers assigned to the Trunk group
The response returns the Trunk group with a Profile Database identifier.

Trunk group This example shows how to create a Trunk group.

Request
<request version="2.0" principal="user" credentials="password">
<target name="TrunkGroupAPI" operation="createTrunkGroup">
<parameter>
<trunk-group>
<name>trunkGroupName</name>
<capacity>100</capacity>
<rms-cluster-id>RMSID#</rms-cluster-id>
<directory-number-ranges>
<directory-number-range>
<range-start>DNR1start</range-start>
<range-end>DNR1end</range-end>
</directory-number-range>
<directory-number-range>
<range-start>DNR2start</range-start>

Service Controller 9.6.1-AAA October 26, 2012 Page 223

Chapter 4 Provisioning APIs Provisioning API Guide

<range-end>DNR2end</range-end>
</directory-number-range>
</directory-number-ranges>
<directory-numbers>
<directory-number>DN1</directory-number>
<directory-number>DN2</directory-number>
</directory-numbers>
</trunk-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="TrunkGroupAPI" operation="createTrunkGroup">
<result>
<trunk-group>
<id>62</id>
<system-element-class>
<name>Trunk Group</name>
</system-element-class>
</trunk-group>
</result>
</target>
</response>

deleteTrunkGroup
Use the deleteTrunkGroup operation to delete a Trunk group.
These elements are required:
• the name or ID of the Trunk group
Note A Trunk group that is assigned to a service entity, such as an Organization,
cannot be deleted.

Trunk group This example shows how to delete a Trunk group.

Request
<request version="2.0" principal="user" credentials="password">
<target name="TrunkGroupAPI" operation="deleteTrunkGroup">
<parameter>
<trunk-group>
<name>trunkGroupName</name>
</trunk-group>

Page 224 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="TrunkGroupAPI" operation="deleteTrunkGroup">
<result/>
</target>
</response>

getTrunkGroup
Use the getTrunkGroup operation to retrieve a fully-populated Trunk group.
These elements are required:
• the name or ID of the Trunk group
The response returns a fully-populated Trunk group.

Retrieve Trunk group This example shows how to retrieve information for a Trunk Group.
information
Request
<request version="2.0" principal="user" credentials="password">
<target name="TrunkGroupAPI" operation="getTrunkGroup">
<parameter>
<trunk-group>
<name>trunkGroupName</name>
</trunk-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="TrunkGroupAPI" operation="getTrunkGroup">
<result>
<trunk-group>
<id>62</id>
<configuration-id>1</configuration-id>
<system-element-class>
<id>6</id>
<configuration-id>1</configuration-id>
<name>Trunk Group</name>
</system-element-class>

Service Controller 9.6.1-AAA October 26, 2012 Page 225

Chapter 4 Provisioning APIs Provisioning API Guide

<name>trunkGroupName</name>
<caption>trunkGroupName</caption>
<status>
<value>active</value>
</status>
<last-modified>2008-11-27 15:50:22</last-modified>
<modified-by>admin</modified-by>
<rms-cluster-id>100</rms-cluster-id>
<capacity>100</capacity>
<maximum-public-sessions>100</maximum-public-sessions>
<directory-number-ranges>
<directory-number-range>
<range-start>1</range-start>
<range-end>3</range-end>
</directory-number-range>
<directory-number-range>
<range-start>4</range-start>
<range-end>7</range-end>
</directory-number-range>
</directory-number-ranges>
</trunk-group>
</result>
</target>
</response>

updateTrunkGroup
Use the updateTrunkGroup operation to modify a Trunk group.
These elements are required:
• the name or ID of the Trunk group
These elements are optional:
• the qualified name of the Trunk group (if renaming the Trunk group)
• the total number of circuits, or capacity, that is available on the Trunk group
• the ID of the RMS that tracks login sessions on the Trunk group
• directory numbers for the Trunk group
• a range of directory numbers assigned to the Trunk group

Change name This example shows how to modify the name of a Trunk group.

Request
<request version="2.0" principal="user" credentials="password">
<target name="TrunkGroupAPI" operation="updateTrunkGroup">

Page 226 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<parameter>
<trunk-group>
<qualified-name>
currentTrunkGroupName
</qualified-name>
<name>newTrunkGroupName</name>
<caption>newTrunkGroupName</caption>
</trunk-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="TrunkGroupAPI" operation="updateTrunkGroup">
<result/>
</target>
</response>

Change RMS cluster This example shows how to modify the RMS cluster tracks login sessions on the
Trunk group.

Request
<request version="2.0" principal="user" credentials="password">
<target name="TrunkGroupAPI" operation="updateTrunkGroup">
<parameter>
<trunk-group>
<name>trunkGroupName</name>
<rms-cluster-id>RMSID#</rms-cluster-id>
</trunk-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="TrunkGroupAPI" operation="updateTrunkGroup">
<result/>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 227

Chapter 4 Provisioning APIs Provisioning API Guide

updateTrunkGroups
Use the updateTrunkGroups operation to modify a set of Trunk groups.
These elements are required:
• the name or ID of the Trunk group
These elements are optional:
• the total number of circuits, or capacity, that is available on the Trunk group
• the ID of the RMS that tracks login sessions on the Trunk group
• directory numbers for the Trunk group
• a range of directory numbers assigned to the Trunk group

Change DNs and DN This example shows how to change the DN ranges of multiple Trunk groups.
ranges This operation replaces all number ranges for each trunk group specified with the
new number ranges, which:
• makes sure that the number ranges for each trunk group do not accumulate
• reduces the probability of failure for the updateTrunkGroups call because there
is less chance that number ranges overlap

Request
<request version="2.0" principal="user" credentials="password">
<target name="TrunkGroupAPI" operation="updateTrunkGroups">
<parameter>
<trunk-groups>
<trunk-group>
<name>trunkGroup1Name</name>
<directory-number-ranges>
<directory-number-range>
<range-start>TG1DNR1start</range-start>
<range-end>TG1DNR1end</range-end>
</directory-number-range>
...
<directory-number-range>
<range-start>TG1DNR2start</range-start>
<range-end>TG1DNR2end</range-end>
</directory-number-range>
</directory-number-ranges>
</trunk-group>
<trunk-group>
<name>trunkGroup2Name</name>
<directory-number-ranges>
<directory-number-range>
<range-start>TG2DNR1start</range-start>

Page 228 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<range-end>TG2DNR1end</range-end>
</directory-number-range>
...
<directory-number-range>
<range-start>TG2DNR2start</range-start>
<range-end>TG2DNR2end</range-end>
</directory-number-range>
</directory-number-ranges>
</trunk-group>
</trunk-groups>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="TrunkGroupAPI" operation="updateTrunkGroups">
<result/>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 229

Chapter 4 Provisioning APIs Provisioning API Guide

UserAPI operations
This section describes the following UserAPI operations:
• createUser
• createUserProfileSet
• deleteUser
• findUsers
• getUser
• getUserWithActiveServices
• getUserProfileSet
• updateUser
• updateUserProfileSet

createUser
Use the createUser operation to insert a subscriber record into the Profile
Database. To change a user name, the account must be deleted with the
deleteUser operation, and then recreated with a new createUser call.
These elements are required:
• the user name
– string, 1 to 80 characters
• the login name
– string, 1 to 80 characters
• the password
– string, 1 to 80 characters
• the organization to which the new user will belong (must already be present)
– specify either the organization qualified name or ID
– ID, if used, must be a positive integer
• a user profile set (must already be present)
– specify either the profile set qualified name and type (“user”), or the ID and
type
These elements are optional:
• the domain to which the user is assigned (must already be present)
– specify either the domain name or ID
• the account to which the user is assigned (must already be present)
– specify either the account name or ID
– account name must be 1 to 64 characters
• the status of the user at time of creation
– either active (default) or pending
• user context (U) profile attributes

Page 230 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

About password To define the password encryption <type> parameter, use one of the following
encryption options.
To encrypt a cleartext password using:
• North American UNIX, use the value “cleartext2unixna”
• BSD MD5, use the value “cleartext2bsdmd5 “
• 2-way MD5, use the value “cleartext2md5x”
Example:
<password>
<type>cleartext2md5x</type>
<value>mypassword</value>
</password>
Note If no value is given for the password <type> parameter, the password is
saved in the clear text format.

Prevent the creation This example shows how to prevent the creation of a user with the same name/
of a user with the login name as a user already present in the database.
same user/login
name Request
<request version="2.0" principal="provclient" credentials="MYSECRET">
<target name="ServiceAPI" operation="createUser">
<parameter>
<user xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://www.bridgewatersystems.com/schema/
bsr6/createUser.xsd">
<name>123456789012</name>
<login-name>123456789012</login-name>
<password >
<value>123456789012</value>
<type>cleartext</type>
<learn-password>false</learn-password>
<suspend-on-collision>true</suspend-on-collision>
</password>
<organization>
<qualified-name>Root Organization/</qualified-name>
</organization>
<status>
<value>active</value>
</status>
<modified-by>root@null</modified-by>
<billing>
<id>45</id>
<date>2012-07-26 10:03:56</date>

Service Controller 9.6.1-AAA October 26, 2012 Page 231

Chapter 4 Provisioning APIs Provisioning API Guide

<unit>month</unit>
<period>1</period>
</billing>
<profile-set>
<name>3040_ps</name>
</profile-set>
</user>
</parameter>
</target>
</request>

Response
This response is returned if a user is present in the database with the same user/
login name. The user status is set to suspended.
<response version="2.0">
<target name="ServiceAPI" operation="createUser">
<error>
<code>USR-00020</code>
<message>
A user with the same login name and password already exists.
Existing user account has been suspended due to potential security breach.
Change the password for user ‘15’ before reactivating the account.
</message>
</error>
</target>
</response>
If <suspend-on-collision> is set to false, the following response is returned. The
user status is not changed.
<response version="2.0">
<target name="ServiceAPI" operation="createUser">
<error>
<code>USR-00021</code>
<message>
A user with the same login name and password already exists.
</message>
</error>
</target>
</response>

Page 232 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Specified domain and This example shows how to create a user in a specified organization (org1) and
organization with a specified domain name (domain1.com).

Request
<request version="2.0" principal="User1" credentials="password">
<target name="UserAPI" operation="createUser">
<parameter>
<user>
<name>user1084374221</name>
<login-name>login1084374221</login-name>
<password>
<value>pwd1084374221</value>
</password>
<organization>
<qualified-name>/BWS</qualified-name>
</organization>
<domain><name>domain1.com</name></domain>
<profile-set>
<qualified-name>/Root User Profile Set
</qualified-name>
</profile-set>
</user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="createUser">
<result>
<user><id>6413</id></user>
</result>
</target>
</response>
The user ID returned within the <id></id> tags is the internal identifier of the created
object.

Generate a random This example shows how to generate a password for the user upon creation. When
password the <generate-password> element is set to true, the Service Controller generates a
password according to the rules defined for the user or the user’s service profile.
A password can also be generated with the updateUser operation.

Service Controller 9.6.1-AAA October 26, 2012 Page 233

Chapter 4 Provisioning APIs Provisioning API Guide

Request
<request version="2.0" principal="admin" credentials="rds32k2894l1k">
<target name="UserAPI" operation="createUser">
<parameter>
<user>
<name>exampleName</name>
<login-name>exampleLogin</login-name>
<password>
<generate-password>true</generate-password>
</password>
<organization>
<id>1</id>
</organization>
<profile-set>
<id>3</id>
</profile-set>
</user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="createUser">
<result>
<user>
<id>111</id>
</user>
</result>
</target>
</response>

Provisioned RADIUS This example shows how to create a user with provisioned user context RADIUS
connection service connection service and user information profile attributes.
profile attributes In this example, the profiles “User Information” and “Radius QoS Profile” must
already be present in the profile set psu1.
User provisioning may require setting multiple user context attributes. A quick
method to determine the required parameters for a new user is to call the getUser
operation for a user in the organization, then use the return values as a template to
create a new user.

Request
<request version="2.0" principal="User1" credentials="password">

Page 234 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<target name="UserAPI" operation="createUser">

<parameter>
<user>
<name>duser1</name>
<login-name>dlogin1</login-name>
<password>
<value>pswd1</value>
</password>
<organization>
<qualified-name>/BWS</qualified-name>
</organization>
<profile-set>
<qualified-name>/BWS/psu1</qualified-name>
<user-information-profile>
<qualified-name>User Information
</qualified-name>
<attribute name="foo">
<value context="user">val1</value>
</attribute>
<attribute name="foo2">
<value context="user"
subscript="0">val2</value>
</attribute>
<attribute name="foo3">
<value context="user"
subscript="0">val3</value>
</attribute>
<attribute name="foo4">
<value context="user"
subscript="0">shouldbechanged</value>
<value context="user"
subscript="1">shouldnotbechanged
</value>
<value context="user"
subscript="2">valueshouldbedeleted
</value>
</attribute>
<attribute name="shouldbedeleted">
<value context="user"
subscript="0">123</value>
</attribute>
</user-information-profile>
<profile>

Service Controller 9.6.1-AAA October 26, 2012 Page 235

Chapter 4 Provisioning APIs Provisioning API Guide

<qualified-name>/Radius QoS Profile

</qualified-name>
<attribute name="name1">
<value segment="segment">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
</profile>
</profile-set>
</user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="createUser">
<result>
<user>
<id>6414</id>
</user>
</result>
</target>
</response>
The user ID returned within the <id></id> tags is the internal identifier of the created
object.

Add WiMAX user This example shows how to add a user’s hotlineReason attribute for WiMAX
attributes hotlining configuration. The hotlineReason value corresponds to a bit action map
configured in hotlineConfig.xml and must be a 16 byte hex string.

Request
<request credentials="rds32k2894l1k" principal="admin" version="2.0">
<target name="UserAPI" operation="createUser">
<parameter>
<user>
<name>user1</name>
<login-name>user1</login-name>
<domain>
<name>null</name>
</domain>
<password>

Page 236 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<value>user1</value>
</password>
<organization>
<qualified-name>/</qualified-name>
</organization>
<profile-set>
<qualified-name>/Root User Profile Set</qualified-name>
</profile-set>
<user-attributes>
<user-attribute name="hotlineReason" type="string">
<value>0000000000000004</value>
</user-attribute>
</user-attributes>
</user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="createUser">
<result/>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 237

Chapter 4 Provisioning APIs Provisioning API Guide

Provisioning a billing Use This example to set the billing day at the User context.
day for a user <target name="UserAPI" operation="createUser">"
<parameter>
<user>
<login-name>lname</login-name>
<name>name</name>
<password>
<value>password</value>
</password>
<account-name>account</account-name>
<organization>
<qualified-name>qname</qualified-name>
</organization>
<profile-set>
<qualified-name>qname</qualified-name>
<user-information-profile>
<qualified-name>User Information</qualified-name>
<attribute name="BillingDay">
<value context="user">10</value>
</attribute>
</user-information-profile>
</profile-set>
</user>
</parameter>
</target>

createUserProfileSet
Use the createUserProfileSet operation to create a user profile set.
These elements are required:
• the profile set name
• the organization in which the profile set is to be created (must already be
present)
These elements are optional:
• a description of the profile set
• an inheritance flag to determine whether the profile set is available to
sub-organizations (default is yes)
• user group context (UG) profile attributes

Provisioned RADIUS This example shows how to create a user profile set with provisioned user group
connection service context RADIUS connection service profile attributes.
profile attributes

Page 238 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="UserAPI" operation="createUserProfileSet">
<parameter>
<user-profile-set>
<name>BWS User Profile Set</name>
<organization><id>4</id></organization>
<profile>
<id>5</id>
<attribute name="name1">
<value segment="seg1">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
</profile>
</user-profile-set>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="createUserProfileSet">
<result/>
</target>
</response>

deleteUser
Use the deleteUser operation removes a user and all of its associated attributes.
Specify one of:
• the user name and domain
• the user ID
• the login name (if login uniqueness is enabled)
• the login name and domain or password

Specified user This example shows how to delete a user with a specified login name (login1) and
domain name (domain1.com).

Request
<request version="2.0" principal="User1" credentials="password">

Service Controller 9.6.1-AAA October 26, 2012 Page 239

Chapter 4 Provisioning APIs Provisioning API Guide

<target name="UserAPI" operation="deleteUser">

<parameter>
<user>
<login-name>login1</login-name>
<domain><name>domain1.com</name></domain>
</user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="deleteUser">
<result/>
</target>
</response>

findUsers
The findUsers operation requests the Provisioning Server to return subscriber
information.

Find specified This example shows how search for subscriber information.
subscriber
Request
<request credentials="root" principal="root" version="2.0">
<target name="UserAPI" operation="findUsers">
<parameter>
<user-search>
<next-index>1</next-index>
<max-results>30</max-results>
<order-by>loginname</order-by>
<include-sub-organizations>false</include-sub-organizations>
<query-deleted-organizations>false</query-deleted-organizations>
<name>r*</name>
<organization>
<id>1</id>
<name>Root Organization</name>
</organization>
</user-search>
</parameter>
</target>
</request>

Page 240 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Response
<response version="2.0">
<target name="UserAPI" operation="findUsers">
<result>
<user-search>
<next-index>-1</next-index>
<max-results>30</max-results>
<order-by>loginname</order-by>
<query-deleted>false</query-deleted>
<include-sub-organizations>false</include-sub-organizations>
<query-deleted-organizations>false</query-deleted-organizations>
<name>r*</name>
<user>
<id>1</id>
<name>root</name>
<login-name>root</login-name>
<organization>
<id>1</id>
<name>Root Organization</name>
<status>
<value>active</value>
</status>
<implicit-status>
<value>active</value>
</implicit-status>
</organization>
<domain>
<id>1</id>
<name>null</name>
<status>
<value>active</value>
</status>
</domain>
<password>
<type>cleartext</type>
<value>root</value>
<learn-password>false</learn-password>
</password>
<status>
<value>active</value>
</status>
<implicit-status>
<value>active</value>

Service Controller 9.6.1-AAA October 26, 2012 Page 241

Chapter 4 Provisioning APIs Provisioning API Guide

</implicit-status>
<creation-date>2009-04-29 18:16:33</creation-date>
<last-modified>2009-04-29 18:16:33</last-modified>
<modified-by>creroot.sql</modified-by>
<billing>
<id>3</id>
<senior-billing-id>3</senior-billing-id>
</billing>
<profile-set>
<id>3</id>
<name>Root User Profile Set</name>
<type>user</type>
</profile-set>
</user>
</user-search>
</result>
</target>
</response>

getUser
Use the getUser operation to retrieve user profile information and, optionally, user
context (U) profile attributes.
These elements are required:
• the user name and domain
• the user ID
• the login name (if login uniqueness is enabled)
• the login name and domain or password
These elements are optional:
• an empty <profile> element to be populated with user context (U) attribute
information. All user profiles and attributes are returned. For example:
<profile-set></profile-set>
• a <profile> element with the profile ID or qualified name that identifies a specific
profile for which attribution information is requested. Only information for that
profile is returned. For example:
<profile-set><profile><id>2</id></profile></profile-set>

Specified user name This example shows how to retrieve user information for a specific user name
and domain (user1) and domain (‘null’).

Request
<request version="2.0" principal="User1"
credentials="password">

Page 242 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<target name="UserAPI" operation="getUser">

<parameter>
<user>
<name>user1</name>
<domain>
<name>null</name>
</domain>
</user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="getUser">
<result>
<user>
<id>6413</id>
<name>user1</name>
<login-name>login1</login-name>
<organization>
<id>1</id>
<name>/BWS</name>
<status>
<value>active</value>
</status>
<implicit-status>
<value>active</value>
</implicit-status>
</organization>
<domain>
<id>1</id>
<name>null</name>
<status>
<value>active</value>
</status>
</domain>
<password>
<type>cleartext</type>
<value>pwd1</value>
</password>
<status>
<value>active</value>

Service Controller 9.6.1-AAA October 26, 2012 Page 243

Chapter 4 Provisioning APIs Provisioning API Guide

</status>
<creation-date>2004-04-23 15:40:44
</creation-date>
<last-modified>
2004-04-23 15:40:44
</last-modified>
<modified-by>User1</modified-by>
<billing>
<id>8754</id>
<senior-billing-id>8754</senior-billing-id>
</billing>
<profile-set>
<id>3</id>
<name>Root User Profile Set</name>
<type>user</type>
</profile-set>
</user>
</result>
</target>
</response>

Specified login name This example shows how to retrieve user information for a user with a specified
and password login name (login1) and password (pwd1).

Request
<request version="2.0" principal="User1" credentials="password">
<target name="UserAPI" operation="getUser">
<parameter>
<user>
<login-name>login1</login-name>
<domain><name>null</name></domain>
<password>
<value>pwd1</value>
</password>
</user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="getUser">
<result>

Page 244 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<user>
<id>6413</id>
<name>user1</name>
<login-name>login1</login-name>
<organization>
<id>1</id>
<name>/BWS</name>
<status>
<value>active</value>
</status>
<implicit-status>
<value>active</value>
</implicit-status>
</organization>
<domain>
<id>1</id>
<name>null</name>
<status><value>active</value></status>
</domain>
<password>
<type>cleartext</type>
<value>pwd1</value>
</password>
<status>
<value>active</value>
</status>
<creation-date>2004-04-23 15:40:44</creation-date>
<last-modified>2004-04-23 15:40:44</last-modified>
<modified-by>User1</modified-by>
<billing>
<id>8754</id>
<senior-billing-id>8754</senior-billing-id>
</billing>
<profile-set>
<id>3</id>
<name>Root User Profile Set</name>
<type>user</type>
</profile-set>
</user>
</result>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 245

Chapter 4 Provisioning APIs Provisioning API Guide

RADIUS connection This example shows how to retrieve user information, including user context profile
service profile attributes, for a user with a specified login name (login1) and domain
attributes (domain1.com).

Request
<request version="2.0" principal="User1" credentials="password">
<target name="UserAPI" operation="getUser">
<parameter>
<user>
<login-name>dlogin1</login-name>
<domain>
<name>domain1.com</name>
</domain>
<profile-set></profile-set>
</user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="getUser">
<result>
<user>
<name>duser1</name>
<login-name>dlogin1</login-name>
<password>
<value>pswd1084374221</value>
</password>
<organization>
<qualified-name>/BWS
</qualified-name>
</organization>
<profile-set>
<qualified-name>/BWS/psu1
</qualified-name>
<user-information-profile>
<qualified-name>User Information
</qualified-name>
<attribute name="foo">
<value context="user">bar</value>
</attribute>
<attribute name="foo2">

Page 246 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<value context="user">bar</value>
</attribute>
<attribute name="foo3">
<value context="user">bar</value>
</attribute>
<attribute name="foo4">
<value context="user" subscript="0">
shouldbechanged
</value>
<value context="user" subscript="1">
shouldnotbechanged
</value>
<value context="user" subscript="2">
valueshouldbedeleted
</value>
</attribute>
<attribute name="shouldbedeleted">
<value context="user">%d</value>
</attribute>
</user-information-profile>
<profile>
<qualified-name>/Radius QoS Profile
</qualified-name>
<attribute name="name1">
<value segment="segment">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
</profile>
</profile-set>
</user>
</result>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 247

Chapter 4 Provisioning APIs Provisioning API Guide

getUserWithActiveServices
Use the getUserWithActiveServices operation to retrieve a list of active RADIUS
connection service profiles.
The following elements are not required in the request message:
• profile-set
• user-attributes

Get list of active This example shows how to retrieve a list of active RADIUS connection service
RADIUS connection profiles.
service profiles
Request
<request version="2.0" principal="admin" credentials="CREDENTIALS">
<target name="UserAPI" operation="getUserWithActiveServices">
<parameter>
<user>
<name/>
<login-name>6135551234</login-name>
<domain>
<name>marktestdomain</name>
</domain>
<profile-set/>
<user-attributes/>
</user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="getUserWithActiveServices">
<result>
<user include-associations="false">
<id>6</id>
<name>6135551234</name>
<login-name>6135551234</login-name>
<organization>
<id>1</id>
<name>Root Organization</name>
<status>
<value>active</value>
</status>
<implicit-status>

Page 248 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<value>active</value>
</implicit-status>
</organization>
<domain>
<id>2</id>
<name>testdomain</name>
<status>
<value>active</value>
</status>
</domain>
<password>
<type>cleartext</type>
<value>password</value>
</password>
<status>
<value>active</value>
</status>
<creation-date>2009-06-16 15:48:42</creation-date>
<last-modified>2009-09-15 19:57:19</last-modified>
<modified-by>root@null</modified-by>
<billing>
<id>9</id>
<senior-billing-id>9</senior-billing-id>
</billing>
<profile-set>
<type>user</type>
<profile>
<name>CONNECTION PROFILE</name>
</profile>
</profile-set>
<user-attributes>
<user-attribute name="001122334455" type="string">
<value id="21">0000000000000004</value>
</user-attribute>
<user-attribute name="hotlineReason" type="string">
<value id="3">7777777777777777</value>
</user-attribute>
</user-attributes>
</user>
</result>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 249

Chapter 4 Provisioning APIs Provisioning API Guide

getUserProfileSet
Use the getUserProfileSet operation to retrieve user profile set information and,
optionally, user group context (UG) profile attributes.
These elements are required:
• the profile set qualified name or ID
These elements are optional:
• an empty <profile> element to be populated with user group context (UG)
profile information. All user profiles and attributes are returned. For example:
<profile></profile>
• a <profile> element with the profile ID or qualified name that identifies a specific
profile for which attribute information is requested. Only information for that
profile is returned. For example:
<profile><id>2</id></profile>
• an empty <radius-qos-selection-profile> element to be populated with user
group context (UG) and default context (DEF) RADIUS QoS selection policy
profile information. All user profiles and attributes are returned. For example:
<radius-qos-selectionprofile>
</radius-qos-selection-profile>
• a <radius-qos-selection-profile> element with the profile ID or qualified name
that identifies a specific profile for which RADIUS QoS selection policy
attribution information is requested. Only information for that profile is returned.
For example:
<radius-qos-selectionprofile>
<id>2</id>
</radius-qos-selection-profile>

Get RADIUS QoS This example shows how to get user group and default context RADIUS QoS
Selection Policy Selection Policy Profile attributes.
Profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="UserAPI" operation="getUserProfileSet">
<parameter>
<user-profile-set>
<qualified-name>/testUPS1</qualified-name>
<radius-qos-selection-profile><id>1198</id>
</radius-qos-selection-profile>
</user-profile-set>
</parameter>
</target>
</request>

Page 250 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Response
<response version="2.0">
<target name="UserAPI" operation="getUserProfileSet">
<result>
<user-profile-set>
<id>1712</id>
<name>testUPS1</name>
<organization><id>1</id></organization>
<inheritance>yes</inheritance>
<status><value>active</value></status>
<radius-qos-selection-profile>
<id>1198</id>
<name>Radius QoS Selection Policy Profile
</name>
<service>
<name>RADIUS QoS Selection Policy</name>
<version>1</version>
</service>
<qos-selection-policy>access
</qos-selection-policy>
<assignment>
<policy-name>local</policy-name>
<qos-profile>
<id>1200</id>
</qos-profile>
</assignment>
<assignment>
<policy-name>roaming</policy-name>
<qos-profile>
<id>1199</id>
</qos-profile>
</assignment>
</radius-qos-selection-profile>
</user-profile-set>
<result/>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 251

Chapter 4 Provisioning APIs Provisioning API Guide

Get RADIUS This example shows how to get user group context RADIUS connection service
connection service profile attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="UserAPI" operation="getUserProfileSet">
<parameter>
<user-profile-set>
<id>5</id>
<profile>
</profile>
</user-profile-set>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="getUserProfileSet">
<result>
<user-profile-set>
<name>BWS User Profile Set</name>
<Account><id>5</id></Account>
<profile>
<id>5</id>
<name>RadiusQoSConnectionService</name>
<service>
<name>RadiusQoSConnectionService </name>
<version>1</version>
</service>
<attribute name="name1">
<value segment="segment">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
</profile>
</user-profile-set>
</result>
</target>
</response>

Page 252 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

updateUser
Use the updateUser operation to modify a subscriber record.
One or more of these elements are required:
• the user name and domain
• the user ID
• the login name (if login uniqueness is enabled)
• the login name and domain or password
Note If login uniqueness if disabled (loginUnique=false, set in the Profile
Database during the BWSwsdbs installation prompts) the domain is
required in the updateUser request.
These elements are optional:
• a new login name for the user specified
• a new password for the user specified
• a new user status (active, pending, suspended, or deleted)
• an account name (1 to 64 characters)
• a user profile set, to which this user should be added or deleted
• user context (U) profile attributes to be added, modified, or deleted from the
domain profile
If the user name changes, then the account must be deleted with the deleteUser
operation, and then recreated with a new createUser call.

Change password This example shows how to change the password for a user with a specified login
name (dlogin1).
To define the password encryption <type> parameter, use one of the following
options.
To encrypt a cleartext password using:
• North American UNIX, use the value “cleartext2unixna”
• BSD MD5, use the value “cleartext2bsdmd5 “
• 2-way MD5, use the value “cleartext2md5x”
Example:
<password>
<type>cleartext2md5x</type>
<value>mypassword</value>
</password>
Note If no value is given for the password <type> parameter, the password is
saved in the clear text format.

Service Controller 9.6.1-AAA October 26, 2012 Page 253

Chapter 4 Provisioning APIs Provisioning API Guide

Request
<request version="2.0" principal="User1" credentials="password">
<target name="UserAPI" operation="updateUser">
<parameter>
<user>
<login-name>dlogin1</login-name>
<domain>
<name>domain1.com</name>
</domain>
<password>
<value>newdpwd1</value>
</password>
</user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="updateUser">
<result/>
</target>
</response>

Generate password A password can be generated for the user with the updateUser or createUser
operations. For an example, see "Generate a random password" on page 233.

Change attributes This example shows how to change user information attributes for a user with a
specified login name (dlogin1) and domain (domain1.com).

Request
<request version="2.0" principal="User1" credentials="password">
<target name="UserAPI" operation="updateUser">
<parameter>
<user>
<login-name>dlogin1</login-name>
<domain>
<name>domain1.com</name>
</domain>
<profile-set>
<qualified-name>/BWS/psu1</qualified-name>
<user-information-profile>
<qualified-name>User Information</qualified-name>

Page 254 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<attribute name="foo4">
<value context="user" subscript="0">changed</value>
<value context="user" subscript="2"
delete="true">
</value>
</attribute>
<attribute name="shouldbedeleted" delete="true"/>
</user-information-profile>
</profile-set>
</user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="updateUser">
<result/>
</target>
</response>

Add or update This example shows how to add or update a user’s hotlineReason attribute for
WiMAX user WiMAX hotlining configuration. The hotlineReason value corresponds to a bit action
attributes map configured in hotlineConfig.xml and must be a 16 byte hex string.
updateUser includes an optional operation attribute which can be used to modify
any User-Attribute that is a string, including hotlineReason. The operation attribute
can have one of the following values:
• bitmaskSet:
– accepts a string of “0” and “1” values
– changes the hotlineReason attribute by changing specified bits to a value
of “1”. For example:
hotlineReason=00000001
<value operation=”bitmaskSet”>00000010</value>
new hotlineReason=00000011
• bitmaskClear:
– accepts a string of “0” and “1” values

Service Controller 9.6.1-AAA October 26, 2012 Page 255

Chapter 4 Provisioning APIs Provisioning API Guide

– changes the hotlineReason attribute by changing specified bits to a value

of “0”. For example:
hotlineReason=00000011
<value operation=”bitmaskClear”>00000010</value>
new hotlineReason=00000001
Note The Provisioning Server applies bitmaskSet and bitmaskClear operations
from right to left when updating the hotlineReason.
Note If the bitmaskSet or bitmaskClear value is longer than the hotlineReason
being modified, the Provisioning Server ignores the bitmask for the extra
bits.

Request to update a bit in the hotlineReason

<request version="2.0" principal="APIUSER" credentials="APIPASSWORD">
<target name="UserAPI" operation="updateUser">
<parameter>
<user>
<login-name>MAC</login-name>
<domain>
<name>DOMAIN</name>
</domain>
<user-attributes>
<user-attribute name=”hotlineReason” type=”string”>
<value operation=”bitmaskSet”>BITMASK</value>
</user-attribute>
</user-attributes>
</user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="updateUser">
<result/>
</target>
</response>

Request to clear a bit in the hotlineReason

<request version="2.0" principal="APIUSER" credentials="APIPASSWORD">
<target name="UserAPI" operation="updateUser">
<parameter>
<user>
<login-name>MAC</login-name>

Page 256 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<domain>
<name>DOMAIN</name>
</domain>
<user-attributes>
<user-attribute name="hotlineReason" type="string">
<value operation="bitmaskClear">BITMASK</value>
</user-attribute>
</user-attributes>
</user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="updateUser">
<result/>
</target>
</response>

Request to update hotlineReason without bitmask

<request credentials="password" principal="admin" version="2.0">
<target name="UserAPI" operation="updateUser">
<parameter>
<user>
<login-name>user1</login-name>
<domain>
<name>null</name>
</domain>
<user-attributes>
<user-attribute name="hotlineReason" type="string"
delete="true">
<value>0000000000000004</value>
</user-attribute>
</user-attributes>
</user>
</parameter>
</target>
</request>

Service Controller 9.6.1-AAA October 26, 2012 Page 257

Chapter 4 Provisioning APIs Provisioning API Guide

Response
<response version="2.0">
<target name="UserAPI" operation="updateUser">
<result/>
</target>
</response>

Change user status This example shows how to change the status to ‘suspended’ for a user with a
specified login name (dlogin1) and domain (domain1.com). To suspend a user, you
must provide a suspension reason.

Request
<request version="2.0" principal="User1" credentials="password">
<target name="UserAPI" operation="updateUser">
<parameter>
<user>
<login-name>dlogin1</login-name>
<domain>
<name>domain1.com</name>
</domain>
<status>
<value>suspended</value>
<suspension-reason>
Suspended by Provisioning System
</suspension-reason>
</status>
</user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="updateUser">
<result/>
</target>
</response>

Page 258 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Change login name This example shows how to change the login name for a user (from login1 to login2)
without having to delete and recreate the account.
Note Login names can only be changed if the LoginUpdatesAllowed flag has
been enabled in the Profile Database.
Note If login uniqueness if disabled (loginUnique=false, set in the Profile
Database during the BWSwsdbs installation prompts) the domain is
required in the updateUser request.

Request
<request version="2.0" principal="User1" credentials="password">
<target name="UserAPI" operation="updateUser">
<parameter>
<user>
<login-name>login1</login-name>
<new-login-name>login2</new-login-name>
</user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="updateUser">
<result/>
</target>
</response>

Update RADIUS This example shows how to update user context RADIUS connection service profile
connection service attributes.
profile attributes The update-only flag indicates that the value should only be updated if it is already
present in the profile. Default action is to add the attribute if it is not already present.

Request
<request version="2.0" principal="User1" credentials="password">
<target name="UserAPI" operation="updateUser">
<parameter>
<user>
<login-name>bob</login-name>
<profile-set>
<qualified-name>/BWS/bobprofileset</qualified-name>
<profile>
<id>25</id>
<attribute name="name1">

Service Controller 9.6.1-AAA October 26, 2012 Page 259

Chapter 4 Provisioning APIs Provisioning API Guide

<value segment="seg1" update-only="true">

value1
</value>
</attribute>
<attribute name="#ActiveStateFlag">
<value>on</value>
</attribute>
</profile>
</profile-set>
</user>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="updateUser">
<result/>
</target>
</response>

Delete RADIUS This example shows how to delete user context RADIUS connection service profile
connection service attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="UserAPI" operation="updateUser">
<parameter>
<user>
<id>5</id>
<profile-set>
<id>15</id>
<profile>
<id>25</id>
<attribute name="name1" delete="true">
<value segment="segment">value1</value>
</attribute>
</profile>
</profile-set>
</user>
</parameter>
</target>
</request>

Page 260 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Response
<response version="2.0">
<target name="UserAPI" operation="updateUser">
<result/>
</target>
</response>

updateUserProfileSet
Use the updateUserProfileSet operation to modify a user profile set.
These elements are required:
• the profile set ID or qualified name
These elements are optional:
• a new profile set description
• a new profile set inheritance flag setting
• a new profile set status (active or deleted)
• a profile to be added to, modified, or deleted from the profile set
• user group context (UG) profile attributes to be added to, modified, or deleted
from an account profile

Create RADIUS QoS This example shows how to create user group context RADIUS QoS Selection
Selection Policy Policy Profile attributes.
Profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="UserAPI" operation="updateUserProfileSet">
<parameter>
<user-profile-set>
<qualified-name>/testUPS1</qualified-name>
<type>user</type>
<radius-qos-selection-profile>
<id>1198</id>
<assignment>
<policy-name>local</policy-name>
<qos-profile>
<id>1199</id>
</qos-profile>
</assignment>
<assignment>
<policy-name>roaming</policy-name>
<qos-profile>
<id>1200</id>

Service Controller 9.6.1-AAA October 26, 2012 Page 261

Chapter 4 Provisioning APIs Provisioning API Guide

</qos-profile>
</assignment>
</radius-qos-selection-profile>
</user-profile-set>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="updateUserProfileSet">
<result/>
</target>
</response>

Update RADIUS QoS This example shows how to update user group context RADIUS QoS Selection
Selection Policy Policy Profile attributes.
Profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="UserAPI" operation="updateUserProfileSet">
<parameter>
<user-profile-set><qualified-name>/testUPS1
</qualified-name>
<radius-qos-selection-profile>
<id>1198</id>
<assignment><policy-name>local</policy-name>
<qos-profile>
<id>1200</id>
</qos-profile>
</assignment>
<assignment>
<policy-name>roaming</policy-name>
<qos-profile>
<id>1199</id>
</qos-profile>
</assignment>
</radius-qos-selection-profile>
</user-profile-set>
</parameter>
</target>
</request>

Page 262 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Response
<response version="2.0">
<target name="UserAPI" operation="updateUserProfileSet">
<result/>
</target>
</response>

Delete RADIUS QoS This example shows how to delete user group context RADIUS QoS Selection
Selection Policy Policy Profile attributes.
Profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="UserAPI" operation="updateUserProfileSet">
<parameter>
<user-profile-set>
<qualified-name>/testUPS1</qualified-name>
<radius-qos-selection-profile>
<id>1198</id>
<assignment delete="true">
<policy-name>local</policy-name>
<qos-profile>
<id>1200</id>
</qos-profile>
</assignment>
</radius-qos-selection-profile>
</user-profile-set>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="updateUserProfileSet">
<result/>
</target>
</response>

Service Controller 9.6.1-AAA October 26, 2012 Page 263

Chapter 4 Provisioning APIs Provisioning API Guide

Update RADIUS This example shows how to update user group context RADIUS connection service
connection service profile attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="UserAPI" operation="updateUserProfileSet">
<parameter>
<user-profile-set>
<id>15</id>
<profile>
<id>5</id>
<attribute name="name1">
<value segment="seg2">value1</value>
</attribute>
<attribute name="name2">
<value segment="segment">value2</value>
</attribute>
</profile>
</user-profile-set>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation="updateUserProfileSet">
<result/>
</target>
</response>

Delete RADIUS This example shows how to delete user group context RADIUS connection service
connection service profile attributes.
profile attributes
Request
<request version="2.0" principal="User1" credentials="password">
<target name="UserAPI" operation="updateUserProfileSet">
<parameter>
<user-profile-set>
<id>15</id>
<profile>
<id>5</id>
<attribute name="name1" delete="true">
<value segment="segment">value1</value>

Page 264 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</attribute>
<attribute name="name2">
<value delete="true" subscript="3">value2
</value>
</attribute>
</profile>
</user-profile-set>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="UserAPI" operation=" updateUserProfileSet ">
<result/>
</target>
</response>

WiMAXAPI operations
This section describes the following WiMAXAPI operations:
• createWiMAXDevice
• createWiMAXHAGroup
• createWiMAXNodeGroup
• deleteWiMAXDevice
• deleteWiMAXHAGroup
• deleteWiMAXNodeGroup
• getWiMAXDevice
• getWiMAXHAGroup
• getWiMAXNodeGroup
• updateWiMAXDevice
• updateWiMAXHAGroup
• updateWiMAXNodeGroup

createWiMAXDevice
Use the createWiMAXDevice operation to create a WiMAX device instance.
These elements are required:
• the WiMAX device identifier, for example a MAC address
• a pre-shared key
These elements are optional:

Service Controller 9.6.1-AAA October 26, 2012 Page 265

Chapter 4 Provisioning APIs Provisioning API Guide

• the caption under which the device is displayed in Service Manager (if not
supplied, the name field is used)
• a description of the device
The response provides the ID of the created WiMAX device.

WiMAX device This example shows how to create a WiMAX device using the MAC address as the
device name (identifier).

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="WiMAXAPI" operation="createWiMAXDevice">
<parameter>
<wimax-device>
<name>00-a3-b4-c5-d6-e7</name>
<pre-shared-key>PSK_value</pre-shared-key>
<wimax-device>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="createWiMAXDevice">
<result>
<wimax-device>
<id>47</id>
</wimax-device>
</result>
</target>
</response>

createWiMAXHAGroup
Use the createWiMAXHAGroup operation to create a WiMAX home agent group
instance.
These elements are required:
• the WiMAX home agent group name
These elements are optional:
• the caption under which the HA group displays in Service Manager (if not
supplied, the name field is used)
• a description of the node
• one or more WiMAX nodes to assign to the HA group

Page 266 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

The response provides the ID of the created WiMAX HA group.

Empty WiMAX HA This example shows how to create a WiMAX home agent group with no nodes
group initially assigned.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="WiMAXAPI" operation="createWiMAXHAGroup">
<parameter>
<wimax-ha-group>
<name>HA Group 1</name>
<description>The description</description>
</wimax-ha-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="createWiMAXHAGroup">
<result>
<wimax-ha-group>
<id>124</id>
</wimax-ha-group>
</result>
</target>
</response>

HA group with two This example shows how to create a WiMAX home agent group with two WiMAX
WiMAX nodes nodes initially assigned. Nodes may be identified either by ID or by qualified name.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="WiMAXAPI" operation="createWiMAXHAGroup">
<parameter>
<wimax-ha-group>
<name>HA Group 2</name>
<description>The description</description>
<wimax-node>
<id>123</id>
</wimax-node>
<wimax-node>

Service Controller 9.6.1-AAA October 26, 2012 Page 267

Chapter 4 Provisioning APIs Provisioning API Guide

<qualified-name>172.17.0.100</qualified-name>
</wimax-node>
</wimax-ha-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="createWiMAXHAGroup">
<result>
<wimax-ha-group>
<id>125</id>
</wimax-ha-group>
</result>
</target>
</response>

createWiMAXNodeGroup
Use the createWiMAXNodeGroup operation to create a WiMAX node group
instance.
These elements are required:
• the WiMAX node group name
• the RMS cluster ID
These elements are optional:
• the caption under which the node group displays in Service Manager (if not
supplied, the name field is used)
• a description of the node
• one or more WiMAX nodes to assign to the node group
The response provides the ID of the created WiMAX node group.

Provisioning multiple RMS cluster IDs

In deployments that require multiple RMS cluster IDs, modify the value of the
<rms-cluster-id> parameter by providing a sequence of comma-separated integers,
such as 1,2,3,4, or a range of integers, such as 1-4.
Example:
<wimax-node-group>
<name>Node Group 1</name>
<description>The description</description>
<rms-cluster-id>1,2,3,4</rms-cluster-id>
</wimax-node-group>

Page 268 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Empty WiMAX node This example shows how to create a WiMAX node group with no nodes initially
group assigned.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="WiMAXAPI" operation="createWiMAXNodeGroup">
<parameter>
<wimax-node-group>
<name>Node Group 1</name>
<description>The description</description>
<rms-cluster-id>3</rms-cluster-id>
</wimax-node-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="createWiMAXNodeGroup">
<result>
<wimax-node-group>
<id>46</id>
</wimax-node-group>
</result>
</target>
</response>

Node group with two This example shows how to create a WiMAX node group with two WiMAX nodes
WiMAX nodes initially assigned. Nodes may be identified either by ID or by qualified name.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="WiMAXAPI" operation="createWiMAXNodeGroup">
<parameter>
<wimax-node-group>
<name>Node Group 2</name>
<description>The description</description>
<rms-cluster-id>2</rms-cluster-id>
<wimax-node>
<id>123</id>
</wimax-node>

Service Controller 9.6.1-AAA October 26, 2012 Page 269

Chapter 4 Provisioning APIs Provisioning API Guide

<wimax-node>
<qualified-name>172.17.0.100</qualified-name>
</wimax-node>
</wimax-node-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="createWiMAXNodeGroup">
<result>
<wimax-node-group>
<id>47</id>
</wimax-node-group>
</result>
</target>
</response>

deleteWiMAXDevice
Use the deleteWiMAXDevice operation removes a WiMAX device.
These elements are required:
• the WiMAX device ID or qualified name

Specified device This example shows how to delete a WiMAX device with a specified ID.

Request
<request version="2.0" principal="User1" credentials="password">
<target name="WiMAXAPI" operation="deleteWiMAXDevice">
<parameter>
<wimax-device>
<id>49</id>
</wimax-device>
</parameter>
/target>
</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="deleteWiMAXDevice">
<result/>
</target>

Page 270 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

</response>

deleteWiMAXHAGroup
Use the deleteWiMAXNodeGroup operation removes a WiMAX home agent group.
These elements are required:
• the WiMAX home agent group ID or qualified name

Specified HA group This example shows how to delete a WiMAX home agent group with a specified ID.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="WiMAXAPI" operation="deleteWiMAXHAGroup">
<parameter>
<wimax-ha-group>
<id>125</id>
</wimax-ha-group>
</parameter>
/target>
</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="deleteWiMAXHAGroup">
<result/>
</target>
</response>

deleteWiMAXNodeGroup
Use the deleteWiMAXNodeGroup operation removes a WiMAX node group.
These elements are required:
• the WiMAX node group ID or qualified name

Specified node group This example shows how to delete a WiMAX node group with a specified ID.

Request
<request version="2.0" principal="User1"
credentials="password">
<target name="WiMAXAPI" operation="deleteWiMAXNodeGroup">
<parameter>
<wimax-node-group>

Service Controller 9.6.1-AAA October 26, 2012 Page 271

Chapter 4 Provisioning APIs Provisioning API Guide

<id>46</id>
</wimax-node-group>
</parameter>
/target>
</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="deleteWiMAXNodeGroup">
<result/>
</target>
</response>

getWiMAXDevice
Use the getWiMAXDevice operation to retrieve WiMAX device information and,
optionally, WiMAX device attributes.
These elements are required:
• the WiMAX node ID or qualified name
These elements are optional:
• the include-attributes attribute, requesting retrieval of WiMAX device
provisioned attribute information

Retrieve WiMAX This example shows how to retrieve WiMAX node information for a specified
device information WiMAX device (00-a3-b4-c5-d6-e7).
only
Request
<request version="2.0" principal="User1" credentials="password">
<target name="WiMAXAPI" operation="getWiMAXDevice">
<parameter>
<wimax-device>
<qualified-name>
00-a3-b4-c5-d6-e7
</qualified-name>
</wimax-device>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="getWiMAXDevice">
<result>

Page 272 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<wimax-device include-attributes="false">
<id>49</id>
<configuration-id>1</configuration-id>
<name>00-a3-b4-c5-d6-e7</name>
<caption>00-a3-b4-c5-d6-e7</caption>
<pre-shared-key>PSK_value</pre-shared-key>
<status>
<value>active</value>
</status>
<last-modified>
2006-08-14 11:43:17
</last-modified>
<modified-by>User1</modified-by>
</wimax-device>
</result>
</target>
</response>

getWiMAXHAGroup
Use the getWiMAXHAGroup operation to retrieve WiMAX home agent group
information and, optionally, provisioned attributes of the home agent group and a
list of WiMAX nodes that are members of the group.
These elements are required:
• the WiMAX home agent group ID or qualified name
These elements are optional:
• the include-nodes attribute, requesting retrieval of WiMAX home agent group
member information
• the include-attributes attribute, requesting retrieval of WiMAX home agent
group provisioned attribute information

Retrieve WiMAX HA This example shows how to retrieve WiMAX home agent group information for a
group information specified WiMAX HA group (HA Group 2).
only
Request
<request version="2.0" principal="User1" credentials="password">
<target name="WiMAXAPI" operation="getWiMAXHAGroup">
<parameter>
<wimax-ha-group>
<qualified-name>HA Group 1</qualified-name>
</wimax-ha-group>
</parameter>
</target>

Service Controller 9.6.1-AAA October 26, 2012 Page 273

Chapter 4 Provisioning APIs Provisioning API Guide

</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="getWiMAXHAGroup">
<result>
<wimax-ha-group include-nodes="false"
include-attributes="false">
<id>124</id>
<configuration-id>1</configuration-id>
<name>HA Group 1</name>
<caption>HA Group 1</caption>
<description>The description</description>
<last-modified>
2006-08-14 11:37:58
</last-modified>
<modified-by>User1</modified-by>
</wimax-ha-group>
</result>
</target>
</response>

Retrieve WiMAX HA This example shows how to retrieve home agent group information, including node
group, nodes, and assignments, and provisioned group attribute information for a specified WiMAX
attribute information home agent group. The response shows that there are two WiMAX nodes in the
group, but no provisioned HA group attributes.

Request
<request version="2.0" principal="User1" credentials="password">
<target name="WiMAXAPI" operation="getWiMAXHAGroup">
<parameter>
<wimax-ha-group include-nodes="true"
include-attributes="true">
<qualified-name>HA Group 2</qualified-name>
</wimax-ha-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="getWiMAXHAGroup">
<result>
<wimax-ha-group include-nodes="true"

Page 274 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

include-attributes="true">
<id>125</id>
<configuration-id>1</configuration-id>
<name>HA Group 2</name>
<caption>HA Group 2</caption>
<description>The description</description>
<wimax-node include-attributes="false"
include-group="false"
include-ha-groups="false">
<id>29</id>
<configuration-id>1</configuration-id>
<name>172.17.0.100</name>
<caption>172.17.0.100</caption>
<protocols>
<radius>
<shared-secret>SECRET</shared-secret>
</radius>
</protocols>
<roles>
<home-agent-role>
<protocols>
<radius>
<skip-count>0</skip-count>
<root-key-lifetime>
86400
</root-key-lifetime>
</radius>
</protocols>
</home-agent-role>
</roles>
<vendor>RFC2138</vendor>
<time-zone>GMT</time-zone>
<last-modified>
2006-08-14 11:18:50
</last-modified>
<modified-by>User1</modified-by>
</wimax-node>
<wimax-node include-attributes="false"
include-group="false"
include-ha-groups="false">
<id>31</id>
<configuration-id>1</configuration-id>
<name>172.17.0.101</name>

Service Controller 9.6.1-AAA October 26, 2012 Page 275

Chapter 4 Provisioning APIs Provisioning API Guide

<caption>172.17.0.101</caption>
<protocols>
<radius>
<shared-secret>SECRET</shared-secret>
</radius>
</protocols>
<roles>
<home-agent-role>
<protocols>
<radius>
<skip-count>0</skip-count>
<root-key-lifetime>
86400
</root-key-lifetime>
</radius>
</protocols>
</home-agent-role>
</roles>
<vendor>RFC2138</vendor>
<time-zone>GMT</time-zone>
<last-modified>
2006-08-14 11:18:54
</last-modified>
<modified-by>User1</modified-by>
</wimax-node>
<last-modified>
2006-08-14 11:37:58
</last-modified>
<modified-by>User1</modified-by>
</wimax-ha-group>
</result>
</target>
</response>

getWiMAXNodeGroup
Use the getWiMAXNodeGroup operation to retrieve WiMAX node group information
and, optionally, provisioned attributes of the node group and a list of WiMAX nodes
that are members of the group.
These elements are required:
• the WiMAX node group ID or qualified name
These elements are optional:
• the include-nodes flag to retrieve WiMAX node group member information

Page 276 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Retrieve WiMAX This example shows how to retrieve WiMAX node group information for a specified
node group WiMAX node group (Node Group 2).
information only
Request
<request version="2.0" principal="User1" credentials="password">
<target name="WiMAXAPI" operation="getWiMAXNodeGroup">
<parameter>
<wimax-node-group>
<qualified-name>Node Group 2</qualified-name>
</wimax-node-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="getWiMAXNodeGroup">
<result>
<wimax-node-group include-nodes="false"
include-attributes="false">
<id>47</id>
<configuration-id>1</configuration-id>
<name>Node Group 2</name>
<caption>Node Group 2</caption>
<description>The description</description>
<rms-cluster-id>2</rms-cluster-id>
<last-modified>
2006-08-14 11:19:00
</last-modified>
<modified-by>User1</modified-by>
</wimax-node-group>
</result>
</target>
</response>

Retrieve information This example shows how to retrieve WiMAX node group information for WiMAX
about nodes (including ASN Gateways) that use the Diameter protocol.
Diameter-enabled
WiMAX node groups Request
<request version="2.0" principal="user" credentials="password">
<target name="WiMAXAPI" operation="getWiMAXNodeGroup">
<parameter>
<wimax-node-group>

Service Controller 9.6.1-AAA October 26, 2012 Page 277

Chapter 4 Provisioning APIs Provisioning API Guide

<qualified-name>Node Group 2</qualified-name>

</wimax-node-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="getWiMAXNodeGroup">
<result>
<wimax-node-group include-attributes="false" include-nodes="false">
<id>33</id>
<configuration-id>1</configuration-id>
<name>Node Group 2</name>
<caption>Node Group 2</caption>
<description>The description</description>
<rms-cluster-id>2</rms-cluster-id>
<last-modified>2006-08-14 11:19:00</last-modified>
<modified-by>user</modified-by>
</wimax-node-group>
</result>
</target>
</response>

Retrieve WiMAX This example shows how to retrieve node group information, including node
group, nodes, and assignments, and provisioned group attribute information for a specified WiMAX
attribute information node group (id 38).

Request
<request version="2.0" principal="User1" credentials="password">
<target name="WiMAXAPI" operation="getWiMAXNodeGroup">
<parameter>
<wimax-node-group include-nodes="true"
include-attributes="true">
<qualified-name>Node Group 2</qualified-name>
</wimax-node-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="getWiMAXNodeGroup">

Page 278 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<result>
<wimax-node-group include-nodes="true"
include-attributes="true">
<id>47</id>
<configuration-id>1</configuration-id>
<name>Node Group 2</name>
<caption>Node Group 2</caption>
<description>The description</description>
<rms-cluster-id>2</rms-cluster-id>
<wimax-node include-attributes="false"
include-group="false"
include-ha-groups="false">
<id>29</id>
<configuration-id>1</configuration-id>
<name>172.17.0.100</name>
<caption>172.17.0.100</caption>
<protocols>
<radius>
<shared-secret>SECRET</shared-secret>
</radius>
</protocols>
<roles>
<home-agent-role>
<protocols>
<radius>
<skip-count>0</skip-count>
<root-key-lifetime>
86400
</root-key-lifetime>
</radius>
</protocols>
</home-agent-role>
</roles>
<vendor>RFC2138</vendor>
<time-zone>GMT</time-zone>
<last-modified>
2006-08-14 11:18:50
</last-modified>
<modified-by>User1</modified-by>
</wimax-node>
<wimax-node include-attributes="false"
include-group="false"
include-ha-groups="false">

Service Controller 9.6.1-AAA October 26, 2012 Page 279

Chapter 4 Provisioning APIs Provisioning API Guide

<id>31</id>
<configuration-id>1</configuration-id>
<name>172.17.0.101</name>
<caption>172.17.0.101</caption>
<protocols>
<radius>
<shared-secret>SECRET</shared-secret>
</radius>
</protocols>
<roles>
<home-agent-role>
<protocols>
<radius>
<skip-count>0</skip-count>
<root-key-lifetime>
86400
</root-key-lifetime>
</radius>
</protocols>
</home-agent-role>
</roles>
<vendor>RFC2138</vendor>
<time-zone>GMT</time-zone>
<last-modified>
2006-08-14 11:18:54
</last-modified>
<modified-by>User1</modified-by>
</wimax-node>
<attribute name="my-group-attribute">
<value id="84">my_value</value>
</attribute>
<last-modified>
2006-08-14 11:19:00
</last-modified>
<modified-by>User1</modified-by>
</wimax-node-group>
</result>
</target>
</response>

updateWiMAXDevice
Use the updateWiMAXDevice operation to modify a WiMAX device.

Page 280 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

These elements are required:

• the WiMAX node ID or qualified name
These elements are optional:
• a new name, caption, or description for the device
• a new status value (active or suspended)

Suspend service for a This example shows how to update the device status for a WiMAX device, setting it
device to ‘suspended’. All other properties remain the same

Request
<request version="2.0" principal="User1" credentials="password">
<target name="WiMAXAPI" operation="updateWiMAXDevice">
<parameter>
<wimax-device>
<qualified-name>
00-a3-b4-c5-d6-e7
</qualified-name>
<status>
<value>suspended</value>
</status>
</wimax-device>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="updateWiMAXDevice">
<result/>
</target>
</response>

updateWiMAXHAGroup
Use the updateWiMAXHAGroup operation to modify a WiMAX home agent group.
These elements are required:
• the WiMAX home agent group ID or qualified name
These elements are optional:
• a new name, caption, or description for the home agent group
• one or more WiMAX nodes to add to the group
• one or more WiMAX nodes and delete flags to indicate that the nodes should
be removed from the group

Service Controller 9.6.1-AAA October 26, 2012 Page 281

Chapter 4 Provisioning APIs Provisioning API Guide

Change name and This example shows how to change the name and caption for a WiMAX home
caption agent group. All other properties remain the same.

Request
<request version="2.0" principal="User1" credentials="password">
<target name="WiMAXAPI" operation="updateWiMAXHAGroup">
<parameter>
<wimax-ha-group>
<qualified-name>HA Group 1</qualified-name>
<name>New Name</name>
<caption>New Caption</caption>
</wimax-ha-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="updateWiMAXHAGroup">
<result/>
</target>
</response>

Add nodes to a This example shows how to add multiple nodes to a WiMAX home agent group.
WiMAX HA group
Request
<request version="2.0" principal="User1" credentials="password">
<target name="WiMAXAPI" operation="updateWiMAXHAGroup">
<parameter>
<wimax-ha-group>
<qualified-name>HA Group 1</qualified-name>
<wimax-node>
<qualified-name>172.17.0.100</qualified-name>
</wimax-node>
<wimax-node>
<qualified-name>172.17.0.101</qualified-name>
</wimax-node>
</wimax-ha-group>
</parameter>
</target>
</request>

Page 282 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

Response
<response version="2.0">
<target name="WiMAXAPI" operation="updateWiMAXHAGroup">
<result/>
</target>
</response>

Remove nodes from This example shows how to remove WiMAX nodes from a WiMAX home agent
a WiMAX HA group group.

Request
<request version="2.0" principal="User1" credentials="password">
<target name="WiMAXAPI" operation="updateWiMAXHAGroup">
<parameter>
<wimax-ha-group>
<qualified-name>HA Group 1</qualified-name>
<wimax-node delete="true">
<qualified-name>172.17.0.100</qualified-name>
</wimax-node>
<wimax-node delete="true">
<qualified-name>172.17.0.101</qualified-name>
</wimax-node>
</wimax-ha-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="updateWiMAXHAGroup">
<result/>
</target>
</response>

updateWiMAXNodeGroup
Use the updateWiMAXNodeGroup operation to modify a WiMAX node group.
These elements are required:
• the WiMAX node group ID or qualified name
These elements are optional:
• a new name, caption, or description for the node group
• one or more WiMAX nodes to add to the group

Service Controller 9.6.1-AAA October 26, 2012 Page 283

Chapter 4 Provisioning APIs Provisioning API Guide

• one or more WiMAX nodes and delete flags to indicate that the nodes should
be removed from the group

Provisioning multiple RMS cluster IDs

In deployments that require multiple RMS cluster IDs, modify the value of the
<rms-cluster-id> parameter by providing a sequence of comma-separated integers,
such as 1,2,3,4, or a range of integers, such as 1-4.
Example:
<wimax-node-group>
<name>Node Group 1</name>
<description>The description</description>
<rms-cluster-id>1,2,3,4</rms-cluster-id>
</wimax-node-group>

Change name and This example shows how to change the name and caption for a WiMAX node
caption group. All other properties remain the same.

Request
<request version="2.0" principal="User1" credentials="password">
<target name="WiMAXAPI" operation="updateWiMAXNodeGroup">
<parameter>
<wimax-node-group>
<qualified-name>Node Group 2</qualified-name>
<name>New Name</name>
<caption>New Caption</caption>
</wimax-node-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="updateWiMAXNodeGroup">
<result/>
</target>
</response>

Add nodes to a This example shows how to add multiple nodes to a WiMAX node group.
WiMAX node group
Request
<request version="2.0" principal="User1" credentials="password">
<target name="WiMAXAPI" operation="updateWiMAXNodeGroup">
<parameter>

Page 284 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 4 Provisioning APIs

<wimax-node-group>
<qualified-name>Node Group 2</qualified-name>
<wimax-node>
<qualified-name>172.17.0.100</qualified-name>
</wimax-node>
<wimax-node>
<qualified-name>172.17.0.101</qualified-name>
</wimax-node>
</wimax-node-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="updateWiMAXNodeGroup">
<result/>
</target>
</response>

Remove nodes from This example shows how to remove WiMAX nodes from a WiMAX node group.
a WiMAX node group
Request
<request version="2.0" principal="User1" credentials="password">
<target name="WiMAXAPI" operation="updateWiMAXNodeGroup">
<parameter>
<wimax-node-group>
<qualified-name>Node Group 2</qualified-name>
<wimax-node delete="true">
<qualified-name>172.17.0.100</qualified-name>
</wimax-node>
<wimax-node delete="true">
<qualified-name>172.17.0.101</qualified-name>
</wimax-node>
</wimax-node-group>
</parameter>
</target>
</request>

Response
<response version="2.0">
<target name="WiMAXAPI" operation="updateWiMAXNodeGroup">
<result/>

Service Controller 9.6.1-AAA October 26, 2012 Page 285

Chapter 4 Provisioning APIs Provisioning API Guide

</target>
</response>

Page 286 October 26, 2012 Service Controller 9.6.1-AAA

 WSDLs

5
Chapter 5
Chapter

This chapter describes WSDLs.

The topics are:
• WSDLs overview
• Obtaining WSDLs
• Sending SOAP requests
• WSDL examples

Service Controller 9.6.1-AAA October 26, 2012 Page 287

Chapter 5 WSDLs Provisioning API Guide

WSDLs overview
WDSL is an XML-based language that is used to model network-based services.
The WSDL file for a service describes supported operations, including applicable
parameters and attributes, and the format of request and response messages.
Developers can use the WSDL description to design third-party applications that
interface with the Provisioning Server.
Note Only APIs that are implemented using SOAP have an associated WSDL.
For APIs not implemented using SOAP there is no associated WSDL and
the procedures in this chapter for obtaining WSDLs and sending SOAP
requests do not apply.

Obtaining WSDLs
Use a SOAP tool to load the WSDL.

To obtain a WSDL
In the SOAP tool, type the location of the WSDL:
http://<hostname>:<port>/soap/services/<ServiceName>?wsdl
where:
hostname is the hostname of the SOAP server
port is the port on the SOAP server
ServiceName is the name of the WSDL to load

DAEAPI example
For example, to load the DAEAPI WSDL, type:
http://hostname1234:32000/soap/services/dae-service?wsdl

Sending SOAP requests

Use a SOAP tool to send requests to the endpoints for WSDLs.

To send a SOAP request

In the SOAP tool, type the endpoint where the Provisioning Server expects to
receive a request:
http://<hostname>:<port>/soap/services/<ServiceName>
where:
hostname is the hostname of the SOAP server
port is the port on the SOAP server
ServiceName is the name of the WSDL to load

Page 288 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 5 WSDLs

DAEAPI example
The DAEAPI endpoint is:
http:/hostname:port/soap/services/dae-service
An example request for the DAEAPI sendCoA operation would be:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soap="http://bridgewatersystems.com/dae/entity/soap/">
<soapenv:Header/>
<soapenv:Body>
<soap:sendCoARequest principal="admin"
credentials="TESTSECRET">
<wimax-hotlining>
<subscriber-name>abc3@null</subscriber-name>
</wimax-hotlining>
</soap:sendCoARequest>
</soapenv:Body>
</soapenv:Envelope>
The endpoint would return this response:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/
envelope/">
<soapenv:Body>
<ns1:sendCoAResponse xmlns:ns1="http:/
bridgewatersystems.com/dae/entity/soap/">
<query-failed>false</query-failed>
<wimax-hotlining>
<fa-node>
<sent>true</sent>
</fa-node>
</wimax-hotlining>
</ns1:sendCoAResponse>
</soapenv:Body>
</soapenv:Envelope>

WSDL examples
This section provides these complete WSDL examples:
• DAEAPI WSDL
• provisionComplete API and WSDL
• abortsession.wsdl

Service Controller 9.6.1-AAA October 26, 2012 Page 289

Chapter 5 WSDLs Provisioning API Guide

DAEAPI WSDL
Use the sendCoA, clearHotline, and sendDisconnect DAEAPI operations to trigger
the Provisioning Server to create and send a CoA or DM request. The sendCoA,
clearHotline, and sendDisconnect operations all use the WSDL described below.
For more information on these operations, see "DAEAPI operations" on page 82.
<definitions xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:wsdl="http://
schemas.xmlsoap.org/wsdl/" xmlns:tns="http://bridgewatersystems.com/dae/entity/
soap/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:xsd="http://
www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/
soap/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" name="DAEService"
targetNamespace="http://bridgewatersystems.com/dae/entity/soap/">
<types>
<xsd:schema xmlns="http://www.w3.org/2000/10/XMLSchema"
targetNamespace="http://bridgewatersystems.com/dae/entity/soap/">
<xsd:complexType name="node">
<xsd:annotation>
<xsd:documentation/>
</xsd:annotation>
<xsd:sequence>
<xsd:element maxOccurs="1" minOccurs="1" name="sent"
type="xsd:boolean"/>
<xsd:element maxOccurs="1" minOccurs="0"
name="pseudo-identifier" type="xsd:string"/>
<xsd:element maxOccurs="1" minOccurs="0"
name="rms-cluster-id" type="xsd:int"/>
<xsd:element maxOccurs="1" minOccurs="0"
name="failed-reason" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="wimaxHotliningInForCoA">
<xsd:annotation>
<xsd:documentation/>
</xsd:annotation>
<xsd:sequence>
<xsd:element default="true" maxOccurs="1" minOccurs="0"
name="send-fa-info" type="xsd:boolean"/>
<xsd:element default="false" maxOccurs="1" minOccurs="0"
name="send-ha-info" type="xsd:boolean"/>
<xsd:element maxOccurs="1" minOccurs="1"
name="subscriber-name" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>

Page 290 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 5 WSDLs

<xsd:complexType name="wimaxHotliningInForDM">
<xsd:annotation>
<xsd:documentation/>
</xsd:annotation>
<xsd:sequence>
<xsd:element maxOccurs="1" minOccurs="1"
name="subscriber-name" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="wimaxHotliningOut">
<xsd:annotation>
<xsd:documentation/>
</xsd:annotation>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="0"
name="fa-node" type="tns:node"/>
<xsd:element maxOccurs="unbounded" minOccurs="0"
name="ha-node" type="tns:node"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="request">
<xsd:annotation>
<xsd:documentation/>
</xsd:annotation>
<xsd:attribute maxOccurs="1" minOccurs="1" name="principal"
type="xsd:string"/>
<xsd:attribute maxOccurs="1" minOccurs="1" name="credentials"
type="xsd:string"/>
</xsd:complexType>
<xsd:element name="sendCoARequest">
<xsd:annotation>
<xsd:documentation/>
</xsd:annotation>
<xsd:complexType>
<xsd:complexContent>
<xsd:extension base="tns:request">
<xsd:sequence>
<xsd:element maxOccurs="1" minOccurs="1"
name="wimax-hotlining"
type="tns:wimaxHotliningInForCoA"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>

Service Controller 9.6.1-AAA October 26, 2012 Page 291

Chapter 5 WSDLs Provisioning API Guide

</xsd:complexType>
</xsd:element>
<xsd:element name="clearHotlineRequest">
<xsd:annotation>
<xsd:documentation/>
</xsd:annotation>
<xsd:complexType>
<xsd:complexContent>
<xsd:extension base="tns:request">
<xsd:sequence>
<xsd:element maxOccurs="1" minOccurs="1"
name="wimax-hotlining"
type="tns:wimaxHotliningInForCoA"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="sendDisconnectRequest">
<xsd:annotation>
<xsd:documentation/>
</xsd:annotation>
<xsd:complexType>
<xsd:complexContent>
<xsd:extension base="tns:request">
<xsd:sequence>
<xsd:element maxOccurs="1" minOccurs="1"
name="wimax-hotlining"
type="tns:wimaxHotliningInForDM"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="sendCoAResponse">
<xsd:annotation>
<xsd:documentation/>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="1" minOccurs="1"
name="query-failed" type="xsd:boolean"/>
<xsd:element maxOccurs="1" minOccurs="0"

Page 292 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 5 WSDLs

name="failed-reason" type="xsd:string"/>
<xsd:element maxOccurs="1" minOccurs="0"
name="wimax-hotlining" type="tns:wimaxHotliningOut"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="clearHotlineResponse">
<xsd:annotation>
<xsd:documentation/>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="1" minOccurs="1"
name="query-failed" type="xsd:boolean"/>
<xsd:element maxOccurs="1" minOccurs="0"
name="failed-reason" type="xsd:string"/>
<xsd:element maxOccurs="1" minOccurs="0"
name="wimax-hotlining" type="tns:wimaxHotliningOut"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="sendDisconnectResponse">
<xsd:annotation>
<xsd:documentation/>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="1" minOccurs="1"
name="query-failed" type="xsd:boolean"/>
<xsd:element maxOccurs="1" minOccurs="0"
name="failed-reason" type="xsd:string"/>
<xsd:element maxOccurs="1" minOccurs="0"
name="wimax-hotlining" type="tns:wimaxHotliningOut"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
</types>
<message name="sendCoARequest">
<part name="parameter" element="tns:sendCoARequest"/>
</message>
<message name="sendCoAResponse">
<part name="parameter" element="tns:sendCoAResponse"/>

Service Controller 9.6.1-AAA October 26, 2012 Page 293

Chapter 5 WSDLs Provisioning API Guide

</message>
<message name="sendDisconnectResponse">
<part name="parameter" element="tns:sendDisconnectResponse"/>
</message>
<message name="clearHotlineResponse">
<part name="parameter" element="tns:clearHotlineResponse"/>
</message>
<message name="clearHotlineRequest">
<part name="parameter" element="tns:clearHotlineRequest"/>
</message>
<message name="sendDisconnectRequest">
<part name="parameter" element="tns:sendDisconnectRequest"/>
</message>
<portType name="DAEServicePortType">
<operation name="clearHotlineReasonOperation">
<input message="tns:clearHotlineRequest"/>
<output message="tns:clearHotlineResponse"/>
</operation>
<operation name="sendCoAOperation">
<input message="tns:sendCoARequest"/>
<output message="tns:sendCoAResponse"/>
</operation>
<operation name="sendDisconnectOperation">
<input message="tns:sendDisconnectRequest"/>
<output message="tns:sendDisconnectResponse"/>
</operation>
</portType>
<binding name="DAESOAPBinding" type="tns:DAEServicePortType">
<soap:binding style="document" transport="http://schemas.xmlsoap.org
soap/http"/>
<operation name="clearHotlineReasonOperation">
<soap:operation soapAction="http://bridgewatersystems.com/entity/soap
DAEService/clearHotlineReasonOperation"/>
<input>
<soap:body use="literal"/>
</input>
<output>
<soap:body use="literal"/>
</output>
</operation>
<operation name="sendCoAOperation">
<soap:operation soapAction="http://bridgewatersystems.com/entity/soap
DAEService/sendCoAOperation"/>

Page 294 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 5 WSDLs

<input>
<soap:body use="literal"/>
</input>
<output>
<soap:body use="literal"/>
</output>
</operation>
<operation name="sendDisconnectOperation">
<soap:operation soapAction="http://bridgewatersystems.com/entity/soap
DAEService/sendDisconnectOperation"/>
<input>
<soap:body use="literal"/>
</input>
<output>
<soap:body use="literal"/>
</output>
</operation>
</binding>
<service name="dae-service">
<port name="DAEService" binding="tns:DAESOAPBinding">
<soap:address location="http://192.168.151.22:32000/soap/services
dae-service"/>
</port>
</service>
</definitions>

provisionComplete API and WSDL

This section provides an example provisionComplete API and provisionComplete
WSDL. The provisionComplete API is used as part of hotlining using the Policy
Controller.
In addition to provisionComplete, hotlining using the Policy Controller includes the
following SOAP APIs:
• newWiMAXDeviceNotification
• registerIPNotification
• returnIPNotification
• wimaxDeviceReauthenticate
For the newWiMAXDeviceNotification, registerIPNotification,
returnIPNotificationwimax, and DeviceReauthenticate WSDLs and APIs, see
mFormation documentation.

provisionComplete <?xml version="1.0" encoding="UTF-8"?>

API

Service Controller 9.6.1-AAA October 26, 2012 Page 295

Chapter 5 WSDLs Provisioning API Guide

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/
2001/XMLSchema-instance">
<soapenv:Body>
<ns1:provisionComplete xmlns:ns1="http://services.mformation.com
MFServices/" soapenv:encodingStyle="http://schemas.xmlsoap.org/soap
encoding/">
<provisionData href="#id0"/>
</ns1:provisionComplete>
<multiRef xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:ns2="http://services.mformation.com/MFServices/" id="id0"
soapenc:root="0" soapenv:encodingStyle="http://schemas.xmlsoap.org
soap/encoding/" xsi:type="ns2:ProvisionData">
<macAddress xsi:type="xsd:string">FFFFFFFFFFFF</macAddress>
<ipAddress xsi:type="xsd:string">0.0.0.11</ipAddress>
<commandStatus href="#id1"/>
</multiRef>
<multiRef xmlns:ns3="http://services.mformation.com/MFServices/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" id="id1"
soapenc:root="0" soapenv:encodingStyle="http://schemas.xmlsoap.org
soap/encoding/" xsi:type="ns3:CommandStatusCode">1</multiRef>
</soapenv:Body>
</soapenv:Envelope>

provisionComplete <?xml version="1.0" encoding="UTF-8"?>

WSDL <definitions xmlns:tns="http://services.mformation.com/MFServices/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://
schemas.xmlsoap.org/wsdl/soap/" xmlns="http://schemas.xmlsoap.org/wsdl/"
targetNamespace="http://services.mformation.com/MFServices/">
<types>
<xsd:schema xmlns:ns0="http://services.mformation.com/MFServices/"
xmlns:ns1="http://services.mformation.com/MFServices/" xmlns:ns2="http://
services.mformation.com/MFServices/" xmlns:tns="http://services.mformation.com/
MFServices/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
attributeFormDefault="qualified" elementFormDefault="qualified"
targetNamespace="http://services.mformation.com/MFServices/"><xsd:import
namespace="http://schemas.xmlsoap.org/soap/encoding/"> </
xsd:import><xsd:complexType
name="RegisterIPNotification"><xsd:sequence><xsd:element maxOccurs="1"
minOccurs="1" name="macAddress" nillable="false" type="xsd:string"/
><xsd:element maxOccurs="1" minOccurs="1" name="validityPeriod"
nillable="false" type="xsd:int"/></xsd:sequence></xsd:complexType>

Page 296 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 5 WSDLs

<xsd:complexType name="MacIpAddr"><xsd:sequence><xsd:element
maxOccurs="1" minOccurs="1" name="macAddress" nillable="false"
type="xsd:string"/><xsd:element maxOccurs="1" minOccurs="1"
name="ipAddress" nillable="true" type="xsd:string"/></xsd:sequence></
xsd:complexType><xsd:simpleType
name="CommandStatusCode"><xsd:restriction base="xsd:int"><xsd:enumeration
value="1"/><!-- Success --><xsd:enumeration value="2"/><!-- Failed --></
xsd:restriction></xsd:simpleType><xsd:complexType
name="ProvisionData"><xsd:sequence><xsd:element maxOccurs="1"
minOccurs="1" name="macAddress" nillable="false" type="xsd:string"/
><xsd:element maxOccurs="1" minOccurs="1" name="ipAddress" nillable="false"
type="xsd:string"/><xsd:element maxOccurs="1" minOccurs="1"
name="commandStatus" nillable="false" type="tns:CommandStatusCode"/></
xsd:sequence></xsd:complexType>
<xsd:element
name="provisionComplete"><xsd:complexType><xsd:sequence><xsd:element
form="unqualified" name="provisionData" type="ns0:ProvisionData"/></
xsd:sequence></xsd:complexType></xsd:element><xsd:element
name="registerIPNotification"><xsd:complexType><xsd:sequence><xsd:element
form="unqualified" name="registerIPNotification" type="ns1:RegisterIPNotification"/
></xsd:sequence></xsd:complexType></xsd:element><xsd:element
name="provisionCompleteResponse"><xsd:complexType><xsd:sequence/></
xsd:complexType></xsd:element><xsd:element
name="registerIPNotificationResponse"><xsd:complexType><xsd:sequence><xsd
:element form="unqualified" name="macIpAddr" type="ns2:MacIpAddr"/></
xsd:sequence></xsd:complexType></xsd:element></xsd:schema>
</types>
<message name="provisionCompleteResponse">
</message>
<message name="provisionComplete">
<part name="provisionData" type="tns:ProvisionData">
</part>
</message>
<message name="registerIPNotificationResponse">
<part name="macIpAddr" type="tns:MacIpAddr">
</part>
</message>
<message name="registerIPNotification">
<part name="registerIPNotification" type="tns:RegisterIPNotification">
</part>
</message>
<portType name="OmadmToAaaPort">
<operation name="registerIPNotification">
<input message="tns:registerIPNotification">
</input>
<output message="tns:registerIPNotificationResponse">

Service Controller 9.6.1-AAA October 26, 2012 Page 297

Chapter 5 WSDLs Provisioning API Guide

</output>
</operation>
<operation name="provisionComplete">
<input message="tns:provisionComplete">
</input>
<output message="tns:provisionCompleteResponse">
</output>
</operation>
</portType>
<binding name="OmadmToAaaBinding" type="tns:OmadmToAaaPort">
<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/
http"/>
<operation name="registerIPNotification">
<soap:operation soapAction="http://services.mformation.com/
MFServices/registerIPNotification"/>
<input>
<soap:body encodingStyle="http://schemas.xmlsoap.org/soap/
encoding/" namespace="http://services.mformation.com/MFServices/"/>
</input>
<output>
<soap:body encodingStyle="http://schemas.xmlsoap.org/soap/
encoding/" namespace="http://services.mformation.com/MFServices/"/>
</output>
</operation>
<operation name="provisionComplete">
<soap:operation soapAction="http://services.mformation.com/
MFServices/provisionComplete"/>
<input>
<soap:body encodingStyle="http://schemas.xmlsoap.org/soap/
encoding/" namespace="http://services.mformation.com/MFServices/"/>
</input>
<output>
<soap:body encodingStyle="http://schemas.xmlsoap.org/soap/
encoding/" namespace="http://services.mformation.com/MFServices/"/>
</output>
</operation>
</binding>
<service name="OmadmToAaaService">
<port name="OmadmToAaa" binding="tns:OmadmToAaaBinding">
<soap:address location="http://localhost:8080/services/OmadmToAaa"/>
</port>
</service>
</definitions>

Page 298 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 5 WSDLs

abortsession.wsdl
This section provides an example of the WSDL used in communication between a
Hotlining Application and the Provisioning Server for Diameter mid-session
hotlining.
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" xmlns:ns0="http://
api.abortsession.bridgewatersystems.com" xmlns:soap12="http://
schemas.xmlsoap.org/wsdl/soap12/" xmlns:http="http://schemas.xmlsoap.org/wsdl/
http/" xmlns:ns1="http://org.apache.axis2/xsd" xmlns:wsaw="http://www.w3.org/
2006/05/addressing/wsdl" xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" targetNamespace="http://
api.abortsession.bridgewatersystems.com">
<wsdl:types>
<xs:schema xmlns:ns="http://api.abortsession.bridgewatersystems.com"
attributeFormDefault="qualified" elementFormDefault="qualified"
targetNamespace="http://api.abortsession.bridgewatersystems.com">
<xs:element name="getUserByIp">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0" name="param0" nillable="true"
type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="getUserByIpResponse">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0" name="return" nillable="true"
type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="getUserByName">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0" name="param0" nillable="true"
type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="getUserByNameResponse">
<xs:complexType>
<xs:sequence>

Service Controller 9.6.1-AAA October 26, 2012 Page 299

Chapter 5 WSDLs Provisioning API Guide

<xs:element minOccurs="0" name="return" nillable="true"

type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="getUserByNameIp">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0" name="param0" nillable="true"
type="xs:string"/>
<xs:element minOccurs="0" name="param1" nillable="true"
type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="getUserByNameIpResponse">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0" name="return" nillable="true"
type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
</wsdl:types>
<wsdl:message name="getUserByNameIpRequest">
<wsdl:part name="parameters" element="ns0:getUserByNameIp"/>
</wsdl:message>
<wsdl:message name="getUserByNameIpResponse">
<wsdl:part name="parameters"
element="ns0:getUserByNameIpResponse"/>
</wsdl:message>
<wsdl:message name="getUserByIpRequest">
<wsdl:part name="parameters" element="ns0:getUserByIp"/>
</wsdl:message>
<wsdl:message name="getUserByIpResponse">
<wsdl:part name="parameters" element="ns0:getUserByIpResponse"/>
</wsdl:message>
<wsdl:message name="getUserByNameRequest">
<wsdl:part name="parameters" element="ns0:getUserByName"/>
</wsdl:message>
<wsdl:message name="getUserByNameResponse">
<wsdl:part name="parameters" element="ns0:getUserByNameResponse"/>
</wsdl:message>

Page 300 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 5 WSDLs

<wsdl:portType name="sess-term-servicesPortType">
<wsdl:operation name="getUserByNameIp">
<wsdl:input message="ns0:getUserByNameIpRequest"
wsaw:Action="urn:getUserByNameIp"/>
<wsdl:output message="ns0:getUserByNameIpResponse"
wsaw:Action="urn:getUserByNameIpResponse"/>
</wsdl:operation>
<wsdl:operation name="getUserByIp">
<wsdl:input message="ns0:getUserByIpRequest"
wsaw:Action="urn:getUserByIp"/>
<wsdl:output message="ns0:getUserByIpResponse"
wsaw:Action="urn:getUserByIpResponse"/>
</wsdl:operation>
<wsdl:operation name="getUserByName">
<wsdl:input message="ns0:getUserByNameRequest"
wsaw:Action="urn:getUserByName"/>
<wsdl:output message="ns0:getUserByNameResponse"
wsaw:Action="urn:getUserByNameResponse"/>
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="sess-term-servicesSOAP11Binding"
type="ns0:sess-term-servicesPortType">
<soap:binding transport="http://schemas.xmlsoap.org/soap/http"
style="document"/>
<wsdl:operation name="getUserByNameIp">
<soap:operation soapAction="urn:getUserByNameIp" style="document"/
>
<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
</wsdl:operation>
<wsdl:operation name="getUserByIp">
<soap:operation soapAction="urn:getUserByIp" style="document"/>
<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
</wsdl:operation>
<wsdl:operation name="getUserByName">

Service Controller 9.6.1-AAA October 26, 2012 Page 301

Chapter 5 WSDLs Provisioning API Guide

<soap:operation soapAction="urn:getUserByName" style="document"/>

<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<wsdl:binding name="sess-term-servicesSOAP12Binding"
type="ns0:sess-term-servicesPortType">
<soap12:binding transport="http://schemas.xmlsoap.org/soap/http"
style="document"/>
<wsdl:operation name="getUserByNameIp">
<soap12:operation soapAction="urn:getUserByNameIp"
style="document"/>
<wsdl:input>
<soap12:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap12:body use="literal"/>
</wsdl:output>
</wsdl:operation>
<wsdl:operation name="getUserByIp">
<soap12:operation soapAction="urn:getUserByIp" style="document"/>
<wsdl:input>
<soap12:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap12:body use="literal"/>
</wsdl:output>
</wsdl:operation>
<wsdl:operation name="getUserByName">
<soap12:operation soapAction="urn:getUserByName"
style="document"/>
<wsdl:input>
<soap12:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap12:body use="literal"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>

Page 302 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 5 WSDLs

<wsdl:binding name="sess-term-servicesHttpBinding"
type="ns0:sess-term-servicesPortType">
<http:binding verb="POST"/>
<wsdl:operation name="getUserByNameIp">
<http:operation location="sess-term-services/getUserByNameIp"/>
<wsdl:input>
<mime:content type="text/xml" part="getUserByNameIp"/>
</wsdl:input>
<wsdl:output>
<mime:content type="text/xml" part="getUserByNameIp"/>
</wsdl:output>
</wsdl:operation>
<wsdl:operation name="getUserByIp">
<http:operation location="sess-term-services/getUserByIp"/>
<wsdl:input>
<mime:content type="text/xml" part="getUserByIp"/>
</wsdl:input>
<wsdl:output>
<mime:content type="text/xml" part="getUserByIp"/>
</wsdl:output>
</wsdl:operation>
<wsdl:operation name="getUserByName">
<http:operation location="sess-term-services/getUserByName"/>
<wsdl:input>
<mime:content type="text/xml" part="getUserByName"/>
</wsdl:input>
<wsdl:output>
<mime:content type="text/xml" part="getUserByName"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="sess-term-services">
<wsdl:port name="sess-term-servicesSOAP11port_http"
binding="ns0:sess-term-servicesSOAP11Binding">
<soap:address location="http://localhost:8080/axis/services"/>
</wsdl:port>
<wsdl:port name="sess-term-servicesSOAP12port_http"
binding="ns0:sess-term-servicesSOAP12Binding">
<soap12:address location="http://localhost:8080/axis/services"/>
</wsdl:port>
<wsdl:port name="sess-term-servicesHttpport"
binding="ns0:sess-term-servicesHttpBinding">
<http:address location="http://localhost:8080/axis/services"/>
</wsdl:port>

Service Controller 9.6.1-AAA October 26, 2012 Page 303

Chapter 5 WSDLs Provisioning API Guide

</wsdl:service>
</wsdl:definitions>

Page 304 October 26, 2012 Service Controller 9.6.1-AAA

 Command line utilities

6
Chapter 6
Chapter

This chapter describes the Service Controller command line utilities used to view or
change Profile Database records.
The topics are:
• About the utilities
• Utility details

Service Controller 9.6.1-AAA October 26, 2012 Page 305

Chapter 6 Command line utilities Provisioning API Guide

About the utilities

The Provisioning Server services all requests from the command line utilities and
the XML API.
The utilities listed in Table 27 can be run manually at the console or called by scripts
on any host machine connected to the Service Controller. These utilities are stored
in the /WideSpan/vip directory.

Table 27: Command line utilities summary

Utility Description

changeprofile Changes the user profile set for a user.

deluser Marks a user as deleted.

insuser Creates a new user record.

listuser List all users that match the search criteria.

moveuser Moves a user to a new organization.

reactivateuser Sets the status of the user record to active, based on login name
and domain.

readuser Returns one or more user records.

setpassword Assigns a password to a user.

suspenduser Sets the status of a specified user record to suspended.

unsuspenduser Reactivates a suspended user.

updattribs Updates or inserts an attribute for a user.

The first argument for utilities is /WideSpan/config/vipclient.conf. The vipclient.conf

file identifies the location of one or more Service Controllers and the port on which
to communicate.
These utilities do not enforce the standard Service Controller business rules.
Each utility requires arguments, as described in the sections that follow. When
entering names, for example domain or user names, the % character can be used
as a wildcard.
Any arguments that contain spaces, such as an organization name, must be
enclosed in single quotation marks. Any single quotations marks used as a part of
an actual name must be escaped.
Note The order of the output from any of these commands is dependent on the
internal structure of the Profile Database and may not always return in the
same order.

Page 306 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 6 Command line utilities

When an execution fails, it results in a simple error message. The detailed error
message is sent to the /var/adm/messages file. Table 28 lists return codes.

Table 28: Exit return codes

Code Description

0 Command was successful

00003 No attributes found. Ensure that all required dependencies are supplied.

1 System error with descriptive message

2 User does not exist

3 Invalid password

4 Privilege violation

5 User already exists

6 User not deleted

7 Service not found

8 Version mismatch between the Provisioning Server and the utility client

9 User already deleted

10 More than one user found

11 User already active

Running the utilities

Log in as the widespan user:
su - widespan
The /WideSpan/vip command utility directory is in the default path for the aaasc
user. Run the utilities by name, for example:
adddntg /WideSpan/config/vipclient.conf -1 trunkgroup2 100
200 -C

Determining CLU version

Each CLU supports the -v option to display the version of the utility. Use this option
to determine patch levels or verify upgrades.
For example:
adddntg -v

Service Controller 9.6.1-AAA October 26, 2012 Page 307

Chapter 6 Command line utilities Provisioning API Guide

Determining usage information

Each CLU supports the -h option to display the usage information for the utility.
For example:
adddntg -h

Utility details
This section describes the command line utilities.
Note When the config_id value is set to -1, the currently active configuration is
referenced.

changeprofile
Changes the user profile set for the specified user. The new user profile set must
exist already.

Usage changeprofile config_file loginname domain profile modby

were:
config_file is the full path to the vipclient.conf file
loginname is the user’s login name (note that this may be different than the user
name that is used as part of the email address)
domain is the domain name to which this user belongs
profile is the new user profile set to assign to this user
modby is the user who issues this request
For example, to change the user bws1234 in the bws.com domain from the "Basic"
user profile set to the "Premium" user profile set, type:
changeprofile /WideSpan/config/vipclient.conf bws1234 bws.com
Premium admin

Output If successful, changeprofile exits with a success code and no message displays.
On error, changeprofile exits with a non-zero exit status and a message line in the
format:
Failed | <message>

Page 308 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 6 Command line utilities

deluser
Marks the specified user as deleted.

Usage deluser config_file loginname domain modby

where:
config_file is the full path to the vipclient.conf file
loginname is the user's login name (note that this may be different than the user
name which is used as part of the email address)
domain is the domain name to which this user belongs
modby is the user who issues this request
For example, to delete user bws1234 in the bws.com domain, type:
deluser /WideSpan/config/vipclient.conf bws1234 bws.com admin

Output If successful, deluser exits with the following message:

OK
If an error occurs, deluser exits with a non-zero exit status and a message line in
the format:
Failed | <message>

insuser
Creates a new user record. A user profile set and an organization must exist to
create a user.
Note In an attempt to create a user with the same login name and password as
another user, the command is rejected and the existing user’s account is
suspended. This is done for security reasons, to prevent a user from
guessing the login name and password of an existing user. Change the
user’s password (see "setpassword" on page 315) and then reactivate the
user account (see "reactivateuser" on page 313).

Usage insuser config_file loginname username password encrypt

org_name profile status authtype billingid paidby modby [-a
account_name] [-u billing unit] [-p billing period] [-d
billing date] [-c conversion flag] [-i] [-m mobile id number]
[-s dmu state] [-k chap key] [-t authenticator]

Service Controller 9.6.1-AAA October 26, 2012 Page 309

Chapter 6 Command line utilities Provisioning API Guide

where:
config_file is the full path to the vipclient.conf file
loginname is the user's login name
username is the user's username
password is the password to assign to the user
If entered as clear text, limit the length according to the encrypt parameter
supplied (-2, -1, or 0)
If entering as encrypted (1 or 2), then limit the length to 255
encrypt is the type of encryption to use when storing the password., 0 = clear
text, 1 = UNIX encryption (password already UNIX encrypted), 2 = BSD
encryption (password already BSD encrypted), -1 = UNIX encryption (password
in clear text; encrypt before storing), -2 = BSD encryption (password in clear
text; encrypt before storing)
org_name is the fully qualified organization name (delimited by ’/’) to which this
user belongs
profile is the user profile set to assign to this user
status is the initial status of the user.
A = active
P = pending
Using -P along with a date deactivates the user until the specified date.
When that date arrives the user is set to active.
authtype (optional) is the authentication type to be applied when this user
connects:
1 = PAP/CHAP
2 = SecureId (future)
billingid (optional) is a billing ID for the new user; enter an empty string ('' '') to
generate an ID
paidby (optional) is the fully qualified organization name (delimited by ’/’) that
identifies the organization that pays this user’s bill. Enter an empty string ('' '') if
the user pays their own bill
modby (optional) is the user who issues this request
account_name (optional) is the account name to assign to this credential

Page 310 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 6 Command line utilities

billing unit (optional) is the interval at which bills are calculated:

M (month) - default
W (week)
D (day)
Y (year)
N (none)
billing period (optional) is the number of units between bill generation; the
maximum is:
M - 11
W - 51
D-6
Y-2
billing date (optional) is a future date on which to start billing (default is
immediate), specified in the format MM/DD/YYYY. Do not set this date to later
than the year 2037
conversion flag (optional):
Y converts user’s password to specified encryption type first time user logs
in
N keeps password as original encryption type
-i is an optional flag which prevents an existing user with the same login name
and password from being suspended; instead, the new user is not created and
the following error is returned: “Failed | User username in domain not
suspended”
Note For the -i flag to work, loginname uniqueness must be disabled in the
database.
mobile id number (optional) is a request to view mobile data for the user
dmu state (optional) is the DMU state. The DMU state is set to DISABLED by
default. Set the DMU state to 1 to update keys
chap key (optional) is the DMU Simple IP CHAP key in hexidecimal format, up
to 16 bytes
authenticator (optional) is the mobile node authenticator in hexidecimal format,
up to 3 bytes
For example, to create a new user, whose organization pays all bills, type:
insuser /WideSpan/config/vipclient.conf bws1234 johnsmith
x1234x 0 ’Root Organization/Bridgewater Systems’ ’Premium’ A
1 ’’ ’Root Organization/Bridgewater Systems’ admin

Service Controller 9.6.1-AAA October 26, 2012 Page 311

Chapter 6 Command line utilities Provisioning API Guide

Output If successful, the utility returns the following message:

OK
If an error occurs, the utility exits with a non-zero exit status and displays a
message in the format:
Failed | <message>

listuser
Lists all users that match the given search criteria.

Usage listuser config_file -b billing_id [-m]

or
listuser config_file -l login [-o org_name] [-d domain] [-m]
where:
config_file is the full path to the vipclient.conf file
billing_id is the billing ID of the user. Use this option on its own if required
login is the user’s login name (-o or -d must be used if -l is specified). To list all
users in an organization or domain use the -l ‘%’ option
org_name is the fully qualified organization name (delimited by “/”)
domain is the domain name
-m is used to display mobile data for the users
When the -l option is used, one of the -o or -d options is also required.
For example:
listuser /WideSpan/config/vipclient.conf -1 roger394 -d
company.com

Output If successful, the utility displays:

OK|status|username|loginname|password|encrypt_type|dom_nam
e|org_name|usr_prf_id|billing_id|snr_billing_id|created|la
stmod|pending_date|reason|modby
If the -m option is specified, the utility displays:
OK|status|username|loginname|password|encrypt_type|dom_nam
e|org_name|usr_prf_id|billing_id|snr_billing_id|created|la
stmod|pending_date|reason|modby|MIN|DMU state|MN HA key|MN
AAA key|Simple IP CHAP key|authenticator
Status includes Active, Suspended, Deleted or Pending. Pending is returned with a
pending date. This indicates that the user is inactive until the specified date.

Page 312 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 6 Command line utilities

If an error occurs, the utility exists with a non-zero exit status and a message line in
the format:
Failed | <message>

moveuser
Moves a user to a new organization.

Usage moveuser config_file loginname domain new_org

where:
config_file is the client configuration file
loginname is the user‘s login name
domain is the domain name for the specified user‘s login name
new_org is the fully qualified name for the user‘s new organization
For example:
moveuser /Widespan/config/vipclient.conf jdoe jdoe.com ‘/
RootOrganization/Parent/Marketing’

Output If successful, the utility displays:

OK|UserId||||
If an error occurs, the utility exists with a non-zero exit status and a message line in
the format:
Failed | <message>

reactivateuser
Changes the status of the specified user record to active, based on login name and
domain. It is used to reactivate a deleted or suspended user.

Usage reactivateuser config_file loginname domain modby

where:
config_file is the full path to the vipclient.conf file
loginname is the user's login name (note that this may be different from the user
name which is used as part of the email address)
domain is the domain name to which this user belongs
modby is the user who issues this request
For example, to activate user bws1234, type:
reactivateuser /WideSpan/config/vipclient.conf bws1234
bws.com admin

Service Controller 9.6.1-AAA October 26, 2012 Page 313

Chapter 6 Command line utilities Provisioning API Guide

Output If successful, reactivateuser exits with a success code and no message displays. If
there is a suspended user matching the specified loginname/domain combination, it
is made active. If there is no suspended user matching the loginname/domain but
there is a single deleted user record found, it is made active.
If several deleted user records are found that match the specified loginname/
domain, a list of deleted user records displays in the following format:
OK|userid|username|loginname|domain|org|billingId|modby|cr
eated
where:
userid is the unique user identifier.
username is the user's username
loginname is the user's loginname
domain is the user's domain name
org is the organization to which this user belongs
billingId is the user's billing identifier
modby is the administrator who created or last modified this record
created is the creation date and time of the record
Use the reactivateuserid utility to reactivate the appropriate record, specifying the
unique user ID.
If an error occurs, reactivateuser exits with a non-zero exit status and displays a
message line in the format:
Failed | <message>

readuser
Reads and returns one or more user records.

Usage readuser config_file loginname domain

where:
config_file is the full path to the vipclient.conf file
loginname is the user's login name. A wildcard character (%) can be used to
read multiple user records
domain is the domain name to which this user belongs
For example, to view the user record for user bws1234, type:
readuser /WideSpan/config/vipclient.conf bws1234 bws.com

Page 314 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 6 Command line utilities

Output If successful, the user records are displayed on standard output, one per line, in the
following format
OK|status|username|loginname|domain|org|profile|billingid|
modby|created|lastmod
where:
status is the status of this record (A=active, D=deleted, S=suspended
P=pending). Using -P along with a date deactivates the user until the specified
date. When that date arrives the user is set to active.
username is the username of this user
loginname is the loginname of this user
domain is the domain name to which this user belongs
org is the organization to which this user belongs
profile is the profile set assigned to this user
billingid is the user's billing ID
modby is the administrator who created or last modified this user record
created is the date this user record was created
lastmod is the date this user record was last modified
If an error occurs, readuser exits with a non-zero exit status and a message line in
the format:
Failed | <message>

setpassword
Assigns a password to a user.

Usage setpassword config_file loginname domain password modby

option -i | -e
where:
config_file is the full path to the vipclient.conf file
loginname is the user's login name
domain is the domain name to which this user belongs
password is the password to assign to the user (cannot contain spaces). Limit
the length of the clear text entered, based on encryption to be performed. This
is controlled by either the stored encryption type and password conversion flag
values, or by the override parameters for this function
modby is the user who issues this request

Service Controller 9.6.1-AAA October 26, 2012 Page 315

Chapter 6 Command line utilities Provisioning API Guide

option is one of:

-i: a flag that prevents an existing user (user A) with the same login name
and password from being suspended if another user (user B) with the same
login name attempts to set their password to the same one as the original
user (user A); instead, the password change fails and an error message
appears: “User loginname in domain not suspended”. If this option is not
specified user A is suspended in this scenario
-e type: a flag that changes the encryption type before setting the
password, where type is one of:
0: changes the encryption type to cleartext. This is the default
1: changes the encryption type to Unix crypt
2: changes the encryption type to MD5
For example, to assign a new password to user bws1234 with MD5 encryption, and
store the existing password and encryption type to restore later, type:
setpassword /WideSpan/config/vipclient.conf bws1234 bws.com
1228 admin -e2

Output If successful, setpassword exits with a success code and no message displays.
If an error occurs, setpassword exits with a non-zero exit status and a message line
in the format:
Failed | <message>

suspenduser
Marks an active user record as suspended.

Usage suspenduser config_file loginname domain modby [-r reason]

where:
config_file is the full path to the vipclient.conf file
loginname is the user's login name
domain is the domain name to which this user belongs
modby is the user who issues this request
-r reason the reason the user is being suspended
For example, to suspend user bws1234, type:
suspenduser /WideSpan/config/vipclient.conf bws1234 bws.com
admin

Page 316 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 6 Command line utilities

Output If successful, suspenduser exits with a success code and no message displays.
If an error occurs, suspenduser exits with a non-zero exit status and displays a
message line in the format:
Failed | <message>

unsuspenduser
Reactivates a suspended user. It does not reactivate a deleted or pending user. To
reactivate a deleted or pending user, use the reactivateuser or reactivateuserid
utilities.

Usage unsuspenduser config_file loginname domain modby

where:
config_file is the full path to the vipclient.conf file
loginname is the user’s login name
domain is the domain name to which this user belongs
modby is the user who issues this request
For example to reactivate user bws1234, type:
unsuspenduser /WideSpan/config/vipclient.conf bws1234 bws.com

Output If successful, unsuspenduser exits with a success code and no message displays.
If an error occurs, unsuspenduser exits with a non-zero exit status and displays a
message line in the format:
Failed | <message>

updattribs
Updates or inserts an attribute for a user. The login name and domain of the user
must be specified to uniquely identify the user. The service name defines the
service class to which the attribute belongs. The context defines the attribute
context.

Usage updattribs config_file name value context subscript loginname

domain service [password]
where:
config_file is the full path to the vipclient.conf file
name is the attribute name to be updated or added
value is the attribute value (always stored as a string)

Service Controller 9.6.1-AAA October 26, 2012 Page 317

Chapter 6 Command line utilities Provisioning API Guide

context is the context for storing this attribute:

1: user
2: user profile set
4: organization
8: organization profile set
16: domain
32: domain profile set
256: default
subscript is the attribute subscript (-1 for single-value attributes; start at 0 for
multi-value attributes);
loginname is the user's login name
domain is the domain name to which this user belongs
service is the name of the service class for which the attributes are to be
inserted
password is the user's password, this is optional. If specified, the user is
authenticated before their attributes are updated
For example:
updattribs /WideSpan/config/vipclient.conf smtpServer
in.mail.com 1 -1 roger394 company.com mail iamroger394
For example, to update attributes for a user with only one connection service
profile:
updattribs /WideSpan/config/vipclient.conf
“Max-Sessions-Per-User” 25 1 “-1” abcuser abc.com “RADIUS
ConnectionService”
An example of updating attributes for a user with multiple connection service
profiles is:
updattribs /WideSpan/config/vipclient.conf
“Max-Sessions-Per-User” 25 1 “-1” abcuser abc.com “RADIUS
ConnectionService:MIPHA”
where:
MIHA represents a connection service profile

Output If successful, the utility outputs this message:

OK
If an error occurs, a message displays in the following format:
Failed | <message>

Page 318 October 26, 2012 Service Controller 9.6.1-AAA

Provisioning API Guide Chapter 6 Command line utilities

If the specified attribute currently exists in the Profile Database at this context, its
value is overwritten with the supplied value. If the attribute does not exist, it is
created.
To delete an attribute, update it with a null value (“”). To delete an array of attributes,
update it with a null value and a subscript of -2.

Service Controller 9.6.1-AAA October 26, 2012 Page 319

Chapter 6 Command line utilities Provisioning API Guide

Page 320 October 26, 2012 Service Controller 9.6.1-AAA

 ©1997-2012
Bridgewater Systems Corporation
All rights reserved.