CA Workload Automation Application Services Agent

CA Workload Automation Application Services Agent Implementation Guide r11.3 This Documentation, which includes embedded help systems and electroni...
Author: Oliver Johnson
37 downloads 0 Views 917KB Size
CA Workload Automation Application Services Agent

Implementation Guide r11.3

This Documentation, which includes embedded help systems and electronically distributed materials, (hereinafter referred to as the “Documentation”) is for your informational purposes only and is subject to change or withdrawal by CA at any time. This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. This Documentation is confidential and proprietary information of CA and may not be disclosed by you or used for any purpose other than as may be permitted in (i) a separate agreement between you and CA governing your use of the CA software to which the Documentation relates; or (ii) a separate confidentiality agreement between you and CA. Notwithstanding the foregoing, if you are a licensed user of the software product(s) addressed in the Documentation, you may print or otherwise make available a reasonable number of copies of the Documentation for internal use by you and your employees in connection with that software, provided that all CA copyright notices and legends are affixed to each reproduced copy. The right to print or otherwise make available copies of the Documentation is limited to the period during which the applicable license for such software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed. TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION “AS IS” WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE. The use of any software product referenced in the Documentation is governed by the applicable license agreement and such license agreement is not modified in any way by the terms of this notice. The manufacturer of this Documentation is CA. Provided with “Restricted Rights.” Use, duplication or disclosure by the United States Government is subject to the restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)(3), as applicable, or their successors. Copyright © 2010 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.

CA Technologies Product References This document references the following CA Technologies products: ■

CA Process Automation



CA Workload Automation AE



CA Workload Automation Agent for Application Services (CA WA Agent for Application Services)



CA Workload Automation Agent for Databases (CA WA Agent for Databases)



CA Workload Automation Agent for i5/OS (CA WA Agent for i5/OS)



CA Workload Automation Agent for Linux (CA WA Agent for Linux)



CA Workload Automation Agent for Micro Focus (CA WA Agent for Micro Focus)



CA Workload Automation Agent for Microsoft SQL Server (CA WA Agent for Microsoft SQL Server)



CA Workload Automation Agent for Oracle E-Business Suite (CA WA Agent for Oracle E-Business Suite)



CA Workload Automation Agent for PeopleSoft (CA WA Agent for PeopleSoft)



CA Workload Automation Agent for Remote Execution (CA WA Agent for Remote Execution)



CA Workload Automation Agent for SAP (CA WA Agent for SAP)



CA Workload Automation Agent for UNIX (CA WA Agent for UNIX)



CA Workload Automation Agent for Web Services (CA WA Agent for Web Services)



CA Workload Automation Agent for Windows (CA WA Agent for Windows)



CA Workload Automation CA 7 Edition



CA Workload Automation DE



CA Workload Automation Desktop Client (CA WA Desktop Client)



CA Workload Automation ESP Edition



CA Workload Control Center

Contact CA Technologies Contact CA Support For your convenience, CA Technologies provides one site where you can access the information that you need for your Home Office, Small Business, and Enterprise CA Technologies products. At http://ca.com/support, you can access the following resources: ■

Online and telephone contact information for technical assistance and customer services



Information about user communities and forums



Product and documentation downloads



CA Support policies and guidelines



Other helpful resources appropriate for your product

Providing Feedback About Product Documentation If you have comments or questions about CA Technologies product documentation, you can send a message to [email protected]. To provide feedback about CA Technologies product documentation, complete our short customer survey which is available on the CA Support website at http://ca.com/docs.

Contents Chapter 1: Introduction

9

Intended Audience ....................................................................................................................................................... 9 Agents and Agent Plug-ins ........................................................................................................................................... 9 CA WA Agent for Application Services ....................................................................................................................... 10 Job Types Supported by CA WA Agent for Application Services ................................................................................ 11

Chapter 2: Implementation Checklist

13

How to Install and Configure CA WA Agent for Application Services ........................................................................ 13 Deciding Whether to Create an Alias ......................................................................................................................... 14

Chapter 3: Installing the Agent Plug-in

15

CA WA Agent for Application Services Installation Options ....................................................................................... 15 Controlling the Agent Plug-in ..................................................................................................................................... 15 Install CA WA Agent for Application Services ............................................................................................................. 16 Configure the Agent Plug-in to Run POJO Jobs .......................................................................................................... 17 How to Remove the Agent Plug-in ............................................................................................................................. 17 Disable CA WA Agent for Application Services ................................................................................................... 18 Remove the Agent Plug-in from the Scheduling Manager .................................................................................. 19

Chapter 4: Your Scheduling Manager and the Agent Plug-in

21

Configuring the Scheduling Manager to Work with the Agent Plug-in ...................................................................... 21 Running a Verification Test ........................................................................................................................................ 21

Chapter 5: Configuring the Agent Plug-in

23

How to Configure Agent Parameters ......................................................................................................................... 23 Configure Agent Parameters on the Agent ......................................................................................................... 23 Configure Agent Parameters on the Scheduling Manager.................................................................................. 24 CA WA Agent for Application Services Parameters in the agentparm.txt File ........................................................... 24 How to Set Up an Alias for the Agent Plug-in ............................................................................................................. 25 Create an Alias for the Agent Plug-in .................................................................................................................. 25 Configuring an Alias on the Scheduling Manager ............................................................................................... 26 Configure SSL and Secure HTTP.................................................................................................................................. 26 Configure the Agent Plug-in for a Proxy ..................................................................................................................... 26 Persist Consumed JMS Subscribe Messages .............................................................................................................. 28

Contents 5

Chapter 6: Configuring the Agent Plug-in to Work with an Application Server

29

Prerequisites and Assumptions .................................................................................................................................. 29 How to Set Up the Agent Plug-in for WebLogic ......................................................................................................... 30 Collect the WebLogic and Client JARs ................................................................................................................. 30 Configure the Agent Plug-in for WebLogic .......................................................................................................... 31 Testing the WebLogic Setup ................................................................................................................................ 31 How to Set up the Agent Plug-in for WebSphere (EJB Jobs only) .............................................................................. 32 Collect the WebSphere and Client JARs .............................................................................................................. 33 Configure the Agent Plug-in for WebSphere....................................................................................................... 34 Testing the WebSphere Setup ............................................................................................................................ 35 How to Set Up the Agent Plug-in for WebSphere MQ (JMS Messaging only) ............................................................ 35 Collecting the WebSphere MQ and Client JARs .................................................................................................. 35 Collecting Your WebSphere MQ Queue Connectivity Information..................................................................... 36 Obtaining the WebSphere MQ JMS Administration Tool ................................................................................... 36 Setting Up a JNDI Provider .................................................................................................................................. 37 Collecting the JNDI Provider JARs ....................................................................................................................... 37 Configure the Agent for the JNDI Provider ......................................................................................................... 38 Defining the JNDI Connectivity Parameters ........................................................................................................ 38 Store the JNDI Information Using JMSAdmin ..................................................................................................... 40 Configure the Agent Plug-in for WebSphere MQ ................................................................................................ 42 Testing the WebSphere MQ Setup...................................................................................................................... 43 How to Set Up the Agent Plug-in for WebSphere and WebSphere MQ (EJB Jobs and JMS Messaging) ................... 44 How to Set Up the Agent Plug-in for JBoss ................................................................................................................ 44 Collect the JBoss and Client Jars ......................................................................................................................... 45 Configure the Agent Plug-in for JBoss ................................................................................................................. 45 Testing the JBoss Setup ....................................................................................................................................... 46 How to Set Up the Agent Plug-in for Oracle Application Server ................................................................................ 46 Collecting the Oracle and Client JARs.................................................................................................................. 47 Configure the Agent Plug-in for Oracle ............................................................................................................... 47 Testing the Oracle Setup ..................................................................................................................................... 48

Chapter 7: Troubleshooting the Agent Plug-in

49

Diagnosing Failed Jobs ............................................................................................................................................... 49 JMS Job Failure Messages .......................................................................................................................................... 49

Chapter 8: Related Documentation

53

CA Workload Automation AE Documentation ........................................................................................................... 53 CA Workload Automation DE Documentation ........................................................................................................... 54 CA Workload Automation ESP Edition Documentation ............................................................................................. 54

6 Implementation Guide

CA Workload Automation CA 7 Edition Documentation ............................................................................................ 55

Index

57

Contents 7

Chapter 1: Introduction This section contains the following topics: Intended Audience (see page 9) Agents and Agent Plug-ins (see page 9) CA WA Agent for Application Services (see page 10) Job Types Supported by CA WA Agent for Application Services (see page 11)

Intended Audience This document is for system administrators who are responsible for upgrading, installing, and configuring agents. You require knowledge of the operating system where the agent is installed and any third-party products or software technology that the agent uses. Notes: ■

The term Windows refers to any Microsoft Windows operating system supported by the agent.



The UNIX instructions in this document also apply to Linux systems unless otherwise noted.

Agents and Agent Plug-ins Agents are the key integration components of CA Technologies workload automation products. Agents let you automate, monitor, and manage workload on all major platforms, applications, and databases. To run workload on a particular system, you install an agent on that system. If your workload must run on a UNIX computer, for example, you can install and configure the CA WA Agent for UNIX. The agent lets you run UNIX scripts, execute UNIX commands, transfer files using FTP, monitor file activity on the agent computer, and perform many other tasks. You can extend the functionality of the agent by installing one or more agent plug-ins in the agent installation directory. If you have a relational database such as Oracle, for example, you can install a database agent plug-in to query and monitor the database. Other agent plug-ins are also available. For more information about agent plug-ins, see the Implementation Guide for the appropriate agent plug-in. Note: The agent plug-ins are only available for UNIX, Linux, and Windows operating environments.

Chapter 1: Introduction 9

CA WA Agent for Application Services

Example: Workload with Different Types of Jobs The following workload contains z/OS jobs, a UNIX job, an SAP job, and a Windows job, running on different computers, in different locations, and at different times:

CA WA Agent for Application Services The CA WA Agent for Application Services lets a user perform tasks such as the following:

10 Implementation Guide



Make simple calls to J2EE session and entity beans



Publish messages to J2EE JMS queues and topics



Monitor messages from J2EE JMS queues and topics



Directly invoke methods on Java classes in the agent class path



Make Java Remote Method Invocation (RMI) calls



Make an HTTP/HTTPS query or call on a servlet

Job Types Supported by CA WA Agent for Application Services

Job Types Supported by CA WA Agent for Application Services With the CA WA Agent for Application Services, you can define and run the following types of jobs: Entity Bean Lets you create an entity bean, update the property values of an existing entity bean, or remove an entity bean from the database. HTTP Lets you invoke a program over HTTP or HTTPS in a similar way to a web browser. For example, you can use the HTTP job to invoke a CGI script, a Perl script, or a servlet. The HTTP job sends a URL over HTTP using the GET method or a form over HTTP using the POST method. JMS Publish Lets you send a message to a queue or publish a message to a topic on a JMS server. JMS Subscribe Lets you consume messages from a queue or topic on a JMS server. JMX-MBean Attribute Get Lets you query a JMX server for the value of an MBean attribute. The returned value is stored on the computer where the Application Services agent plug-in resides. JMX-MBean Attribute Set Lets you change the value of an MBean attribute on a JMX server. JMX-MBean Create Instance Lets you create an MBean on a JMX server. JMX-MBean Operation Lets you invoke an operation on an MBean on a JMX server. JMX-MBean Remove Instance Lets you remove an MBean from a JMX server. JMX-MBean Subscribe Lets you monitor an MBean for a single notification or monitor continuously for notifications.

Chapter 1: Introduction 11

Job Types Supported by CA WA Agent for Application Services

POJO Lets you instantiate a class to create a Java object and invoke a method on it. The job is restricted to classes that take constructors with no arguments (default constructors). You can use the POJO job to invoke custom Java code on a local computer. RMI Lets you set up interaction between Java objects on different computers in a distributed network. Using an RMI job, you can access a remote server and invoke a method on a Java object. Session Bean Lets you access a session bean on an application server. This job type can make a Remote Procedure Call (RPC) to the session bean, invoke a method that defines the business logic, pass parameters to the method, and have the results returned as serialized Java output. You can access stateless and stateful session beans using the Session Bean job.

12 Implementation Guide

Chapter 2: Implementation Checklist This section contains the following topics: How to Install and Configure CA WA Agent for Application Services (see page 13) Deciding Whether to Create an Alias (see page 14)

How to Install and Configure CA WA Agent for Application Services CA WA Agent for Application Services is an agent plug-in that installs into the CA WA Agent for UNIX, Linux, or Windows installation directory. Note: Before installing the agent plug-in, you must install and configure the agent. To install and configure the agent plug-in, follow these steps: 1.

Review the system requirements in the CA Workload Automation Agent for Application Services Release Notes.

2.

Decide whether to create an alias (see page 14).

3.

Apply the latest agent patch on the platform where you are installing the agent plug-in. For example, if you are installing on Windows, install the latest patch for CA Workload Automation Agent for Windows.

4.

Install the agent plug-in (see page 16).

5.

Configure the agent plug-in to run POJO jobs (see page 17).

6.

Configure the scheduling manager to work with the agent plug-in (see page 21).

7.

(Optional) Run a verification test (see page 21).

8.

(Optional) Configure the agent plug-in:

9.



Configure SSL and Secure HTTP (see page 26)



Configure the agent plug-in for a proxy (see page 26)



Persist subscribed messages consumed by JMS Subscribe jobs (see page 28)

(Optional) Configure the agent plug-in to work with an application server (see page 29).

Chapter 2: Implementation Checklist 13

Deciding Whether to Create an Alias

Deciding Whether to Create an Alias Note: If you are installing the agent plug-in to work with CA Workload Automation DE, you must set up an alias. Setting up an alias for use with other scheduling managers is optional. You install an agent plug-in into the agent installation directory to extend the core functionality of the agent. By default, the agent plug-in operates under the same agent name that is assigned to the agent. An alias lets you create a unique agent name for an agent plug-in, which is useful for controlling agent security or for setting up clustered environments. Suppose you have installed an agent named AGT10 on a UNIX computer. Users who have access to that agent through their security permissions specify AGT10 as the agent name in their job definitions. Now suppose that you install an agent plug-in into the installation directory for AGT10. You can create an alias for the agent plug-in, for example, AGT10_DB. You can then restrict access to that alias to only those users that run database workload. Those specific users then must specify AGT10_DB as the agent name in their job definitions. Each agent plug-in has a default alias that you can enable during installation. For example, the agent plug-in for CA WA Agent for Databases has the default alias agentname_DB. You can enable or change the default alias name after installation. To work, you must also configure the alias on the scheduling manager. To configure agent aliasing for clustered environments, see the CA Workload Automation Agent for UNIX, Linux, or Windows Implementation Guide.

14 Implementation Guide

Chapter 3: Installing the Agent Plug-in This section contains the following topics: CA WA Agent for Application Services Installation Options (see page 15) Controlling the Agent Plug-in (see page 15) Install CA WA Agent for Application Services (see page 16) Configure the Agent Plug-in to Run POJO Jobs (see page 17) How to Remove the Agent Plug-in (see page 17)

CA WA Agent for Application Services Installation Options The interactive installation program prompts you for the following information: Do you want to set up the alias? Sets whether the default alias is enabled for the agent plug-in. ■

Y—Enables the default alias.



N—Disables the default alias.

Default: Y Note: The default alias for CA WA Agent for Application Services is AGENT_AS.

Controlling the Agent Plug-in You control the agent plug-in using the agent where the plug-in is installed. Depending on your operating system, you have several options for starting or stopping the agent. On UNIX, you must issue a command to run a start or stop script. On Windows, you must start or stop the agent as a Windows service using the command prompt. Note: For instructions to start and stop the agent, see the CA Workload Automation Agent for UNIX, Linux, or Windows Implementation Guide.

Chapter 3: Installing the Agent Plug-in 15

Install CA WA Agent for Application Services

Install CA WA Agent for Application Services You install the agent plug-in using an interactive program that prompts you for the required information. To install CA WA Agent for Application Services 1.

Copy the as.pak file into the directory where the agent is installed. You can copy this file from the product DVD or download a zip file that contains the file from the CA Support Online website, found at http://ca.com/support.

2.

Change to the agent installation directory. For example, type the following command: ■

On UNIX: cd opt/CA/WA_Agent_R11_3



On Windows: cd C:\Program Files\CA\WA Agent R11.3

3.

Type the following command to stop the agent: ■

On UNIX ./cybAgent -s



On Windows cybAgent -s

The agent stops. 4.

Type the following command to start the installation program: ■

On UNIX ./PluginInstaller as.pak install_dir



On Windows PluginInstaller as.pak install_dir

install_dir

Specifies the agent installation directory. The CA WA Agent for Application Services installation program opens. 5.

Enter the information the installation program prompts you for. The installation program displays a message and closes automatically upon a successful installation.

16 Implementation Guide

Configure the Agent Plug-in to Run POJO Jobs

6.

Type the following command to start the agent: ■

On UNIX ./cybAgent &



On Windows cybAgent -a

The agent starts. Note: The installation program backs up all modified and replaced files. The backup files are compressed into a file named backup_timestamp.zip, located in the backups subdirectory of the agent installation directory. You can use Winzip or other similar utilities to open the backup file. A backup copy of the agentparm.txt file is stored in the zip file. More information: Deciding Whether to Create an Alias (see page 14)

Configure the Agent Plug-in to Run POJO Jobs To run a POJO job you must add the JAR or class files the job invokes to the agent installation directory using this procedure. To configure the agent plug-in to run POJO jobs 1.

Locate the JAR or class files your POJO jobs invoke.

2.

Do the following: ■

If you use JAR files, place the JAR files in the jars/ext directory (UNIX) or jars\ext (Windows) in the agent installation directory.



If you use class files, create a jars/ext/classes (UNIX) or jars\ext\classes (Windows) directory in the agent installation directory. Copy the package of POJO classes to the new directory.

How to Remove the Agent Plug-in You can remove an agent plug-in when you no longer require it. To remove the agent plug-in, follow these steps: 1.

Disable the agent plug-in (see page 18).

2.

(Optional) Remove the agent plug-in from the scheduling manager (see page 19).

Chapter 3: Installing the Agent Plug-in 17

How to Remove the Agent Plug-in

Disable CA WA Agent for Application Services Use this procedure when you want to remove CA WA Agent for Application Services from your system. To remove CA WA Agent for Application Services 1.

Ensure all workload is complete.

2.

Stop the agent.

3.

Open the agentparm.txt file located in the agent installation directory.

4.

Comment out the plugins.start_internal_n parameter, and renumber any subsequent plugins.start_internal_n parameters. Note: Renumber all other agent plug-ins that are assigned a greater number than the agent plug-in you are uninstalling.

5.

Comment out the communication.alias parameter if you created an alias during the agent plug-in installation. Note: Renumber any subsequent communication.alias_n parameters.

6.

Save and close the agentparm.txt file.

7.

Remove the appservices.jar and dataservices.jar files from the JARs subdirectory of the agent installation directory.

8.

Start the agent.

Example: Renumber the plugins.start_internal_n Parameter Suppose you have the following agent plug-ins set in the agentparm.txt file: plugins.start_internal_1=runner plugins.start_internal_2=as plugins.start_internal_3=ftp plugins.start_internal_4=microfocus

To disable the agent plug-in for CA WA Agent for Application Services, you would modify the agentparm.txt file as follows: plugins.start_internal_1=runner #plugins.start_internal_2=as plugins.start_internal_2=ftp plugins.start_internal_3=microfocus

18 Implementation Guide

How to Remove the Agent Plug-in

Example: Renumber the communication.alias_n Parameter Suppose you have two alias agent plug-ins. The agentparm.txt file has the following parameters: communication.alias_1=AGENT_AS communication.alias_2=AGENT_MF

To disable the agent plug-in for CA WA Agent for Application Services, modify the agentparm.txt file as follows: #communication.alias_1=AGENT_AS communication.alias_1=AGENT_MF

Remove the Agent Plug-in from the Scheduling Manager In addition to disabling the agent plug-in, you can remove it from the configuration on the scheduling manager. Note: For detailed instructions to remove the agent from the scheduling manager, see the documentation for your scheduling manager.

Chapter 3: Installing the Agent Plug-in 19

Chapter 4: Your Scheduling Manager and the Agent Plug-in This section contains the following topics: Configuring the Scheduling Manager to Work with the Agent Plug-in (see page 21) Running a Verification Test (see page 21)

Configuring the Scheduling Manager to Work with the Agent Plug-in If you have defined the following items for the agent plug-in, you must configure the items on the scheduling manager: ■

An alias



A user

For detailed configuration instructions, see the documentation for your scheduling manager.

Running a Verification Test For your verification test, you define and run a POJO job. To define the job, you require the following information: Agent name Specifies the name of your agent or the alias for the agent plug-in if you created an alias. Class name Specifies the Java class to instantiate. Method Specifies the Java method to call on the instance of the Java object.

Chapter 4: Your Scheduling Manager and the Agent Plug-in 21

Running a Verification Test

Example: Define a POJO Job Suppose that you want to define a POJO job that creates an empty java string, and calls the method parseInt on it with the argument “5”. To define a POJO job, use the following values: ■

Class name—java.lang.Integer



Method—parseInt



Parameter Type—java.lang.String



Parameter Value—5

For more information about defining a POJO job, see the documentation for your scheduling manager. More information: Configure the Agent Plug-in to Run POJO Jobs (see page 17)

22 Implementation Guide

Chapter 5: Configuring the Agent Plug-in This section contains the following topics: How to Configure Agent Parameters (see page 23) CA WA Agent for Application Services Parameters in the agentparm.txt File (see page 24) How to Set Up an Alias for the Agent Plug-in (see page 25) Configure SSL and Secure HTTP (see page 26) Configure the Agent Plug-in for a Proxy (see page 26) Persist Consumed JMS Subscribe Messages (see page 28)

How to Configure Agent Parameters You configure agent parameters by editing the agentparm.txt file, located in the agent installation directory. When you install the agent, the installation program adds frequently-configured agent parameters to the file. Other agent parameters exist, which you must manually add to the agentparm.txt file to configure the agent. For any configuration changes to take effect, always stop and restart the agent. For some agent parameters, such as the agent name and communication parameters, also configure the parameters on the scheduling manager. To configure agent parameters, do the following: 1.

Configure agent parameters on the agent (see page 23).

2.

Configure agent parameters on the scheduling manager (see page 24).

Configure Agent Parameters on the Agent Use the following procedure to configure agent parameters on CA WA Agent for UNIX, Linux, or Windows. To configure agent parameters on the agent 1.

Change to the agent installation directory.

2.

Stop the agent. At the command prompt, enter the following command: ■

On UNIX: ./cybAgent -s



On Windows: cybAgent -s

The agent stops.

Chapter 5: Configuring the Agent Plug-in 23

CA WA Agent for Application Services Parameters in the agentparm.txt File

3.

Open the agentparm.txt file located in the agent installation directory.

4.

Edit the parameters to make the required changes.

5.

Save and close the agentparm.txt file.

6.

Start the agent. At the command prompt, enter the following command: ■

On UNIX: ./cybAgent &



On Windows: cybAgent -a

The agent starts and the parameters are configured.

Configure Agent Parameters on the Scheduling Manager When you change an agent parameter in the agentparm.txt file that is also defined on the scheduling manager, such as the agent name, configure the agent parameter on the scheduling manager. Note: For detailed instructions to configure agent parameters on the scheduling manager, see the documentation for your scheduling manager.

CA WA Agent for Application Services Parameters in the agentparm.txt File The agent plug-in installation program adds the parameters listed below to the agentparm.txt file. The file is located in the agent installation directory. You can open the agentparm.txt file in any standard text editor. Note: You must save the file after making edits to persist the changes. communication.alias_n Defines the alias name for the agent. The n suffix increments sequentially for each alias agent. Note: To enable an alias on the agent, verify that the comment character (#) is removed from the parameter line. Default: AGENT_AS

24 Implementation Guide

How to Set Up an Alias for the Agent Plug-in

plugins.start_internal_n Specifies the agent plug-in to start by the core Java agent. n Denotes an integer assigned to the agent plug-in, starting at 1. The n suffix must increase sequentially for each agent plug-in.

How to Set Up an Alias for the Agent Plug-in When you install the agent plug-in, you are prompted to create a default alias, which you can change after installation. If you enable an alias on the agent plug-in, you must also configure the alias on the scheduling manager. To set up an alias for the agent plug-in, follow these steps: 1.

Create an alias for the agent plug-in (see page 25).

2.

Configure the alias on the scheduling manager (see page 26).

More information: Deciding Whether to Create an Alias (see page 14)

Create an Alias for the Agent Plug-in An alias lets you create a unique agent name for an agent plug-in. Each agent plug-in has a default alias, which you can enable or change. To create an alias for the agent, configure the following agent parameter on the agent: communication.alias_n Defines the alias name for the agent. The n suffix increments sequentially for each alias agent. Note: To enable an alias on the agent, verify that the comment character (#) is removed from the parameter line.

Chapter 5: Configuring the Agent Plug-in 25

Configure SSL and Secure HTTP

Configuring an Alias on the Scheduling Manager When you create an alias for an agent plug-in, you must also configure the alias on the scheduling manager. You must define the alias on the scheduling manager with the same address, port number, and encryption key as the agent where the agent plug-in is installed. Note: For detailed instructions to configure an alias on the scheduling manager, see the documentation for your scheduling manager.

Configure SSL and Secure HTTP You can configure the agent for a secure HTTP connection using Secure Sockets Layer (SSL) encryption by adding the following parameters to the agentparm.txt file and restarting the agent: javax.net.ssl.trustStore Specifies the full path of the keystore file. Example: javax.net.ssl.trustStore=D:/sslfiles/.keystore javax.net.ssl.trustStorePassword.encr Specifies the encrypted password for the client truststore file that contains some common CA X509 certificates. The default password is changeit (encrypted). Example: javax.net.ssl.trustStorePassword.encr=055A55EB863D2A5 Note: The password must be encrypted. To encrypt a password, use the Password utility provided with the agent. For more information about the Password utility, see the CA Workload Automation Agent for UNIX, Linux, or Windows Implementation Guide.

Configure the Agent Plug-in for a Proxy To access a computer outside the firewall of your company, configure the agent-plug to communicate through a proxy server. You require the proxy host, port, user name, and encrypted password for the configuration. You require this configuration if schedulers are running workload that includes HTTP and Web Service jobs. To configure the agent plug-in for a proxy, manually add the following parameters to the agentparm.txt file and restart the agent: http.proxyDomain Specifies the domain for proxy authentication. Example: http://host.domain.proxy

26 Implementation Guide

Configure the Agent Plug-in for a Proxy

http.proxyHost Specifies the host name of the proxy server. Example: caproxy http.proxyPort Specifies the port on the server of the proxy. Example: 80 Add the following parameters set to values for your proxy if the proxy requires authentication: http.proxyOrigin Specifies the origin host name for proxy authentication. Example: http://host.origin.proxy http.proxyUser Specifies the user name for proxy authentication. To specify a domain, use the following format: domain\user. Examples: pmf01, mydomain\causer http.proxyPassword.encr Specifies the encrypted proxy server password. Example: 9DD43DA16CBFAE06 Notes: ■

The password must be encrypted. To encrypt a password, use the Password utility that is provided with the agent. For more information about the Password utility, see the CA Workload Automation Agent for UNIX, Linux, or Windows Implementation Guide.



Although not recommended, if you do not want to encrypt the proxy password, you can specify the password in plain text using the http.proxyPassword parameter. If you specify both the http.proxyPassword and http.proxyPassword.encr parameters, the encrypted value is used.

Note: You must run the agent plug-in under a user account or in Windows console mode when NTLM proxy authentication is required.

Chapter 5: Configuring the Agent Plug-in 27

Persist Consumed JMS Subscribe Messages

Persist Consumed JMS Subscribe Messages The agent can persist the subscribed messages consumed by JMS Subscribe jobs as serialized Java objects. The serialized Java objects are stored as files on the agent computer and can be passed as input to a payload consuming job. By default, the agent does not persist subscribed messages as JMS Subscribe jobs can consume thousands or millions of messages in a short time, thus generating many files. To persist subscribed messages consumed by JMS Subscribe jobs 1.

Change to the agent installation directory.

2.

Stop the agent.

3.

Open the agentparm.txt file.

4.

Add the following parameter: appservices.jms.subscribe.persist=true

5.

Save and close the agentparm.txt file.

6.

Start the agent. The agent persists all subscribed messages. Notes: ■

To prevent many messages being persisted, verify that the filter criteria defined in each JMS Subscribe job limits the number of subscribed messages.



To disable persistence, configure the agent to set appservices.jms.subscribe.persist=false.

More information: Configure Agent Parameters on the Agent (see page 23)

28 Implementation Guide

Chapter 6: Configuring the Agent Plug-in to Work with an Application Server By configuring the agent plug-in to work with one of the supported application servers, you can run JMS Publish, JMS Subscribe, Entity Bean, and Session Bean jobs. The agent plug-in currently supports WebLogic, WebSphere, JBoss, and Oracle application servers. Note: The agent does not support JMS messaging on WebSphere. If you have IBM WebSphere MQ, you can set up the agent plug-in to run JMS Publish and JMS Subscribe for JMS queues. This section contains the following topics: Prerequisites and Assumptions (see page 29) How to Set Up the Agent Plug-in for WebLogic (see page 30) How to Set up the Agent Plug-in for WebSphere (EJB Jobs only) (see page 32) How to Set Up the Agent Plug-in for WebSphere MQ (JMS Messaging only) (see page 35) How to Set Up the Agent Plug-in for WebSphere and WebSphere MQ (EJB Jobs and JMS Messaging) (see page 44) How to Set Up the Agent Plug-in for JBoss (see page 44) How to Set Up the Agent Plug-in for Oracle Application Server (see page 46)

Prerequisites and Assumptions CA WA Agent for Application Services acts as a client to a Java Enterprise Edition (Java EE) application server. To use this technology, you must have expertise in Java EE development. The instructions in this chapter assume that you have the prerequisite knowledge to work with Java applications and that you have one of the following application servers installed: ■

Oracle WebLogic Application Server



IBM WebSphere Application Server



JBoss Application Server



Oracle Application Server

Note: For information about which versions of an application server are supported, see the CA Workload Automation Agent for Application Services Release Notes.

Chapter 6: Configuring the Agent Plug-in to Work with an Application Server 29

How to Set Up the Agent Plug-in for WebLogic

How to Set Up the Agent Plug-in for WebLogic WebLogic is a J2EE operating environment product, owned by Oracle, that includes a J2EE application server. If necessary, you can download the Oracle WebLogic Application Server from the Oracle website. Setting up the agent plug-in for WebLogic allows you to run JMS Publish, JMS Subscribe, Entity Bean, and Session Bean jobs. To set up the agent plug-in for WebLogic, do the following: 1.

Collect the WebLogic and client JARs (see page 30).

2.

Configure the agent plug-in for WebLogic (see page 31).

3.

Test the WebLogic setup (see page 31).

Collect the WebLogic and Client JARs Note: The JAR listed is based on WebLogic Server 8.1. Other versions of WebLogic can contain different JAR files. Collect all the JAR files for your particular version. To configure the agent plug-in to access your Java applications deployed on your WebLogic server, collect the following JAR files: ■

weblogic.jar located in the WebLogic installation directory



client JARs that contain the interfaces and stubs for the application Enterprise JavaBeans (EJBs) you intend to access using the agent Java applications

Contact the Java EE developer to locate the client JAR for the Java applications you intend to use with the agent plug-in.

30 Implementation Guide

How to Set Up the Agent Plug-in for WebLogic

Configure the Agent Plug-in for WebLogic Add the required JAR files to your agent installation directory and configure the classpath of the agent to specify the location of those files. Note: The instructions in this section are based on WebLogic Server 8.1. To configure the agent for WebLogic 1.

Create a subdirectory within your agent installation directory to store the WebLogic JAR files, for example, agentdir/jars/weblogic.

2.

Copy the weblogic.jar file, located in the weblogic81/server/lib directory, to the new subdirectory.

3.

Create a second subdirectory to store the client JAR for the Java applications you intend to use, for example, agentdir/jars/ext/stubs. Note: We recommend that you create the subdirectory in the existing agentdir/jars/ext directory.

4.

Copy the client JAR to the new subdirectory.

5.

Stop the agent.

6.

Open the agentparm.txt file and configure the oscomponent.classpath parameter to specify the WebLogic and client classpaths. For example, on UNIX, specify jars/weblogic/*.jar:jars/ext/stubs/*.jar.

7.

Add the following parameters to the agentparm.txt file set to the values shown: javax.xml.transform.TransformerFactory=com.sun.org.apache.xalan.internal.xslt c.trax.TransformerFactoryImpl javax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jaxp.SA XParserFactoryImpl javax.xml.parsers.DocumentBuilderFactory=com.sun.org.apache.xerces.internal.j axp.DocumentBuilderFactoryImpl

8.

Save and close the agentparm.txt file.

9.

Start the agent. The agent plug-in is configured for the WebLogic server.

Testing the WebLogic Setup After you have set up the agent plug-in for WebLogic, you can run one of the following jobs to test the setup: ■

Entity Bean or Session Bean



JMS Publish or JMS Subscribe

Chapter 6: Configuring the Agent Plug-in to Work with an Application Server 31

How to Set up the Agent Plug-in for WebSphere (EJB Jobs only)

To define these jobs, you require the following WebLogic information: ■

Initial context factory



Provider URL

Note: For more information about defining these jobs, see the documentation for your scheduling manager.

How to Set up the Agent Plug-in for WebSphere (EJB Jobs only) You can set up the agent for IBM WebSphere Application Server to run Entity Bean and Session Bean jobs. Note: WebSphere does not support JMS messaging. If you have IBM WebSphere MQ, you can perform additional steps to set up the agent to run JMS Publish and JMS Subscribe jobs. To set up the agent for WebSphere, do the following:

32 Implementation Guide

1.

Collect the WebSphere and client JARs (see page 33).

2.

Configure the agent plug-in for WebSphere (see page 34).

3.

Test the WebSphere setup (see page 35).

How to Set up the Agent Plug-in for WebSphere (EJB Jobs only)

Collect the WebSphere and Client JARs Note: The WebSphere JARs listed are based on IBM WebSphere Server 6.1. Other versions of WebSphere can contain different JAR files. Collect all the JAR files for your particular version. To configure the agent to access your Java applications deployed on your WebSphere application server, collect the following WebSphere JAR files: ■

java/jre/lib/ext/iwsorbutil.jar



java/jre/lib/ibmcfw.jar



java/jre/lib/ibmorb.jar



java/jre/lib/ibmorbapi.jar



lib/WMQ/java/lib/com.ibm.mq.jar



lib/WMQ/java/lib/com.ibm.mqjms.jar



lib/WMQ/java/lib/dhbcore.jar



lib/bootstrap.jar



lib/j2ee.jar



lib/lmproxy.jar



lib/startup.jar



lib/urlprotocols.jar



plugins/com.ibm.ws.emf_2.1.0.jar



plugins/com.ibm.ws.runtime_6.1.0.jar

In addition to the WebSphere JAR files, collect the client JAR that contains the interfaces and stubs for Java applications that you intend to use with the agent. Contact the Java EE developer to locate the client JAR.

Chapter 6: Configuring the Agent Plug-in to Work with an Application Server 33

How to Set up the Agent Plug-in for WebSphere (EJB Jobs only)

Configure the Agent Plug-in for WebSphere Add the required JAR files to your agent installation directory and configure the classpath of the agent to specify the location of those files. Note: The instructions in this procedure are based on IBM WebSphere Server 6.1. To configure the agent plug-in for WebSphere 1.

Create a subdirectory within your agent installation directory to store the WebSphere JAR files, for example, agentdir/jars/mq.

2.

Copy the WebSphere JARs into the new subdirectory.

3.

Create a second subdirectory to store the client JAR for the Java applications you intend to use, for example, agentdir/jars/ext/stubs. Note: We recommend that you create the subdirectory in the existing agentdir/jars/ext directory.

4.

Copy the client JAR to the new subdirectory.

5.

Stop the agent.

6.

Open the agentparm.txt file and configure the oscomponent.classpath parameter to specify the WebSphere and client classpaths. For example, on UNIX, specify jars/mq/*.jar:jars/ext/stubs/*.jar.

7.

Add the following lines to the agentparm.txt file: org.omg.CORBA.ORBClass=com.ibm.CORBA.iiop.ORB org.omg.CORBA.ORBSingletonClass=com.ibm.rmi.corba.ORBSingleton

Note: If you do not add these two lines to the agentparm.txt file, you receive "Failed to initialize the ORB" errors. 8.

Save and close the agentparm.txt file.

9.

Start the agent.

10. Open the runner_os_component.log file and verify that all the JAR files appear in the “Jars found” log entry. The agent plug-in is configured for WebSphere.

34 Implementation Guide

How to Set Up the Agent Plug-in for WebSphere MQ (JMS Messaging only)

Testing the WebSphere Setup After you have set up the agent plug-in for WebSphere, you can run an Entity Bean or Session Bean job to test the setup. To define these jobs, you require the following WebSphere information: ■

Initial context factory



Provider URL

Note: For more information about defining these jobs, see the documentation for your scheduling manager.

How to Set Up the Agent Plug-in for WebSphere MQ (JMS Messaging only) While IBM MQ Series queues do not directly support JMS connectivity, IBM provides a software layer that enables JMS connectivity. You can set up the agent for IBM WebSphere MQ to run JMS Publish and JMS Subscribe jobs. Note: This process assumes you have IBM WebSphere MQ installed and only want to set up the agent for JMS messaging. To set up the agent for WebSphere MQ , do the following: 1.

Collect the WebSphere MQ and client JARs (see page 35).

2.

Collect your WebSphere MQ queue connectivity information (see page 36).

3.

Obtain the WebSphere MQ JMS Administration Tool (JMS Admin) (see page 36).

4.

Set up a JNDI provider (see page 37).

5.

Collect the JNDI provider JARs (see page 37).

6.

Configure the agent plug-in for the JNDI provider (see page 38).

7.

Define the JNDI connectivity parameters (see page 38).

8.

Store the JNDI information using JMS Admin (see page 40).

9.

Configure the agent for WebSphere MQ (see page 42).

10. Test the WebSphere MQ setup (see page 43).

Collecting the WebSphere MQ and Client JARs To configure the agent to access your Java applications deployed on your WebSphere MQ application server, collect all JAR files in the MQInstall/Java/lib directory.

Chapter 6: Configuring the Agent Plug-in to Work with an Application Server 35

How to Set Up the Agent Plug-in for WebSphere MQ (JMS Messaging only)

Collecting Your WebSphere MQ Queue Connectivity Information You require the following WebSphere MQ queue connectivity information from your MQ administrator: MQ Queue Manager Specifies the name of the MQ Queue Manager. Example: queue.manager Host Specifies the host for the listening MQ Queue Manager. Example: somehost Port number Specifies the port for the listening MQ Queue Manager. Default: 1414 MQ Queue Specifies the name of the MQ queue. Example: MY.QUEUE

Obtaining the WebSphere MQ JMS Administration Tool WebSphere MQ provides a Java utility named JMSAdmin, which lets you connect to a JNDI provider and define your bindings within the JNDI namespace. You require JMSAdmin to store the JNDI information required as part of the WebSphere MQ setup process for JMS messaging. Note: To obtain JMSAdmin, install WebSphere MQ. JMSAdmin is located in the WebSphere MQ installation directory. The following table lists the location of the WebSphere MQ installation directory based on platform.

36 Implementation Guide

Platform

WebSphere MQ Installation Directory

AIX

/usr/mqm/java/

HP-UX and Solaris

/opt/mqm/java/

Linux

/opt/mqm/java/

UNIX

/opt/mqm/java/bin

Windows

\Program Files\IBM\WebSphere MQ\java

How to Set Up the Agent Plug-in for WebSphere MQ (JMS Messaging only)

To use the JMSAdmin utility, see “Using the WebSphere MQ JMS administration tool” in IBM WebSphere MQ Using Java with the file name CSQZAW12.pdf. You can locate this IBM document by searching the Internet for CSQZAW12.

Setting Up a JNDI Provider The JNDI provider stores the WebSphere MQ queue connectivity information that the agent uses to look up the JMS objects. When choosing the JNDI provider, consider using one you currently have such as LDAP or iiop. If you do not already have a JNDI provider, the simplest one to set up is a file located on the same computer as the agent (file-based JNDI). Note: Consider using LDAP and iiop if multiple agents must access the MQ queue. To use a file-based JNDI for multiple agents, copy the generated JNDI data to each agent that requires access to the MQ queue.

Collecting the JNDI Provider JARs To configure the agent to access the JNDI provider, you require JNDI-specific JAR files available from Sun Microsystems. To use a file system-based JNDI, for example, you require the following two JARs: ■

providerutil.jar



fscontext.jar

You can download these JNDI-related JARs from the Sun website at http://java.sun.com. Note: For other JNDI providers, such as LDAP, you need different JAR files.

Chapter 6: Configuring the Agent Plug-in to Work with an Application Server 37

How to Set Up the Agent Plug-in for WebSphere MQ (JMS Messaging only)

Configure the Agent for the JNDI Provider Add the required JNDI-specific JAR files to your agent installation directory and configure the classpath of the agent to specify the location of those files. To configure the agent for the JNDI provider 1.

Create a subdirectory within your agent installation directory to store the JNDI JAR files, for example, agentdir/jars/jndi.

2.

Copy the JNDI JARs into the new subdirectory.

3.

Stop the agent.

4.

Open the agentparm.txt file and configure the oscomponent.classpath parameter to specify the JNDI classpath. For example, on UNIX, specify jars/jndi/*.jar.

5.

Save and close the agentparm.txt file.

6.

Start the agent.

The agent plug-in is configured for the JNDI provider.

Defining the JNDI Connectivity Parameters To communicate with WebSphere MQ, you must define the following four parameters in JNDI: Initial context factory Specifies the name of the Java class that builds connections. This name depends on the JNDI provider you use. You can use the following types of context factories: ■

File-based Example: com.sun.jndi.fscontext.RefFSContextFactory



LDAP Example: com.sun.jndi.ldap.LdapCtxFactory



iiop Example: com.ibm.websphere.naming.WsnInitialContextFactory

38 Implementation Guide

How to Set Up the Agent Plug-in for WebSphere MQ (JMS Messaging only)

Provider URL Specifies the URL of your JNDI provider, which provides the location to look up the WebSphere MQ connectivity information. Use the following formats for these common JNDI providers: ■

File-based file:[drive:]/pathname



LDAP ldap://hostname/contextname



iiop iiop://hostname[:port] /[?TargetContext=ctx]

Example: file:/var/mqm/fsjndi Connection factory Defines a name that you assign to identify your MQ queue connection. The connection factory is an arbitrary name that you create to correspond to the MQ Queue Manager, host, and port. Example: MY_QUEUE_CF JNDI destination Defines a name you assign to identify the MQ queue. The JNDI destination is an arbitrary name that you create to correspond to the MQ queue. Example: MY_QUEUE

Chapter 6: Configuring the Agent Plug-in to Work with an Application Server 39

How to Set Up the Agent Plug-in for WebSphere MQ (JMS Messaging only)

Store the JNDI Information Using JMSAdmin You use the JMSAdmin utility to store the JNDI information on the system where WebSphere MQ is installed. Note: The instructions in this procedure use a file-based JNDI. You will need to adapt these steps if you are using another JNDI provider. To store the JNDI information 1.

Source the code in the MQ environment.

2.

Create a directory on your file system for a file-based JNDI, if applicable.

3.

Create a JMSAdmin configuration file by copying and editing the JMSAdmin.config file located in the WebSphere MQ installation directory.

4.

Edit the two lines in the JMSAdmin configuration file that correspond to the following parameters: ■

INITIAL_CONTEXT_FACTORY



PROVIDER_URL



Comment out all of the other settings in the JMSAdmin configuration file.

Note: For a file-based JNDI, the INITIAL_CONTEXT_FACTORY and PROVIDER_URL are the only parameters you need. 5.

Invoke the JMSAdmin utility with the configuration file you edited. The InitCtx> prompt appears indicating that you are connected to the initial context factory and provider URL you defined in the configuration file. Note: For information about the JMSAdmin utility, see the WebSphere MQ JMS Administration Tool.

6.

Enter the following command to define the JMS connection factory object: DEFINE QCF(connectionfactory) TRANSPORT(CLIENT) QMGR(queuemanager) HOSTNAME(host) PORT(port)

7.

Enter the following command to define the JMS destination: DEFINE Q(destination) QMGR(queuemanager) QUEUE(queuename)

8.

Enter the following command to check your definition: DISPLAY CTX

The JMSAdmin utility displays lines for your two definitions. 9.

Type END to complete the definition and exit the utility. The JNDI information is stored.

40 Implementation Guide

How to Set Up the Agent Plug-in for WebSphere MQ (JMS Messaging only)

Example: Store the Information for a File-based JNDI on UNIX This example creates a subdirectory /var/mqm/fsjndi on a UNIX file system. The subdirectory contains a .bindings file that stores the WebSphere MQ queue connection information. To store the information for a file-based JNDI on UNIX 1.

To store the information for a file-based JNDI on UNIX

2.

Enter the following line to source the code into the shell environment on UNIX: ./opt/mqm/java/bin/setjmsenv

3.

Type the following lines at the prompt to create a directory named fsjndi on the file system: cd /var/mqm mkdir fsjndi

4.

Enter the following line to create a JMSAdmin configuration file named MyJMSAdmin.config: cp $MQ_JAVA_INSTALL_PATH/bin/JMSAdmin.config MyJMSAdmin.config

5.

Edit the JMSAdmin configuration file for the initial context factory and provider URL lines as follows: INITIAL_CONTEXT_FACTORY=com.sun.jndi.fscontext.RefFSContextFactory PROVIDER_URL=file:/var/mqm/fsjndi

6.

Comment out any of the other settings in the JMSAdmin configuration file.

7.

Enter the following line to invoke the JMSAdmin utility with the JMSAdmin configuration file. MQ_JAVA_INSTALL_PATH/bin/JMSAdmin -cfg MyJMSAdmin.config

Chapter 6: Configuring the Agent Plug-in to Work with an Application Server 41

How to Set Up the Agent Plug-in for WebSphere MQ (JMS Messaging only)

8.

Enter the following command to define the JMS connection factory object: DEFINE QCF(MY_QUEUE_CF) TRANSPORT(CLIENT) QMGR(queue.manager) HOSTNAME(somehost) PORT(1414)

9.

Enter the following command to define the JMS destination: DEFINE Q(MY_QUEUE) QMGR(queue.manager) QUEUE(MY.QUEUE)

10. Enter the following command to check your definition: DISPLAY CTX

The JMS Admin utility displays the following lines. .bindings MY_QUEUE_CF MY_QUEUE

java.io.File com.ibm.mq.jms.MQQueueConnectionFactory com.ibm.mq.jms.MQQueue

11. Type END to complete the definition and exit the utility. Note: You can copy the entire fsjndi subdirectory to anywhere you want on any computer you want, but you must update the Provider URL parameter used during queue connections to the corresponding location.

Configure the Agent Plug-in for WebSphere MQ Add the required JAR files to your agent installation directory and configure the classpath of the agent to specify the location of those files. To configure the agent for WebSphere MQ 1.

Create a subdirectory within your agent installation directory to store the WebSphere MQ JAR files, for example, agentdir/jars/mq.

2.

Copy the WebSphere MQ JARs into the new subdirectory.

3.

Stop the agent.

4.

Open the agentparm.txt file and configure the oscomponent.classpath parameter to specify the WebSphere MQ classpath. For example, on UNIX, specify jars/mq/*.jar:jars/ext/*.jar.

42 Implementation Guide

How to Set Up the Agent Plug-in for WebSphere MQ (JMS Messaging only)

5.

Add the following lines to the agentparm.txt file: org.omg.CORBA.ORBClass=com.ibm.CORBA.iiop.ORB org.omg.CORBA.ORBSingletonClass=com.ibm.rmi.corba.ORBSingleton

Note: If you do not add these two lines to the agentparm.txt file, you receive "Failed to initialize the ORB" errors. 6.

Save and close the agentparm.txt file.

7.

Start the agent.

8.

Open the runner_os_component.log file and verify that all the JAR files appear in the “Jars found” log entry. The agent plug-in is configured for WebSphere MQ.

Testing the WebSphere MQ Setup After you have set up the agent plug-in for WebSphere MQ, you can run a JMS Publish or JMS Subscribe job to test the setup. JMS Publish and JMS Subscribe jobs require the following four JMS parameters to connect to a JMS provider: ■

Initial context factory



Provider URL



Connection factory



JNDI destination

Note: For more information on defining these jobs, see the documentation for your scheduling manager.

Chapter 6: Configuring the Agent Plug-in to Work with an Application Server 43

How to Set Up the Agent Plug-in for WebSphere and WebSphere MQ (EJB Jobs and JMS Messaging)

How to Set Up the Agent Plug-in for WebSphere and WebSphere MQ (EJB Jobs and JMS Messaging) Note: This process assumes you have a WebSphere Application Server as well as WebSphere MQ. If you have both products, you can set up the agent to run JMS Publish, JMS Subscribe, Entity Bean, and Session Bean jobs. To set up the agent for WebSphere and WebSphere MQ, do the following: 1.

Complete the process to set up the agent for WebSphere.

2.

Collect your WebSphere MQ queue connectivity information.

3.

Obtain the WebSphere MQ JMS Administration Tool.

4.

Set up a JNDI provider.

5.

Collect the JNDI provider jars.

6.

Configure the agent for the JNDI provider.

7.

Define the JNDI connectivity parameters.

8.

Store the JNDI information using JMS Admin.

9.

Configure the agent for WebSphere MQ.

10. Test the WebSphere MQ setup.

How to Set Up the Agent Plug-in for JBoss JBoss Application Server is a free open source J2EE-based software program. If necessary, you can download the JBoss Application Server from the JBoss website. To set up the agent for JBoss, do the following:

44 Implementation Guide

1.

Collect the JBoss and client jars (see page 45).

2.

Configure the agent for JBoss (see page 45).

3.

Test the JBoss setup (see page 46).

How to Set Up the Agent Plug-in for JBoss

Collect the JBoss and Client Jars Note: The JARs listed are based on JBoss Application Server 4.2.0. Other versions of JBoss can contain different JAR files. Collect all the JAR files for your particular version. To configure the agent to access your Java applications deployed on your JBoss Application Server, collect the following JAR files: ■

jbossall-client.jar located in the JBoss installation directory



client JARs that contain the interfaces and stubs for the application Enterprise JavaBeans (EJBs) you intend to access using the agent Java applications

Contact the Java EE developer to locate the client JAR for the Java applications you intend to use with the agent plug-in.

Configure the Agent Plug-in for JBoss You must add the required JAR files to your agent installation directory and configure the agent's classpath to specify the location of those files. Note: The following instructions are based on JBoss Application Server 4.2.0. To configure the agent for JBoss 1.

Create a subdirectory within your agent installation directory to store the JBoss jar files, for example, agentdir/jars/jboss.

2.

Copy the jbossall-client.jar file into the new subdirectory.

3.

Create a second subdirectory to store the client JAR for the Java applications you intend to use, for example, agentdir/jars/ext/stubs. Note: We recommend you create the subdirectory in the existing agentdir/jars/ext directory.

4.

Copy the client JAR to the new subdirectory.

5.

Stop the agent.

6.

Open the agentparm.txt file and configure the oscomponent.classpath parameter to specify the JBoss and client classpaths. For example, on UNIX, specify jars/jboss/*.jar:jars/ext/stubs/*.jar.

Chapter 6: Configuring the Agent Plug-in to Work with an Application Server 45

How to Set Up the Agent Plug-in for Oracle Application Server

7.

Add the following parameters to the agentparm.txt file set to the values shown: javax.xml.transform.TransformerFactory=com.sun.org.apache.xalan.internal.xslt c.trax.TransformerFactoryImpl javax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jaxp.SA XParserFactoryImpl javax.xml.parsers.DocumentBuilderFactory=com.sun.org.apache.xerces.internal.j axp.DocumentBuilderFactoryImpl

8.

Save and close the agentparm.txt file.

9.

Start the agent. The agent plug-in is configured for the JBoss Application Server.

Testing the JBoss Setup After you have set up the agent plug-in for JBoss, you can run one of the following jobs to test the setup: ■

Entity Bean or Session Bean



JMS Publish or JMS Subscribe

To define these jobs, you require the following JBoss-specific information: ■

Initial context factory



Provider URL

Note: For more information on defining these jobs, see the documentation for your scheduling manager.

How to Set Up the Agent Plug-in for Oracle Application Server Oracle Application Server is a software program that deploys J2EE-based applications using Oracle Containers (OC4J). If required, you can download the OC4J file from the Oracle website. To set up the agent for Oracle Application Server, do the following:

46 Implementation Guide

1.

Collect the Oracle and client jars (see page 47).

2.

Configure the agent plug-in for Oracle (see page 47).

3.

Test the Oracle setup (see page 48).

How to Set Up the Agent Plug-in for Oracle Application Server

Collecting the Oracle and Client JARs Note: The JARs listed are based on Oracle Application Server 10g. Other versions of Oracle can contain different JAR files. Collect all the JAR files for your particular version. To configure the agent plug-in to access your Java applications deployed on your Oracle Application Server, collect the following JAR files: ■

ejb.jar, javax77.jar, jms.jar, jta.jar located in the j2ee/home/lib directory



oc4jclient.jar located in the j2ee/home directory



optic.jar located in the opmn/lib directory



client JARs that contain the interfaces and stubs for the application Enterprise JavaBeans (EJBs) you intend to access using the agent Java applications

Contact the Java EE developer to locate the client JAR for the Java applications you intend to use with the agent plug-in.

Configure the Agent Plug-in for Oracle Add the required Oracle JAR files to your agent installation directory and configure the classpath of the agent to specify the location of those files. Note: The following instructions are based on Oracle Application Server 10g. To configure the agent for Oracle 1.

Create a subdirectory within your agent installation directory to store the Oracle JAR files, for example, agentdir/jars/oc4j.

2.

Copy the Oracle JAR files into the new subdirectory.

3.

Create a second subdirectory to store the client JAR for the Java applications you intend to use, for example, agentdir/jars/ext/stubs. Note: We recommend that you create the subdirectory in the existing agentdir/jars/ext directory.

4.

Copy the client JAR into the new subdirectory.

5.

Stop the agent.

6.

Open the agentparm.txt file and configure the oscomponent.classpath parameter to specify the Oracle and client classpaths. For example, on UNIX, specify jars/oc4j/*.jar:jars/ext/stubs/*.jar.

7.

Save and close the agentparm.txt file.

8.

Start the agent. The agent plug-in is configured for the Oracle Application Server.

Chapter 6: Configuring the Agent Plug-in to Work with an Application Server 47

How to Set Up the Agent Plug-in for Oracle Application Server

Testing the Oracle Setup After you have set up the agent plug-in for Oracle, you can run one of the following jobs to test the setup: ■

Entity Bean or Session Bean



JMS Publish or JMS Subscribe

To define these jobs, you require the following Oracle-specific information: ■

Initial context factory



Provider URL



User and password (depending on the Oracle Application Server setup)

Note: For more information about defining these jobs, see the documentation for your scheduling manager.

48 Implementation Guide

Chapter 7: Troubleshooting the Agent Plug-in This section contains the following topics: Diagnosing Failed Jobs (see page 49) JMS Job Failure Messages (see page 49)

Diagnosing Failed Jobs To diagnose a failed job, you must check the agent log files. Spool file exception and stack traces are not stored in the spool file for the agent.

JMS Job Failure Messages This section provides common JMS job failure messages returned by the agent plug-in. Note: For more information about MQJMSxxx exception messages, see Appendix I. JMS exception messages in the IBM documentation. com/ibm/mq/MQException Reason: The com.ibm.mq JAR file is missing from the classpath of the agent plug-in. Action: Add the JAR file to the classpath of the agent plug-in. java.lang.ClassCastException Reason: The com.ibm.mqjms jar file is missing from the classpath of the agent plug-in. Action: Add the JAR file to the classpath of the agent plug-in.

Chapter 7: Troubleshooting the Agent Plug-in 49

JMS Job Failure Messages

com.sun.jndi.fscontext.RefFSContextFactory Exception Reason: The fscontext.jar file is missing from the classpath of the agent plug-in. Action: Add the JAR file to the classpath of the agent plug-in. com/sun/jndi/toolkit/chars/CharacterDecoder Reason: The providerutil.jar file is missing from the classpath of the agent plug-in. Action: Add the JAR file to the classpath of the agent plug-in. Status is class name Reason: In general, if any status message is the name of a specific class, the specific class is not in the classpath of the agent plug-in. Action: Find the JAR that the class resides in, and add it to the classpath of the agent plug-in. Cannot instantiate class: class name Reason: The class name for the initial context factory is incorrect. Action: Review the class name for the initial context factory and correct it for the JMS server you are using. javax.naming.NameNotFoundException; remaining name '/bad/location' Reason: The provider URL you specified in the JMS job definition is incorrect. Action: Open the JMS job that failed, review the provider URL field, and correct it.

50 Implementation Guide

JMS Job Failure Messages

jndi connection factory name Reason: If the status message contains the value you entered for the connection factory in the job definition, then most likely no binding exists for this JNDI name. Action: Verify that the binding is defined correctly for the JMS server you are using and that the connection factory is spelled correctly. jndi queue name Reason: If the status message contains the value you entered for the JNDI destination in the job definition, then most likely no binding exists for this JNDI name. Action: Verify that the binding is defined correctly for the JMS server you are using and that the JNDI destination is spelled correctly. MQJMS2005: failed to create MQQueueManager for user ID:QM_user ID Reason: This message appears for the following reasons: ■

The MQ queue manager and listener are not running.



The JNDI binding for the MQ connection factory is incorrect.



The host or port is incorrect.



The queue manager name is missing or incorrect.

Action: Verify that the MQ queue manager and listener are running. If so, double review your JNDI binding for the MQ connection factory. You may have specified an invalid host or port. If no queue manager name has been specified, verify that the default queue manager has been defined.

Chapter 7: Troubleshooting the Agent Plug-in 51

JMS Job Failure Messages

MQJMS2008: failed to open MQ queue Reason: This message appears when there is a problem with the MQ queue definition. Action: Verify that the MQ queue has been defined. If so, the JNDI binding for the MQ queue is most likely incorrect. Review the definition for spelling mistakes or case sensitivity issues. java.lang.MyObject: Unable to instantiate the object Reason: The message class you specified in the JMS job definition is incorrect or is missing in the classpath of the agent plug-in. Action: Open the JMS job that failed, review the message class and correct it if necessary. Also ensure the message class you specified in the job definition is included in the classpath of the agent plug-in. Invalid format, Unknown parameter type Reason: The parameter type for one of the message parameters in the JMS job definition is incorrect or is missing in the classpath of the agent plug-in. Action: Open the JMS job that has the SUBERROR state, review the types of the message parameters and make corrections if necessary. Also ensure the parameter type you specified in the job definition is included in the classpath of the agent plug-in. No such plugin Reason: The J2EE plugin is not enabled for the agent plug-in. Action: Open the agentparm.txt file and edit the plugins.start_internal_n parameter, where n is the next available agent plug-in number.

52 Implementation Guide

Chapter 8: Related Documentation Documentation for the agent and scheduling managers is available in PDF format at http://ca.com/support. Note: To view PDF files, you must download and install the Adobe Reader from the Adobe website if it is not already installed on your computer. This section contains the following topics: CA Workload Automation AE Documentation (see page 53) CA Workload Automation DE Documentation (see page 54) CA Workload Automation ESP Edition Documentation (see page 54) CA Workload Automation CA 7 Edition Documentation (see page 55)

CA Workload Automation AE Documentation To work with the agent and CA Workload Automation AE, see the following documentation:

Task

Documentation

Configure the scheduling CA Workload Automation AE UNIX Implementation manager to work with the agent Guide CA Workload Automation AE Windows Implementation Guide Define, monitor, and control jobs

CA Workload Automation AE Reference Guide CA Workload Automation AE User Guide CA Workload Control Center Workload Scheduling Guide

Chapter 8: Related Documentation 53

CA Workload Automation DE Documentation

CA Workload Automation DE Documentation To work with the agent and CA Workload Automation DE, see the following documentation:

Task

Documentation

Configure the scheduling manager to work with the agent

CA Workload Automation DE Admin Perspective Help

Define jobs

CA Workload Automation DE Define Perspective Help

Monitor and control jobs

CA Workload Automation DE Monitor Perspective Help

Note: The online help is available in HTML and PDF formats.

CA Workload Automation ESP Edition Documentation To work with the agent and CA Workload Automation ESP Edition, see the following documentation:

Task

Documentation

Configure the scheduling manager to work with the agent

CA Workload Automation ESP Edition Installation and Configuration Guide

Define jobs

CA Workload Automation Agent for Application Services User Guide

Monitor and control jobs

CA Workload Automation Agent for UNIX, Linux, or Windows User Guide CA Workload Automation ESP Edition Operator's Guide

54 Implementation Guide

CA Workload Automation CA 7 Edition Documentation

CA Workload Automation CA 7 Edition Documentation To work with the agent and CA Workload Automation CA 7 Edition, see the following documentation:

Task

Documentation

Configure the scheduling CA Integrated Agent Services Implementation Guide manager to work with the agent CA Workload Automation CA 7 Edition Interface Reference Guide CA Workload Automation CA 7 Edition Systems Programming Guide Define, monitor, and control jobs

CA Integrated Agent Services User Guide CA Workload Automation CA 7 Edition Interface Reference Guide CA Workload Automation CA 7 Edition Database Maintenance Guide CA Workload Automation CA 7 Edition Command Reference Guide

Chapter 8: Related Documentation 55

Index A agent plug-in configuring • 23 controlling • 15 description • 9 function • 10 installation and configuration process • 13 installing (UNIX, Windows) • 16 uninstall process • 17 using an alias • 14 agentparm.txt file, parameters • 24 alias description • 14 setup process • 25 application servers, supported • 29

JMS jobs, failure messages • 49 JMS Subscribe jobs persisting subscribed messages • 28 job types, supported • 11

N name, agent plug-in • 25

O Oracle agent plug-in configuration • 47 required JAR files • 47 setup test • 48

P

C

POJO jobs, agent plug-in configuration • 17 proxy server, agent plug-in configuration • 26

configuration parameters, descriptions • 24 configuration process, agent plug-in • 23 configuring the agent plug-in • 26

S

F

scheduling manager configuration for the agent plug-in • 21 configuring agent parameters • 24 configuring an alias • 26 documentation • 53 starting and stopping, agent plug-in • 15

firewall, agent plug-in configuration • 26

T

H

troubleshooting, agent plug-in • 49

http connection, securing • 26

V

I

verification test, agent plug-in installation • 21

D documentation, scheduling manager • 53

installation instructions • 16 options • 15 process • 13 removing the plug-in • 17 verification test • 21

J JBoss agent plug-in configuration • 45 required JAR files • 45 setup test • 46

W WebLogic agent plug-in configuration • 31 required JAR files • 30 setup test • 31 WebSphere agent plug-in configuration • 34 EJB jobs and JMS messaging • 44 required JAR files • 33 setup for EJB jobs • 32 setup test • 35

Index 57

WebSphere MQ EJB jobs and JMS messaging • 44 JMS messaging • 35 WebSphere MQ setup • 35, 44 workload example, different jobs • 9

58 Implementation Guide