3 Using Service Controller MBeans to Configure a Domain

This chapter provides a high-level overview of using Oracle Communications Service Controller MBeans to configure a domain.

About Service Controller MBeans

The Service Controller Administration Server exposes a set of Java Management eXtensions (JMX) Configuration MBeans enabling JMX-compliant clients to manage and monitor the system.

After initial domain configuration using the Administration Console, the typical method for a telecom carrier to work with Service Controller is to integrate it with a JMX-compatible Network Management System (NMS). The Service Controller configuration MBeans hierarchical tree-structure will be explained in this chapter using a standard JConsole MBeans client.

For more information see the following sources:

Service Controller Configuration and Runtime MBean Java API Reference.
Service Controller runtime MBeans described in "Monitoring Service Controller Using Runtime MBeans"
Using SNMP to monitor Service Controller in "Remote Monitoring Service Controller with SNMP"

Audience For Using Service Controller MBeans

The roles who use the Service Controller MBeans include the following: System Administrator, Integration Developer, Network Engineer, and Application Developer.

Tasks You Can Perform Using Service Controller MBeans

Using Service Controller MBeans, you can perform all tasks that are supported by the Administration Console including the following:

Add and configure managed servers in a domain
Manage Signaling Domain Signaling Server Units (SSUs): Configure IP addresses, point codes, routes, timeout intervals
Manage Processing Domain Interworking Modules (IMs) and supplementary IMs
Configure the Orchestration Engine (OE)
Manage Applications
Manage the Subscriber Store
Install and update software bundles
Configure SNMP traps
Configure Diameter AVPs
Manage the credential stores
Manage the persistent store
Configure a domain if the Administration Console cannot be accessed

Overview of the Configuration MBeans Tree-Structure

This section describes at a high level the tree-structure of Service Controller configuration MBeans. For additional information, see Service Controller Configuration and Runtime MBean Java API Reference.

You access configuration MBeans by connecting your JMX-client to the Administration Console. If you connect to the managed servers, you will view runtime MBeans. See Chapter 15, "Monitoring Service Controller Using Runtime MBeans" for more information.

Do the following: Start JConsole, connect to the Administration Server process, and select the MBeans tab. You should see an MBeans tree-structure similar to this:

Figure 3-1 Service Controller Configuration MBeans Tree-Structure

Administration Server Deployments and Presentation MBeans

If you expand the com.convergin node, there are two nodes:

Deployments: The MBeans under this node are used to add IMs via JMX.
Presentation: The MBeans under this node are used to construct the Administration Console GUI. These MBeans are read-only.

Service Controller Configuration MBeans

The Service Controller configuration MBeans are located under the Oracle node. Expand the Oracle node, to view the Service Controller configuration MBeans. Most configuration MBeans are under the oracle.axia.cm.ConfigurationMBean node:

oracle.axia.api.management.cm.ConfigurationAdminMBean
oracle.axia.api.management.credentialstore.CredentialStoreAdminMBean
oracle.axia.api.management.deployment.DeploymentServiceMBean
oracle.axia.api.management.ds.DomainServiceMBean
oracle.axia.api.management.upgrade.UpgradeManagementMBean
oracle.axia.cm.ConfigurationMBean

Managing the Life Cycle of Domain Configuration Changes

To implement configuration changes you need to open and close the domain, lock and edit, commit changes, discard changes, and propagate the changes to managed servers.

Note:

Open domain and close domain operations are applicable only to JMX-clients and to scripts, not to the Administration Console.

Open a Domain for Configuration

To make changes in a domain configuration, you need to specify the path of the domain to open for configuration. After you open the domain for configuration, no one else can make any changes in the domain.

Invoke the following operation of DomainServiceMBean:
```
void openDomain(String domainPath)
```

See Service Controller Configuration and Runtime MBean Java API Reference for more information.

Select a Domain Configuration Update Mode

After you open the domain for configuration, you can make changes to the configuration using either one of these modes:

Note:

These attributes control how changes to the configuration are made, not how the changes are propagated to the managed servers. See "Specify the Managed Servers Update Mode" for more information.

Autocommit

Autocommit is the default mode when using JMX-clients. Autocommit is not an option that is available when using the Administration Console.

When you update configurations using the Autocommit mode, your changes are committed and written to the configuration directory immediately.
Transaction

When you update configuration using this mode, multiple changes accumulate into one transaction. Using the transaction mode makes it possible to perform a set of configuration updates and then apply them all at once.

The read-only TransactionActive attribute of ConfigurationAdminMBean shows whether you are in transaction or autocommit mode.

To start a transaction:

Invoke the following operation of DomainServiceMBean:
```
void begin()
```

To end a transaction:

Invoke the following operation of DomainServiceMBean:
```
void commit() 
```
Note:
The DomainServiceMBean operations begin, commit, and rollback correspond to the Administration Console Lock&Edit, Commit, and Discard operations.

Close the Domain

To release the lock:

Invoke the following operation of DomainServiceMBean:
```
void closeDomain()
```

See Service Controller Configuration and Runtime MBean Java API Reference for more information.

Specify the Managed Servers Update Mode

Use one of the following modes to specify how configuration changes are propagated to the managed servers:

Online mode: Configuration updates are propagated to all servers in the domain when the changes are committed.
Offline mode: Updates are carried out to the domain configuration and applied to each server only when the server is restarted.

Setting the domain configuration offline makes it possible to perform a set of configuration updates and apply them the next time a server is restarted. This is used, for example, when implementing a rolling upgrade of a Service Controller installation.

To specify the Domain Configuration Update Mode:

Set the OffLine attribute of DomainServiceMBean to one of the following values:
- true
- false

See "Domain Configuration and Managed Server Update Modes" for more information.

Manage the Domain Properties

Each domain configuration has a set of properties that are set during domain creation. The properties are defined as name-value pairs.

After the domain is created, you can change domain properties at any time using DomainServiceMBean.

To change a domain property:

Invoke the following operation of DomainServiceMBean:
```
void setDomainProperty (name, value)
```

For more information, see Service Controller Configuration and Runtime MBean Java API Reference.

Naming Conventions For Service Controller Configuration MBeans

The Service Controller MBeans are registered in an MBean Server under a unique object name. The MBean instances reside in a hierarchy according to its object name. Each Mbean name enables a JMX-compliant client to retrieve an MBean of interest for a particular management operation.

Service Controller names its MBean objects as follows:

oracle:Type=oracle.axia.cm.ConfigurationMBean,Name=com.convergin<component-name.unique-resource>,Version=version_number,name<index0>=resource,name<index1>=resource,name<index2>=resource

Table 3-1 describes the key properties that Service Controller encodes in its MBean object names.

Table 3-1 Service Controller MBean Object Name Key Properties

Property	Description
Type=MBean-type-name	The name of the MBean's type: oracle.axia.cm.ConfigurationMBean
Name=component-name.unique-resource-name	The name of the Service Controller component whose configuration is stored in the MBean, followed by a unique string that was provided upon creation of the MBean to identify the component resource which is represented by the MBean. The name is prefixed: com.convergin
Version=version_number	Specifies the version of the MBean instance. When you upgrade an MBean to a more recent version, this parameter enables Service Controller to keep the same name for different versions of the same MBean and use the version number to differentiate between them.
Name<index>=resource	Identifies object name segments using indexed property names.

For example this is the object name of a SIP protocol adapter MBean:

oracle:type=oracle.axia.cm.ConfigurationMBean,name=oracle.axia.protocol.sip.adapter,version=6.2.0,name0=ProtocolAdapter

Example: Configuring the SS7 Signaling Server Unit for SIGTRAN

This section compares configuring an SS7 Signaling Server Unit for SIGTRAN when using the Administration Console and when using Service Controller configuration MBeans.

See the discussion on configuring the SS7 signaling Server unit for SIGTRAN in Service Controller Signaling Server Units Configuration Guide for details on performing this task using the Administration Console.

The Administration Console provides application level logic that hides the complexity of accessing and configuring the underlying MBeans layer.

Figure 3-2 shows the Administration Console for inputting configuration values.

Figure 3-2 Administration Console: Configuring the SS7 Signaling Server Unit for SIGTRAN

To use MBeans to configure an SS7 Signaling Server Unit for SIGTRAN first start a JMX client such as JConsole. Figure 3-3 shows how you can use the JConsole to update Service Controller MBeans.

Figure 3-3 JConsole/MBeans: Configuring the SS7 Signaling Server Unit for SIGTRAN

Do the following:

Select the node Oracle then select oracle.axia.cm.ConfigurationMbean.
Select com.convergin.wcs.osgi.sf.ssuss7.sigtran. Each attribute and operation is represented by an MBean.
Follow the steps described in this section: "Managing the Life Cycle of Domain Configuration Changes".
Configure all relevant MBeans using the Administration Console to guide you through this task. See the discussion on configuring the SS7 signaling server unit for SIGTRAN in Service Controller Signaling Server Units Configuration Guide for details.

The Service Controller MBean layer is exposed primarily to enable a telecom carrier to integrate Service Controller with a JMX-compliant NMS.

Using a JConsole client for any configuration tasks is recommended only to facilitate the NMS integration or for any technical support inquiries.