10 Geographic Location

This chapter provides information about the Oracle Communications Unified Inventory Management (UIM) features that enable you to define the geographical aspects of your inventory. There are two ways to model geographic locations in UIM:

Place entities are hierarchical in nature. They enable you to define locations as parts of geographical hierarchies such as Country - Province - City - Area. See "Places" for more information.
Property Location entities are optimized for defining the locations of devices and services in your network. See "Property Locations" for more information.

You can include property locations in the hierarchies of Place entities. For example, you could create property locations for sites that host equipment and include them in the hierarchies of Place entities that represent geographic areas.

Places

You use Place specifications to define geographic entities that can be located on a map, such as a state, city, street, postal address, campus, or building. Place entities answer the business question of where other inventory entities (such as subscribers, services, equipment, service terminations, and so on) are located.

There are four types of Place specification that describe different geographical entities:

Location defines places based on geographic references.
Address defines ways to locate places based on textual information.
Address Range defines a group of addresses as a range, such as an address defined with a low street number and high street number.
Site defines places that do not have a single, precise location, such as a regional office. They can also be used for places that may change physical locations over time, such as a cell site. Because sites are only loosely defined, they can evolve over time. For example, you might need to plan a VPN without knowing the specific locations of the VPN sites. You can create configurations to keep track of the changes.

UIM includes a related entity type, called Location, that you use specifically to represent locations related to connectivity. See "Property Locations" for more information.

Note:

Location entities and Location-type Place entities are not equivalent. They are used for different purposes and have different capabilities.

Geographic Coordinates

You can add geocodes to Place entities to identify their placement and to enable geographic visualizations of your network or business. See UIM System Administrator's Guide and UIM Developer's Guide for more information about setting up geocoding.

You can use one of two coordinate systems:

The universal geographic coordinate system based on latitude and longitude. You must use decimal degrees to enter latitude and longitude. For example, a Dallas location can be expressed in decimal degrees of 32.93499 and -97.00791.
The North American V & H (vertical and horizontal) coordinate system. Telecommunication companies use the V & H coordinate system to calculate distances between locations for the purposes of tariffs, call rating, and revenue sharing. For example, a Dallas location can be expressed as 8398, 4037.

Both coordinate systems are available for a place, but you can enter only one or the other in UIM. When you enter the coordinates for one type of coordinate system, the other coordinate system is disabled for that specific place entity.

Understanding Location-Type Place Entities

You use the Location type for places that can be specifically defined by geographic references. Locations can be very specific places, such as a residence, or more general places, such as a city.

Location Hierarchy

To view your network components graphically and drill down the view from a high level to a lower level, you need to create a location hierarchy.

For example, you can set up a structure as address, city, state, and country. For example, the street address of 7460 Warren Parkway could exist in the city of Frisco within the state of Texas within the country of United States. When viewing networks graphically, you can choose to view networks at the country level, drill down to view the state level, and then drill down to the city level.

Setting Up Locations in Design Studio

In Oracle Communications Design Studio, you define a Place specification for each type of place. For example, create a Place specification for address, another for city, another for state, and one for country. Choose the entity type of Location for each of them. In UIM, you can create a location hierarchy.

Creating Place Entities and Hierarchies in UIM

First create your place based on the appropriate location specification. For example, to create the country Ireland, use the Country specification defined in Design Studio. See the UIM Help for the steps to create locations. Additionally, you can add your geographic information when creating locations.

In UIM, you create the hierarchies in the Place Hierarchy section of the Place Summary page. For example, if you create several cities, you open the state in which the cities reside and assign the cities to the state.

See the UIM Help for the steps to create a place and associate it to the correct hierarchy.

In UIM, you can also assign roles to places. For example, you can assign the role of Headquarters to a site. You assign roles to place entities in the Roles section of the Place Summary page. Role specifications must be defined in Design Studio to enable their use with Place entities. See "About Roles" for additional information.

Understanding Address-Type Place Entities

An address is a textual way to describe a location or site. Address types are managed separately from Locations or Site types because a location or site can have more than one address. For example:

A campus of many buildings has many addresses
A building with entrances on more than one street can have more than one address

An address can define a standard address format to meet your business requirements and national postal standards. For example, in North America, you could define an address to include the following information:

Street address
City name
State
Country
Postal code

These individual pieces of information are called address components. You define them as characteristics and add them to a Place specification with the entity type of Address.

Configuring Address Selections

When you define Address specifications, you can use features that constrain the selections that users see in UIM.

For example, you can constrain that the list of countries available for selection in UIM to only those countries for which entities exist. For example, if only US, UK, and Canada entities exist in the UIM database, only those countries are available for selection. You use the entity link feature in Design Studio to configure an Address specification for this behavior. See the Design Studio Help for more information.

You can also design specifications so that selections are constrained by location hierarchies. For example, when a user selects Texas in the State field, their choices in the City field are limited to cities in that state.

Understanding Address Ranges

You use Address Range to define collections of addresses such as those used in MSAG (Master Street Address Guide) implementations. You define the range by adding address component characteristics to the Address Range specification. You also associate the Address Range specification to the Address specification for which it defines a range.

You can associate an address range to resources or services that serve a range of addresses. Through the use of rulesets, you can use address ranges to validate that new addresses are within a range. See UIM Developer's Guide for more information about rulesets.

Understanding Site-Type Place Entities

A site is a loosely defined place such as a campus, cell site, or VPN site. Unlike a location, a site is not necessarily bound to specific geographic coordinates. Because sites are only loosely defined, they can evolve over time. For example, you might need to plan a VPN without knowing the specific locations of the VPN sites. You can create place configurations to keep track of the changes.

If a site includes multiple specific locations, you can include them in a place hierarchy for the site. For example, if you create a site entity for a campus, you can create locations for its individual buildings and include them in the site's place hierarchy.

Place Configurations

Place configurations provide a versioning capability that enables you to describe how a site is realized and what resources are assigned to a site's configuration items over time. See "Configurations" for general configuration information.

To track the changes to sites, you define Place Configuration specifications. You can use the Specifications Options tab to associate entity specifications. This relationship constrains the types of entities that can be assigned or referenced by the site.

Associating Places with Other Entities

Some entities are place-enabled, meaning you can associate places to those entities. For example, you can associate a location to a piece of equipment. In UIM, you make these associations in the Places section of the Summary page of the entity. In addition, you can specify the role played by the place in its involvement with the entity. See "Involvements" for more information about involvements.

The following types of entities are place-enabled:

Custom network address
Custom object
Device interface
Equipment
Inventory group
Logical device
Logical device account
Network
Network node
Party
Physical device
Pipe
Pipe termination point
Service

Property Locations

Property Location entities define where resources are located and where connectivity is terminated.

Note:

Property Location entities are similar to but not equivalent to Place entities. The two entities have different capabilities. Currently, Property Location entities are used only with connectivity. Place entities are used in all other contexts.

A Property Location entity represents a piece of land with defined legal boundaries. It is the lowest-level element in the hierarchy that identifies a location (country, state/province, city, street address).

When you create a property location, you define it as one or both of the following types:

Network location. A network location is one that hosts devices involved in connectivity. Defining a property location as a network location requires the assignment of a network location code. See "About Network Locations" for more information.
Service location. A service location is one where a service originates or is delivered. See "About Service Locations" for more information.

Property Location entities are different than most other entities because they are all based on a single specification. You can supplement the default data elements of Property Location entities by using entity-level characteristics.

A Property Location specification is included in the ora_uim_basetechnologies base cartridge for this purpose. Entity-level characteristics apply to all Property Location entities in UIM. See UIM Cartridge Guide for information about ora_uim_basetechnologies and the Design Studio Help for information about entity-level characteristics.

You can modify also modify the behavior of Property Locations by using global rulesets. See UIM Developer's Guide for more information about using rulesets.

About Property Addresses

A property address provides a textual way of describing how to find a property. Property addresses are separate entities, but they exist only as part of a property location. They are created automatically when you create property locations. Property addresses can be related only to property locations.

When you create a property location, a primary property address is required. The address fields (Street Address, Apt/Room/Suite, City, Sub Area, State, Postal Code, and Country) are combined to form the default name value for the property location.

You can override the default value and can choose to set the property name to the value of the network location code. For service locations, however, the property name must be unique. If you change the default property name of a service location to a non-unique value, UIM displays an error.

Country and state values are defined as standard ISO abbreviations in the country.properties configuration file. You can define a default country value by editing the system-config.properties file. See UIM System Administrator's Guide for more information about configuration files.

You can validate property addresses using a geocoding system, such as Oracle eLocation. When you validate an address, UIM sets the property address to the value returned by the geocoding system. See "About Validating Addresses" for more information.

About Validating Addresses

When you create a Property Location and enter its address, you can choose to validate the address. Validating addresses ensures accuracy and limits duplication caused by similar addresses.

When you validate an address, UIM sends the address data to a geocoding system, such as Oracle eLocation. (You can configure UIM to use a different geocoding system. See UIM System Administrator's Guide for more information.)

The geocoding system returns one or more possible address from which you can select. You can accept one of the suggested addresses; accept the existing, non-validated address; or choose to neither validate nor accept the address.

If you select one of the possible addresses, the data from the geocoding system replaces the values in the address fields. In addition, the latitude and longitude are updated (unless you have locked the coordinate values). UIM marks the address as validated and displays a green check mark in the address area.
If you accept the existing address, the Accept As-Is check box is selected, indicating that the address does not require validation or correction.
If you cancel the validation, the address remains unvalidated and unchanged.

UIM ignores the Apt/Room/Suite field in the address during validation and does not change it if you select one of the addresses returned by the geocoder.

About Geographic Coordinates in Property Locations

You can enter geographic coordinates for property locations. Geographic coordinates in Property Location entities are similar to geographic coordinates in Place entities. (See "Geographic Coordinates" for more information about how coordinates are used in Place entities.) The are two important differences, however:

In property locations, when you enter a latitude and longitude position or a V & H location, UIM automatically converts it to the other system and populates the corresponding fields. As a result, geographic coordinates are always displayed in both systems.
When you accept a validated address from a GIS system, the geographic coordinates are populated (or replaced) automatically unless you have locked the geographic coordinate fields. See the UIM Help for information about locking coordinates.

About Service Locations

You can define a property location as a service location. A service location represents the place where a service originates or where the service is delivered. (Service locations are sometimes called customer sites or end-user locations.)

For example, Carrier Ethernet service is delivered to one or more service locations by a service provider. In UIM, you reference service locations as configuration items in the configurations of the services that include them. The collection of service locations in a Carrier Ethernet service constitutes a service network. See "About Service Networks" for more information.

Service locations can be outside the boundaries of a service provider's network. For example, Figure 10-1 illustrates a Carrier Ethernet network in which three service locations are inside the service provider network and one service location is outside it. The three service locations inside the provider network are included in an Ethernet Virtual Connection (EVC) and the other service location is an Operator Virtual Connection (OVC) connected to the EVC by a connectivity. (Both EVCs and OVCs are types of private virtual networks (PVNs).)

Figure 10-1 Carrier Ethernet Network with Service Locations

Description of "Figure 10-1 Carrier Ethernet Network with Service Locations"

Because service locations can be outside of the service provider network, they do not require network location codes or network entity codes. In cases where service locations are within your provider network, however, you may want to identify a service location as a network location by assigning it a network location code. In this scenario, the Property Location entity is both a service location and a network location.

By default, property names for service locations are a concatenation of the address details, such as 329 BENBOW ST. APT 29 SACRAMENTO CA 95812 US or 200 LOWER HIGH ST, LONDON, GREATER LONDON SE3 1JX, UK. You can override the default value, but the property name must be unique for service locations because it is used as an identifier.

If the property location is defined as both a network location and a service location, the network location code can override the property name.

About Network Locations

You can define a property location as a network location. Network locations are property locations that host a service provider's inventoried network infrastructure. In UIM, network locations host network devices (logical devices associated with that location). When you define a property location as a network location, you must assign it a network location code.

Network location codes are strings of up to 10 alphanumeric characters, with letters in upper case. Network location codes can be CLLI (Common Language Location Identifier) codes, but UIM does not validate against the CLLI standard.

Oracle recommends an expanded version of the CLLI standard for network location codes. This version includes an additional two characters to represent the country, which is not present in CLLI codes. The Oracle-recommended code format is:

MMMMSSCCPP

where:

MMMM represents the municipality in four characters (the same as CLLI and other standards). For example, Plano is PLAN and Cleveland is CLEV. This value must be unique within the state.
SS represents the state in two characters, as in the ISO standards.
CC represents the country in two characters, as in the ISO standards.
PP represents the property in two characters. This is the same as the CLLI building or site value and must be unique within the municipality.

For example, PLANTXUSXA identifies a property location (XA) in Plano, Texas, in the United States.

You can set minimum and maximum values for your system in the system-config.xml file. See UIM Systems Administrator's Guide for more information. For example, to support CLLI coding, you can specify minimum and maximum values of 8. For the Oracle-recommend format, you could specify minimum and maximum values of 10.

About Network Entities

Network locations can host logical devices that you identify with network entity codes. Logical devices that are hosted at network locations are called network entities. Network entity codes must be unique within each network location, but can be duplicated in the network as a whole. Each network entity code identifies a single logical device and a logical device can have only one network entity code.

Note:

Physical devices cannot be directly associated with network locations.You can make an indirect association by associating a physical device to a logical device at a network location. See "Associating Physical Devices to Logical Devices" for more information.

Network entity codes can contain information that identifies the type of entity for which they are used. For example, codes used for digital cross-connect systems could begin with the letter K. The entity codes K01 and K02 could be used to identify two digital cross-connect devices at network location MTVWCAUS99. The same codes could be used to identify two different digital cross-connect devices at PLANTXUSXA77.

By default, network entity codes are three characters long. You can set the default minimum and maximum length in the system-config.xml file. See UIM System Administrator's Guide for more information about setting default values.

Note:

Network entity codes are optional and are typically not used for devices that do not require activation or management.

Figure 10-2 illustrates the relationship between network locations and network entities.

Figure 10-2 Network Locations and Network Entities

Description of "Figure 10-2 Network Locations and Network Entities"

Network entity codes are always displayed with their parent network location codes to form a network entity location code. For example, the network entity locations mentioned previously are displayed as MTVWCAUS99.K01, MTVWCAUS99.K02, and so on. By default, UIM uses a dot as the delimiter between the network location code and the network entity code, but you can suppress the display of the delimiter by changing an entry in the system-config.xml file. See UIM Systems Administrator's Guide for more information.

You can select a network location or a network entity location in logical device entities to establish the relationship between the device and the location. See "Associating Logical Devices with Network Locations and Network Entity Locations" for more information.

The endpoints (pipe termination points) of a Connectivity entity can be associated with a network location, such as PLANTXUS or to a network entity location such as PLANTXUS.K01. You can associate a network location or a network entity location to an end point even before the location has been associated to a logical device. See "About Network Locations" for more information.

If the connectivity end point is associated with a network entity location, the end point can be terminated only on an interface that is part of the logical device at the location. The network entity location code is incorporated into the connectivity identifier of the Connectivity entity. See "About Termination" for more information.