Command assistance simplifies administrative scripting in WebSphere Application Server

Command assistance is a feature that provides wsadmin commands in the Jython scripting language for various actions performed within the IBM® WebSphere® Application Server V7 administrative console. This article offers usage scenarios that could assist you in leveraging the full capabilities of this feature. Those who will benefit most from this information are administrators with beginner to intermediate experience with wsadmin and scripting. Those not familiar with command assistance will learn how to use it, store a history of commands, and make the commands generic through the use of variables.

Philippa Rhodes (prhodes@us.ibm.com), User Experience Engineer , IBM

Author photoPhilippa Rhodes has been a User Experience Engineer for WebSphere Application Server since graduating from The University of Georgia with a PhD in Computer Science, minor in Statistics, in 2007. She supports features related to systems management, virtualization, and SOA.



17 December 2008

Also available in Chinese

Introduction

During the development of IBM WebSphere Application Server V7, usability studies revealed the command assistance scenario to be of critical importance to users, emphasizing the heavy usage of scripting and the need to continue to provide quality scripting tools and assistance. Command assistance is a feature that provides wsadmin commands in the Jython scripting language for various actions performed within the WebSphere Application Server administrative console.

Command assistance was first made available in WebSphere Application Server V6.1 with limited support, providing commands for approximately 185 tasks. Due to customer requests and tremendous appreciation of the feature, coverage was increased and the number of supported commands more than quadrupled to over 750 supported tasks for V7.

Four wsadmin objects are provided for users to administer the WebSphere Application Server environment: AdminConfig, AdminTask, AdminApp, and AdminControl. Prior to command assistance, administrators tasked with writing scripts would often need to consult various resources to accurately identify the script components for the items they wanted to manipulate, including the appropriate command object, syntax, and parameters. With command assistance implemented in the administrative console, you (as the administrator) can simply complete tasks via the user interface one time, then retrieve and save the set of commands that was generated.

To help you leverage the full capabilities and get the most value from command assistance, this article explains the basics of using command assistance with some usage scenarios, and also looks at some specific features that might make your job a bit easier.

Using command assistance

Command assistance provides three ways to retrieve commands:

Generate a command using the console

The first method is the most basic use of command assistance. You launch the administrative console, perform an action, and access the command assistance panel, which displays the wsadmin command for that action.

Consider an example in which you want to create a new business-level application. As part of the application, you first need to import the application files into an asset repository. An asset can be considered a building block for composing a business-level application; it represents physical binaries and is the smallest unit of management for application contents in the business-level application architecture.

To import an asset using the administrative console:

  1. Expand the Applications section in the left navigation menu.
  2. Select New Application and then select New Asset.
  3. Specify the file, complete the required fields, and click Next. Figure 1 shows the summary panel that displays. Notice the Command Assistance area circled in red.
    Figure 1. Administrative console with command assistance
    Figure 1. Administrative console with command assistance
  4. Click View administrative scripting command for last action to launch a command assistance panel (Figure 2). This panel shows the wsadmin scripting command for importing an asset, provided in the Jython scripting language. You can now copy and paste the command directly into an active wsadmin session or into a file for future modification and use. When running these commands in wsadmin, make sure it is launched using Jython and from the /bin directory of the profile running the administrative console, as in:
    C:\IBM\WebSphere\AppServerGM\profiles\Dmgr01\bin> wsadmin -lang jython.
    Figure 2. Command assistance
    Figure 2. Command assistance

    Figure 2 also shows the command assistance preferences, enable command assistance notifications, and log command assistance commands. These options can be used to record a history of the commands, and are explained more in the next sections.

Maintain history with logging

The command assistance panel only displays command(s) for the last action performed in the console. However, you can enable the logging option to save all commands that were generated in a log file. The name of the file is commandAssistanceJythonCommands_<user name>.log and is stored within the log directory of the profile running the administrative console, for example:

C:\IBM\WebSphere\AppServerGM\profiles\Dmgr01\logs\dmgr\
commandAssistanceJythonCommands_phil.log

Logging for command assistance can be enabled either in the command assistance panel (Figure 2) or within the console preferences (Figure 3).

Figure 3. Console preferences
Figure 3. Console preferences

Continuing with the business-level application example, suppose you import one or more assets, create a new, empty business-level application, and then add assets or other nested business-level applications to it. Listing 1 shows a sample of some of the commands captured in a log file that are necessary to complete this task.

Listing 1. Sample content of a command assistance log file
# [10/31/08 0:03:11:396 EST] Assets > Assets
AdminTask.importAsset('[-storageType FULL -source C:/IBM/WebSphere/AppServerGM/profiles/
Dmgr01/wstemp/null/upload/login.ear -AssetOptions [[login.ear login.ear defaultbinding.
virtual.host#defaultbinding.force "" "" "WebSphere:spec=Java EE ear" "" .*\.dll=755#.*\
.so=755#.*\.a=755#.*\.sl=755 false]]]')

# [10/31/08 0:04:01:489 EST] BLAManagement
AdminTask.listBLAs('[-includeDescription true ]')

# [10/31/08 0:04:45:146 EST] Business-level applications > New
AdminTask.createEmptyBLA('[-name DefaultApp_BLA -description "Sample BLA adding log-in
capability to DefaultApplication." ]')

# [10/31/08 0:05:37:552 EST] Business-level applications > DefaultApp_BLA > Add
AdminTask.listAssets('[-includeDescription true -includeDeplUnit true -assetID login.
ear ]')

# [10/31/08 0:05:57:114 EST] Business-level applications > DefaultApp_BLA > Add
AdminApp.install('C:/IBM/WebSphere/AppServerGM/profiles/Dmgr01/logs/app2467.ear', '[  
-nopreCompileJSPs -distributeApp -nouseMetaDataFromBinary -nodeployejb -appname 
LoginApplication -createMBeansForResources -noreloadEnabled -nodeployws -validateinstall 
warn -noprocessEmbeddedConfig -filepermission .*\.dll=755#.*\.so=755#.*\.a=755#.*\.
sl=755 -noallowDispatchRemoteInclude -noallowServiceRemoteInclude -blaname WebSphere:
blaname=DefaultApp_BLA -asyncRequestDispatchType DISABLED -nouseAutoLink -MapWebModToVH 
[[ LoginWebApp login.war,WEB-INF/web.xml default_host ]]]' )

# [10/31/08 0:06:59:208 EST] Business-level applications > DefaultApp_BLA > Add
AdminTask.addCompUnit('[-blaID WebSphere:blaname=DefaultApp_BLA -cuSourceID WebSphere:
blaname=DefaultApplication -CUOptions [[WebSphere:blaname=DefaultApp_BLA WebSphere:
blaname=DefaultApplication DefaultApplication_0001 "" 1]]]')

# [10/31/08 0:08:26:442 EST] Adding asset to repository
AdminConfig.save()

# [10/31/08 0:09:41:708 EST] Business-level applications
AdminTask.startBLA('[-blaID WebSphere:blaname=DefaultApp_BLA ]')

Application deployment is a very common task for WebSphere Application Server users, but since the concept of a business-level application (and its associated commands) is new in V7, the ability to generate this set of commands in just a few minutes attests to the value and efficiency of the command assistance feature. The command assistance log file in Listing 1 shows a set of actions necessary to create, save, and start a new business-level application. The first line of each log entry consists of a timestamp and the location within the console where the command was generated. This log file shows:

  • How to import an asset with the AdminTask.importAsset command.
  • How to create a new application with the AdminTask.createEmptyBLA command.
  • The next actions, AdminApp.install (adds the login.ear asset) and AdminTask.addCompUnit, are used to build the business-level application.
  • The remaining two commands simply show how to save and start the new application.

Send commands to a scripting tool

You can also use command assistance notifications to automatically save the command output. WebSphere Application Server uses Java Management Extensions (JMX) notifications to send commands to compatible Jython editors.

Configuring command assistance notifications

For the purpose of this article, IBM Rational Application Developer for WebSphere Software 7.5 is the IDE used in this example. To use Rational Application Developer with the administrative console:

  1. You must associate an application server with the IDE tool by creating a pointer from the tool’s workbench to a server. If administrative security is enabled for the WebSphere Application Server profile, you will be required to authenticate to the server from Rational Application Developer. You must provide the same username and password for both the server and the tool, because the tool will only receive commands from that authenticated console user.
  2. In the WebSphere Application Server administrative console, make sure Enable command assistance notifications is selected and the change applied, either in the command assistance panel (Figure 2) or in the console preferences (Figure 3).
  3. From the servers view in Rational Application Developer, launch the WebSphere Administration Command Assist window for the associated server.
  4. Return to WebSphere Application Server admin console and perform tasks.

As commands are generated by the console, they appear in the WebSphere Administration Command Assist view of Rational Application Developer (Figure 4). The commands that are shown in this view can be inserted into any part of any Jython file simply by placing the cursor in the desired location in the file, right-click the command, and selecting Insert (Figure 4).

Figure 4. Command assist window in Rational Application Developer
Figure 4. Command assist window in Rational Application Developer

Using command assistance with variables

The commands generated throughout the administrative console provide the correct wsadmin object type, function, syntax, properties, and sample values for creating and manipulating items in the environment. They are a great starting point if you are a novice wsadmin script writer, or if you need to write scripts for new features.

The sample commands in Figure 4 for listing and modifying ports was inspired by a customer who needed listings of sets of items associated with each server; for example, ports, applications, resources, and so on. With an environment that contained more than 70 servers, a script was absolutely necessary. To show you how to create a script to list all resources (such as JDBC drivers) for each server, the steps below describe the procedure for generating commands for a script file. Although this is a fairly simple exercise, doing so will show how you can combine commands generated by command assistance with basic capabilities of Jython to create a solution that accommodates a specific need.

For this example, your requirement is to obtain commands that list all your WebSphere Application Servers, plus all the JDBC drivers for each server. The cell for this example consists of a deployment manager and three servers.

In the deployment manager’s administrative console:

  1. Navigate to Servers => Server Types => WebSphere application servers. The center portion of the panel displays a list of such servers in the cell.
  2. If neither command assistance logging nor notifications is enabled, click the View administrative scripting command for last action link to retrieve, copy, and save the command.
  3. The following command is displayed:
    AdminTask.listServers('[-serverType APPLICATION_SERVER ]')
  4. Navigate to Resources => JDBC => JDBC providers. The center portion of the panel displays a list of such providers in the cell.
  5. Change the scope to one of the servers:
    Node=T60P-2007-CQ8Node03, Server=server1
  6. If neither command assistance logging nor notifications is enabled, click the View administrative scripting command for last action link to retrieve, copy, and save the command.
  7. A command similar to the following is displayed:
    AdminConfig.list('JDBCProvider', AdminConfig.getid( '/Cell:T60P-	
    2007-CQ8Cell01/Node:T60P-2007-CQ8Node03/Server:server1/'))

These two commands can now be combined with other Jython code to produce a listing of the desired JDBC providers for each server. To run the script, launch wsadmin with the file option and the file name specified, as in:

wsadmin -f c:\IBM\AppServer_list_jdbc.py

A sample script is shown in Listing 2. (Jython does not use line numbers, but this example shows them strictly for explanatory purposes.)

Listing 2. Contents of a script file combining commands and Jython scripting language
1  appServers = AdminTask.listServers('[-serverType APPLICATION_SERVER ]').splitlines()
2 
3  for appServ in appServers:   
4    print appServ
5    jdbc = AdminConfig.list('JDBCProvider', appServ) 
6    print jdbc

Line 1 uses splitlines(), a string function, to separate the list of servers, and then these values are stored as a variable, appServers. The values stored in this list for each server is a unique identification. Lines 3-6 iterate through the list and, for each server, prints its ID (Line 4), retrieves a list of all JDBC providers scoped within that server (Line 5), and then prints the properties and values of each provider (Line 6). See Listing 3 for sample output. Notice that in Line 5 the command generated by command assistance has been slightly modified to be more generic; instead of retrieving the ID of a specific server, it can now be given any value held by the appServ variable.

Listing 3. Partial output from the script file
server3(cells/T60P-2007-CQ8Cell01/nodes/T60P-2007-CQ8Node03/servers/server3|server.xml)
"Derby JDBC Provider (XA)(cells/T60P-2007-CQ8Cell01/nodes/T60P-2007-CQ8Node03/servers/
	server3|resources.xml#builtin_jdbcprovider)"
[classpath ${DERBY_JDBC_DRIVER_PATH}/derby.jar]
[description "Built-in Derby JDBC Provider (XA)"]
[implementationClassName org.apache.derby.jdbc.EmbeddedXADataSource]
[isolatedClassLoader false]
[name "Derby JDBC Provider (XA)"]
[nativepath []]
[providerType "Derby JDBC Provider (XA)"]
[xa true]
server1(cells/T60P-2007-CQ8Cell01/nodes/T60P-2007-CQ8Node03/servers/server1|server.xml)
		...

Other wsadmin commands, such as AdminConfig.showall(), or various other Jython capabilities and functions, such string manipulation functions, can be used to retrieve, modify, or format command assistance output, as desired.

Conclusion

The purpose of this article was to increase awareness of the command assistance feature, a Jython scripting assistance tool, in WebSphere Application Server, and to provide examples to demonstrate both built-in and external solutions to address your administrative requirements.

Scripting is used heavily by those who administer large environments, and by those who perform commonly repeated tasks. There is not a great deal of consistency between the syntax, functions, and naming conventions of the four wsadmin command objects. Identifying the accurate commands to complete the desired actions and constructing scripts for wsadmin can sometimes be a challenging and time-consuming task, especially for novice to intermediate script developers. Command assistance simplifies this process considerably and improves efficiency at the same time.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=358208
ArticleTitle=Command assistance simplifies administrative scripting in WebSphere Application Server
publish-date=12172008