Oracle® Communications IP Service Activator

API Developer's Guide

Release 7.3.4

E75634-01

June 2016

Oracle Communications IP Service Activator API Developer's Guide, Release 7.3.4

E75634-01

Copyright © 2016, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.

Contents

Preface

- Audience

- Accessing Oracle Communications Documentation

- Documentation Accessibility

- Document Revision History

1 API Overview

- About this Guide

- About IP Service Activator APIs

2 Working with the OJDL API

- About the OJDL API

- System Architecture

- Prerequisites for Installing OJDL

- Installing OJDL

- Using the OJDL API

- Java Development Environment

- OJDL Directory and File Structure

- The doc Directory

- The lib Directory

- The Samples Directory

- JavaDocs

- Java Classes

- Best Practices for Minimizing Commits

- Managing Configuration Policies Using the OJDL API

- Initial Setup

- Creating a Configuration Policy

- Creating the Configuration Policy Data Type

- Creating the RuleGeneric Object to Contain the Configuration Policy

- Assigning the Configuration Policy to the Required Device and Interface Roles

- Modifying a Configuration Policy

- Querying the EOM for the Configuration Policy

- Modifying the Policy Definition

- Registering an Interface Policy

- Creating a Subinterface

- Creating a Main Interface

- Decorating an Interface

- Comparing Created and Discovered Interfaces

- Configuration Policy Classes

- Example Source Code

3 Working with the Programmatic Intent-Based Network REST API

- About the REST API

- About REST API Methods

- About Installing the REST API

- Setting Up WebLogic Server Security

- Configuring Identity and Trust Keystores in WebLogic Server

- Testing the SSL Configuration

- Security and Authentication

- Working with the Groovy Scripting Language

- Developing Custom Groovy Scripts

- Groovy Script Examples

- Example: Generating CTM Commands

- Example: Deleting a Layer 2 Ethernet Service

- About Transactions

- About Polling Using the GET Method

- About Logging

- Logging Using WebLogic Server Configuration

- Configuring EOM Logging Using the IP Service Activator Configuration GUI

- Configuring Additional Logging Using Groovy Scripts

4 Working with the Web Service API

- About the Web Service API

- About Web Services and OIM

- Design Studio for IP Service Activator

- Configuring Web Services

- Pre-requisites for Web Services

- Configuring Web Services

- Configuring OSS Integration Manager

- Deploying and Undeploying Web Services

- About Web Service Security

- About OSM Data Providers

- Finding and Retrieving Data

- Finding Objects

- Retrieving Objects

- Retrieving Other Data

- Web Service Operations

Preface

This guide provides information about developing application programming interfaces (APIs) to Oracle Communications IP Service Activator.

This guide provides information about the following APIs:

- OSS Java Development Library (OJDL) API

- REST API

- Web Services API

Audience

This guide is intended for systems integrators and developers who will be using any of the supported APIs to develop their own interfaces to IP Service Activator. For example, you can use OJDL to develop customized web-based applications for Customer Network Management.

It assumes that readers have the following knowledge:

- Familiarity with the core IP Service Activator features

- Knowledge of the Oracle Solaris operating system and its commands

Accessing Oracle Communications Documentation

IP Service Activator for Oracle Communications documentation, and additional Oracle documentation, is available from Oracle Help Center:

http://docs.oracle.com

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

Document Revision History

The following table lists the revision history for this guide.

Version

Date

Description

E75634-01

June 2016

Initial release

1 API Overview

This guide provides information that you can use when working with Oracle Communications IP Service Activator application programming interfaces (APIs). The IP Service Activator APIs can be extended through custom code. The APIs, or extended APIs, can be called from various places, such as from custom rulesets, custom Web services, or customized portions of the user interface (UI).

About this Guide

This guide provides information about common things you need to do when working with any of the IP Service Activator APIs, such as working with transactions, handling errors, and logging messages.

The IP Service Activator APIs documented in this guide describe API usage patterns and best practices for implementing common business scenarios. Code samples are provided to show how to use the APIs and what to expect when implementing the APIs.

This guide provides information about managing configuration policies using the APIs, entity manager classes, and examples of code that show common methods.

This guide does not include detailed Javadoc information, nor does it cover model and domain information that are provided in other IP Service Activator documentation. This guide assumes that you are familiar with IP Service Activator functionality, and are planning to extend IP Service Activator functionality by implementing a custom solution based on information provided in IP Service Activator developer documentation.

About IP Service Activator APIs

The following APIs are provided with IP Service Activator and are documented in this guide:

- OSS Java Development Library (OJDL) API: Allows you to use Java to develop or customize interfaces, including web-based or intranet-based user interfaces.

- REST API: Allows you to create customized Groovy scripts with common REST methods that you can use to make calls through a REST web service interface to retrieve, update, delete, and create resources. You can use this API from Oracle Communications Order and Service Management (OSM) or any client that is capable of using the REST protocol.

- Web Services API: Provides a web service interface through which OSM can manage service activation transactions. This web service is usable only from the activation task in OSM.

2 Working with the OJDL API

This chapter outlines OSS Java Development Library (OJDL) for Oracle Communications IP Service Activator, including the Java classes provided for developers.

The OJDL provides a Java-based Application Programming Interface (API) to IP Service Activator. It includes a set of Java classes with some code samples, and an example web interface.

This chapter assumes you have the following:

- Knowledge of the OSS Integration Manager (OIM), including the External Object Model (EOM), the OIM command language, and the ability to write scripts. See IP Service Activator OSS Integration Manager Guide for more information.

- Experience using the Java programming language and Java technologies.

About the OJDL API

The OJDL API is a generic Java API for IP Service Activator, which allows Java developers to develop or customize interfaces, including web-based or intranet-based user interfaces.

The OJDL package includes:

- Java classes

- Java code samples

You can use the OJDL to develop Java-based interfaces that are used to integrate IP Service Activator with components of your environment. These could include, for example, your internal Operational Support System (OSS) environment or an external Customer Network Management solution.

System Architecture

Figure 2-1 shows the relationship between the OJDL and the rest of the IP Service Activator system:

Figure 2-1 OJDL in the IP Service Activator System

The OJDL uses the OSS Integration Manager (OIM) interface and provides access to the External Object Model (EOM), a simplified version of IP Service Activator's internal object model used by the OIM API. The OJDL is OSS compliant.

In effect, the OJDL provides additional layers that are built on top of OIM, which in turn sits on top of the core IP Service Activator system, as shown in Figure 2-2.

Figure 2-2 OJDL in the IP Service Activator Architecture Layers

The EOM is a subset of IP Service Activator's internal object model. It defines all the objects that can be accessed or updated by external applications, including their attributes and the relationships between them. The EOM allows you to create and access data objects without requiring knowledge of the underlying complexity of the entire object model.

The OJDL Java classes provide access to the objects in the EOM. The OJDL provides the same functionality as the OIM CLI, allowing you to create objects, get and set attributes, search for objects, manage transactions, and report errors.

Prerequisites for Installing OJDL

There are no restrictions on where to install the OJDL directory on the host system.

The prerequisites for using the OJDL are:

- Your IP Service Activator installation must include an instance of the OIM. For more information, see IP Service Activator Installation Guide.

- If you are developing Java code or running web-based applications, a suitable Java development environment must be installed, such as the Java Platform, Standard Edition (Java SE). For more information, see "Java Development Environment".

- You must have IP Service Activator configured to allow users to log in concurrently, so that you can log in to IP Service Activator using OJDL. By default, the user that is created during IP Service Activator installation does not have this option enabled. For more information about enabling this option, see the section about changing the default user in IP Service Activator System Administrator's Guide.

Installing OJDL

The OJDL package is not installed as part of the IP Service Activator standard installation. It is a separate package that you can download from the Oracle software delivery website.

To install the OJDL:

1. Log in to the Oracle software delivery Web site and select Product Downloads. Select Oracle Communications IP Service Activator, and then select the Components folder for the release that you want.

2. Download the ojdlpackage-versionNum.zip file available at the following path on the Oracle software delivery website:
Oracle Communications IP Service Activator Media Pack -> Oracle Communications IP Service Activator Software for Solaris

where versionNum is the version of IP Service Activator.

3. Move the file to the desired directory on the host where you are installing OJDL. There are no restrictions on that directory path that you choose.

4. Unzip the file to create the OJDL directory. The name of the OJDL directory is in the following format: ojdlpackage-versionNum.
The OJDL directory consists of the following subdirectories:

- doc: Contains the Java documentation (JavaDocs)

- lib: Contains the OJDL jar file that contains the Java classes

- samples: Contains code samples for testing purposes

Using the OJDL API

This section outlines the OJDL, including the Java classes provided for developers.

Java Development Environment

In order to develop Java code you need a suitable development environment, such as the Java Platform, Standard Edition (Java SE), which includes the Java Development Kit (JDK). You can download Java SE from the Oracle Technology Network Web site:

http://www.oracle.com/technetwork/java/javase/downloads/index.html

For information about the recommended JDK version for use with the OJDL, see IP Service Activator Installation Guide.

Java SE/JDK can be downloaded free of charge, and can be used for commercial or non-commercial purposes. However, you must retain the copyright notices.

This guide assumes the use of JDK, but other suitable Java tools can be used if required. You need to ensure they are configured correctly.

OJDL Directory and File Structure

When using the OJDL for developing Java code, you need the directories shown in Figure 2-3.

Figure 2-3 OJDL Directories

The doc Directory

The doc directory includes HTML files that contain class and package information. The index.html file lists all the classes and packages, and contains links to access the HTML files that provide the relevant information. The doc directory contains the following two subdirectories:

- doc\com\mslv\osa\ojdl\eom contains HTML files describing the EOM Java API classes.

- doc\com\mslv\osa\ojdl\Oim contains HTML files describing the OIM Java API subclasses (for the OIM IDL).

The lib Directory

The lib directory includes the ojdl.jar file, which contains a compressed version of all the OJDL Java classes. Figure 2-4 shows the internal directory structure of ojdl.jar.

Figure 2-4 Internal Directory Structure of ojdl.jar

Note:
You must put the ojdl.jar file in the class path.

The Samples Directory

The samples directory contains Java code samples, which provide an illustration of the use of the OJDL classes. The Java code samples are available in the following directory:

samples\com\oracle\communications\ipsa\ojdlSamples

For a brief explanation of the code samples, see the README.txt file in the ojdlSamples folder.

JavaDocs

The JavaDocs are stored in the doc directory. See "The doc Directory" for more information.

Java Classes

The OJDL Java classes provide access to the EOM objects. The classes can also be used to create Java beans which can then be used to create reusable user interface components for particular tasks. These may be written as Java applications, applets, or as scripts within a Java Server Page.

The OJDL Java classes are stored in the lib directory. See "The lib Directory" for more information.

The Java classes are documented as follows:

- Information about the classes is accessed through the doc\index.htm file.

- Details of methods and variables used are contained in the doc\index-all.htm file.

The main classes are summarized in Table 2-1. Refer to the JavaDocs for details.

Table 2-1 Main Java Classes

Class

Description

EomAttribute

A base class for representing an attribute within the EOM.

EomAttributesSe

Holds a set of EomAttribute objects.

EomConnectionManager

Defines a connection manager interface for connecting to the OIM.

EomDebug

Provides a way to enable traces.

EomDefaultConnection

The default implementation of EomConnectManager using the JDK ORB.

EomDifferenceResolver

Finds the logical difference of EomObjects contained in two iterators.

EomDiscovery

Enables the discovery of devices.

EomException

The base class for any exception thrown by the OJDL. May be thrown by methods interacting with the OIM.

EomExtendedSearchIterator

Extends the EomSearchIterator by searching on an iterator of EomObjects.

EomIntersectionResolver

Finds the logical intersection of EomObjects contained in two iterators.

EomIterator

An extension of the java.util.Iterator interface. Provides a wrapper around the search functionality of the OIM find command.

EomIteratorParameters

Provides a way to pass parameters to an EomSearchIterator to refine the search.

EomNonIntegerException

Thrown when a non-integer value is being assigned to an integer variable.

EomObject

A base class for representing objects within the EOM. Each object has an Id, name, and set of attributes.

EomObjectException

Thrown during an EomObject creation.

EomObjectFactory

A factory to build EomObjects.

EomOimException

Thrown when a command cannot be executed by OIM.

EomResolver

A base class for combining the results of two iterator sets.

EomSearchIterator

Looks for all objects of a specific type with a given attribute.

EomSession

Represents a connection to the OIM.

EomSessionException

Thrown by a method in EomSession when connected to the OIM.

EomTransaction

Models the general IP Service Activator transaction concept.

EomTransactionStateChange

A base class that allows IP Service Activator to synchronously return configuration success or failure messages through the OJDL for transactions which perform adds, modifies, or deletes.

Best Practices for Minimizing Commits

It is good to minimize the number of IP Service Activator transaction commits to complete an operation, because each commit introduces a delay when the object model is updated to reflect the new changes.

The following example shows how commits may be minimized when an application generates a large number of devices for testing. These devices are all of the same type and use the device capabilities of an existing device.

To link the desired capabilities, you must first unlink the default capabilities that are linked when the device is created. In the least efficient case, the client code would take three commits; device create, commit, setpath to device and unlink existing caps, commit, link new caps, commit.

In the more efficient form, the client code could accomplish this through one commit by constructing a reference to the default capabilities of the device by appending the following to the path of the device object:

/DeviceCapabilities:"DeviceCapabilities"

The following excerpt shows how to construct an EomIdentifier that references the capabilities linked to the device when the transaction is committed:

EomIdentifier idForNotYetLinkedDefaultCaps = new EomIdentifier("DeviceCapabilities", "DeviceCapabilities", newDevice.getPath() + "/" + "DeviceCapabilities" + ":\"DeviceCapabilities\"");

Then the default caps are unlinked and the appropriate device caps are linked using the following excerpt:

itsTransaction.unlinkObjects(newDevice, itsSession.createEomObject(idForNotYetLinkedDefaultCaps));
itsTransaction.linkObjects(newDevice, deviceCaps);
tr = eomSession.openTransaction();
tr.commit();

Very large transactions can take more time to process after you commit them. This must be balanced against the overall number of commits you issue.

Managing Configuration Policies Using the OJDL API

This section outlines how to use the OJDL API to manage Configuration Policies in Oracle Communications IP Service Activator.

Initial Setup

The following JAR files are required in the application classpath in order to create configuration policies using the OJDL API. They are installed with the Network Processor.

- servicemodelextensions.jar contains XML Bean Classes for the Configuration Policy Service Model Extensions.

- xbean.jar contains Apache XML Beans API.

- jsr173_api.jar contains streaming API for XML, provided as part of the Apache XML Beans API.

- ojdl.jar contains IP Service Activator OSS Java Development Library (OJDL) API.

These files are located in the following IP Service Activator installation directory:

- Solaris: /opt/OracleCommunications/ServiceActivator/lib/java-lib

If your development environment is on a separate machine you will have to copy the JAR files from an IP Service Activator machine.

Creating a Configuration Policy

Configuration policies are optional XML extensions to the IP Service Activator object model that are supported by the Network Processor cartridges.

A configuration policy can be created using the OJDL API by creating a RuleGeneric object. A RuleGeneric object must have two parent objects: a Policy Type object, and the object to which you want it to apply. The latter object can be an interface, or other applicable objects. For details, refer to the discussion of the RuleGeneric object and the external object model in IP Service Activator OSS Integration Manager Guide.

There are code examples available in the additional documentation included with the OJDL libraries. For more information, see the StaticNATsConfigurationPolicyExample file in samples\com\oracle\communications\ipsa\ojdlSamples. The Configuration Policy XML definition is set in the RuleGeneric ContentValue attribute.

The structure of the XML for each configuration policy is defined by an XML Schema specification in servicemodelextension-api-versionNum.buildNum.zip, which is installed with the IP Service Activator client in the Service_Activator_Home\SamplePolicy folder. An API is provided to programmatically construct the configuration policy XML data structures using Java XML Beans, using the Apache XML Beans technology available at the Apache web site:

http://xmlbeans.apache.org/

Creating the Configuration Policy Data Type

Each configuration policy top level XML element is represented by an XML Beans Document class. For example, the StaticNats configuration policy is created as a StaticNatsDocument object. Refer to "Configuration Policy Classes" for the complete configuration policy class mapping.

The content of the StaticNats object is set using the XML Beans API.

There are code examples available in the additional documentation included with the OJDL libraries. For more information, see the StaticNATsConfigurationPolicyExample file in the samples directory.

Creating the RuleGeneric Object to Contain the Configuration Policy

Configuration Policy objects are represented in the IP Service Activator External Object Model (EOM) as RuleGeneric objects. The following two attributes must be set:

- ContentType: the configuration policy type

- ContentValue: the configuration policy xml string

The ContentValue configuration policy XML is generated by invoking the toString() function.

There are code examples available in the additional documentation included with the OJDL libraries. For more information, see the StaticNATsConfigurationPolicyExample file in the samples directory.

When passing XML strings into the EOM object attributes, some special characters need to be escaped by pre-pending an additional \ character. For example, \" and \' must be fully escaped to \\\" and \\\' respectively. This conversion is performed by the escapeForOIM() function provided in the example.

Assigning the Configuration Policy to the Required Device and Interface Roles

The RuleGeneric object can be created as a child of many objects in the object hierarchy (as documented in IP Service Activator OSS Integration Manager Guide). However, the policy object Concrete is applied on any of the Interface objects in the inheritance hierarchy that match the RuleGeneric Roles. The RuleGeneric device and interface roles must match the device and interface roles on the interface where the configuration policy is applied.

There are code examples available in the additional documentation included with the OJDL libraries. For more information, see the StaticNATsConfigurationPolicyExample file in the samples directory.

Modifying a Configuration Policy

Modification of a configuration policy involves querying the object model for the current configuration policy definition, modifying the configuration policy, and updating the whole definition back into the object model.

Querying the EOM for the Configuration Policy

The configuration policy XML can be obtained from the RuleGeneric ContentValue parameter. The XML is parsed back into the XML Beans object definition of the service model extension.

There are code examples available in the additional documentation included with the OJDL libraries. For more information, see the StaticNATsConfigurationPolicyExample file in the samples directory.

As with creating the configuration policy, the XML content of RuleGeneric is updated to handle the extra escape characters around the \" and \' characters. This conversion is performed by the unescapeFromOIM() function.

Modifying the Policy Definition

The configuration policy definition is modified using the XML Bean API for the service model extension documents.

There are code examples available in the additional documentation included with the OJDL libraries. For more information, see the StaticNATsConfigurationPolicyExample file in the samples directory.

Registering an Interface Policy

Creating a new interface in IP Service Activator through the OIM and OJDL APIs involves a specialized use of configuration policies with the interface configuration management framework. As with interface management through IP Service Activator, there are three types of interface management interactions:

- Main interface creation

- Subinterface creation

- Interface decoration

Each possible interaction must be registered as an Interface Policy Registration. The Interface Policy Registration objects can either be pre-configured in IP Service Activator, or created using the IP Service Activator APIs.

There are code examples available in the additional documentation included with the OJDL libraries. For more information, see the nterfaceManagementPolicyExample file in the samples directory.

Once an Interface Policy Registration is used to create or decorate an interface it cannot be modified or deleted until all dependent parent interfaces have been deleted or unlinked from the policy registration.

Creating a Subinterface

This section describes how to create a new interface in IP Service Activator so that the new interface configuration will also be correctly provisioned on the device.

As a prerequisite the appropriate subinterface creation Interface Policy Registration must be created.

Creating the Subinterface Object

Create a new subinterface object under the target interface. For consistency, it is recommended that you create the child subinterface with the correct ifType, although IP Service Activator will update this value on the next device discovery.

Create a new subinterface object under the target interface. For consistency, it is recommended that you create the child subinterface with the correct ifType, although IP Service Activator will update this value on the next device discovery.

The following example shows the creation of a new subinterface:

// Create the new subinterface interface object
String subinterfaceName = "Serial1/3.100";
attributes = new EomAttributesSet();
attributes.setAttribute("Type", "32");
EomObject subinterface = tr.createObject(parentInterface, "Subinterface",
subinterfaceName, attributes);

Linking the New Subinterface Object to the Interface Policy Registration

The created subinterface object is linked to the previously defined Interface Policy Registration. The act of linking the policy registration automatically creates a new RuleGeneric configuration policy object with the correct data type settings based on the Interface Policy Registration definition.

The following example shows the linking of the subinterface object with the interface policy registration:

// Link the new subinterface object to the interface policy registration
tr.linkObjects(subinterface, registrationPolicy);
tr.commit();

The new RuleGeneric object name consists of the interface names with -Data appended to it.

Modifying the Interface Configuration Policy Data

The interface management configuration policy does not contain any default settings. These must be manually created using the appropriate XML data structure for the configuration policy data type defined in the interface registration policy. The XML content can be created manually or using the XML Beans API provided.

There are code examples available in the additional documentation included with the OJDL libraries. For more information, see the InterfaceManagementPolicyExample file in the samples directory.

Linking the New Subinterface to an Interface Role

Up to this point the new subinterface has only been created in the IP Service Activator object model. Before committing the subinterface creation to the device, the new subinterface object must be linked to an appropriate interface role.

There are code examples available in the additional documentation included with the OJDL libraries. For more information, see the InterfaceManagementPolicyExample file in the samples directory.

(Optional) Discovering the Device

Optionally, the device can be re-discovered to align any interface changes (such as to the ifType or VC objects) with the object model. For interface types that have child VC object created by the configuration (such as the framerelay DLCI) device re-discovery is recommended.

The following example shows the optional device discovery:

// Optionally rediscover the device the get any VC level objects (in this example
// the DLCI)
eomSession.sendCommandtoOIM("discover " + parentDeviceId);

Creating a Main Interface

The steps for main interface creation are largely the same as for subinterface creation. For a main interface, the new interface is created as a child of the device and is linked to an appropriate Interface type Interface Policy Registration object.

When creating a main interface, the Interface Policy Registration must define the default capabilities that the interface (and its sub-interfaces and VCs) will be assigned. If the default settings are used, the created interface will not have any capabilities assigned and a capabilities reset and re-discovery must be performed instead.

Decorating an Interface

For interface decoration, follow the same steps as with subinterface creation, with the exception that the interface does not need to be created first. For interface decoration, the existing interface must be linked to a Decorate type Interface Policy Registration object.

Comparing Created and Discovered Interfaces

It is possible to determine if an interface was created using the IP Service Activator interface configuration management framework or was initially discovered from the device by inspecting the IsConfigurable parameter on the Interface or SubInterface object.

If IsConfigurable is set to True then the interface was created within IP Service Activator. If it is set to False then the interface was added through discovery.

Configuration Policy Classes

Table 2-2 lists the configuration policy classes.

Table 2-2 Configuration Policy Classes

Extension

Configuration Policy

Java XMLBeans Class

AtmPvcVcClassModule

atmPvcVcClass

com.metasolv.serviceactivator.atmpvcvcclass.AtmPvcVcClassDocument

CatOSPolicingRuleModule

catOSPolicingRule

com.metasolv.serviceactivator.catospolicingrule.CatOSPolicingRuleDocument

CiscoEthernetPortCharacteristicsModule

ciscoEthernetPortCharacteristics

com.metasolv.serviceactivator.ciscoEthernetPortCharacteristics.CiscoEthernetPortCharacteristicsDocument

CiscoQosPfcTxPortQueuesModule

ciscoQosPfcTxPortQueues

com.metasolv.serviceactivator.ciscoqospfctxportqueues.CiscoQosPfcTxPortQueuesDocument

DlswModule

dlswDevice

com.metasolv.serviceactivator.dlsw.DlswDeviceDocument

DlswModule

dlswEthernetInterface

com.metasolv.serviceactivator.dlsw.DlswEthernetInterfaceDocument

DlswModule

dlswTokenRingInterface

com.metasolv.serviceactivator.dlsw.DlswTokenRingInterfaceDocument

InterfaceConfigMgmtModule

atmSubInterfaceData

com.metasolv.serviceactivator.subinterface.AtmSubInterfaceDataDocument

InterfaceConfigMgmtModule

backUpInterfacePolicy

com.metasolv.serviceactivator.subinterface.BackUpInterfacePolicyDocument

InterfaceConfigMgmtModule

basicRateInterfaceData

com.metasolv.serviceactivator.subinterface.BasicRateInterfaceDataDocument

InterfaceConfigMgmtModule

ciscoUniversalInterface

com.metasolv.serviceactivator.subinterface.CiscoUniversalInterfaceDocument

InterfaceConfigMgmtModule

dialerInterface

com.metasolv.serviceactivator.subinterface.DialerInterfaceDocument

InterfaceConfigMgmtModule

e1ChannelizedSerialInterface

com.metasolv.serviceactivator.subinterface.E1ChannelizedSerialInterfaceDocument

InterfaceConfigMgmtModule

e1Controller

com.metasolv.serviceactivator.controller.E1ControllerDocument

InterfaceConfigMgmtModule

e3ChannelizedSerialInterface

com.metasolv.serviceactivator.subinterface.E3ChannelizedSerialInterfaceDocument

InterfaceConfigMgmtModule

e3Controller

com.metasolv.serviceactivator.controller.E3ControllerDocument

InterfaceConfigMgmtModule

frSubInterfaceData

com.metasolv.serviceactivator.subinterface.FrSubInterfaceDataDocument

InterfaceConfigMgmtModule

hsrp

com.metasolv.serviceactivator.hsrp.HsrpDocument

InterfaceConfigMgmtModule

loopbackInterfaceData

com.metasolv.serviceactivator.subinterface.LoopbackInterfaceDataDocument

InterfaceConfigMgmtModule

multilinkInterface

com.metasolv.serviceactivator.subinterface.MultilinkInterfaceDocument

InterfaceConfigMgmtModule

plPosInterfaceData

com.metasolv.serviceactivator.subinterface.PlPosInterfaceDataDocument

InterfaceConfigMgmtModule

pppMultilink

com.metasolv.serviceactivator.subinterface.PppMultilinkDocument

InterfaceConfigMgmtModule

stm1ChannelizedSerialInterface

com.metasolv.serviceactivator.subinterface.Stm1ChannelizedSerialInterfaceDocument

InterfaceConfigMgmtModule

stm1Controller

com.metasolv.serviceactivator.controller.Stm1ControllerDocument

InterfaceConfigMgmtModule

t1ChannelizedSerialInterface

com.metasolv.serviceactivator.subinterface.T1ChannelizedSerialInterfaceDocument

InterfaceConfigMgmtModule

t1Controller

com.metasolv.serviceactivator.controller.T1ControllerDocument

InterfaceConfigMgmtModule

t3ChannelizedSerialInterface

com.metasolv.serviceactivator.subinterface.T3ChannelizedSerialInterfaceDocument

InterfaceConfigMgmtModule

t3Controller

com.metasolv.serviceactivator.controller.T3ControllerDocument

InterfaceConfigMgmtModule

virtualTemplateInterface

com.metasolv.serviceactivator.subinterface.VirtualTemplateInterfaceDocument

InterfaceConfigMgmtModule

vlanSubInterface

com.metasolv.serviceactivator.subinterface.VlanSubInterfaceDataDocument

InterfaceConfigMgmtModule

vrfExportRouteFilter

com.metasolv.serviceactivator.vrfexportroutefilter.VrfExportRouteFilterDocument

IpsecModule

IPsecModule

com.metasolv.serviceactivator.ipsecmodule.IpsecmoduleDocument

LspModule

lspTunnel

com.metasolv.serviceactivator.lsp.LspTunnelDocument

L2QosModule

rateLimit

com.metasolv.serviceactivator.l2Qos.RateLimitDocument

JuniperQosCosAttachmentModule

juniperQosCosAttachment

com.metasolv.serviceactivator.juniperqoscosattachment.JuniperQosCosAttachmentDocument

MiscPluginsModule

atmVcClass

com.metasolv.serviceactivator.vcclass.AtmVcClassDocument

MiscPluginsModule

banners

com.metasolv.serviceactivator.banner.BannersDocument

MiscPluginsModule

bgpCE

com.metasolv.serviceactivator.bgpce.BgpCEDocument

MiscPluginsModule

dailerList

com.metasolv.serviceactivator.dialerList.DialerListDocument

MiscPluginsModule

dslInterfaceData

com.metasolv.serviceactivator.subinterface.DslInterfaceDataDocument

MiscPluginsModule

extendedAcl

com.metasolv.serviceactivator.extendedAcl.ExtendedAclDocument

MiscPluginsModule

ipPools

com.metasolv.serviceactivator.ippool.IpPoolsDocument

MiscPluginsModule

keyChains

com.metasolv.serviceactivator.keyChain.KeyChainsDocument

MiscPluginsModule

saveConfig

com.metasolv.serviceactivator.saveConfig.SaveConfigDocument

MiscPluginsModule

staticNats

com.metasolv.serviceactivator.staticnat.StaticNatsDocument

MiscPluginsModule

staticRoutes

com.metasolv.serviceactivator.staticroute.StaticRoutesDocument

MiscPluginsModule

userAuth

com.metasolv.serviceactivator.userAuth.UserAuthDocument

MiscPluginsModule

userData

com.metasolv.serviceactivator.userData.UserDataDocument

MulticastModule

multicastAutoRp

com.metasolv.serviceactivator.multicast.MulticastAutoRpDocument

MulticastModule

multicastBootstrapRouter

com.metasolv.serviceactivator.multicast.MulticastBootstrapRouterDocument

MulticastModule

multicastDevice

com.metasolv.serviceactivator.multicast.MulticastDeviceDocument

MulticastModule

multicastInterface

com.metasolv.serviceactivator.multicast.MulticastInterfaceDocument

MulticastModule

multicastVrf

com.metasolv.serviceactivator.multicast.MulticastVrfDocument

PrefixListModule

prefixListEntries

com.metasolv.serviceactivator.prefixlist.PrefixListEntriesDocument

QosCosAttachmentModule

qosCosAttachment

com.metasolv.serviceactivator.qoscosattachment.QosCosAttachmentDocument

RoutePolicyModule

bgpRoutePolicy

com.metasolv.serviceactivator.routePolicy.BgpRoutePolicyDocument

RoutePolicyModule

vrfRoutePolicy

com.metasolv.serviceactivator.routePolicy.VrfRoutePolicyDocument

SubInterfaceModule

plSerialInterfaceData

com.metasolv.serviceactivator.subinterface.PlSerialInterfaceDataDocument

ServiceAssuranceModule

collectorParameters

com.metasolv.serviceactivator.collectorParameters.CollectorParametersDocument

ServiceAssuranceModule

netflowParameters

com.metasolv.serviceactivator.netflowParameters.NetflowParametersDocument

ServiceAssuranceModule

rtrResponder

com.metasolv.serviceactivator.rtrr.RtrResponderDocument

SgbpModule

sgbp

com.metasolv.serviceactivator.sgbp.SgbpDocument

SnmpModule

snmpCommunities

com.metasolv.serviceactivator.snmp.SnmpCommunitiesDocument

SnmpModule

snmpHosts

com.metasolv.serviceactivator.snmp.SnmpHostsDocument

VlanModule

vlanDefinitions

com.metasolv.serviceactivator.vlanModule.VlanDefinitionsDocument

VlanInterfaceModule

mgmtVlanInterface

com.metasolv.serviceactivator.vlanInterface.MgmtVlanInterfaceDocument

VlanInterfaceModule

vlanInterface

com.metasolv.serviceactivator.vlanInterface.VlanInterfaceDocument

VrfCustomNamingModule

vrfCustomNaming

com.metasolv.serviceactivator.vrfCustomNaming.VrfCustomNamingDocument

VrfIPsecModule

customerIPsec

com.metasolv.serviceactivator.vrfipsec.CustomerIPsecDocument

VrfIPsecModule

publicIPsec

com.metasolv.serviceactivator.vrfipsec.PublicIPsecDocument

Example Source Code

Code examples are available in the additional documentation included with the OJDL libraries.

For configuration policy example source code, see the StaticNATsConfigurationPolicyExample file in the samples directory.

For interface management example source code, see the InterfaceManagementPolicyExample file in the samples directory.

3 Working with the Programmatic Intent-Based Network REST API

This chapter describes the Oracle Communications IP Service Activator programmatic intent-based network Representational State Transfer (REST) API. You can use the REST API to provision customer-defined services and to integrate IP Service Activator with Oracle Communications Order and Service Management (OSM).

About the REST API

You can use REST constraints to create a software architecture style that is based on resources. A resource is an object with a type, associated data, relationships to other resources, and a set of methods that operate on it. It is similar to an object in an object-oriented programming language; however, only a few standard methods are defined for a resource, while an object typically has many methods.

In the REST-based architecture, you access resources by using a common interface that is based on HTTP standard. A REST server manages and provides access to the resources, and a REST client accesses and modifies the resources through the common API. The common API is called the REST API and the services that support the API are called the REST web service.

The REST API includes an API Software Development Kit (SDK) that enables you to define API calls with a high level of granularity, which simplifies the logic that is required to provision complex services. The REST API uses the Groovy scripting language to create high-level API functions. See "Working with the Groovy Scripting Language" for more information.

The REST API uses Secure Sockets Layer (SSL) so all the connections are secure and encrypted. See "Setting Up WebLogic Server Security" for more information.

About REST API Methods

Every resource supports some or all of the HTTP common methods. A resource is identified by a global ID that is typically a URI. A resource can be in a variety of formats, such as XML, JavaScript Object Notation (JSON), plain text, HTML, and user-defined data format. A REST client application can require a specific representation format by using the HTTP/HTTPS protocol content negotiation.

The common REST API methods are the following:

- GET: Retrieves one or more resources. You can use this method to check the state of a resource.

- PUT: Updates a resource. The PUT method updates the full definition of a resource, regardless of what has changed.

- DELETE: Removes one or more resources.

- POST: Creates a new resource.

- PATCH: Updates only the parts of a resource definition that have changed.

A common flow includes using a method to perform an action on a resource, and then using the GET method to check the state of that action. For example, you can create a resource using the POST method (which includes a URI that points to the new resource), and then, because it might take a long time for that resource to be applied to the network, use the GET method to periodically check the state of the new resource. See "About Polling Using the GET Method" for more information.

About Installing the REST API

If you want to use the REST API with IP Service Activator, you can select the Web Service optional integration component when you run the Oracle Universal Installer. Alternatively, if you are running a silent installation, you can use the Web Service response file to install IP Service Activator with REST API capability. For more information about hardware requirements, selecting the Web Service component, and using the Web Service response file, see IP Service Activator Installation Guide.

Installing IP Service Activator with the Web Service component allows you to use the REST web service. If the Web Service component was installed on a previous version of IP Service Activator, upgrading to the latest version and then redeploying the web service gives you access to the REST API.

To use a REST web service, you must set up Secure Sockets Layer (SSL) in WebLogic Server. See "Setting Up WebLogic Server Security" for more information.

Setting Up WebLogic Server Security

To use the REST API web service you must have an Oracle WebLogic Server installed and configured with SSL. For more information about installing and using WebLogic Server, see WebLogic Server product documentation.

Configuring Identity and Trust Keystores in WebLogic Server

To configure the WebLogic Server to use SSL, you must have an SSL certificate for the server that is running WebLogic. Production servers should have a trusted certificate. Lab and testing servers can use self-signed certificates. Use java to generate custom keystore files and then configure WebLogic Server to use those files.

To configure the WebLogic Server to use custom identity and trust keystore files:

1. Generate custom SSL identity and trust files by entering the following in the Java utility:

keytool -genkey -alias mykey -keyalg RSA -keysize 1024
-sigalg SHA256withRSA -validity 128 -keypass 123456 -keystore identity.jks -storepass 123456
keytool -export -alias mykey -file root.cer
-keystore identity.jks -storepass 123456
keytool -import -alias mykey -file root.cer -keystore trust.jks
-storepass 123456

where mykey is the key name, and 123456 is the key password.

The system generates the following two files:

- identity.jks

- trust.jks

2. Copy the .jks files to the security directory of the WebLogic Server, for example, OracleHome/user_projects/domains/domain_name/security.

3. Log in to the WebLogic Server.
The WebLogic Administration Console is displayed.

4. In the left pane, expand Environment, and select Servers.

5. Select the server where you want to configure the identity and trust keystores.

6. Select Configuration, Keystores.

7. Select the Custom Identity and Custom Trust option, and specify the identity.jks and trust.jks files that you generated in step 1.

Note:
The key name must match the key password that you entered when you generated the files.

Testing the SSL Configuration

You can test whether SSL is set up correctly in the WebLogic Server.

To test the SSL configuration:

1. In a browser, go to the WebLogic Administration Console, for example, enter:
http://hostname:7001/console

If SSL is configured correctly, the browser connects to the WebLogic Administration Console using a secure connection and the URL changes from http:// to https://, for example:

https://hostname:7002/console

The default port number for SSL is 7002 and if your browser connects, SSL is configured correctly.

Note:
If you are using a self-signed certificate for authentication, the browser might need to import the certificate before you make the connection.

Security and Authentication

The web service supports only secure connections with authentication.

When you deploy the REST web service, the system creates and configures a WebLogic group called IpsaDomainController. The REST web service user, which is called ipsa_ws_user by default, is configured in the Web Service/Common section of the IP Service Activator Configuration graphical user interface (GUI). This web service user is automatically added to the IpsaDomainController group. See "Deploying and Undeploying Web Services" for information about deploying the web service for use with the REST API.

The REST web service is configured to accept calls only from a user that belongs to the IpsaDomainController group, as authenticated by WebLogic Server, or is a specific user with the name IpsaDomainController.

You can configure additional users and add them to this group using the WebLogic Administration Console. For information about managing users in the WebLogic Administration Console, see WebLogic Server documentation.

Working with the Groovy Scripting Language

Groovy script is a general-purpose scripting language that runs on the Java Virtual Machine (JVM). The syntax that is used for Groovy scripts is similar to the syntax for Java code. Most Java code is also valid Groovy script.

REST resources are mapped to Groovy scripts using a registry. Each REST call is done to a specific resource. Oracle recommends that you map each combination of REST method and resource to a single script.

For example, a REST request to activate an Ethernet service could be done using a REST PUT method to a resource called SCA_ETH_FDFr_EC. In this example, the URI that is called using the REST service would be the following:

https://hostname:7002/Oracle/CGBU/IPSA/DomainController/resources/data/SCA_ETH_FDFr_EC.

The first part of the URI references the server with the web service, that is: https://hostname:7002. The next part references the IP Service Activator web service API, that is: Oracle/CGBU/IPSA/DomainController/resources/data. The last part references the resource, and can also contain a hierarchy, for example, Ethernet/SCA_ETH_FDFr_EC. The corresponding Groovy registry entry is like the following example:

<groovyScript>
<name>groovy/Post_SCA_ETH_FDFr_EC.groovy</name>
<target>SCA_ETH_FDFr_EC</target>
<operation>POST</operation>
</groovyScript>

The registry entry has the following components:

- Name: The name of the Groovy script that you want to run. In the example, the Groovy script is contained in a directory.

- Operation: The REST methods that are supported by the script. You can include multiple method entries. See "About REST API Methods" for supported methods and their definitions.

- Target: The resource supported by the script. This can be a single resource (for example, EthernetConnection), or a hierarchy with a resource (for example, Services/Ethernet/EthernetConnection).

The registry is loaded from the following directory: Service_Activator_home/DomainController/groovy.registry

A sample Groovy registry and Groovy scripts are provided in the Service_Activator_home/ServiceActivator/DomainController/sample directory. You can copy the registry and scripts directly into the Service_Activator_home/ServiceActivator/DomainController directory for testing. Sample JSON input is also provided in corresponding .txt files.

Note:
When using sample Groovy scripts, you must change the input to match the specific devices and interfaces that are configured in IP Service Activator.

Developing Custom Groovy Scripts

You run Groovy scripts to process REST requests. Each script is run with certain input and output available, and an API is provided for interacting with IP Service Activator.

Table 3-1 lists and describes the variables that are available for creating custom Groovy scripts.

Table 3-1 Variables for Creating Custom Groovy Scripts

Variable

Description

json

The input JSON format payload, converted to a map representation. If no JSON payload is provided (for example, with a GET method), this variable is an empty map.

output

An ArrayList of strings. These are the OIM commands that the script will generate. They are processed as a single transaction after the Groovy script returns its results.

For information about commands and their formats, see IP Service Activator OSS Integration Manager Guide.

returnedJson

Map of the output JSON resource that will be returned. This gets converted from a map back into JSON when it is returned to the caller.

uriArray

An array of the elements of the URI. This is useful when you are specifying a hierarchy in the registry with multiple resources mapping to the same script. This allows the script to see what resource and hierarchy it is called with.

queryMap

Map of any query parameters passed on the request. For example, a GET request might specify:

https://.../Layer3Ethernet?Customer=MyCustomer

The parts after the '?' will be parsed into the queryMap.

transactionNameArray

An array of strings that are used when constructing the name of the transaction.

helper

The API that is provided for assistance. This API has its own javadocs, but is provided for doing IP Service Activator operations (for example, looking up resources or attributes) and constructing some OIM commands automatically without needing to explicitly create and add them to the output variable.

return

This is not a variable, but is the return code from the script. It is returned as the status of the REST call. If the status is not successfully, for example it is 400 or greater, any IP Service Activator operations are not performed. If the script returns successfully, the REST call might still receive an error if the methods are invalid or if IP Service Activator does not accept the transaction.

Groovy Script Examples

The examples in this section are intended to give further guidance about using the sample Groovy scripts that are provided with IP Service Activator.

Example: Generating CTM Commands

This example implements a REST-based mechanism for generating CTM commands. The sample Groovy script is available in the following location: Service_Activator_home/DomainController/sample/groovy/Post_CTM.groovy.

Note:
Oracle recommends using the POST method to implement this script because generating these commands is similar to the commands for creating a resource, even though this example does not create resources.

Step 1: Configuring JSON

Using JSON format, you must first design the input/output of the service that you want to implement. The input must indicate the template that you want to use (name, versions, driver type, and so on), as well as a list of attributes (name/value pairs).

The input is the following:

{
"templateName":"String",
"deviceRoll":"String",
"interfaceRoll":"String",
"schemaRelease":"Number",
"templateVersion":"Number",
"driverType":"String",
"objectType":"String",
"interfaceType":"String",
"templateVariables": {
"Name1":"Value1",
"Name2":"Value2",
…
}
}

In this example, the template name is mandatory and all other template information is optional. You can use wildcards in the CTM call for non-mandatory template information. The structure of the templateVariables attribute contains a list of the variables that are part of the template. The list of variables depends on the type of template that you are using. The Groovy script does not enforce the variables in the list; however, CTM generates an error if the variables are incorrect for the template.

The output is the following simple JSON with an array of strings that contain the generated commands:

{
"Commands": [
"StringCommand1",
"StringCommand2",
…
"StringCommandN"
]
}

Step 2: Developing the Groovy Script

This section of the example shows the Groovy script that you can develop to accomplish the task of implementing a REST-based mechanism for generating CTM commands.

You can use the helper API to check for the mandatory parts of the incoming JSON code. Create a map that contains the parts of the JSON code that are mandatory, in this example that is the templateName and templateVariables. Note that this example does not check for specific variable names in the templateVariables because these can change based on the specific template.

The input JSON is located in the variable json, which is included in the call to isJsonValid, as in the following:

def expectedJson = [ templateName:"",
templateVariables:""
]
if (!helper.isJsonValid(expectedJson, json)) {
returnedJson.BadRequestErrorType = [ "title":"Exception",
"detail":'Invalid ctm input json']
logger.log(Level.SEVERE, "Input is missing required ctm fields")
return 400;
}

The next part of this step is to put the variables into a hashtable so that they can be passed to CTM when generating the template. Groovy provides a way to iterate over the items in the JSON format map, and allows you to add each key/value pair to the new hashtable. Using validation, you can ensure that all the types are strings, in case an incorrect structure was accidentally passed into this part of the JSON. Even numeric fields are strings because JSON format does not differentiate numbers from strings. For example:

def Hashtable<String, String> fieldMap = new Hashtable<String, String>()
json.templateVariables.each { key, value ->
if (value.getClass() == String) {
fieldMap.put(key, value)
}
}

You create Groovy variables that store the values that are needed to specify the template. In this way, you can also check when a value is not specified and then set it to null. Null is used by the CTM call to indicate that the value should not be used when searching for the template and acts as a wildcard. The template name is also stored in a variable for convenience. For example:

def templateName = json.templateName
def deviceRoll = null
if (json.containsKey("deviceRoll")) {
deviceRoll = json.deviceRoll
}

def interfaceRoll = null
if (json.containsKey("interfaceRoll")) {
interfaceRoll = json.interfaceRoll
}

def schemaRelease = null
if (json.containsKey("schemaRelease")) {
schemaRelease = Integer.valueOf(json.schemaRelease)
}
templateVersion = null
if (json.containsKey("templateVersion")) {
templateVersion = json.templateVersion
}

def driverType = null
if (json.containsKey("driverType")) {
driverType = json.driverType
}

def objectType = null
if (json.containsKey("objectType")) {
objectType = json.objectType
}

def interfaceType = null
if (json.containsKey("interfaceType")) {
interfaceType = json.interfaceType
}

All the data that is required for generating the commands from the template is now prepared, and you can call the CTM method using the helper API. This returns a vector containing the string commands:

def Vector<String> cmds = helper.generateCtmCommands(templateName, deviceRoll, interfaceRoll, schemaRelease, templateVersion, driverType, objectType, interfaceType, fieldMap)

If there is an error and the commands could not be generated, the helper API returns null. If this occurs, you can construct a different JSON output that indicates the failure. Use the variable returnedJson to construct the JSON map that gets sent back. In this example, the JSON has two elements, a "title" and "detail." It also returns a status 400, which indicates a "Bad Request," because something was wrong with the data that prevented the commands from being generated. This return code is passed back to the calling system.

if (cmds == null)
{
returnedJson.BadRequestErrorType = [ "title":"Exception",
"detail":'Error generating template']
return 400
}

If the command vector is successfully generated, you can put the vector into the Commands element of the returned JSON. The vector maps to an array in the JSON and then returns the status of 200 to indicate that it was successful.

returnedJson.Commands = cmds

return 200

The result is that the registry is edited with the following entry added for this service:

<groovyScript>
<name>groovy/Post_CTM.groovy</name>
<target>CTM</target>
<operation>POST</operation>
</groovyScript>

Example: Deleting a Layer 2 Ethernet Service

This example is for deleting a layer 2 service by using the sample that is in the following location: Service_Activator_home/DomainController/sample/groovy/ Post_SCA_ETH_FDFr_EC.groovy. This example uses Groovy functions.

The first Groovy function is used to substitute all ':' characters in a string with '_' and return the result, as in the following:

def String sanitizeIdentifier(String source)
{
if (source == null)
return null
return source.replaceAll(':', '_')
}

One of the results of creating this service is that subinterfaces that do not already exist might be created. This method searches for all the subinterfaces under the customer. Subinterfaces are IP Service Activator objects. For information about finding and retrieving IP Service Activator objects, see IP Service Activator OSS Integration Manager Guide.

The following Groovy script searches all the subinterfaces and uses the helper API to find a generic rule with a specific name that matches the one used in the creation of the subinterface. For information about the RuleGeneric object type, see IP Service Activator OSS Integration Manager Guide. If the script locates a subinterface, it adds the delete command with the object ID to the variable output. This output is what gets processed when the script returns and performs operations on the OIM.

def void deleteGeneratedInterfaces(customerPath)
{
// First, find all the subs
subs = helper.findObjects("Subinterface", customerPath, [:])
for (Map sub : subs)
{
// Now look for the subinterface creation policy underneath each
subifCreation = helper.findObjectPath("RuleGeneric",
sub.id,
["name":sub.name + "-Data"])
if (subifCreation != null && !subifCreation.isEmpty())
{
output.add("delete [" + sub.id + "]")
}
}
}

This is a delete method, so there is no JSON output. Instead, the parameters that are used to specify the instance that you want to delete are provided as part of the URI. For example:

https://hostname:7002/Oracle/CGBU/IPSA/DomainController/resources/data/SCA_ETH_FDFr_EC?evcCfgIdentifier=EVC_BOA_001_1_BOA_002

A "?" separates the resource (SCA_ETH_FDFr_EC) from the parameters. In this example, you must specify a parameter called evcCfgIdentifier, which identifies the specific instance of the resource that is to be deleted. Not specifying this parameter results in the following error:

if (queryMap.evcCfgIdentifier == null)
{
returnedJson.BadRequestErrorType = [ "title":"Exception",
"detail":"No evcCfgIdentifier specified on delete operation" ]
return 400
}

Begin deleting the service by using the evcCfgIdentifier parameter in the queryMap. This is a map that is provided with all the query parameters. You can do this using a loop that will support multiple evcEvcIdentifier parameters using a single URI.

Run the character conversion function on each identifier (which is also done on create), to get an ID without ':' characters. Then you can search for the customer that matches that ID. If there is no result, you can assume it is already removed and ignore the ID. In this way, if there is a duplicate or resent request, the system does not generate an error (idempotent).

If you find the customer, you can add a delete method to the output to delete the customer. Doing this also deletes everything contained within that customer (for example, sites, VPNs, and so on). At this point, the customer has not yet been deleted, but the delete command has been added to the output array.

Now you can call the method to remove any generated subinterfaces.

Note:
The commands put in the output are buffered and not executed in real time. They are processed only when the script completes, which makes it safe for the method deleteGeneratedInterfaces to search on the customer, even though the previous line adds the command to delete the customer to the output. It would not be safe for this method to reference the customer object in anything it added to the output buffer.

{
def String deleteId=sanitizeIdentifier(id)
String customerPath = helper.findObjectPath("Customer", "/",
["name":"CE_" + deleteId])
if (customerPath != null) {
// Start by removing any created interfaces
output.add("delete " + customerPath)
deleteGeneratedInterfaces(customerPath)
}
}

Next, you return a success code 202, accepted for processing. The processing of the output happens in the background after this returns.

return 202 // Accepted for processing, not completed

Finally, you must add an entry to the Groovy registry for this script, for example:

<groovyScript>
<name>groovy/Delete_SCA_ETH_FDFr_EC.groovy</name>
<target>SCA_ETH_FDFr_EC</target>
<operation>DELETE</operation>
</groovyScript>

About Transactions

If REST methods are intended to modify the system, the system creates transactions. REST methods such as POST, PUT, PATCH, and DELETE can modify the system. If there are no commands in the output map, the system does not need to be modified and no transaction is created. See IP Service Activator Concepts for information about transactions.

Add the commands in the output map to a single transaction, which ensures that the transaction has been successfully submitted into IP Service Activator before the REST response is sent. The transaction could still fail and have configuration that could not be applied. Further GET methods should be performed when the status of the changes is required.

About Polling Using the GET Method

The REST protocol does not automatically poll resources. If you want to know when the state of a resource has changed, you must poll manually. Use the GET method to retrieve the current state of the resource.

It is important to plan your strategy for using the GET method to poll a resource for a state change (for example, when creating a resource). Running the GET method too frequently can negatively affect system performance, whereas running the GET method too infrequently means the system might not be responsive enough.

Determine the polling strategy by considering how long it takes for the service to typically be applied to the network and routers. For example, if the sample Ethernet service takes a minimum of 20 minutes to apply to the network (with slow routers and low bandwidth), it would not be useful to poll for the status every 20 seconds. In this case, polling in 5-minute intervals is more acceptable, although the polling interval also depends on the calling system's latency requirements.

About Logging

You can configure logging using the WebLogic Administration Console and the IP Service Activator Configuration GUI. You can configure logging for the REST web service by using Groovy scripts and the Java logging utilities.

Logging Using WebLogic Server Configuration

You can configure and manage logging by using WebLogic Server. You set logging levels in WebLogic for the server that is running the REST web service.

By default, the system logs errors at the ERROR level. When you are troubleshooting REST web service errors, you can change the logging to report DEBUG logs. If you change the logging option, you might have to restart the WebLogic server for changes to take effect.

For more information about setting up logging in WebLogic Server, see WebLogic Server documentation.

Configuring EOM Logging Using the IP Service Activator Configuration GUI

Configuring EOM logging by using the IP Service Activator Configuration GUI provides logging information only about the connection between the REST web service and IP Service Activator. See "Configuring Web Services" for information about setting log levels in the configuration GUI.

If you change this configuration, you must redeploy the REST web service for the change to take effect.

See IP Service Activator System Administrator's Guide for information about using configuration GUI log files.

Configuring Additional Logging Using Groovy Scripts

You can use Groovy scripts to configure additional logging on the REST web service by using the Java logging framework. This log output is included in the set of logs that is managed by WebLogic Server. See "Working with the Groovy Scripting Language" for more information.

Add logging to a Groovy script by importing the Java logging utilities at the beginning of the script, as in the following:

import java.util.logging.Level
import java.util.logging.Logger

def Logger logger = Logger.getLogger("MyClassOrFileName")

You can then use the logger within the Groovy script, for example:

logger.log(Level.SEVERE, "Error msg")

4 Working with the Web Service API

This chapter describes the Oracle Communications IP Service Activator web service API, which can be used to integrate IP Service Activator with Oracle Communications Order and Service Management (OSM).

About the Web Service API

IP Service Activator provides a web service interface through which OSM can manage service activation transactions. For more information about OSM, see OSM Concepts.

Web services for IP Service Activator is an optional component that is available during IP Service Activator installation. For information about installing and configuring web services, see IP Service Activator Installation Guide.

Web services is deployed on WebLogic Server. For information about WebLogic Server, see WebLogic Server documentation.

The web service is an OSS/J-based interface that provides an external API for system integration. IP Service Activator transactions can be managed by the web service. Each IP Service Activator request that is sent to the web service contains a list of commands. These commands are then performed using a single transaction, without the need to specify the beginning and ending of the transaction. The web service monitors these transactions and provides status notifications based on the result.

The external transport protocols for using web services are HTTP, HTTPS, and JMS, and the data service formats are SOAP v1.1 and 1.2. Access-level security is provided through the implementation of the WebLogic WS-Policy specification, which enforces authentication. See "About OSM Data Providers" for more information about using SOAP as the data provider.

About Web Services and OIM

The IP Service Activator web service supports the use of multiple OSS Integration Manager (OIM) instances connected to a single instance of IP Service Activator. Use multiple OIM instances to improve performance by allowing operations to be directed to OIMs on the basis of operation type, and also to allow for load sharing.

You can configure web services to use previously configured OIMs using the web services Configuration graphical user interface (GUI). For information about configuring web services as a post-installation task, see IP Service Activator Installation Guide. For information about the Configuration GUI, see IP Service Activator System Administrator's Guide.

Design Studio for IP Service Activator

An IP Service Activator activation cartridge is provided with the installation. This cartridge includes service action definitions that map to all IP Service Activator operations that are supported by the IP Service Activator web services API.

Activation tasks within Design Studio provide integration between OSM and IP Service Activator. You must install OSM, IP Service Activator, and the IP Service Activator integration cartridge in Design Studio.

For information about working with activation tasks, see Design Studio online Help.

Configuring Web Services

The web service is an optional component for an IP Service Activator installation. If you selected the Web Services component during installation, or if you selected the option to install all components, the web service is available. If correctly installed, the IP Service Activator Configuration GUI shows the Web Service folder in the tree view. You can install web services on the same server with other IP Service Activator components, or you can install it as a standalone component. See IP Service Activator Installation Guide for more information.

Use the IP Service Activator Configuration GUI to configure the web service and deployment parameters, and then deploy the web service.

Note:
The database and CORBA components must also be configured for the Web service to function correctly. See IP Service Activator System Administrator's Guide for information about configuring other components using the Configuration GUI.

Pre-requisites for Web Services

In order to use the web service API to integrate with Oracle Communications Order and Service Management, you must complete the following tasks in sequential order: install a WebLogic server, install Oracle Application Development Framework (ADF), and create a WebLogic domain. For information about installing WebLogic and ADF, see Order and Service Management Installation Guide.

Configuring Web Services

Use the IP Service Activator Configuration GUI to configure the web service and deployment parameters, and to deploy or undeploy the web service. For information about web service parameters, see IP Service Activator Installation Guide, Post-Installation Tasks.

Note:
When you change IP Service Activator web service parameters, re-deploy the web service to ensure that the changes take effect.

For information about configuring other components in the Configuration GUI, see IP Service Activator System Administrator's Guide.

Configure web services using the IP Service Activator Configuration GUI.

To configure web services:

1. In the Configuration GUI tree view, double-click the Web Service folder.

2. Click Common.

3. Enter the configuration parameters.
For information about web service configuration parameters, see Table 4-1.

Table 4-1 Web Service Configuration Parameters

Parameter

Description

IPSA ORB Initial Host

The host machine for IPSA CORBA. Default is 127.0.0.1.

IPSA ORB Initial Port

The host port for IPSA CORBA. Default is 2809.

Database Server IP Address

Database server IP address.

Database Server Port

The database server port. Default is 1521.

Database Service Name

The database service name. Default is IPSA.WORLD.

Database User Id

The database user ID. Default is admin.

Database User Password

The database user password.

Confirm Database User Password

Re-enter the database user password.

IPSA User Name

The IP Service Activator user name. Default is admin.

IPSA User password

The IP Service Activator web service user password.

Confirm IPSA User password

Re-enter the IP Service Activator web service user password.

IPSA Web Service User Name

The IP Service Activator web service user name. Default is ipsa_ws_user.

IPSA Web Service User password

The IP Service Activator web service user password.

Maximum Query Load

The maximum query load in bytes. Default is 1024000.

EOM Debug Level

Select an option to define the IP Service Activator EOM Debug level.

OFF: logging is disabled

ERROR: unexpected exceptions are logged at this level (default)

TRACE: all logging is enabled. OIM commands and responses are logged at this level.

DEBUG: lower logging level than Trace

INFO: informational logging. Lower logging level than Debug.

Maximum Retry on Connection Failure

The maximum number of retries on recoverable conditions, for example, database/OIM failures. Default is 3.

OIM Session Timeout

OSS Integration Manager session timeout in seconds. Default is 1200.

OJDL Transaction Short Watch Interval

The OJDL transaction short watch interval in seconds. Default is 5.

OJDL Transaction Short Watch Period

The OJDL transaction short watch period in seconds. Default is 300.

OJDL Transaction Long Watch Interval

The OJDL transaction long watch interval in seconds. Default is 60.

OJDL Transaction Long Watch Period

The OJDL transaction long watch period in seconds. Default is 3600.

OJDL Transaction Commit Period

The OJDL transaction commit period in seconds. Default is 60.

Default Failed Transaction Rollback Behavior

Specifies if failed transactions are automatically rolled back by default. Default is False.

Note: You can override this default by specifying different rollback behavior.

Configuring OSS Integration Manager

If you have an OSS Integration Manager (OIM), or multiple OIMs on multiple servers, that you previously installed and configured in IP Service Activator, you can configure the parameters that allow the web service to interact with those OIMs.

Note:
IP Service Activator does not support multiple OIMs on a single server.

Using the OIM Configuration component in IP Service Activator Configuration GUI, you can add, delete, and modify the OIM configurations that are used for web services.

For more information about installing and configuring OIMs in IP Service Activator, see IP Service Activator OSS Integration Manager Guide.

To configure OIM for Web services:

1. In the Configuration GUI tree view, double-click the Web Service folder.

2. Click OIM Configuration.

3. Enter the configuration parameters for the OIM that you want to configure.
For information about OIM configuration parameters, see Table 4-2.

Table 4-2 OIM Configuration Parameters

Parameter

Description

Name

The CORBA name of the integration manager.

Maximum Sessions

The maximum number of OIM sessions. Default is 10.

Minimum Idle Sessions

The minimum number of idle sessions. Default is 5.

Read Only

Select this option if you want to use the integration manager for read only. Deselect this option if you want to use it for both reading and writing.

Deploying and Undeploying Web Services

Deploy the web service after you configure all parameters, including the deployment parameters, in the IP Service Activator Configuration GUI. For information about web service parameters, see "Configuring Web Services". For information about OIM configuration parameters, see "Configuring OSS Integration Manager".

You can also undeploy the web service.

Note:
To configure the web service deployment, you require information about the WebLogic server on which the Order and Service Management (OSM) server is deployed. WebLogic parameters are required to connect to a Oracle WebLogic Server.

For information about WebLogic, see WebLogic product documentation. For information about OSM, see Order and Service Management Concepts. For information about installing OSM, see Order and Service Management Installation Guide.

To deploy the web service:

1. In the Configuration GUI tree view, double-click the Web Service folder.

2. Click Deployment.

3. Enter the configuration parameters for the Web service deployment.

4. Click Deploy.
The configuration tool does the following:

- Updates the IpsaWebService.ear file with the parameter values that you entered in the web service node.

- Creates a JMS Server, a JMS Module, and JMS queues in WebLogic, if they are not already created.

- Creates a web service security user group and a user in WebLogic, if they are not already created.

- Deploys the IpsaWebService.ear file to WebLogic.

For information about web service deployment parameters, see Table 4-3.

Table 4-3 Web Service Deployment Parameters

Parameter

Description

Weblogic Host

The WebLogic host. Default is 127.0.0.1.

Weblogic Port

The port number for the WebLogic server. Default is 7001.

Weblogic Admin User Name

The WebLogic administrator user name. Default is weblogic.

Weblogic Admin User Password

The WebLogic administrator user password.

Confirm Weblogic Admin User Password

Re-enter the WebLogic administrator user password.

Weblogic Secure Connection

Select this option if you want to use a secure connection to the WebLogic server. Check box is selected by default.

Weblogic Target Server

The WebLogic target server where you want to deploy the IP Service Activator web service.

Weblogic Home

The directory where WebLogic is installed on the server.

To undeploy the web service:

1. In the Configuration GUI tree view, double-click the Web Service folder.

2. Click Deployment.

3. Click Undeploy.

About Web Service Security

IP Service Activator access control security for web services determines the functionality to which each user has access. To set up access control security, create a security role. Give this role the privilege to start IP Service Activator web services. When the web service client accesses the web service, the client needs to authenticate itself to the Oracle WebLogic Server hosting IP Service Activator Web Service. See Oracle WebLogic Administration Guide for information about setting up access security.

Note:
Oracle WebLogic access control security protects only WebLogic Server resources and does not cover secure communication with IP Service Activator web services. As a result, SOAP messages transmitted between the web service and its clients are in plain text.

The web service allow only access level security. Clients must use a user id that is a member of the IPSA_WS_USERS_GROUP group to communicate with IP Service Activator web services. The web.xml file defines the security role IPSA_WS_USERS and the weblogic.xml file defines the security principal name as IPSA_WS_USERS_GROUP.

Running the installer creates a default user. For information about the default user names and passwords used with web services, see IP Service Activator Installation Guide. This user is a member of the IPSA_WS_USERS_GROUP group. Due to limitations of the WebLogic console, information created by the command line tools, such as the role name, might not be available on the console.

About OSM Data Providers

A data provider is used to retrieve data in an XML format from external systems.

The data provider type for IP Service Activator web service is SOAP, which enables you access to web services from OSM and use the responses within behaviors. The required parameter is soap.endpoint, which is an element that identifies the URL to which the SOAP request is sent. Specify the soap.endpoint as:

http://ws_IP:Port/Oracle/IPSAView/Ws/Http

Where ws_IP:Port is the IP Service Activator web service IP and port.

The soap.action parameter contains the URI that identifies the intent of the message. There are several actions that you can specify in the soap.action parameter for IP Service Activator web services. Table 4-4 lists these actions and their corresponding parameters. For more information about the built-in SOAP data provider parameters, and about using data instance behaviors, see Order and Service Management Developer's Guide.

Table 4-4 Action Parameters

soap.action

Parameters

tns/getObject

<soap:Body xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.oracle.com/cgbu/ipsa/osmipsa/ws">

<ws:getObject><-- Mandatory. Path to an object -->

</ws:getObject>

</soap:Body>

tns/getId

<soap:Body xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.oracle.com/cgbu/ipsa/osmipsa/ws">

<ws:getId><-- Mandatory. Path to an object -->

</ws:getId>

</soap:Body>

tns/getPath

<soap:Body xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.oracle.com/cgbu/ipsa/osmipsa/ws">

<ws:getPath><-- Mandatory. Object ID whose path is required -->

</ws:getPath>

</soap:Body>

tns/getName

<soap:Body xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.oracle.com/cgbu/ipsa/osmipsa/ws">

<ws:getName><-- Mandatory. Path to an object or its ID -->

</ws:getName>

</soap:Body>

tns/getParents

<soap:Body xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.oracle.com/cgbu/ipsa/osmipsa/ws">

<ws:getParents><-- Mandatory. Path to an object or its ID -->

</ws:getParents>

</soap:Body>

tns/getChildren

<soap:Body xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.oracle.com/cgbu/ipsa/osmipsa/ws">

<ws:getChildren><-- Mandatory. Path to an object or its ID -->

</ws:getChildren>

</soap:Body>

tns/getAttributes

<soap:Body xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.oracle.com/cgbu/ipsa/osmipsa/ws">

<ws:getAttributes>

<-- Mandatory. Path to an object or its ID -->

</ws:getAttributes>

</soap:Body>

tns/getTransactionStatus

<soap:Body xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.oracle.com/cgbu/ipsa/osmipsa/ws">

<ws: getTransactionStatus>

<-- Mandatory. Path to an object or its ID -->

</ws: getTransactionStatus>

</soap:Body>

tns/getTargets

<soap:Body xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.oracle.com/cgbu/ipsa/osmipsa/ws">

<ws:getTargets>

<-- Mandatory. Path to a ParameterSetInstance object or its ID -->

</ws:getTargets>

</soap:Body>

tns/find

<soap:Body xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.oracle.com/cgbu/ipsa/osmipsa/ws">

<ws:find>

<-- Mandatory. Path to an object or its ID. This is the start point of the search -->

<ws:objectId></ws:objectId>

<-- Mandatory. Type of object to find such as Device, Interface, etc. -->

<ws:type>Interface</ws:type>

<-- Mandatory. Name of the object to find. -->

<-- Wildcards are allowed: * (any number of characters), or ? (any single character) -->

<ws:name>Serial*</ws:name>

<-- Optional. Indicates the direction of the search. Possible values are: parent, child. -->

<-- parent - to search upwards through the hierarchy. -->

<-- child - to search downwards through the hierarchy (this is the default) -->

<ws:findDirection>child</ws:findDirection>

<-- Optional. attribute=value pairs on which to search. -->

<-- Wildcards are allowed in string arguments: * (any number of characters), or ? (any single character) -->

<ws:attr1Name></ws:attr1Name>

<ws:attr1Value></ws:attr1Value>

<ws:attr2Name></ws:attr2Name>

<ws:attr2Value></ws:attr2Value>

<ws:attr3Name></ws:attr3Name>

<ws:attr3Value></ws:attr3Value>

<ws:attr4Name></ws:attr4Name>

<ws:attr4Value></ws:attr4Value>

<ws:attr5Name></ws:attr5Name>

<ws:attr5Value></ws:attr5Value>

</ws:find>

</soap:Body>

tns/findParameters

<soap:Body xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.oracle.com/cgbu/ipsa/osmipsa/ws">

<ws:findParameters>

<-- Mandatory. Path to an object or its ID. This is the start point of the search -->

<ws:objectId><ws:objectId>

<-- Mandatory. Type of object to find such as Device, Interface, etc. -->

<ws:type>Interface</ws:type>

<-- Mandatory. Name of the object to find. -->

<-- Wildcards are allowed: * (any number of characters), or ? (any single character) -->

<ws:name>Serial*</ws:name>

<-- Optional. Indicates the direction of the search. Possible values are: parent, child. -->

<-- parent - to search upwards through the hierarchy. -->

<-- child - to search downwards through the hierarchy (this is the default) -->

Finding and Retrieving Data

Using parameters for search criteria, you can find and retrieve data, such as objects, in IP Service Activator. When searching, the supported wildcard characters are ”*” and ”?”.

For more information, see Order and Service Management Developer's Guide.

Finding Objects

Find objects parameters allow you to find objects in IP Service Activator. For information about objects in IP Service Activator, see OSS Integration Manager Guide.

Use the find objects parameters listed in Table 4-5 to find IP Service Activator objects.

Table 4-5 Find Objects Parameters

Find Objects Parameters

Definition

parentID

The starting path for the IP Service Activator FIND command.

type

The type of object to find in IP Service Activator.

name

The name of the object to find in IP Service Activator.

direction

Search direction; either parent or child.

attr1Name

The first attribute name.

attr1Value

The first attribute value.

attr2Name

The second attribute name.

attr2Value

The second attribute value.

attr3Name

The third attribute name.

attr3Value

The third attribute value.

attr4Name

The fourth attribute name.

attr4Value

The fourth attribute value.

attr5Name

The fifth attribute name.

attr5Value

The fifth attribute value.

The following is an example service request:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header />
<env:Body>
<find xmlns="http://www.oracle.com/cgbu/ipsa/osmipsa/ws">
<parentId>/Policy:"policy"</parentId>
<type>Concreteobject</type>
<name>*</name>
<direction>child</direction>
<!--Optional:-->
<att1Name>state</att1Name>
<!--Optional:-->
<att1Value>installed</att1Value>
<!--Optional:-->
<att2Name />
<!--Optional:-->
<att2Value />
<!--Optional:-->
<att3Name />
<!--Optional:-->
<att3Value />
<!--Optional:-->
<att4Name />
<!--Optional:-->
<att4Value />
<!--Optional:-->
<att5Name />
<!--Optional:-->
<att5Value />
</find>
</env:Body>
</env:Envelope>
Service Response
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header />
<env:Body>
<ws:findResponse xmlns:ws="http://www.oracle.com/cgbu/ipsa/osmipsa/ws">
<ws:eomObject>
<ws:objectId>1425</ws:objectId>
<ws:objectName>1111 on Serial2/0/1.1/1/1/1:2</ws:objectName>
<ws:objectType>ConcreteObject</ws:objectType>
</ws:eomObject>
<ws:eomObject>
<ws:objectId>1430</ws:objectId>
<ws:objectName>111 on Serial2/0/1.1/1/1/1:2</ws:objectName>
<ws:objectType>ConcreteObject</ws:objectType>
</ws:eomObject>
</ws:findResponse>
</env:Body>
</env:Envelope>

Retrieving Objects

Use find parameters to retrieve objects in IP Service Activator.

Use the parameters listed in Table 4-6 to retrieve IP Service Activator objects to which a ParameterSetInstance object applies.

Table 4-6 Find Parameters for Retrieving Objects

findParameter

Definition

parentID

The starting path for the IP Service Activator FIND command.

type

The type of object to find in IP Service Activator.

direction

Search direction; either parent or child.

attr1Name

The first attribute name.

attr1Value

The first attribute value.

attr2Name

The second attribute name.

attr2Value

The second attribute value.

attr3Name

The third attribute name.

attr3Value

The third attribute value.

attr4Name

The fourth attribute name.

attr4Value

The fourth attribute value.

attr5Name

The fifth attribute name.

attr5Value

The fifth attribute value.

The following is an example retrieval request:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header />
<env:Body>
<findParameters xmlns="http://www.oracle.com/cgbu/ipsa/osmipsa/ws">
<parentId>/</parentId>
<type>devicetype</type>
<direction>child</direction>
<!--Optional:-->
<att1Name />
<!--Optional:-->
<att1Value />
<!--Optional:-->
<att2Name />
<!--Optional:-->
<att2Value />
<!--Optional:-->
<att3Name />
<!--Optional:-->
<att3Value />
<!--Optional:-->
<att4Name />
<!--Optional:-->
<att4Value />
<!--Optional:-->
<att5Name />
<!--Optional:-->
<att5Value />
</findParameters>
</env:Body>
</env:Envelope>
Service Response
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header />
<env:Body>
<ws:findParametersResponse xmlns:ws="http://www.oracle.com/cgbu/ipsa/osmipsa/ws">
<ws:objects>
<ws:objectId>551</ws:objectId>
<ws:objectName>Huawei Quidway NetEngine 80E</ws:objectName>
<ws:objectType>DeviceType</ws:objectType>
</ws:objects>
<ws:objects>
<ws:objectId>552</ws:objectId>
<ws:objectName>Huawei Quidway NetEngine 5000E</ws:objectName>
<ws:objectType>DeviceType</ws:objectType>
</ws:objects>
<ws:objects>
<ws:objectId>553</ws:objectId>
<ws:objectName>Huawei Quidway NetEngine NE5000EMulti</ws:objectName>
<ws:objectType>DeviceType</ws:objectType>
</ws:objects>
<ws:objects>
<ws:objectId>554</ws:objectId>
<ws:objectName>Huawei Quidway NetEngine NE40E</ws:objectName>
<ws:objectType>DeviceType</ws:objectType>
</ws:objects>
<ws:objects>
<ws:objectId>555</ws:objectId>
<ws:objectName>Huawei Quidway NetEngine NE20E-4</ws:objectName>
<ws:objectType>DeviceType</ws:objectType>
</ws:objects>
<ws:objects>
<ws:objectId>556</ws:objectId>
<ws:objectName>Huawei Quidway NetEngine NE20E-8</ws:objectName>
<ws:objectType>DeviceType</ws:objectType>
</ws:objects>
<ws:objects>
<ws:objectId>557</ws:objectId>
<ws:objectName>Huawei Quidway NetEngine 40-4</ws:objectName>
<ws:objectType>DeviceType</ws:objectType>
</ws:objects>
<ws:objects>
<ws:objectId>558</ws:objectId>
<ws:objectName>Huawei Quidway NetEngine 40-2</ws:objectName>
<ws:objectType>DeviceType</ws:objectType>
</ws:objects>
<ws:objects>
<ws:objectId>559</ws:objectId>
<ws:objectName>Huawei Quidway NetEngine 40-8</ws:objectName>
<ws:objectType>DeviceType</ws:objectType>
</ws:objects>
<ws:objects>
<ws:objectId>560</ws:objectId>
<ws:objectName>Huawei Quidway Eudemon 500</ws:objectName>
<ws:objectType>DeviceType</ws:objectType>
</ws:objects>
<ws:objects>
<ws:objectId>561</ws:objectId>
<ws:objectName>Huawei Quidway Eudemon 1000</ws:objectName>
<ws:objectType>DeviceType</ws:objectType>
</ws:objects>
<ws:objects>
<ws:objectId>562</ws:objectId>
<ws:objectName>Foundry NetIron IMR 640</ws:objectName>
<ws:objectType>DeviceType</ws:objectType>
</ws:objects>
<ws:objects>
<ws:objectId>563</ws:objectId>
<ws:objectName>Foundry NetIron XMR 4000</ws:objectName>
<ws:objectType>DeviceType</ws:objectType>
</ws:objects>      <ws:objects>        <ws:objectId>564</ws:objectId>        <ws:objectName>Foundry NetIron XMR 8000</ws:objectName>        <ws:objectType>DeviceType</ws:objectType>      </ws:objects>      <ws:objects>        <ws:objectId>565</ws:objectId>        <ws:objectName>Foundry NetIron XMR 16000</ws:objectName>        <ws:objectType>DeviceType</ws:objectType>      </ws:objects>      <ws:objects>        <ws:objectId>566</ws:objectId>        <ws:objectName>Foundry NetIron MLX-4</ws:objectName>        <ws:objectType>DeviceType</ws:objectType>      </ws:objects>      <ws:objects>        <ws:objectId>567</ws:objectId>        <ws:objectName>Foundry NetIron MLX-8</ws:objectName>        <ws:objectType>DeviceType</ws:objectType>      </ws:objects>      <ws:objects>        <ws:objectId>568</ws:objectId>        <ws:objectName>Foundry NetIron MLX-16</ws:objectName>        <ws:objectType>DeviceType</ws:objectType>      </ws:objects>      <ws:objects>        <ws:objectId>569</ws:objectId>        <ws:objectName>Paradyne GranDSLAM 4200</ws:objectName>        <ws:objectType>DeviceType</ws:objectType>      </ws:objects>      <ws:objects>        <ws:objectId>570</ws:objectId>        <ws:objectName>RedBack Networks SMS 1000</ws:objectName>        <ws:objectType>DeviceType</ws:objectType>      </ws:objects>      <ws:objects>        <ws:objectId>571</ws:objectId>        <ws:objectName>RedBack Networks SMS 500</ws:objectName>        <ws:objectType>DeviceType</ws:objectType>      </ws:objects>    </ws:findParametersResponse>  </env:Body>  </env:Envelope>

Retrieving Other Data

You can also use parameters to retrieve other data in IP Service Activator, for example, attributes, child objects, and immediate parent objects.

Use the parameters in Table 4-7 to retrieve other data in IP Service Activator.

Table 4-7 Find Parameters for Retrieving Other Data

findParameter

Definition

getAttributes

Retrieves attributes of an object.

Path: the path/ID to the object.

getChildren

Retrieves immediate child objects of an object.

Path: the path/ID to the objects.

getId

Retrieves the ID of an object.

Path: the path/ID to the objects.

getName

Retrieves the name of an objects.

Path: the path/ID to the objects.

getOrderStatus

Retrieves the order status of an OSM order.

orderKey: the key of an OSM order.

getParents

Retrieves the immediate parent objects of an object.

Path: the path/ID to the objects.

getPath

Retrieves the path on an object.

Path: the path/ID to the object.

getTargets

Retrieves the targets that a ParameterSetInstance object applies to.

Path: the path/ID to the object.

The following is an example for getAttributes:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header />
<env:Body>
<getAttributes xmlns="http://www.oracle.com/cgbu/ipsa/osmipsa/ws">[13]</getAttributes>
</env:Body>
</env:Envelope>
Service Response
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header />
<env:Body>
<ws:getAttributesResponse xmlns:ws="http://www.oracle.com/cgbu/ipsa/osmipsa/ws">
<ws:attribute>
<ws:attributeName>name</ws:attributeName>
<ws:attributeValue />
</ws:attribute>
<ws:attribute>
<ws:attributeName>remarks</ws:attributeName>
<ws:attributeValue />
</ws:attribute>
<ws:attribute>
<ws:attributeName>type</ws:attributeName>
<ws:attributeValue>Any</ws:attributeValue>
</ws:attribute>
<ws:attribute>
<ws:attributeName>id</ws:attributeName>
<ws:attributeValue>13</ws:attributeValue>
</ws:attribute>
</ws:getAttributesResponse>
</env:Body>
</env:Envelope>

Web Service Operations

The set of operations described in Table 4-8 is provided.

Table 4-8 Web Service Operations

Operation

Definition

Parameter

createOrderByValue

Converts an OSM order to an IP Service Activator transaction.

OrderValue

cancelOrderByKey

The web service rolls back the corresponding IP Service Activator transaction.

OrderId

abortOrderByKey

The web service rolls back the corresponding IP Service Activator transaction.

OrderKey

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2016, Oracle and/or its affiliates. All rights reserved.

License Restrictions Warranty/Consequential Damages Disclaimer

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Warranty Disclaimer

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

Restricted Rights Notice

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

Hazardous Applications Notice

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Trademark Notice

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

Third-Party Content, Products, and Services Disclaimer

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.

Alpha and Beta Draft Documentation Notice

If this document is in preproduction status:

This documentation is in preproduction status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.

Private Alpha and Beta Draft Documentation Notice

If this document is in private preproduction status:

The information contained in this document is for informational sharing purposes only and should be considered in your capacity as a customer advisory board member or pursuant to your beta trial agreement only. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described in this document remains at the sole discretion of Oracle.

This document in any form, software or printed matter, contains proprietary information that is the exclusive property of Oracle. Your access to and use of this confidential material is subject to the terms and conditions of your Oracle Master Agreement, Oracle License and Services Agreement, Oracle PartnerNetwork Agreement, Oracle distribution agreement, or other license agreement which has been executed by you and Oracle and with which you agree to comply. This document and information contained herein may not be disclosed, copied, reproduced, or distributed to anyone outside Oracle without prior written consent of Oracle. This document is not part of your license agreement nor can it be incorporated into any contractual agreement with Oracle or its subsidiaries or affiliates.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.