Running the SAF Sample for OSM Cloud Native

10 Running the SAF Sample for OSM Cloud Native

It is highly recommended that you explore OSM cloud native support of SAF using a predefined set of configurations and instructions. This activity not only serves to quickly identify issues with your cloud environment but also enables you to familiarize yourself with setting up the connectivity for your own projects, which are likely to be more complex than the SAF sample this section describes.

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

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

SimpleProvisioningCartridge sample cartridge available as a par file, ready to be deployed using the OSM cloud native DB Installer. This cartridge implements a flow that consists of sending a JMS message to a remote system and receiving a JMS message in response. The order then ends.
Configuration fragments for a project and an instance. These can be added to your project and instance specifications 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 can be run as a separate project and instance, derived from the samples in the OSM cloud native toolkit. Alternatively, it can be added on to the specifications of a basic OSM instance. A project can consist of multiple cartridges. If you add the specifications to a basic OSM instance, the project consists of SimpleRabbits and SimpleProvisioningCartridge; instances of this project can consume both types of orders.

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 OSM cloud native instance. For example, use kubernetes access IP address quick.sr.osm.org t3.quick.sr.osm.org admin.quick.sr.osm.org.

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

Running the SAF sample involves the following tasks:

Preparing the WebLogic system to run the emulator
Deploying the emulator on the WebLogic system
Deploying the SimpleProvisioning sample cartridge
Preparing the OSM instance
Validating the SAF endpoints
Submitting OSM orders

Preparing the WebLogic System to Run the Emulator

Install WebLogic 12.2.1.4 on the 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:

Start WebLogic server and create a domain accepting all the default settings. Do not enable JRF or any other Fusion MiddleWare capabilities for this sample. Name the domain simple.
Stop the WebLogic server and find the domain home for simple.
Edit the domain-home/config/config.xml file and delete the line: admin-server-nameAdminServer/admin-server-name.
Locate and open the samples/saf-sample/emulated-weblogic-resources/config/config_fragment.xml configuration fragment XML file in the OSM cloud native toolkit.
Copy the contents under the domain element and append them to the end of the domain element in the domain-home/config/config.xml file just before </domain>.
This creates a persistent store for JMS as well as a JMS server and a SAF agent. The SAF agent is used in sending emulator responses back to the OSM cloud native instance.
Copy the samples/saf-sample/emulated-weblogic-resources/config/jms folder in the toolkit to <domain-home>/config. This creates a folder jms under the target config directory with the specific JMS configuration. This also creates JMS queues and SAF entities.
Configure the SAF system to connect to your OSM cloud native instance. The instance does not need to be up at this point, but you should have decided on a project name, instance name, and the WebLogic username and password. If you want to reuse the basic OSM instance, you should already have these ready.
Edit the <domain-home>/config/jms/simple_osm_jms_module-jms.xml file and update the fields underlined in the following fragment. The password is entered as plain text and gets auto-encrypted during WLS startup:
```
    <saf-login-context>
        <loginURL>{osm_cn_t3_url}</loginURL>
        <username>{osm_weblogic_username}</username>
        <password-encrypted>{osm_weblogic_password}</password-encrypted>
    </saf-login-context>
```
osm_cn_t3_url is:
- If Oracle Cloud Infrastructure Load Balancer is not used: http://t3.instance.project.osm.org:30305
- If Oracle Cloud Infrastructure Load Balancer is used: http://t3.instance.project.osm.org:80
Start WebLogic. At this point, if you see errors from SAF/JMS about your OSM cloud native instance, you can ignore them. These errors go away once the OSM cloud native instance is up and configured for the SAF sample.

Deploying the Emulator on the WebLogic System

To deploy the emulator on the WebLogic system:

Find the samples/saf-sample/emulator-mdb/emulator-mdb-1.0.0.jar emulator MDB jar file in the OSM cloud native toolkit.
Open the WebLogic Console for the simple domain.
In Deployments, upload the emulator MDB jar file.
Complete the deployment using the defaults and ensure that the MDB file is shown with State "Active" and Health "OK".

Deploying the SimpleProvisioning Sample Cartridge

The SimpleProvisioning sample cartridge contains the following:

process_1 process
A manual creation task
An automation task with the following:
- qQuerySender XQuery Sender
- Receiver XQuery Automator

To deploy the SimpleProvisioning cartridge:

Identify a PDB for use with the SAF sample.
This must be ready to host an OSM cloud native instance with RCU DB schema and OSM DB schema in place. You can use a fresh PDB and run the OSM cloud native DB Installer, or reuse or clone the PDB from the basic OSM cloud native instance. If you reuse the PDB in the basic OSM cloud native instance, you must use the basic OSM cloud native project and instance specification files in subsequent steps and delete the basic OSM cloud native instance.

Deploy the SimpleProvisioning cartridge using the script in the toolkit:

./scripts/manage-cartridges.sh -p project_name -i instance_name -s $SPEC_PATH -f $OSM_CNTK/samples/saf-sample/cartridge-resources/cartridge-par/SimpleProvisioning.par -c parDeploy

Preparing the OSM Cloud Native Instance

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

Obtain a starter project specification. This can be the samples/project.yaml sample in the toolkit or you can reuse the project specification created for the basic OSM cloud native instance.
1. Configure a UDQ (SimpleResponseQueue) to receive the response from an external WebLogic domain by replacing the following line:
```
uniformDistributedQueues: {}
```
  with the following:
```
uniformDistributedQueues:
  - name: SimpleResponseQueue
    jndiName: oracle.communications.ordermanagement.SimpleResponseQueue
    resetDeliveryCountOnForward: false
    deliveryFailureParams:
      expirationPolicy: Discard
      redeliveryLimit: 10
    deliveryParamsOverrides:
      timeToLive: -1
      priority: -1
      redeliveryDelay: 1000
      deliveryMode: 'No-Delivery'
```
  If uniformDistributedQueues already exists in your project.yaml file, do not create a new element. Instead, append the item SimpleResponseQueue from the above snippet to the end of the existing list of items for uniformDistributedQueues.
2. Configure the SAF Queue (RequestQueue) by replacing the following line:
```
safDestinationConfig: {}
```
  with the following:
```
safDestinationConfig:
  - name: simple
    destinations:
      - jndiPrefix: simple.
        queues:
          - queue:
             localJndi: RequestQueue
             remoteJndi: RequestQueue
```
  The cartridge deployed for this sample uses this SAF queue to send messages to the external WebLogic domain.
  If safDestinationConfig already exists in your project.yaml file, do not create a new element. Instead, append the item simple from above to the end of the existing list of items for safDestinationConfig.
Obtain a starter instance specification. This can be the samples/instance.yaml sample in the toolkit or you can reuse the instance specification created for your basic OSM instance.
1. If you start with the instance.yaml sample, you must use your experience with creating a basic OSM cloud native instance to set up the DB server, NFS for logs (optional), authentication, and so on.
2. Configure the connection to the external OSM WebLogic domain by replacing the following line:
```
safConnectionConfig: {}
```
  with the following:
```
safConnectionConfig:
  - name: simple
    t3Url: t3://{simple_weblogic_hostname}:{simple_weblogic_port}
    secretName: simplesecret
```
  Replace the value of {simple_weblogic_hostname} and {simple_weblogic_port} with the hostname and port where simple WebLogic domain is installed. If safConnectionConfig already exists in your project-instance.yaml, do not create a new element. Instead, append the item simple from the above to the end of the existing list of items for safConnectionConfig.
Create a secret to contain the credentials for the simple WebLogic domain by running the following command. Name the secret as simpleSecret as specified in the above steps for the SAF connection and Replace the username and password with the values for the simple WebLogic domain.
```
kubectl -n project create secret generic simplesecret --from-literal=username='simple_domain_weblogic_username' --from-literal=password='simple_domain_weblogic_password'
```
Bring up the OSM cloud native instance. If you are not reusing the basic OSM instance, you will have to first create all the required secrets.
If you used a clone of the PDB of the basic OSM cloud native instance, you must replicate the opssWF and opssWP secrets from your basic OSM instance and set rcu.db.preexisting to true in your instance specification file. Failing to do this results in your new instance not being able to process the cloned PDB.
Once the OSM cloud native instance is up, do the following:
1. Log in to the OSM Orchestration UI.
2. Go to Administer Workgroups.
3. Choose the OSM user you will be using to inject orders and add this user to the "SimpleProvisioningRole" workgroup.
This allows your chosen user to create orders in the SimpleProvisioning cartridge.
Both SAF endpoints, one on simple and one in this OSM cloud native instance should now be active. You can confirm this by validating the setup.

Validating the SAF Endpoints

To validate the SAF endpoints:

On the simple WebLogic domain, log in to the WebLogic console and do the following:
1. Navigate to Remote Endpoints. You should see a remote endpoint called simple_osm_saf_agent with the URL pointing to your OSM cloud native instance.
2. Navigate to Deployments. You should see the emulator MDB shown with State "Active" and Health "OK".
On the OSM cloud native instance, log in to the WebLogic console and navigate to Remote Endpoints. You should see the following remote endpoints pointing to the simple WebLogic domain:
```
osm_simple_jms_module!osm_saf_destinations_simple.!<saf_queuex|saf_topicx>@osm_saf_agent@ms1
```

Submitting Orders

You can submit orders with HTTP and T3 over HTTP.

Submitting Orders with HTTP

To submit orders with HTTP:

Submit orders using the OSM Task Web Client or SoapUI:
1. If you wish to use SoapUI, find the sample order payload for the SimpleProvisioning cartridge in the toolkit at samples/saf-sample/cartridge-resources/CreateOrderBySpec.xml.
2. In the OSM Task Web client, create a new order of type SimpleProvisioning.
In the order data, find the "data" element and replace MsgText with a unique value.
Submit the order.
Examine the order in OSM Task Web Client of the OSM cloud native instance. It is very likely that the order completes very quickly and therefore does not appear in the Worklist. Use Query to look for completed orders and find the order. The completed order should show the response from the emulator.

If there are any issues with connectivity, the order does not complete successfully. Examine the message count on the queues in both OSM cloud native and in the simple WebLogic domain to see where the sequence was disrupted.

Submitting Orders with T3 over HTTP

To submit orders with T3 over HTTP, install SoapUI and HermesJMS and set them up to connect to your cloud native environment. SoapUI uses plain HTTP to submit orders. By using SoapUI with HermesJMS, orders can also be submitted as JMS messages using T3 over HTTP.

Consider the following when setting up SoapUI and HermesJMS:

Java 8: If you use Java 8, you must find your Hermes installation location and the hermes.sh file within that location in the bin directory. Edit this file to replace the existing invocation of JAVACMD with the following:

"$JAVACMD" -Dorg.xml.sax.parser=com.sun.org.apache.xerces.internal.parsers.SAXParser 
-Djavax.xml.parsers.DocumentBuilderFactory=com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl 
-Djavax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl 
-XX:NewSize=512m -Xmx2048m $HERMES_OPTS -Dlog4j.configuration=file:$HERMES_HOME/bin/log4j.props 
-Dhermes.home=$HERMES_HOME -Dhermes=$HERMES_CFG -Dhermes.libs=$HERMES_LIB -classpath 
$LOCALCLASSPATH hermes.browser.HermesBrowser

WebLogic Libraries: When you create a session in HermesJMS preferences, create a Classpath Group that includes the WebLogic jar files weblogic.jar, wlclient.jar and wlthint3client.jar. These jar files are found in the standard WebLogic installation. Provide the full path to each jar file in the HermesJMS preferences.

Connection Properties: When you set up a Connection Factory in your HermesJMS Session, add the following properties to it to point to your OSM cloud native instance:

Table 10-1 Connection Properties for HermesJMS Session

Property	Value
providerURL	http://t3.instance.project.osm.org:access-port access-port is the Traefik (ingress controller) NodePort or the Load Balancer port.
binding	oracle/communications/ordermanagement/osm/ExternalClientConnectionFactory
initialContextFactory	weblogic.jndi.WLInitialContextFactory
securityPrincipal	osm-user-name
securityCredentials	password-for-osm-user-name

With these in place, you should now be able to discover the JMS queues and topics from your OSM cloud native instance

Target JMS Queue: Add a JMS endpoint using the Session created. Specify the "Send/Publish Destination" as oracle/communications/ordermanagement/WebServiceQueue. If you wish to see the responses, specify the "Receive/Subscribe Destination" as oracle/communications/ordermanagement/SoapUIResponseQueue. You need to have first specified this response queue as an additional queue in your project specification.
HermesJMS submits the order requests into the OSM cloud native WebServiceQueue distributed queue and optionally shows you responses in the SoapUIResponseQueue distributed queue.
SoapUI Test Case: When you create a test case with the sample order payload, do the following:
- Choose Basic authentication and specify the osm-user-name and password-for-osm-user-name as earlier.
- If you use responses, set the JMSReplyTo JMS Property to oracle/communications/ordermanagement/SoapUIResponseQueue
- Add "JMS Headers" properties with name-value as:
```
_wls_mimehdrContent_Type : text/xml; charset="utf-8" 
URI                      : /osm/wsapi 
```
This setup can now submit orders into the OSM cloud native instance as JMS messages. The SoapUI project and configuration can be saved to serve as a template for future reuse.