Administrator's Guide: BMC Atrium Integration Engine 7.1.00

BMC Atrium Integration Engine 7.1.
00
Administrators Guide
August 2007
www.bmc.com
Contacting BMC Software

You can access the BMC Software website at http://www.bmc.com. From this website, you can obtain information about the company, its products, corporate offices, special events, and career opportunities.
United States and Canada

Address BMC SOFTWARE INC 2101 CITYWEST BLVD HOUSTON TX 77042-2827 USA Telephone 713 918 8800 or 800 841 2031 Fax 713 918 8000
Outside United States and Canada

Telephone (01) 713 918 8800 Fax (01) 713 918 8000
If you have comments or suggestions about this documentation, contact Information Development by email at doc_feedback@bmc.com. Copyright 19992007 BMC Software, Inc. BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are registered with the U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other BMC trademarks, service marks, and logos may be registered or pending registration in the U.S. or in other countries. All other trademarks or registered trademarks are the property of their respective owners. DB2 is a registered trademark of International Business Machines Corporation. IBM is a registered trademark of International Business Machines Corporation. ITIL is a registered trademark, and a registered community trademark of the Office of Government Commerce, and is registered in the U.S. Patent and Trademark Office. Linux is the registered trademark of Linus Torvalds in the U.S. and other countries. Oracle is a registered trademark of Oracle Corporation. UNIX is a registered trademark of The Open Group. BMC Software considers information included in this documentation to be proprietary and confidential. Your use of this information is subject to the terms and conditions of the applicable End User License Agreement for the product and the proprietary and restricted rights notices included in this documentation.
Restricted Rights Legend

U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is BMC Software, Inc., 2101 CityWest Blvd., Houston, TX 77042-2827, USA. Any contract notices should be sent to this address.
Customer Support
You can obtain technical support by using the Support page on the BMC Software website or by contacting Customer Support by telephone or email. To expedite your inquiry, please see Before Contacting BMC Software.
Support Website
You can obtain technical support from BMC Software 24 hours a day, 7 days a week at http://www.bmc.com/support_home. From this website, you can:

Read overviews about support services and programs that BMC Software offers. Find the most current information about BMC Software products. Search a database for problems similar to yours and possible solutions. Order or download product documentation. Report a problem or ask a question. Subscribe to receive email notices when new product versions are released. Find worldwide BMC Software support center locations and contact information, including email addresses, fax numbers, and telephone numbers.
Support by telephone or email

In the United States and Canada, if you need technical support and do not have access to the Web, call 800 537 1813 or send an email message to customer_support@bmc.com. (In the Subject line, enter SupID:<yourSupportContractID>, such as SupID:12345.) Outside the United States and Canada, contact your local support center for assistance.
Before Contacting BMC Software

Have the following information available so that Customer Support can begin working on your issue immediately:
Product information Product name Product version (release number) License number and password (trial or permanent)
Operating system and environment information Machine type Operating system type, version, and service pack System hardware configuration Serial numbers Related software (database, application, and communication) including type, version, and service pack or maintenance level
Sequence of events leading to the problem Commands and options that you used Messages received (and the time and date that you received them) Product error messages Messages from the operating system, such as file system full Messages from related software
Contents
Preface 9
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Best Practice and New icons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Related documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Integration Engine documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 BMC Atrium CMDB documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 AR System documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Chapter 1 Understanding Integration Engine 15 16 17 18 18 19 19 19 20 21 22 22 25 26 27 28 28 29 29 31 31 35 39 42 43 43 44
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integration Engine components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Exchange application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integration Engine service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Request interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Development Kit interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The data transfer process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The initialization phase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The processing phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performance considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 2 Installing Integration Engine
Installation overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting the prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Windows prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UNIX prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database adapter prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Gathering information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing or upgrading Integration Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing or upgrading Integration Engine on Windows . . . . . . . . . . . . . . . . . . . . Installing or upgrading Integration Engine on UNIX . . . . . . . . . . . . . . . . . . . . . . . Installing Integration Engine Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Post-installation configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Uninstalling Integration Engine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing Integration Engine from Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing Integration Engine from UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents
Chapter 3
Defining rules and queries
45
Defining rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Constant syntax (constant|<string>) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Precedence syntax (<{rule}> <{rule}> <{rule}>) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Function syntax (function|<function(parameters)>) . . . . . . . . . . . . . . . . . . . . . . . . . 48 SQL command syntax (sql|<command>) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Target SQL command syntax (targetsql|<command>) . . . . . . . . . . . . . . . . . . . . . . . 53 Process command syntax (process|<command>) . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Target process command syntax (targetprocess|<command>) . . . . . . . . . . . . . . . . 54 If/then/else syntax (STMT|<statement>) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Defining queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 AR System query syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Data key syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Row-level query syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Using the adapter rule helper utilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Using the DB2 Adapter Rule Helper utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Using the Oracle Adapter Rule Helper utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Using the SQL Adapter Rule Helper utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Using the XML Adapter Rule Helper utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Using the File Adapter Rule Helper utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Using the the adapter rule helper utilities on UNIX platforms. . . . . . . . . . . . . . . . 69 Populating the rule control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Chapter 4 Activating event-driven data exchanges 73
Creating a request on the Application Pending form . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Creating a request using the eiexfer utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Examples of the event-driven request command syntax . . . . . . . . . . . . . . . . . . . . . 80 Completion codes returned by eiexfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Activating an event-driven data exchange through workflow . . . . . . . . . . . . . . . . . . . 83 Chapter 5 Running and configuring the Integration Engine service 85
Running the Integration Engine service on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Running the Integration Engine service on UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Loading the adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Understanding the configuration file and its parameters . . . . . . . . . . . . . . . . . . . . . . . 88 Sample configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Editing the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Managing instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Changing Integration Engine AR System password. . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Chapter 6 Logging and debugging 97
Log messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Debug messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Using the <instance name>_eiemain.dbg debug file . . . . . . . . . . . . . . . . . . . . . . . . 102 Using an <exchange_name>.dbg debug file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Debug logging settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
6 Administrators Guide
Chapter 7
Troubleshooting Integration Engine
109
Running the Integration Engine service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Estimating memory usage when running a data exchange . . . . . . . . . . . . . . . . . 110 Troubleshooting data exchanges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Export exchange and mapping configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Handling data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Using date functions in AR System Date/Time fields . . . . . . . . . . . . . . . . . . . . . . . . . 114 Using character string comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Determining if a record has an out-of-range error . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Stopping the AR System server accidentally when stopping the Integration Engine service on UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Adding missing items in the AR System field drop-down lists . . . . . . . . . . . . . . . . . 116 Index 119
Contents
Preface
This document describes how to install, license, and use the BMC Atrium Integration Engine (Integration Engine) application. Integration Engine is used to transfer data between external databases and BMC Remedy Action Request System (AR System) applications or between external databases and the BMC Atrium Configuration Management Database (CMDB) product.
Audience
This document is intended for AR System administrators who install, configure, use, or maintain a custom-built or BMC Remedy application that they want to use with an external database. The administrator is the architect of AR System applications and oversees their integration with external applications. As an administrator, you must know how to use the AR System, including the BMC Remedy Administrator, Remedy Import, and BMC Remedy User applications. The AR System administrator can designate another user to be the subadministrator. Subadministrators must be familiar with external applications and their database table structure. They must also be familiar with access principles and designing and modifying workflow. See the BMC Remedy User Online Help and the BMC Remedy Action Request System 7.1.00 Workflow Objects for additional information.
Preface
BMC Atrium Integration Engine 7.1.00
Best Practice and New icons

Documentation for Integration Engine contains two icons:
Icon Description The New icon identifies features or products that are new or enhanced with version 7.1.00.
The Best Practice icon highlights processes or approaches that BMC has identified as the most effective way to leverage certain features in the application.
Related documentation
This section describes the related documentation for Integration Engine, BMC Atrium CMDB, and AR System.
Integration Engine documents

The following table shows the Integration Engine documentation. The softcopy documentation is available in the Docs directory of the product DVD, the Electronic Product Distribution (EPD) site at http://webapps.bmc.com/epd and the Support site at http://www.bmc.com/support_home.
Title BMC Atrium Integration Engine 7.1.00 Adapter Development Kit Developers Guide Description Audience Format Print and PDF
Procedures describing how to build adapters that Developers can transfer information between an external data store and either AR System forms or BMC Atrium CMDB.
BMC Atrium Integration Procedures describing how to create data Engine 7.1.00 Online Help exchanges and data mappings and to configure administrative options, available by clicking Help in the product interface. BMC Atrium Integration Combined index of all guides. Engine 7.1.00 Master Index BMC Atrium Integration Information about new features, open issues, and Engine 7.1.00 Release Notes resolved issues. BMC Atrium Integration Procedures and conceptual information about Engine 7.1.00 Users Guide creating data exchanges and data mappings.
Users and Product Administrators Help
Everyone Everyone Users
Print and PDF Print and PDF Print and PDF
10
BMC Atrium CMDB documents

The following table shows BMC Atrium CMDB documentation. The softcopy documentation is available in the Docs directory of the product DVD, the Electronic Product Distribution (EPD) site at http://webapps.bmc.com/epd and the Support site at http://www.bmc.com/support_home.
Title BMC Atrium CMDB 2.1.00 Common Data Model Diagram BMC Atrium CMDB 2.1.00 Concepts and Best Practices Guide BMC Atrium CMDB 2.1.00 Data Model Help Document provides Hierarchical diagram of all classes in the Common Data Model (CDM) including unique attributes and applicable relationships Audience Administrators Format Print and PDF
Information about CMDB concepts and best IT leaders and practices for planning your BMC Atrium CMDB administrators implementation Description and details of superclasses, subclasses, attributes, and relationship classes for each class. Contains only information about the Common Data Model at first, but can be updated to include information about data model extensions you install. Administrators
Print and PDF
HTML
BMC Atrium CMDB 2.1.00 Developers Reference Guide BMC Atrium CMDB 2.1.00 Installation and Configuration Guide
Information about creating API programs, using Administrators C and web services API functions and data and programmers structures, and a list of error messages Information about installing and configuring BMC Atrium CMDB, including permissions, class definitions, reconciliation, and federation Administrators
Print and PDF
Print and PDF
BMC Atrium CMDB Information about Java classes, methods, and 2.1.00 Javadoc API Help variables that integrate with BMC Atrium CMDB Mapping Your Data to BMC Atrium CMDB 2.1.00 Classes
Programmers
HTML
Administrators Mappings of common IT objects to the appropriate class in which to store them, whether part of the Common Data Model or an extension. Also includes information about further categorizing instances using key attributes. Combined index of all guides Everyone
Spreadsheet, print and PDF
BMC Atrium CMDB 2.1.00 Master Index BMC Atrium CMDB 2.1.00 Online Help BMC Atrium CMDB 2.1.00 Release Notes
Print and PDF Product Help
Help for using and configuring BMC Atrium Users and CMDB, available by clicking Help in the product administrators interface Information about new features, open issues, and resolved issues Everyone
Print and PDF
Preface
11
Title BMC Atrium CMDB 2.1.00 Troubleshooting Guide
Document provides Information about resolving issues with BMC Atrium CMDB components, including API, filter, and console error messages and their solutions.
Audience
Format
Administrators, Print and PDF programmers, and BMC Support personnel Print and PDF
BMC Atrium CMDB 2.1.00 Users Guide
Information about using BMC Atrium CMDB, Users including searching for and comparing CIs and relationships, relating CIs, viewing history, and launching federated data
AR System documents
The following table shows BMC Remedy AR System documentation. The softcopy documentation is available in the Docs directory of the product DVD, the Electronic Product Distribution (EPD) site at http://webapps.bmc.com/epd and the Support site at http://www.bmc.com/support_home.
Title BMC Remedy Action Request System 7.1.00: Concepts Description Overview of AR System architecture and features with in-depth examples; includes information about other AR System products as well as a comprehensive glossary for the entire AR System documentation set. Procedures for installing AR System Audience Everyone Format PDF and Print
BMC Remedy Action Request System 7.1.00: Installing BMC Remedy Action Request System 7.1.00: Getting Started BMC Remedy Action Request System 7.1.00: Form and Application Objects BMC Remedy Action Request System 7.1.00: Workflow Objects BMC Remedy Action Request System 7.1.00: Configuring
Administrators
PDF and Print PDF and Print PDF and Print
Topics that are usually only learned when Everyone first starting to use the system, including logging in, searching for objects, and so on. Information about the components necessary to build applications in AR System, including applications, fields, forms, and views. Developers
Overview of all the workflow information. Developers Information about configuring AR System Administrators servers and clients, localizing, importing and exporting data, and archiving data.
PDF and Print PDF and Print PDF and Print
Information about the mid tier, including Administrators BMC Remedy Action Request mid tier installation and configuration, and System 7.1.00: Installing and Administering BMC Remedy Mid web server configuration. Tier BMC Remedy Action Request System 7.1.00: Integrating with Plug-ins and Third-Party Products Information about integrating AR System Administrators with external systems using plug-ins and and Developers other products, including LDAP, OLE, and ARDBC.
PDF and Print
12
Title BMC Remedy Action Request System 7.1.00: Optimizing and Troubleshooting
Description
Audience
Format PDF and Print
Server administration topics and technical Administrators essays related to monitoring and maintaining AR System for the purpose of optimizing performance and troubleshooting problems.
BMC Remedy Action Request Database administration topics and rules Administrators System 7.1.00 Database Reference related to how AR System interacts with specific databases; includes an overview of the data dictionary tables. BMC Remedy Action Request System 7.1.00: Administering BMC Remedy DSO BMC Remedy Action Request System 7.1.00: Administering BMC Remedy Flashboards Server administration and procedures for Administrators implementing a distributed AR System server environment with the BMC Remedy Distributed Server Option (DSO). Flashboards administration and procedures for creating and modifying flashboards and flashboards components to display and monitor AR System information. Information about AR System data structures, C API function calls, and OLE support. Quick reference to C API function calls.
PDF and Print
PDF and Print
Administrators PDF and and Programmers Print
BMC Remedy Action Request System 7.1.00: C API Reference BMC Remedy Action Request System 7.1.00: C API Quick Reference BMC Remedy Action Request System 7.1.00: Administering BMC Remedy Email Engine BMC Remedy Action Request System 7.1.00: Error Messages BMC Remedy Action Request System 7.1.00: Master Index BMC Remedy Action Request System 7.1.00: Release Notes
Administrators PDF and and Programmers Print Administrators PDF and and Programmers Print PDF and Print
Procedures for installing, configuring, and Administrators using the BMC Remedy Email Engine. List and expanded descriptions of AR System error messages. Combined index of all books.
Administrators PDF and and Programmers Print Everyone PDF and Print PDF and Print
Information about new features list, Everyone compatibility lists, international issues, and open and fixed issues.
Unless otherwise noted, all online documentation is available in Adobe Acrobat (PDF) format on the BMC Remedy Electronic Software Distribution and on the BMC Remedy Customer Support website.
Preface
13
14
Chapter
Understanding Integration Engine

The Integration Engine application allows you to transfer data between an external data store and AR System forms or BMC Atrium CMDB classes. You can use the included adapters for Microsoft SQL Server, Oracle, IBM DB2 UDB, XML, and flat files such as comma-separated value (CSV) files. You can also use the Integration Engine Adapter Development Kit to build your own adapters to meet your organizations specific needs. The following topics are provided: Overview (page 16) Integration Engine components (page 17) The data transfer process (page 19) Performance considerations (page 22) Getting started (page 22)
Chapter 1
15
Overview
With Integration Engine, you can do scheduled bulk data transfers and eventbased integrations initiated by either side. You can also use Integration Engine for initial data load, incremental data transfers, and data synchronization. You can build links between BMC Remedy IT Service Management applications and Enterprise Resource Planning (ERP), Customer Relationship Management, Supply Chain Management, and other enterprise applications. For example, you can use Integration Engine to: Synchronize data from your Human Resources applications with employee data in your BMC Remedy Service Desk application. Synchronize asset data tracked in BMC Remedy Asset Management applications with corporate asset data stored in ERP applications. Synchronize IT data from a discovery application with BMC Atrium CMDB, where it can be reconciled with data from other sources to your production dataset. Figure 1-1 shows how you can transfer data in either direction: from an external data store to an AR System application or BMC Atrium CMDB class, or from an AR System application or BMC Atrium CMDB class to an external data store.
Figure 1-1: Overview of the data transfer process
AR System database External data store
Data object
BMC Atrium Integration Engine
AR System form
CMDB class
During the data transfer, Integration Engine identifies the records to be transferred and performs some or all of the following tasks, depending upon how you have configured your data exchange: Reads records Creates new records Updates records Deletes records
16
Integration Engine components
Integration Engine components

Integration Engine has four main components: Data Exchange application (page 18) Integration Engine service (page 18) Event Request interface (page 19) Adapter Development Kit interface (page 19) Figure 1-2 shows how these components work with other Integration Engine components and related objects.
Figure 1-2: Integration Engine components
AR System database or BMC Atrium CMDB
Data Exchange application Application Pending form

AR System APIs CMDB APIs
BMC Atrium Integration Engine
Integration Engine service
Event Request interface (eiexfer)
Adapter Development Kit interface
DB2 adapter
Oracle adapter
SQL adapter
XML adapter
Flat File adapter
?
DB2 database Oracle SQL Server database database XML file Flat file
Other Other Other data store data store data store
Out-of-box adapters
Custom adapters (not included)
Chapter 1
17
Data Exchange application

The Data Exchange application is a group of AR System forms that is available from your AR System home page as the AIE Console link, and you use it to work with these integration objects: A data exchange is the object that you execute to move data with Integration Engine, and a single execution of a data exchange is called a data transfer. A data exchange specifies whether the external data store is the source or the target for a data transfer, which adapter is used, how to connect to the external data store, and the method used to execute the exchange. A data exchange also specifies the conditions under which data is created, updated, and deleted. You associate a data exchange with one or more data mappings to specify which data is transferred. A data mapping defines data to be transferred. It specifies the external file or database table and the AR System form or BMC Atrium CMDB class between which data is transferred, and defines the primary key that identifies a row of data on either side. A data mapping specifies the fields or attributes to be transferred from the source and maps them to fields or attributes in the target, and specifies any fields or attributes in the source that should be updated when a record in the target is created, updated, or deleted. A data mapping can limit the rows of data to be transferred from the source, updated in the target, and updated in the source by including queries for each of these things. You use a data mapping by associating it with a data exchange. The Data Exchange application also lets you perform the following configuration tasks: Define external data store connection parameters for multiple data exchanges simultaneously. Populate Integration Engine menus with the names of tables and columns from external data stores to simplify the process of creating data mappings. Specify the administrator user and online help path for the application. View the Integration Engine instances you defined at installation time and edit some settings for them. Display version numbers for Integration Engine and related products.
Integration Engine service

The Integration Engine service obtains the defined data exchange from the Data Exchange application and completes the transfer of data by communicating with the adapter specified in the data exchange definition. Adapters are software, either provided by BMC or custom built, that provides access to external data and responds to calls from Integration Engine during a data exchange.
18
The data transfer process
The Integration Engine service can connect to any Windows or UNIX AR System server. It does not need to reside on the same computer as the AR System server or the external data stores, but can be on any computer that is network-connected to both of these. The Integration Engine service runs as a client to the AR System server using the AR System application programming interface (API). For information about the AR System API, see BMC Remedy Action Request System 7.1.00: C API Reference.
Event Request interface

You can execute a data exchange on an event-driven basis using the Event Request interface. Each event-driven request is created as an entry in the Application Pending form on the AR Server where the Data Exchange application is installed. You create an event-driven request by directly creating an Application Pending entry, by using AR System workflow to create the entry, or by invoking the eiexfer utility. The Integration Engine service processes requests at a scheduled interval configured in the eie.cfg file, regardless of which method was used to create the requests. Optionally, the Integration Engine service can handle individual event requests immediately if you enter them through the eiexfer utility.
Adapter Development Kit interface

Integration Engine also has a special interface that allows it to interact with adapters. The Adapter Development Kit interface is an interface built into Integration Engine that allows Integration Engine to communicate with non-BMC adapters. The Adapter Development Kit interface defines a set of C++ objects that are used by the Integration Engine service to manage data exchanges that use these adapters.

When you start Integration Engine, it locates data exchanges by reading entries in the Data Exchange application. When Integration Engine detects a data exchange, the Integration Engine service loads the adapter that is associated with that data exchange. The adapter needs to be licensed before you can run it. You can design the adapter to obtain a license that is specifically issued to it or get a license from a pool of available adapter licenses issued to Integration Engine. If the license comes from a pool of Integration Engine licenses, you can implement further license checking in the adapter to prevent unauthorized use of the adapter. If the adapter is not licensed, a log message is written to the EIE:Log form and the Integration Engine log file indicating that the adapter is not licensed. After the appropriate adapter is located and its license is verified, the adapter is loaded.
Chapter 1
19
After this point, there are two phases to a data transfer: the initialization phase where a data exchange is prepared to run, followed by the processing phase where data is transferred.
The initialization phase

The initialization phase prepares a data exchange to run. Data is not actually exchanged until the processing phase, which is described in the next section. In the initialization phase, the Integration Engine service:
a Loads data exchange rules.
The Integration Engine service loads all the rules defined in the Data Exchange application and prepares the C++ objects defined by the Adapter Developer Kit interface. The C++ objects contain the data exchange definition, the data mapping rules, and all adapter-defined configuration parameters and rules.
b Connects to data stores to validate rules.
The Integration Engine service connects to both the source and target data stores. An AR System form or BMC Atrium CMDB class can serve as either the source or the target. The Integration Engine service does not transfer data at this point, but a connection to both data stores is necessary to validate rules.
c Validates data exchange rules.
The Integration Engine service validates rules owned by Integration Engine. During validation, the Integration Engine service indicates if any errors or warnings were detected and if the rules are ready to be used in a data exchange. At the same time, the adapter is called to validate adapter-owned rules. During validation, the adapter indicates if any errors or warnings were detected and if the rules are ready to be used in a data exchange.
d Disconnects from data sources.
After the rules are validated, the Integration Engine service disconnects from both data sources.
e Starts a thread.
At the end of the initialization phase, the Integration Engine service starts a thread to manage the data exchange process.
20
The processing phase

In the processing phase, the transfer of data takes place. This phase begins when the data exchange is executed, which can be scheduled or event driven. During the processing phase, the Integration Engine service: Refreshes the data exchange. Before data is exchanged, the Integration Engine service checks the Data Exchange application to determine if any changes were made to the data exchange definition. If changes were made, the Integration Engine service updates the loaded data exchange with the new definition. Starts a separate thread for each data exchange. Each data exchange connects to data stores. The Integration Engine service connects to both the source and target data stores. The Integration Engine service communicates through the AR System API or BMC Atrium CMDB API to pull data out of and push data into those data stores, and through the Adapter Developer Kit interface to pull data out of and push data into the external data store. Locates data to be exchanged. The Integration Engine service obtains a list of keys from AR System or BMC Atrium CMDB and asks the adapter to create a list of keys. The Integration Engine service converts the keys to a common data type (if necessary) and then sorts the keys to make sure that they are in the same order so the key lists can be compared. Transfers data. The Integration Engine service compares the keys and determines from the data exchange definition how new and existing records should be treated. The Integration Engine service decides on a key-by-key basis whether to create, update, or delete records. For each key, adapters can be called to read, write, update, or delete a record. Disconnects from data stores. After all keys are processed, the data transfer is considered complete. The Integration Engine service closes the connection to AR System or BMC Atrium CMDB and asks the adapter to close the connection to the external data store.
NOTE
The thread remains active, as does the adapter, unless the data exchange is deactivated in the Data Exchange application or the Integration Engine service is asked to terminate. In either of those events, the adapter .dll is released and the thread terminates.
Chapter 1
21
Performance considerations
Performance considerations for Integration Engine are difficult to quantify because performance is affected by your network, AR System, the AR System server database, and the external data store load. It is difficult to predict the effect of a specific change on Integration Engine performance, but configuration considerations can influence it. While it is easy to add field mappings or extra rules for each field, remember that each item you add is compared against every record in your database. Seemingly minor additions could have major effects if many records are in your database. For example, if you have 1200 records in your database and the change you make adds an additional half-second to the run time for each record, the data transfer might take an additional 10 minutes to run.
Getting started
If you are new to BMC Atrium Integration Engine, you might be wondering where to start to get your first successful data transfer underway. After installing, here are the high-level steps you need to take. See the recommended area of the Integration Engine documentation for specific instructions on each.
To get started using Integration Engine

Step 1 Populate the database field menus for your external data stores using the rule
helpers in the Database Field Menus Console.
This greatly simplifies the process of creating data mappings by allowing you to choose field names from a menu instead of manually typing them. For instructions, see the section Using the adapter rule helper utilities in the Administrators Guide.
Step 2 Create a data mapping to specify which data should be transferred and where it
should go.
For instructions, see the appropriate chapter of the Users Guide: Chapter 3, Creating a data mapping for BMC Atrium CMDB CI classes, Chapter 4, Creating a data mapping for BMC Atrium CMDB relationship classes, or Chapter 5, Creating a data mapping for AR System forms.
Step 3 Create a data exchange to control the execution, direction, and other characteristics
of your data transfers.
For instructions, see Chapter 2, Creating a data exchange, in the Users Guide. These three steps are sufficient to enable a simple data transfer. If you have a more complex situation, you might need to perform more configuration than this.
22
Getting started
Chapter 1
23
24
Chapter
Installing Integration Engine
This section describes how to install Integration Engine. The following topics are provided: Installation overview (page 26) Getting the prerequisites (page 27) Gathering information (page 29) Installing or upgrading Integration Engine (page 31) Post-installation configuration tasks (page 42) Uninstalling Integration Engine (page 43)
Chapter 2
25
Installation overview
When you run the Integration Engine installer, you install: Integration Engine This includes the Integration Engine service, the Data Exchange application, the Event Request interface, and optionally the Integration Engine development kit (also called the Integration Engine Adapter Developers Kit (ADK)). Adapters This can include the DB2 Adapter, File Adapter, Oracle Adapter, SQL Server Adapter, and XML Adapter.
NOTE
All products can now be downloaded from the Electronic Product Distribution (EPD) page at http://webapps.bmc.com/epd or from the product DVD. The product documentation is no longer installed as a part of the Integration Engine installation. Click the product documentation link and unzip the files. The unzip process creates two folders: Docs and Help. After you unzip the documentation files, you can manually copy the documentation files to your local file system. This documentation includes all Integration Engine manuals and the Release Notes in PDF format.
IMPORTANT
The Integration Engine installer installs the Integration Engine components on the machine on which you run the installer. However, if you enter a remote AR System server during installation, the Data Exchange application is installed on the remote AR System server. After the Integration Engine components and adapter products are installed, you can move the Event Request interface as needed on your network. For more information, see Post-installation configuration tasks on page 42.
:
26
Getting the prerequisites
Figure 2-1 shows a sample installation of the Integration Engine components on a network.
Figure 2-1: Sample installation of Integration Engine integration components
AR System and BMC Atrium CMDB Atrium Integration Engine DB2 Adapter
DB2
Database
File Adapter
XML Adapter
Oracle Adapter
Oracle
File Source
XML Source
SQL Adapter
SQL
Event Request Interface
Set 1
Set 2
Set 3
In this example, the Integration Engine and the adapters are installed on one machine (see Set 2). The AR System and the CMDB server are network-connected to the Integration Engine machine (see Set 1). The third-party database (DB2, Oracle, or SQL) and the Event Request interface are installed on another networkconnected machine (see Set 3). Sets 1, 2, and 3 can each reside on the same host or on three different hosts.
Getting the prerequisites

Before you begin installation, make sure you have the following Windows or UNIX requirements. For the latest compatibility information, see the Product Availability and Compatibility section of the BMC support website:
http://www.bmc.com/info_center_support/overview 0,3252,19097_63537447,00.html
Chapter 2
27
Windows prerequisites
Review the prerequisites in Table 2-1 for Windows.
Table 2-1: Windows prerequisites Integration Engine component All components Data Exchange application Requirements Windows administrator privileges Valid AR System server user ID and password.
Note: The user must have AR System administrator
Check
privileges.
You must install the Data Exchange application on a server running AR System: 7.0, 7.0.01, or 7.1.00 On a supported platform
Note: The Integration Engine installer can install the Data
Exchange application on a remote machine.
To exchange data with CMDB, you must have CMDB v2.0.1 or v2.1.00 installed.
UNIX prerequisites
Review the prerequisites in Table 2-2 for UNIX.
Table 2-2: UNIX prerequisites Integration Engine component All components Requirements UNIX administrator privileges (root)
Note: Installation is possible by a non-root user, but
Check
you still need root privileges available for some activities.
Data Exchange application You must install the Data Exchange application on a server running AR System: 7.0, 7.0.01, or 7.1.00 On a supported platform
Note: The Integration Engine installer can install the
Data Exchange application on a remote machine.
To exchange data with CMDB, you must have CMDB v2.0.1 or v2.1.00 installed.
28
Gathering information
Database adapter prerequisites

Review the prerequisites in Table 2-3 for database adapters.
Table 2-3: Database adapter prerequisites Integration Engine component DB2 adapter Requirements Check
DB2 8.2 client software installed on the computer where the DB2 adapter is installed. The client must be configured to point to your DB2 database.
Oracle 9i (Release 2) or Oracle 10g (Release 2) client software installed on the computer where the Oracle adapter is installed. The client must be configured to point to your Oracle database. SQL Server 2000 or 2005 (Standard or Enterprise) client software installed on the computer where the SQL Server Adapter is installed. The client must be configured to point to your SQL Server database.
Oracle adapter
SQL Server adapter
Gathering information
The worksheet in Table 2-4 includes a list of selections for which you are prompted during installation. It is organized by dialog boxes, which are placed in the order in which they are displayed during the installation. Complete the worksheet before starting the installation.
Table 2-4: Integration Engine installer worksheet Entry or selection AR server name Description Enter your information
Action Request System server information window Name of your AR System server.
AR server port Number of the port you want to number use. To locate the port number on UNIX, go to <ar_install_dir>/ conf/ar.conf and find the key name TCD-Specific Port. To find the port number on Windows, go to
<ar_install_dir>\CONF\ar.cfg
and find TCD-Specific-Port. If your AR System server uses portmapper, use the default value. AR server Administrator User name of the AR System administrator.
Chapter 2
29
Entry or selection AR server admin password
Description The password for the AR System administrator. The default password for administrator Demo is an empty string.
Enter your information
DB2 Database Information window

Note: This window and corresponding fields only appear if you select the Custom mode
of installation and the DB2 adapter from the custom installation window. DB2 database user name. DB2 database password. DB2 instance.
Database Alias DB2 database alias name. Username Password DB2 Instance
SQL Server Database Information window

Note: This window and corresponding fields only appear if you selected the Custom mode
of installation and SQL adapter from the custom installation window. SQL server computer name. SQL database name. Option to select whether you want to connect using Windows authentication or SQL Server Authentication using a Username and Password. SQL server user name. SQL server password.
SQL Server Name Database Name Connect using
Username Password
Oracle Database Information window

Note: This window and corresponding fields only appear if you selected the Custom mode
of installation and Oracle adapter from the custom installation window. Directory where you want the Oracle database to be installed. Database system identifier (SID). Oracle database user name. Oracle database password. The folder where the product is installed. The default folders are: Windows: C:\Program Files\BMC Software\BMC Atrium Integration Engine\<server name>-<port number> UNIX: /usr/bmc/apps/aie/ <server name>-<port number>/
Oracle Home Directory Database SID Username Password Destination folder
Database Alias Databse alias.
Choose Destination Location window
30
Installing or upgrading Integration Engine

This section contains instructions for installing or upgrading Integration Engine on Windows and UNIX. It also contains instructions for installing the Integration Engine Online Help.
Installing or upgrading Integration Engine on Windows

You can install BMC Atrium Integration Engine or upgrade to BMC Atrium Integration Engine from BMC Remedy Enterprise Integration Engine.
To install or upgrade Integration Engine on Windows

1 From the folder where you unzipped the product download or from the root folder
of the product DVD, double-click aieinstall_windows.exe.
The Welcome window appears.

2 Click Next.
The License Agreement window appears.

3 Select I accept the terms of the license agreement, and then click Next.
The Action Request System server information window appears.

Figure 2-2: Action Request System server information window
NOTE
The Data Exchange application is installed on the machine on which the AR System server runs. This can be a different machine from the Integration Engine service. For details, see Getting the prerequisites on page 27.
Chapter 2
31
BMC Atrium Integration Engine 7.1.00 4 Do the following actions:
Accept the default value in the ARServer Name field, or type the name of your AR System server. Accept the default value in the ARServer Port Number field, or type the number of the port you want to use. Accept the default value in the ARServer Administrator field, or type the name of an AR System administrator user. Type the users password in the ARServer Admin Password field.
5 Click Next.
NOTE
If you are upgrading to BMC Atrium Integration Engine from BMC Remedy Enterprise Integration Engine, a confirmation dialog box appears asking you if you are sure you want to upgrade. Click Yes. The Setup Type window appears.
6 Do one of the following actions: Select Express To Install BMC Atrium Integration Engine with all adapters and the Adapter Development Kit. Only one instance of the Integration Engine service is installed. Choose which components to install and how many instances of the Integration Engine service to install. Then The Choose Destination Location window appears. Click Next, and skip to step 19 on page 35. The Select Components window appears. Click Next, and continue with step 7.
Custom
7 Select the components you want to install. The following components are available
for installation:
Adapter Development Kit DB2 Adapter File Adapter Microsoft SQL Server Adapter Oracle Adapter XML Adapter
IMPORTANT
If you are upgrading existing ADK, Integration Engine, Remedy Link For Oracle, or Remedy Link For SQL installations, the ADK, File Adapter, Oracle adapter, and SQL adapters will be selected for installation by default. These cannot be deselected.
32
If you selected the DB2 Adapter component to install, the DB2 Database Information window appears.
Figure 2-3: DB2 Database Information window
8 Enter your DB2 database alias, database instance, username, and password in the
appropriate fields, and click Next.
If you selected the SQL Server Adapter component to install, the Microsoft SQL Server Database Information window appears.
Figure 2-4: Microsoft SQL Server Database Information window
9 Enter your SQL Server computer name in the SQL Server Name field and your
database name in the Database Name field.
10 Select whether to connect to the database using Windows Authentication or SQL
Server Authentication.
11 If you selected SQL Server Authentication, enter a valid SQL Server user name and
password in the Username and Password fields.
Chapter 2
33
BMC Atrium Integration Engine 7.1.00 12 Click Next.
If you selected the Oracle Adapter component to install, the Oracle Database Information window appears.
Figure 2-5: Oracle Database Information window
13 In the Oracle Home Directory field, enter the directory where Oracle database is
installed.
14 Enter the database SID and alias. 15 Enter a valid Oracle user name and password in the Username and Password
fields.
16 Click Next.
The Instance Information window appears.

Figure 2-6: Instance Information window
34
Installing or upgrading Integration Engine 17 In the Number of Instances field, type the number of instances of the Integration
Engine service you want to install.
NOTE
If you are upgrading your existing installation, you can continue the installation without adding any instances by typing 0 in the Number Of Instances field.
18 In the Instance Startup Mode field, select whether you want all instances to start
automatically or you want them all to start manually, and then click Next. The Choose Destination Location window appears.
19 Accept the default installation location, or click Browse to select another location. 20 In the Space Required and Space Available fields, verify that you have enough free
space on the drive which you choose for installation, and then click Next. The Start Copying Files window appears.
21 Click Next.
The Integration Engine installation process begins. The installer copies files and loads workflow, which can take several minutes to complete. Once the installation is complete, a message appears telling you that installation of BMC Atrium Integration Engine is now complete.
22 To view the installation log, select the View log file checkbox and then click Finish
to complete your installation.
Installing or upgrading Integration Engine on UNIX

To install or upgrade Integration Engine on UNIX
1 From the folder where you unzipped the product download or from the root folder
of the product DVD, locate and extract aieinstall_<platform>.tar.gz.
IMPORTANT
If you are performing the installation with a non-root user ID, you must extract the installer, .tar.gz, by that user ID only.
2 Type the following command:
./aie_install.sh
3 Press Enter.
A message appears asking if you wish to install BMC Atrium Integration Engine.
4 Type Y, and press Enter.
A message appears telling you that a record of the installation will be preserved in the following directory: /usr/tmp/aie_install.log.
Chapter 2
35
BMC Atrium Integration Engine 7.1.00 5 Read the End User License and Maintenance Agreement, and press Enter to accept
the agreement.
TIP
Press Enter to scroll through the entire agreement. At any time while reading the agreement, you can press q to accept, reject, or re-read the agreement. At the end of the agreement, the following message appears:
Please select one of the following, 1) Yes, I agree to the terms of this agreement. 2) No, I disagree to the terms of the agreement. 3) I would like to read the agreement again.
6 At the prompt, type 1 to accept the agreement, and press Enter.
A message appears informing you the AR System server was found.

7 At the server name prompt, press Enter to accept the default server, or type the
name of your AR System server, and press Enter. A confirmation message apppears:
You have chosen AR System server <servername> Is this correct? [y]
8 Press Enter to accept the default.
A message appears asking you to specify the directory where the Action Request System is currently installed.
9 At the installation directory prompt, press Enter to accept the default directory
path, or type the name of the new directory path, and press Enter. the correct port number, and press Enter.
10 At the TCP/IP port prompt, press Enter to accept the default port number, or type
A message appears notifying you that to load an application into the AR System, you must have a valid AR System Administrator ID and password.
11 At the AR System Administrator ID prompt, press Enter to accept the default ID,
or type the ID, and press Enter.
12 At the password for the AR System Administrator prompt, press Enter to accept
the default, or type a password, and press Enter.
The default administrator login for a new installation is the Demo user name and no password.
13 Press Enter.
NOTE
If you are upgrading to BMC Atrium Integration Engine from BMC Remedy Enterprise Integration Engine, a confirmation message appears asking you to upgrade the existing installation. Press Enter to accept the default (Y).
36
Installing or upgrading Integration Engine 14 The following message appears allowing you to run the installation in two modes:
Installation can be run in the following two modes: 1) Express: All the components (ADK, DB2 adapter, File adapter, Oracle adapter, XML adapter) will be installed iwth default settings. 2) Custom: Select the components that you want to install. Recommended for advanced users.
At the prompt, do one of the following actions:

Select Express (Press Enter to accept this default). To Install BMC Atrium Integration Engine with all adapters and the Adapter Development Kit. Only one instance of the Integration Engine service is installed. Choose which components to install and how many instances of the Integration Engine service to install. Then Skip to step 20 on page 39.
Custom (Type 2, and press Enter).
Continue with step 15 on page 37.
If you choose a custom installation, the following components are available for installation: Adapter Development Kit DB2 Adapter File Adapter Oracle Adapter XML Adapter If you are upgrading an existing installation of ADK, Integration Engine, or Remedy Link For Oracle, these components will not be available for component selection. They will be upgraded by default.
15 After each of the following prompts, press Enter to accept the default (Y) and
NOTE
install that component, or type N, and press Enter to skip installation of that component and move to the next option. The following prompts appear in this order:
Do you want to install Adapter Development Kit? [y] Do you want to install DB2 Adapter? [y] Do you want to install File Adapter? [y] Do you want to install Oracle Adapter? [y] Do you want to install XML Adapter? [y]
After selecting the components you want to install, a prompt appears asking you to add more instances.
Chapter 2
37
BMC Atrium Integration Engine 7.1.00 16 Press Enter to accept the default [n], or type Y to add more instances, and press
Enter.
If you type Y, then a message appears asking you to please enter the number of instances you want to add.
17 Type the number of instances you want to add, and press Enter.
IMPORTANT
Steps 18 and 19 will only appear, depending on which components you chose to install. After you complete these steps, skip to step 20 on page 39.
NOTE
If you are installing Integration Engine which points to the AR server that already has Integration Engine forms (possibly imported by another installation from another Integration Engine host), in steps 18 and 19, the installer shows the default values in square brackets. For example, [system] for Oracle User, which is actually read from the existing forms. You can either enter new values, or you can accept the defaults.
18 If you selected the DB2 Adapter component to install, a prompt appears, asking
you for a valid DB2 login name. Complete the following actions: press Enter.
a At the DB2 instance name prompt, type the DB2 database instance name, and b Type the DB2 login name, and press Enter.
A confirmation prompt appears, asking you if this is correct.

c Press Enter. d At the password prompt, type the DB2 login password, and press Enter. e At the verification prompt, retype the DB2 login password, and press Enter. f At the DB2 alias prompt, type the DB2 database alias name, and press Enter. g At the DB2 installation path prompt, type the installation path where the DB2 is
installed, and press Enter.
19 If you selected the Oracle Adapter component to install, a prompt appears, asking
you for a valid Oracle login name. Complete the following actions: Enter.
a At the Oracle database System ID prompt, type the Oracle system ID, and press b Type the Oracle login name, and press Enter.
A confirmation prompt appears, asking you if this is correct.

c Press Enter. d Af the verification prompt, retype the Oracle login password, and press Enter.
38
Installing or upgrading Integration Engine e At the Oracle database alias prompt, type the Oracle database alias name, and
press Enter.
f At the Oracle installation path prompt, type the installation path where the
Oracle client is installed, and press Enter.
20 After you complete the steps for the components you want to install, a prompt
appears asking you for the directory to install BMC Atrium Integration Engine. Press Enter to accept the default directory, or type the directory, and press Enter. The installer copies files and loads workflow, which can take several minutes to complete. Once the installation is complete, a message appears telling you that installation of BMC Atrium Integration Engine is now complete. The message also refers you to the installation and workflow import logs.
Installing Integration Engine Online Help

The Help system for Integration Engine is installed separately from the application itself. You must perform the procedure in this section to install the Online Help. Help is installed on a web server and launched with URLs sent from Integration Engine. It does not require the BMC Remedy Mid Tier. This web server does not have to be installed on the same machine as Integration Engine. If you want Help to reside on a different machine, run the Help installer on the web server where Help is to be installed. You can install Online Help on the machine where you have Mid Tier and use its web server.
NOTE
IMPORTANT
You can install Help files on either Windows or UNIX systems. To install Help files on multiple systems, run the installer locally on each individual system.
To install Help for the Integration Engine on Windows

1 Make sure that:
Integration Engine is installed The AR System server where the Integration Engine is installed is running The web server for Help is running
2 Navigate to the AIEHelp folder of your installation DVD or download, then double-
click setup.exe.
The Welcome window appears.
Chapter 2
39
BMC Atrium Integration Engine 7.1.00 3 Click Next, and then click I Agree to accept the license agreement on the next
window.
The Enter Required Information For Atrium Integration Engine Online Help window appears.
Figure 2-7: Enter Required Information For Atrium Integration Engine Online Help window
4 Enter the login and server information for the AR System server from which you
want to install Help.
You need the user name and password for an AR System administrator and the name of an AR System server. If you access the server on a particular port, enter that number in the Port Number field.
40
The Atrium Integration Engine Online Help window appears.

Figure 2-8: Atrium Integration Engine Online Help window
5 Enter the host name and port number of the web server to deliver the requested
Help files to users, and then click Next.
The Choose Destination Location window appears.

Figure 2-9: Choose Destination Location window
Chapter 2
41
BMC Atrium Integration Engine 7.1.00 6 Accept the default installation folder or browse and choose another folder, then
click Next.
The Start Copying Files window appears.

7 Review your settings, and click Next if they are correct. Otherwise, click Back and
modify them.
The installer copies necessary files to the installation folder, and then the InstallShield Wizard Complete window appears.
8 Select View installation log file if you want to examine the log after installation,
and then click Finish to exit.
Post-installation configuration tasks

After installing Integration Engine and the optional components, you should complete the following post-installation configuration tasks: Configure the Data Exchange application by creating data exchanges and data mappings to transfer your data. For more information, see the BMC Atrium Integration Engine 7.1.00 Users Guide. Configure the Event Request interface if you want to use it on a remote machine.
To configure the Event Request interface on a remote machine

Copy the platform-appropriate eiexfer to any remote application host that uses the Event Request interface. These files are listed in Table 2-5.
Table 2-5: Platform directory files for Event Request Platform Windows Directory
<aie_install_dir>/service/bin/eiexfer.exe <aie_install_dir>/service/bin/arapi70.dll <aie_install_dir>/service/bin/arrpc70.dll <aie_install_dir>/service/bin/arutl70.dll <aie_install_dir>/service/bin/icudt32.dll <aie_install_dir>/service/bin/icuin32.dll <aie_install_dir>/service/bin/icuuc32.dll <aie_install_dir>/service/bin/eiexfer <aie_install_dir>/service/bin/libicudatabmc.so.32 <aie_install_dir>/service/bin/libicui18nbmc.so.32 <aie_install_dir>/service/bin/libicuucbmc.so.32
UNIX
42
Uninstalling Integration Engine
Uninstalling Integration Engine

You might want to remove Integration Engine to reinstall it or to move it to another machine.
WARNING
By uninstalling Integration Engine, you might lose all data that is part of the Data Exchange application. Make sure that you back up any forms and data you might need.
Removing Integration Engine from Windows

To remove Integration Engine from Windows
1 Choose Start > Settings > Control Panel on the Windows desktop. 2 In the Control Panel dialog box, double-click Add/Remove Programs. 3 In the Add/Remove Programs dialog box, select BMC Atrium Integration Engine
[<server name>(<port number>)].
4 Click Remove.
A confirmation dialog box appears.

5 Click Yes.
IMPORTANT
If you have two instances of Integration Engine that use the same AR System server, you will receive a message stating "any other AIE installation using may become invalid.
<ARServerName> as ARS Server may become invalid if you uninstall the Data Exchange Application." If you continue with the uninstallation any other instances
Chapter 2
43
The Action Request System server information window appears.

Figure 2-10: Action Request System server information window
6 Accept the default value in the ARServer Administrator field, or type the name of
the AR System server administrator.
7 In the ARServer Admin Password field, type the AR administration password. 8 Click Next.
A dialog box appears asking if you want to uninstall the Data Exchange application.
9 Click Yes.
The uninstall process begins. When the uninstall process is complete, the Uninstallation completed window appears.
10 Click Finish.
Removing Integration Engine from UNIX

To remove Integration Engine from UNIX
1 Start BMC Remedy Administrator. 2 Delete all forms with the prefix EIE. 3 Delete all menus with the prefix EIE. 4 Delete all the files and folders in the Integration Engine installation directory. 5 Remove the eie.reg registry file in /etc/eie.reg.
44
Chapter
In Integration Engine, you use rules to map AR System fields or BMC Atrium CMDB classes to an external data store. You use queries to limit the data exchange to data that meets certain criteria. You can also make defining a data mapping more convenient by adding external data store field names and rules to drop-down lists in the data mapping windows. The following topics are provided: Defining rules (page 46) Defining queries (page 55) Using the adapter rule helper utilities (page 59) Populating the rule control (page 70)
Chapter 3
45
Defining rules
This section outlines the rule syntax used to define how AR System fields and BMC Atrium CMDB classes are mapped to the external data store. A rule syntax can be a data constant, a simple mapping of external data store and AR System fields or BMC Atrium CMDB classes, or a complex set of functions used to compute the value for a rule. Table 3-1 describes the use of each kind of rule syntax. Each is described in detail in the sections that follow, with examples and descriptions of the results.
Table 3-1: Rule syntax for AR System forms and BMC Atrium CMDB classes Rule Syntax
constant| <{rule}> <{rule}> <{rule}> function| sql| targetsql| process| targetprocess| stmt| function|calc_tokenid
Description Interprets the value that follows the pipe as a constant. Each set of curly brackets ({}) encloses a field mapping rule that is evaluated independently. The first rule to return a response value is considered the value to be returned. Performs the function that follows the pipe. Runs an SQL command to obtain a value. Runs an SQL command on the target to obtain a value. Runs a process to obtain a single character value in response. Runs a process on the target to obtain a value. Defines an if/then/else statement to obtain a value. Calculates a unique alphanumeric value for all the fields mentioned within the function.
Note: This function works similarly to generating a Unique
GUID for multiple fields.
xxxxxx
Any other value is dependent on whether the rule is defined for the AR System, the BMC Atrium CMDB, or for the external data store. For the AR System, this is considered a field definition and is the name of a field on an AR System form. For the BMC Atrium CMDB, this is considered an attribute definition and is the name of an attribute in a BMC Atrium CMDB class. For an external data store rule, see the external data store documentation for an explanation of the external data stores rule syntax.
46
Defining rules
Constant syntax (constant|<string>)

This syntax allows you to generate a value to be placed into a field or class. Integration Engine does not perform a database lookup in this case; instead, the specified value is used. This syntax is useful if you populate some fields with known values when you create a request. Integration Engine attempts to assign a data type to the constant. To force the value to be a string, put quotes around the value. If not, Integration Engine tries to determine if the value is a date or a number before it defaults to a character value. Table 3-2 provides examples of how to use the constant syntax.
Table 3-2: Constant syntax examples Example
constant|Hardware constant|15 constant|15
Results Returns the character string Hardware. Returns the number 15. Returns the character string 15.
Precedence syntax (<{rule}> <{rule}> <{rule}>)

This syntax allows you to set the precedence for a set of rules. Each set of curly brackets ({}) encloses a field mapping rule that Integration Engine evaluates independently. The first rule to return a response value is considered the value to be returned. Table 3-3 provides examples of how to use the precedence syntax.
Table 3-3: Precedence syntax example Example
{PO Number} {Notification Number} {constant|Unknown Value}
Results The PO Number is returned if not null. If the PO Number is not found, the Notification Number is returned if not null. If the Notification Number is not found, the Unknown Value string is placed in the field.
Chapter 3
47
Function syntax (function|<function(parameters)>)

Each function defines an operation that Integration Engine performs to obtain a value. The parameters can be any of these: Constants Field names These must be delimited by dollar signs ($), for example:
concat ($<fieldname>$, $<fieldname>$)
Other function formats Any parameter not recognized as a field name or a function is treated as a constant. Characters must be in quotation marks (" "), but numbers are entered without quotation marks. Integration Engine converts the data obtained for each parameter to the correct data type if the data type is not already in the database in the required syntax. Table 3-4 provides examples of the supported functions.
Table 3-4: Function syntax examples Function
calc_token_id
Example
function|calc_token_id ($field1$,$field2$)
Results Calculates the token ID. Returns the value that results from appending the string:
abcdef
concat(string, function|concat("abc", string,string,...) "def")
(where string is a constant, field name, or function)

currentdate() function|currentdate()
Returns the current date as a character string:

August 3, 2007
currenttime()
function|currenttime()
Returns the current time as a character string:

12:15:00
date(timestamp)
function|date
(where timestamp is a ($createdate$) constant, field name, (if $createdate$ is set to Friday, August 3, 2007 or function) 12:15:00 a.m.)
day(timestamp) function|day
Returns the date portion of the time stamp data from the field as a character string:
August 3, 2007
Returns the day of the time stamp (1 to 31):

3
48
Defining rules

hour(timestamp)
Example
Results Returns the hour of the time stamp (0 to 23):

12
function|hour (where timestamp is a ($createdate$) constant, field name, (if $createdate$ is set to
or function)
Friday, August 3, 2007 12:15:00 a.m.)
left(string,long)
function|left("Dana",2) Returns the left-most bytes of a
(where string and long are constants, field names, or functions)

length(string)
character string up to the number of bytes indicated:

Da
Returns the length of a character function|length("Dana") string. Example 1: Example 2 (values in database field char1 for five 4 records): Example 2:
fantastic africa ice liver rice function|length ($char1$) 9 6 3 5 4
Example 1:
lower(string)
function|lower("EIE")

lpad(string,long, string)
Converts a character string to lowercase:

eie
function|lpad("ABC",10, Returns the value that results from "LEAD000000") padding the character string to the

ltrim(string) function|ltrim(" abc")
left with another string, to a specified length:

LEAD000ABC

max(any,any,any, ...) max($field$,$field 2$, ...) function|max(15, 3, 7)
Strips any leading blanks from a character string:

abc
Returns the maximum value from a set of values (all must be the same data type):
15
(where any is a constant, field name, or function)
All data types are supported. These can be field references or constants. Any non-null value (positive or negative) is greater than null.
Chapter 3
49

min(any,any,any, ...)
Example
function|min ("a", "b", "c")
Results Returns the minimum value from a set of values (all must be the same data type):
a
(where any is a constant, field name, or function)
All data types are supported. These can be field references or constants. Any non-null value (positive or negative) is greater than null. Returns the minute of the time stamp (0 to 59):
15
minute(timestamp)
function|minute (where timestamp is a ($createdate$) constant, field name, (if $createdate$ is set to
or function)
Friday, August 3, 2007 12:15:00 a.m.)
month(timestamp)
function|month
null() function|null()
Returns the month of the time stamp (1 to 12):

1
Returns a null value. This is mostly used in queries to see if a value is null. Integration Engine does not set an AR System value or a BMC Atrium CMDB attribute to null:
null value
constant, field name, or function)
replace(string, function|replace string,string,...) ("abcdefghi", "def", "xxx") (where string is a
Replaces all instances of a value in a character string with a new value:

abcxxxghi
You can use field references or constants. Returns the right-most bytes of a character string up to the indicated number of bytes:
ie function|round(5.1)
long are constants, field names, or functions) round(real)
right(string,long) function|right ("Allie",2) (where string and
(where real is a constant, field name, or function)

rpad(string,long, string)
Returns the rounded value of a real number (5.1 to 5.4 are rounded to 5; 5.5 to 5.9 are rounded to 6):
5
function|rpad("ABC",10, Returns the value that results from "000000LEAD") padding a character string to the
right with another string, to a specified length:

ABC000LEAD
50
Defining rules

rtrim(string)
Example
function|rtrim("abc ")
Results Removes any trailing blanks from a string:

abc

second(timestamp) function|second
(where timestamp is a ($createdate$) constant, field name, (if $createdate$ is set to or function) Friday, August 3, 2007 12:15:00 a.m.)
status() function|status()
Returns the second from the time stamp (0 to 59):

0
Returns an integer value to indicate the completion status for the transfer of data for an individual record:
0 indicates that the data
transferred without error. This function is only used for response mapping.
1 indicates that an error occured.
strstr(string, string)
Example 1:
function|strstr ("abcdefg", "def")
Example 2 (values in database field char1 for 5 records):

fantastic africa ice liver rice function|strstr ($char1$, ic)
Returns an integer indicating the position of a string within a string. Starting position is 0 indexed. If the string is not found, -1 is returned. Example 1:
3
Example 2:
7 3 0 -1 1
substr(string, long,[,long])
function|substr ("abcdefg", 2, 4)

timestamp() function|timestamp()
Returns the substring of characters in a string starting at a specified position up to an optional end position. Starting position is 0 indexed:
cde
Returns the current time as an AR System time stamp:

Friday, August 3, 2007 12:15:00 am
time(timestamp)
function|time
Returns the time portion of the time stamp (as a character string):
12:15:00
Chapter 3
51

trunc(real)
Example
function|trunc(5.6)
Results Truncates a real number (5.1 to 5.9 results in value 5):

5
(where real is a constant, field name, or function)

upper(string) function|upper("Alex")
Converts a string to uppercase:

ALEX

weekday(timestamp) function|weekday (where timestamp is a ($createdate$)
Returns the weekday of the time stamp (1 to 7 where 1=Sunday):

6
constant, field name, or function)
(if $createdate$ is set to Friday, August 3, 2007 12:15:00 a.m.)
year(timestamp)
function|year (where timestamp is a ($createdate$) constant, field name, (if $createdate$ is set to
Returns the year portion of the time stamp as a four-digit year:

2007
or function)
Friday, August 3, 2007 12:15:00 a.m.)
SQL command syntax (sql|<command>)

Integration Engine runs the select statement (<command>) after the pipe to obtain a value. This syntax differs from the target SQL command syntax (described in the following section) in this Integration Engine runs the select statement on the source database defined for the data exchange. You can embed field names (<$field$>) into the select statement. The value of the field is substituted prior to running the select statement. For example, in Table 3-5, the value for the Category field ($category$) is replaced in the select statement before the statement is processed. If the SQL command returns more than one field or more than one row, Integration Engine uses the first value and ignores the remaining values.
Table 3-5: SQL command syntax example Example
sql|select categoryid from categories where name = $category$
NOTE
Results Returns category IDs from the categories table where the name equals the value obtained for the $category$ field.
52
Defining rules
Target SQL command syntax (targetsql|<command>)

Integration Engine runs the select statement (<command>) after the pipe to obtain a value. This syntax differs from the SQL command syntax (described in the preceding section) in this Integration Engine runs the select statement on the target database defined for the data exchange. You can embed field names (<$field$>) into the select statement. The value of the field is substituted prior to running the select statement. The value of the field is obtained from the source database and substituted prior to invoking the select statement on the target database. For example, in Table 3-6, the value for the Location field ($location$) is obtained from the source database and replaced in the select statement before it is passed to the target database for processing.
Table 3-6: Target SQL command syntax example Example
targetsql|select locationid from location where department = $location$
Results Runs the location ID from the location table where the department equals the value of the $location$ field obtained from the source database.
Process command syntax (process|<command>)

Integration Engine runs the command that follows the pipe to obtain a value. This syntax differs from the target process command syntax in that Integration Engine runs the command on the source database defined for this data exchange. If the command has embedded $-delimited field names, the values for the fields are first obtained and substituted prior to invoking the command.
$field2$
For example, in Table 3-7, Integration Engine replaces the values for $keyName$ and with the actual data values before running the process.
Table 3-7: Process command syntax example Example

process| getlastupdate ($keyName$,$field2$)
Results Runs the command getlastupdate on the source database, passing the values for $keyName$ and $field2$ as parameters. The response from the command is used.
Chapter 3
53
Target process command syntax (targetprocess|<command>)

The command that follows the pipe is run on the target database to obtain a value. This syntax differs from the process command syntax in that Integration Engine runs the command on the target database defined for this data exchange. If the command has embedded $-delimited field names, Integration Engine obtains the value for the field from the source database and substitutes its value in the command, which the target database then runs. For example, in Table 3-8, Integration Engine replaces the values for $keyName$ and $field2$ with the actual data values in the source database before running the process on the target database.
Table 3-8: Target process command syntax example Example
targetprocess| getlastupdate ($keyName$,$field2$)
Results Runs the command getlastupdate on the target database, passing the values from the source database for $keyName$ and $field2$ as parameters. The response from the command is used.
If/then/else syntax (STMT|<statement>)

This syntax allows you to use an if/then/else statement to obtain a value. You can use STMT only with character or selection fields in the target. The syntax is as follows:
STMT|IF Condition THEN Execution [ELSE Execution] ENDIF
The following conditions apply: The line breaks following THEN and ELSE are required.
Condition is in the format $SourceField$ Operator Value. Operator must be one
of:
=SourceField
matches Value does not match Value
!=SourceField LIKEAny
part of SourceField matches Value
Execution can be either an assignment or another IF block. Assignments must be in the format VALUE = value, with string values in double quotation marks.
54
Defining queries
Table 3-9 provides examples of how to use the stmt syntax.

Table 3-9: Stmt syntax examples Example
STMT| IF $CDiOsType$ = "Windows XP Professional" THEN VALUE = "Windows XP (67)" ENDIF
Results Returns Windows XP (67).
(if $CDiOsType$ is set to Windows XP Professional)

STMT|IF $CDiOsType$ LIKE "Windows XP" THEN VALUE = "Windows XP (67)" ELSE VALUE = "Unknown" ENDIF (if $CDiOsType$ is set to Windows 2003
The string Windows XP does not appear in Windows 2003 Professional. Returns Unknown.
Professional)
STMT|IF $ChassisType$ = "12" THEN IF $ChassisSize$ = "Large" THEN VALUE="12CRPF" ENDIF ElSE VALUE="13CRPF" ENDIF
The top-level IF statement matches, but the nested one does not. Because no ELSE clause exists on the nested IF statement, no value is returned.
(if $ChassisType$ is set to 12 and $ChassisSize$ is set to Small)
Defining queries
Use the following query syntax to define queries on the Query tab of the three Mapping Information windows.
<$field$> <operator> <value>
This query syntax applies to AR System forms only. Each third-party adapter defines its own query syntax, which might not be similar to the query syntax described in this section. See the adapter documentation for the query syntax supported by your adapter.
Chapter 3
55
AR System query syntax

When you use the AR System query syntax, you can supply any number of operations. Each, however, must be concatenated with either AND or OR, depending on the condition you want. Table 3-10 describes the query syntax options.
Table 3-10: Query syntax options Option
<$field$>
Description The field name to be used in the comparison. The fields are delimited by dollar signs. For AR System queries, <$field$> names a field on an AR System form. The value used in the comparison. Use the AR System query syntax, or enter a data constant, for example, $SALARY$ > 2000. The relational operators are: Returns all the values in <$field$> when the value is greater than <value>. Returns all the values in <$field$> when the value is less than <value>. Returns all the values in <$field$> when the value is equal to <value>. Returns all the values in <$field$> when the value is not equal to <value>. Returns all the values in <$field$> when the value is greater than or equal to <value>. Returns all the values in <$field$> when the value is less than or equal to <value>. Parentheses are placed around strings. When you use multiple operators to construct query criteria, parentheses are the first operators evaluated. Logical AND of the results of two conditions. (The result is true if both conditions are true.) Logical OR of the results of two conditions. (The result is true if either condition is true.) Negates the condition that follows. (If the condition is false, the result is true.) Performs a pattern search. For example, Submitter LIKE Bob finds all requests with a submitter name that begins with the letters Bob (such as Bobby Compton). Returns all the values in <$field$> when the value is in the list of values in <value>. This differs from = in that the <value> must be a list. Returns all the values in <$field$> when the value is not in the list of values in <value>. This differs from != in that the <value> must be a list.
<value> <operator>
<
> = != <= >= ()
AND OR NOT LIKE
IN NOT IN
56
Defining queries
Function query syntax ($function|...$)

This is a special syntax that enables you to generate a value for the Value option in your query syntax rather than entering a data constant. You can use the functions listed in Table 3-11 in your query. The functions supported are listed in the dropdown list accessed by the Rules button on the Query tab of the respective Mapping Information windows for AR System forms, CI classes, and relationship classes. Three different Mapping Information windows exist for AR System forms, CI classes, and relationship classes which can be accessed using left side navigation panel provided on Integration Engine console.
Table 3-11: Function query syntax examples Syntax
currentdate() currenttime() null() timestamp() $category$ != $function|null()$
Description Supplies the current date. Supplies the current time. Identifies a null value (different from blank). Supplies the current date and time. Returns all entries in the database where the $category$ field is not a null value.
Data key syntax

You can only use the syntax described in this section in a data key query. Data key queries are defined on the Data Key Query subtab of the Query tab on the respective Mapping Information windows for AR System forms, CI classes, and relationship classes.
Field option in the query syntax ($<field>$)

This is a special syntax for data key queries. You can use any syntax in Table 3-12 for the Field option within the query syntax.
Table 3-12: Field option in the query syntax Syntax
$KEY$
Description Indicates all field names defined on the Primary Key Mapping tab of the respective Mapping Information windows for AR System forms, CI classes, and relationship classes.
$KEY$ is likely to be supported by any adapter.
$<fieldname>$
Anything other than $KEY$ is considered a field definition. For AR System, this is an AR System field name.
Chapter 3
57
Value option in the query syntax (<value>)

This is a special syntax for data key queries. You can use any syntax in Table 3-13 for the Value option within the query syntax.
Table 3-13: Value option in the query syntax Syntax
$function|$
Description Performs the function that follows the pipe to obtain a value. The value is placed in the query before it is used to limit the data used in the data exchange. Indicates that all keys from the target database are to be placed in the query before it is used to limit the data in the data exchange.
$KEYLIST$ is usually supported by any adapter.
$KEYLIST$
xxxxxxx
Any other value is treated as a constant and passed to AR System server for handling.
KEY syntax ($KEY$)

This is a special syntax for data key queries. It enables you to automatically include the correct syntax for a multiple or single column key. It is especially useful when trying to specify a query for all keys in a key list.
NOTE
$KEY$
is a keyword that is usually supported by any adapter.
An example is defined in Table 3-14.

Table 3-14: KEY syntax example Example
$KEY$ = $KEYLIST$
Result
$<keyfield1>$ = key1 AND $<keyfield2>$ = key2
KEYLIST
This is a special syntax for data key queries. If this syntax is entered for an AR System query, it requests a list of data values from the external data store for the key fields that are defined on the Primary Key Mapping tab of the respective mapping console for AR, CMDB and Relationship data exchange. It generates a query that returns all requests from an AR System form where the AR System data keys for this data mapping exist in the key list obtained from the External data store. The External data store list is either all key values in the thirdparty data store or a subset of keys based on the query defined in the External Data Store Query field on the Data Key Query sub tab of the Query tab on the Mapping Information window.
NOTE
$KEYLIST$
is a keyword that is usually supported by any adapter.
58
Using the adapter rule helper utilities
The operators IN, =, NOT IN, or != can precede $KEYLIST$. (For the $KEYLIST$ syntax, = is the same as IN, and != is the same as NOT IN.) $KEYLIST$ is expanded with a series of <$field$> <operator> <value> statements as shown in Table 3-15.
Table 3-15: KEYLIST syntax examples Example
$KEY$ = $KEYLIST$ $KEY$ != $KEYLIST$
Result Indicates that all records matching the keys in the $KEYLIST$ are to be returned. Indicates that all records not matching the keys in the $KEYLIST$ are to be returned.
Row-level query syntax

You can only use the syntax described in this section in the query syntax for a rowlevel query. Integration Engine supports update, response, and deletion row-level queries. Row-level queries are defined on the Update Query sub tab of the Query tab on the EIE:ARMappingInfo form.
SRC syntax ($SRC| <fieldname>$)

SRC (source) syntax is a special syntax for row-level queries. It allows you to have values from the source row substituted into the query before the query is compared against the target row. The query is applied to the target row rather than the source and target rows. Examples are defined in Table 3-16.
Table 3-16: SRC syntax examples Example
$LastModified$ < $SRC|LastMod$
Result
$LastModified$ < 05/23/07
(if LastMod is a field in the source database with a value of 05/23/07)

The Database Field Menus Console is used for populating field menus which are used when you create data mappings. The field menus allow you to choose the fields from your external data store from a list instead of typing them manually. You use the adapter rule helpers to create field menus for external data store tables. The DB2, Oracle, and SQL Server rule helpers are used through the Database Field Menus Console. XML Helper and File Helper are used through workflows. They can also be run from a command line to populate fields in .tbl and .xsd in the EIE:VendorFieldNames form.
NOTE
All helper binaries are available in the <AIE install directory>\bin directories.
Chapter 3
59
Using the DB2 Adapter Rule Helper utility

You can populate field information for a single external data table or multiple external data tables using commands. You can also populate multiple external data tables by adding the DB2 tables and views to the rule menus using the Integration Engine console. If the list does not populate using the console, you can use the command-line procedure instead.
Populating DB2 field information for multiple external data tables

The following steps describe how you populate DB2 fields for multiple external data tables.
To populate DB2 field information for multiple external data tables

1 From the Integration Engine console, click Configuration > Database Field Menus.
The Database Field Menus Console appears.

Figure 3-1: Database Field Menus Console
The DB2 tab appears by default.

2 Type your database instance, database alias, login name, and password in the
respective fields.
3 In the Limit tables and views for owner field, type the user (owner) name. 4 Click Load Table & View Names.
All the tables and views from the user database are populated in the Available Tables and Views list.
60 Administrators Guide
Using the adapter rule helper utilities 5 From the Available Tables and Views list, select the table or view, and click Add.
The table or view is added to the Selected Tables and Views list.
6 Click Update Columns.
The rule menus with your table and view names are populated into the EIE:VendorFieldNames form. This form provides the field names to the rule menus in the data mapping windows.
Populating DB2 field information for external data tables using a command line
The following steps describe how you populate DB2 fields for multiple external data tables and single external data tables using a command line.
To populate DB2 field information for multiple external data tables using a command line
db2helper -ax <ARServername>-ar 0 -al <Demo> -ap <> -da <DB2Alias> dl<DB2Login> -dp <DB2Password> -to <DB2User or DB2Owner> -di <DB2InstanceName> -d
2 After you execute the command, click Refresh Table List on the Database Field
Menus Console window.
The Available Tables and Views list should now be populated.

3 From the Available Tables and Views list, select the table or view, and click Add.
4 After the Selected Tables and Views list is populated with table names, then use
the following command to populate the table fields in the EIE:VendorFieldnames form:
db2helper -ax <ARServername>-ar 0 -al <Demo> -ap <> -da <DB2Alias> dl<DB2Login> -dp <DB2Password> -di <DB2InstanceName> -c
To populate DB2 field information for single external data tables using a command line
Type the following command:
db2helper -ax <ARServername>-ar 0 -al <Demo> -ap <> -da <DB2Alias> dl<DB2Login> -dp <DB2Password> -di <DB2InstanceName> -to <Table Owner> tn <Table Name> -c
You must use three additional parameters:

-c
(Create menu to EIE:VendorFieldNames form) (Table Owner)Valid table name in capital letters.
-to
-tn (Table Name)Valid table name owned by the table owner mentioned in the -to parameter.
Chapter 3
61
Using the Oracle Adapter Rule Helper utility

You can populate field information for a single external data store table or multiple external data store tables using commands. You can also populate multiple external data store tables by adding the Oracle tables and views to the rule menus using the Integration Engine console. If the list does not populate using the console, you can use the command-line procedure instead.
Populating Oracle field information for multiple external data tables

The following steps describe how you populate Oracle fields for multiple external data store tables.
To populate Oracle field information for multiple external data tables

The Database Field Menus Console window appears. The DB2 tab appears by default.
2 Click the Oracle tab.
The Oracle Adapter Rule Helper Utility window appears.

Figure 3-2: Oracle Adapter Rule Helper Utility window
3 Type your SID, database alias, database directory, login name, and password in
the respective fields. Oracle helper.
4 In the DB Directory field, type the Oracle home directory where you will execute
62
Using the adapter rule helper utilities 5 In the Limit tables and views for owner field, type the user (owner) name. 6 Click Load Table & View Names.
Populating Oracle field information for external data tables using a command line
The following steps describe how you populate Oracle fields for multiple external data tables and single external data tables using a command line.
To populate Oracle field information for multiple external data tables using a command line
rlohelper -ax <ARServername>-ar <ARPort> -al <ARUser> -ap <ARPassword> os <SID> -ol <DBUser> -op <DBPassword> -oh <OracleDBDirectory> -oa <SID> -to <DBOwner> -d
2 After you execute the command, click Refresh Table List on the Database Field
Menus Console window.
The Available Tables and Views list should now be populated.

4 After the Selected Tables and Views list is populated with table names, then use
the following command to populate the table fields in the EIE:VendorFieldnames form:
rlohelper -ax <ARServername>-ar <ARPort> -al <ARUser> -ap <ARPassword> os <SID> -ol <DBUser> -op <DBPassword> -oh <OracleDBDirectory> -oa <SID> -c -d
Chapter 3
63
To populate Oracle field information for single external data tables using a command line
Type the following command:
rlohelper -ax <ARServername>-ar <ARPort> -al <ARUser> -ap <ARPassword> os <SID> -ol <DBUser> -op <DBPassword> -oh <OracleDBDirectory> -oa <SID> -c -d -to <Table Owner> -tn <Table Name>
You must use three additional parameters:

-c
(Create menu to EIE:VendorFieldNames form) (Table Owner)Valid table name in capital letters.
-to
-tn (Table Name)Valid table name owned by the table owner mentioned in the -to parameter.
Using the SQL Adapter Rule Helper utility

You can add SQL Server tables and views to rule menus using the Integration Engine console. If the list does not populate using the console, you can use the command-line procedure instead.
Populating SQL field information for multiple external data tables

The following steps describe how you populate SQL fields for multiple external data tables.
64
To populate SQL field information for multiple external data tables

The Database Field Menus Console window appears. The DB2 tab appears by default.
2 Click the SQL Server tab.
The SQL Adapter Rule Helper Utility window appears.

Figure 3-3: SQL Adapter Rule Helper Utility window
3 In the Server Name field, type the name of your SQL Server. 4 In the Database Name field, type the name of your SQL Server database. 5 Complete one of the following actions:
Type your user name in the Login Name field and the password in the Password field. If you use Windows authentication for your database, click the Enable Windows Authentication check box. If you select this option, you do not need to type a login name or password.
6 Click Save. 7 In the Limit tables and views for owner field, complete one of the following
actions:
Leave this field blank to have Integration Engine retrieve all tables and views. Type a user (owner) name in this field to retrieve only the tables and views owned by that user.
Chapter 3
65
BMC Atrium Integration Engine 7.1.00 8 Click Load Table & View Names.
Populating SQL field information for multiple external data tables using a Windows-based application
The following steps describe how you populate SQL fields for multiple external data tables using a Windows-based application. For example,
<AIE_install_dir>\bin\rlshelper.exe.
To populate SQL field information for multiple external data tables using a Windows-based application
1 Choose Start > Run from the Windows start menu.
The Run dialog box appears.

2 In the Open field, browse to select the path for running the Rule Helper utility.
NOTE
The utility is located at <AIE_install_dir>\bin\rlshelper.exe. The Rule Helper window appears. The Main tab appears by default.
66
Using the adapter rule helper utilities 3 Click the Database Connection tab.
The database login information appears.

Figure 3-4: Database Connection tab
You use the Database Connection tab to define connection information to locate the SQL Server database (used as a rule source) and the AR System server where the Data Exchange application is installed.
4 In the Microsoft SQL Server Connection area, do the following tasks: a In the Database Server field, type the name of the Windows host where the SQL
Server database is installed.
b In the Database Name field, type the name of the SQL Server database from
which the Rule Helper utility obtains table and view definitions. database.
c In the User Name field, type the user name for connecting to the SQL Server
The user must have privileges to read the system catalog to obtain the definition of the database objects used in the exchange. The user must also have access to the objects used in the data exchange.
d In the Password field, type the password associated with the user name used to
connect to the SQL Server database.
e To enable Windows authentication for database connection, select the Enable
Windows Authentication check box.
For example, the user who is logged on to Integration Engine, will be considered for database authentication.
Chapter 3 Defining rules and queries 67
BMC Atrium Integration Engine 7.1.00 5 In the AR System Server Connection area, do the following tasks: a In the AR Server field, type the host name of the AR System server. b In the RPC Port field, type the port number of the AR System server. c In the User Name field, type the user name for the AR System administrator. d In the Password field, type the password for the AR System administrator. 6 Click the Main tab.
The SQL Server database tables and views information appears.

Figure 3-5: Main tab
7 Click Load Table/View Names.
The list on the left is updated with the tables and views from the SQL Server database.
8 Select the tables and views you want to add from the list on the left, and click Add
to add them to the EIE Data Exchange menu list on the right.
9 Click Create Menu. 10 Click Close.
68
Using the XML Adapter Rule Helper utility

You must run the XML Adapter Rule Helper utility from a command line. Type the following command:
xmlhelper -ax <ARServerName> -al Login -ap Password -ar port -xp <Path to the xml schema> -xr <xml row identifier>-d
Using the File Adapter Rule Helper utility

You must run the File Adapter Rule Helper utility from a command line. Type the following command:
filehelper -ax <ARServerName> -al Login -ap Password -ar port -fn <Path to the file on the local machine> -d
Using the the adapter rule helper utilities on UNIX platforms

For UNIX platforms, rlohelper.sh and db2helper.sh are the two scripts that are executed. These scripts are located in the <arserver_installation>/bin directory. These scripts internally invoke the respective Rulehelper utilities for both Oracle and DB2.
NOTE
For DB2 rule helper, if you have AR server installed on Oracle, you must change the db2helper.sh script to set the DB2 client installation directory.
To edit the script for DB2

1 Open <arserver_installation>/bin/db2helper.sh. 2 Append the line, AIE_DB2_LIB_DIR=,to read as follows:
AIE_DB2_LIB_DIR=/opt/IBM/db2/V9.1.
NOTE
You must enter the path to the parent of the lib/lib32 directory only. For Oracle, the path derives from the command line parameter.
Chapter 3
69
Populating the rule control

You can append rules to the rule control on the Field Mapping, Response, Delete, and Query tabs of the EIE:ARMappingInfo form by using the EIE:Rules form. Customizing this control helps you add rules and functions that you often use. Table 3-17 shows how this control is implemented on each tab.
Table 3-17: Rule control implementation Tab Data Field Mapping Response Field Mapping Delete Field Mapping Query Implementation Rules list Rules list Rules list Rules list
For example, the following procedure describes how you can add a customized rule that concatenates the first and last name fields.
To populate the rule control

1 Log on to BMC Remedy User as an administrator. 2 Choose File > Open > Object List.
The Object List window appears.

Figure 3-6: Object List window
3 Select EIE:Rules.
70
Populating the rule control 4 Click New.
The EIE:Rules window appears.

Figure 3-7: EIE:Rules window
5 In the EIE Keyword field, type the item that you want to append to the list.
This is just a text identifier for the field or rule. It need not be the exact syntax of the rule. For example, type First & Last Name.
6 In the Syntax field, type the syntax of the field or rule.
This is the actual text that is placed into the field in the EIE:ARMappingInfo form. For example, type concat($FirstName$, " ", $LastName$) to generate a first name followed by a space and then a last name.
7 In the Category drop-down list, select a category that represents the fields to
populate with your item. The choices are: Field Rule
Populates the selections from the Rule control for data mappings. Query Rule Populates the selections from the Rule control for queries. For this example, select Field Rule. Delete Rule Populates the selections from the Rule control for deletions.
Chapter 3
71
BMC Atrium Integration Engine 7.1.00 8 In the Prefix Syntax drop-down list, select the syntax of a prefix that is required for
the category of a command.
NOTE
Currently function | is the only valid prefix. If a prefix is present, workflow verifies that the field receiving the keyword starts with a prefix. If it does, the prefix is placed at the start of a line followed by the syntax field contents. This is intended for items with prefixes, such as functions. For this example, select function|.
9 In the Rule Owner field, type the data store for which this rule is valid.
To limit the use of this field or rule to a particular external data store, type the name of the adapter, which is the value defined in the External Data Store field on the EIE:DataExchange form. If this field is left blank, all Integration Engine services can use this field or rule.
10 In the Rule Display field, type the name of the rule as you would like it displayed. 11 Click Save.
The concat($LastName$,",",$FirstName$) function that you just created is available from the selection list that is accessed from the Rule control located on the Field Mapping tab.
72
Chapter
Activating event-driven data exchanges

You can create an event-driven data exchange request by using the Application Pending form, invoking the eiexfer utility, or creating AR System workflow that does either of these. The following topics are provided: Creating a request on the Application Pending form (page 74) Creating a request using the eiexfer utility (page 78) Activating an event-driven data exchange through workflow (page 83)
Chapter 4
73
Creating a request on the Application Pending form

Whether you create requests using the Application Pending form or the eiexfer utility, all event-driven requests are written to the Application Pending form. The Integration Engine service processes requests on the Application Pending form on a scheduled interval that is configured in the eie.cfg file (the AsyncInterval parameter).
NOTE
The Integration Engine service has no mechanism for clearing entries on the Application Pending form. From time to time, you must delete old entries manually to keep the database from getting too large. Alternatively, you can write workflow that periodically deletes entries automatically. You can identify a record that you want to transfer either by its key or its AR System request ID. Alternatively, you can include all records configured for exchange by running a bulk exchange.
NOTE
You cannot identify a record by its AR System request ID if you are running a data exchange between an external data store and BMC Atrium CMDB classes. In this case, you must use its key.
74
Creating a request on the Application Pending form
To create a request on the Application Pending form

1 Log in to BMC Remedy User. 2 Choose File > Open > Object List.
The Object List window appears.

Figure 4-1: Object List window
3 Select the Application Pending form. 4 Click New.
The Application Pending window appears.

Figure 4-2: Application Pending window
5 In the Category field, type EIE.
Chapter 4
75
BMC Atrium Integration Engine 7.1.00 6 In the Command field, type the name of the data exchange that you want to use.
The data exchange name is the value you typed in the Exchange Name field on the Main tab of the EIE:DataExchange form.
7 In the Form field, type the instance name. 8 In the Source ID field, type New.
The Source ID field indicates the status of the request. Table 4-1 shows the list of status values.
Table 4-1: Status values Status New In Progress Completed Error Description The request has been submitted but has not been processed. The request is currently being processed. The request completed successfully. The request for a data transfer did not take place because there was a problem. The most common problem is an error in the syntax in the Other Short field or an unrecognized data exchange name. The text in the Other Long field indicates the cause of the error. As with log messages, the you can write workflow to send a notification to the submitter to indicate if an error has occurred. Failed The request for data transfer was attempted and failed. The text in the Other Long field indicates the cause of the error.
9 In the Tag field, enter one of the following types of event driven exchange:
Immediate Request On Schedule Interval
76
Creating a request on the Application Pending form 10 In the Other Short field, type the key or the AR System request ID for the record
that you want to include in the data exchange, or invoke all records configured for a data exchange using one or more of the parameters in Table 4-2.
Table 4-2: Data Exchange parameters Parameter Description is the value you typed in the Exchange Name field on the Main tab of the EIE:DataExchange form. This parameter is mandatory if you want to specify individual records for exchange rather than invoking a bulk transfer.
-s <data_exchange_name> Specifies the data exchange to use. The data exchange name
-k <key_value>
Specifies the key value of the record you want to transfer. Every key value that you enter must have a corresponding entry on the Primary Key Mapping tab of the EIE:ARMappingInfo form. You must enter multiple key values if multiple key fields are defined on the Primary Key Mapping tab.
Note: If you want a space to be recognized as a space, add
single quotes around the value. For example, to enter the last name Van Arc as a single value, enclose it in quotation marks: -k Van Arc Vicki.
-r <request_id>
Specifies the AR System request ID of the record you want to transfer. You can use this parameter to request a record only if your data exchange already contains a data mapping for the form to which this record is transferred.
Note: The -r parameter is not supported for data exchanges
between an external data store and BMC Atrium CMDB classes. -r 0000001472 -r 0000003742).
Note: You can specify one or more request IDs (for example:
-b <data_exchange_name> Specifies that a bulk data transfer of all data defined for a
data exchange is to occur.
NOTE
The -k or -r parameter is used to select individual records for exchange and must be accompanied by the -s parameter. If the -b parameter is used to invoke the exchange of all records, the -s parameter is not used. The Other Long field is completed by Integration Engine after the completion of the data exchange. This field enables printing of the final exchange completion statistics. For example, how many records were inserted or updated.
11 In the Status options, select Pending. 12 Click Save.
Chapter 4
77
Creating a request using the eiexfer utility

The eiexfer utility is an AR System client that opens a connection to AR System and sets up the conditions for the transfer of data on an event-driven basis, according to the parameters specified on the command line. Use this method if you have a distributed environment and are submitting a request from a machine other than the one running the Data Exchange application and the AR System server. Whether you create requests using the Application Pending form or the eiexfer utility, all event-driven requests are written to the Application Pending form. The Integration Engine service processes requests on the Application Pending form on a scheduled interval that is configured in the eie.cfg file (the AsyncInterval parameter). In addition to the scheduled interval, you can also configure the Integration Engine service to process individual event requests immediately if you enter them through the eiexfer utility.
NOTE
If your event-driven data exchange does not need to occur immediately, type your request into the Application Pending form rather than invoking the eiexfer utility to improve performance. By default, the eiexfer utility for Windows is installed in the following directory: <eie_install_dir>\service\bin\eiexfer.exe. However, you can manually move the eiexfer utility (and its supporting DLL files on Windows) to another machine.
To create a request using the eiexfer utility

1 Navigate to the command line of the machine where you installed AR System and
the Data Exchange application.
2 Type the following command using the AR System parameters in Table 4-3, the
Data Exchange parameters in Table 4-4, and the optional immediate parameters in Table 4-5 (if you want to run the data exchange request immediately).
<eie_install_dir>\service\bin\eiexfer.exe
78
Table 4-3 lists the AR System parameters you must use with the eiexfer utility.
Table 4-3: AR System parameters Parameter
-x <arserver_name> -rpcport <port_number> -l <login_name> -p <password>
Description Specifies the name of the AR System server where the Application Pending form resides. Specifies the port of the AR System server (for example, rpcport 4500). Specifies the AR System server login name for connecting to the AR System server. Specifies the password associated with the AR System server login name.
Table 4-4 lists the Data Exchange parameters you can use when using the eiexfer utility.
Table 4-4: Data Exchange parameters Parameter
-s <data_exchange_name>
Description
Specifies the data exchange to use. The data exchange name is the value you typed in the Data Exchange Name field on the Main tab of the EIE:DataExchange form. This parameter is mandatory if you want to specify individual records for exchange rather than invoking a bulk transfer. Specifies the key value of the record you want to transfer. For every key value that you enter, you must have a corresponding entry on the Primary key Mapping tab of the EIE:ARMappingInfo form. You must enter multiple key values if multiple key fields are defined on the Primary Key Mapping tab.
Note: If you want a space to be recognized as a space, add
-k <key_value>
single quotation marks around the value. For example, to enter the last name Van Arc as a single value, enclose it in quotation marks: -k Van Arc Vicki.
-r <request_id>
Specifies the AR System request ID of the record you want to transfer. You can use this parameter to request a record only if your data exchange already contains a data mapping for the form to which this record is transferred.
Note: The -r parameter is not supported for data exchanges
between an external data store and BMC Atrium classes. -r 0000001472 -r 0000003742).
Note: You can specify one or more request IDs (for example:
Chapter 4
79
Table 4-4: Data Exchange parameters Parameter

-b <data_exchange_name> -n <instance_name>
Description
Specifies that a bulk data transfer of all data defined for a data exchange is to occur. Specifies the instance associated with this data exchange.
NOTE
The -k or -r parameter is used to select individual records for exchange and must be accompanied by the -s parameter. If the -b parameter is used to invoke the exchange of all records, the -s parameter is not used. Table 4-5 lists the optional immediate parameters you can use when using the eiexfer utility.
Table 4-5: Optional immediate parameters Parameter
-i -w <no. of seconds before checking for a response> -c
Description
Specifies that the request should be processed immediately. Specifies the number of seconds to wait before checking for the completion status of the request. If you do not specify a value for the -w parameter, the number of seconds defaults to five. Specifies the number of times the program checks for a response before ending. If you do not specify a value for the -c parameter, the number of times defaults to three.
NOTE
The -i parameter is required for immediate handling. The -w and -c parameters are optional.
Examples of the event-driven request command syntax

The following examples assume an AR System server name of myserver, a login name of jdoe, and a password of password. To specify an event-driven request to transfer a record for an employee named Smith from the employees data exchange:
eiexfer -x myserver -l jdoe -p password -s employees -k Smith -n <instance name>
To specify an event-driven request for a bulk exchange of all employee records:

eiexfer -x myserver -l jdoe -p password -b employees -n <instance name>
80
To specify an immediate event-driven request for an employee whose record is identified by the AR System server ID number 23456 from the employees data exchange using a wait interval of 10 seconds and a retry count of 20:
eiexfer -x myserver -l jdoe -p password -s employees -r 23456 -i -w 10 -c 20 -n <instance name>
To specify an immediate event-driven request for a bulk exchange of all employee records using the default wait time of 5 seconds and a retry count of 20:
eiexfer -x myserver -l jdoe -p password -b employees -i -c 20 -n <instance name>
To specify an event-driven request to transfer a record for an employee named Tom Smith from the employees data exchange:
eiexfer -x myserver -l jdoe -p password -s employees -k Smith Tom -n <instance name>
Completion codes returned by eiexfer

Data exchange requests that are submitted through the eiexfer utility return completion codes that indicate the status of a request. These codes fall into several categories, which are listed in Table 4-6.
Table 4-6: eiexfer completion code categories Category 0 100-199 200-299 300-399 400-499 Description Request completed successfully. Request was not submitted to event-driven request queue. Request was submitted, but the Integration Engine service could not be notified to handle the request. Request was submitted and the Integration Engine service was notified to handle the request, but the completion status could not be obtained. Request was handled by the Integration Engine service, but the data failed to transfer. The request in the Application Pending form contains the error message indicating the cause of the failure.
The completion codes are listed in Table 4-7. A brief definition follows each message in the table.
Table 4-7: eiexfer completion code messages ID Number 0 Message
Request completed successfully.
The event-driven request is complete and no errors were encountered during the data transfer. -101
Required parameters are missing.
One or more required parameters are missing from the event-driven request. The request was not submitted for processing.
Chapter 4
81
Table 4-7: eiexfer completion code messages ID Number -102 Message

Unable to create buffer for the event request.
The event-driven interface ran out of available memory and was unable to create a request block to transmit the request. The processing cannot continue. This is a fatal error. -103
AR Initialization failed. Verify login information is correct.
The event-driven interface was unable to connect to the AR System server identified by the parameters. Verify the AR System server login parameters. If the parameters are correct, verify that the AR System server is running. -104
Failed to submit event request. ARCreateEntry returns error.
The event-driven request could not be submitted to the Application Pending form on the AR System server. Verify that the AR System server identified in the startup parameters has the Data Exchange application installed. -201
Unable to retrieve host name and port for EIE service. Make sure the AR System user name and password are correct.
The event-driven request has been submitted, but the Integration Engine service could not be notified to handle the request. The Integration Engine service sets the wakeup port information in the EIE:BackupLoadFlag form. If the values are not set, no active Integration Engine service exists to handle the request at this time. -202
EIE service wakeup port not set in EIE:BackupLoadFlag form.
The event-driven request has been submitted, but the Integration Engine service could not be notified to handle the request. The Integration Engine service sets the wakeup port information in the EIE:BackupLoadFlag form. If the values are not set, no active Integration Engine service exists to handle the request at this time. -203 -204
Unable to create socket. Unable to establish socket connection to EIE service.
The event-driven request has been submitted, but the Integration Engine service could not be notified to handle the request. A socket connection to the Integration Engine service has been identified in the EIE:BackupLoadFlag form, but the socket connection could not be established. -205
Unable to send immediate request to EIE service.
The event-driven request has been submitted, but the Integration Engine service could not be notified to handle the request. A socket connection to the Integration Engine service has been established, but the wakeup request could not be sent. -301
Unable to access Event Request form to obtain response.
The event-driven request has been submitted, and the Integration Engine service has been notified to handle the request. The Application Pending form could not be accessed to obtain the completion status.
82
Activating an event-driven data exchange through workflow
Table 4-7: eiexfer completion code messages ID Number -302 Message

Request has not completed in time interval allowed.
The event-driven request has been submitted, and the Integration Engine service has been notified to handle the request. The request has not completed within the time interval allotted to check for a request. The event-driven interface makes three attempts to check for the completion status. Each request is tried after waiting the number of minutes in the -w parameter specified in eiexfer. -401
Transfer failed when handled by EIE service.
The event-driven request is complete and the Integration Engine service has returned an error indicating the data transfer failed. For detailed information about the error, check the debug file associated with the data exchange used in the data transfer.
Activating an event-driven data exchange through workflow

You can enter a request for an event-driven data exchange from an active link or filter. The active link or filter can either write a request directly in the Application Pending form or run the eiexfer utility. See BMC Remedy Action Request System 7.1.00 Workflow Objects for instructions on how to create active links or filters on your AR System form.
Chapter 4
83
84
Chapter
Running and configuring the Integration Engine service

You can run the Integration Engine service on Windows and UNIX. On Windows, you run the Integration Engine service from a command line or as a Windows service. On UNIX, you run the Integration Engine service from a command line in your terminals foreground or as a daemon. The Integration Engine service parameters are defined in the configuration file (eie.cfg). The following topics are provided: Running the Integration Engine service on Windows (page 86) Running the Integration Engine service on UNIX (page 87) Understanding the configuration file and its parameters (page 88) Managing instances (page 93) Changing Integration Engine AR System password (page 95)
Chapter 5
85
Running the Integration Engine service on Windows

When installing Integration Engine, you can choose to start the Integration Engine service in automatic or manual mode. Selecting manual mode prevents the Integration Engine service from starting automatically before you are ready to run in production mode.
To run the Integration Engine service from a command line

Type the following parameters on the command line in the directory where the Integration Engine executable is located (for example, <eie_install_dir>\service\bin) using the parameters in Table 5-1:
eie.exe -x <AR Server name> -p <port number> -n <instance name> -m
Table 5-1: EIE service command-line parameters for Windows Parameter -m -x -n -p Description Indicates that the Integration Engine service is running from the command line. This parameter is required for both Windows and UNIX. AR server name on which Integration Engine is installed. Instance name which user wants to run. Port number for AR.
One of the following messages appear: If Integration Engine was able to execute the data exchanges, then this message appears:
The engine is running and has detected n active data exchanges on AR System: STUDIO
If Integration Engine is not able execute the data exchanges then the following message appears:
Failed to retrieve any active data exchange defined on AR System: STUDIO
There could be three reasons for this to occur: You did not select any data exchange as active. The AR System user assigned to Integration Engine in the Integration Engine Application console does not have administrator privileges. You did not select a data mapping for the active data exchange definition.
NOTE
If you change the eie.cfg file to solve the problem, then stop and restart the service to continue.
86
Running the Integration Engine service on UNIX
Running the Integration Engine service on UNIX

You can run the Integration Engine on UNIX.
To run the Integration Engine service in the foreground

1 Open a terminal window. 2 Change to the directory where the Integration Engine service is installed (or
include the full path):
/usr/bmc/apps/aie/{ServerName-Port}/service/bin
3 Start the Integration Engine service.
In the service bin directory there are different start up script files are created to start different instance. You can access them at: ./aie001 start.
NOTE
On UNIX, Integration Engine services are created as batch files based on the number of Integration Engine instances you install. For example, if you install three instances of Integration Engine, then three Integration Engine Service batch files are created named aie001, aie002, and aie003. You then create your data exchanges based on these instances. In this case, if you wanted to run a data exchange for the second instance, you would type ./aie002 start on the command line.
4 Do one of the following actions:
stop.
Stop a particular instance by using its script and parameter as stop: ./aie002 Restart a particular instance by using its script and parameter restart: ./aie002
restart.
During startup, the Integration Engine service displays a message telling how many active data exchanges are running. The message is refreshed at an interval configured in the eie.cfg file. However, this information does not indicate whether the active data exchanges are running successfully. To determine whether the data exchange ran successfully, check the data exchange debug or log files for details about individual data exchanges. By default, debug files are located in the <eie_install_dir>\service\debug directory, and log files are located in the <eie_install_dir>\service\log directory.
Chapter 5
87
Loading the adapters

If you installed Integration Engine in custom mode and did not provide the Oracle directory or the DB2 directory or if you chose the express setup, either of the following warning messages will appear if you try to start the aie instance.
WARNING: Please make sure that AIE_ORACLE_LIB_DIR is set to point to Oracle client directory if you are going to use Oracle Adapter. WARNING: Please make sure that AIE_DB2_LIB_DIR variable is set to point to DB2 client directory if you are going to use DB2 Adapter.
To load the adapters

1 Do either of the following tasks:
For Oracle, you can either set the environment variable AIE_ORACLE_LIB_DIR or open the startup script file and provide the appropriate value for AIE_ORACLE_LIB_DIR which points to the Oracle 32 bit lib folder located inside the oracle client/database installation folder. For DB2, you can either set the environment variable AIE_DB2_LIB_DIR or open the startup script file and provide the appropriate value for AIE_DB2_LIB_DIR which points to the DB2 32 bit lib folder located inside the DB2 client/database installation folder.
2 To set the variable inside the script file, do the following tasks: a Locate the script file:
{start_instance() { [ ! "$AIE_ORACLE_LIB_DIR" ] && AIE_ORACLE_LIB_DIR=.
The "." indicates that the database path is not being provided.
b Replace the "." with the appropriate database path indicated in the following
example for DB2:
[ ! "$AIE_DB2_LIB_DIR" ] && AIE_DB2_LIB_DIR=/opt/IBM/DB2/V9.1
Understanding the configuration file and its parameters

The configuration file (eie.cfg) is used by the Integration Engine service to locate the AR System server where the Data Exchange application is installed. It also contains global logging and debugging information. Some of the parameters in the configuration file are generated during installation based on the values you enter at that time. The rest are set with default values at installation. To change any of these settings, you can edit eie.cfg by opening it in a text editor and making the necessary changes.
88
Sample configuration file

If you installed Integration Engine in the default location, eie.cfg is located in:
<eie_install_dir>\service\conf\eie.cfg
In the sample eie.cfg file that follows, lines beginning with the pound (#) symbol are comments. See Configuration file parameters on page 90 for more information about eie.cfg parameters.
# Integration Engine Configuration Parameters [Log] # Adds one record, indicating status and other details, in the # EIE:Log form for each record transferred during each data # exchange. This form can quickly become populated with a large # number of records, so do not leave the Logging parameter set to # Yes for extended periods. Also defines the location of the log # file and whether it is active or inactive. Logging: Yes LogPath: C:\Program Files\BMC Software\BMC Atrium Integration Engine\human resources\service\log # Size of the file in bytes. MaxLogSize: 102400 [Debug] # Max size for debug(.dbg) files MaxDebugSize: 102400 # Timestamp option adds a timestamp on each debug message: # Yes/No. TimestampDebug: Yes # DebugOn option activates a debug file for eiemain. (Yes/No) Can # also be specified on the command line to activate a debug file # prior to the config file being read. DebugOn: Yes DebugPath: C:\Program Files\BMC Software\BMC Atrium Integration Engine\human resources\service\debug # Debug option: Stack trace for the engine: Yes/No. StackTrace:No [AR System Info] # AR System Server connection information for engine-owned # AR System resources. ARServerName: humanresources ARLogin: Demo ARPassword: ARPort: 0 Unicode: No [Data Exchange Info] # Defines, in minutes, how often the engine checks for data # exchanges that have become active or inactive since the last # poll interval. For data exchanges that have become # activated, it creates new threads. For data exchanges that have # become deactivated, it removes their threads. If you give 1440 # as the value for the parameter, the engine checks for activated # and deactivated data exchanges one time each day. Default is # set to 5 minutes for debugging. For production, set it to # 60 minutes or greater.
Chapter 5
89
ConfigInterval:
# Defines how many times the data exchange definitions are read # before the engine stops. Set to 0 to run the engine without # ending. This is for production use. Set to 1 or more to run the # engine for 1 or more passes. Can be used for debugging. ConfigPassCount: 0 # Defines how often the async event queue is read. If this # parameter is left blank (or set as 0) it will be set to a # default value of 5 minutes. AsyncInterval: 5
Configuration file parameters

Table 5-2 provides an alphabetical list of all the standard configuration parameters used by the Integration Engine service. The Integration Engine service ignores any unrecognized or misspelled parameters. Default values, if any, are indicated in the description.
Table 5-2: Integration Engine service configuration parameters Parameter # ARLogin Description A comment character. It enables you to comment out any line in the configuration file so that the program bypasses the line. Indicates the AR System account that the Integration Engine service uses for accessing the server. This account must be an AR System administrator account so that you can modify, add, and delete the requests for the forms and fields it accesses. The value is specified during installation, and can also be modified from the Integration Engine Application console. Indicates the password associated with the login for access to this server. For security, this field is encrypted. Indicates the name of the AR System server to which this service connects. During installation, the value entered for the AR System server is recorded here. You can change this parameter to another server name. The number of minutes the async thread waits before looking for new async requests. Every <x> minutes, the Integration Engine service checks for entries on the Application Pending form requesting an asynchronous transfer of data. If it finds such entries, it processes all requests on the form, and then checks again after <x> minutes. The default is five minutes. For better performance, if you are not planning to submit event-driven requests to the Integration Engine service, set this parameter to zero so that the Integration Engine service ignores it.
ARPassword ARServerName
AsyncInterval
90
Table 5-2: Integration Engine service configuration parameters Parameter ConfigInterval Description Defines, in minutes, how often the Integration Engine service waits between checking for data exchanges that have become active or inactive since the last poll interval. The Integration Engine service creates new threads for active data exchanges and removes the associated threads for data exchanges that have become deactivated. A value of 1440 results in the Integration Engine service checking for activated and deactivated data exchanges once a day. The default is five minutes, which is appropriate for debugging. This parameter works with the settings on the Schedule tab of the EIE:DataExchange form. The ConfigInterval parameter determines how often the Integration Engine service checks the status of the data exchanges. The settings on the Schedule tab initiate the data exchanges at the interval or time specified. ConfigPassCount Number of passes that the Integration Engine service makes looking for active data exchanges. This parameter is useful for testing. After the Integration Engine service has completed the designated number of passes, it does not become active again until it is stopped and restarted. A value of 0 results in continuous activity. The default is one pass. Enables the Integration Engine service to record details and problems with the Integration Engine service in the eiemain.dbg file. See Chapter 6, Logging and debugging for more information. The default setting is Yes. Logging Enables or disables logging of messages to the local log file and to the EIE:Events form. See Chapter 6, Logging and debugging to view a list of log file messages. Valid values are:
Yes (enable logging) No (disable logging)
DebugOn
The default setting is Yes. MaxDebugSize Indicates the maximum size in bytes that the debug file reaches before it closes the current file and copies it to a .bak version. The previous .bak version is overwritten. The default value is 102400. Indicates the maximum size in bytes that the log file reaches before it closes the current file and copies it to a .bak version. The previous .bak version is overwritten. The default value is 102400.
MaxLogSize
Chapter 5
91
Table 5-2: Integration Engine service configuration parameters Parameter StackTrace Description Stores a line-by-line account of the activity of the Integration Engine service in the eiemain.dbg file and in each data exchange debug file. Use only when necessary as the debug files can become large. Valid values are:
Yes (enable stack trace) No (disable stack trace)
The default setting is No. TimeStampDebug Adds a timestamp at the beginning of each line in eiemain.dbg and in every <exchange_name>.dbg file. The default value is Yes.
Editing the configuration file

Most of the parameters in the configuration file are set with default values at installation. To change any of these settings (for example, increasing the maximum log size), you can edit eie.cfg by opening it in a text editor and making the necessary changes.
ARServerName)
The AR System parameters in the configuration file (ARLogin, ARPassword, and are set based on values that you enter during installation. As with the other configuration file parameters, you can edit these settings using a text editor.
If you edit the configuration file with a text editor, the ARPassword parameter appears in plain text in eie.cfg, rather than being encrypted. This can pose a security risk. You can use the eiecfedit utility to edit the ARPassword parameter while maintaining encryption for your AR System password in eie.cfg.
IMPORTANT
92
Managing instances
To edit and encrypt a password in the configuration file

Type the following command on the command line using the parameters in Table 5-3:
<eie_install_dir>\service\bin\eiecfedit.exe -x <arsystem_name> -s <arserver_name> -l <login_name>-p <password>
Table 5-3: eiecfedit parameters Parameter -x -s Description Indicates the server name that goes in eie.cfg. Indicates the server name specified during installation when you are installing multiple instances on different AR System servers. Indicates the login name used to login to the AR System server. Indicates the login password for a given login name.
-l -p
Managing instances
In the Instances Console, you can view and edit information about Integration Engine instances.
To modify an Integration Engine instance

1 On the navigation panel, click Configuration > Instances.
The Instances Console appears.

Figure 5-1: Instances Console
Chapter 5
93
BMC Atrium Integration Engine 7.1.00 2 In the Instance Name field, type the name you want to see when selecting this
instance in other areas of the Integration Engine interface. set.
3 In the Unicode field, you select whether the instance uses the Unicode character
If you select No, Integration Engine uses the character set you specify at the data exchange level.
4 Click Save. 5 You can view, but not modify, the remaining instance information:
Internal Instance NameThe name created by the installer for this instance HostThe name of the server where Integration Engine is installed PortThe port on which Integration Engine communicates. The default value is 3021. Engine LoadThe readiness of the Integration Engine service. If this value is Yes, the service is ready to start. AIE VersionThe version of Integration Engine you are running.
94
Changing Integration Engine AR System password
Changing Integration Engine AR System password

If you have changed your password in AR System, you must also change it in Integration Engine console and the eie.cfg file.
To change your AR System password on the Integration Engine console

1 From Integration Engine navigation bar, select Configuration > Integration Engine
App.
The Integration Engine Application Console appears.

Figure 5-2: Integration Engine Application Console
2 In the Admin Login Name field, type the administrator login name you used for
AR System. System.
3 In the Admin Password field, type the administrator password you used for AR 4 Click Save.
Using this method keeps the password encrypted.
Chapter 5
95
To change your AR System password in the eie.cfg file

1 Run the eiecfedit command line utility located in $AIE_HOME/service/bin.
This utility helps set the encrypted password in the eie.cfg file and ensures the utility can be run on UNIX as well.
NOTE
To run this utility on UNIX, you must set a library path. The following prompt appears:
usage: -s <AR server(During Installation)> -n <Port Number (During Installation)> -x <AR Server> -l <user name> -p <password> where: -s <AR Server> Server name given during EIE Installation (mandatory) -n <Port Number> Port given during EIE Installation (default 0) -x <AR System> Server name which goes in eie.cfg file -1 <user name> is the logon name used to log on to the AR System server -p <password> is the users password
2 Change the user name and password.
96
Chapter
Logging and debugging
You can diagnose errors and verify the completion of data exchanges using the logging and debugging facilities in Integration Engine. The logging facility aids in long-term management of data exchanges. The logging of events is controlled by the logging parameter in the eie.cfg file. You can configure and test data exchanges by using the debug facility. The debugging files provide detailed operational information to diagnose errors in a data exchange. The following topics are provided: Log messages (page 98) Debug messages (page 102) Debug logging settings (page 106)
Chapter 6
97
Log messages
Log messages record all major events about data exchanges and individual record transfers. All log events are recorded both in the Integration Engine log file and the EIE:Log form. Log messages are useful but provide only broad information about events and errors. For more detailed information, you should also use the log of debug events to assist you in understanding the nature of problems that you encounter and how to correct them. Logging is controlled by the Logging parameter in eie.cfg. Both the Logging parameter and the eie.cfg file are explained in greater detail in Chapter 5, Running and configuring the Integration Engine service. Log messages are sorted into several event categories. Each category has both informational messages and error messages. You can use the log message categories to determine what kind of workflow to generate. For example, you might want to write workflow to send notifications based on log message numbers or categories to the individuals in your company who are responsible for managing various parts of the data exchanges. Table 6-1 shows the supported log message event categories.
Table 6-1: Log message event categories Category Service Status Session Statistics Description Indicates when a data exchange starts and when it ends. Provides statistics about the number of records processed for the main mapping of a data exchange. The count includes records added, updated, or not transferred due to an error. Indicates an error with a data exchange that prevents the data exchange from taking place.
Service Error
Transfer Warning Indicates that a transfer was made despite a possible problem, such as data truncated to fit a field. The key of the request is provided in the message text. Transfer Error Indicates that a transfer was not made due to a problem, such as a data conversion error. The error message indicates the key of the record that failed and any associated AR System server error messages. More detailed information about why a record was not transferred is recorded in the debug file (if debugging is activated). Indicates that the adapter could not be used by Integration Engine. This could be the result of an invalid registry entry, a .dll file not in the correct path, and so on.
Adapter Error
98
Log messages
Table 6-2 lists log messages that you might receive during a data exchange. Some messages contain placeholders, such as %1, %2, and so on. These placeholders represent text that is completed during run time. Next to each message in Table 6-2, is a brief description of what caused the message to appear.
Table 6-2: Log file messages ID Number 3301 Message
BMC Remedy Link starting to process requests <%1>. BMC Remedy Link Terminating <%1>. No Field Mapping entries defined for VendorApp: <%1>.
Description The Integration Engine service started a data exchange session at the time indicated. An error condition caused the Integration Engine service to terminate at the indicated time. No requests exist on the Data Field Mapping tab of the EIE:ARMappingInfo form for the Integration Engine service to use. The Integration Engine service does not process requests without field mapping rules defined. The Integration Engine service ran out of available memory and cannot continue. This is a fatal error. No rules were defined for the specified field mapping. The Integration Engine service ignores this request and continues. After rules are defined, the Integration Engine service uses this request. The Integration Engine service received an error while trying to process the specified form and request ID. An additional error message precedes this error, indicating that a call to the AR System server failed. The Integration Engine service received an error from the AR System server that was trying to create a request in the specified form. The Integration Engine service received an error while trying to add a unique identifier to the specified form. Additional errors precede this one, indicating which calls to the AR System server failed. The Integration Engine service could not find or open eie.cfg. Verify that the configuration file exists and is accessible. The specified configuration parameter was missing or typed incorrectly. Add or correct the entry in eie.cfg.
3302
3303
3304
Malloc failed.
3305
No Rules defined for field mapping <%1>; field mapping definition ignored. Failed to update form <%1> request-id <%2>.
3306
3307
Failed to create request in form <%1>.
3308
Failed to add request <%1> to form <%2>.
3310
Failed to open configuration file <%1>. Required configuration parameter is missing <%1>.
3311
Chapter 6
99

Form <%1> does not exist or is not accessible.
Description The specified form does not exist or is not accessible. Verify that the form exists and that the login used by the Integration Engine service has permission to create, modify, and delete requests. No valid requests exist in the corresponding mapping consoles for AR and CMDB. Correct the existing requests rules, or create valid rules. The Integration Engine service could not load the indicated message .dll file. The Integration Engine service could not delete the specified request in the form. The Integration Engine service deletes requests that do not have a matching primary form request. Make sure that the account being used by the Integration Engine service has permission to delete requests. The specified form is missing one or more required fields. Use the respective Mapping Information windows for AR System forms, CI classes, and relationship classes to create or modify all the field mappings.
3313
No valid field mapping rules are defined; daemon cannot run. Failed to load message DLL <%1>. Failed to delete request <%1> for form <%2>.
3314 3315
3316
One or more required fields are missing from form <%1>.
3317
A fatal setup error A nonrecoverable error occurred while the Integration Engine service was being set occurred; service cannot run until it is corrected. up to process requests. Previous messages
indicate what is wrong.
3318
A setup error occurred; the service will try again at its next scheduled time. Setup completed successfully, starting to process requests. Failed to update form <%1> request <%2>.
A recoverable error occurred while the Integration Engine service was being set up to process requests. A previous message indicates what is wrong. The Integration Engine service completed setup and will begin a data exchange. The Integration Engine service received an error from the AR System server while trying to update the indicated request in the specified form.
3319
3320
3321
Could not find the field The Integration Engine service was unable mapping name <%1> for to locate the indicated field mapping name request <%2> in form <%3>. in the specified form for the indicated
request. The request will not be updated.
3322
No data was returned using field mapping definition <%1> for request <%2>. BMC Remedy Link finished processing requests <%1>.
The Integration Engine service did not receive data from the AR System server for the indicated request. Indicates that the Integration Engine service completed a data exchange at the indicated time.
3323
100
Log messages

BMC Remedy Link does not have a license, and cannot be run. Session <%1> statistics: AR System requests: <%2>, Vendor requests: <%3>.
Description Indicates that the Integration Engine service does not have a license. Indicates the following statistics:
<%1> Name of the session ID tag from the EIE:DataExchange form. <%2> Number of AR System keys processed. <%3> Number of external data store keys processed.
3325
3326
Session <%1> statistics: Requests added: <%2>, updated: <%3>, errors: <%4>, warnings: <%5>.
Indicates the following statistics:

<%1> Name of the session ID tag from the EIE:FieldMapping form. <%2> Number of requests added. <%3> Number of requests updated. <%4> Number of requests ignored due to an error. <%5> Number of requests updated and added, but some fields were ignored due to an error.
3327
Session <%1>: Request <%2> error: record ignored due to error. Session <%1>: Request <%2> warning: one or more fields not processed. Adapter <%1>: Cannot find adapter file at<%2>. Adapter <%1>: Failed to load adapter <%2>. Adapter <%1>: GetProcAddress() failed. Adapter <%1>: Failed to initialize adapter: <%2>. Adapter <%1>: Failed to create adapter object: <%2>. Adapter <%1>: Failed to terminate the adapter: <%2>. Adapter <%1>: Failed to open connection to data source: <%2>.
The record was not exchanged for the named session ID tag and the named data key. Verify that the session ID tag and the data key are correct in the field mapping. The fields were not processed for the named session ID tag and the named data key. Verify that the session ID tag and the data key are correct in the field mapping. Adapter is not present at mentioned path. Please check adapter installation directory. Adapter library failed to load. Please check dependencies. Unable to get function address in adapter library. Failed to initialize adapter object. Please check external data store configuration parameters. Failed to allocate memory for adapter object. Failure during adapter close connection and release resources. Failure during adapter open connection with data store.
3328
3329
3330 3331 3332
3333
3334
3336
Chapter 6
101

There is another Atrium Integration Engine process running on this machine, engine exit. Active event request without a configured data exchange. Data exchange: <%1>. %s adapter cannot obtain a license as the maximum number of exchange for a Demo license has exceeded. Data exchanges using that adapter cannot run.
Description Another Integration Engine process is running on this machine, engine exit. The data exchange is activated with improper configuration. Adapter cannot obtain a license as the maximum number of exchanges for a Demo license has exceeded.
3339
3340
Debug messages
Debug messages help you detect errors and events in the data exchange process. Integration Engine generates two types of debug files:
<instance_name>_eiemain.dbg
The eiemain.dbg file is a special, high-level debug file that records details and problems with Integration Engine service. It does not record events that occur for individual data exchanges.
<exchange_name>.dbg
After each data exchange starts, the Integration Engine service creates a unique debug file for it. Debug files created to record debug events for individual data exchanges follow this naming convention: <exchange_name>.dbg.
Using the <instance name>_eiemain.dbg debug file

When you start the Integration Engine service, you have the option of running it with debugging enabled or not, depending on whether you specify the debug startup parameters on the command line. If you specify the debug startup parameters, the Integration Engine service creates the <instance name>_eiemain.dbg file on startup. If the <instance name>_eiemain.dbg file is not created, useful diagnostic information about the initialization errors is not recorded.
102
Debug messages
In addition to startup information, the <instance name>_eiemain.dbg file records high-level information about data exchanges found, licenses issued, licenses absent, and event requests. You should consult <instance name>_eiemain.dbg if your data exchange fails to start and no <exchange_name>.dbg file is created, or if an event request fails to run.
NOTE
Only one <instance name>_eiemain.dbg debug file is created regardless of how many data exchanges are configured. The following text is an example of <instance name>_eiemain.dbg:
Starting to look for changes to data exchange definitions Service has detected 1 active data exchanges on AR System Location of 'FlatFile' adapter obtained License granded to FlatFile. Adapter Version: 7.1.00 Thread started to manage exchange: SamplePullExchange_2 Starting threads to manage event driven requests Immediate async thread started. Event Request cleanup thread started. Waiting for 5 minutes to look for changes to data exchange definitions.
Using an <exchange_name>.dbg debug file

For detailed information about the problems that occur in specific data exchanges, you should enable the log of debug events in eie.cfg. If you enable the logging of debug events, when a data exchange starts, the Integration Engine service creates a unique debug file for it, assigning it the name of the data exchange. For example, if the data exchange is named GetDiskDetail, the debug file will have the name GetDiskDetail.dbg.
NOTE
If you configure multiple concurrent data exchanges on the Main tab of the EIE:DataExchange, the Integration Engine service debug files are assigned the name of the data exchange with a sequence number appended to it. Using the example in the previous paragraph, if two concurrent data exchanges are configured, the debug file names are getdiskdetail_1.dbg and getdiskdetail_2.dbg. Each data exchange debug file provides a list of all rules entered in the Data Exchange application in the order that they are entered on the respective Mapping Information window for AR System forms, CI classes, or relationship classes. The debug file also indicates on which tabs of the forms these rules are entered.
NOTE
EIE:DataMapping, EIE:CMDBDataMapping, and EIE:CMDBRelMapping are backend forms used to store information. You cannot interact directly with these forms.
Chapter 6
103
Each data exchange debug file records events as they take place when a data exchange is run. Events recorded are: Data retrieved Any values generated by rule syntax Data conversions performed Data updated, created, or deleted Errors or warnings
Initialization phase
During the initialization phase, the Integration Engine debug facilities record all data exchange and data handling rules.
StartDataHandlers: Connection established to both AR/CMDB and vendor >>>ARS Form Fields: Field mappings in: 'FlatFileSamplePull' Rule 1: <First Name (id: 536870914)> Set to data type: 4 (Character) Rule 2: <Salary (id: 536870916)> Set to data type: 3 (Real) Rule 3: <Gender (id: 536870917)> Set to data type: 6 (Enum) >>>ARS Form Key Fields: Key Rule 1: <Last Name (id: 536870913)> Set to data type: 4 (Character) >>>ARS System Query: No query defined. All entries will be processed. >>>Vendor Rules: Field mappings in: 'FlatFileSamplePull' Rule 1: <FNAME> Set to data type: 4 (Character) Rule 2: <SALARY> Set to data type: 3 (Real) Rule 3: <GENDER> Set to data type: 2 (Integer) >>>Vendor Keys: Key Rule 1: <LNAME> Set to data type: 4 (Character) >>>Vendor Query: No query defined: All entries will be processed. StopDataHandlers: Disconnected from both AR/CMDB and Vendor applications
Processing phase
During the processing phase, the debug file shows all rules retrieved from the Data Exchange application and the page of the respective Mapping Information window for AR System forms, CI classes, or relationship classes from which it was retrieved, and the data type of the data defined by the rule.
104
Debug messages
The debug file identifies the success or failure of the data transfer. If any Integration Engine service or AR System errors occur, the Integration Engine service debug file shows a detailed error message.
Start comparing list of records on Mon Jul 02 16:29:21 2007 SessionID=SamplePullExchange direction=VendorDataIntoAR updateType=Both New and Changed AR System Data Server Data obtained from Source for mappings: 'FlatFileSamplePull' Rule 1: 'FNAME', Value: 'Mary' Rule 2: 'SALARY', Value: '135' Rule 3: 'GENDER', Value: '1' Key Rule 1: 'LNAME', Value: 'Poulos' Setting field values of Target for mappings 'FlatFileSamplePull' Rule 1: <First Name (id: 536870914)> set to 'Mary' Rule 2: <Salary (id: 536870916)> set to '135' Rule 3: <Gender (id: 536870917)> set to '1' Key Rule 1: <Last Name (id: 536870913)> set to 'Poulos' Adding entry Poulos to form 'EIE:FlatFileSample' Data obtained from Source for mappings: 'FlatFileSamplePull' Rule 1: 'FNAME', Value: 'Tom' Rule 2: 'SALARY', Value: '234' Rule 3: 'GENDER', Value: '0' Key Rule 1: 'LNAME', Value: 'Smith' Setting field values of Target for mappings 'FlatFileSamplePull' Rule 1: <First Name (id: 536870914)> set to 'Tom' Rule 2: <Salary (id: 536870916)> set to '234' Rule 3: <Gender (id: 536870917)> set to '0' Key Rule 1: <Last Name (id: 536870913)> set to 'Smith' Adding entry Smith to form 'EIE:FlatFileSample'
Final Statistics
The Integration Engine service debug file also lists statistics. When a data exchange starts, the <exchange_name>.dbg file records the number of records obtained from each data store. When a data exchange stops, the <exchange_name>.dbg file shows statistics of the number of records actually transferred. For each data exchange, only the statistics for the main mapping are recorded in the debug file. Statistics for other data mappings are not recorded.
Number of AR System Keys obtained 0. Number of Vendor Keys obtained 0. Session statistics: AR requests: 0, Vendor requests: 5 Session statistics: Requests added: 5, updated: 0, deleted: 0, errors: 0, warning Sleep until next poll interval or scheduled time for data transfer StopDataHandlers: Disconnected from both AR/CMDB and Vendor application.
Chapter 6
105
Debug logging settings

From the Data Exchanges Information window, you can now log various levels of debug information.
To enable debug logging

1 On the Data Exchanges Information window, click the Advance Settings tab.
The Debug Settings window appears.

Figure 6-1: Debug Settings window--Advance Settings tab
2 In the Enable Debug Logging field, click Yes. 3 In the Debug File Path, browse to select the location of the debug files.
If the Debug File Path field is blank and you have clicked Yes to enable debug logging, then the log is written to the default debug path you specified during installation of Integration Engine.
4 In the Debug File Creation area, do one of the following:
Click Create Backup to create new log files and write the contents of the previous log files to the <DataExchangeName>_<TimeStamp>.bak file. Click Append To Existing to preserve the log files and their contents. New information is appended to the existing file or is wrapped to the top of the file.
5 In the Max Debug Size field, type the maximum size (in bytes) for the log file.
NOTE
The log file size cannot be set to less than 4096 because that could be the length of a single log line. When the log file reaches the maximum limit, depending upon the Log-File Creation settings either the backup file is created or the new information wraps to the top of the file, overwriting the old information.
106
Debug logging settings 6 In the Enable Thread Based Logging field, click Yes to create thread-based log files.
The name of the log file would be formatted as follows: <DataExchangeName>_T<ThreadNumber>.dbg.

7 In the Debug Level area, select any of the the check boxes to do the following:
API CallsLogs information about all API calls made by Integration Engine. Information is logged on entry and exit of every API call. SQL StatementsLogs SQL commands sent to the database. Information is logged for each SQL command issued, including a time stamp. Record SummaryLogs summary information for each record. Summary information includes whether the record is getting added, updated, or deleted and then if it was successfully added, updated, or deleted. Record DetailsLogs detailed level information for each record. Details are provided at the field level. Information can include the value for each Source field, how it is getting converted to the Destination field after applying any rules, and whether the record is getting successfully added, updated, or deleted.
8 Click Apply To All Exchanges.
The Debug settings are applied to all other Exchanges which are in the Active state.
9 Click Save.
Chapter 6
107
108
Chapter

Troubleshooting information can help you diagnose problems that you might encounter when running the Integration Engine service and configuring data exchanges and data mappings. The following topics are provided: Running the Integration Engine service (page 110) Troubleshooting data exchanges (page 111) Export exchange and mapping configuration (page 112) Handling data types (page 114) Using date functions in AR System Date/Time fields (page 114) Using character string comparisons (page 115) Determining if a record has an out-of-range error (page 115) Stopping the AR System server accidentally when stopping the Integration Engine service on UNIX (page 115) Adding missing items in the AR System field drop-down lists (page 116)
Chapter 7
109
Running the Integration Engine service

The first time you run the Integration Engine service, it might fail if it is not configured correctly. Ask yourself the following questions: Did you set the data exchange to run in debug mode so that it would generate a debug file? Was the debug file created? If not, did you disable debugging by selecting No for the Enable Debug Logging option on the Advance Settings tab of the Data Exchange Information window? Did you license Integration Engine? If you have a license for Enterprise Integration Engine or BMC Atrium Integration Engine, then all other adapter license checks are bypassed. But if either of these licenses are not present, then the Integration Engine service will check for an adapter-specific license (RLS and RLO) and will work accordingly. Did you enter the correct external data store connection information? Did you enter the correct AR System user name and password? Do you have enough memory? For information about estimating memory usage, see the next section, Estimating memory usage when running a data exchange on page 110. Are your field mappings correct?
TIP
Please verify that Data Exchange can be used to validate the data exchange configuration and field mappings, before you execute exchange. Are 8-bit characters used in the external data store user name and password? You must use only 8-bit characters in English strings.
Estimating memory usage when running a data exchange

Before you activate your data exchange, make sure your system has adequate memory. These formulas are guidelines only.
To estimate memory if transferring records for the first time

Number of data keys per exchange * 1.2 KB * Number of records in vendor data
For example, you have three data keys in your exchange and 10,000 records in your external data store: 3 * 1.2 KB * 10,000 = 36000 KB or 36 MB
110
Troubleshooting data exchanges
To estimate memory if updating records

Number of data keys per exchange * 1.2 KB * Number of records in vendor data + Number of records in AR target form
For example, you have three data keys in your exchange, 10,000 records in your external data store, and 11,000 records in your AR System target form: (3 x 1.2 KB * 10,000) + (1.2 KB * 11,000) = 49200 KB or 49.2 MB
Troubleshooting data exchanges

If your data exchange does not run, or you receive error messages, ask yourself the following questions: Are data field sizes large enough to accommodate the data? For example, in Integration Engine, if a field is created to hold the contents of a functional location number, such as 0001-001-AA-01, the size of that field must be at least the size of the largest possible value. Are default values set for required, unused, and Integration Engine core fields? Are you using the correct data key, which is specified on the Primary Key Mapping tab of the respective mapping console for AR, CMDB and Relationship data exchange? EIE:DataMapping and EIE:CMDBDataMapping are backend forms used to store data. You must use EIE:MappingInfo where the Primary Key tab can be referred. Did you make sure that the fields you selected on the Options tab of the of the respective mapping console for AR, CMDB and Relationship data exchange are being added to your AR System data forms as expected? When you select Yes for the fields on the Options tab, some fields on this page generate a drop-down list. Have you accidentally selected any <system generated > numbered fields for your data mappings? When set to Yes, the following options on the corresponding console forms for AR generate a numbered field when you select <system generated> from the drop-down list: Maintain Change History for Fields Update Record Only if Checksum for Mapped Field Has Changed
NOTE
Chapter 7
111
Export exchange and mapping configuration

You no longer need to back up your data for exchange and manually map to find the root cause of an issue. You can now export the configuration into a text (.arx) file which contains data from the following forms: EIE:ApplicationPending EIE:ApplicationSettings EIE:BackUpLoadFlag EIE:CMDBDataMapping EIE:CMDBRelationshipData EIE:CMDBRelMapping EIE:Data EIE:DataExchange EIE:DataExgLookup EIE:DataMapping EIE:RelContainerHolder EIE:Trigger_DE EIE:VendorParamLookup EIE:VendorConfiguration
112
Export exchange and mapping configuration
To export exchange and mapping configuration

1 On the Integration Engine console, click the Integration Objects drop-down menu
and select Data Exchanges.
A new menu item, AIE, appears on the menu bar.
NOTE
The AIE menu is not available for the other integration objects consoles: CI Class Mappings, Relationship Class Mappings, and AR System Form Mappings.
Figure 7-1: Export Configuration menu item
2 Choose AIE > Export Configuration.
The Export Configuration Utility window appears.

Figure 7-2: Export Configuration Utility window
3 In the Output Directory field, type the valid directory path. For example, D:\. 4 Click Export.
AIE_Configuration.arx AIE_Configuration.arx
is created in the directory path you specified. contains configuration information of all data exchanges
as well as mappings.
Chapter 7
113
Handling data types

Decimal values brought into an integer field lose their decimal positions. To round a value, use the round() function. In this case, if the decimal value is 5.5 to 5.9, it is rounded to an integer value of 6. If it is 5.4 or less, it is rounded to an integer value of 5. The AR System Date/Time field holds dates from 1/1/1970 to mm/dd/2036. If you are using an AR System Date/Time field for date values exchanged with the data store, you must use an AR System Character field. The string value can be any of the AR System supported date formats. When the Integration Engine service encounters a date type field with a string value, it attempts to treat it as an AR System date. If it is a valid AR System date, the date transfers correctly. To make sure that dates transfer correctly, see the date format information in Table 7-1.
Table 7-1: Date formats Date Within AR System Date Limits? Yes No Allowed Date Formats Required AR System Field Type Char only
Any of the AR System date formats Date/Time or Char mm/dd/yyyy, dd.mm.yyyy, and yyyymmdd
Using date functions in AR System Date/Time fields

When date information is mapped to an AR System Date/Time field, the AR System attempts to convert the date information into an AR System Date/ Time value, which includes both the date and the time. Some Integration Engine functions return partial date information. To return a date only, use the following function:
currentdate()
returns mm/dd/yy returns hh:mm:ss
To return the time only, use the following function:

currenttime()
You can also use Date/Time fields in an update query to compare attributes in the external data store and AR System or CI classes as dates rather than as internal values.
114
Using character string comparisons
For example, suppose you had an attribute in your external data store called DATETIME and an attribute in a CI class called DateTime. If you define the update query in a CI class data mapping as g, then Integration Engine replaces the DATETIME attribute with a value and passes the query to the target to qualify the update operation on a record-by-record basis. In this case, any record that satisfies the qualifer will be updated in the target.
Using character string comparisons

In some cases, when character string comparisons are run, a external data store might add zeroes to a character field. If this occurs, the Integration Engine service assumes that 0000000011 is 11. When an external character field that pads numbers is used as a key field, the AR System cannot locate it. In other words, AR System searches for 11, which does not match the 0000000011 in the external data store. In this case, you must not map a character field in the external data store as a number field in the AR System.
Determining if a record has an out-of-range error

The AR System server workflow allows you to put a range limit on certain fields. Integration Engine cannot transfer a particular record when one of the mapped fields contains an out-of-range error. For example, if the value in the source for an enumerated field is out of range, the entire record fails during the transfer. Integration Engine cannot transfer the data for the other fields and ignores the enumerated field because an enumerated field always has a default choice (unknown to Integration Engine), and it cannot be left empty.
Stopping the AR System server accidentally when stopping the Integration Engine service on UNIX
If you use the same terminal window to start the AR System server as you do to start and stop the Integration Engine service, the AR System server is stopped, and the system displays the following error message when you enter the command (Ctrl+C) to stop the Integration Engine service:
390600: Another copy of the server is already running on the same RPC socket 390600: AR System server terminated -- fatal error encountered
Chapter 7
115
There are two solutions: Use different terminal windows to start the AR System server and Integration Engine service. Start and run the Integration Engine service in the background by typing:
./eie001start <parameters>
Then, when you want to stop the Integration Engine service, type:
./eie001stop
NOTE
./eie001 is
a script associated with a particular instance.
Adding missing items in the AR System field drop-down lists

By design, temporary fields and names with symbols that affect the data exchange process do not appear in the menu lists for AR System fields. However, you can remove some of these restrictions.
NOTE
Integration Engine should not map or populate these fields. They can, however, be mapped to populate other fields not related to Integration Engine.
Table 7-2: Drop-down list restrictions Restriction
(NOT ( 'Field Name' LIKE "zTmp%" ))
Description Integration Engine has a naming convention for temporary fields that are used for workflow processing. Fields starting with zTmp are considered working variables on the form and should not be used in a data mapping because their content is not fixed. If you do not follow this convention, you might need to remove this restriction to expose fields that are needed in a field mapping. One of the rules allowed in a data mapping is a precedence rule. Precedence rules use curly brackets ({}) to delimit a single rule in a precedence sequence. This restriction prevents fields with brackets from appearing in the dropdown list.
(NOT ( 'Field Name' LIKE "%}%" ))
116
Adding missing items in the AR System field drop-down lists
Table 7-2: Drop-down list restrictions Restriction

(NOT ( 'Field Name' LIKE "%|%" ))
Description Several rules used in a data mapping use the syntax <category>|<value>. The category represents the category of a rule (such as function or constant). The pipe terminates the category and starts the actual value that is supplied by the rule. This restriction prevents any fields with the pipe from appearing in the drop-down list. If this restriction is removed, the field name preceding the pipe must not be a keyword. Field names cannot have embedded commas. This restriction prevents any fields with commas from appearing in the drop-down list. If this restriction is removed, a field name with a comma cannot be used in a function. However, a field name with a comma can be used in other rule formats.
(NOT ( 'Field Name' LIKE "%,%" ))
Chapter 7
117
118
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Index
Symbols
# parameter 90 $field$ option for AR System query syntax 56
B
Best Practice icon 10 BMC Atrium Integration Engine installation overview 26 introduction to 16 BMC Software, contacting 2
A
Adapter Development Kit interface 19 adapter licenses 19 adapter rule helper utility DB2 60 file 69 Oracle 62 SQL 64 using 59 XML 69 adding restricted items in AR System field drop-down lists 116 AR System adding missing items to field menus 116 adding restricted drop-down list items 116 API documentation 19 date formats 114 date functions 114 query syntax 5557 range limits on fields 115 removing menu restrictions 116 stopping server when stopping Integration Engine service 115 ARLogin parameter 90 ARPassword parameter 90 ARServerName parameter 90 AsyncInterval parameter 90 audience for this book 9
C
character string comparisons 115 command-line parameter 86 ConfigInterval parameter 91 ConfigPassCount parameter 91 configuration file editing 92 location 89 parameters 90 sample file 89 constant syntax 46, 47 customer support 3
D
Data Exchange application 18 data exchange debug files overview 102 statistics 105 timestamp 92 data exchange definitions importing and exporting 112 data exchanges definitions 18 memory usage, estimating 110 running on UNIX 87 data key queries 5759 data mappings defining queries 5559 data transfer, direction of 16 data types, handling 114 date formats 114
Index
119
date functions in AR System 114 debugging data exchange debug files overview 102 statistics 105 timestamp 92 Integration Engine service debug file (eiemain.dbg) disabling 91 enabling 91 overview 102 parameters 91 timestamp 92 using 102103 maximum debug file size 91 DebugOn parameter 91 decimal values in integer fields 114 defining queries 5559 rules 4654 direction of data transfer 16 disabling debugging 91 logging 91 drop-down list items, adding restricted AR System fields 116 Event Request interface activating requests through workflow 83 definition of 19 invoking requests through eiexfer 7883 exporting data exchange definitions 112
F
field option for data key query syntax 57 formats for dates 114 function syntax AR System queries 57 rules 46, 4852
H
handling data types 114 help, installing on Windows 39
I
icons Best Practice 10 New 10 importing data exchange definitions 112 initialization phase 104 overview 20 installation log error 116 installing criteria for installing components 26 installation prerequisites for UNIX 28 for Windows 28 Windows online help system 39 integer fields 114 Integration Engine service 18 command-line parameter 86 debug file (eiemain.dbg) disabling 91 enabling 91 overview 102 parameters 91 timestamp 92 using 102103 rule syntax 4654 running on UNIX from a command line 87 stopping without disrupting AR System server 115
E
eie.cfg file editing 92 location 89 parameters 90 sample file 89 eiemain.dbg file overview 102 parameters 91 timestamp 92 using 102103 eiexfer utility command syntax examples 80 completion code messages 81 completion codes returned by 81 definition of 19 enabling debugging 91 logging 91 error messages of log files 99
120
K
KEY syntax for data key queries 58 KEYLIST syntax for data key queries 5859
L
licenses adapter 19 log files disabling 91 enabling 91 maximum size 91 log messages, overview 98 logging parameter 91, 98
parameters (continued) eie.cfg TimeStampDebug 92 populating SQL field information 66 precedence syntax 46, 47, 54 prerequisites for installing BMC Atrium Integration Engine on UNIX 28 on Windows 28 process command syntax 46, 53 processing phase 21, 104 product support 3
Q
queries, defining 5559 query syntax AR System syntax $field$ option 56 function syntax 57 syntax statement 55 value option 56 data key syntax field option 57 KEY syntax 58 KEYLIST syntax 5859 value option 58 row-level syntax SRC syntax 59
M
MaxDebugSize parameter 91 maximum file size debug 91 log 91 MaxLogSize parameter 91
N
New icon 10
O
out-of-range error 115
R
range limits on fields 115 records not transferred during exchange 115 row-level queries 59 rule helper utility DB2 60 file 69 Oracle 62 SQL 64 using 59 XML 69 rules constant syntax 46, 47 defining 4654 function syntax 46, 4852 precedence syntax 46, 47, 54 process command syntax 46, 53 SQL command syntax 46, 52 stmt command syntax 54 target process command syntax 46, 54 Index 121
P
parameters command line 86 debug file 91 debug timestamp 92 eie.cfg # (pound sign) 90 ARLogin 90 ARPassword 90 ARServerName 90 AsyncInterval 90 ConfigInterval 91 ConfigPassCount 91 DebugOn 91 logging 91, 98 MaxDebugSize 91 MaxLogSize 91 StackTrace 92
rules (continued) target SQL command syntax 46, 53 vendor rules 46 running the Integration service on UNIX from a command line 87
S
security 92 source syntax 59 SQL command syntax 46, 52 SQL field information, populating 66 SRC syntax for row-level queries 59 StackTrace parameter 92 stmt command syntax 54 support, customer 3 syntax ($KEYLIST$) 58 syntax statement for AR System queries 55
T
target process command syntax 46, 54 target SQL command syntax 46, 53 technical support 3 timestamp parameters for debug files 92 TimeStampDebug parameter 92
U
UNIX installation prerequisites 28 running the Integration Engine service from a command line 87 untransferred records 115 utilities adapter rule helper 59
V
value option AR System query syntax 56 data key query syntax 58 vendor rules 46
W
Windows installation prerequisites 28 installing online help system 39
122
*69247* *69247* *69247* *69247*

*69247*

Administrator's Guide: BMC Atrium Integration Engine 7.1.00

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Administrator's Guide: BMC Atrium Integration Engine 7.1.00

Uploaded by

Copyright:

Available Formats

BMC Atrium Integration Engine 7.1.

Contacting BMC Software

United States and Canada

Outside United States and Canada

Restricted Rights Legend

Support by telephone or email

Before Contacting BMC Software

Defining rules and queries

Troubleshooting Integration Engine

BMC Atrium Integration Engine 7.1.00

Best Practice and New icons

Integration Engine documents

Users and Product Administrators Help

Everyone Everyone Users

Print and PDF Print and PDF Print and PDF

BMC Atrium CMDB documents

Print and PDF

Print and PDF

Print and PDF

Spreadsheet, print and PDF

Print and PDF Product Help

Print and PDF

BMC Atrium Integration Engine 7.1.00

Title BMC Atrium CMDB 2.1.00 Troubleshooting Guide

BMC Atrium CMDB 2.1.00 Users Guide

PDF and Print PDF and Print PDF and Print

PDF and Print PDF and Print PDF and Print

PDF and Print

Format PDF and Print

PDF and Print

PDF and Print

Administrators PDF and and Programmers Print

BMC Atrium Integration Engine 7.1.00

Understanding Integration Engine

Understanding Integration Engine

BMC Atrium Integration Engine 7.1.00

BMC Atrium Integration Engine

Integration Engine components

Integration Engine components

AR System database or BMC Atrium CMDB

Data Exchange application Application Pending form

Integration Engine service

Event Request interface (eiexfer)

Adapter Development Kit interface

Flat File adapter

Other Other Other data store data store data store

Custom adapters (not included)

Understanding Integration Engine

BMC Atrium Integration Engine 7.1.00

Data Exchange application

Integration Engine service

The data transfer process

Event Request interface

Adapter Development Kit interface

The data transfer process

Understanding Integration Engine

BMC Atrium Integration Engine 7.1.00

The initialization phase

The data transfer process

The processing phase

Understanding Integration Engine

BMC Atrium Integration Engine 7.1.00