4 Monitoring and Managing Unified Inventory Management

This chapter provides monitoring and managing activities that you may need to perform after installing or upgrading the Oracle Communications Unified Inventory Management (UIM) software.

Sharing JAR Files

After you install UIM, you need to share specific JAR files with Oracle Communications Design Studio for use with cartridges. Each individual UIM system administrator must determine the best method for sharing these JAR files, based on your company's standard practices.

Note:

These JAR files change with each new patchset or maintenance release. The JAR files need to be re-distributed each time UIM is upgraded with a patchset or maintenance release and the Design Studio system administrator needs to be notified.

For more information on sharing JAR files with Design Studio, see the chapter on ”Using Design Studio to Extend UIM” in UIM Developer's Guide.

Disabling the HTTP Port

After you install UIM, you can disable the HTTP (non-SSL) port if it was enabled during installation.

To disable the HTTP port:

  1. Ensure you are logged into the WebLogic Administration Console.

  2. Click Lock & Edit.

  3. In the Domain Structure tree, expand Environment, and then click Servers.

    The Summary of Servers page appears.

  4. Select the AdminServer.

    The Settings for AdminServer page appears.

  5. Deselect the Listen Port Enabled setting.

    Note:

    If you disable this port, then you must enable the SSL port.

  6. Click Save.

  7. Click Activate Changes.

Setting the Database Row Prefetch Size

You can specify the number of result set rows to prefetch.

  1. Ensure you are logged into the WebLogic Administration Console.

  2. Click Lock & Edit.

  3. In the Domain Structure tree, expand Services and then click Data Sources.

    The Summary of JDBC Data Sources page appears.

  4. Click the InventoryDataSource data source.

    The Settings for InventoryDataSource page appears.

  5. Under Configuration, click the Connection Pool tab.

  6. In the Properties field, enter the following:

    defaultRowPrefetch=50

  7. Click Save.

  8. Repeat steps 3 through 7 for InventoryTxDataSource.

  9. Click Activate Changes.

  10. Restart the WebLogic Application Server.

Modifying the Default File Encoding

The UIM installer automatically sets the default file encoding to UTF8 for both full installations and upgrades. Check the startup script to verify that the default file encoding is set to UTF8. If this setting is incorrect, you can manually change the default file encoding setting in the CUSTOM SECTION segment of the startup script.

The following example shows the correct command syntax:

JAVA_OPTIONS="${JAVA_OPTIONS}-Dfile.encoding=UTF-8"

Modifying the Time Zone

For full installations and upgrades, the UIM installer automatically sets the time zone for your locale. You should check your startup script to verify that the time zone setting for your locale is correct. If this setting is incorrect, add a line to the CUSTOM SECTION segment of your startup script. Enter the time zone ID in a format that is recognizable by the java.util.TimeZone object. The following example shows the command syntax:

JAVA_OPTIONS="${JAVA_OPTIONS} -Duser.timezone=Asia/Shanghai"

To view a list of valid time zone values, run the following command:

import java.util.*;
public class TimeZoneList {
  public static void main(String[] args) {
  String[] sZoneIds = TimeZone.getAvailableIDs();
  List lZoneIdList = Arrays.asList(sZoneIds);
  Collections.sort(lZoneIdList);
  System.out.println(lZoneIdList);
  }
}

Note:

If your application server and database server are located in different time zones, set the application server's user.timezone value to match the database server's time zone. The application server and database server time zones must match.

Note:

The application server time zone is defaulted to the underlying operating system time zone. To configure a different time zone for the application server, add the following value to the startup script at Domain_Home/bin/setUIMenv.sh. The valid time zone values are defined in java.util.TimeZone.

JAVA_OPTIONS="${JAVA_OPTIONS} -Duser.timezone=timezone"

where timezone is a valid string value defining the time zone ID such as GMT or EST.

Configuring Your Server's Timers

You can create and configure timers for:

  • Monitoring whether the server that manages the cluster-aware timers is still running

  • Custom extensions

  • Cleaning up expired reservations

  • Cleaning up expired entity row locks

  • Recalling disconnected IP resources

  • Detecting telephone number jeopardy and publishing notification events

You configure the timers for your servers in the UIM_Home/config/timers.properties file. For more information, see the comments in the timers.properties file.

Registering Entities to the LifeCycle Listener

You can register all or a subset of entities for create, retrieve, update, and delete (CRUD) events. For example, you can specify that create events are generated when any entity is created. Likewise, you can specify that update events are generated only when Equipment and TelephoneNumber entities are updated.

Configuring Exception-Type-to-Error-Code Mappings

You can map error codes to exception types to help the persistence framework manage validation exceptions. For example, you can map error codes to DuplicateEntityException or to AttributeRequiredException.

You map error codes to exception types by using the UIM_Home/config/resources/logging/exception.properties file. For more information, see the comments in the exception.properties file.

Localizing UIM Error Messages

You can localize UIM error messages and items by modifying properties files in the UIM_Home/config/resources/logging directory.

Table 4-1 lists each property's file name, error ID range, and the error messages or items it localizes.

Table 4-1 Properties Files for Localizing UIM Error Messages and Items.

Property File Name Error ID Range Error Message or Item It Localizes

addressrange.properties

N/A

Property names for the address range cartridge

businessInteraction.properties

270000-279999

Error messages generated by the business interaction module

capacity.properties

320000-329999

Error messages generated by the capacity module

configaction.properties

240000-249999

Error messages generated by the configuration actions

configuration.properties

240000-249999

Tree node label names

connectivity.properties

260000-269999

Error messages generated by the connectivity module

consumer.properties

220000-229999

Error messages generated by the consumer module

countries.properties

N/A

Error messages generated by the countries module

custom.properties

280000-289999

Error messages generated by the custom module

enum.properties

N/A

Error messages generated by enumeration

equipment.properties

210000-219999

Error messages generated by the equipment module

exception.properties

N/A

Error messages generated by the framework module

extensibility.properties

180000-189999

Error messages generated by the extensibility module

flowidentifiers.properties

620000-629999

Error messages generated by the packet connectivity module

importExport.properties

160000-169999

Error messages generated by the import/export module

inventoryGroup.properties

190000-199999

Error messages generated by the inventory group module

ip.properties

610000-619999

Error messages generated by the IP address module

location.properties

420000-420999

Error messages generated by the location module

logicaldevice.properties

290000-299999

Error messages generated by the logical device module

media.properties

350000-359999

Error messages generated by the media module

mediaResource.properties

360000-369999

Error messages generated by the mediaResource module

network.properties

300000-309999

Error messages generated by the network module

networkaddress.properties

620000-629999

Error messages generated by the network address module

number.properties

120000-129999

Error messages generated by the number module

party.properties

230000-239999

Error messages generated by the party role module

place.properties

250000-259999

Error messages generated by the place module

product.properties

390000-399999

Error messages generated by the product module

project.properties

140000-149999

Error messages generated by the project module

resource.properties

330000-339999

Resource entity names and resource-related error messages

role.properties

90000-99999

Error messages generated by the role module

service.properties

110000-119999

Error messages generated by the service module

signal.properties

310000-319999

Error messages generated by the connectivity signal module

specification.properties

130000-139999

Error messages generated by the specification module

status.properties

N/A

Error messages generated by the status module

subscriber.properties

150000-159999

Error messages generated by the subscriber module

system.properties

100000-109999

Error messages generated by the framework module

topology.properties

340000-349999

Error messages generated by the topology module

workflow.properties

N/A

Error messages generated by the workflow module

wsservice.properties

400000-409999

Error messages generated by the wsservice module

For more information on how to localize UIM, see UIM Developer's Guide.

Localizing the UIM Server and the Application Server

By default, the UIM and application server software display information in English. You can set the software to display information in another language by localizing text strings in the UIM properties files. For more information, see UIM Developer's Guide.

Shutting Down an Application Server

UIM provides a script to shut down an application server. Use the following command or the kill command on the machine running the server to be shut down:

stopWebLogic.sh AdminUserID AdminPassword ServerName AdminServerURL

where AdminServerURL is in the format: t3://ServerName:PortNumber

For example:

stopWebLogic.sh weblogic password server03 t3://wplsnroyall:7101

Deploying the Inventory Enterprise Application

UIM's core functionality runs as an Enterprise Application on the application server under the deployment name oracle.communications.inventory. The application file associated with the inventory enterprise application is the inventory.ear file. The following describes the steps for deployment:

Note:

You must ensure the application is un-deployed before doing a deploy. Optionally, ensure the temporary files for the WebLogic Server are cleaned up when the server is shut down, so that they cannot be used as cached information.

  1. Start the Weblogic administration server.

  2. Start the WebLogic Server Administration Console using the following URL:

    http://serverName:port/console

    where

    • serverName is the host name for UIM

    • port is the port number of the machine on which UIM is installed

  3. Enter the administration user name and password and click Login.

  4. In the Change Center of the administration console, click Lock & Edit.

  5. In the left Domain Structure pane of the console, select Deployments.

  6. In the right pane under Deployments, click Install.

  7. In the Install Application Assistant, navigate to or enter the directory path location of the inventory.ear file.

  8. Click the radio button next to the inventory.ear file, and click Next.

    The Choose targeting style window appears.

  9. Select Install this deployment as an application and click Next.

  10. Ensure the deployed name of the application is set to the following:

    oracle.communications.inventory

    and click Next.

  11. Review the configuration settings you have chosen and click Finish.

    If you chose to change the deployment configuration later, the console returns to the Deployments table.

  12. To activate the changes, under the Change Center area of the console, click Activate Changes.

Configuring the SSL Policy/Certificate

This section describes the configuration of SSL with Oracle WebLogic server. You must configure the new self-signed certificate in the WebLogic Administration Console.

To generate a new private key and self-signed certificate:

  1. Navigate to the WL_home/server/lib directory and run the following command:

    keytool -alias aliasValue -genkey -keypass keypassword -keystore keystore.jks -storepass keystorepass

    where:

    • aliasValue is the name

    • keypassword is the password

    • keystore.jks is the key store name

    • keystorepass is the key store password

  2. For What is your first and last name?, enter the application server IP address.

  3. Provide relevant information for the following prompts:

    • What is the name of your organizational unit?

    • What is the name of your organization?

    • What is the name of your City or Locality?

    • What is the name of your State or Province?

    • What is the two-letter country code for this unit?

      A summary is displayed showing the information you entered, as shown in the example below:

      Is CN=IPAddressProvided, OU=OrganizationalUnit, O=Organization, L=Locality, ST=State, C=CountryCode correct?

    • Enter Yes.

      The keystore keystore.jks file is created.

To configure the new self-signed certificate in the WebLogic Administration Console:

  1. Log in to the WebLogic server Administration Console using the Administrator credentials.

    The Home page appears.

  2. Click Lock & Edit.

  3. In the Domain Structure tree, expand Environment and then click Servers.

    The Summary of Servers page appears.

  4. In the Servers table, click AdminServer.

    The Settings for AdminServer page appears.

    The General tab is displayed by default.

  5. Select SSL Listen Port Enabled.

  6. In the SSL Listen Port field, update the value as appropriate.

  7. Click Save.

  8. Click the Keystores tab.

  9. Click Change and then from the Keystores list, select Custom Identity and Java Standard Trust.

  10. Do the following:

    • In the Custom Identity Keystore field, enter the full path to your JKS file as follows:

      WL_Home/server/lib/keystore.jks

    • In the Custom Identity Keystore Type field, enter jks.

    • In the Custom Identity Keystore Passphrase field, enter the keystore password.

    • Leave the Java standard trust key as the default.

    • Click Save.

  11. Click the SSL tab.

  12. Do the following:

    • From the Identity and Trust Locations list, select Keystores.

    • In the Private Key Alias field, enter the alias name.

    • In the Private Key Passphrase field, enter the private key password.

    • Click Save.

    • Click Advanced.

    • From the Two Way Client Cert Behavior list, select Client Certs Requested But Not Enforced.

    • Click Save.

  13. Click Activate Changes in the Change Center in the left pane.

    For more information on SSL configuration, see the WebLogic Server Administration Console Help.

    Note:

    To replace a self-signed certificate with a production-quality certificate, or to import a trusted CA certificate into a keystore, run the following command:

    keytool -import -alias aliasValue -file cert.pem -keypass keypassword -keystore keystore.jks -storepass keystorepass

    Note:

    If you import a trusted CA certificate, no existing entry for alias should be in the keystore.

    While accessing the application, the browser asks to install the certificate. Install the certificate in Trusted Root Certification Authorities.

Resetting/Changing the WebLogic Server's Database Connections

You may need to reset the WebLogic server's database connections when the following occurs:

  • The database goes down while UIM is active

  • UIM is started when the database is down

You reset the database connections by resetting the following JDBC data sources in the WebLogic server administration console: InventoryDataSource, InventoryTxDataSource, CMDSInventoryPersistentDS, InventoryMapDataSource, InvJMSPersistentDS, mds-commsRepository, opss-audit-DBDS, opss-audit-viewDS, opss-data-source, LocalSvcTblDataSource, and UIMAdapterDS.

To reset/change the database connections:

  1. Log in to the WebLogic server administration console at:

    http://ServerName:PortNumber/console

  2. Click Lock & Edit.

  3. In the Domain Structure tree, expand Services and then click Data Sources.

    The Summary of JDBC Data Sources page appears.

  4. Click InventoryDataSource.

    The Settings for InventoryDataSource page appears.

  5. Click the Control tab.

  6. Select the check box next to the data source instance that you want to reset.

  7. Click Reset.

  8. Click Yes.

    Note:

    If you want to change the database connection, perform steps 9 and 10.

  9. Click the Connection Pool tab.

  10. Modify the following fields to match your environment:

    • URL

    • Properties

    • Password

    • Confirm Password

  11. Repeat steps 4 through 10 for all the remaining data sources.

Setting the Default Telephone Number Edit Mask

The default telephone number edit mask defines the length format for telephone numbers entered into the UIM system. This value is used when a Telephone Number specification does not specify a ruleset extension point to customize the edit mask. See UIM Developer's Guide for more information on customizing the telephone number edit mask.

The initial default value of ########## (ten digits) is specified in the numbers.properties file, which you can modify.

When a custom ruleset or modified properties file doe not specify a default edit mask, UIM uses the initial default edit mask from the number.properties file.

To modify the default telephone number edit mask:

  1. Open UIM_Home/config/resources/logging/number.properties.

  2. Find the following entry:

    number.defaultEditMask=##########

  3. Change ########## to the desired length.

    For example, enter ############ to set the telephone number length to 12 digits. Each pound sign symbol (#) represents one digit.

Setting the Default Place Type

Place entities can be of several different types:

  • Location

  • Address

  • Address Range

  • Site

You can specify the default type by setting the value of the place.defaultPlaceType property in the place.properties file. This default value determines which type appears first in the Place Type list when you create a Place entity. By default, the value is set to Address.

To modify the default place type:

  1. Open UIM_Home/config/resources/logging/place.properties.

  2. Find the following entry:

    place.defaultPlaceType

  3. Change the value to the desired place type.

Load Balancing a Clustered Server

The two methods for load balancing a clustered server include a hardware-based load balancer and a software-based proxy server.

Note:

Oracle recommends using the hardware-based load balancer in production environments. Use either the hardware-based load balancer or the software-based proxy server in test or development environments.

Depending on the type of environment being deployed, do one of the following:

  • Configure the load balancer

  • Configure the proxy server

Configuring the Load Balancer

The requirement for the load balancer service is server affinity, also known as a sticky session. For example, a user starts a new session and it is load balanced to server #2. The subsequent HTTP requests in this session is always routed to server #2 until server #2 fails.

For information on load balancer requirements, refer to the WebLogic document: Using WebLogic Server Clusters (see Load Balancing in a Cluster).

F5 BIG-IP Configuration

For information about deploying the BIG-IP system with Oracle WebLogic Server, refer to the deployment guide at the F5 Networks Web site.

Configuring the Proxy Server

There are several options available for the proxy server, refer to Oracle WebLogic Server documentation for information on configuring the various proxy server options.

Configuring Topology Updates

To configure topology updates, see the following topics:

Configuring Asynchronous Topology Updates

By default, the UIM topology is updated synchronously with business model changes. The topology and the business model are updated in single transaction to reflect new, changed, and deleted entities. See UIM Concepts and UIM Developer's Guide for more information about topology.

You can configure UIM to update the topology asynchronously from business model updates. In this scenario, topology updates are performed in a separate transaction from business model updates. Configuring UIM to update the topology asynchronously can improve performance by reducing the system overhead associated with business model changes.

To configure UIM for asynchronous topology updates:

  1. Stop the UIM application server.

  2. Open the UIM_home/config/topologyProcess.properties file.

  3. Change the value of the processSynchronous entry to false.

  4. Save the file.

Turning Off Topology Updates

If you use topology infrequently or want to optimize UIM performance, you can turn off topology updates entirely. If updates are turned off and you want to use topology-related features, such as path analysis, you must first rebuild the topology. See "Rebuilding Topology".

To turn off topology updates:

  1. Stop the UIM application server.

  2. Open the UIM_home/config/topologyProcess.properties file.

  3. Change the value of the disableTopology entry to true.

  4. Save the file.

Rebuilding Topology

If you have turned off topology updates, you must rebuild the topology before you can use any topology-related features, such as path analysis or visualization. You should schedule this as a maintenance task during a time when no changes to the inventory will take place.

Caution:

When you rebuild, the old topology is deleted and a new one created. You should back up your old topology to ensure that you can return to it if necessary.

If UIM is installed in a cluster environment, only one instance can be rebuilt at a time. When a rebuild is in progress on one instance, the rebuild operation is disabled for other instances.

You should schedule topology rebuilds during times when no changes to the inventory will take place.

To rebuild the UIM topology:

  1. Log in to UIM.

  2. In the Tasks panel, click Rebuild Topology.

    The Rebuild Topology page appears.

  3. Click the Rebuild Topology button.

    The topology begins to be rebuilt. You can refresh the page to see status updates. When the process is complete, the page reverts to its original appearance and the Rebuild Topology button becomes available.

    You can check on the success of the rebuild by consulting the log at:

    WLServer_Home/user_projects/domains/Domain_Home/uim/logs/****Server_uim_rebuild.log

Configuring a Geocode Service

To configure a geocode service, see the following topics:

About Oracle eLocation

UIM uses Oracle eLocation as the default geocode service, but you may opt to use a different geocode service. This section describes Oracle eLocation, and provides information about configuring UIM to use a different geocode service.

UIM interfaces with Oracle eLocation through an XML API request that is sent when you click Validate Address from within UIM when creating a location. Oracle eLocation returns an XML API response to UIM, indicating whether or not the address sent in the request was a valid address. For valid addresses, the response includes a geocode, which is a specific latitude and longitude that represents the location.

Using a Geocode Service other than Oracle eLocation

Upon installation, UIM is configured to use the Oracle eLocation geocode service. However, you can configure UIM to use a geocode service other than the default Oracle eLocation. For example, you may opt to use a third-party geocode service, or create a custom geocode service to use.

UIM is tightly coupled with Oracle eLocation. As a result, when you click Validate Address from within UIM when creating a location, UIM creates an XML request based on what the Oracle eLocation geocode service is expecting. Similarly, UIM expects an XML response based on what the Oracle eLocation geocode service returns. You can find detailed information about the eLocation XML request and response structures at the following Web site:

http://elocation.oracle.com/geocoder/concept.html

Using a Third-Party Geocode Service

To use a third-party geocode service, you can host your own eLocation service that:

  • Handles the input XML request from UIM

  • Creates a new XML request based on what the third-party geocode service is expecting

  • Maps the data from the input XML request to the new XML request

  • Sends the new XML request to the third-party geocode service

  • Handles the response from the third-party geocode service

  • Creates a new XML response based on what UIM is expecting

  • Maps the data from the XML response to the new XML response

  • Sends the new XML response to UIM

In this scenario, the eLocation service is just a middle tier that performs XML mapping, allowing UIM and the third-party geocode service to communicate.

For information on how to host your own eLocation service, see Oracle Spatial eLocation Quick Start Guide:

http://download.oracle.com/otndocs/products/spatial/pdf/elocation_quickstart.pdf

Using a Custom Geocode Service

To use a custom geocode service, you can host your own eLocation service that:

  • Handles the input XML request from UIM

  • Performs custom address analysis based on input XML request data to determine the geocode

  • Creates an XML response based on what UIM is expecting

  • Sends the new XML response to UIM

In this scenario, the eLocation service hosts the custom geocode service.

For information on how to host your own eLocation service, including how to develop the custom geocode service that runs on your eLocation service, see Oracle Spatial eLocation Quick Start Guide:

http://download.oracle.com/otndocs/products/spatial/pdf/elocation_quickstart.pdf

Configuring UIM

After your eLocation service is up and running, you must configure the UIM_Home/config/system-config.properties file to point to your eLocation service. This file defines several properties related to the geocode service that UIM is using, such as host name, user ID, password, and so forth. See "Setting System Properties" for more information.

Purging UIM Services

This section describes how to perform a service purge for UIM. The service purge tool is available as part of the ora_uim_dbtools.jar file, located in the UIM_Home/util/ folder.

WARNING:

Performing a service purge deletes database records permanently. You must back up the database before performing any service purge options.

Scenarios

The service purge functionality purges services that meet the following criteria:

  • Cancelled services without In Service child services.

  • Disconnected services without In Service child services.

  • Cancelled services with cancelled child services.

  • Disconnected services with disconnected child services.

  • Cancelled services with disconnected child services.

  • Disconnected services with cancelled child services.

  • In Service services with Cancelled configuration versions.

  • Disconnected or Cancelled services without configuration items in the Transitional or Disconnected status for the following configuration item entities:

    • Telephone Number

    • IPv4Subnet

    • IPv6Subnet

    • IPv4Address

    • IPv6Address

Prerequisites

Before you perform a UIM service purge do the following:

  • Gather the statistics of the schema before and after running purge scripts. You use the following command to retrieve the statistics:

    EXEC DBMS_STATS.gather_schema_stats(uim_db_schema_username);

  • Provide admin privileges to the database user.

  • Back up the database before executing purge scripts. The purge scripts delete the records matching specified criteria permanently.

  • Ensure you have the correct version of Java installed. See UIM Installation Guide for software version requirements.

Configuring the UIM Service Purge Environment

You set up the service purge tool environment by performing the following tasks:

  1. Extract Service Purge Files from ora_uim_dbtools.jar

  2. Set Up the Service Purge Tool Script

  3. Set Up Service Purge Tables and Procedures

Extract Service Purge Files from ora_uim_dbtools.jar

Extract the ora_uim_dbtools.jar from the UIM Installer. Use the following command to extract contents of the JAR file:

jar -xvf ora_uim_dbtools.jar

The JAR file contains SQL scripts and also command files for the service purge tool. Save the path of these extracted JAR files as the dbtools_extracted_dir path value which is referenced in this section for the additional steps.

Set Up the Service Purge Tool Script

After the files are extracted, edit the servicePurge.sh file in the root directory, and set the following variables:

  1. Set JAVA_HOME to the directory of your JDK.

  2. Modify these parameters to point to the database:

    • DB_HOSTNAME - host name of the database

    • DB_PORT - database port

    • DB_SERVICE_NAME - database service name

  3. Add the folder path of the extracted JAR files to existing 'sqlFileLocation' variable and substitute the path for the <add-extracted-path> string value placeholder. This path is the same as the dbtools_extracted_dir path.

Set Up Service Purge Tables and Procedures

Before you use the service purge tool, you must run a SQL script to set up the required new database tables and procedures. Run ServicePurgeScripts.sql on the database. This SQL script is located in the ora_uim_dbtools.jar/sqlscripts directory. To run this SQL script, use SQL Plus and perform the following steps:

  1. Log in to SQL Plus.

  2. Execute following command:

    @dbtools_extracted_dir/sqlscripts/ServicePurgeScripts.sql

    where dbtools_extracted_dir is the directory for the extracted contents of the ora_uim_dbtools.jar file.

You can run this SQL script more than once if you want to drop and recreate all the service purge audit and error log tables.

Database Tables

The ServicePurgeScripts.sql script creates the following tables to capture the service purge audit and error details:

  • Purge_Error_Log

  • Purge_Audit

  • Service_Purge_Helper (Internal only)

  • Purge_Log (Internal only)

Purge_Error_Log

This table stores error or failure information from the purge. The service purge can create errors. Errors are created if any invalid data is detected and these issues are recorded in this table. Table 4-2 shows the columns in the Purge_Error_Log table:

Table 4-2 Purge_Error_Log Columns

Column Name Description

ID

ID for the table entry and primary key.

ERROR_CODE

Error code for the entry which can be a SQL error code.

ERROR_MESSAGE

Error message text which can be a SQL error message.

REPORTED_DATE

Time when the error is recorded or persisted in the table.

Purge_Audit

This table records the service purge reporting information. Table 4-3 shows the columns in the Purge_Audit table:

Table 4-3 Purge_Audit Columns

Column Name Description

JOBID

For every purge, a new record is created in this table. This is primary key for the table.

PURGETYPE

Defaults to SERVICE.

STARTDATE

The date and time when the purge is initiated. In the case of a scheduled purge, the value is set to the scheduled time and once the process starts the process updates this value with the time when the process is initiated.

ENDDATE

The date and time when the purge process is completed or cancelled.

CRITERIA

The criteria string that is generated by the API using criteria specified by the caller. You can specify information about parallel processes and the batch size. For example:

(ADMINSTATE LIKE 'CANCELLED') AND LASTMODIFIEDDATE <= to_date('07/30/2014:23:59:59','mm/dd/yyyy:hh24:mi:ss'):10:1000

In this example the first portion is the search criteria followed by the number of parallel processes 10 and batch size 1000.

STATUS

The status of the service purge. Has one of the following values:

  • INPROGRESS: The purge process has started.

  • SCHEDULED: A purge process is scheduled.

    Note: When a scheduled purge starts, the STATUS and STARTDATE columns are updated to INPROGRESS and the scheduled time.

  • CANCELLED: The purge process has been cancelled.

  • FAILED: The purge process has failed due to errors when one or more services were not processed. One of the reasons for an error may be inconsistent data values.

PARENTJOB

The parent JOBID record for each new child purge record. Having a parent and child job exists when a purge is suspended and later resumed.

For example, if a purge is started and later suspended, there is a record for this job with a status of SUSPENDED. When the purge is resumed, the original record is updated with a status of COMPLETED. A new record is created which refers to the completed parent job record in the JOBID column. This provides you with a history of the purge requests.

USERNAME

The database schema user name that performs the purge.

REPORTNAME

The report name generated for the service purge.

Operations

The service purge functionality can be requested with the following options:

Report

You use the report option to run a sample version of the purge, but this option does not delete services. You specify criteria and the tool determines the number of records that are affected. These records are later deleted with the execute option. With this number, you can then estimate the amount of freed disk space. This option provides information, but does not actually purge or delete any records.

Use the following arguments with the report option request:

  • -status: This argument is optional. Use the status argument to specify an additional inventory status of services. By default, the service purge includes services in a cancelled status. Currently, the status of ”disconnected” is the only valid status for this argument. When you include this argument, all services with a disconnected or a cancelled inventory status are included in the service purge. In addition, all service configuration versions in a cancelled status are included in the purge. The following is an example using this argument:

    ./servicePurge.sh report -status disconnected -ed 02/21/2012

    In this example, all services with an inventory status of disconnected or cancelled are in the report output, and also all service configuration versions in a cancelled status. See the examples in this section for more information on the results of using this status argument.

  • -ed: This argument is mandatory. Use the ed argument to specify an end date. The service purge tool only considers services with a ”last modified date” on or before this end date for purging. You must specify the date with the following format: MM/DD/YYYY. For example:

    ./servicePurge.sh report -ed 02/21/2012

  • -sd: This argument is optional. Use the sd argument to specify the start date. The service purge tool only considers services with a ”last modified date” on or after this start date for purging. You must specify the date with the following format: MM/DD/YYYY. For example:

    ./servicePurge.sh report -ed 02/21/2012 -sd 02/21/2010

  • -icsc: This argument is optional. Use the icsc argument to ignore cancelled service configurations. Cancelled service configuration versions of active services are not purged. For example:

    ./servicePurge.sh report -ed 02/21/2012 -icsc

  • -sid: This argument is optional. Use the sid argument to use service entity identifiers or IDs as criteria for purging. You specify multiple values delimited by a comma for this argument. The service purge only affects the cancelled services in the specified entity identifier list. For example:

    ./servicePurge.sh report -ed 02/21/2012 -sid 575001,525004

Execute

WARNING:

Performing a service purge deletes database records permanently. You must back up the database before performing any service purge operations.

The execute option enables you to purge cancelled services and optionally purge disconnected services. The purge deletes rows from several tables using the specified criteria. The execute option always creates a report. You are prompted for a confirmation if the purge end date specified is within one year from the current date.

You cannot run more than one execute operation at a time. If you need to start a new execute operation, then the old execute operation must be cancelled or completed. In the case of a suspended purge operation, no new execute operations can be initiated until the suspended operation is also cancelled or completed.

The following is the list of tables which are affected by the purge request:

  • Service

  • Service_Char

  • Party_ServiceRel

  • Place_ServiceRel

  • ServiceAssignment

  • ServiceConsumer

  • ServiceReservation

  • ServiceCondition

  • ServiceConfigurationVersion

  • BusinessInteraction

  • ConfigurationInput

  • TopologyProfile

  • TopologyProfileEdge

  • TopologyProfileNode

  • ServiceConfigurationItem

  • ServiceConfigurationItem_Char

  • BusinessInteractionItem

  • EntityConsumer

  • EntityAssignment

  • EntityConfigRef

    where Entity is the entity type of the related resource. In the list of affected tables, the EntityConsumer, EntityAssignment, and EntityConfigRef tables are applicable to the following entity resources, which can be consumed by a Service:

  • Custom Network Address

  • Custom Object

  • Device Interface

  • Equipment

  • Equipment Holder

  • Geographic Location

  • Geographic Site

  • Logical Device Account

  • Logical Device

  • Network

  • Physical Connector

  • Physical Device

  • Physical Port

  • Pipe

  • Service

  • Telephone Number

When an execute purge operation is performed, a new record with a status of INPROGRESS is created in the Purge_Audit table. When the execute operation completes successfully, the status is updated to COMPLETED.

The following arguments can be used during the execute operation:

  • -status: This argument is optional. Use the status argument to specify an additional inventory status of services. By default, the service purge includes services in a cancelled status. Currently, the status of ”disconnected” is the only valid status for this argument. When you include this argument, all services with a disconnected or a cancelled inventory status are included in the service purge. In addition, all service configuration versions in a cancelled status are included in the purge. The following is an example using this argument:

    ./servicePurge.sh execute -status disconnected -ed 02/21/2012

    In this example, all services with an inventory status of disconnected or cancelled are purged, and also all service configuration versions in a cancelled status. See Example 4-1, "Execute Operation Purge Example" and Example 4-2, "Execute Operation Purge Example with a Status Argument" for more information on the results of using this status argument.

  • -ed: This argument is mandatory. Use the ed argument to specify an end date. The service purge tool only considers services with a ”last modified date” on or before this end date for purging. You must specify the date with the following format: MM/DD/YYYY. For example:

    ./servicePurge.sh execute -ed 02/21/2012

  • -sd: This argument is optional. Use the sd argument to specify the start date. The service purge tool only considers services with a ”last modified date” on or after this start date for purging. You must specify the date with the following format: MM/DD/YYYY. For example:

    ./servicePurge.sh execute -ed 02/21/2012 -sd 02/21/2010

  • -icsc: This argument is optional. Use the icsc argument to ignore cancelled service configurations. Cancelled service configuration versions of active services are not purged. For example:

    ./servicePurge.sh execute -ed 02/21/2012 -icsc

  • -force: This argument is optional. Use the force argument to avoid the service purge operation prompting you for confirmations. For example:

    ./servicePurge.sh execute -ed 02/21/2012 -force

  • -s: This argument is optional. Use the s argument to specify a start date and time for the purge to run. You must specify the date with a format of MM/DD/YYYY:hh:mm:ss. For example:

    ./servicePurge.sh execute -ed 02/21/2012 -s 06/26/2012:19:30:00

  • -c: This argument is optional. Use the c argument to set the commit size for the purge. By default, the commit size is set to 1000. The maximum value is 10000. If you specify a value greater than 10000, the purge ignores the argument value and uses the maximum value of 10000. For example:

    ./servicePurge.sh execute -ed 02/21/2012 -c 200

  • -t: This argument is optional. Use the t argument to set the number of parallel processes allowed. By default, the number of parallel processes is set to 10. The maximum value you can specify is 100. If you specify a value greater than 100, the purge ignores the argument value and uses the maximum value of 100. For example:

    ./servicePurge.sh execute -ed 02/21/2012 -t 15

  • -sid: This argument is optional. Use the sid argument to use service entity identifiers or IDs as criteria for purging. You specify multiple values delimited by a comma for this argument. The service purge only affects the cancelled services in the specified entity identifier list. For example:

    ./servicePurge.sh execute -ed 02/21/2012 -sid 575001,525004

Example 4-1 shows an execute command with end date and start date arguments.

Example 4-1 Execute Operation Purge Example

./servicePurge.sh execute -sd 02/21/2014 -ed 02/21/2016

Table 4-4 shows the service and service configuration version statuses with the results of the purge execute command in Example 4-1.

Table 4-4 Results for the Example Service Purge

Service Status Service Configuration Version Status Resulting Entities Purged

Cancel Pending Disconnect

Cancelled

Service Configuration Versions

Cancelled

Cancelled

Services

Service Configuration Versions

Disconnected

Cancelled

Service Configuration Versions

In-Service

Cancelled

Service Configuration Versions

Pending Disconnect

Cancelled

Service Configuration Versions

Suspended

Cancelled

Service Configuration Versions

Example 4-2 shows an execute command with end date, start date, and status arguments.

Example 4-2 Execute Operation Purge Example with a Status Argument

./servicePurge.sh execute -sd 02/21/2014 -ed 02/21/2016 -status DISCONNECTED

Table 4-5 shows the service and service configuration version statuses with the results of the purge execute command in Example 4-2.

Table 4-5 Results for the Example Service Purge with Disconnect Status

Service Status Service Configuration Version Status Resulting Entities Purged

Cancel Pending Disconnect

Cancelled

Service Configuration Versions

Cancelled

Cancelled

Services

Service Configuration Versions

Disconnected

Cancelled

Services

Service Configuration Versions

In-Service

Cancelled

Service Configuration Versions

Pending Disconnect

Cancelled

Service Configuration Versions

Suspended

Cancelled

Service Configuration Versions

Note:

The execute operation excludes disconnected services that contain any aging Telephone Number resources. See UIM Concepts for more information on Telephone Number Aging.

The execute operation deletes only entity assignment information for resources. It does not delete the actual resources that were consumed or referenced by the service.

The execute operation does not affect services in Pending or Pending Cancel status because cancelled service configuration versions do not exist for those service statuses.

Status

The status option shows information for in-progress and suspended purge processes. It also provides the following information related to the purge:

  • Active service purge information.

  • Number of services purged.

  • All the jobs related to service purge.

  • Report file name which is generated while services are purged.

Suspend

The suspend option suspends the service purge and allows active parallel processes to continue to run and complete. No new processes can be created, however. Before suspending the active service purge, the service purge provides the following information:

  • Active service purge information.

  • Number of services purged.

  • All the jobs related to service purge.

  • Report file name which is generated while services are purged.

Note:

One purge operation can create multiple software processes to perform the requested purge.

A suspended operation can be cancelled or resumed, but once the purge is suspended, no new purge operations can be initiated. After an execute operation is suspended, the Purge_Audit STATUS record value is updated to COMPLETED and a new record is created with a status of SUSPENDED.

Please note that there are processes which are still in RUNNING status when a purge operation is suspended. After these processes complete execution, the processes update to DISABLED. When all the processes have changed to DISABLED status, no new processes are created.

Resume

The resume option restarts the service purge operation using the specified arguments. In this case, the Purge_Audit STATUS value is updated to INPROGRESS for the record that was suspended. The following arguments can be specified when resuming a purge operation:

  • -s: This argument is optional. Use the s argument to specify a start date and time for the purge to run. You must specify the date with a format of MM/DD/YYYY:hh:mm:ss. For example:

    ./servicePurge.sh resume -s 06/26/2014:19:30:00

  • -c: This argument is optional. Use the c argument to set the commit size for the purge. By default, the commit size is set to 1000. The maximum value is 10000. If you specify a value greater than 10000, the purge ignores the argument value and uses the maximum value of 10000. For example:

    ./servicePurge.sh resume -c 200

  • -t: This argument is optional. Use the t argument to set the number of parallel processes allowed. By default, the number of parallel processes is set to 10. The maximum value you can specify is 100. If you specify a value greater than 100, the purge ignores the argument value and uses the maximum value of 100. For example:

    ./servicePurge.sh resume -t 15

Cancel

The cancel option terminates all service purge processes with a status of INPROGRESS or SUSPENDED. It also provides the following information related to purge process, before requesting confirmation:

  • Active service purge operation.

  • Number of services purged.

  • All the jobs related to service purge.

  • Report file name which is generated while services are purged.

After this information is provided, you must confirm the cancellation of in-progress or suspended operations. When the service purge is cancelled, the Purge_Audit STATUS value is updated to CANCELLED for records with an INPROGRESS or SUSPENDED status.

Configuring Email Addresses and User Data

To support the message notification functionality, you maintain users and user groups along with their contact information. You manage this information through the embedded Lightweight Directory Access Protocol (LDAP) server within Oracle Weblogic Server or optionally through another LDAP-compliant product. For information about managing the embedded LDAP server within Oracle Weblogic Server, see the following web site:

http://docs.oracle.com/middleware/12212/wls/SECMG/ldap.htm#SECMG327

Alternatively, there are additional products such as Oracle Identity Management - Oracle Internet Directory that may be chosen depending on the required scale of the installation. For more information about message notification functionality, see UIM Developer's Guide.