If you're a WebSphere administrator or if you're trying to automate some tasks around the IBM WebSphere line of products, you'll inevitably be using WAS scripting (a.k.a. "wsadmin"). For the record, it is also possible to use Java and JMX-based APIs for automation, but it's is more complex and less documented. So "wsadmin" scripting tool is the primary tool of trade for any WebSphere administrator.

There are several things that you need to do in order to be successful with wsadmin:

• Learn Python. Wsadmin uses Python as a language (JACL was deprecated a long time ago and should not be used) and relies on jython. Jython provides full implementation of Python language sans some libraries. Needless to say that good knowledge of Python is essential for developing wsadmin scripts. Most WebSphere admins have Java background. In my opinion (and speaking from personal experience), knowing Java does more harm than good for a Python developer. Java people usually speak Python "with accent" and have a hard time properly utilizing all python capabilities such as closures, list comprehensions and even modules and packages. It's no wonder, the two languages are very different. For example, in Java everything is a class and in most cases a class resides in its own file. In Python a module can encompass multiple classes and classes themselves are completely optional. Learning how to properly use modules and classes takes some mental shift.

• Invest in designing your scripts. I'm not even sure if "scripting" is the right word to use in this context. Scripts are usually relatively simple. Wsadmin scripts are anything but. A seemingly simple task of application deployment may require many lines of code if you want to do it right. Unless you're really trying to do something unsophisticated (e.g., setting heap size), you'll be developing a full-blown python application. Therefore, you'll need to think about its design. Python has excellent support for modules. You'll have at least one module in your application. Do not put any logic into the "main" file that you'll be calling from wsadmin. Instead, define appropriate functions and classes in your modules and call them from the main file.

• Invest in setting up your development environment. Notepad or vi are not going to cut it. Remember, Python lacks compiler, so the only way to find out if your code is even syntactically correct is to execute it. That is, unless you use an IDE, such as PyDev. The latest version of PyDev is very good at detecting syntax errors and many other issues, such as uninitialized variables. It also has very decent (for a dynamic language) code completion.
  You will also need to setup your wsadmin shell script to supply python path (using -javaoption "-Dpython.path=your_path"). Do not forget to put python libraries (the ones that come with jython) on the python path. I prefer using thin administration client as this is more flexible. I also use 2.2.1 version of jython since jython 2.1 that comes with wsadmin is just too old and misses a lot of important language features.
  Another practical piece of advice is to never use "wsadmin -f" to test your scripts. Wsadmin takes eternity to come up, so running it every time you want to run your scripts is simply counterproductive. Instead, load it once and then run your script using Python "execfile" function. Don't forget to call reload function for all modules that are part of your applications, otherwise you won't see the changes until your re-start wsadmin.

• Help function is your best friend, so learn how to use it. I'm talking about the "help" function available for all key wsadmin modules (AdminConfig, AdminControl, etc). Wsadmin APIs, in my opinion, are poorly organized and difficult to learn. Ten thousand options available for AdminApp.install function is an example of that. Also, "lists of lists" data structures used by AdminTask and AdminApp are truly baffling. In any event, I usually run a separate wsadmin window that I use solely for consulting "help". This is much faster than searching for the same information in InfoCenter.

• Finally, you will need a testing environment. You can do some development using a standalone WAS installation but eventually you'll need to test your code against a Network Deployment environment with deployment manager and, ideally, multiple servers and multiple nodes. In other words, your test environment should resemble the target environments where you're going to run your scripts. There are many things that are impossible to test with just a standalone profile, one such example is node synchronization.

This post is part of the series on WebSphere Application Server administration. Please subscribe to our blog if you'd like to receive updates.

Note: We offer professional services in the area of WebSphere architecture, implementation and operations. If you're looking for help with any of these tasks, please let us know.

Most people assume that in order to run WAS admin scripts, you need to have full WAS installation available on the client machine. This is not correct. Starting with WAS 6.1, it is possible to use the so-called administration thin client instead.

The thin client has many benefits:

• The client consists of only two jars approximately 33MB in size, so you can set it up anywhere. With the traditional wsadmin client, you have to get WAS installed on your machine just so you can run wsadmin scripts. This is especially tedious if you have to deal with multiple versions of WebSphere products (and most large organizations have WAS versions in parallel). With the thin client you can just copy the two jars from an existing WAS installation onto a client machine. The only catch is that IBM JDK (or, more precisely, a JDK containing IBM security provider -- on Sun and HP-UX WAS actually comes with the Sun JDK) is still required. You can copy it from an existing install as well (I hope it doesn't violate any licensing terms).

• Since the client's size is so small, you can add it to your version control or to your Maven repository. This makes the build more repeatable for developers (your build does include deploying to the application server and running tests against it, doesn't it?).

• The shell script to run the thin client could be easily customized. For example, you may want to add some Java classes to wsadmin classpath. This will make it possible to invoke these classes from your wsadmin scripts. Or you may want to use a more modern jython version for your scripts. In fact IBM does't supply a shell script with the thin client, they just provide an example .

You'll need to make sure that you update your client jars whenever the server installation is upgraded.

Oh, and if you're using WebSphere ESB/Process Server and want to utilize some of WESB-specific admin tasks (available from AdminTask object), you're out of luck; the thin client will not support those.

This post is part of the series on WebSphere Application Server administration. Please subscribe to our blog if you'd like to receive updates.

Note: We offer professional services in the area of WebSphere architecture, implementation and operations. If you're looking for help with any of these tasks, please let us know.

Setting maximum heap size and changing other JVM parameters is a fairly common administration task. JVM configuration might be changing quite often during application development, usually as a result of performance testing.

Typically JVM parameters have to be updated for all application servers in a cell or at least for application servers that belong to a particular cluster.

Conveniently, WebSphere Application Server (WAS) supports updating JVM parameters using its administration APIs, specifically, AdminConfig object. This is illustrated by the script below.

import sys

"""
Change JVM heap size for all application servers in a cell
"""
# New heap size is passed as a parameter to the script
max_heap_size=sys.argv[0]

# Get the string with config ids of all serves
server_confids=AdminConfig.list("Server")
# Iterate over all servers - config ids are separated by \n 
for server_confid in server_confids.split("\n"):
    server_confid=server_confid.strip()
    # obtain the type - types are APPLICATION_SERVER, DEPLOYMENT_MANAGER, NODE_AGENT, WEB_SERVER
    server_type=AdminConfig.showAttribute(server_confid, "serverType")
    # we're changing the heap size for application servers - we want to exclude node agents, etc.
    if server_type == "APPLICATION_SERVER":
        server_name=AdminConfig.showAttribute(server_confid, "name")
        # this is the query to get JavaVirtualMachine configuration object for a particular server
        jvm_path="/Server:%s/JavaProcessDef:/JavaVirtualMachine:/" % server_name
        jvm_confid=AdminConfig.getid(jvm_path)
        # "modify" accepts  a list of lists - each list contains name and value (odd choice I must say, why not use tuples?)
        AdminConfig.modify(jvm_confid, [["maximumHeapSize", max_heap_size]])

# Commit our changes to the repository        
AdminConfig.save()

This post is part of the series on WebSphere Application Server administration. Please subscribe to our blog if you'd like to receive updates.

Note: We offer professional services in the area of WebSphere architecture, implementation and operations. If you're looking for help with any of these tasks, please let us know.

There are many instances when it is necessary to find members (servers) that constitute a cluster. For example, to script starting and stopping an application, we need to know names of servers and nodes where the application is installed. Or we may want to restart all members of a cluster after some configuration change.

As always, this is easy to do when you know what you're doing. A query-like activity in WAS environment usually heavily relies on AdminConfig object. Our example is no exception:

import sys

"""
List application servers that belong to a particular cluster
Cluster name is passed as a parameter to the script
"""
cluster_name=sys.argv[0]

# Get configID of the cluster
cluster_conf_id = AdminConfig.getid("/ServerCluster:"+cluster_name )
if not cluster_conf_id:
    raise "Cluster %s does not exist!" % cluster_name

# Get confids of the cluster members
member_conf_ids = AdminConfig.showAttribute(cluster_conf_id, "members")
# AdminConfig returns the list in [], get rid of the brackets
member_conf_ids = member_conf_ids[1:-1]
print "Cluster %s has following members:" % cluster_name  
# split by space
for member_conf_id in member_conf_ids.split():
    # Obtain server name and node name
    member_name=AdminConfig.showAttribute(member_conf_id, "memberName")
    node_name=AdminConfig.showAttribute(member_conf_id, "nodeName")
    print node_name+"/"+member_name

Now we can do a lot of useful things with node_name and member_name variables; for example, we can try to get an MBean of this server and check its state. Or we can attempt to restart it. I will cover this in one of the future posts.

This post is part of the series on WebSphere Application Server administration. Please subscribe to this blog if you'd like to receive updates.

It is often desirable to "push" configuration changes to nodes in the cell without having to wait for the periodic node sync process to kick in. This becomes a requirement if you want to run some kind of automated testing as part of your configuration/deployment process (which is a very good practice). For example, you may have a build process which runs HTTPUnit tests immediately after the change.

In this case, you really don't want to rely on any artificial "sleeps" and delays in your script, so triggering synchronization programmatically is the best option.

This is actually quite simple to accomplish, as illustrated by the following script:

"""
Sync configuration changes with nodes
"""

# Commit changes to the configuration repository 
AdminConfig.save()

# Obtain deployment manager MBean
dm=AdminControl.queryNames("type=DeploymentManager,*")

# "syncActiveNodes" can only be run on the deployment manager's MBean, 
# it will fail in standalone environment
if dm:
    print "Synchronizing configuration repository with nodes. Please wait..."
    # Force sync with all currently active nodes
    nodes=AdminControl.invoke(dm, "syncActiveNodes", "true")
    print "The following nodes have been synchronized: "+str(nodes)
else:
    print "Standalone server, no nodes to sync"

This post is part of the series on WebSphere Application Server administration. Please subscribe to this blog if you'd like to receive updates.

AdminContol and AdminConfig are two key scripting objects that any WAS administrator must know by heart.

The objects are available from wsadmin WAS administration tool.

AdminConfig provides an interface to the WAS configuration repository available under profile_root/config. All AdminConfig services are provided by the Deployment Manager (assuming you're connecting remotely); there is no dependency on node agents.

AdminControl provides an interface to JMX managed beans (MBeans) in your WAS environment. In general, MBeans are only available for the resources that are running. For example, if an application server is down, the corresponding MBean will not be available.

AdminConfig and AdminContol could complement each other nicely, especially when you need to find out the status of "things" in a WAS cell. To illustrate the point, here is a simple script that prints the status of all application servers within a cell:

"""
List all application servers in a cell and print their status (up or down)
"""

# Get the string with config ids of all serves
server_confids=AdminConfig.list("Server")
#Iterate over all servers - config ids are separated by \n 
for server_confid in server_confids.split("\n"):
    server_confid=server_confid.strip()
    # obtain the type - types are APPLICATION_SERVER, DEPLOYMENT_MANAGER, NODE_AGENT, WEB_SERVER
    server_type=AdminConfig.showAttribute(server_confid, "serverType")
    
    # we are only interested in application servers
    if server_type == "APPLICATION_SERVER":
        # obtain the name of the server
        server_name=AdminConfig.showAttribute(server_confid, "name")
        print "Checking the state of the server %s of type %s" % (server_name, server_type) 
        
        #Now we can try to get the mbean of the server. We could've used AdminConfig.getObjectName() as 
        #a shortcut, but for the sake of the example we'll use AdminControl explicitly
        
        # Query to search for mbeans - note the wildcard at the end to match the rest of mbean parameters
        # Note that we're simplifying a little bit since we're ignoring node names -
        # server names may not be unique within cell  
        server_query="type=Server,name=%s,*" % server_name
        server_mbean=AdminControl.queryNames( server_query )
        # AdminContol returns None if there is no running mbean for this server
        if server_mbean:
            print "Server is up"
        else:
            print "Server is down!"

This post is part of the series on WebSphere Application Server administration. Please subscribe to this blog if you'd like to receive updates.