Running the SAF Sample for UIM Cloud Native

10 Running the SAF Sample for UIM Cloud Native

It is highly recommended that you explore UIM cloud native support of SAF using a predefined set of configurations and instructions. This activity not only serves to quickly identify any environment issues but also provides the experience in setting up the connectivity for your own projects.

This chapter describes how to run the SAF sample for UIM cloud native.

The SAF sample for UIM cloud native consists of the following components:

The SAFSample cartridge that is ready to be deployed. This cartridge implements a flow that consists of sending a JMS message to a remote system and receiving a JMS message in response.
Configuration fragments for a project and an instance. These can be added to your project specification and contain all the SAF connection specifications as well as endpoint identification.
A simple emulator that is available as a JAR file, along with instructions and configuration samples. This emulator can be set up on a WebLogic system outside the Kubernetes cluster and functions as a "remote system" in the SAF communication. The emulator simply echos the message given to it.

The SAF sample described in this section uses "sr" as project and "quick" as instance names.

Prerequisites for running the SAF sample

For the SAF sample, you need the following:

A Linux host capable of running WebLogic Server 12.2.1.4 outside of the Kubernetes cluster.
Traffic should be routable between the Kubernetes cluster and this host.
If you are not using a centralized DNS resolution server, edit the /etc/hosts file of the Linux host to add resolution for your UIM cloud native instance. For example, use <k8s-access-ip> quick.sr.uim.org t3.quick.sr.uim.org admin.quick.sr.uim.org.

For further details, see "Planning and Validating Your Cloud Environment".

Running the SAF sample involves the following tasks:

Preparing WebLogic System to Run the Emulator

Install WebLogic 12.2.1.4 on the prepared Linux host. The specific patchset does not matter as long as it contains the patch referenced in "Applying the WebLogic Patch for External Systems".

To prepare the WebLogic system to run the emulator:

Create a WebLogic domain while accepting all defaults.

Note:
Do not enable JRF or any other Fusion Middleware capabilities for this sample. WebLogic domain should be standalone installation with development mode.
Stop WebLogic and find the domain home.
Edit <domain-home>/config/config.xml with the configuration fragment xml file in the UIM_CNTK, at samples/saf-sample/remote-weblogic-resources/config/config_fragment.xml.
From the configuration fragment file, copy the following contents to the config.xml file:
1. Add <jms-system-resource> for SAF Module at the end, just before </domain>.
2. Add <saf-agent> at the end, just before </domain>.
This creates a JMS Module and a SAF agent. The SAF agent will eventually get used in sending emulator responses back to the UIM cloud native instance.
From the $UIM_CNTK folder, copy the samples/saf-sample/remote-weblogic-resources/config/jms/uim-saf-module-jms.xml file to <domain-home>/config/jms.
This creates SAF entities.
Update SAF configuration for connecting to UIM cloud native instance. This instance does not need to be up at this point, but you do need the details such as project name, instance name, weblogic username, and weblogic password.
1. Edit the <domain-home>/config/jms/uim-saf-module-jms.xml file and update the following fields:
  
  Note:
  The password is entered as plain text, and gets auto-encrypted during WLS startup.
```
<saf-login-context>
    <loginURL>{uim_cn_t3_url}</loginURL>
    <username>{uim_cn_weblogic_username}</username>
    <password-encrypted>{uim_cn_weblogic_password}</password-encrypted>
</saf-login-context>
```
  Where uim_cn_t3_url is http://t3.instance.project.uim.org:30305 or http://t3.instance.project.uim.org:80.
2. Start WebLogic. At this point, if you see errors from SAF or JMS about your UIM cloud native instance, you can ignore the errors. These errors go away once the UIM cloud native instance is up and configured for SAF sample.

Note:

You can also manually set up SAF agent and SAF entities through WebLogic Server Administration console.

Deploying the Emulator on the WebLogic System

To deploy the emulator on the WebLogic system:

Find the samples/saf-sample/remote-weblogic-resources/emulator-resources/uim-emulator-mdb-0.0.1-SNAPSHOT.jar emulator MDB jar file in $UIM_CNTK.
Open the remote WebLogic console.
In the Install folder of Deployments, upload the emulator MDB jar file under Upload.
Complete the deployment using the defaults and ensure that the MDB file is shown with State "Active" and Health "OK".

Preparing the UIM Cloud Native Instance

To prepare the UIM cloud native instance for the SAF sample:

Create customized image with $UIM_CNTK/samples/saf-sample/uim-cn-resources/cartridge-resources/SAFSample cartridge. See "Adding Solution Cartridge Customizations" for more information.
Enable the extension mechanism by setting the custom flag to true in the project specification.
Copy $UIM_CNTK/samples/customExtensions/_custom-domain-model.tpl to your customExtPath directory.
From $UIM_CNTK, copy the contents from samples/saf-sample/uim-cn-resources/_custom-jms-support.tpl to $UIM_CNTK/samples/customExtensions/_custom-jms-support.tpl.
Copy $UIM_CNTK/samples/customExtensions/_custom-jms-support.tpl to your customExtPath directory.
Set the jms flag in the project specification to true.
From $UIM_CNTK, copy the contents from samples/saf-sample/uim-cn-resources/_custom-saf-support.tpl to $UIM_CNTK/samples/customExtensions/_custom-saf-support.tpl.
Copy $UIM_CNTK/samples/customExtensions/_custom-saf-support.tpl to your customExtPath directory.

Set the saf flag in the project specification to true.

The sample settings are as follows:

custom:
  enabled: true
  application: false
  jdbc: false
  jms: true
  saf: true
  #wdtFiles: {} # This empty declaration should be removed if adding items here.
  wdtFiles:
   - _custom-domain-model.tpl
  # - _custom-jdbc-support.tpl
   - _custom-jms-support.tpl
   - _custom-saf-support.tpl

Create a secret for storing the remote server credentials.

Replace the user name and password with the values for remote WebLogic credentials as follows:

kubectl create secret generic secret_name -n project --from-literal username=remote_domain_weblogic_username --from-literal password=remote_domain_weblogic_password

Configure the SAF URL and SAF Queue (RequestQueue). The cartridge deployed for this sample uses this SAF Queue (RequestQueue) to send messages to external Weblogic domain.
Replace safDestinationConfig: {} in <project>.yaml with the following:
```
safDestinationConfig:
 - name: sample
   t3Url: "t3://{remote_weblogic_hostname}:{remote_weblogic_port}"
   secretName: samplesecret
   destinations:
    - jndiPrefix: 
      queues:
       - queue:
          localJndi: RequestQueue
          remoteJndi: RequestQueue
```
Replace the value of {remote_weblogic_hostname} and {remote_weblogic_port} with the hostname and port where remote WebLogic is installed.

Note:
If safDestinationConfig already exists in your <project>.yaml, do not create a new element; append SAFSample to the end of the existing list of items in safDestinationConfig.
Create UIM cloud native instance as follows:
```
$UIM_CNTK/scripts/create-instance.sh -p sr -i quick -s $SPEC_PATH -m customExtPath
```
Both the SAF endpoints, one on the remote WebLogic and one on this UIM cloud native instance, become active.

Deploying the SAF Sample Cartridge

Deploy the SAF sample cartridge from $UIM_CNTK/samples/saf-sample/uim-cn-resources/cartridge-resources/ to UIM cloud native instance using Design Studio or CMT. The deployment does not have any dependency on base cartridges. See "Deploying Cartridges" for information on deploying cartridges using Design Studio or CMT.

Validating the SAF Endpoints

To validate the SAF endpoints:

On the remote WebLogic, login to the WebLogic console and perform the following:
1. Navigate to Store and Forward Agents, Monitoring, and then to Remote Endpoints. You can see a remote endpoint uim-saf-module!uim_saf_destination!uim_saf_queue@uim_saf_agent with the URL pointing to your UIM cloud native instance.
2. Navigate to Deployments. You can see the emulator MDB shown with State "Active" and Health "OK".
On the UIM cloud native instance, login to the WebLogic console.
Navigate to Store and Forward Agents, Monitoring, and then to Remote Endpoints. You can see a remote endpoint uim_sample_saf_module!uim_sample_saf_destinations_0!saf_queue_0@uim_saf_agent@ms1 with the URL pointing to your remote WebLogic.

Performing a Test

You can perform a test as follows:

Navigate to Administration, Execute Rule, Select SAFSample, and then to Process.
Navigate to Store and Forward Agents, uim_saf_agent, Monitoring, and then to Statistics.
Validate messages received count increased in remote WebLogic console.
Validate that the following message appears in custom_jms_module/ResponseQueue:
```
Hello!
TimeStamp: 2021.08.25.07.44.01
```