44 Using the IP Address Manager APIs

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.

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 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:

  1. 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

  2. PCM_OP_DEVICE_CREATE performs this task:

    • Calls PCM_OP_DEVICE_POL_CREATE

  3. PCM_OP_DEVICE_POL_CREATE performs this task:

    • Passes everything to PCM_OP_IP_POL_DEVICE_CREATE

  4. 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

  5. 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.

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 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.

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 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.

Associating an IP Address with Accounts or Services

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:

  1. PCM_OP_DEVICE_ASSOCIATE performs this task:

    • Calls PCM_OP_DEVICE_POL_ASSOCIATE

  2. 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

  3. 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

  4. PCM_OP_DEVICE_SET_STATE performs this task:

    • Calls PCM_OP_IP_POL_DEVICE_SET_STATE

  5. 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

  6. 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

  7. 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.

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 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

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.

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:

  1. PCM_OP_IP_DEVICE_SET_STATE performs this task:

    • Calls PCM_OP_DEVICE_SET_STATE

  2. PCM_OP_DEVICE_SET_STATE performs this task:

    • Calls PCM_OP_DEVICE_POL_SET_STATE

  3. 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

  4. 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

  5. PCM_OP_DEVICE_POL_SET_STATE performs this task:

    • Returns the output flist to PCM_OP_DEVICE_SET_STATE

  6. 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.

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. 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:

  1. 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

  2. PCM_OP_DEVICE_SET_ATTR performs this task:

    • Calls PCM_OP_DEVICE_POL_SET_ATTR

  3. 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

  4. 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

  5. PCM_OP_DEVICE_POL_SET_ATTR performs this task:

    • Returns the flist to PCM_OP_DEVICE_SET_ATTR

  6. 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.

Setting the Brand on an IP Device

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.

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. 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:

  1. PCM_OP_IP_DEVICE_DELETE performs this task:

    • Calls PCM_OP_DEVICE_DELETE

  2. PCM_OP_DEVICE_DELETE performs this task:

    • Calls PCM_OP_DEVICE_POL_DELETE

  3. PCM_OP_DEVICE_POL_DELETE performs this task:

    • Calls PCM_OP_IP_POL_DEVICE_DELETE if the object passed in is type /device/ip

  4. 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

  5. PCM_OP_DEVICE_POL_DELETE performs this task:

    • Returns the flist to PCM_OP_DEVICE_DELETE

  6. PCM_OP_DEVICE_DELETE performs this task:

    • Deletes the /device/ip object

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.

This is the calling sequence:

  1. PCM_OP_DEVICE_CREATE performs this task:

    • Calls PCM_OP_DEVICE_POL_CREATE

  2. PCM_OP_DEVICE_POL_CREATE performs this task:

    • If the device type is /device/apn, calls PCM_OP_APN_POL_DEVICE_CREATE

  3. 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

  4. PCM_OP_DEVICE_POL_CREATE performs this task:

    • Returns the flist to PCM_OP_DEVICE_CREATE

  5. PCM_OP_DEVICE_CREATE performs these tasks:

    • Creates the /device/apn object

    • Returns an error if the APN name is a duplicate

Associating APN with an Account or Service

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:

  1. PCM_OP_DEVICE_ASSOCIATE performs this task:

    • Calls PCM_OP_DEVICE_POL_ASSOCIATE

  2. 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

  3. 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

  4. PCM_OP_DEVICE_POL_ASSOCIATE performs this task:

    • Returns the flist to PCM_OP_DEVICE_ASSOCIATE

  5. 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.

Modifying an APN Device

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:

  1. PCM_OP_DEVICE_SET_ATTR performs this task:

    • Calls PCM_OP_DEVICE_POL_SET_ATTR

  2. 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

  3. 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

  4. PCM_OP_DEVICE_POL_SET_ATTR performs this task:

    • Returns the flist to PCM_OP_DEVICE_SET_ATTR

  5. 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.

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.

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:

  1. PCM_OP_DEVICE_SET_STATE performs this task:

    • Call PCM_OP_DEVICE_POL_SET_STATE

  2. 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

  3. 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

  4. PCM_OP_DEVICE_POL_SET_STATE performs this task:

    • Returns the output flist to PCM_OP_DEVICE_SET_STATE

  5. 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.

Setting the Brand for an APN Device

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:

  1. PCM_OP_DEVICE_SET_BRAND performs this task:

    • Calls PCM_OP_DEVICE_POL_SET_BRAND

  2. 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

  3. 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

  4. 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

  5. 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

  6. PCM_OP_DEVICE_POL_SET_BRAND performs this task:

    • Returns the input flist to PCM_OP_DEVICE_POL_SET_BRAND

  7. PCM_OP_DEVICE_POL_SET_BRAND performs this task:

    • Returns the input flist to PCM_OP_DEVICE_SET_BRAND

  8. 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.

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.

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:

  1. 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

  2. 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

  3. 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

  4. PCM_OP_DEVICE_POL_DELETE performs this task:

    • Returns the flist to PCM_OP_DEVICE_DELETE

  5. PCM_OP_DEVICE_DELETE performs this task:

    • Deletes the /device/apn object

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.