This chapter describes how to deploy Oracle User Messaging Service (UMS) drivers by using Oracle WebLogic Scripting Tool (WLST), Oracle Enterprise Manager Fusion Middleware Control, Oracle Fusion Middleware Configuration Wizard, and the wsadmin
utility of IBM WebSphere Application Server. It also describes how to undeploy and register Oracle UMS drivers.
This chapter includes the following topics:
When you install Oracle UMS, preinstalled drivers are included (Email, XMPP, SMPP, and VoiceXML). Among these drivers, only the Email driver is deployed to the WebLogic Server. To deploy other drivers, target that driver to the WebLogic Server (using Oracle WebLogic Server Administration Console, or you can target the drivers when creating or extending the domain using the Oracle Fusion Middleware Configuration Wizard).
The Worklist driver must be deployed to a SOA Server to make use of the UMS integration with Worklist. Because this integration involves multiple JEE applications and a SOA composite, there is a special extension template you must use to enable this feature in one step. See Install the Worklist Driver on the Oracle WebLogic Server Platform and Install the Worklist Driver on IBM WebSphere Platform for more information.
You can deploy additional drivers in a variety of ways using: WLST commands (recommended), wsadmin tool, Oracle Enterprise Manager Fusion Middleware Control, and through the Oracle Fusion Middleware Configuration Wizard.
The section includes the following topics:
Section 28.1.2, "Deploying Drivers Using Oracle Enterprise Manager Fusion Middleware Control"
Section 28.1.3, "Deploying Drivers Using the Oracle Fusion Middleware Configuration Wizard"
Note:
To deploy two or more driver instances of a particular driver EAR, you must use the custom deployment plan templates available at $ORACLE_HOME/communications/plans
. Deploying drivers using WLST commands is recommended because these commands automatically modify your deployment plans for you; using other methods requires you to manually modify your deployment plans.
You can deploy drivers using the WLST command deployUserMessagingDriver
.
Command Category: UMS
Use with WLST: Online
deployUserMessagingDriver
is used to deploy additional instances of user messaging drivers.Specify a base driver type (for example: email, xmpp, voicexml, and others) and a short name for the new driver deployment. The string usermessagingdriver- is prepended to the specified application name. Any valid parameters for the deploy command can be specified, and is passed through when the driver is deployed.
deployUserMessagingDriver(baseDriver, appName, [targets], [stageMode], [options])
Argument | Definition |
---|---|
|
Specifies the base messaging driver type. Must be a known driver type, such as email, proxy, smpp, voicexml, or xmpp. |
|
A short descriptive name for the new deployment. The specified value is prepended with the string |
|
Optional. Additional arguments that are valid for the |
To deploy a second instance of an email driver with name myEmail
.
wls:/base_domain/serverConfig> deployUserMessagingDriver(baseDriver='email', appName='myEmail')
To deploy a second instance of an email driver, specifying deployment targets.
wls:/base_domain/serverConfig> deployUserMessagingDriver(baseDriver='email', appName='email2', targets='server1,server2')
To deploy drivers using Oracle Enterprise Manager Fusion Middleware Control:
Retrieve a deployment template (for example: ORACLE_HOME/communications/plans
)
Copy the plan to a location of your choice (to the same directory or any other directory).
Replace DriverDeploymentName
with whichever name you want to use (ensure you replace all instances of the name).
Replace DriverShortName
with any name you like.
Replace the @RunAsPrincipalName@
token with a valid principal for use by UMS. In a default deployment, the system principal OracleSystemUser
is available for this purpose.
Start Oracle Enterprise Manager Fusion Middleware Control.
Enter the location of the .ear
file.
Click Next.
The Select Target page appears.
Enter the location of the deployment plan.
Select the SOA target.
Enter an application name in the Application Attributes page. The application name must exactly match the string used for DriverDeploymentName (in Step 3 above) which is provided in the deployment plan. If it does not, the deployment and activation fails. The Deployment Setting page appears.
Click Deploy. The Deployment Completed page appears.
To see the result (driver deployed), start the SOA Server.
To install the SMPP, XMPP, and VoiceXML drivers, extend the domain using the extension template available at $ORACLE_HOME/common/templates/applications/oracle.ums.drivers_template_11.1.1.jar
.To extend a domain using Oracle Fusion Middleware Configuration Wizard:
Launch Oracle Fusion Middleware Configuration Wizard ($ORACLE_HOME/common/bin/config.sh
or %ORACLE_HOME%\common\bin\config.cmd
).
Select the Extend an existing WebLogic domain option.
Select the desired domain directory containing UMS.
Select the Extend my domain using an existing extension template option.
Click Browse, and navigate to $ORACLE_HOME/common/templates/applications
Select oracle.ums.drivers_template_11.1.1.jar
.
Complete the remaining steps of the Oracle Fusion Middleware Configuration Wizard, and remember to target the required drivers to the desired Oracle WebLogic Servers, clusters, or both.
Restart the appropriate Oracle WebLogic Servers.
You can deploy additional instances of UMS drivers by using the Oracle Fusion Middleware-specific wsadmin
command OracleUMS.deployUserMessagingDriver
.
This section describes the syntax and arguments for the wsadmin OracleUMS.deployUserMessagingDriver
command.
OracleUMS.deployUserMessagingDriver
is used to deploy additional instances of user messaging drivers.
Specify a base driver type (email, xmpp, smpp, voicexml, proxy, or worklist) and a short name for the new driver deployment. The string "usermessagingdriver-" is prepended to the specified application name.
OracleUMS.deployUserMessagingDriver(baseDriver, appName, required_options)
Argument | Definition |
---|---|
|
Specifies the base messaging driver type. Must be a known driver type, such as email, proxy, smpp, voicexml, 'proxy', or 'worklist'. |
|
A short descriptive name for the new deployment. The specified value is prepended with the string |
|
Additional arguments that are valid for the "AdminApp.install" command. These options are mandatory for this command:
|
Example:
OracleUMS.deployUserMessagingDriver('email', 'myEmail', '-node myNode -cell myCell -server myServer -usedefaultbindings -defaultbinding.virtual.host default_host')
where:
email
and myEmail
represent values for the baseDriver
and appName
arguments respectively.
-node
, -cell
, -server
, -usedefaultbindings
, -defaultbinding.virtual.host
are the required options. myNode
, myCell
, myServer
and default_host
represent the values of respective options.
To deploy a second instance of an email driver with name "smpp2" on a SOA Server named "soa_server1":
wsadmin> OracleUMS.deployUserMessagingDriver('smpp','smpp2','-node DefaultNode01 -cell DefaultCell01 -server soa_server1 -usedefaultbindings -defaultbinding.virtual.host default_host')
To deploy a second instance of an email driver with name "email2" on a BAM Server named "bam_server1":
wsadmin> OracleUMS.deployUserMessagingDriver('email','email2','-node DefaultNode01 -cell DefaultCell01 -server bam_server1 -usedefaultbindings -defaultbinding.virtual.host default_host')
To deploy the UMS drivers by using the wsadmin
tool, do the following:
Open a browser and enter the following URL to access the IBM WebSphere Administrative Console (also known as IBM WebSphere Integrated Solutions Console):
https://hostname:SSL Port/ibm/console
Log in to the administration console by using the administrator name and password.
Navigate to System administration > Deployment manager > Configuration > Ports > BOOTSTRAP_ADDRESS and identify the corresponding port number.
On the system where Oracle SOA server is running, set the ORACLE_HOME
environment variable to the location where Oracle Fusion Middleware SOA component is installed. You should set this variable before running the wsadmin
command.
For example,
On UNIX platform, run the following command in the UNIX shell:
$ export ORACLE_HOME=/fmwwas-nd/middleware/Oracle_SOA1
On Windows platform, run the following command in the DOS shell:
C:\> set ORACLE_HOME=C:\fmwwas-nd\middleware\Oracle_SOA1
From the ORACLE_HOME
\common\bin
folder, run the wsadmin
command. Specify the RMI port number (see Step 2) as the value for the -port
option.
On UNIX:
ORACLE_HOME/common/bin/wsadmin.sh -profileName profilename -connType RMI -host hostname -port RMI_port -user admin_user -password admin_password
On Windows:
ORACLE_HOME\common\bin\wsadmin.cmd -profileName profilename -connType RMI -host hostname -port RMI_port -user admin_user -password admin_password
To view the list of enterprise applications and drivers that are already deployed, run the wsadmin
command as follows:
wsadmin>print AdminApp.list() DMS Application_11.1.1.1.0 DefaultToDoTaskFlow Dmgr DMS Application_11.1.1.1.0 FMW Welcome Page Application_11.1.0.0.0 User Messaging Parlay X Sample App composer em oracle-bam soa-infra usermessagingdriver-email usermessagingdriver-smpp usermessagingdriver-voicexml usermessagingdriver-xmpp usermessagingserver worklistapp wsil-nonwls wsm-pm
Run the OracleUMS.deployUserMessagingDriver
command to deploy the UMS driver(s) as follows:
wsadmin> OracleUMS.deployUserMessagingDriver('email','email01','-node DefaultNode01 -cell DefaultCell01 -server soa_server1 -usedefaultbindings -defaultbinding.virtual.host default_host')
To verify that the newly deployed UMS driver(s) is listed along with the rest of enterprise applications and drivers, run the following command:
wsadmin>print AdminApp.list() DMS Application_11.1.1.1.0 DefaultToDoTaskFlow Dmgr DMS Application_11.1.1.1.0 FMW Welcome Page Application_11.1.0.0.0 User Messaging Parlay X Sample App composer em oracle-bam soa-infra usermessagingdriver-email usermessagingdriver-email-email01 usermessagingdriver-smp usermessagingdriver-voicexml usermessagingdriver-xmpp usermessagingserver worklistapp wsil-nonwls wsm-pm
Make sure that the newly deployed UMS drivers(s) is listed. In the above example, usermessagingdriver-email-email01
is the new driver.
For more information about using the wsadmin utility to configure Oracle Fusion Middleware products, see Oracle Fusion Middleware Configuration Guide for IBM WebSphere Application Server. For more information about managing Oracle SOA Suite on IBM WebSphere, see Oracle Fusion Middleware Third-Party Application Server Guide.
Since Messaging Drivers are standard JEE applications, they can be undeployed from the Oracle WebLogic Server using standard Oracle WebLogic tools such as the Administration Console or WLST.
However, since the UMS server keeps track of the messaging drivers that have been registered with it in a persistent store (database), this registration must be cleaned in a separate step using a runtime MBean exposed by the UMS server. The procedure to do this from Oracle Enterprise Manager Fusion Middleware Control is as follows.
To undeploy and unregister drivers:
Ensure the UMS server is available.
In Oracle Enterprise Manager Fusion Middleware Control, select any usermessagingserver
target in the domain.
From the target's menu, select System MBean Browser.
In System MBean Browser, locate the ComponentAdministration MBean of usermessagingserver
:
Expand the folder com.oracle.sdp.messaging > Server (such as Server: soa_server1) > SDPMessagingrun time > ComponentAdministration.
Invoke the operation listDriverInstances.
Click the Operations tab.
Click the operation listDriverInstances.
Click Invoke.
Identify and copy the name of the driver you want to unregister. (for example: /Farm_soa_bam_domain/soa_bam_domain/soa_server1/usermessagingdriver-email:oracle_sdpmessagingdriver_email#Email-Driver
)
Click Return.
Invoke the operation unregisterDriverInstance with the desired driver name.
Click the operation unregisterDriverInstance.
Paste the driver name in the Value field (for example: /Farm_soa_bam_domain/soa_bam_domain/soa_server1/usermessagingdriver-email:oracle_sdpmessagingdriver_email#Email-Driver
).
Click Invoke.
Check the confirmation dialog for success.
This completes the unregistration of the specified driver from the UMS server and it is no longer used in future message delivery.