ca workload automation application services agent workload automation system agent... · ca...

Implementation Guide r11.3.3

CA Workload Automation Application Services Agent

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 is proprietary information of CA and may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA.

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 © 2014 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 Informatica (CA WA Agent for Informatica)

■ 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.

http://www.ca.com/support

mailto:[email protected]

http://www.ca.com/docs

http://www.ca.com/docs

Contents 5

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 ................................................................................................... 17

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 ............................................................................................................. 26

Create an Alias for the Agent Plug-in .................................................................................................................. 27

Configuring an Alias on the Scheduling Manager ............................................................................................... 27

Configure SSL and Secure HTTP .................................................................................................................................. 27

Configure the Agent Plug-in for a Proxy ..................................................................................................................... 28

Persist Consumed JMS Subscribe Messages .............................................................................................................. 29

6 Implementation Guide

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

Prerequisites and Assumptions .................................................................................................................................. 31

How to Set Up the Agent Plug-in for WebLogic ......................................................................................................... 32

Collect the WebLogic and Client JARs ................................................................................................................. 32

Configure the Agent Plug-in for WebLogic .......................................................................................................... 33

Testing the WebLogic Setup ................................................................................................................................ 34

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

Collect the WebSphere and Client JARs .............................................................................................................. 35

Configure the Agent Plug-in for WebSphere ....................................................................................................... 36

Testing the WebSphere Setup ............................................................................................................................ 37

How to Set up the Agent Plug-in for WebSphere (JMX Jobs only) ............................................................................. 37

Copy the IBM JARs to the Agent Computer ........................................................................................................ 38

Convert the IBM Truststore to SUN .................................................................................................................... 39

Copy the WebSphere Properties Files to the Agent Computer .......................................................................... 40

Configure the Agent Plug-in for JMX ................................................................................................................... 41

Testing the WebSphere Setup ............................................................................................................................ 42

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

Collecting the WebSphere MQ and Client JARs .................................................................................................. 43

Collecting Your WebSphere MQ Queue Connectivity Information ..................................................................... 44

Obtaining the WebSphere MQ JMS Administration Tool ................................................................................... 44

Setting Up a JNDI Provider .................................................................................................................................. 45

Collecting the JNDI Provider JARs ....................................................................................................................... 45

Configure the Agent for the JNDI Provider ......................................................................................................... 46

Defining the JNDI Connectivity Parameters ........................................................................................................ 46

Store the JNDI Information Using JMSAdmin ..................................................................................................... 48

Configure the Agent Plug-in for WebSphere MQ ................................................................................................ 50

Testing the WebSphere MQ Setup...................................................................................................................... 50

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

How to Set Up the Agent Plug-in for JBoss ................................................................................................................ 51

Collect the JBoss and Client Jars ......................................................................................................................... 52

Configure the Agent Plug-in for JBoss ................................................................................................................. 52

Testing the JBoss Setup ....................................................................................................................................... 53

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

Collecting the Oracle and Client JARs.................................................................................................................. 54

Configure the Agent Plug-in for Oracle ............................................................................................................... 54

Testing the Oracle Setup ..................................................................................................................................... 55

Chapter 7: Troubleshooting the Agent Plug-in 57

Diagnosing Failed Jobs ............................................................................................................................................... 57

JMS Job Failure Messages .......................................................................................................................................... 57

Contents 7

Chapter 8: Related Documentation 61

CA Workload Automation AE Documentation ........................................................................................................... 61

CA Workload Automation DE Documentation ........................................................................................................... 62

CA Workload Automation ESP Edition Documentation ............................................................................................. 62

CA Workload Automation CA 7 Edition Documentation ............................................................................................ 63

Index 65


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 can 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, 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.

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 the following tasks:

■ 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



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.



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 can 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.

Chapter 2: Implementation Checklist 13

Chapter 2: Implementation Checklist


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 you install the agent plug-in, 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:

■ Configure SSL and Secure HTTP (see page 27)

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

■ Persist subscribed messages that are consumed by JMS Subscribe jobs (see page 29)

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

Deciding Whether to Create an Alias


Deciding Whether to Create an Alias

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. The installation program generates the alias by adding a suffix to the agent name.

Note: If you are installing the agent plug-in to work with CA Workload Automation DE, an alias is required. Setting up an alias for use with other scheduling managers is optional.

Suppose that you have installed an agent that is named AGT10 on a Linux 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_AS. You can then restrict access to that alias to only those users that run Application Services workload. Those specific users then must specify AGT10_AS 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 Application Services has the default alias agentname_AS. You can enable or change the default alias name after installation. To work, also configure the alias on the scheduling manager.

Note: To configure agent aliasing for clustered environments, see the CA Workload Automation Agent for UNIX, Linux, or Windows Implementation Guide.


Chapter 3: Installing the Agent Plug-in


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 agentname_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, issue a command to run a start or stop script. On Windows, start or stop the agent as a Windows service.

Note: For more information about starting and stopping the agent, see the CA Workload Automation Agent for UNIX, Linux, or Windows Implementation Guide.

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.

Follow these steps:

1. Copy the appservices.pak file into the agent installation directory. You can copy this file from the product DVD or you can download a zip file that contains the file from the CA Support Online website (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. Stop the agent using one of the following commands:

■ On UNIX:

./cybAgent -s

■ On Windows:

cybAgent -s

4. Start the installation program using one of the following commands:

■ On UNIX:

./PluginInstaller appservices.pak install_dir

■ On Windows:

PluginInstaller appservices.pak install_dir

install_dir

Specifies the agent installation directory.

5. Enter the information the installation program prompts you for.

The installation program displays a message and closes automatically upon a successful installation.

6. Start the agent using one of the following commands:

■ On UNIX:

./cybAgent &

■ On Windows:

cybAgent -a



Configure the Agent Plug-in to Run POJO Jobs


Note: The installation program backs up all modified and replaced files. The backup files are compressed into a file that is 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.

Configure the Agent Plug-in to Run POJO Jobs

To run a POJO job, add the JAR or class files the job invokes to the agent installation directory using this procedure.

Follow these steps:

1. Stop the agent.

2. Locate the JAR or class files your POJO jobs invoke.

3. Do the following steps as required:

■ 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.

4. Start the agent.

The agent plug-in is configured to run POJO jobs.

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 17).

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

Disable CA WA Agent for Application Services

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

Follow these steps:

1. Ensure that all workload is complete.

2. Stop the agent.



3. Open the agentparm.txt file that is 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 that 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

Example: Renumber the communication.alias_n Parameter

Suppose that 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 4: Your Scheduling Manager and the Agent Plug-in 21

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


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, 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.

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)


Chapter 5: Configuring the Agent Plug-in


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 26) Configure SSL and Secure HTTP (see page 27) Configure the Agent Plug-in for a Proxy (see page 28) Persist Consumed JMS Subscribe Messages (see page 29)

How to Configure Agent Parameters

You configure agent parameters by editing the agentparm.txt file, which is 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 steps:

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

Configure agent parameters on CA WA Agent for UNIX, Linux, or Windows using the following procedure.

Follow these steps:

1. Change to the agent installation directory.

2. Stop the agent using one of the following commands:

■ On UNIX:

./cybAgent -s

■ On Windows:

cybAgent -s

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


3. Open the agentparm.txt file that is located in the agent installation directory.

4. Make the required changes to the agent parameters.


6. Start the agent using one of the following commands:

■ On UNIX:

./cybAgent &

■ On Windows:

cybAgent -a

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.


You can configure the following parameters in 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.

appservices.jms.subscribe.persist

Indicates whether to persist all subscribed messages that JMS Subscribes jobs consume as serialized Java objects. JMS Subscribe jobs can consume thousands or millions of messages in a short time, thus generating many files.

true

Persists all subscribed messages that JMS Subscribe jobs consume.

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

false

Does not persist subscribed messages that JMS Subscribe jobs consume.

Default: false



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

http.proxyDomain

Specifies the domain for proxy authentication.

Example: http://host.domain.proxy

http.proxyHost

Specifies the host name of the proxy server.

Example: caproxy

http.proxyOrigin

Specifies the origin host name for proxy authentication.

Example: http://host.origin.proxy

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, 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.

http.proxyPort

Specifies the port on the server of the proxy.

Example: 80

http.proxyUser

Specifies the user name for proxy authentication. To specify a domain, use the following format: domain\user.

Examples: pmf01, mydomain\causer

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


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 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.

oscomponent.classpath

Specifies the path to the JAR files that the agent requires.

plugins.start_internal_n

Specifies the agent plug-in to start by the core Java agent.

n

Denotes an integer that is 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

During the agent plug-in installation, you are prompted to create a default alias, which you can change after installation. If you enable an alias on the agent plug-in, 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 27).

2. Configure the alias on the scheduling manager (see page 27).

Configure SSL and Secure HTTP


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 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.

Configuring an Alias on the Scheduling Manager

When you create an alias for an agent plug-in, also configure the alias on the scheduling manager. 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.

To configure SSL and Secure HTTP, configure the following parameters on 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 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.

Configure the Agent Plug-in for a Proxy


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

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

Persist Consumed JMS Subscribe Messages


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, 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: Run the agent plug-in under a user account or in Windows console mode when NTLM proxy authentication is required.


The agent can persist the subscribed messages that JMS Subscribe jobs consume 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.

Follow these steps:

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


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)


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, JMX, 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.


Prerequisites and Assumptions (see page 31) How to Set Up the Agent Plug-in for WebLogic (see page 32) How to Set up the Agent Plug-in for WebSphere (EJB Jobs only) (see page 34) How to Set up the Agent Plug-in for WebSphere (JMX Jobs only) (see page 37) How to Set Up the Agent Plug-in for WebSphere MQ (JMS Messaging only) (see page 43) How to Set Up the Agent Plug-in for WebSphere and WebSphere MQ (EJB Jobs and JMS Messaging) (see page 51) How to Set Up the Agent Plug-in for JBoss (see page 51) How to Set Up the Agent Plug-in for Oracle Application Server (see page 53)

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.

How to Set Up the Agent Plug-in for WebLogic



WebLogic is a J2EE operating environment product that Oracle owns and 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, complete the following steps:

1. Collect the WebLogic and client JARs (see page 32).

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

3. Test the WebLogic setup (see page 34).

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 that are 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

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



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.

Follow these steps:

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, which is 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:

■ On agents running on HP-UX, HP-Itanium, Solaris, and Linux:

javax.xml.transform.TransformerFactory=com.sun.org.apache.xalan.internal.

xsltc.trax.TransformerFactoryImpl

javax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jax

p.SAXParserFactoryImpl

javax.xml.parsers.DocumentBuilderFactory=com.sun.org.apache.xerces.intern

al.jaxp.DocumentBuilderFactoryImpl

■ On agents running on AIX, z/Linux, and i5/OS:

javax.xml.transform.TransformerFactory=com.ibm.xtq.xslt.jaxp.compiler.Tra

nsformerFactoryImpl

javax.xml.parsers.SAXParserFactory=com.ibm.xml.xlxp.api.jaxp.impl.SAXPars

erFactoryImpl

javax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentB

uilderFactoryImpl


9. Start the agent.

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

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


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

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.


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 complete more steps to set up the agent to run JMS Publish and JMS Subscribe jobs.

To set up the agent for WebSphere, follow these steps:

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

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

3. Test the WebSphere setup (see page 37).



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 that are 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. To locate the client JAR, contact the Java EE developer.



Configure the Agent Plug-in for WebSphere


Note: The instructions in this procedure are based on IBM WebSphere Server 6.1.

Follow these steps:

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.




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.


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.

How to Set up the Agent Plug-in for WebSphere (JMX Jobs 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:


■ Provider URL



You can set up the agent for IBM WebSphere Application Server to run JMX jobs.

To set up the agent for JMX jobs on WebSphere, follow these steps:

1. Copy the IBM JARs to the agent computer (see page 38).

2. Convert the IBM truststore to SUN (see page 39).

3. Copy the WebSphere properties files to the agent computer (see page 40).

4. Configure the agent plug-in for JMX (see page 41).

5. Test the WebSphere setup (see page 42).

Note: In these procedures, we assume a standard WebSphere Application Server installation with a standalone application server profile. In a standard installation, the installation directory is C:\WebSphere and the application server profile is C:\WebSphere\AppServer\profiles\AppSrv01.



Copy the IBM JARs to the Agent Computer

To set up the agent plug-in for JMX jobs on WebSphere, first copy the IBM JARs to the agent computer.

Follow these steps:

1. Collect the following JAR files from the WebSphere installation directory:

■ runtimes/com.ibm.ws.admin.client_*.jar

■ runtimes/com.ibm.ws.ejb.thinclient_*.jar

■ runtimes/com.ibm.ws.orb_*.jar

2. (On agents running on HP-UX, HP-Itanium, Solaris, Linux, and Windows) Collect the following JAR files from the IBM JRE that WebSphere uses:

■ java/jre/lib/ibmpkcs.jar

■ java/jre/lib/ext/ibmkeycert.jar

■ java/jre/lib/ext/ibmjceprovider.jar

■ java/jre/lib/ext/ibmjcefips.jar

■ java/jre/lib/ibmjgssprovider.jar

3. Copy the collected JAR files to the following directory on the agent computer:

■ On UNIX:

install_dir/jars/ext

■ On Windows:

install_dir\jars\ext

install_dir




Convert the IBM Truststore to SUN

The default password for the IBM truststore is WebAS.

On a base application server, the default key and truststores are stored in the node directory of the configuration repository. For example, the default key.p12 and trust.p12 stores are created with the AppSrv01 profile name, the myhostNode01Cell name, and the myhostNode01 node name.

For a standard WebSphere Application Server installation with a standalone application server profile, the key and truststores are located in the following directories:

C:\WebSphere\AppServer\profiles\AppSrv01\config\cells\myhostNode01Cell\nodes\myho

stNode01\key.p12

C:\WebSphere\AppServer\profiles\AppSrv01\config\cells\myhostNode01Cell\nodes\myho

stNode01\trust.p12

The key.p12 file is optional and can be ignored.

Follow these steps:

1. Run the following command on the WebSphere Application Server computer to convert the truststore file from PKCS12 format to JKS format:

■ On UNIX:

./jre/bin/keytool -importkeystore -srckeystore truststore -srcstoretype

PKCS12 -deststoretype JKS -destkeystore trust.jks

■ On Windows:

.\jre\bin\keytool -importkeystore -srckeystore truststore -srcstoretype

PKCS12 -deststoretype JKS -destkeystore trust.jks

truststore

Specifies the name of the truststore file that is specific for your installation, for example, trust.p12.

When prompted for the destination keystore password, specify something at least eight characters long. You will need this password when you edit the ssl.client.props file on the WebSphere Application Server computer.

2. Create a directory on the agent computer to store the trust.jks file that you created in Step 1.

Note: Ensure that the full path to the directory does not contain spaces, for example: C:\WAS_security.

3. Copy the trust.jks file to the directory that you created.



Copy the WebSphere Properties Files to the Agent Computer

On the WebSphere Application Server computer, the properties files are stored in the following folder:

C:\WebSphere\AppServer\profiles\AppSrv01\properties

The following properties files are required for JMX:

■ ssl.client.props

■ sas.client.props

Follow these steps:

1. Copy the ssl.client.props file to a temporary directory.

Perform all subsequent operations on the ssl.client.props file using the copy that you have made.

2. Open the copied ssl.client.props file and locate the following property:

com.ibm.ssl.trustStorePassword={xor}CDo9Hgw=

3. Change the value of the property as follows:

com.ibm.ssl.trustStorePassword=password

password

Specifies the password that you changed using keytool.

4. Run the following command from the temporary directory:

C:\WebSphere\AppServer\bin\PropFilePasswordEncoder.bat ssl.client.props

com.ibm.ssl.keyStorePassword,com.ibm.ssl.trustStorePassword

The passwords in the copied ssl.client.props file are encoded.

5. Copy the ssl.client.props file from the temporary directory on the WebSphere Application Server computer to the agent installation directory on the agent computer.

6. Update the ssl.client.props file on the agent computer as follows:

a. Change the value of the user.root property to the directory where you copied the trust.jks file, for example:

user.root=C:/WAS_security

b. Change the value of the com.ibm.ssl.trustStore property to your trust.jks file:

com.ibm.ssl.trustStore=${user.root}/trust.jks

c. Replace the following occurrences in the file with the indicated value:

■ IbmPKIX with SunX509

■ IbmX509 with SunX509



■ IBMJSSE2 with SunJSSE

■ SSL_TLS with SSL

■ PKCS12 with JKS

■ IBMJCE with SUN

d. Change the property value for com.ibm.ssl.enableSignerExchangePrompt to false, instead of gui:

com.ibm.ssl.enableSignerExchangePrompt=false

7. Copy the sas.client.props file from the Web Sphere Application Server computer to the agent installation directory on the agent computer.

8. Change the property value for com.ibm.CORBA.loginSource in the copied sas.client.props file to none, instead of prompt (standard value):

com.ibm.CORBA.loginSource=none

Configure the Agent Plug-in for JMX

Update the agentparm.txt file with the location of the ssl.client.props and sas.client.props files.

Follow these steps:

1. Stop the agent.


com.ibm.SSL.ConfigURL=file:/install_dir/ssl.client.props

com.ibm.CORBA.ConfigURL=file:/install_dir/sas.client.props

appservices.jmx.provider=was

java.util.logging.config.class=cybermation.commonservice.logging.CybJavaLoggi

ngHandler$Factory

install_dir



4. Start the agent.

The agent plug-in is configured for JMX jobs on WebSphere.



Testing the WebSphere Setup

After you have set up the agent plug-in for JMX jobs on WebSphere, you can run a JMX job to test the setup.

For more information about defining JMX jobs, see the documentation for your scheduling manager.

Important! When defining a JMX job, specify the following format for the URL:

service:jmx:rmi://server:port/

server

Specifies the host name or IP address of the JMX server.

port

Specifies the port number of the JMX server.

Notes:

■ Due to a limitation with the IBM JRE, you may not be able to list all the domains and MBeans on a server. However, if a nonlisted MBean exists, it can be used in a job definition.

■ The cancel operation is not applicable to Application Services jobs.

■ If a credential problem occurs, an I/O error is thrown. Review the agent logs for the actual exception.

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 that 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 , follow these steps:

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

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

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

4. Set up a JNDI provider (see page 45).

5. Collect the JNDI provider JARs (see page 45).

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

7. Define the JNDI connectivity parameters (see page 46).

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

9. Configure the agent for WebSphere MQ (see page 50).

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

Collecting the WebSphere MQ and Client JARs

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



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 that is named JMSAdmin. The utility lets you connect to a JNDI provider and define your bindings within the JNDI namespace. You require JMSAdmin to store the JNDI information that is 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 that is based on platform.

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



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 that is 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.

http://java.sun.com/

http://java.sun.com/



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.

Follow these steps:

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.


6. Start the agent.

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

Defining the JNDI Connectivity Parameters

To communicate with WebSphere MQ, 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



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 that 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



Store the JNDI Information Using JMSAdmin

You use the JMSAdmin utility to store the JNDI information about the system where WebSphere MQ is installed.

Note: The instructions in this procedure use a file-based JNDI. If you are using another JNDI provider, you will need to adapt these steps.

Follow these steps:

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 that is 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 that 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. Define the JMS connection factory object using the following command:

DEFINE QCF(connectionfactory) TRANSPORT(CLIENT) QMGR(queuemanager)

HOSTNAME(host) PORT(port)

7. Define the JMS destination using the following command:

DEFINE Q(destination) QMGR(queuemanager) QUEUE(queuename)

8. Verify your definition using the following command:

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.



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.

Follow these steps:

1. Source the code into the shell environment on UNIX:

./opt/mqm/java/bin/setjmsenv

2. Create a directory named fsjndi on the file system:

cd /var/mqm

mkdir fsjndi

3. Create a JMSAdmin configuration file named MyJMSAdmin.config:

cp $MQ_JAVA_INSTALL_PATH/bin/JMSAdmin.config MyJMSAdmin.config

4. 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

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

6. Invoke the JMSAdmin utility with the JMSAdmin configuration file:

MQ_JAVA_INSTALL_PATH/bin/JMSAdmin -cfg MyJMSAdmin.config

7. Define the JMS connection factory object using the following command:

DEFINE QCF(MY_QUEUE_CF) TRANSPORT(CLIENT) QMGR(queue.manager)

HOSTNAME(somehost) PORT(1414)

8. Define the JMS destination using the following command:

DEFINE Q(MY_QUEUE) QMGR(queue.manager) QUEUE(MY.QUEUE)

9. Verify your definition using the following command:

DISPLAY CTX

The JMS Admin utility displays the following lines.

.bindings java.io.File

MY_QUEUE_CF com.ibm.mq.jms.MQQueueConnectionFactory

MY_QUEUE com.ibm.mq.jms.MQQueue

10. 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. Update the Provider URL parameter that is used during queue connections to the corresponding location.



Configure the Agent Plug-in for WebSphere MQ


Follow these steps:

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.


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.


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:


■ Provider URL

■ Connection factory

■ JNDI destination


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 that 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, follow these steps:

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, follow these steps:

1. Collect the JBoss and client jars (see page 52).

2. Configure the agent for JBoss (see page 52).

3. Test the JBoss setup (see page 53).

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 that are deployed on your JBoss Application Server, collect the following JAR files:

■ jbossall-client.jar located in the JBoss installation directory



Configure the Agent Plug-in for JBoss


Note: The following instructions are based on JBoss Application Server 4.2.0.

Follow these steps:

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.


Note: We recommend you create the subdirectory in the existing agentdir/jars/ext directory.


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.

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


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:



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


■ Provider URL



Oracle Application Server is a software program that deploys J2EE-based applications using Oracle Containers (OC4J). If necessary, you can download the OC4J file from the Oracle website.

To set up the agent for Oracle Application Server, follow these steps:

1. Collect the Oracle and client jars (see page 54).

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

3. Test the Oracle setup (see page 55).



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 that are 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



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.

Follow these steps:

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.



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.


8. Start the agent.

The agent plug-in is configured for the 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:



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


■ Provider URL

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



Chapter 7: Troubleshooting the Agent Plug-in


Diagnosing Failed Jobs (see page 57) JMS Job Failure Messages (see page 57)

Diagnosing Failed Jobs

To diagnose a failed job, 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 that the agent plug-in returns.

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:




com.sun.jndi.fscontext.RefFSContextFactory Exception

Reason:

The fscontext.jar file is missing from the classpath of the agent plug-in.

Action:


com/sun/jndi/toolkit/chars/CharacterDecoder

Reason:

The providerutil.jar file is missing from the classpath of the agent plug-in.

Action:


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.



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.



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 that 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 verify that 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 verify that 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.


Chapter 8: Related Documentation

Documentation for the agent and scheduling managers is available in HTML and PDF format at http://ca.com/support.

Note: To view PDF files, download and install the Adobe Reader from the Adobe website if it is not already installed on your computer.


CA Workload Automation AE Documentation (see page 61) CA Workload Automation DE Documentation (see page 62) CA Workload Automation ESP Edition Documentation (see page 62) CA Workload Automation CA 7 Edition Documentation (see page 63)

CA Workload Automation AE Documentation

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

Task Documentation

Configure the scheduling manager to work with the agent

CA Workload Automation AE UNIX Implementation 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


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


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


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

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


CA Integrated Agent Services Implementation Guide

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

Index 65

Index

A

agent plug-in configuring • 23 controlling • 15 description • 9 function • 10 installation and configuration process • 13 uninstall process • 17

agentparm.txt file, parameters • 24 alias

setup process • 26 application servers, supported • 31

C

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

D

documentation, scheduling manager • 61

F

firewall, agent plug-in configuration • 28

H

http connection, securing • 27

I

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

J

JBoss agent plug-in configuration • 52 required JAR files • 52 setup test • 53

JMS jobs, failure messages • 57 JMS Subscribe jobs

persisting subscribed messages • 29 job types, supported • 11

N

name, agent plug-in • 27

O

Oracle agent plug-in configuration • 54 required JAR files • 54 setup test • 55

P

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

S

scheduling manager configuration for the agent plug-in • 21 configuring agent parameters • 24 configuring an alias • 27 documentation • 61

starting and stopping, agent plug-in • 15

T

troubleshooting, agent plug-in • 57

V

verification test, agent plug-in installation • 21

W

WebLogic required JAR files • 32 setup test • 34

WebSphere agent plug-in configuration • 36 EJB jobs and JMS messaging • 51 required JAR files • 35 setup for EJB jobs • 34 setup test • 37

WebSphere MQ EJB jobs and JMS messaging • 51 JMS messaging • 43

WebSphere MQ setup • 43, 51 workload example, different jobs • 9

ca workload automation application services agent workload automation system agent... · ca...

Documents