C Base Rulesets

Note:

This appendix assumes that you have read Chapter 8, "Extending UIM Through Rulesets" and have an understanding of rulesets, extension points, ruleset extension points, and enabled extension points.

This appendix provides information about the Oracle Communications Unified Inventory Management (UIM) base rulesets, which are located in the UIM_Home/cartridges/base/ora_uim_baserulesets.jar file. This appendix provides a description of each base ruleset, and instructions on how to run each base ruleset.

Each base ruleset provides both a DRL file and a GROOVY file.

Address Range Validation

The Address Range Validation base ruleset validates the content of an input GeographicAddressRange object. If a validation error is encountered, the ruleset logs an error. If a validation error is not encountered, processing continues. You can customize the base ruleset to perform custom validations as required by your business needs, and configure the ruleset to run when an address is associated with an address range in UIM.

Running the Base Ruleset

To run the base ruleset, perform the following steps. For instructions on how to perform each step, see the Oracle Communications Design Studio Help and the UIM Help.

  1. In Design Studio, import the ora_uim_baseextpts and ora_uim_baserulesets cartridges.

  2. Modify the ADDRESS_RANGE_VALIDATION base ruleset to reflect your business needs regarding validating address ranges.

  3. Save the modified base ruleset.

  4. Deploy the extended ora_uim_baserulesets cartridge, which now contains the modified ADDRESS_RANGE_VALIDATION ruleset.

  5. Create an Inventory project.

    The Inventory Project editor appears.

  6. Click the Dependency tab.

  7. Add the ora_uim_baseextpts and ora_uim_baserulesets cartridges as dependencies.

  8. Save the Inventory cartridge.

  9. Within the cartridge, create a global ruleset extension point.

    The Ruleset Extension Point-Global editor appears.

  10. Configure the global ruleset extension point as indicated in Table C-1:

    Table C-1 Global Ruleset Extension Point Configuration

    Ruleset Point Placement

    ADDRESS_RANGE_VALIDATION

    AddressRangeManager_validateAddressForRange

    Instead

    (There are no core validations. The validateAddresForRange() method exists for the purpose of running custom validations. So, whether you configure the base ruleset to run before, after, or instead, the outcome is the same; the custom validations are the only validations that run.)

  11. Save the global ruleset extension point.

  12. Build the cartridge and deploy it into UIM.

  13. In UIM, associate an address to an address range.

    When you associate an address to an address range, the AddressRangeManager.validateAddressForRange() method is called. This results in the base ruleset running instead the method, thereby running your custom validations.

Convert LD SR1 to SR2

Because logical devices were enhanced to include the ability to define rate codes. The Convert LD SR1 to SR2 base ruleset updates existing logical devices that were created in UIM prior to release 7.2.2 to have rate codes.

For example, prior to UIM Release 7.2.2, XYZ Logical Device Specification is created and does not define rate codes; all logical devices created in UIM based on XYZ Logical Device Specification do not have rate codes. In UIM 7.2.2, XYZ Logical Device Specification is updated to define rate codes; from UIM 7.2.2 and later, all logical devices created in UIM based on XYZ Logical Device Specification have rate codes. This base ruleset provides the ability to update the existing pre-7.2.2 logical devices to have rate codes that reflect the rate codes XYZ Logical Device Specification now defined.

Running the Base Ruleset

To run the base ruleset, perform the following steps. For instructions on how to perform each step, see the Design Studio Help and the UIM Help.

  1. Create a text file, input.txt, and save it in a temporary directory, tempDir.

  2. Format the input.txt file as follows:

    LogicalDeviceSpecificationName1
LogicalDeviceSpecificationName2
LogicalDeviceSpecificationName3

    where LogicalDeviceSpecification is the name of a Logical Device Specification that defines rate codes. The input file can contain multiple Logical Device Specification names, formatted one per line.

  3. Save the input.txt file.

  4. In UIM, in the Tasks panel Administration group, click the Execute Rule link.

    The Execute Rule page appears.

  5. From the Ruleset list, select CONVERT_LD_SR1_TO_SR2.

  6. Click Browse.

    The Choose File to Upload window appears.

  7. Navigate to tempDir.

  8. Select the input.txt file.

  9. Click Open.

    The Choose File to Upload window closes.

  10. In the Execute Rule page, in the upper-right corner, click Process.

    The base ruleset runs and, based on the input file content, updates any logical device entities that were created from the specified input Logical Device Specifications. The logical device entities are updated with the rate codes defined for the applicable Logical Device Specification.

Create Address Characteristic Map

The Create Address Characteristic Map base ruleset creates a Map object and populates it with characteristic names and corresponding values. The characteristic names and values are mapped from a GeographicAddress object that is input to the ruleset, and the characteristics in the GeographicAddress are derived from the Place specification from which the input GeographicAddress entity was created.

For example, the MyPlace Place specification defines characteristics of address, city, state, and zipCode, as well as a default value for each. In UIM, when a place is created from the MyPlace Place specification, the characteristics are populated with the default values defined in the Place specification. The place is saved as a GeographicPlace object. If the Create Address Characteristic Map base ruleset is called passing in this place, the result is a Map object containing the characteristics of address, city, state, and zipCode, and the corresponding value for each.

Running the Base Ruleset

The Create Address Characteristic Map base ruleset is a supporting ruleset that is called by the Find Address Range and Validate Address For Range base rulesets. The Create Address Characteristic Map ruleset is not intended to be configured to run through a ruleset extension point. See "Find Address Range" and "Validate Address for Range" for more information, and where modifying the Create Address Characteristic Map base ruleset is a step in the instructions for running these base rulesets.

Find Address Range

The Find Address Range base ruleset finds an AddressRange that is valid for the input GeographicAddress, and returns the found AddressRange through the ruleset context. You can customize the base ruleset to find the AddressRange based on customized criteria from the input GeographicAddress, and configure the ruleset to run when you search for an address range for a specific address.

The Find Address Range base ruleset calls the Create Address Characteristic Map base ruleset. See "Create Address Characteristic Map" for more information about this supporting base ruleset.

Running the Base Ruleset

To run the base ruleset, perform the following steps. For instructions on how to perform each step, see the Design Studio Help and the UIM Help.

  1. In Design Studio, import the ora_uim_baseextpts and ora_uim_baserulesets cartridges.

  2. Modify the FIND_ADDRESS_RANGE base ruleset to reflect your business needs regarding finding an address range.

  3. Modify the CREATE_ADDRESS_CHARACTERISTIC_MAP base ruleset, which the FIND_ADDRESS_RANGE ruleset calls.

    See "Create Address Characteristic Map" for more information.

  4. Save the modified base ruleset.

  5. Deploy the extended ora_uim_baserulesets cartridge, which now contains the modified FIND_ADDRESS_RANGE ruleset.

  6. Create an Inventory project.

    The Inventory Project editor appears.

  7. Click the Dependency tab.

  8. Add the ora_uim_baseextpts and ora_uim_baserulesets cartridges as dependencies.

  9. Save the Inventory cartridge.

  10. Within the cartridge, create a global ruleset extension point.

    The Ruleset Extension Point-Global editor appears.

  11. Configure the global ruleset extension point as indicated in Table C-2:

    Table C-2 Global Ruleset Extension Point Configuration

    Ruleset Point Placement

    FIND_ADDRESS_RANGE

    AddressRangeManager_findAddressRange

    Instead

  12. Save the global ruleset extension point.

  13. Build the cartridge and deploy it into UIM.

  14. In UIM, search for an address range for a specific address.

    When you search for an address range for a specific address, the AddressRangeManager.findAddressRange() method is called. This results in the base ruleset running instead the method, where your customized search criteria is then used to find the address range.

Import Inventory

The Import Inventory base ruleset does the following, using an input text file that provides a telephone number ID, a logical device account ID, and an equipment ID:

  • Creates an instance of a telephone number if it does not exist

  • Creates an instance of a logical device account if it does not exist

  • Creates an instance of equipment if it does not exist

  • Validates and creates a custom involvement between the telephone number and logical device account

  • Validates and creates a custom involvement between the logical device account and equipment

Running the Base Ruleset

To run the base ruleset, perform the following steps. For instructions on how to perform each step, see the Design Studio Help and the UIM Help.

  1. In Design Studio, create the following specifications, which will be used by the ruleset to create telephone numbers, logical device accounts, and equipment:

    • Telephone Number Specification

    • Logical Device Account Specification

    • Equipment Specification

  2. Save the specifications.

  3. Deploy the cartridge containing the specifications you just created.

  4. Import the ora_uim_baserulesets cartridge into Design Studio.

  5. Modify the IMPORT_INVENTORY ruleset to reflect the specification names you just created.

  6. Save the modified base ruleset.

  7. Deploy the extended ora_uim_baserulesets cartridge, which now contains the modified Import Inventory ruleset.

  8. Create an input text file, input.txt, and save it in a temporary directory, tempDir.

  9. Format the content of the comma delimited input.txt file as follows:

    TN,LDA,EQUIP
TelephoneNumberId,LogicalDeviceAccountId,EquipmentId

    where TN, LDA, and EQUIP are the attribute names defined in the ruleset, and where TelephoneNumberId, LogicalDeviceAccountId, and EquipmentId are the corresponding values of the attributes. The file format requires a minimum of one set of attribute values, but multiple sets of attribute values can also be specified.

  10. Save the input.txt file.

  11. In UIM, in the Tasks panel Administration group, click the Execute Rule link.

    The Execute Rule page appears.

  12. From the Ruleset list, select IMPORT_INVENTORY.

  13. Click Browse.

    The Choose File to Upload window appears.

  14. Navigate to tempDir.

  15. Select the input.txt file.

  16. Click Open.

    The Choose File to Upload window closes.

  17. In the Execute Rule page, in the upper-right corner, click Process.

    The base ruleset runs and, based on the input file content, telephone numbers, logical devices, and equipment are created if the supplied IDs are not found. The ruleset also creates custom involvements between any supplied telephone numbers and logical devices, and creates custom involvements between ant supplied logical device accounts and equipment.

Place Format Identifier

The Place Format Identifier ruleset defines the display format of the Formatted Identifier field for places that are associated with a specific Place specification. The field is comprised of the characteristics defined for the Place specification with which the place is associated. This ruleset runs in UIM whenever the Formatted Identifier field displays for a place. Figure C-1 shows the Place Summary page for an address where the ruleset concatenates the State, City, Zip Code, Country, Address Line 1, and Address Line 2 characteristics to set the Formatted Identifier field.

Figure C-1 Formatted Identifier Field

Description of Figure C-1 follows
Description of ''Figure C-1 Formatted Identifier Field''

To modify the ruleset, open it in Design Studio and modify the boldface code in Example C-1 if using Drools, or in Example C-2 if using Groovy. The default code randomly appends the characteristics defined for the specification. By modifying the code, you can specify the characteristics to include in the display, and you can specify the order in which the characteristics appear in the display.

Example C-1 Place Format Identifier Rule (Drools)

rule "Locations"
        salience 0
    when
        place : GeographicPlace()
        eval(place instanceof GeographicLocation)
    then
        // execute for location
        StringBuilder formattedIdentifier = new StringBuilder();
        List pc = new ArrayList(place.getCharacteristics());
    if (pc != null) {
        for(int i=0;i<pc.size();i++) {
            String value = ((PlaceCharacteristic)pc.get(i)).getValue();
        if (value != null) formattedIdentifier.append(value).append(" ");
        }
    }
    place.setFormattedIdentifier(formattedIdentifier.toString().trim());    
end
rule "Addresses"
        salience 0
    when
        place : GeographicPlace()
        eval(place instanceof GeographicAddress)
    then
        // execute for address
        StringBuilder formattedIdentifier = new StringBuilder();
        List pc = new ArrayList(place.getCharacteristics());
    if (pc != null) {
        for(int i=0;i<pc.size();i++) {
            String value = ((PlaceCharacteristic)pc.get(i)).getValue();
           if (value != null) formattedIdentifier.append(value).append(" ");
        }
    }
    place.setFormattedIdentifier(formattedIdentifier.toString().trim());   
end

Example C-2 Place Format Identifier Rule (Groovy)

if (place instanceof GeographicLocation) 
{
        // execute for location
        StringBuilder formattedIdentifier = new StringBuilder();
            List pc = new ArrayList(place.getCharacteristics());
            if (pc != null) 
    {
                        for(int i=0;i<pc.size();i++) 
        {
                                String value = ((PlaceCharacteristic)pc.get(i)).getValue();
                                if (value != null) formattedIdentifier.append(value).append(" ");
                        }
        }
     place.setFormattedIdentifier(formattedIdentifier.toString().trim());
}
if (place instanceof GeographicAddress) 
{
            // execute for address
            StringBuilder formattedIdentifier = new StringBuilder();
            List pc = new ArrayList(place.getCharacteristics());
            if (pc != null) 
    {
                        for(int i=0;i<pc.size();i++) 
        {
                                String value = ((PlaceCharacteristic)pc.get(i)).getValue();
                                if (value != null) formattedIdentifier.append(value).append(" ");
                        }
            }
    place.setFormattedIdentifier(formattedIdentifier.toString().trim());
}

Running the Base Ruleset

To run the base ruleset, perform the following steps. For instructions on how to perform each step, see the Design Studio Help and the UIM Help.

  1. In Design Studio, import the ora_uim_baseextpts and ora_uim_baserulesets cartridges.

  2. Modify the PLACE_FORMAT_IDENTIFER ruleset as described above to reflect the needs of your UIM environment.

  3. Save the modified base ruleset.

  4. Deploy the extended ora_uim_baserulesets cartridge, which now contains the modified PLACE_FORMAT_IDENTIFIER ruleset.

  5. Create an Inventory project.

    The Inventory Project editor appears.

  6. Click the Dependency tab.

  7. Add the ora_uim_baseextpts and ora_uim_baserulesets cartridges as dependencies.

  8. Save the Inventory cartridge.

  9. Within the cartridge, create a ruleset extension point.

    The Ruleset Extension Point editor appears.

  10. Configure the ruleset extension point as indicated in Table C-3:

    Table C-3 Ruleset Extension Point Configuration

    Ruleset Point Placement

    PLACE_FORMAT_IDENTIFIER

    PlaceManager_createGeographicPlace

    After

  11. Save the ruleset extension point.

  12. Within the cartridge, create another ruleset extension point.

    The Ruleset Extension Point editor appears.

  13. Configure the ruleset extension point as indicated in Table C-4:

    Table C-4 Ruleset Extension Point Configuration

    Ruleset Point Placement

    PLACE_FORMAT_IDENTIFIER

    PlaceManager_updateGeographicPlace

    After

  14. Save the ruleset extension point.

  15. Because you are working with specification-based extension points, you must also configure any applicable Place Specifications for the ruleset extension points by doing the following for each applicable Place specification:

    Note:

    You do not need to create enabled extension points to configure the Place Specifications; the ora_uim_baseextpts cartridge provides the following base enabled extension points, which enable the PlaceManager_createGeographicPlace and PlaceManager_updateGeographicPlace specification-based extension points for the Place Specification:

    • PlaceSpecification_PlaceManager_createGeographicPlace

    • PlaceSpecification_PlaceManager_updateGeographicPlace

    1. Open the Place Specification editor.

    2. Click the Rules tab.

    3. Click Select.

      The Add Entities window appears.

    4. Select the two ruleset extension points that you just created.

    5. Click OK.

      The Add Entities window closes, and the Place Specification is now configured for the two ruleset extension points.

    6. Save the Place Specification.

  16. Build the cartridge and deploy it into UIM.

  17. In UIM, create or update a place.

    When a place is created or updated, the PlaceManager.createGeographicPlace() method or PlaceManager.updateGeogrphicPlace() method is called. This results in the base ruleset running after, which uses the customized formatting to display the Place Summary Formatted Identifier field.

Reservation Check Redeemer

The Reservation Check Redeemer ruleset enables reservation redemption validations in UIM. By default, reservation redemption validations are disabled in UIM.

In UIM, you can reserve resources to prevent them from being used by other entities or processes. If the reservation is not redeemed by the expiry date, the resource is released back into inventory. You redeem a reserved resource when you assign the resource to a configuration item. By default, UIM does not validate the redemption to ensure that it matches the reservation. So, you may wish to use this ruleset to enable reservation redemption validations.

See UIM Concepts for more information about reservations.

Running the Base Ruleset

To run the ruleset, perform the following steps. For instructions on how to perform each step, see the Design Studio Help and the UIM Help.

  1. In Design Studio, import the ora_uim_baseextpts and ora_uim_baserulesets cartridges.

  2. Create an Inventory project.

    The Inventory Project editor appears.

  3. Click the Dependency tab.

  4. Add the ora_uim_baseextpts and ora_uim_baserulesets cartridges as dependencies.

  5. Save the Inventory cartridge.

  6. Within the cartridge, create a global ruleset extension point.

    The Ruleset Extension Point-Global editor appears.

  7. Configure the global ruleset extension point as indicated in Table C-5:

    Table C-5 Global Ruleset Extension Point Configuration

    Ruleset Point Placement

    RESERVATION_CHECK_REDEEMER

    ReservationManager_checkRedeemer

    Instead

  8. Save the global ruleset extension point.

  9. Build the cartridge and deploy it into UIM.

  10. In UIM, assign a reserved resource to a configuration item.

    When you assign a reserved resource to a configuration item, the ReservationManager.checkRedeemer() method is called. This method simply returns false, which results in reservation redemption validations being disabled. Conversely, the base ruleset simply returns true. So, when you configure the base ruleset to run instead of the ReservationManager.checkRedeemer() method, reservation redemption validations are enabled. When enabled, and you assign a reserved resource to a configuration item, you are required to enter valid reservation information to redeem the reservation.

Note:

If you enable reservation validations through the base ruleset and then later decide you want to disable reservation validations, modify the ruleset to return false and redeploy the cartridge.

Reservation Expiration

The Reservation Expiration base ruleset customizes the reservation expiration process by setting a custom value for the expiry interval when expiring reservations.

When a reservation is created, you can set an expiry date. The expiry date indicates when resource a resource is no longer reserved and the resource returns to the Unassigned state. If no expiry date is set when the reservation is created, the expiry date is calculated and set based on a default interval specified in the UIM_Home/config/consumer.properties file. The default interval indicates the period of time that must elapse before a resource is no longer reserved and returns to the Unassigned state.

The reservation expiration process runs at timed intervals, as specified in the UIM_Home/config/timers.properties file. When the reservation expiration process runs, reservations are checked to see if the expiry date has been reached. If the expiry date has been reached, the reservation is deleted and the resource is returned to the Unassigned state.

The Reservation Expiration ruleset is used to customize the telephone number aging process, which is configured to run at timed intervals specified in the UIM_Home/config/timers.properties file. Reservation expiration is the process of checking reservations to see if the expiry date has been reached. The Reservation Expiration ruleset provides a way to customize the stateExpiry interval for telephone numbers in the Disconnected state. At the specified timed intervals, the ruleset queries for telephone numbers in the Disconnected or Transitional state. If a telephone number is the Disconnected state, the ruleset transitions the state to Transitional, and if a telephone number is the Transitional state, the ruleset transitions the state to Unassigned.

Running the Base Ruleset

To run the base ruleset, perform the following steps. For instructions on how to perform each step, see the Design Studio Help and the UIM Help.

  1. In Design Studio, import the ora_uim_baseextpts and ora_uim_baserulesets cartridges.

  2. Modify the RESERVATION_EXPIRATION ruleset to reflect the needs of your UIM environment regarding reservation expiration for short term or long term reservations, or both.

  3. Save the modified base ruleset.

  4. Deploy the extended ora_uim_baserulesets cartridge, which now contains the modified RESERVATION_EXPIRATION ruleset.

  5. Create an Inventory project.

    The Inventory Project editor appears.

  6. Click the Dependency tab.

  7. Add the ora_uim_baseextpts and ora_uim_baserulesets cartridges as dependencies.

  8. Save the Inventory cartridge.

  9. Within the cartridge, create a global ruleset extension point.

    The Ruleset Extension Point-Global editor appears.

  10. Configure the global ruleset extension point as indicated in Table C-6:

    Table C-6 Global Ruleset Extension Point Configuration

    Ruleset Point Placement

    RESERVATION_EXPIRATION

    ReservationManager_expireReservation

    Instead

  11. Save the global ruleset extension point.

  12. Build the cartridge and deploy it into UIM.

  13. Modify following property values in the UIM_Home/config/timers.properties file as needed for your UIM environment configuration:

    • cleanReservation.firstTime

    • cleanReservation.period

    See UIM System Administrator's Guide for more information about the timers.properites file.

  14. Save the modified timers.properties file.

    ReservationManager.expireReservation() is automatically called at the timer intervals you specified in the timers.properties file. When ReservationManager_expireReservation() is called, the ruleset runs instead of the method, as specified by the global ruleset extension point. The ruleset runs your custom code and sets the custom expiry interval for short term or long term reservations, or both.

System Export and System Import

The System Export and System Import rulesets are used to manage UIM data. For example, you may wish to create a new UIM test environment and load the test environment with data from another UIM environment, or you may wish to export UIM data to send the data upstream in the order fulfillment process.

Exporting Data

The System Export ruleset exports database entities into XML-formatted output files, places the XML files in a ZIP file, and returns the ZIP file. Input to the System Export ruleset is a text file that specifies the export configuration. The input text file name is arbitrary, but it is commonly named config.txt. The config.txt file is also returned in the ZIP file, along with the XML files.

The export configuration specified in the config.txt file defines two sections:

Queries

Queries must be in the form of:

ClassName#QueryString

where ClassName is the data object representation of the database table you are querying, and QueryString is a valid query statement. For example:

oracle.communications.inventory.api.entity.TelephoneNumberSpecification#o.name LIKE 'Sample'
oracle.communications.inventory.api.entity.TelephoneNumberSpecification#o.lastModifiedUser='inventory'

When defining the queries section in the config.txt file:

  • You must pre-pend all attribute names with o because the table name is hard-coded to have an alias of o in the extensibility framework.

  • You can specify multiple queries within a single config.txt file.

Parameters

Parameters must be in the form of:

commitSize=NumericValue
duplicateAction=ActionEnumValue
relationshipsToInclude=IncludeEnumValue

Where NumericValue, ActionEnumValue, and IncludeEnumValue are described as values for the commitSize, duplicateAction, and relationshipsToInclude parameters as follows:

  • commitSize: numeric value greater than 1 and up to a reasonable export size. The default value is 1000.

  • duplicateAction: action to take when duplicate data is encountered in the target data store. Options are:

    • Update: (default) any duplicate record is updated with the newly imported data values.

    • Ignore: do not process, skip the duplicate record.

    • Error: when a duplicate record exists in the target data store, report it as such and end the transaction without taking any action.

  • relationshipsToInclude: describes how to process objects that are related to the selected entity. Options are:

    • Meta: (default) only include relationships that are metadata type relationships, such as specification relationships.

    • Data: only include relationships that are business data in nature, such as characteristics.

    • All: include all relationships including metadata and normal business data associations.

    • None: do not include any relationships and only process the integral type attributes of the selected entity.

For example:

commitSize=1000
duplicateAction=Error
relationshipsToInclude=Meta

When defining the parameters section in the config.txt file:

  • You must place the parameters section directly after the queries section.

  • You may specify all, some, or none of the parameters. Any parameters not specified assume the default value.

Caution:

The System Export ruleset exports data from the UIM database. Metadata Services (MDS) stores additional data used by the UIM UI in the presentation of specifications and characteristics. The export ruleset does not export this additional data from the MDS.

If you are using System Export to export data from environment A, along with System Import to import data into environment B, you can do the following to work around the issue:

  1. Run the System Export ruleset in environment A.

  2. Run the System Import ruleset in environment B.

  3. Deploy the cartridge or cartridges that define the specifications and characteristics that were previously deployed into environment A (resulting in the additional specification and characteristic data being stored in the MDS) into environment B.

If you are using the System Export ruleset without System Import, for example to send data upstream, this is not an issue.

Importing Data

The System Import ruleset imports previously exported XML-formatted data into the system and returns a count of the records imported. Input to the System Import ruleset is the ZIP file returned by the System Export ruleset; the ZIP file contains the XML files.

Note:

To perform the System Import, you must deploy all the same cartridges, that are deployed the System Export environment, to the System Import environment as well.

Caution:

Prior to importing data, you must check the data in the XML files for entity IDs that are duplicates of any entity IDs already in the system into which you are importing. If you find duplicate entity IDs, modify the entity IDs in the XML file prior to importing the data.

The way UIM handles duplicate IDs during import depends on the value of the DuplicateAction parameter specified in the config.txt file. (The config.txt file is available to the System Import ruleset because the input is the ZIP file returned from the System Export ruleset; and the ZIP file contains the XML files and the config.txt file.)

Running the Base Rulesets

To run the base rulesets, perform the following steps. For instructions on how to perform each step, see the Design Studio Help and the UIM Help.

  1. Create a text file, config.txt, and save it in a temporary directory, tempDir.

  2. Format the config.txt file as described above in the "Exporting Data" section.

  3. Save the config.txt file.

  4. In the UIM environment from where you plan to export data, in the Tasks panel Administration group, click the Execute Rule link.

    The Execute Rule page appears.

  5. From the Ruleset list, select SYSTEM_EXPORT.

  6. Click Browse.

    The Choose File to Upload window appears.

  7. Navigate to tempDir.

  8. Select the config.txt file.

  9. Click Open.

    The Choose File to Upload window closes.

  10. In the Execute Rule page, in the upper-right corner, click Process.

    The base ruleset runs and, based on the queries and parameters specified in the config.txt file, exports the data to a ZIP file.

    When the process completes, a message displays on the UIM Execute Rule page, informing you of the number of records processed, and the location and name of the created ZIP file. For example:

    Processed 85 Records Successfully.
Exported Inventory to the location: 
/share/uimcluster/domains/clusterUim722b385/UIM/tmp/xmldata/uimuser1/export/xmlexport.zip

  11. Click Download File to save xmlexport.zip to a temporary directory.

    The File Download window appears.

  12. Click Save.

    The Save As window appears.

  13. Navigate to a temporary directory and click Save.

  14. If necessary, copy xmlexport.zip to a location that can be accessed from the UIM environment where you plan to import the data. (If the UIM environments from which you are exporting and importing are running on the same machine, you do not need to perform this step.)

  15. In the UIM environment where you plan to import the data that you just exported, in the Tasks panel Administration group, click the Execute Rule link.

    The Execute Rule page appears.

  16. From the Ruleset list, select SYSTEM_IMPORT.

  17. Click Browse.

    The Choose File to Upload window appears.

  18. Navigate to the temporary directory that contains the xmlexport.zip file.

  19. Select the xmlexport.zip file.

  20. Click Open.

    The Choose File to Upload window closes.

  21. In the Execute Rule page, in the upper-right corner, click Process.

    The base ruleset runs and, based on the xmlexport.zip file content, imports the data.

Telephone Number Formatting

The Telephone Number Formatting base ruleset defines the telephone number length and display format of telephone numbers in UIM. The ruleset defines a default edit mask that is applied to all telephone numbers, unless otherwise specified. The ruleset can also define additional edit masks that apply to specified Telephone Number specifications. The ruleset runs in UIM when working with telephone numbers and applies a default edit mask of 10 digits (##########).

To modify the base ruleset in Design Studio, scroll to the FUNCTIONS section of the code. You can modify the default edit mask, the specification name and corresponding edit mask, or both. You can also replicate the code and define multiple edit masks that are specific to a particular specification. In Example C-3, the boldface code is the code you need to modify.

Example C-3 Telephone Number Formatting Rule (Drools)

//--------------------------------------------------------------------
// FUNCTIONS
//--------------------------------------------------------------------
function String getEditMask(TelephoneNumberSpecification tnSpec)
{   // The character # is reserved and represents a required digit.
    // The default mask is eight required digits.
    String editMask = "##########";
    if ( tnSpec == null )
        return editMask;
     
    // Define the edit mask based on the spec name   
    if(tnSpec.getName().equals("TNspec NPA-NXX"))
        editMask = "###-###-####";
            
    return editMask;
}
//-------------------------------------------------------------------
// RULES
//-------------------------------------------------------------------
rule "Get TN Edit Mask"
        salience 0
    when
        telephoneNumberSpecification : TelephoneNumberSpecification()
        context : ExtensionPointRuleContext()
    then
        String editMask = getEditMask(telephoneNumberSpecification);
        context.setReturnValue(editMask);  
end

Example C-4 Telephone Number Formatting Rule (Groovy)

//-------------------------------------------------------------------
// FUNCTIONS
//-------------------------------------------------------------------
def String getEditMask(TelephoneNumberSpecification tnSpec) 
{
        // The character # is reserved and represents a required digit.
            // The default mask is eight required digits.
            String editMask = "##########";
            if ( tnSpec == null )
                        return editMask;
 
        // Define the edit mask based on the spec name
            if(tnSpec.getName().equals("TNspec NPA-NXX"))
                        editMask = "###-###-####";
 
        return editMask;
}
//-------------------------------------------------------------------
// RULE
//-------------------------------------------------------------------
log.debug ("", "Get TN Edit Mask");
String editMask = getEditMask(telephoneNumberSpecification);
context.setReturnValue(editMask);

Example C-5 (Drools) and Example C-6 (Groovy) show the modified portion of the Telephone Formatting rule in boldface. (The only difference between the two examples is that Drools defines a function and Groovy defines a def.)

In these examples, the modified rule redefines the default edit mask length format from 10 digits to 11 digits. The examples also redefine the telephone number display format for telephone numbers created from the NANPA telephone number specification to display as +# (xxx) xxx-xxxx. For example, +1 (972) 555-8495.

Example C-5 Telephone Number Formatting Rule (Drools)

function String getEditMask(TelephoneNumberSpecification tnSpec)
 {
    // The character # is reserved and represents a required digit.
    // The default mask is eleven required digits.
    String editMask = "###########";
    if ( tnSpec == null )
        return editMask;

    // Define the edit mask based on the spec name 
    if(tnSpec.getName().equals("NANPA"))
        editMask = "+# (###) ###-####";

    return editMask;
}

Example C-6 Telephone Number Formatting Rule (Groovy)

def String getEditMask(TelephoneNumberSpecification tnSpec)
 {
    // The character # is reserved and represents a required digit.
    // The default mask is eleven required digits.
    String editMask = "###########";
    if ( tnSpec == null )
        return editMask;

    // Define the edit mask based on the spec name 
    if(tnSpec.getName().equals("NANPA"))
        editMask = "+# (###) ###-####";

    return editMask;
}

From this point forward, all telephone numbers created from the NANPA telephone number specification and the TELEPHONE_NUMBER_FORMATTING ruleset are based on the new default length and display format. Any telephone numbers created from the NANPA telephone number specification prior to this ruleset being deployed do not reflect this new default length and display format, nor will they; the telephone number formatting is not applied retroactively.

You can also modify the telephone number default edit mask in the number.properties file. See UIM System Administrator's Guide for more information.

Running the Base Ruleset

To run the base ruleset, perform the following steps. For instructions on how to perform each step, see the Design Studio Help and the UIM Help.

  1. In Design Studio, import the ora_uim_baseextpts and ora_uim_baserulesets cartridges.

  2. Modify the TELEPHONE_NUMBER_FORMATTING ruleset as described above to reflect the needs of your UIM environment.

  3. Save the modified base ruleset.

  4. Deploy the extended ora_uim_baserulesets cartridge, which now contains the modified TELEPHONE_NUMBER_FORMATTING ruleset.

  5. Create an Inventory project.

    The Inventory Project editor appears.

  6. Click the Dependency tab.

  7. Add the ora_uim_baseextpts and ora_uim_baserulesets cartridges as dependencies.

  8. Save the Inventory cartridge.

  9. Within the cartridge, create a ruleset extension point.

    The Ruleset Extension Point editor appears.

  10. Configure the ruleset extension point as indicated in Table C-7:

    Table C-7 Ruleset Extension Point Configuration

    Ruleset Point Placement

    TELEPHONE_NUMBER_FORMATTING

    SpecManager_getEditMask

    Instead

  11. Save the ruleset extension point.

  12. Because you are working with a specification-based extension point, you must also configure any applicable Telephone Specifications for the ruleset extension point by doing the following for each applicable Telephone Number specification:

    Note:

    You do not need to create an enabled extension point to configure the Telephone Number Specifications; the ora_uim_baseextpts cartridge provides the following base enabled extension point, which enables the SpecManager_getEditMask specification-based extension point for the Telephone Number Specification:

    • TelephoneNumberSpecification_SpecManager_getEditMask

    1. Open the Telephone Number Specification editor.

    2. Click the Rules tab.

    3. Click Select.

      The Add Entities window appears.

    4. Select the ruleset extension point that you just created.

    5. Click OK.

      The Add Entities window closes, and the Telephone Number Specification is now configured for the ruleset extension point.

    6. Save the Telephone Number Specification.

  13. Build the cartridge and deploy it into UIM.

  14. In UIM, create or update a telephone number.

    When you create or update a telephone number, the SpecManager_getEditMask() method is called. This results in the ruleset running instead of the method, which applies the default edit mask or specified edit mask to the telephone number and displays the number accordingly.

Note:

Telephone number formatting is not applied retroactively. If you change the formatting for a telephone number specification, the change is not applied to existing telephone numbers created from the specification prior to the edit mask change. However, the change is applied to any new telephone numbers you create from the specification.

Telephone Number Grading

The Telephone Number Grading base ruleset is no longer used. However, the ruleset provides a good example of how to set a characteristic or field, such as country code, when a telephone number is created.

TN Selection

The Telephone Number Grading base ruleset is no longer used, but provides a good ruleset example to follow when creating custom rulesets.

Trail Pipe Topology Edge

Note:

The Trail Pipe Topology Edge base ruleset is valid for use with Connectivity - Pipe entities; it is not valid for use with Connectivity - Channelized entities.

The Trail Pipe Topology Edge base ruleset provides a way for a trail pipe to become a topology edge, which makes the trail pipe be included in the topology and available for path analysis.

In pipe connectivity, all trail pipes are topology edged. However, in channelized connectivity, trail pipes that ride channelized pipes are not topology edges and not available for path analysis. So, you may wish to use this ruleset in channelized connectivity to make trail pipes that ride channelized pipes topology edges so they are included in the topology and available for path analysis.

Running the Base Ruleset

To run the ruleset, perform the following steps. For instructions on how to perform each step, see the Design Studio Help and the UIM Help.

  1. In Design Studio, import the ora_uim_baseextpts and ora_uim_baserulesets cartridges.

  2. Create an Inventory project.

    The Inventory Project editor appears.

  3. Click the Dependency tab.

  4. Add the ora_uim_baseextpts and ora_uim_baserulesets cartridges as dependencies.

  5. Save the Inventory cartridge.

  6. Within the cartridge, create a ruleset extension point.

    The Ruleset Extension Point editor appears.

  7. Configure the ruleset extension point as indicated in Table C-8:

    Table C-8 Ruleset Extension Point Configuration

    Ruleset Point Placement

    TRAIL_PIPE_TOPOLOGY_EDGE

    TopologyMapper_createEnabledByPipes TopologyEdge

    Instead

  8. Save the ruleset extension point.

  9. Because you are working with a specification-based extension point, you must also configure any applicable Pipe specifications for the ruleset extension point by doing the following for each applicable Pipe specification:

    Note:

    You do not need to create an enabled extension point to configure the Pipe Specifications; the ora_uim_baseextpts cartridge provides the following base enabled extension point, which enables the TopologyMapper_createEnabledByPipesTopologyEdge specification-based extension point for the Pipe Specification:

    • PipeSpecification_TopologyMapper_createEnabledByPipesTopologyEdge

    1. Open the Pipe Specification editor.

    2. Click the Rules tab.

    3. Click Select.

      The Add Entities window appears.

    4. Select the ruleset extension point that you just created.

    5. Click OK.

      The Add Entities window closes, and the Pipe Specification is now configured for the ruleset extension point.

    6. Save the Pipe Specification.

  10. Build the cartridge and deploy it into UIM.

  11. In UIM, within a topology model, enable a trail pipe through one or more pipes and save the pipes.

    Saving a pipe calls the processPipe() method, which eventually calls the TopologyMapper_createEnabledByPipesTopologyEdge method.

    When the TopologyMapper.createEnabledByPipesTopologyEdge() method is called, the ruleset is called instead.

Validate Address for Range

The Validate Address For Range base ruleset takes in a GeographicAddressRange and a GeographicAddress and determines whether the given address range is valid for the given address. If valid, the ruleset returns the valid geographic address range through the ruleset context. If not valid, the ruleset returns null. You can customize the base ruleset to perform custom validations as required by your business needs, and configure the ruleset to run when an address is associated with an address range in UIM.

The Validate Address for Range base ruleset calls the Create Address Characteristic Map base ruleset. See "Create Address Characteristic Map" for more information.

Running the Base Ruleset

To run the base ruleset, perform the following steps. For instructions on how to perform each step, see the Design Studio Help and the UIM Help.

  1. In Design Studio, import the ora_uim_baseextpts and ora_uim_baserulesets cartridges.

  2. Modify the VALIDATE_ADDRESS_FOR_RANGE base ruleset to reflect your business needs regarding validating address ranges.

  3. Modify the CREATE_ADDRESS_CHARACTERISTIC_MAP base ruleset, which the VALIDATE_ADDRESS_FOR_RANGE ruleset calls.

    See "Create Address Characteristic Map" for more information.

  4. Save the modified base ruleset.

  5. Deploy the extended ora_uim_baserulesets cartridge, which now contains the modified VALIDATE_ADDRESS_FOR_RANGE ruleset.

  6. Create an Inventory project.

    The Inventory Project editor appears.

  7. Click the Dependency tab.

  8. Add the ora_uim_baseextpts and ora_uim_baserulesets cartridges as dependencies.

  9. Save the Inventory cartridge.

  10. Within the cartridge, create a global ruleset extension point.

    The Ruleset Extension Point-Global editor appears.

  11. Configure the global ruleset extension point as indicated in Table C-9:

    Table C-9 Global Ruleset Extension Point Configuration

    Ruleset Point Placement

    VALIDATE_ADDRESS_FOR_RANGE

    AddressRangeManager_validateAddressForRange

    Instead

    (There are no core validations. The validateAddresForRange() method exists for the purpose of running custom validations. So, whether you configure the base ruleset to run before, after, or instead, the outcome is the same; the custom validations are the only validations that run.)

  12. Save the global ruleset extension point.

  13. Build the cartridge and deploy it into UIM.

  14. In UIM, associate an address to an address range.

    When you associate an address to an address range, the AddressRangeManager.validateAddressForRange() method is called. This results in the base ruleset running instead the method, thereby running your custom validations.

Validate Relate Places

The Validate Relate Places base ruleset validates the existence of a parent-child relationship between two input GeographicAddress objects by determining if the specifications from which the graphic addresses were created have a parent-child relationship.

Running the Base Ruleset

To run the base ruleset, perform the following steps. For instructions on how to perform each step, see the Design Studio Help and the UIM Help.

  1. In Design Studio, import the ora_uim_baseextpts and ora_uim_baserulesets cartridges.

  2. Create an Inventory project.

    The Inventory Project editor appears.

  3. Click the Dependency tab.

  4. Add the ora_uim_baseextpts and ora_uim_baserulesets cartridges as dependencies.

  5. Save the Inventory cartridge.

  6. Within the cartridge, create a ruleset extension point.

    The Ruleset Extension Point editor appears.

  7. Configure the ruleset extension point as indicated in Table C-10:

    Table C-10 Ruleset Extension Point Configuration

    Ruleset Point Placement

    VALIDATE_RELATE_PLACES

    PlaceManager_relatePlaces

    Before

  8. Save the ruleset extension point.

  9. Because you are working with a specification-based extension point, you must also configure any applicable Place specifications for the ruleset extension point by doing the following for each applicable Place specification:

    Note:

    You do not need to create an enabled extension point to configure the Place Specifications; the ora_uim_baseextpts cartridge provides the following base enabled extension point, which enables the PlaceManager_relatePlaces specification-based extension point for the Place Specification:

    • PlaceSpecification_PlaceManager_relatePlaces

    1. Open the Place Specification editor.

    2. Click the Rules tab.

    3. Click Select.

      The Add Entities window appears.

    4. Select the ruleset extension point that you just created.

    5. Click OK.

      The Add Entities window closes, and the Place Specification is now configured for the ruleset extension point.

    6. Save the Place Specification.

  10. Build the cartridge and deploy it into UIM.

  11. In UIM, relate two places.

    When you relate two places, the PlaceManager.relatePlaces() method is called. This results in the ruleset running before the method, which validates the relationship between the geographic places before establishing the relationship between them.