Using the IP Address Manager APIs

24 Using the IP Address Manager APIs

Learn about the tasks you can perform using the Oracle Communications Billing and Revenue Management (BRM) IP Address Manager APIs.

For an overview of IP Address Manager features, see "About IP Address Manager" in BRM Telco Integration.

Topics in this document:

Opcodes Described in This Chapter

Table 24-1 lists the opcodes described in this chapter.

Caution:

Always use the BRM API to manipulate data. Changing data in the database without using the API can corrupt the data.
Do not use SQL commands to change data in the database. Always use the API.

Table 24-1 Opcodes Described in This Chapter

Opcode	Topic
PCM_OP_APN_POL_DEVICE_ASSOCIATE	Associating APN with an Account or Service
PCM_OP_APN_POL_DEVICE_CREATE	Creating an APN Device Changing the APN Device State
PCM_OP_APN_POL_DEVICE_DELETE	Deleting an APN Device
PCM_OP_APN_POL_DEVICE_SET_ATTR	Modifying an APN Device
PCM_OP_APN_POL_DEVICE_SET_STATE	Changing the APN Device State
PCM_OP_DEVICE_ASSOCIATE	Associating an IP Address with Accounts or Services Associating APN with an Account or Service
PCM_OP_DEVICE_CREATE	Creating a Single IP Address Device Creating an APN Device
PCM_OP_DEVICE_DELETE	Deleting an IP Address Device Deleting an APN Device
PCM_OP_DEVICE_POL_ASSOCIATE	Disassociating an IP Address Device from Accounts or Services Associating APN with an Account or Service
PCM_OP_DEVICE_POL_CREATE	Creating a Single IP Address Device Creating an APN Device
PCM_OP_DEVICE_POL_DELETE	Deleting an APN Device
PCM_OP_DEVICE_POL_SET_ATTR	Modifying an IP Address Device Modifying an APN Device
PCM_OP_DEVICE_POL_SET_STATE	Changing IP Device States from Unallocated to Returned Changing the APN Device State
PCM_OP_DEVICE_SET_ATTR	Modifying an IP Address Device' Modifying an APN Device
PCM_OP_DEVICE_SET_STATE	Changing IP Device States from Unallocated to Returned Changing the APN Device State
PCM_OP_IP_DEVICE_CREATE	Creating a Single IP Address Device Creating a Range of IP Address Devices Creating a Range of IP Addresses with a Subnet Mask
PCM_OP_IP_DEVICE_DELETE	Deleting an IP Address Device
PCM_OP_IP_DEVICE_SET_ATTR	Modifying an IP Address Device
PCM_OP_IP_DEVICE_SET_STATE	Changing IP Device States from Unallocated to Returned
PCM_OP_IP_POL_DEVICE_ASSOCIATE	Associating an IP Address with Accounts or Services
PCM_OP_IP_POL_DEVICE_CREATE	Creating a Single IP Address Device Customizing IP Address Creation Changing the APN Device State
PCM_OP_IP_POL_DEVICE_DELETE	Deleting an IP Address Device
PCM_OP_IP_POL_DEVICE_SET_ATTR	Modifying an IP Address Device
PCM_OP_IP_POL_DEVICE_SET_STATE	Changing IP Device States from Unallocated to Returned Modifying an IP Address Device

Managing Your IP Address Device Life Cycle

This section explains how to use the IP Facilities Module (FM) and IP Policy FM to manage your IP address inventory.

Creating a Single IP Address Device

You create a single IP address device by calling PCM_OP_IP_DEVICE_CREATE and passing it an flist that includes:

A type-only POID that specifies the device type of /device/ip in the PIN_FLD_POID field
A valid IP address in the PIN_FLD_START_ADDRESS field
The database being used

You add any validation checks or other business logic related to creating a single IP address device to PCM_OP_IP_POL_DEVICE_CREATE.

This is the calling sequence:

PCM_OP_IP_DEVICE_CREATE performs these tasks:
- Verifies that the device type is /device/ip
- Returns an error if the IP address already exists
- Calls PCM_OP_DEVICE_CREATE
PCM_OP_DEVICE_CREATE performs this task:
- Calls PCM_OP_DEVICE_POL_CREATE
PCM_OP_DEVICE_POL_CREATE performs this task:
- Passes everything to PCM_OP_IP_POL_DEVICE_CREATE
PCM_OP_IP_POL_DEVICE_CREATE performs these tasks:
- Determines the IP address number
- Validates that the new IP/APN device combination is unique in the database
- Runs any other validation checks or business logic that you have added
- Returns an error if the IP device/APN device combination is a duplicate
- Passes this information back to PCM_OP_DEVICE_CREATE
PCM_OP_DEVICE_CREATE performs these tasks:
- Creates the object
- Returns an error if the address is invalid

For more information on using PCM_OP_DEVICE_CREATE and PCM_OP_DEVICE_POL_CREATE, see "Creating /device Objects".

Creating a Range of IP Address Devices

You create a range of IP addresses the same way you create a single IP address, with a single call to PCM_OP_IP_DEVICE_CREATE. To create a range of addresses you enter valid start and end IP addresses in the PIN_FLD_START_ADDRESS and PIN_FLD_END_ADDRESS fields. This opcode creates a contiguous range of /device/ip objects, one for each of the addresses, including the start and end addresses.

You have the option of using wildcard characters in the last two octets of the PIN_FLD_START_ADDRESS field. If they are used, PCM_OP_IP_DEVICE_CREATE creates a range using them.

If wildcard characters are not used, PCM_OP_IP_DEVICE_CREATE performs one of the following actions:

Creates a range using the end address
Creates a range using subnet mask
Creates a single IP device

PCM_OP_IP_DEVICE_CREATE returns an error if the range is invalid.

Creating a Range of IP Addresses with a Subnet Mask

You create a range of all possible IP addresses under a specific subnet mask the same way you create a single IP address, with a single call to PCM_OP_IP_DEVICE_CREATE. To create an IP address/subnet mask range, you pass in the following information:

A valid address in the PIN_FLD_START_ADDRESS field
A valid subnet mask address in the PIN_FLD_SUBNET_MASK field

PCM_OP_IP_DEVICE_CREATE verifies that the range is valid and then creates all possible IP addresses in the range including the start and end addresses.

PCM_OP_IP_DEVICE_CREATE returns an error if the range is invalid.

Customizing IP Address Creation

Use PCM_OP_IP_POL_DEVICE_CREATE to customize IP address device creation. By default this opcode only checks to make sure the IP addresses to be created are not duplicates of existing IP addresses. This opcode is an empty hook.

Associating an IP Address with Accounts or Services

You associate an IP address with any number of accounts or services by calling PCM_OP_DEVICE_ASSOCIATE. You also make device state changes to or from the allocated state with a call to PCM_OP_DEVICE_ASSOCIATE.

PCM_OP_DEVICE_ASSOCIATE requires the this information:

An array of IP address objects to associate
A PIN_FLD_SERVICES array containing an /account or /service POIDs in the PIN_FLD_ACCOUNT_OBJ or PIN_FLD_SERVICE_OBJ field
The PIN_FLD_FLAGS field set to 0 (indicating an association)

Use PCM_OP_IP_POL_DEVICE_ASSOCIATE to customize how to verfiy changing the state of an IP address device when services are assigned to, or removed from the device.

Disassociating an IP Address Device from Accounts or Services

The process of disassociating an IP address from accounts or services is much like associating IP addresses and accounts or services, except that you send in the input flist with PIN_FLD_FLAGS set to 1. In this case PCM_OP_DEVICE_POL_ASSOCIATE:

Confirms that none of the IP devices are associated with a service or account
Changes the states from allocated to unallocated
Disassociates the accounts or services by removing them from the /device/ip object

Changing IP Device States from Unallocated to Returned

You change IP device states between unallocated to returned using a call to PCM_OP_IP_DEVICE_SET_STATE. You pass in an array of the IP devices that get the state change, and the new state.

Note:

To make any device state changes to or from the allocated state, see "Associating an IP Address with Accounts or Services".

PCM_OP_IP_DEVICE_SET_STATE calls PCM_OP_DEVICE_SET_STATE.

When setting states for multiple IP devices, PCM_OP_IP_DEVICE_SET_STATE operates on a contiguous range of IP addresses devices based on starting and ending IP addresses you supply. The opcode sets the state for all /device/ip objects in that range.

You add any validation checks or other business logic related to changing the state of all instances of an IP device to PCM_OP_IP_POL_DEVICE_SET_STATE.

PCM_OP_IP_POL_DEVICE_SET_STATE enables you to customize how to verify that an IP address device is eligible to accept a device state change.

PCM_OP_IP_POL_DEVICE_SET_STATE changes the state for all instances of an IP device. This opcode searches for all instances of an IP address in the database and changes their states. If the IP device is associated with multiple APNs, they are all changed.

PCM_OP_IP_POL_DEVICE_SET_STATE is called by PCM_OP_DEVICE_POL_SET_STATE.

PCM_OP_IP_POL_DEVICE_SET_STATE determines whether the IP state change is from or to the allocated state.

If the state change is from or to allocated, it calls PCM_OP_IP_POL_DEVICE_ASSOCIATE to perform the change.
For all other state changes, it calls PCM_OP_IP_DEVICE_SET_STATE to make the state change.

Modifying an IP Address Device

You use PCM_OP_IP_DEVICE_SET_ATTR to change the APN an IP is associated with. You call this opcode and pass it the POID of the /device/ip object and the change you want to make.

This opcode calls PCM_OP_DEVICE_SET_ATTR. To set attributes for a range of devices, send in start and end POIDs and this opcode make changes to all IP devices within that contiguous range.

You add any validation checks or other business logic related to modifying an IP device to PCM_OP_IP_POL_DEVICE_SET_ATTR.

PCM_OP_IP_POL_DEVICE_SET_ATTR verifies that an IP address device is not in an allocated or returned state, and then changes an attribute for the /device/ip object.

PCM_OP_IP_POL_DEVICE_SET_ATTR is an empty hook.

PCM_OP_IP_POL_DEVICE_SET_ATTR is called by PCM_OP_DEVICE_POL_SET_ATTR and PCM_OP_IP_POL_DEVICE_SET_STATE.

Sorting IP Devices by Using Canonical IP Address

The /device/ip object stores a canonical version of the device IP address that sorts more logically than a raw IP address. The PIN_FLD_DEVICE_CANONICAL_ID field contains an IP address that has been canonicalized by expanding all four parts to three digits each by using 0 (zero) as a placeholder. For example, the IP address 152.3.44.67 is stored in PIN_FLD_DEVICE_CANONICAL_ID as 152.003.044.067. Any standard ASCII search will sort these normalized IP address representations in simple numerical order.

Deleting an IP Address Device

To delete an IP address, call PCM_OP_IP_DEVICE_DELETE with a /device/ip object on the input flist. Before you delete IP devices, be sure to disassociate them from and accounts, services, or APNs.

This opcode calls PCM_OP_IP_DEVICE_DELETE. This opcode deletes one IP device at a time. You must call it once for each device to delete.

You add any validation checks or other business logic related to deleting an IP device to PCM_OP_IP_POL_DEVICE_DELETE.

PCM_OP_IP_POL_DEVICE_DELETE verifies that an IP address device is not in an allocated state, and then deletes the /device/ip object.

PCM_OP_IP_POL_DEVICE_DELETE is an empty hook.

You cannot use the IP Address Administrator to delete devices. Using PCM_OP_DEVICE_DELETE is the only way to do this.

Managing your APN Device Life Cycle

This section explains how to use the APN FM to manage your APN device inventory.

Creating an APN Device

To create an APN device, call PCM_OP_DEVICE_CREATE with a /device/apn object on the input flist. You add any validation checks or other business logic related to creating an APN device to PCM_OP_APN_POL_DEVICE_CREATE.

PCM_OP_APN_POL_DEVICE_CREATE is called by PCM_OP_DEVICE_POL_CREATE.

PCM_OP_APN_POL_DEVICE_CREATE verifies that the APN names and IDs being created are correct and determines whether there are any existing APN devices with duplicate names.

PCM_OP_APN_POL_DEVICE_CREATE is an empty hook.

Associating APN with an Account or Service

You associate an APN with an account or service by calling PCM_OP_DEVICE_ASSOCIATE, passing it an flist with the following:

The POID of the /device/apn object in the PIN_FLD_POID field
An account or service POID in the PIN_FLD_ACCOUNT_OBJ or PIN_FLD_SERVICE_OBJ field

You add any validation checks or other business logic related to associating an APN with an account or service PCM_OP_APN_POL_DEVICE_ASSOCIATE.

PCM_OP_APN_POL_DEVICE_ASSOCIATE is called by PCM_OP_DEVICE_POL_ASSOCIATE.

PCM_OP_APN_POL_DEVICE_ASSOCIATE verifies that the APN device is in a new or usable state.

For more information on associating devices by using PCM_OP_DEVICE_ASSOCIATE and PCM_OP_DEVICE_POL_ASSOCIATE, see "Device Management Opcodes", "Device FM Policy Opcodes", and "Device FM Standard Opcodes".

Modifying an APN Device

To modify an APN, call PCM_OP_DEVICE_SET_ATTR, passing it a valid APN ID in the PIN_FLD_DEVICE_ID field. You add any validation checks or other business logic related to modifying an APN device to PCM_OP_APN_POL_DEVICE_SET_ATTR.

PCM_OP_APN_POL_DEVICE_SET_ATTR verifies that an APN device is in a state to accept changes, and then makes the changes.

PCM_OP_APN_POL_DEVICE_SET_ATTR confirms the following:

The APN device object type is /device/apn.
None of the IP addresses associated with the APN device are in an allocated state.

PCM_OP_APN_POL_DEVICE_SET_ATTR is called by PCM_OP_DEVICE_POL_SET_ATTR.

For more information on modifying devices using PCM_OP_DEVICE_SET_ATTR and PCM_OP_DEVICE_POL_SET_ATTR, see "Device Management Opcodes", "Device FM Policy Opcodes", and "Device FM Standard Opcodes".

Changing the APN Device State

To change the state of an APN device, pass the /device/apn object POID and the new state to PCM_OP_DEVICE_SET_STATE. Add any validation checks or other business logic related to changing the state of an APN to PCM_OP_APN_POL_DEVICE_SET_STATE.

PCM_OP_APN_POL_DEVICE_SET_STATE verifies that an APN device is eligible to accept a device state change, and then makes the changes.

PCM_OP_APN_POL_DEVICE_SET_STATE is called by PCM_OP_DEVICE_POL_SET_STATE.

By default, PCM_OP_APN_POL_DEVICE_SET_STATE confirms the following:

If the state change is from usable to unusable, none of its associated IP devices are in an allocated state. If any are, an error is returned, and the entire transaction is rolled back.
If the APN device state change is from new to usable, PCM_OP_IP_POL_DEVICE_CREATE was used to call this opcode.

When changing device states:

The new device state is set by PCM_OP_APN_POL_DEVICE_CREATE only when an APN is created.
Changing the device state from new to usable is allowed only as part of creating an IP device (which must be associated with an APN. In this case PCM_OP_APN_POL_DEVICE_SET_STATE confirms that PCM_OP_IP_POL_DEVICE_CREATE is part of the calling sequence. See "Creating a Single IP Address Device" and "Creating a Range of IP Address Devices".

Deleting an APN Device

You delete an APN device by calling PCM_OP_DEVICE_DELETE with the object type of /device/apn in the input flist. Before you delete the APN device, be sure to disassociate any IP devices or services. You add any validation checks or other business logic related to deleting an APN device to PCM_OP_APN_POL_DEVICE_DELETE.

PCM_OP_APN_POL_DEVICE_DELETE performs validation checks and deletes associated IP devices during APN device deletion. If any associated IP devices are allocated, this opcode does not delete it or the APN device.

PCM_OP_APN_POL_DEVICE_DELETE is called by PCM_OP_DEVICE_POL_DELETE.

You cannot use the IP Address Administrator application to delete devices. Using PCM_OP_DEVICE_DELETE is the only way to do this.

Extending the IP Address Manager Storable Classes

You use the BRM Storable Class Editor to extend the /device/ip storable class to meet your business needs. For more information, see "Creating Custom Fields and Storable Classes" in BRM Developer's Guide.

Adding Business Logic to the IP Address and APN Policy FMs

The IP and APN policy Facilities Modules (FMs) are designed for you to add your own customizations, such as additional validation checks. For information on extending these FMs, see "Adding and Modifying Policy Facilities Modules" in BRM Developer's Guide.