33 About Managing Telephone Numbers

This chapter describes how to manage telephone number inventory in your Oracle Communications Billing and Revenue Management (BRM) system by using Number Manager and Number Administration Center.

You need to manage number inventory when you offer GSM services. For information, see "About Integrating Wireless Services".

Before setting up number management, you need to know the following information:

Important:

Number Manager and Number Administration Center are optional components.

About Managing Numbers

To manage telephone numbers, you use the following components:

  • Number Manager includes the number management opcodes, utilities, configuration files, and storable classes.

  • Number Administration Center is a GUI application used by operations personnel to manage telephone number inventory.

You use Customer Center to assign and manage numbers in customer accounts. For more information, see information about working with GSM accounts in the Customer Center Help.

About Using Number Administration Center

To create an inventory of telephone numbers in the BRM database, you use Number Administration Center to create blocks of numbers. Blocks of numbers usually correspond to geographic regions or business entities. When you create a block of numbers, all the numbers in the block share the block name and the telephone number attributes, such as the network element (also known as home location register, or HLR), and brand. See "Creating a Block of Telephone Numbers".

About Managing Blocks and Numbers

After creating the numbers as devices in the BRM database, you can do the following:

About Managing Numbers with Branded Accounts

When you assign a brand to a block, the telephone numbers in that block are available only to that brand. When you choose a number in Customer Center, you can only choose numbers in the brands for which you have permissions.

In Number Administration Center, brand access is determined by the login. You can create and modify blocks of numbers only for the brands you have permission to access. (For information about brand access, see "About Granting Access to Brands" in BRM Managing Customers.)

When you create a block, you can assign it to a brand, but you can change a block's brand after you create it. However, you cannot change the brand of individual telephone numbers.

If you have access to multiple brands, you can search for blocks or telephone numbers by choosing the brand name.

See "About Branding" in BRM Managing Customers.

Note:

If you use a multischema system, see "Managing Numbers in a Multischema System" for more information about using brands.

Brand-Aware Number Attributes

You can configure the following number attributes for each brand:

Number Attributes that Are Not Brand Aware

You cannot configure the following number attributes for specific brands. Instead, they apply to all numbers in the BRM system:

  • Number categories

  • Network elements

  • Vanity types

Managing Numbers in a Multischema System

If you manage numbers in a multischema system:

  • You cannot change the brand of a block to a brand that is hosted in a different database schema from the schema that the current brand is hosted in. For example, if a block belonging to Brand A is in schema 0.0.0.1, you cannot change the block to Brand B if Brand B is in schema 0.0.0.2.

  • If you log in as a brand host administrator and select Brand Host as the brand to create a new block, you can create blocks only in the schema that you logged in to. If you select any other brand, the block is created in the schema that hosts the selected brand.

  • When searching for blocks or numbers, if you log in as a brand host administrator and you select the top-level brand without including sub-brands in the search criteria, the search results include only numbers or blocks from the schema you logged in to.

  • In a multischema environment that is not brand enabled, you can create numbers only in the schema you are logged in to.

Getting Information about Number Usage

You can get information about number inventory and status by running the Number Manager reports. See "Number Manager Reports" in BRM Reports.

In addition, you can display the history of a customer's number in Customer Center. See information about displaying telephone number history in the Customer Center Help.

You can also display the number inventory in Number Administration Center. See "Displaying the Number Inventory".

About Managing Telephone Numbers in Customer Center

To create accounts and manage telephone numbers in existing accounts, use Customer Center. You can perform the following tasks:

  • Assign telephone numbers to services.

  • Change a customer's telephone number.

  • Display the history of a customer's number.

For more information, see information about working with GSM accounts in the Customer Center Help.

About Number Device States

Telephone numbers have the following device states: new, assigned, quarantined, and unassigned.

  • When you create a number, the device state is New.

  • When you assign a number to a customer, the device state is Assigned.

  • When a customer cancels the service associated with the number, the device state is Quarantined.

    Note:

    By default, you can assign a quarantined number to an account. You can modify the PCM_OP_NUM_POL_DEVICE_ASSOCIATE policy opcode to not allow assigning a quarantined number to an account. You can also write a custom opcode and use it in the device state transition from quarantined to assigned. See "Customizing Device States".

  • By default, a number is unquarantined after 90 days. After a number has been unquarantined, the device state changes to Unassigned.

Figure 33-1 shows how number device state changes:

Figure 33-1 Number Device State Changes

Description of Figure 33-1 follows
Description of ''Figure 33-1 Number Device State Changes''

You cannot use Number Administrator to change the number device state. Instead, the number device state is changed automatically when the number is assigned to an account and when an account or service changes status (for example, when a customer cancels the service that the number is associated with).

Note:

You can create your own number device states. See "Defining the Device Life Cycle" in BRM Developer's Guide.

Taking Numbers Out of Quarantine

By default, a number is quarantined for 90 days. You can change the number of days by running the "load_pin_num_config" utility. See "Changing the Default Quarantine Period".

If you run out of new or unassigned numbers, you can use the "pin_change_num_quarantine" utility to unquarantine numbers. See "Changing the Quarantine Status Manually".

Displaying the Number Inventory

By default, Number Administration Center displays the number inventory when you start the application. To display it at any time, choose View - Number Inventory.

If you log in as a brand account, the inventory is shown for your brand.

Figure 33-2 shows the Number Inventory window.

Figure 33-2 Number Inventory Window

Description of Figure 33-2 follows
Description of ''Figure 33-2 Number Inventory Window''

You can also display the number status of the numbers in a single block. See "About Modifying a Block".

Creating a Block of Telephone Numbers

Important:

Before creating numbers, you must define network elements and any other number properties required by your system (for example, number categories). See "Mandatory Configuration Tasks".

To create a block of numbers in the BRM database, start Number Administration Center and choose File - New Block.

Figure 33-3 shows the block creation screen in Number Administration Center:

Figure 33-3 Block Creation in Number Administration Center

Description of Figure 33-3 follows
Description of ''Figure 33-3 Block Creation in Number Administration Center''

To create a block of numbers, you enter the following information:

  • A start number and an end number that together form the range of numbers in the block. You can use any common format when entering numbers. For example:

    • 1-800-555-1212

    • 1(800) 555-1212

    • 1.800.555.1212

    • 18005551212

  • A block name. This can be any name you want, but you can only use the same name for one block. The maximum length is 255 characters. You can change the block name at any time.

In addition to the block name and the range of numbers in the block, you assign the following number attributes to all the numbers in the block:

  • The brand. When you assign a brand to a block, the telephone numbers in that block are available only for that brand. When you choose a number in Customer Center, you can only choose numbers in the brands for which you have permissions.

    When you assign the brand, you can choose only from the brands for which you have access. If you have the proper brand permissions, you can change the brand after you create the block.

  • The network element. You can change the network element after you create the block.

    To specify the network element, you choose from a list. By default, there are no network elements; you must add your own. You can also localize network elements. See "Creating Network Elements".

  • The number category. This is a configurable field that you can use for managing numbers. It is typically used for identifying corporate entities, but it can be used for defining any type of number classification. For example, you can create number categories for business or residential numbers. You can also localize number categories.

    You can change the number category after you create the block.

    To customize the list of number categories, see "Creating Number Categories". By default, the number categories are None and Reserved.

  • The vanity type. This attribute can be used for customized pricing and rating (see "Rating Implementation and Customization" in BRM Setting Up Pricing and Rating). Number Manager includes only sample vanity types; if you use vanity types, you must create your own. You can localize vanity types. See "Creating Vanity Types".

    When you create a block of numbers, you cannot choose the vanity type for the entire block. By default, the vanity type applied to a new block is the first vanity type defined in the num_vanities.locale file. After creating the numbers, you can apply vanity types to numbers.

  • The service type. You can use the service type to customize business policies. By default, the service type is not applied to any business logic. See "Customizing How Service Types Are Used".

About Customizing Block Creation and Modification

By default, BRM prevents the creation of duplicate numbers. To customize how numbers are created (for example, to prevent numbers or ranges of numbers from being created), edit the PCM_OP_NUM_POL_DEVICE_CREATE source code.

  • You can change the prefix (for example, the North American area code) for a block of numbers. To allow changing of other parts of the number (for example, country codes), modify the PCM_OP_NUM_POL_DEVICE_SET_ATTR source code.

About Modifying a Block

To modify a block:

  1. In Number Administration Center, choose File - Open a Block.

  2. Enter the search criteria. You can search for block name, telephone number, and brand. You can use wildcards when searching for numbers:

    • Use the asterisk (*) to match zero or more characters.

    • Use the question mark (?) to match a single character.

    • To search by brand, choose the brand from the list. To search in all of the brand's sub-brands, select Include sub-brands.

      If you do not use a brand-enabled system, the Brand search attribute and the Brand column are not shown.

    The search results display the block and show the block name, start and end numbers, quantity of the range, brand, when the block was created, and when it was last modified.

    Figure 33-4 shows the Open a Block dialog box:

    Figure 33-4 Open a Block Dialog Box

    Description of Figure 33-4 follows
    Description of ''Figure 33-4 Open a Block Dialog Box''

  3. Select the block and click Open.

    Figure 33-5 shows the Modify Block tab:

  4. Change the block name, prefix, or brand. By default, you can change only the North American area code digits.

  5. Choose File - Commit to Database.

Changing the Size of the Number Block

You can extend the block size by specifying a new higher value for the end number. You can shrink the range of an existing block of numbers by doing either of the following:

  • Specifying a new lower value for the end number.

  • Specifying a new higher value for the start number.

To change the size of the number block:

  1. In Number Administration Center, choose File - Open a Block.

  2. Enter the search criteria.

    You can search for block name, telephone number, and brand. You can use wildcards when searching for numbers:

    • Use the asterisk (*) to match zero or more characters.

    • Use the question mark (?) to match a single character.

    • To search by brand, choose the brand from the list. To search in all of the brand's sub-brands, select Include sub-brands.

    If you do not use a brand-enabled system, the Brand search attribute and the Brand column are not shown. The search results display the blocks and show the block name, start and end numbers, quantity of the range, brand, when the block was created, and when it was last modified.

  3. Select the block and click Open.

  4. In the Modify Block tab, select the Extend/Shrink check box as shown in Figure 33-6.

    Figure 33-6 Extend/Shrink Check Box

    Description of Figure 33-6 follows
    Description of ''Figure 33-6 Extend/Shrink Check Box''

  5. Do one of the following:

    • To extend the number block, in the End number field, enter a value that is higher than the previous end number.

      Note:

      The new end number that you specify must be in a continuous range and not overlap with any other existing blocks.

    • To shrink the number block, in the End Number field, enter a value that is less than the previous end number. Alternatively, in the Start Number field, enter a value that is higher than the previous start number.

  6. Choose File - Commit to Database.

Splitting a Block

You can split a block into two or more blocks. After you split a block, you can modify the blocks (for example, change the North American area code) or brand of the numbers in the blocks.

  1. In Number Administration Center, choose File - Open the block.

  2. Click the Split Block tab.

    By default, two rows are displayed in a table as shown in Figure 33-7:

    Figure 33-7 Splitting a Block

    Description of Figure 33-7 follows
    Description of ''Figure 33-7 Splitting a Block''

    You can use two methods for splitting a block:

    • Enter a quantity in either of the rows. It must be smaller than the current quantity of the block.

    • Enter an end number. It must be a number within the current block range. You cannot enter a start number.

      In either case, the quantity and start and end numbers are updated to match the new block size.

  3. Enter names for the new blocks.

  4. Click Add Block.

  5. Click Commit.

Updating Telephone Numbers

You can use Number Administration Center to search for telephone numbers and modify them. You can update all number attributes except the status and the number itself. For information about number attributes, see "Creating a Block of Telephone Numbers".

Note:

  • You can update numbers by updating a block of numbers. For example, you can change the prefix (by default, the North American area code) for a block of numbers.

  • Changing a telephone number or changing any of its attributes does not create a new /device/number object in the database. Instead, the existing number is updated.

  • It is possible to delete numbers by using opcodes, but it is not recommended. You could reduce data integrity, or accidentally delete a number that is in use.

To update a number:

  1. In Number Administration Center, choose File - Search Numbers.

    The Search window opens.

  2. Enter the search criteria.

    You can search on any number attribute. You can use wildcards when searching for numbers and number category:

    • Use the asterisk (*) to match zero or more characters.

    • Use the question mark (?) to match a single character.

    • Number Administration Center ignores all other punctuation. For example, searching for *8-5* is the same as searching for *85*.

    Figure 33-8 shows the Search Numbers dialog after a search:

    Figure 33-8 Search Number Dialog Box

    Description of Figure 33-8 follows
    Description of ''Figure 33-8 Search Number Dialog Box''

  3. Open the numbers that you want to modify.

    • To open all numbers found in the search, click Open All.

    • To open the page of numbers that is currently displayed, click Open. Click Next Page and Previous Page to display different numbers.

    • Select one or more numbers and click Open.

    • Choose File - Search Numbers to return to the search results.

      To select numbers:

      • To select one number, click it.

      • To select all numbers, click Select All.

      • To select a range of numbers, press SHIFT and click the first and last numbers in the range.

      • To select multiple numbers not in a range, press CTRL and click the numbers.

        Note:

        If the quantity of numbers found is the same or less than the quantity of numbers per page, the Open and Open All buttons open the same set of numbers. For example, if you specify 100 numbers per page, and only 50 numbers are found, both buttons open 50 numbers.

    Figure 33-9 shows the Modify Number Parameters window:

    Figure 33-9 Modify Number Parameters Window

    Description of Figure 33-9 follows
    Description of ''Figure 33-9 Modify Number Parameters Window''

  4. Select the numbers that you want to modify.

  5. Enter the new number attributes.

  6. Click Commit.

About Number Customization Options

You can customize how you manage number inventory as follows:

About the Number Manager Opcodes

To create telephone numbers in the BRM database, Number Manager opcodes do the following tasks:

  • Create and modify blocks of numbers.

  • Manage number quarantine.

  • Manage number portability.

Creating Blocks of Numbers

To create a block of numbers, use the PCM_OP_NUM_CREATE_BLOCK opcode.

PCM_OP_NUM_CREATE_BLOCK calls the PCM_OP_CUST_POL_CANONICALIZE and the PCM_OP_NUM_POL_CANONICALIZE policy opcodes to format the block name and telephone numbers. It calls the PCM_OP_DEVICE_CREATE opcode to create numbers and the PCM_OP_CREATE_OBJ opcode to create the block.

This opcode returns an error if the block name already exists or if any of the telephone numbers already exists.

Modifying Blocks of Numbers

To modify a block of numbers, use the PCM_OP_NUM_MODIFY_BLOCK opcode.

If numbers are changed, this opcode calls the PCM_OP_NUM_POL_CANONICALIZE policy opcode to normalize the number and the PCM_OP_DEVICE_SET_ATTR opcode to change attributes such as the manufacturer, model number, and description.

This opcode returns an error if the new block name already exists or if the range of numbers specified is not valid.

If this opcode runs successfully, it returns the POID of the modified block and an array of POIDs for new blocks.

Splitting Blocks of Numbers

To split a block of numbers, use the PCM_OP_NUM_SPLIT_BLOCK opcode.

The input includes the POID and name of the existing block and the start and end numbers for each block.

If this opcode runs successfully, it returns the POIDs of the original block and the new blocks.

If an invalid block or number attribute is found, this opcode returns an error to the error buffer.

Managing Number Quarantine

To quarantine numbers, use the PCM_OP_NUM_QUARANTINE opcode.

This opcode creates or deletes a /schedule/device object to manage the telephone number quarantine. PCM_OP_NUM_QUARANTINE is called by the PCM_OP_DEVICE_SET_STATE opcode when the number device state changes in and out of the Quarantined state. This is the default behavior as specified in the number device state configuration.

  • If the state transition is to Quarantined, this opcode calls the PCM_OP_ACT_SCHEDULE_CREATE opcode to create a /schedule/device object that, at the end of the quarantine period, will be used to change the state to Unassigned.

  • There are two possible exit transitions from the Quarantined state:

    • If the state transition is from Quarantined to Assigned, this opcode calls the PCM_OP_SEARCH opcode to find the /schedule/device object associated with the number and calls the PCM_OP_ACT_SCHEDULE_DELETE opcode to delete the /schedule/device object.

    • If the state transition is from Quarantined to Unassigned, this opcode calls the PCM_OP_DEVICE_SET_ATTR opcode to delete the text in the device description field so it does not display in Customer Center.

To customize how number quarantine works, you can edit and load the pin_device_state file to call a custom opcode instead of calling PCM_OP_NUM_QUARANTINE. See "Defining the Device Life Cycle" in BRM Developer's Guide.

Managing Number Portability

To manage number portability, use the PCM_OP_NUM_PORT_IN and PCM_OP_NUM_PORT_OUT opcodes.

PCM_OP_NUM_PORT_IN creates a number device using the provided number. This opcode is used when porting the number from another service provider into the existing network.

PCM_OP_NUM_PORT_IN calls standard opcodes to do the following:

  • Create the number and the /device/num object.

  • Set the status of the /device/num object.

  • Reformats the number provided in the input flist to your required format.

  • Validate the required information in the input flist.

  • Search for the provided number in the database and, if found, return an error.

  • If not found, create the number in the number device and update the status of the number device and commit the number to associate the device with the account.

PCM_OP_NUM_PORT_OUT sets the status of the specified telephone number as quarantine_port_out in the /device/num object. PCM_OP_NUM_PORT_OUT is used when porting the number from your network to another service provider.

Note:

The present state of the device must be assigned and the new state must be set to quarantine_port_out. If these are not the states, PCM_OP_NUM_PORT_IN returns an error.

PCM_OP_NUM_PORT_OUT calls standard opcodes to perform the necessary validations and set the status of the number device. This opcode:

  • Validates the number to be ported out.

  • Validates the current status of the number device.

  • Updates the status of the number device.

Customizing Number Manager

Use the following policy opcodes to customize Number Manager:

Customizing Number Normalization

To customize number normalization, use the PCM_OP_NUM_POL_CANONICALIZE policy opcode. This policy opcode handles number normalization when receiving numbers from applications and outputting numbers to other opcodes or applications.

The PCM_OP_NUM_POL_CANONICALIZE opcode is called by PCM_OP_NUM_CREATE_BLOCK opcode when a block of numbers is created.

You can customize this policy opcode to change normalization rules for handling numbers.

By default, this policy opcode performs the following translations:

  • Adds two leading zero characters (00) if they are missing from the input.

  • Removes all characters except digits.

The PCM_OP_NUM_POL_CANONICALIZE policy opcode returns an error when the minimum or maximum length is not valid. These values are defined in the PIN_NUM_CANON_MIN_LENGTH and PIN_NUM_CANON_MAX_LENGTH entries in the pin_num.h file in BRM_Home/include.

If successful, this policy opcode returns the normalized string.

Customizing How Numbers Are Associated with Services

To customize how numbers are associated with services, use the PCM_OP_NUM_POL_DEVICE_ASSOCIATE policy opcode. This policy opcode specifies the rules for associating or disassociate a number and a service. This policy opcode is called by the PCM_OP_DEVICE_ASSOCIATE opcode when a number is associated or disassociated with a service.

  • If the number is being associated and there is no service currently associated with the number, this policy opcode calls the PCM_OP_DEVICE_SET_STATE opcode to change the state to Assigned. This is the default behavior as specified in the number device state configuration.

  • If the number is being disassociated, and there is only one service associated with the number, this policy opcode calls the PCM_OP_DEVICE_SET_STATE opcode to change the state to Quarantined. This is the default behavior as specified in the number device state configuration.

When associating a number that is already associated with a service, the following rules are applied:

  • A number can be associated with multiple services, but each service must be of a different type. For example, you cannot associate one number with two SMS services. To do so, you need to customize the PCM_OP_NUM_POL_DEVICE_ASSOCIATE policy opcode.

  • A number can be associated with multiple services, but all services must belong to the same account.

  • If an associated service has a SIM card device associated with it, the number and the SIM card must have the same network element.

To allow Pipeline Manager to find an account based on the IMSI or MSISDN in the CDR, the PCM_OP_NUM_POL_DEVICE_ASSOCIATE policy opcode copies the IMSI and MSISDN to the alias list array in the associated service object. The element ID is significant:

  • The IMSI is copied to ALIAS_LIST[0]

  • The MSISDN is copied to ALIAS_LIST[1]

The PCM_OP_NUM_POL_DEVICE_ASSOCIATE policy opcode returns an error in the following cases:

  • The number is already associated with the same type of service. For example, if the number is already associated with a fax service, an error is returned if you try to associate the number with another fax service.

  • The service that is being associated does not belong to the same account as an existing associated service.

  • The number network element is not the same as the network element of a SIM card that is already associated with the service.

Customizing Telephone Number Attributes

To customize telephone number attributes when a number is created, use the PCM_OP_NUM_POL_DEVICE_CREATE opcode. This policy opcode validates a new number to make sure it is unique in the database.

This policy opcode is called by the PCM_OP_DEVICE_CREATE opcode and calls the PCM_OP_NUM_POL_CANONICALIZE policy opcode.

You can customize this policy opcode if you extend the number device attributes and require additional validation or if you want to change existing validations.

The PCM_OP_NUM_POL_DEVICE_CREATE policy opcode returns an error if a new number is not unique in the database.

Customizing How a Number Can Be Changed

To customize how a number can be changed, for example, which digits can be changed, use the PCM_OP_NUM_POL_DEVICE_SET_ATTR policy opcode.

By default, the PCM_OP_NUM_POL_DEVICE_SET_ATTR opcode supports changing US area codes by using the following logic: If the number starts with 001 and is 13 digits long, allow changing digits 4 through 6.

This opcode is called by the PCM_OP_DEVICE_SET_ATTR opcode and calls the PCM_OP_NUM_POL_CANONICALIZE policy opcode.

You can customize the PCM_OP_NUM_POL_DEVICE_SET_ATTR policy opcode to allow customized modifications on numbers. For example, you can customize this policy opcode to allow changing digits 5 through 7 of a number if the number starts with 44.

Changing a Block's Brand

To change a block's brand, and the brand of all numbers in the block, use the PCM_OP_NUM_POL_DEVICE_SET_BRAND policy opcode.

All numbers must be in a New or Unassigned state. This policy opcode is called by the PCM_OP_NUM_MODIFY_BLOCK opcode.

You can customize this policy opcode to change how numbers are associated with brands.