8 Administering a UIM Cloud Native Deployment

Perform UIM cloud native deployment administration tasks.

This chapter provides information about UIM cloud native deployment administration tasks.

Overview of UIM Cloud Native Deployment Administration Tasks

UIM cloud native deployment administration tasks include day-to-day tasks of maintaining and managing UIM cloud native instances and its users. The tasks also include managing UIM and other related components in your cloud native environment.

You perform the following tasks as an administrator:

Starting, Stopping, and Restarting a UIM Cloud Native Instance

The UIM cloud native toolkit provides scripts for managing your UIM cloud native instances.

  • To create or start a UIM cloud native instance, run the following script:
    $COMMON_CNTK/scripts/create-applications.sh -i instance -p project -s $SPEC_PATH -a uim

    Note:

    Run this command only when an instance is completely down. For details about verifying if the instance started, see "Verifying the UIM Server Started".
  • To stop all the UIM instances, including the administrator instance, run the following command:
    $COMMON_CNTK/scripts/delete-applications.sh -i instance -p project -s $SPEC_PATH -a uim
  • To restart the UIM managed server, run the following command:
    $COMMON_CNTK/scripts/restart-applications.sh -i instance -p project -s $SPEC_PATH -a uim -r ms

    Note:

    For details about verifying if the instance started, see "Verifying the UIM Server Started".
  • To restart the UIM administration server, run the following command:
    $COMMON_CNTK/scripts/restart-applications.sh -i instance -p project -s $SPEC_PATH -a uim -r admin
  • To restart all the servers (UIM managed servers and the administration server), run the following command:
    $COMMON_CNTK/scripts/restart-applications.sh -i instance -p project -s $SPEC_PATH -a uim -r all

Upgrading Your UIM Cloud Native Instance

You upgrade your UIM cloud native instance in the following scenarios:

  • To scale down. The instances in the environment would be reduced according to the clusterSize value specified in the <shape>uim.yaml file.
  • To scale up. The instances in the environment would be increased according to the clusterSize value specified in the <shape>uim.yaml file.
  • To upgrade the UIM Docker image to a newer image.
  • To install updates to system configuration properties or log_level changes.
  • To use WDT extensions.
To upgrade a UIM cloud native instance, run the following command:
$COMMON_CNTK/scripts/upgrade-application.sh -i instance -p project -s $SPEC_PATH -a uim

For details about upgrading your cloud native environment, see "Upgrading the UIM Cloud Native Environment" in UIM Cloud Native Deployment Guide.

Securing Your UIM Cloud Native Deployment

You manage most aspects of UIM security externally rather than in the application itself. For detailed information about how you perform application security tasks in external systems, see the corresponding product documentation for these systems. For information about UIM security, see "UIM Security Overview".

As part of authenticating users for access to a UIM cloud native deployment, you do the following configuration tasks:

Setting Session Timeout for UIM Cloud Native Instances

To set session timeout for your cloud native instances, you add the following session timeout details in the inventory-clusterPlan.xml file.
// Add below in variable-definition block, change session time out value to desired number of seconds.
<variable>
   <name>SessionDescriptor_TimeoutSecs_16315175580860</name>
   <value>1800</value>
 </variable>
 
// Add below in inventory.ear module-override block
 <module-descriptor external="false">
   <root-element>weblogic-application</root-element>
   <uri>META-INF/weblogic-application.xml</uri>
   <variable-assignment>
     <name>SessionDescriptor_TimeoutSecs_16315175580860</name>
     <xpath>/weblogic-application/session-descriptor/timeout-secs</xpath>
   </variable-assignment>
 </module-descriptor>

For more details about updating the inventory-clusterPlan.xml file, see "Customizing Images" in UIM Cloud Native Deployment Guide.

Authenticating Web Services for a UIM Cloud Native Deployment

To secure custom web services, update your deployment plan with the required policies. You can use the security policy that is available with the Auth.xml UIM instance file, the security policy that is available with the SampleAuth.xml Reference Web Service ZIP file, or create your own security policy file. Custom policies are generally available in the custom webservice war/WEB-INF/policies folder. For more details about authentication, see "Authentication".

The following example shows an update to the inventory-clusterPlan.xml file with default Auth.xml policy:
<module-override>
  <module-name>ReferenceUim.war</module-name>
  <module-type>war</module-type>
  <module-descriptor external="false">
    <root-element>weblogic-web-app</root-element>
    <uri>WEB-INF/weblogic.xml</uri>
  </module-descriptor>
  <module-descriptor external="false">
    <root-element>web-app</root-element>
    <uri>WEB-INF/web.xml</uri>
  </module-descriptor>
  <module-descriptor external="false">
    <root-element>weblogic-webservices</root-element>
    <uri>WEB-INF/weblogic-webservices.xml</uri>
  </module-descriptor>
  <module-descriptor external="false">
    <root-element>webservices</root-element>
   <uri>WEB-INF/webservices.xml</uri>
  </module-descriptor>
  <module-descriptor external="false">
    <root-element>webservice-policy-ref</root-element>
    <uri>WEB-INF/weblogic-webservices-policy.xml</uri>
    <variable-assignment>
      <name>WsPolicy_policy:Auth.xml_Direction_13075993400140</name>
      <xpath>/webservice-policy-ref/port-policy/[port-name="UIMReferenceUimHTTPPort"]/ws-policy/[uri="policy:Auth.xml"]/direction</xpath>
    </variable-assignment>
    <variable-assignment>
      <name>WsPolicy_policy:Auth.xml_Direction_13075993400140</name>
      <xpath>/webservice-policy-ref/port-policy/[port-name="UIMReferenceUimJMSPort"]/ws-policy/[uri="policy:Auth.xml"]/direction</xpath>
    </variable-assignment>
  </module-descriptor>
</module-override>

Authorization in UIM Cloud Native Deployment

Authorization can be achieved using Application roles and Application polices. All the operations performed using Oracle Enterprise Manager Console for managing roles and policies are persisted in the database. A UIM cloud native deployment does not require specific actions to be performed for authorization. See "Authorization" for more details.

Monitoring and Managing a UIM Cloud Native Deployment

You perform monitoring and managing activities after deploying or upgrading your UIM cloud native instance.

The tasks you perform include the following:

For information about the following, see "Overview of the UIM Cloud Native Deployment" in UIM Cloud Native Deployment Guide:
  • Managing UIM cloud native metrics using Prometheus and Grafana
  • Managing WebLogic Monitoring Exporter metrics

Setting the Database Row Prefetch Size in a Cloud Native Deployment

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

To set the database row prefetch size:
  1. Update the value for the rowPrefetchSize parameter in the respective <shape>/uim.yaml file.
    jdbc:
  rowPrefetchSize: 50
  2. Run the following command: 
    $COMMON_CNTK/scripts/upgrade-applications.sh -i instance -p project -s $SPEC_PATH -a uim

Modifying the Default File Encoding for a Cloud Native Deployment

To modify the default file encoding:
  1. Update the value for the java_options parameter in the app-uim.yaml file.
    managedServers:
  project:
    #JAVA_OPTIONS for all managed servers at project level
    java_options: "-Dfile.encoding=UTF-8"
  2. Run the following command:
    $COMMON_CNTK/scripts/upgrade-applications.sh -i instance -p project -s $SPEC_PATH -a uim

Modifying the Time Zone for a Cloud Native Deployment

To modify the time zone:
  1. Update the value for the java_options parameter in the app-uim.yaml file: 
    managedServers:
  project:
    #JAVA_OPTIONS for all managed servers at project level
    java_options: "-Duser.timezone=Asia/Shanghai"
  2. Run the following command:
    $COMMON_CNTK/scripts/upgrade-applications.sh -i instance -p project -s $SPEC_PATH -a uim

For more details about modifying the time zone, see "Modifying the Time Zone".

Configuring Timers in a Cloud Native Deployment

To configure timers:
  1. Add the timer property to the $SPEC_PATH/project/instance/config/uim/system-config/custom-config.properties file.
  2. Run the following command: 
    $COMMON_CNTK/scripts/restart-applications.sh -i instance -p project -s $SPEC_PATH -a uim -r all

See "Configuring Your Server's Timers" for more details.

Controlling Application Metrics

You use the custom-config.properties file to control application metrics.

To control application metrics:
  1. Add the property with the desired value in the $SPEC_PATH/project/instance/config/uim/system-config/custom-config.properties file.
  2. Do the following:
    • To update sfws and service metrics property values, run the following command: 
      $COMMON_CNTK/scripts/upgrade-applications.sh -i instance -p project -s $SPEC_PATH -a uim
    • To update jvm metrics property value, run the following command:
      $COMMON_CNTK/scripts/restart-applications.sh -i instance -p project -s $SPEC_PATH -a uim -r all
See "Setting System Properties" for details about the properties you can configure.

Configuring Exception-Type-To-Error-Code Mappings in a Cloud Native Deployment

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.

To configure exception-type-to-error-code mappings:
  1. Map the error codes to exception types by using the ora_uim_localization_reference cartridge in the model\content\product_home\config\resources\logging\exception.properties file. For more information, see the comments in the exception.properties file.
  2. Build the UIM Docker image. See the section about "Customizing Images" in UIM Cloud Native Deployment Guide for more details.
  3. Run the following command: 
    $COMMON_CNTK/scripts/upgrade-applications.sh -i instance -p project -s $SPEC_PATH -a uim

Localizing UIM Error Messages

You can localize UIM error messages and items by modifying the properties files in the ora_uim_localization_reference cartridge located in the model\content\product_home\config\resources\logging directory. See the table in "Localizing UIM Error Messages" for details about each property's file name, error ID range, and the error messages or items it localizes.

After modifying the properties files, build the UIM Docker image and run the following command: 
$COMMON_CNTK/scripts/upgrade-applications.sh -i instance -p project -s $SPEC_PATH -a uim

Localizing the UIM Server and the Application Server

By default, the UIM server and the 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 "Overview" in UIM Developer's Guide.

Configuring SSL Policy for a UIM Cloud Native Deployment

This section describes how to configure SSL in a UIM cloud native deployment. In a UIM cloud native deployment, you enable SSL in Ingress Controller. The following procedures provide information about configuring SSL with Nginx Ingress Controller.

Enabling SSL

To enable SSL incoming on UIM, see "Setting Up UIM Cloud Native for Incoming Access" in UIM Cloud Native Deployment Guide.

Configuring Incoming HTTPS Requests: Configure the external web clients that connect to UIM cloud native to accept the certificates from UIM cloud native. The clients then connect using the HTTPS endpoint and port 30543.

Configuring Incoming JMS Requests: For external servers that are connected to UIM cloud native through SAF, copy the certificate for the t3 endpoint to the host where the external domain is running.

If your external WebLogic configuration uses Custom Identity and Java Standard Trust, to upload the certificate to the Java Standard Trust, run the following command:

/keytool -importcert -v -trustcacerts -alias alias -file /path_to_copied_t3_certificate/commoncert.pem -keystore /path_to_jdk/jre/lib/security/cacerts -storepass default_password

If, however, you are using a CustomTrust, then upload the certificate into the custom trust keystore. The keytool is found in the bin directory of your jdk installation. The alias should uniquely describe the environment where this certificate is from.

Configuring Custom Trust Store

You should load the UIM cloud native domain with the required certificates into the trust store to communicate to an SSL configured external system. You should also configure custom trust store.

To configure custom trust store for the UIM cloud native domain:

  1. Load the certificate from your remote server (external system) into a trust store and make it available to the UIM cloud native instance. Use the Java keytool to create a jks file (truststore) that holds the certificate from your SSL server:
    keytool -importcert -v -alias alias -file /path-to/certificate.cer -keystore /path-to/truststore.jks -storepass password

    Note:

    Repeat this step to add as many trusted certificates as required.
  2. Create a Kubernetes secret to hold the truststore file and the passphrase by running the following command. For more information, see "Common TrustStore Secret" in Unified Inventory and Topology Deployment Guide.
    $COMMON_CNTK/scripts/manage-app-credentials.sh -p project -i instance  -s $SPEC_PATH create commonTrust
  3. Create the UIM cloud native instance by running the following command:
    $COMMON_CNTK/scripts/create-applications.sh -i instance -p project -s $SPEC_PATH -a uim

Resetting the WebLogic Server's Database Connections

You may need to reset the WebLogic server's database connections in the following situations:
  • The database goes down while UIM is active
  • UIM is started when the database is down
You reset the database connections by running the manage-app-credentials.sh script with the update option. 
#Run the following script to update the database schema details in Kubernetes secretes
$COMMON_CNTK/scripts/manage-app-credentials.sh -i instance -p project -a uim update uimdb,rcudb
When you reset the database connections, the following are updated:
  • InventoryDataSource
  • InventoryTxDataSource
  • CMDSInventoryPersistentDS
  • InventoryMapDataSource
  • InvJMSPersistentDS
  • mds-commsRepository
  • opss-audit-DBDS
  • opss-auditviewDS
  • opss-data-source
  • LocalSvcTblDataSource
  • UIMAdapterDS
  • JDBC data sources
To pick the latest secrets, run the following command:
#Run the following script to upgrade the UIM instance to pick the latest secrets
$COMMON_CNTK/scripts/upgrade-applications.sh -i instance -p project -s $SPEC_PATH -a uim

Setting the Default Telephone Number Edit Mask in a UIM Cloud Native Deployment

To modify the default telephone number edit mask:

  1. Update the number.properties file in the ora_uim_localization_reference cartridge in the model/content/product_home/config/resources/logging directory. See "Setting the Default Telephone Number Edit Mask" for more details about the default telephone number edit mask.
  2. Build custom UIM Docker image and run the following command:
    $COMMON_CNTK/scripts/upgrade-applications.sh -i instance -p project -s $SPEC_PATH -a uim
    See "Overview of the UIM Cloud Native Deployment" in UIM Cloud Native Deployment Guide for information about building custom images.

Setting the Default Place Type in a Cloud Native Deployment

To set the default place type in a cloud native deployment:
  1. Add or update the property in the $SPEC_PATH/project/instance/config/uim/system-config/custom-config.properties file. See "Setting the Default Place Type" for details about the default place type property.
  2. Run the following command: 
    $COMMON_CNTK/scripts/restart-applications.sh -i instance -p project -s $SPEC_PATH -a uim -r all

Configuring Topology Updates in a Cloud Native Deployment

To configure topology updates in a cloud native deployment:
  1. Add the property in the $SPEC_PATH/project/instance/config/uim/system-config/custom-config.properties file. See "Configuring Topology Updates" for more details about topology updates.
  2. Run the following command: 
    $COMMON_CNTK/scripts/restart-applications.sh -i instance -p project -s $SPEC_PATH -a uim -r all

Configuring a Geocode Service in a Cloud Native Deployment

To configure a Geocode service in a cloud native deployment:
  1. Add the property in the $SPEC_PATH/project/instance/config/uim/system-config/custom-config.properties file. See "Configuring a Geocode Service" for more details about Geocoding service.
  2. Run the following command:
    $COMMON_CNTK/scripts/restart-applications.sh -i instance -p project -s $SPEC_PATH -a uim -r all

Purging UIM Entities in a Cloud Native Deployment

For UIM cloud native deployments, the purge tool is part of the DB image. The purge tool supports various operations. See "Purging UIM Entities" for more details about purging.

Note:

To view the purge reports and logs, ensure that Persistent Volume Mounts is enabled.
To install or update the purge utility, run the following command:
$COMMON_CNTK/scripts/install-database.sh -i instance -p project -s $SPEC_PATH -a uim -c 9

To purge UIM schema in a UIM cloud native environment:

  1. In the database.yaml file, set the value for purge to true. The following example shows the purge command for purging logical devices:
    purge:
  enabled: true
  purgeCommand: ./ldPurge.sh report -spec LDSpec -ed 01/01/2021
    See "Operations" for information about purge operations.
  2. Run the following command:

    Note:

    The purge operation deletes the database records permanently. You must back up the database before performing any purge operation. 
    $COMMON_CNTK/scripts/install-database.sh -i instance -p project -s $SPEC_PATH -a uim -c 4

Note:

The purge execute command needs to be run with the -force option for purge to be run successfully.
You can also run the install-database.sh script without changing the database.yaml file. You can use this option for scheduling using the cron job:
$COMMON_CNTK/scripts/install-database.sh -i instance -p project -s $SPEC_PATH -a uim -c 4 -u "./ldPurge.sh report -spec LDSpec -ed mm/dd/yyyy"

Preventing a ZIP Bomb When Uploading Ruleset Files in a Cloud Native Deployment

In some scenarios, you may be required to upload ruleset files in a ZIP file.

To prevent a ZIP bomb when uploading ruleset files in a cloud native deployment:
  1. Add the property in the $SPEC_PATH/project/instance/config/uim/system-config/custom-config.properties file. See "Preventing a ZIP Bomb When Uploading Ruleset Files" for the list of properties.
  2. Run the following command:
    $COMMON_CNTK/scripts/upgrade-applications.sh -i instance -p project -s $SPEC_PATH -a uim

Customizing UIM Functionality

You can customize UIM functionality by extending the following:
  • CLASSPATH
  • EXT_PRE_CLASSPATH
To extend CLASSPATH:
  1. Update the value for classpath in the app-uim.yaml file.
    managedServers:
  project:
    #CLASSPATH for all managed servers at project level, separate the jars with colon(:)
    classpath: "/UIM/lib/MetasolvPersistent.jar"
  2. Run the following command:
    $COMMON_CNTK/scripts/upgrade-applications.sh -i instance -p project -s $SPEC_PATH -a uim
To extend EXT_PRE_CLASSPTH:
  1. Update the value for extPreClasspath in the app-uim.yaml file.
    managedServers:
  project:
    #EXT_PRE_CLASSPATH for all managed servers at project level, separate the jars with colon(:)
    extPreClasspath: "/UIM/lib/MetasolvPersistent.jar"
  2. Run the following command:
    $COMMON_CNTK/scripts/upgrade-applications.sh -i instance -p project -s $SPEC_PATH -a uim

Improving the Performance of a UIM Cloud Native Deployment

This section describes ways to improve the performance of a UIM cloud native deployment.

You perform the following tasks to improve UIM performance:

Improving Performance of Searches That Include Characteristics in a Cloud Native Deployment

To improve the performance of searches that include characteristics:
  1. Add the properties to the $SPEC_PATH/project/instance/config/uim/system-config/custom-config.properties file.
  2. Run the following command:
    $COMMON_CNTK/scripts/upgrade-applications.sh -i instance -p project -s $SPEC_PATH -a uim -r all
See "Improving Performance of Searches That Include Characteristics" for more details.

Changing the Logging Level in a Cloud Native Deployment

UIM uses log4j for logging the services. For more details about log4j, see: https://logging.apache.org/log4j/2.x/manual/.

The logging level is defined in the $SPEC_PATH/project/instance/config/uim/logging/loggingconfig.xml file.

See the Appender Configuration, Logger Configuration, and Connecting debugger to UIM sub-sections in "Changing the Logging Level" for more details.

Enabling SQL and Other EclipseLink Logging in a Cloud Native Deployment

To enable SQL and Other EclipseLink logging:
  1. Log in to Oracle Enterprise Manager Console.
  2. Navigate to the oracle.communication.inventory application deployment and choose the managed server for which you want to enable logging.
  3. Edit Current Log Level to choose FINEST.

Updating the System Configuration Files in a Cloud Native Deployment

You use files to control many aspects of UIM performance and configuration. These system configuration files are packaged in the UIM docker image and are available in the UIM/config folder in the runtime container. Each file includes properties for which you can set values. See "Updating the System Configuration Files" for the list of files and available properties in each of the files.

To override the value for any property in the configuration files:
  1. Add the property with the new value in the $SPEC_PATH/project/instance/config/uim/system-config/custom-config.properties file.
  2. Do any one of the following:
    • If the added property is dynamic in nature, then run the following command:
      $COMMON_CNTK/scripts/upgrade-applications.sh -i instance -p project -s $SPEC_PATH -a uim
    • If the added property is static in nature and if restarting the server is required, then run the following command: 
      $COMMON_CNTK/scripts/restart-applications.sh -i instance -p project -s $SPEC_PATH -a uim -r all

Changing the Query Behavior and Row Limit Parameters in a Cloud Native Deployment

To change the query behavior and row limit parameters:
  1. Update the $SPEC_PATH/project/instance/config/uim/system-config/custom-config.properties file.
  2. Run the following command:
    $COMMON_CNTK/scripts/upgrade-applications.sh -i instance -p project -s $SPEC_PATH -a uim
See "Changing the Query Behavior and Row Limit Parameters" for more details about the parameters you can change.