This chapter describes the tasks you can perform using the Oracle Communications Billing and Revenue Management (BRM) IP Address Manager APIs. Before performing any of these tasks, read this information:
For an overview of IP Address Manager features, see "About IP Address Manager".
Most IP Address Manager customizations will include modifying the IP Facilities Module (FM). For information and advice on how to do this, see "Writing a Custom Facilities Module" in BRM Developer's Guide.
If you need to create subclasses of the default IP Address Manager storable classes, see "Creating Custom Fields and Storable Classes" in BRM Developer's Guide.
To create APN and IP address devices in the BRM database, the IP Address Manager opcodes do the following tasks:
This section explains how to use the IP Facilities Module (FM) and IP Policy FM to manage your IP address inventory.
You create a single IP address device by calling the PCM_OP_IP_DEVICE_CREATE opcode 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
Calls PCM_OP_DEVICE_SET_BRAND to get the correct brand of the IP address
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.
Executes 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" in BRM Developer's Guide.
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 range of /device/ip objects, one for each of the addresses, including the start and end addresses.
PCM_OP_IP_DEVICE_CREATE returns an error if the range is invalid.
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.
Use the PCM_OP_IP_POL_DEVICE_CREATE policy opcode 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 a hook designed for you to add any more validation checks or business logic that your business requires.
You associate an IP address with any number of accounts or services by calling the PCM_OP_DEVICE_ASSOCIATE opcode. 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)
This is the calling sequence:
PCM_OP_DEVICE_ASSOCIATE performs this task:
Calls PCM_OP_DEVICE_POL_ASSOCIATE
PCM_OP_DEVICE_POL_ASSOCIATE performs these tasks:
Executes any validation checks or other business logic that you added
Calls PCM_OP_IP_POL_DEVICE_ASSOCIATE if the device type is /device/ip
PCM_OP_IP_POL_DEVICE_ASSOCIATE performs these tasks:
Calls PCM_OP_DEVICE_SET_STATE to change the device state from new or unallocated to allocated
Executes any validation checks or business logic that you added
Calls PCM_OP_DEVICE_SET_STATE
PCM_OP_DEVICE_SET_STATE performs this task:
Calls PCM_OP_IP_POL_DEVICE_SET_STATE
PCM_OP_DEVICE_POL_SET_STATE performs the following tasks:
Executes any other validation checks or business logic that you have added
Calls PCM_OP_IP_POL_DEVICE_SET_STATE to change the device state
PCM_OP_IP_POL_DEVICE_SET_STATE performs these tasks:
Executes any validation checks or business logic that you added
Returns the flist to PCM_OP_DEVICE_ASSOCIATE
Returns an error if an IP address is already allocated, or an IP address/service combination is not permitted
PCM_OP_DEVICE_ASSOCIATE performs this task:
Modifies the /device/ip object by adding the accounts or services passed to it
For more information on device associations using PCM_OP_DEVICE_ASSOCIATE and PCM_OP_DEVICE_POL_ASSOCIATE, see "Associating /service and /device Objects" in BRM Developer's Guide.
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 the PCM_OP_DEVICE_POL_ASSOCIATE policy opcode:
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
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.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.
First you start by passing in an input flist to PCM_OP_IP_DEVICE_SET_STATE with this information:
An array of POIDS to change (probably search results)
The new state of for the devices
This is the calling sequence:
PCM_OP_IP_DEVICE_SET_STATE performs this task:
Calls PCM_OP_DEVICE_SET_STATE
PCM_OP_DEVICE_SET_STATE performs this task:
Calls PCM_OP_DEVICE_POL_SET_STATE
PCM_OP_DEVICE_POL_SET_STATE performs these tasks:
Executes any other validation checks or business logic that you have added
Calls PCM_OP_IP_POL_DEVICE_SET_STATE if the device passed in is type /device/ip
PCM_OP_IP_POL_DEVICE_SET_STATE performs these tasks:
Executes any other validation checks or business logic that you have added
Returns the output flist to PCM_OP_DEVICE_POL_SET_STATE
PCM_OP_DEVICE_POL_SET_STATE performs this task:
Returns the output flist to PCM_OP_DEVICE_SET_STATE
PCM_OP_DEVICE_SET_STATE performs this task:
Makes the state change to all the /device/ip objects that have the same address
For more information on PCM_OP_DEVICE_SET_STATE and PCM_OP_DEVICE_POL_SET_STATE, see "Changing the State of a /device Object" in BRM Developer's Guide.
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. You add any validation checks or other business logic related to modifying an IP device to PCM_OP_IP_POL_DEVICE_SET_ATTR.
This is the calling sequence:
PCM_OP_IP_DEVICE_SET_ATTR performs this task:
Calls PCM_OP_DEVICE_SET_ATTR if the device POID passed in is an /device/ip object
PCM_OP_DEVICE_SET_ATTR performs this task:
Calls PCM_OP_DEVICE_POL_SET_ATTR
PCM_OP_DEVICE_POL_SET_ATTR performs these tasks:
Performs any validation checks or business logic that you have added
Calls PCM_OP_IP_POL_DEVICE_SET_ATTR if the object passed in is type /device/ip
PCM_OP_IP_POL_DEVICE_SET_ATTR performs these tasks:
Validates that the object type is /device/ip.
Validates that the opcode being called is PCM_OP_IP_POL_DEVICE_SET_ATTR
Validates that the device state is not allocated or returned
Validates that the caller is not trying to change the IP device address
Executes any other validation checks or business logic that you have added
Returns an error if any of the validation checks fail
Returns the output flist to PCM_OP_DEVICE_POL_SET_ATTR
PCM_OP_DEVICE_POL_SET_ATTR performs this task:
Returns the flist to PCM_OP_DEVICE_SET_ATTR
PCM_OP_DEVICE_SET_ATTR performs this task:
Makes the changes to the /device/ip object
For more information on modifying devices using PCM_OP_DEVICE_SET_ATTR and PCM_OP_DEVICE_POL_SET_ATTR, see "Changing the Attributes of /device Objects" in BRM Developer's Guide.
You cannot change an IP device by itself. Instead, you use the instructions in Setting the Brand for an APN Device to change the brands of all IP devices associated with a single APN at the same time.
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.
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. You add any validation checks or other business logic related to deleting an IP device to PCM_OP_IP_POL_DEVICE_DELETE.
Note:
The IP Address Administrator does not support deleting devices. Using PCM_OP_DEVICE_DELETE is the only way to do this.This is the calling sequence:
PCM_OP_IP_DEVICE_DELETE performs this task:
Calls PCM_OP_DEVICE_DELETE
PCM_OP_DEVICE_DELETE performs this task:
Calls PCM_OP_DEVICE_POL_DELETE
PCM_OP_DEVICE_POL_DELETE performs this task:
Calls PCM_OP_IP_POL_DEVICE_DELETE if the object passed in is type /device/ip
PCM_OP_IP_POL_DEVICE_DELETE performs these tasks:
Validates that the object type is /device/ip
Validates that the IP device is not in an allocated state
Executes any validation checks or other business logic that you have added
Returns an error if any of the validation checks fail
Returns the flist to PCM_OP_DEVICE_POL_DELETE
PCM_OP_DEVICE_POL_DELETE performs this task:
Returns the flist to PCM_OP_DEVICE_DELETE
PCM_OP_DEVICE_DELETE performs this task:
Deletes the /device/ip object
This section explains how to use the APN FM to manage your APN device inventory.
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.
This is the calling sequence:
PCM_OP_DEVICE_CREATE performs this task:
Calls PCM_OP_DEVICE_POL_CREATE
PCM_OP_DEVICE_POL_CREATE performs this task:
If the device type is /device/apn, calls PCM_OP_APN_POL_DEVICE_CREATE
PCM_OP_APN_POL_DEVICE_CREATE performs these tasks:
Validates that the APN name is unique within the database passed in
Executes any other validation checks or business logic that you have added
Returns the output flist to PCM_OP_DEVICE_POL_CREATE
PCM_OP_DEVICE_POL_CREATE performs this task:
Returns the flist to PCM_OP_DEVICE_CREATE
PCM_OP_DEVICE_CREATE performs these tasks:
Creates the /device/apn object
Returns an error if the APN name is a duplicate
You associate an APN with an account or service by calling the PCM_OP_DEVICE_ASSOCIATE opcode, 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.
This is the calling sequence:
PCM_OP_DEVICE_ASSOCIATE performs this task:
Calls PCM_OP_DEVICE_POL_ASSOCIATE
PCM_OP_DEVICE_POL_ASSOCIATE performs these tasks:
Executes any validation checks or business logic that you have added
Calls PCM_OP_APN_POL_DEVICE_ASSOCIATE
PCM_OP_APN_POL_DEVICE_ASSOCIATE performs these tasks:
Changes the device state from new to allocated
Executes any validation checks or business logic that you have added
Returns the flist to PCM_OP_DEVICE_POL_ASSOCIATE
PCM_OP_DEVICE_POL_ASSOCIATE performs this task:
Returns the flist to PCM_OP_DEVICE_ASSOCIATE
PCM_OP_DEVICE_ASSOCIATE performs this task:
Modifies the /device/apn object by adding the account or service passed to it
For more information on associating devices using PCM_OP_DEVICE_ASSOCIATE and PCM_OP_DEVICE_POL_ASSOCIATE, see "Associating /service and /device Objects" in BRM Developer's Guide.
To modify an APN, call the PCM_OP_DEVICE_SET_ATTR opcode, 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.
This is the calling sequence:
PCM_OP_DEVICE_SET_ATTR performs this task:
Calls PCM_OP_DEVICE_POL_SET_ATTR
PCM_OP_DEVICE_POL_SET_ATTR performs these tasks:
Executes any validation checks or business logic that you have added
Calls PCM_OP_APN_POL_DEVICE_SET_ATTR
PCM_OP_APN_POL_DEVICE_SET_ATTR performs these tasks:
Executes any validation checks or business logic that you have added
Validates that:
The object type is /device/apn.
The opcode being called is PCM_OP_APN_POL_DEVICE_SET_ATTR.
None of the IP devices associated with the APN are in an allocated state.
The caller is not trying to change the APN device address to one that is already in use.
Executes any other validation checks or business logic that you have added
Returns an error is any of the IP devices associated with the APN have a status of allocated or returned
Returns an error if you are trying to change the device ID and the new device ID is a duplicate of an existing device ID
Returns the output flist to PCM_OP_DEVICE_POL_SET_ATTR
PCM_OP_DEVICE_POL_SET_ATTR performs this task:
Returns the flist to PCM_OP_DEVICE_SET_ATTR
PCM_OP_DEVICE_SET_ATTR performs this task:
Makes the changes to the /device/apn object
For more information on modifying devices using PCM_OP_DEVICE_SET_ATTR and PCM_OP_DEVICE_POL_SET_ATTR, see "Changing the Attributes of /device Objects" in BRM Developer's Guide.
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.
State change notes:
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.
This is the calling sequence:
PCM_OP_DEVICE_SET_STATE performs this task:
Call PCM_OP_DEVICE_POL_SET_STATE
PCM_OP_DEVICE_POL_SET_STATE performs these tasks:
Executes any other validation checks or business logic that you have added
If the object passed in is the type /device/apn, calls PCM_OP_APN_POL_DEVICE_SET_STATE
PCM_OP_APN_POL_DEVICE_SET_STATE performs these tasks:
Executes any other validation checks or business logic that you have added
This opcode first confirms that none of the IP devices associated with the APN device are in an allocated state. If any are, it returns an error and rolls back the entire transaction
Returns the output flist to PCM_OP_DEVICE_POL_SET_STATE
If the device state change is from new to usable, confirms that is being done as a part of IP device creation by confirming that PCM_OP_IP_POL_DEVICE_CREATE is part of the calling sequence
PCM_OP_DEVICE_POL_SET_STATE performs this task:
Returns the output flist to PCM_OP_DEVICE_SET_STATE
PCM_OP_DEVICE_SET_STATE performs this task:
Makes the change to the /device/apn object
For more information on PCM_OP_DEVICE_SET_STATE and PCM_OP_APN_POL_DEVICE_SET_STATE, see "Changing the State of a /device Object" in BRM Developer's Guide.
To set the brand for an APN, call the PCM_OP_DEVICE_SET_BRAND opcode, passing it a valid brand POID in the PIN_FLD_POID field. You add any validation checks or other business logic related to setting the brand for an APN device to PCM_OP_APN_POL_DEVICE_SET_BRAND.
This is the calling sequence:
PCM_OP_DEVICE_SET_BRAND performs this task:
Calls PCM_OP_DEVICE_POL_SET_BRAND
PCM_OP_DEVICE_POL_SET_BRAND performs these tasks:
Executes any other validation checks or business logic that you have added
Calls PCM_OP_APN_POL_DEVICE_SET_BRAND
PCM_OP_APN_POL_DEVICE_SET_BRAND performs these tasks:
Validates that the device type is /device/apn
Validates that the opcode being called is PCM_OP_APN_POL_DEVICE_SET_BRAND
Validates that the APN has a state of new. or usable
Validates that none of the IP addresses associated with the APN are in an allocated state
Executes any other validation checks or business logic that you have added.
Returns an error message if any of the validation checks fail
Calls PCM_OP_DEVICE_SET_BRAND for each IP device associated with the APN, and passes it the /device/apn object
PCM_OP_DEVICE_SET_BRAND performs these tasks for each IP device it finds:
Calls PCM_OP_DEVICE_SET_BRAND and PCM_OP_DEVICE_POL_SET_BRAND
PCM_OP_DEVICE_POL_SET_BRAND calls PCM_OP_IP_POL_DEVICE_SET_BRAND
PCM_OP_IP_POL_DEVICE_SET_BRAND performs these tasks for each IP device:
Validates that the device type is /device/ip
Validates that the opcode being called is PCM_OP_IP_POL_DEVICE_SET_BRAND
Validates that the call is from PCM_OP_APN_POL_DEVICE_SET_BRAND
Validates that the state of the IP device is either new or allocated
Executes any other validation checks or business logic that you have added
If an error is returned while setting the brand on any of the IP devices, the entire transaction is aborted and rolled back (no IP devices get the name change)
Returns the input flist or an error message to PCM_OP_DEVICE_POL_SET_BRAND
PCM_OP_DEVICE_POL_SET_BRAND performs this task:
Returns the input flist to PCM_OP_DEVICE_POL_SET_BRAND
PCM_OP_DEVICE_POL_SET_BRAND performs this task:
Returns the input flist to PCM_OP_DEVICE_SET_BRAND
PCM_OP_DEVICE_SET_BRAND performs this task for the APN device:
Sets the brand to the APN device object
For more information on setting brands using PCM_OP_DEVICE_SET_BRAND and PCM_OP_DEVICE_POL_SET_BRAND, see "Associating /devices and /brand Objects" in BRM Developer's Guide.
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.
Note:
The IP Address Administrator does not support deleting devices. Using PCM_OP_DEVICE_DELETE is the only way to do this.This is the calling sequence:
PCM_OP_DEVICE_DELETE performs these tasks:
Calls PCM_OP_DEVICE_POL_DELETE
Executes any other validation checks or business logic that you have added
PCM_OP_DEVICE_POL_DELETE performs this task:
Calls PCM_OP_APN_POL_DEVICE_DELETE if the object passed to it is type /device/apn
PCM_OP_APN_POL_DEVICE_DELETE performs these tasks:
Validates that the object type is /device/apn
Probes for IP devices associated with the APN device; if it finds any, performs these tasks:
Confirms that none of the IP devices are allocated; if any are, returns an error
Deletes the IP devices by calling PCM_OP_DEVICE_POL_DELETE once for each device
PCM_OP_DEVICE_POL_DELETE performs this task:
Returns the flist to PCM_OP_DEVICE_DELETE
PCM_OP_DEVICE_DELETE performs this task:
Deletes /device/ip objects that were associated with the APN device
Executes any other validation checks or logic that you have added
Returns an error if any of the validation checks fail
Returns the flist to PCM_OP_DEVICE_POL_DELETE
PCM_OP_DEVICE_POL_DELETE performs this task:
Returns the flist to PCM_OP_DEVICE_DELETE
PCM_OP_DEVICE_DELETE performs this task:
Deletes the /device/apn object
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.
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.