IBM® Tivoli®

IBM Tivoli Composite Application Manager for Microsoft

® BizTalk

Server Agent

KB Notes and HOW TOs

CONTENTS

OVERVIEW 3

1.1 INTRODUCTION 3 1.2 TERMS AND ABBREVIATIONS 3 1.3 USER GUIDES 3

HOW TOS 4

1.4 HOW TO CONFIGURE THE AGENT STARTUP? 4 1.5 HOW TO RECONFIGURE THE AGENT? 5 1.6 HOW TO CHECK WHETHER PREREQUISITES ARE FULFILLED AND AGENT CAN BE INSTALLED ON THE SYSTEM? 7 1.7 HOW TO SEED AGENT SUPPORT TO REMOTE ITM? 8 1.8 HOW TO GENERATE IDML BOOK FROM AGENT DLA? 8 1.9 DOES THE AGENT SUPPORT IN CLUSTER ENVIRONMENT? IF YES THEN PROVIDE THE STEPS FOR CONFIGURATION? 9 1.10 HOW TO ENABLE MAXIMUM TRACE LOGS? 9 1.11 HOW TO BUNDLE LOGS FOR L3 TEAM? 10 1.12 HOW TO RUN PARAMETERIZED TAKE ACTION COMMANDS? 11 1.13 CAN NON-ADMINISTRATOR USER RUN THE MONITORING AGENT? 12 1.14 HOW TO START OR STOP ALL PRE-DEFINED SITUATIONS? 13 1.15 HOW TO SET PARAMETERS FOR DATA COLLECTION INTERVAL? 13 1.16 HOW TO ADD LOG DETAILS FOR „KQB_APPSTATUS.EXE‟ APPLICATION? 14

PROBLEMS, SYMPTOMS, SOLUTIONS 16

1.1 BIZTALK AGENT DOESN‟T DISPLAY NEW PERFMON OBJECTS. 16 1.2 TWO INSTANCES OF BIZTALK AGENT ARE DISPLAYED IN AMS WORKSPACE. 16 1.3 NAVIGATOR ITEMS AND WORKSPACE TITLES ARE LABELED WITH INTERNAL NAMES LIKE IN A FORMAT KXX:KXX0000 16 1.4 THE HOVER HELP FOR FULL NAME ATTRIBUTE IN AVAILABILITY GROUP DISPLAYS SOME TEXT 17 1.5 HISTORICAL DATA COLLECTION IS UNAVAILABLE 17 18

Overview

1.1 Introduction

This document lists and provides solutions to common problems faced by customers of IBM Tivoli Microsoft BizTalk Server Agent during setting up/monitoring of the product in their BizTalk Server environments. The intended audience of the document is Level 2 personnel for IBM Tivoli Microsoft BizTalk Server Agent and the customers of the product.

1.2 Terms and abbreviations

1. WMI: Windows Management Instrumentation

2. SOAP: Simple Object Access Protocol

3. TEP: Tivoli Enterprise Portal

4. TCR: Tivoli Common Reporting

5. RFC: Request For Change

6. FTP : File Transfer Protocol

7. MSMQ: Microsoft Message Queuing

8. BTS: BizTalk Server

9. POP: Post Office Protocol

10. BAM: Bussines Activity Monitoring

11. TDDS: Tracking Data Decode Service

12. SWG: Software Group

13. SDA: Self Describing Agent

14. EDI: Electronic Data Interchange

15. EIP: Enterprise Integration Platform

16. SSO: Single Sign-On

Note: Please follow the below link to have complete list of acronyms and abbreviations used with BizTalk Server.

http://msdn.microsoft.com/en-us/library/aa578028

1.3 User Guides

Provide the links for UG‟s – online links

HOW TOs

1.4 How to configure the agent startup?

By default the Agent is installed and running by “Local System” account which have administrative Privileges over the System.

If any other specific credentials required other than the default “Local System” Account, then right click on agent service and select Change Startup. The options are displayed as in the image below, provide the username and the password of the user configured which has appropriate rights/privileges to various groups. Once done, click OK.

Recycle the Agent to take the configuration effects.

1.5 How to reconfigure the Agent?

We need to reconfigure the agent when we want to establish its connection with a TEMS (Monitoring Server).

1 Right-click on Agent, and select „Reconfigure‟ option. 2 Provide the TEMS machine IP Address or Hostname.

3 Configuration Panel will get appear:

Configuration parameters for the Application Status attribute group:

a) API File Path (KQB_API_FILEPATH)

Type Default or specify the full path of the Microsoft.BizTalk.ExplorerOM.dll file. Default Value is Default.

b) Use Windows Authentication (KQB_DBACCESS_USE_WINDOWS_AUTHENTICATION) Type True or False. If you type False, then specify the database user ID and password. If you type True to select the Windows Authentication mode, you do not have to specify the user ID and password to access the BizTalk Management database. Default Value is true.

c) Database User ID (KQB_DB_USER_ID) Type the user ID for the BizTalk Management database. No default value.

d) Database Password (KQB_DB_USER_PWD) Type the password for the BizTalk Management database. No default value.

4 Recycle the agent for the changes to take effect.

1.6 How to check whether prerequisites are fulfilled and Agent can be installed on the System?

The Install Prerequisite checker feature makes it possible to identify many issues where agent installations can fail due to environment/machine setup prior to agent installation.

Predefined checks provided by Install Prerequisite Checker:

Physical Memory availability

Storage availability

User admin rights

OS version, level, architecture and configurations

Availability & version of application to be monitored by agent.

Install prerequisites are not common across all component installations, some agents require specific prerequisite checks based on the application/system they are monitoring. Agent can use required predefined checks respective to the agent or can implement agent specific checks those are not available in predefined checks. Prerequisite checks can be different for different versions of the agent.

Install prerequisite can be executed in two ways.

1. Remotely through tacmd command:

Prerequisite bundles are automatically gets selected for agent when we add that agent‟s bundle files.

tacmd addbundles –i <image path> -t <product code>

To execute prerequisite of required agent command is

tacmd checkprereq –h <target m/c> -u <user name> -w <password> -t <product code>

This command will give result in tacmd getdeploystatus. If prerequisites are not fulfilled, log file is created in CANDLEHOME\logs\checkprereq_results folder describing failure reasons (location of logs is same for UNIX machine).

2. Local Standalone execution: Install prerequisite checker can be executed locally on a machine. To execute install prerequisite checker untar prerequisite tar file on a local m/c or use the file from ITCAMMA installer‟s windows\prereqchecker folder by copying to a temporary folder. Traverse to the prereqchecker\windows folder and execute the command.

prereq_checker.bat "<Product Code1> [product version1],[ <Product Code2> [product version2]]..." [detail] [debug] [PATH=<Agent install path>]

Ex. prereq_checker.bat "KQB" detail PATH=<CANDLEHOME>

Result of this command is displayed on command prompt. Result.txt is also gets created in the prereqchecker folder.

Multiple product code can be given to check those all agents‟ prerequisites on the target m/c. It will check prerequisite for all agents specified in the product code list.

Product version specifies for which agent version prerequisite checks will be performed. Readme file is a help file available for Local Standalone execution.

1.7 How to seed Agent support to remote ITM?

The self-describing agent (SDA) feature, introduced in ITCAMMA v6.3, makes it possible for the agents to become operational after installation, without having to perform additional product support installation steps on ITM side.

The self-describing agent feature must be enabled on the following IBM Tivoli Monitoring components:

• Hub Tivoli Enterprise Monitoring Server.

• Tivoli Enterprise Portal Server.

• Self-describing agent supported agents. The Default state of SDA for BizTalk agent is „Enabled‟.

• Any Remote Tivoli Enterprise Monitoring Server the agent is connected to.

The SDA feature can be enabled for TEPS & TEMS by changing an environment variable in ENV File. For example:

TEPS_SDA=Y

KMS_SDA=Y

SDA feature is supported by Agent Framework v623+. So, you can upgrade the Agent framework with ITM or OS Agent installer v623+.

Once the SDA is enabled, support will get seeded remotely on TEMS & TEPS, once agent is successfully installed and configured to proper TEMS.

1.8 How to generate IDML book from Agent DLA?

DLA (kqb_tmsdla.xml) comes with Agent‟s TEPS support and is present in the location C:\IBM\ITM\CNPS\tmsdla.

OS Agent DLA (knt_tmsdla.xml) is prerequisite for Biztalk Agent DLA.

To generate IDML book run the command:

C:\IBM\ITM\CNPS\tmsdla.bat

1.9 Does the Agent support in Cluster Environment? If yes then provide the steps for configuration?

SQL Backend used in BizTalk server Deployment supports Clustered Environment for user load balancing.

Also multiple BizTalk servers can be configured under a BizTalk Group for load balancing purpose.

But BizTalk Agent needs to be installed on each Server machine to view data for respective services.

1.10 How to enable maximum trace logs?

The BizTalk Server Agent generates a set of logs while it runs. It logs some steps in its execution. These logs are helpful to trace the working of the BizTalk agent in case of a failure or if the agent is not working as expected. The logging has certain „levels‟ to it and for the maximum coverage the logging has to be set to the maximum. Follow the steps mentioned below to enable the perfmon counters.

Step 1) Launch the „IBM Tivoli Monitoring‟ application

Step 2) Right click the agent name and click „Advanced‟ and then „Edit Trace Parms‟

Step 3) Select / set the options as in the image below and click OK

1.11 How to bundle logs for L3 team?

The logs generated by the agent are trace marks about the working of the agent. These logs contain vital information about the steps the agent executed. The logs generated by the agent are located at the path

C:\IBM\ITM\TMAITM6\logs (in case the agent is installed on another drive, the path would start with that drive letter). ZIP the logs folder entirely to be sent to the L3 team.

You can use the pdcollect tool to collect the most commonly used information from a system. This tool gathers log files, configuration information, version information, and other data. For more information about using this tool, see the "pdcollect tool" in the IBM Tivoli Monitoring Troubleshooting Guide.

For information about working with IBM Software Support, see IBM Support Portal Service Requests and

PMRs (http://www.ibm.com/support/entry/portal/Open_service_request/Software/Software_support_(general)).

1.12 How to run Parameterized Take Action Commands?

Most „Take Actions‟ don‟t take any user inputs and perform a single specific operation like starting or stopping a service.

However a parameterized Take Actions take parameters provided by user to perform an operation. For example, in BizTalk Agent has

Start Host Instance Service

There are two ways in which you can use these Take Actions effectively

1. Provide the service name, as parameter to Take Action, which you want to start.

2. Right-click on the service in Availability workspace, which you want to start.

Click Select under Take Action option.

Select the desired Take Action and click Run.

1.13 Can Non-Administrator user run the monitoring Agent?

You can run the monitoring agent for BizTalk Server as a non-administrator user; however, some functionality is unavailable. To create a non-administrator user, create a new user (non-administrator) and set up registry permissions as follows for the new user:

Full access to HKEY_LOCAL_MACHINE\SOFTWARE\Candle

Read access to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowsNT\CurrentVersion\Perflib

If you define these permissions for a non-administrator user, data is displayed for all the Perfmon-based attribute groups. See User Guide for a list of all Perfmon-based attributes.

The following attribute groups display data for users who are members of the Administrators group:

Availability

Messagebox Database

Management Database

Rule Engine Database

BAM Database

Tracking Database

Application Status

Send Port Status

Send Port Group Status

Orchestration Status

Receive Location Status

Service Instance Status and Class

BizTalk Group Server Host

1.14 How to Start or stop all pre-defined Situations?

On ITM Portal for to MS BizTalk Server node, and select Manage Situations.

Either click on „Select All‟ or select the required situations.

Now click Start or stop button place on top-left side of the window.

1.15 How to set parameters for Data Collection interval?

Event Log workspace events are unfiltered, are not collected more than every 60 seconds, and are removed from the Event Log Views after 1 hour of being received. All events currently in the Application Event Log are sent to the Tivoli Enterprise Monitoring Server when the agent starts. Environment variables that control the behavior of the Event Log Workspace are stored in the agent ENV file on the Tivoli Enterprise Monitoring Agent where the agent is running. These variables are stored:

CDP_DP_CACHE_TTL

This value is the minimum number of seconds before data (for a particular table) is collected again. By default this variable is present in the ENV file and the value is set to 60.

CDP_NT_EVENT_LOG_GET_ALL_ENTRIES_FIRST_TIME

This variable determines whether the agent sends all events currently in the Application Event Log to the Tivoli Enterprise Monitoring Server when the agent starts. Legal values are YES and NO. By default this variable is present in the ENV file and the value is set to NO.

CDP_NT_EVENT_LOG_CACHE_TIMEOUT

This variable determines how long in seconds that events are displayed in the Tivoli Enterprise Monitoring Server Event Log Views. By default, this variable is not present in the ENV file. A default value of 3600 (1 Hour) is used unless overridden by the presence of this variable in the agent ENV file. The minimum legal value is 300.

To view or edit the agent ENV file on the Tivoli Enterprise Monitoring agent where the agent is installed, use Manage Tivoli Enterprise Monitoring Services to select the agent. Right-click and select Advanced - Edit ENV File. The agent must be restarted to implement changes.

1.16 How to add log details for ‘KQB_AppStatus.exe’ application?

To get the trace logs for „KQB_AppStatus.exe‟ application which is used to fetch data for the Application Status attribute group, complete the following steps:

1. Copy and paste the following snippet in a text editor:

<!--START-->

<configuration>

<system.diagnostics>

<trace autoflush="true">

<listeners>

<remove name="Default"/>

<add name="EventLogListener"

type="System.Diagnostics.EventLogTraceListener"

initializeData="kqbAppsDS"/>

<add name="TextWriterListener"

type="System.Diagnostics.TextWriterTraceListener"

initializeData="<Folder_Path>\<File_Name>.log"/>

</listeners>

</trace>

</system.diagnostics>

</configuration>

<!--END-->

Note:

Include add name="EventLogListener" to save trace information in an event log file. Include add name="TextWriterListener" to save trace information in a text file. If both options are used, trace information is saved in both the event log and text file.

Enter the required <folder path> and <file name> in the initializeData option.

For Example:

initializeData="<Folder_Path>\<File_Name>.log"/>

Would be

initializeData="C:\logs\appl_status_attr_group_data.log"/>

2. Save the file as "KQB_AppStatus.exe.config" to your hard disk drive.

3. Copy "KQB_AppStatus.exe.config" file to the Microsoft BizTalk Server agent installation directory, depending on your operating system:

CANDLEHOME\TMAITM6 (32-bit Windows operating system)

CANDLEHOME\TMAITM6_X64 (64-bit Windows operating system)

Problems, Symptoms, Solutions

Information flow from Tivoli Monitoring for Microsoft Applications: Microsoft BizTalk Server Agent v6.3 component to /from Tivoli Enterprise Portal (TEP), TEP Server (TEPS), Hub/Remote and Tivoli Enterprise Monitoring Servers (TEMS) will remain unchanged.

1.1 BizTalk Agent doesn’t display new perfmon objects.

Problem:

If you load or unload the BizTalk performance monitor objects while the agent is active, the BizTalk agent does not dynamically update the values and displays the previous values.

Solution:

Recycle the BizTalk agent.

1.2 Two instances of BizTalk agent are displayed in AMS workspace.

Problem:

If you change the BizTalk agent startup with a user that has domain administrator privileges in the Agent Management Services, and then recycle the BizTalk and OS agent, two instances of the agent are displayed in the Agent Management Services workspace.

Solution:

To resolve the issue, follow these steps:

1. Stop the OS agent.

2. Navigate to the \\TMAITM6\CAP folder.

3. Delete the pas.dat file.

4. Start the OS agent.

1.3 Navigator items and workspace titles are labeled with internal names like in a format Kxx:KXX0000

Symptom(s):

1. Navigator items and workspace titles are labeled with internal names or agent IDs like Kxx:KXX0000 instead of the correct names (such as Communicator Web Access, Archiving), where XX and xx represent the two-character agent code.

Possible Reason(s):

• Agent Support might not get correctly installed on TEMS, TEPS and TEP client.

Solution(s):

Ensure that application support has been added on the monitoring server, portal server, and portal client.

For more information about installing application support, see “Installing and enabling application support” in the IBM Tivoli Monitoring Installation and Setup Guide.

1.4 The hover help for Full Name attribute in Availability Group displays some text

Symptom(s):

2. On the Tivoli Enterprise Portal, the hover help for the Full Name attribute in the Availability attribute group displays the following text for both services and processes:

3. The full name of the process including the path.

4. This description is valid only when the attribute name refers to a process. The description is not valid for a service because a service name does not display a path.

Possible Reason(s):

This behavior is expected. The Tivoli Enterprise Portal is designed to display the same hover help for the Full name attribute, regardless of whether the attribute is a process or a service.

Solution(s):

• None.

1.5 Historical data collection is unavailable

Symptom(s):

Historical data collection is unavailable because of incorrect queries in the Tivoli Enterprise Portal

Possible Reason(s):

• The Sort By, Group By and First/Last functions column are not compatible with the historical data collection feature. Use of these advanced functions makes a query ineligible for historical data collection.

• Even if data collection has been started, you cannot use the time span feature if the query for the chart or table includes column functions or advanced query options (Sort By, Group By, First/Last).

Solution(s):

To ensure support of historical data collection, do not use the Sort By, Group By, or First/Last functions in your queries.

See the IBM Tivoli Monitoring Administrator‟s Guide or the Tivoli Enterprise Portal online help for information about the Historical Data Collection function.

End of Document