5-Part WLST Best Practices Series

A while ago I wrote a 5-part WLST Best Practices series . Here I am consolidating this post with link to all those 5 posts.

• Variable Definitions In The Preamble [WLST scripting Best Practices (Part-1)]
• Do Not Step On Other's Feet [WLST scripting Best Practices (Part-2)]
• Check for resource/configuration existence [WLST scripting Best Practices (Part-3)]
• Use definitions for Reuse [WLST scripting Best Practices (Part-4)]
• Understanding WLST built-in variables . . .[WLST scripting Best Practices (Part-5)]

Running OS Commands From WLST

If you spend a lot of time with WLST in the interactive mode, I am sure you have opened another command prompt/shell to check something at the OS file system level. If you wonder whether can execute an OS command from within WLST prompt, the answer is "Yes". This is very convenient similar to how you can execute OS commands from within "Vi" editor.

In fact this feature is not from WLST but from underlying Jython. There is "os" module in Jython that provides a unified interface to a number of operating system functions. There is "system" function in the "os" module that can take a OS command as a string input and returns either "0" or "1" depends on whether the command was successful or failed. So this feature can also be used with scripting mode where the return code can be verified for further processing in the script.

For eg. os.system(r'dir c:\bea') can list the contents of the bea folder under c drive. Notice the use of the preceding 'r' for escaping the entire string.

Node Manager as a UNIX Startup Process

Configuring WebLogic Server (WLS) as a startup process was a common administrative process in the past. But after Node Manager (NM) was introduced as an agent to start, stop, restart and monitor WebLogic Server it is now recommended that you start WebLogic Server using NM. But NM has to configured as a startup process on the respective OS so that it is always running to manage the respective WLS instances on that machine. NM can either be Java based NM or Script based NM. Script based NM uses OS services like SSH or RSH to execute the NM script. But Java based NM is a Java process that should be started. So setting up NM as a service will ensure that NM is always running. There is a lot of information in the WebLogic Server documentation about setting up NM. But there is very less or no information about setting NM as a service on a non-Windows environment. For Windows environment there are pre-packged scripts that you can use. These scripts exists under WL_HOME/server/bin folder (installNodeMgrSvc.cmd, uninstallNodeMgrSvc.cmd). But for UNIX based environment you should do this manually or with the help of OS specific utilities like chkconfig etc.

For *nix environment NM should be configured as startup process using rc scripts. Creating rc scripts for configuring NM as a service is even simpler than configuring WebLogic Server as a service. This is mainly because NM doesn't have to be shutdown gracefully. All you have to do is write a simple shell script that starts the NM and create the symbolic link to that script from the right run level folder. The following illustrates the steps to confiure NM as service under LINUX environment. It should be very similar on other *nix environments. You need root permission to peform the following steps.


1. Create a shell script (wlsnmd) under /etc/init.d/ folder:

#! /bin/bash
case "$1" in
    start)
        WL_HOME = /usr/middleware/11.1.0/wlserver_10.3
        $WL_HOME/server/bin/startNodeManager.sh
        ;;

    *)
        echo "Usage: $0 {start}"
        exit 1
esac

exit_status

2. Assuming that we are going to start NM at run level 5, create a sysmbolic link in /etc/rc.d/rc5.d/ folder. Since it a startup script we should start the symbolic link with "S" and followed by a number which decide the order in which services will be called. As we are fine to start NM after all the other application/services are start let us choose 99 which is the highest number.

ln -s /etc/init.d/wlsnmd S99weblogic

If you don't want to do these manually you can also use utilities like chkconfig (included in Red Hat distributions) for managing your startup scripts. For configuring WebLogic Server as a startup process there are pre-packaged scripts (installSvc.cmd, uninstallSvc.cmd). But you have to create rc scripts similarly for WLS as well in UNIX based environments. Here is an example rc script for configuring a WebLogic Server as a startup process. But here we also need to implement the kill/stop to gracefully shutdown the server.

#! /bin/bash

case "$1" in
    start|reload)
        DOMAIN_HOME = /usr/middleware/domains/med_analysis
        $DOMAIN_HOME/bin/startWebLogic.sh
        ;;
    stop)
        $DOMAIN_HOME/bin/stopWebLogic.sh
        ;;
    restart|force-reload)
        $0 stop
        $0 start
        ;;
    *)
        echo "Usage: $0 {start|stop|restart}"
        exit 1
esac

exit_status

Understanding WLST built-in variables . . .[WLST scripting Best Practices (Part-5)]

This post is a continuation of my previous post - in a series of posts about WLST scripting best practices.

Managed Beans (MBeans) are used to represent all the configuration and runtime information about WebLogic Domain, Servers, the applications and services deployed on a WebLogic Server Domain. While you can get all the information from WebLogic MBeans, WLST simplifies the task of building scripts by providing some built-in variables. These WLST variables are initialized and/or modified when you change to online mode (connect to a server), start an edit session etc. to appropriate values.

One of the very useful WLST variable is cmo. cmo stands for current management object. When navigating in WLST you can use cmo to reference the current MBean (object) instance you are navigating into. The cmo value is changed when you navigate to different hierarchy of MBeans under different MBean trees in WebLogic (except jndi tree). The following illustrates the use of cmo.

...
connect(username, password, url)
edit()
startEdit()
cd('/Servers/server1')
s1=cmo
cd('/Servers/server2')
s2=cmo
print 'Listenport of server1 -> ' + s1.getListenPort()
print 'Listenport of server2 -> ' + s2.getListenPort()
...

Notice the use of cmo can for invoking operations on the respective MBean object. There are many such variables that will help you to write better and efficient WLST scripts. See here for the list of all the WLST variables.

If you know a variable name you can simply use it in you script. dumpVariables() command can be used to list all the variables and their values.

wls:/testdomain/serverConfig> dumpVariables()
adminHome                     weblogic.rmi.internal.BasicRemoteRef - hostID: '328889774891021637S:127.0.0.1:[7001,7001,-1,-1,-1,-1,-1]:testdomain:AdminServer',oid: '259', channel: 'null'
cmgr                          [MBeanServerInvocationHandler]com.bea:Name=ConfigurationManager,Type=weblogic.management.mbeanservers.edit.ConfigurationManagerMBean
cmo                           [MBeanServerInvocationHandler]com.bea:Name=testdomain,Type=Domain
connected                     true
domainName                    testdomain
...

In addition you should also be aware of these WLST variables in order to NOT use them to store your own information. If you do so then WLST will overwrite these variables during your interaction like connect, startEdit etc. So make sure you understand these WLST variables, use them in your scripts and do not use them to store your information.

More ways to check the existense of a resource with WLST

In one of my previous post, I discussed a couple of ways with which you can find out whether a particular configuration already exists before you create them. The methods are not just limited to the one on that post. So now I am here to discuss couple more way to do the same check. But just for completeness I shall also include the methods I discussed in my previous post. I am taking a sample use case to check whether a particular WebLogic Server instance exists in the domain or not. But you can extrapolate these technique for any other resource like JDBC Data Source, JMS Server, JMS Queue etc.

Goal - Check whether a server with the name 'mymanagedserver' exists in the domain

Method-1 Using "cd"

A simple approach is to use the "cd" command to navigate into that configuration MBean. If the "cd" command throws an exception then you can safely assume that the resource/configuration doesn't exists and you can continue with your task.

...
mgdServerName = 'mymanagedserver'
### Checking for the server
try:
 cd('/Servers/' + mgdServerName)
 print '===> Server \"' +mgdServerName+'\" already exists'
 print '===> No action was performed'
 exit()
except:
 pass
### Continue to create the server
...

Method-2 Catch "BeanAlreadyExistsException"

Another approach is to catch the "BeanAlreadyExistsException" when creating the resource and safely exiting the script.

...
mgdServerName = 'mymanagedserver'
### Create the Managed Server
edit()
startEdit()
try:
 create(mgdServerName, resourceType)
 print '===> Created Managed Server - ' + mgdServerName
 pass
except BeanAlreadyExistsException:
 print '===> Server \"' +mgdServerName+'\" already exists'
 print '===> No action was performed'
 cancelEdit('y')
 exit()
...

But with this approach you are starting an edit session and creating the server to find out it's existence. So you have to cancel the edit session once you find out that the resource that you are creating already exists if not you might get a warning message similar to the following:

You have an edit session open and you will lose all outstanding changes and your edit session will be stopped if you exit. Are you sure you would like to exit? (y/n)

So canceling the edit session with a response 'y' will make WLST not to prompt for the user response.


Method-3 Using "getMBean"

There is a WLST command called getMBean which will return the MBean object when you specify the appropriate path. If the instance is not found then it will return None. But getMBean command does not throw an exception when an instance is not found. So you have explicitly check result of the getMBean.

...
mgdServerName = 'mymanagedserver'
ref = getMBean('/Servers/' + mgdServerName)
if(ref != None):
print 'Server ' +  servername + 'already exists'
disconnect()
exit()
else:
pass
### Continue to create the server
...

Method-4 Using "ls"

You can simply navigate to the resource type and execute ls. This will return the list of all the instances as a string when you assign the output to a variable. Then you can use the find method on that string variable to check whether your server exists. The find method returns a "0" on success or "-1" on failure.

...
mgdServerName = 'mymanagedserver'
cd('/Servers')
servers = ls()
if (servers.find(servername) != -1):
print 'Server ' +  servername + ' already exists'
disconnect()
exit()
else:
pass
### Continue to create the server
...

Use definitions for Reuse [WLST scripting Best Practices (Part-4)]

This post is a continuation of my previous post - in a series of posts about WLST scripting best practices. When you are authoring WLST scripts for automating WebLogic administration tasks, you can reuse or extend an existing logic written in WLST or Jython scripts. You can also leverage or extend logic written in Java which I will discuss later in a different post. Definition are reusable code blocks in Jython. Think of definitions as methods or functions. You can pass parameters into definitions. You can reuse definitions from the same script or from a different script. A script that contains definitions for other scripts to use is usually called as a 'Module'. If you are using a definition from a module then you should import it in your script. The definition should be defined before they get called in the script.

Let us see an example of a using definition in the same script.

#Definition for connecting to a server
def connectToServer():
    username = 'weblogic'
    password = 'weblogic'
    url = 't3://egAdm:7001'
    connect(username, password, url)

#Definition to print a running servers heap details
def printHeapDetails(server_name):
    domainRuntime()
    cd('/')
    cd('ServerRuntimes/'+server_name+'/JVMRuntime/'+server_name)
    hf = float(get('HeapFreeCurrent'))/1024
    hs = float(get('HeapSizeCurrent'))/1024
    hf = hf/1024
    hs = hs/1024
    print 'HeapFreeCurrent - ' + `hf` + 'MB'
    print 'HeapSizeCurrent - ' + `hs` + 'MB'

#Definition to disconnect from a server
def disconnectFromServer():
    disconnect()
    exit()

#Calling connectToServer definition with no arguments
connectToServer()

#Calling printHeapDetails with arguments
printHeapDetails('AdminServer')
printHeapDetails('mgds1')
printHeapDetails('mgds2')

#Calling disconnectFromServer definition with no arguments
disconnectFromServer()

In the above script we are connecting to the administration server of a domain and then printing the heap details for the admin server and 2 other managed servers. The logic to navigate to the respective runtime mbean and printing the heap related attributes is being defined as reusable definition and called multiple times.

WLST-BP-4 Use definitions for Reuse

Check for resource/configuration existence [WLST scripting Best Practices (Part-3)]

This post is a continuation of my previous post in a series of posts about WLST scripting best practices. When you are authoring WLST scripts to create new resource/configuration in WebLogic domain then check for its existence. If the resource/configuration already exists then you might get an error similar to the following:

weblogic.descriptor.BeanAlreadyExistsException: Bean already exists

A simple approach is to use the "cd" command to navigate into that configuration MBean. If the "cd" command throws an exception then you can safely assume that the resource/configuration doesn't exists and you can continue creating.

...
### Check for the server
try: 
    cd('/Servers/' + mgdServerName)
    print '===> Server \"' +mgdServerName+'\" already exists'
    print '===> No action was performed'
    exit()
except:
    pass
...

The other approach is to catch the "BeanAlreadyExistsException" while creating the resource and safely exiting the script.

...
### Create the Managed Server
edit()
startEdit()
try:
    create(mgdServerName, resourceType)
    print '===> Created Managed Server - ' + mgdServerName
    pass 
except BeanAlreadyExistsException:
    print '===> Server \"' +mgdServerName+'\" already exists'
    print '===> No action was performed'
    cancelEdit('y')
    exit()
...

But with this approach you are starting an edit session and creating the server to find out it's existence. So you have to cancel the edit session once you find out that the resource that you are creating already exists if not you might get a warning message similar to the following:

You have an edit session open and you will lose all outstanding changes and your edit session will be stopped if you exit. Are you sure you would like to exit? (y/n)

So cancelling the edit session with a responce 'y' will make WLST not to prompt for user response. I shall discuss how to streamline the outputs from WLST and redirect them to an output file or log file in a later post.

WLST-BP-3 Check for the resource or configuration existence before creating them

Do Not Step On Other's Feet [WLST scripting Best Practices (Part-2)]

This post is a continuation of my previous post - in a series of posts about WLST scripting best practices. When using WLST script for performing configuration changes always check whether someone else is making changes. WebLogic support configuration changes using many methods but not limited to:

• Administration Console
• Interactive WLST
• WLST SCripts
• JMX
• Ant Scripts
• 3rd Party Tools

So it is always better to check whether someone else is making changes while you are ready to start a change session. WebLogic Server will allow only one change session at a time no matter which one of the above methods you use for configuration management. Especially environments with multiple administrators the best practice is to have individual logins for each administrator so that you can have more controlled environment. If you are interested in configuration auditing to find out who is responsible for what, see this post.

Use the Configuration Manager to find out information about existing change sessions. You can find out whether someone else had already started a change session, if so who is making changes, are there any unactivated changed, if so what changes are unactivated etc. from the configuration manager. The following example illustrates a code snippet which checks for existing sessions using configuration manager:

...
### Get the Configuration Manager and check for existing session
cfgManager = getConfigManager()
try:
   cfgManager.getChanges()
   print '===> Someone else is making changes'
except: 
   print '===> No one else is making changes'
...

The following example illustrates a code snippet which checks for the number of unactivated changes using configuration manager:

...
### Get the Configuration Manager and check for existing session
cfgManager = getConfigManager()
try:
   cfgManager.getChanges()
   print '===> Someone else is making changes'
   noOfChanges = cfgManager.getUnactivatedChanges().__len__()
   print 'There are ' + noOfChanges + ' unactivated pending changes in the current edit session'
except: 
   print '===> No one else is making changes'
...

The above code snippet may work only if you are the user who is making the changes. The following example illustrates a code snippet which checks and prints the user who is currently making changes using configuration manager:

...
### Get the Configuration Manager and check for existing session
cfgManager = getConfigManager()
try:
   cfgManager.getChanges()
   print '===> User ' + configmanager.getCurrentEditor() + ' is making changes'
except: 
   print '===> No one else is making changes'
...

The following example is a complete script which checks for an existing session and if one doesn't exists then it will create a new managed server by starting a new session. If a session already exists then it will simply display that information and will exit.

from weblogic.management.mbeanservers.edit import NotEditorException

### CreateMgdServer.py
### Define all the requried variable
username = 'braman'
password = 'weblogic'
url = 't3://localhost:7001'
mgdServerName = 'mgdserver1'
resourceType = 'Server'
listenAddress = 'egmgd1'
listenPort = 2001

### Connect to the Administration Server
connect(username, password, url)

### Get the Configuration Manager
cfgManager = getConfigManager()
try:
   cfgManager.getChanges()
   print '===> Currently there is a Session'
   if cfgManager.isEditor() == true:
       ### You are making changes!!!
       print '===> Looks like you started that session'
       print '===> You can check the console for any pending changes'
       print '===> Try rerunning this script after you release or commit the pending changes'
   exit()

except NotEditorException, e:
   if cfgManager.getCurrentEditor() is None:
   ### No session
       pass
   else:
       ### Someone else is making changes
       userWithSession = cfgManager.getCurrentEditor().replace(' ', '')
       print '===> Currently there is a Session'
       print '===> User \"' +userWithSession+'\" is making the changes'
       print '===> Wait until \"' +userWithSession+'\" complete the current session'
       exit()
   pass
except Exception:
   ### Other Errors
   print '===> Error, see log for more info'
   exit()


### Start a change session
edit()
startEdit()

### Create the Managed Server
create(mgdServerName, resourceType)
cd('/Servers/' + mgdServerName)
cmo.setListenPort(listenPort)
cmo.setListenAddress(listenAddress)
print '===> Created Managed Server - ' + mgdServerName

### Activate the changes
save()
activate()

### Disconnect from the Administration Server
disconnect()
exit()

To explain some tricky parts of the above script:

This is line of code is used to import the exception class
from weblogic.management.mbeanservers.edit import NotEditorException

To check whether you are holding on to a session currently you can use the following method on the configuration manager
cfgManager.isEditor()

To get the user who is currently making changes you use the getCurrentEditor method on the configuration manager
cfgManager.getCurrentEditor()

To get rid of all the white spaces you can use a replace method from the string class (this is Jython)
userWithSession = cfgManager.getCurrentEditor().replace(' ', '')


The above example works if you don't have a managed server named egmdg1. But if you already have a managed server in your domain with the same name then the script will fail with the following error:

weblogic.descriptor.BeanAlreadyExistsException: Bean already exists

You can handle that situation in couple of different ways. I shall continue on how to tackle that in my next post.

WLST-BP-2 Check for existing session before you start one

Variable Definitions In The Preamble [WLST scripting Best Practices (Part-1)]

With WLST becoming popular among WebLogic Administrator, there is an unsaid need to discuss the best practices with respect to WLST scripting. I am being asked to share information about WLST like an introductory/101 post. But I decided to start a series of post which might help WebLogic Administrators with some of the must follow best practices rather than writing some introductory post which might duplicate the documentation. For WLST documentation see here.

The common steps involved in a WLST script that is used to configure WebLogic Server are as follows:

1. Connect to server
2. Navigate to the respective location (MBean)
3. Modify the required properties
4. If more configuration needs to be modified continue Step-2
5. Else disconnect
6. Exit

The first of the series of best practices in authoring a WLST script is to define all the required variables at the beginning before connecting to the server. That way if any modifications must be done in the future it will be as easy as changing the variables defined at the beginning of the script. In the coming posts, I will talk about more of other best practices like writing a reusable WLST script, consuming information from the environment variables, exception handling, defensive scripting, avoiding to hard code critical information like username, password, url etc.

The usual variables are the username, password, url, resource names, attribute values etc. The following is an example of a script that defines all the required values as script variables which can avoid hardcoding and will also facilitate simple way to modify them in the future if required.

#CreateServer.py
#Define all the requried variable
username = 'system'
password = 'weblogic'
url = 't3://egAdm:7001'
serverName = 'mgdserver1'
listenAddress = 'egmgd1'
listenPort = '2001'

#Connect to the Administration Server
connect(username, password, url)

#Start a change session
edit()
startEdit()

#Create the Managed Server
create(serverName, 'Server')
cd('/Servers/' + serverName')
cmo.setListenPort(listenPort)
cmo.setListenAddress(listenAddress)

#Activate the changes
save()
activate()

#Disconnect from the Administration Server
disconnect()
exit()

The above script may not be authored using all the best practices now. But I will eventually build on the same example of creating a new Managed Server in my subsequent posts to address the other best practices as well. My next post will talk about how to check for existing change session before you start one with WLST.

WLST-BP-1 Define all the variables in the preamble