IBM WebSphere Developer Technical Journal: System management for WebSphere Application Server V6 -- Part 4

New AdminTask commands make wsadmin scripting less complex and more practical

The new AdminTask command feature in IBM® WebSphere® Application Server V6 simplifies the wsadmin command interface to reduce the effort required to automate WebSphere Application Server configuration and administration functions. This article, the fourth in a series, explores AdminTask features and commands, and explains how to use these commands to manage WebSphere Application Server easily and efficiently.

Share:

Qinhua Wang (qwang@us.ibm.com), Senior Software Engineer, IBM

Qinhua Wang is a senior software engineer with IBM working in the WebSphere Application Server development organization in Austin, Texas. She has been one of the leading developers on the WebSphere system administration team since WebSphere Application Server Version 3.5. The main focus of her work is WebSphere configuration.



John Chang (jchang3@us.ibm.com), Advisory Software Engineer, IBM

John Chang is an advisory software engineer with IBM working on WebSphere Application Server development in Austin. John worked on the WebSphere security team before joining the WebSphere Web Services team, where he works primarily on WebSphere Web services administration.



21 September 2005

From the IBM WebSphere Developer Technical Journal.

Introduction

IBM WebSphere Application Server V6 contains many significant enhancements in system management functionality over the previous release, Version 5. This article series explores the evolution of the product in this area, with each article focusing on the details related to a specific feature. The articles in this series so far include:

with additional installments on the way.


What is AdminTask?

The wsadmin scripting utility was introduced in IBM WebSphere Application Server V5 as a non-graphical administrative command interface using scripting languages. Jython and Jacl are the two scripting languages that are currently supported. The wsadmin utility extends basic scripting languages with the use of these WebSphere-specific objects:

  • AdminConfig for running configuration commands.
  • AdminApp for performing application administration.
  • AdminControl for running operational commands.

Using the wsadmin tool, administrators can configure, deploy, and manage elements of WebSphere Application Server the same as if the administrative console was being used instead. Furthermore, users can combine wsadmin commands with functionality native to the scripting language being used to develop scripts that also automate their own customized admin procedures.

The wsadmin utility is a very powerful tool through which you can tune virtually every knob that WebSphere Application Server provides -- that is, if you know which knob to tune and how to tune it, neither of which is very easy understand. To use AdminConfig, for example, you should understand the schema and directory structure of the configuration documents; to use AdminControl, you should know the JMX MBean types of the run time components before you can operate on them. In other words, there are a lot of low level details that administrators need to understand about WebSphere Application Server and the environment to really be able to use these commands effectively. In contrast, using the AdminApp object is much easier than using the others, since it provides commands that correlate directly to what users want to achieve (like "install" or "uninstall" an application) -- but AdminApp only provides application deployment capability. Overall, wsadmin presented something of a learning curve for Version 5 users.

Wouldn't it be nice if the ease of using AdminApp was extended to other administrative areas, like configuration and operations? The development of the new AdminTask object was rooted in that idea and debuted in WebSphere Application Server V6.0, providing user friendly and task-oriented commands for a very wide variety of administrative functions, with the same syntax as AdminApp commands. AdminTask commands also provide usability enhancements that help users actually find the proper command for what they want to do, understand the command, and learn the syntax.

Detailed information on AdminTask commands and syntax is available in the WebSphere Application Server V6 Information Center. In this article, therefore, we will look at the various features AdminTask commands provide through command and scripting examples, and offer guidance on how to manage your WebSphere Application Server environment effectively with these new commands.


Command syntax

Let's look a set of sample AdminTask commands to illustrate their basic syntax. First, you should know that you can access AdminTask commands the same way you would any other wsadmin commands. This means that you begin by issuing the following command (if you are using a Windows® platform):

LanguageCommand
Jythoncd <PROFILE_DIRECTORY>\bin .\wsadmin.bat -lang jython
Jacl.\wsadmin.bat -lang jacl (Jacl)

All AdminTask commands start with AdminTask." Each command addresses a specific administrative task and has a name that reflects what the command does. (By default, the profile directory will be under <PRODUCT_INSTALL_DIRECTORY>\profiles\<PROFILE_NAME>. See Part 3 in this article series for information on the concept of profiles and the profile directory. )

Commands without parameters

The simplest AdminTask commands are executed without parameters, and the syntax is basically AdminTask followed by the command name. For example, the command listServerTypes lists all the server types defined in the system. If you execute the following command in a Jython wsadmin interpreter shell:

wsadmin>print AdminTask.listServerTypes()

the result would be:

APPLICATION_SERVER
WEB_SERVER
GENERIC_SERVER

This syntax applies to any command that does not require additional parameters. Another example is:

LanguageCommand
Jythonwsadmin>print AdminTask.listServers()
Jaclwsadmin>$AdminTask listServers

and the output with either scripting language should be similar to this:

server1(cells/myHostCell/nodes/myHost/servers/server1|server.xml)
nodeagent(cells/myHostCell/nodes/myHost/servers/nodeagent|server.xml)
dmgr(cells/myHostCell/nodes/myHostCellManager/servers/dmgr|server.xml)

The output from the listServers command indicates there are three servers defined in the configuration: the deployment manager, a node agent, and an application server.

A word about formatting

Throughout this article, you will notice the use of print preceding the AdminTask command. This is not part of the command syntax; it merely formats the output for readability. Do not add "print" to AdminTask commands in a script file. Without print, the command in Jython would look like:

wsadmin>AdminTask.listServerTypes()

and the raw output without formatting would appear as:

'APPLICATION_SERVER\r\nWEB_SERVER\r\nGENERIC_SERVER'

Using Jacl as the scripting language, you could launch the wsadmin shell and execute the same command:

wsadmin>$AdminTask listServerTypes

and get the same output:

APPLICATION_SERVER
WEB_SERVER
GENERIC_SERVER

Jacl does not require using print for formatting.

Commands with parameters

The listServers command used above has an optional parameter "serverType" that lists all servers of a particular server type. Therefore, to see all servers that are application servers, we would specify the parameter value in the command:

LanguageCommand
Jythonwsadmin>print AdminTask.listServers('[-serverType APPLICATION_SERVER]')
Jaclwsadmin>$AdminTask listServers {-serverType APPLICATION_SERVER}

and see this output:

server1(cells/myHostCell/nodes/myHost/servers/server1|server.xml)

Additional parameters on the same command can be specified in a similar way. For example, adding a "nodeName" parameter lists the servers on only one specific node:

LanguageCommand
Jythonwsadmin>AdminTask.listServers('[-serverType APPLICATION_SERVER -nodeName myHost ]')
Jaclwsadmin>$AdminTask listServers {-serverType APPLICATION_SERVER -nodeName myHost}

In the commands above, "myHost" is the value for the "nodeName" parameter. If you need to specify additional parameters, just append them in the same way. This syntax applies to other commands that also take parameters.

Commands with target object

In addition to parameters, some AdminTask commands also take a target object, which is the target resource upon which the AdminTask command acts. The createApplicationServer command below creates an application server in the system and takes the node name as a target object. This command creates an application server named "testServer" on node name "myHost":

LanguageCommand
Jythonwsadmin>AdminTask.createApplicationServer('myHost', '[-name testServer ]')
Jaclwsadmin>$AdminTask createApplicationServer myHost {-name testServer}

Target object can be required or optional.


Get command information with built-in help

Need more information about a command before you use it? You can get command, target, and parameter information from the WebSphere Application Server V6 Information Center, but you can also use the built-in help provided by wsadmin with this command:

LanguageCommand
Jythonwsadmin>print AdminTask.help()
Jaclwsadmin>$AdminTask help

Use this additional parameter with the help command to get data on a specific command:

LanguageCommand
Jythonwsadmin>print AdminTask.help('COMMAND_NAME')
Jaclwsadmin>$AdminTask help COMMAND_NAME

If we substitute COMMAND_NAME with that value "createApplicationServer", you should see the following:

WASX8006I: Detailed help for command: createApplicationServer
Description: Command that creates a server
*Target object: The Node Name

Arguments:
  *name - The Server Name
  templateName - The Template Name
  genUniquePorts - Parameter to generate unique http ports for a server.
  templateLocation - The location where the template is stored. Use system defined 
location if it is not specified. Using system defined location is recommended.

Steps:
   ConfigCoreGroup - No description available

Most information presented by the built-in help facility is self explanatory, with an asterisk (*) indicating something that is required. Help information is localized and therefore accomodates many national languages. This help facility is intended to help you compose whatever AdminTask command you need to use, quickly and with the appropriate options.


Generate the proper syntax through interactive mode

Now that you know the syntax rules, we will point out that it is not critical that you remember them, since every AdminTask command has an -interactive option that lets you enter the target object and any parameters interactively. The wsadmin tool executes the command, asks you for specific values, and constructs the proper command syntax for you.

The format for using the interactive option is:

LanguageCommand
Jythonwsadmin>AdminTask.COMMAND_NAME('-interactive')
Jaclwsadmin>$AdminTask COMMAND_NAME -interactive

Below is a sample interactive execution of the createApplicationServer command, which generates a unique port number by default for a created server to avoid port conflicts when the server starts. In this example:

  • Bold type indicates user inputs.
  • {ret} represents the return key.
  • * indicates a required field. You can bypass entering a value for optional parameters by pressing the return key, as shown in the example below.
  • Parenthetical text indicates the parameter name.
  • Bracketed text indicates a parameter's default value.

This command has multiple steps, which we will look at in the next section. For now, we will bypass the steps and complete the command execution by selecting the Finish option.

Using Jython:

wsadmin>AdminTask.createApplicationServer('-interactive')[ret]
Create Server

Command that creates a server

*Node Name: myHost{ret}
*Server Name (name): testServer{ret}
Template Name (templateName): {ret}
Generate Unique Ports (genUniquePorts): [true] {ret}
template location (templateLocation): {ret}
Create Server
Command that creates a server
->  1. No description available (ConfigCoreGroup)

S (Select)
F (Finish)
C (Cancel)
H (Help)

Select [S, F, C, H]: [F] {ret}
WASX7278I: Generated command line: AdminTask.createApplicationServer(myHost, '[-name 
testServer ]')
'testServer(cells/myHostCell/nodes/myHost/servers/testServer|server.xml#Server_11242
32687936)'

Interactive mode execution is practical for several reasons, most notably:

  • It enables you to execute commands without knowing the actual command syntax, making it particularly handy if you only use wsadmin commands on occasion.

  • Interactive mode generates the proper command syntax for what you want to do, making it a good tool for learning commands, and for generating actual commands for use in your administrative scripting.

The AdminTask in Jacl supports the same capability and functions basically the same, with the main difference being that the generated command line is in Jacl.

Using Jacl:

wsadmin>$AdminTask createApplicationServer -interactive
Create Server

Command that creates a server

*Node Name: myHost{ret}
*Server Name (name): testServer{ret}
Template Name (templateName): {ret}
Generate Unique Ports (genUniquePorts): [true] false{ret}
template location (templateLocation): {ret}
Create Server

Command that creates a server

->  1. No description available (ConfigCoreGroup)

S (Select)
F (Finish)
C (Cancel)
H (Help)

Select [S, F, C, H]: [F] {ret}
WASX7278I: Generated command line: 
$AdminTask createApplicationServer myHost {-name testServer} 
testServer(cells/myHostCell/nodes/myHost/servers/testServer|server.xml#Server_11242351489
25)

AdminTask commands with multiple steps

Some administrative tasks are more involved than others, take more than a few parameters, and involve multiple flows (or steps) depending on choices users make. Some steps of a task can also take a table of data in which each column in the table maps to a parameter in the step. An example of this type of task might be application installation; the steps that users need to take will vary depending on the type of application, installation options chosen, the number of modules in each application, and so on. The notion of steps is very similar to the notion of tasks associated with AdminApp commands; in fact the syntax for AdminTask steps is the same as the syntax for AdminApp install and update commands.

We will look at the syntax of commands with steps from an interactive point of view first. If you only need to execute complex commands occasionally, interactive mode is probably the best execution option. Let's look at the interactive execution of the createApplicationServer command again, as we did in the previous section. This time, though, rather than finish, we will Select to execute the subsequent "ConfigCoreGroup" step:

Select [S, F, C, H]: [F] S{ret}
No description available (ConfigCoreGroup)
No description available (coregroupName):

Select [C (Cancel), E (Edit)]: [E] E{ret}

The last line shown above prompts you to either edit (E) the step parameters or cancel (C) to exit the step. Enter E to edit the step. The interactive display prompts for the name of the core group. You can enter DefaultCoreGroup, as shown below, or, since it is not required, press Enter to accept the default value. Steps with no required parameters are optional (which is why we were able to skip the step in the previoius section).

No description available (coregroupName): DefaultCoreGroup{ret}

Back at the main menu, select F for Finish. The resulting command syntax and the execution result displays, as shown below. The part of the command that represents the step appears bold.

Create Server
Command that creates a server
    1. No description available (ConfigCoreGroup)
->  End of task

F (Finish)
C (Cancel)
H (Help)
Select [F, C, H]: [F] {ret}
WASX7278I: Generated command line: AdminTask.createApplicationServer(myHost, '[-name 
testServer -ConfigCoreGroup [[DefaultCoreGroup]]]')
'testServer(cells/myHostCell/nodes/myHost/servers/testServer|server.xml#Server_11261
91505917)'

As you can see in this example, step parameters are specified like other parameters on the command except that the parameter name is replaced with the step name. However, some steps accept tables as input; in this case, the value of the parameter is a table:

  • The columns of the table correspond to the parameters of the step.
  • The table is formatted with two layers of brackets; the outer brackets encloses the entire table for the step; the inner brackets designate a row in the table.

If the step does not take a table as input, such as this example, then the syntax is equivalent to a table with a single row. All the parameter values of the step are specified in the proper sequence and separated with a space within the inner brackets. If any parameter value contains a space then the parameter value must be in double quotes. For example, if the core group name is "my core group", then the step command syntax would be:

AdminTask.createApplicationServer(myHost, '[-name testServer -ConfigCoreGroup [["my core group"]]]')

This format may seem like overkill and a bit complicated, but this syntax is consistent with AdminApp commands and makes the input more efficient when table data needs to be specified. However, you can always execute in interactive mode and not worry about whether you've missed any quotes.

If using Jacl, the syntax is similar to the Jython commands above, the main difference being the replacement of brackets with braces:

WASX7278I: Generated command line: $AdminTask createApplicationServer myHost {-name testServer -ConfigCoreGroup {{DefaultCoreGroup}}}


Finding the right AdminTask command to use

All the AdminTask commands are documented in the WebSphere Application Server V6 Information Center; search using the term "AdminTask commands". However, the built-in AdminTask help is provided to help you find the right command. To list all of the commands available:

LanguageCommand
Jythonwsadmin>$AdminTask help -commands
Jaclwsadmin>$AdminTask COMMAND_NAME -interactive

Of course, an alphabetical list of commands may not be all that helpful. To narrow down your search, the concept of a command group (in the next section) will be beneficial.

Using command groups

AdminTask commands are grouped based on their functionality, and so the main purpose of a command group is to associate related commands together so that commands can be found easily and intuitively; for example, the ServerManagement command group contains all the commands related to server management. Use this command to view a list of all defined command groups with a brief description:

LanguageCommand
Jythonwsadmin>print AdminTask.help('-commandgroups')
Jaclwsadmin>$AdminTask help -commandgroups

For a list of commands associated with a specific command group:

LanguageCommand
Jythonwsadmin>print AdminTask.help('COMMAND_GROUP_NAME')
Jaclwsadmin>$AdminTask help COMMAND_GROUP_NAME

For example, to display the names and descriptions of commands associated with the ServerManagement command group:

LanguageCommand
Jythonwsadmin>print AdminTask.help('ServerManagement')
Jaclwsadmin>$AdminTask help ServerManagement

Available AdminTask commands

You get a rough idea of the primary function areas covered by AdminTask commands by listing the command groups (above), but generally, they include server management, cluster management, J2C resource adapter, messaging related configuration, core group configuration, Web service and channel framework, and so on. However, if you are not able to find a command that you expect to be supported by AdminTask, keep in mind that since AdminTask was introduced in Version 6 of WebSphere Application Server, many of the new features and functions that became available with this release are the first to be supported by the AdminTask mechanism, while support for some existing features and functions from prior releases are still forthcoming.

Nonetheless, replacing AdminConfig or AdminControl commands is not the purpose of AdminTask; AdminConfig and AdminControl provide lower level interfaces with more complicated syntax while the AdminTask offers a higher-level mechanism to make common admin tasks easier.


Using AdminTask within wsadmin scripts

Since AdminTask commands are wsadmin commands, as are AdminConfig, AdminControl and AdminApp commands, they can be used together with (and in the same manner) as other wsadmin commands. For example, if you were to implement the common scenario of automating application configuration and deployment, you would execute the following tasks, which are accomplished with a variety of wsadmin commands:

  1. Create server (AdminTask)
  2. Modify configuration on the server (AdminConfig)
  3. Configure data source required by the application (AdminConfig)
  4. Configure messaging bus and destination for the application (AdminTask)
  5. Configure JMS resource required by the application (AdminTask)
  6. Install the application (AdminApp)
  7. Save (AdminConfig)
  8. Sync and start the server and application (AdminControl)

As more AdminTask commands become available, you may wish to replace parts of your script that currently use (for example) the more complex AdminConfig commands with any new applicable AdminTask commands to simplify your script and lower your maintenance cost.

Using variables in AdminTask commands

In interactive mode, literal parameter values are typically specified when executing AdminTask commands. When invoked from within a script, it is usually more desirable (and practical) to specify variables rather than literals. Variable names can be used with wsadmin commands the same as they can with any other built-in Jython and Jacl scripting commands. However, care must be given to AdminTask punctuation to avoid tricky problems.

In Jython, variables are directly referred to by name. However, all parameter values are enclosed in single quotes, which makes the contents within the quotes a literal string. The easiest way to refer to variables within the quotes is to break the string into pieces and concatenate them together with a plus sign (+). Using the createApplicationServer command as an example, we can replace myHost, testServer and DefaultCoreGroup with variables node, name and coregroup respectively, in a manner similar to Java code, as shown below:

wsadmin>node='myHost'
wsadmin>name='testServer'
wsadmin>coregroup='DefaultCoreGroup'
wsadmin>AdminTask.createApplicationServer(node, '-name ' + name + ' 
-ConfigCoreGroup [[' + coregroup + ']]]')

In Jacl, variables are referred to by $VARIABLE_NAME, and so you usually need only replace the literal value of a parameter with the appropriate $VARIABLE_NAME. However, the braces and double braces in the AdminTask syntax turn variable references into literal strings; this applies to other wsadmin commands with contain braces as well. The trick here is to execute a subst command in front of the most outer brace, which substitutes the variable reference with its actual values, regardless of how many layers of braces there are. Using the createApplicationServer command again, we can replace myHost, testServer and DefaultCoreGroup with variable node, name and coregroup, as shown below:

wsadmin>set name testServer
wsadmin>set node myHost
wsadmin>set coregroup DefaultCoreGroup
wsadmin>$AdminTask createApplicationServer $node [subst {-name $name -ConfigCoreGroup 
{{$coregroup}}}]

Conclusion

AdminTask commands, introduced in WebSphere Application Server V6, provide a set of high level, user friendly, task-oriented wsadmin commands. Simple syntax, a built-in help feature, and interactive execution capability make it easier to use these wsadmin commands in practical configuration and operation scenarios, and reduces the effort involved in automating these WebSphere Application Server functions. This article offered an introduction to these new commands with examples to help get you started managing your WebSphere Application Server environment more efficiently.

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=94257
ArticleTitle=IBM WebSphere Developer Technical Journal: System management for WebSphere Application Server V6 -- Part 4
publish-date=09212005