bmc atrium integration engine 7.6.04 users guide

www.bmc.com

BMC Atrium Integration Engine 7.6.04

User’s Guide

January 2011

If you have comments or suggestions about this documentation, contact Information Design and Development by email at [email protected].

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

© Copyright 2009-2011 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, DB2 Universal Database and IBM are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both.

IT Infrastructure Library® is a registered trademark of the Office of Government Commerce and is used here by BMC Software, Inc., under license from and with the permission of OGC.

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, and is used here by BMC Software, Inc., under license from and with the permission of OGC.

Linux is the registered trademark of Linus Torvalds in the U.S. and other countries.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

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

http://www.bmc.com

mailto:[email protected]

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. 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 [email protected]. (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

http://www.bmc.com/support


License key and password information

If you have a question about your license key or password, contact Customer Support through one of the following methods:

■ E-mail [email protected]. (In the Subject line, enter SupID:yourSupportContractID, such as SupID:12345.)

■ In the United States and Canada, call 800 537 1813. Outside the United States and Canada, contact your local support center for assistance.

■ Submit a new issue at http://www.bmc.com/support.



Contents

BMC Atrium Core documentation 11

Chapter 1 Understanding BMC Atrium Integration Engine 15

Overview of BMC Atrium Integration Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Calbro Services user story in BMC Atrium Integration Engine documents . . . . . . . . 17

Roles used in the Calbro Services user story . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17BMC Atrium Integration Engine components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Data Exchange application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18AIE service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Event Request interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Adapter Development Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Data transfer process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Initialization phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Processing phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Performance considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Using multiple data exchanges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Roles and permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26BMC Atrium Integration Engine in a server group environment . . . . . . . . . . . . . . . . 28

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28How BMC Atrium Integration Engine works in a server group . . . . . . . . . . . . . . 29Debug files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Accessing the Data Exchange Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Accessing the BMC Atrium Integration Engine monitoring console. . . . . . . . . . . . . . 34

Information displayed in the monitoring console . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Chapter 2 Populating database field menus 39

Using the adapter rule helper utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Using the DB2 Adapter Rule Helper utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Populating DB2 UDB field information using the Database Field Menus Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Populating DB2 UDB field information for external data tables using a command line. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Using the DB2 UDB adapter rule helper utility on UNIX platforms. . . . . . . . . . . 43

Using the Oracle Adapter Rule Helper utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Populating Oracle field information using the Database Field Menus Console . 44

5

Populating Oracle field information for external data tables using a command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Using the Oracle adapter rule helper utility on UNIX platforms . . . . . . . . . . . . . . 47Using the SQL Server Adapter Rule Helper utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Populating SQL Server field information for multiple external data tables . . . . . 48Populating SQL Server field information for multiple external data tables using a Windows based application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Populating SQL Server field information for BMC Atrium Integration Engine on Windows and BMC Remedy AR System on UNIX. . . . . . . . . . . . . . . . . . . . . . . 52

Using the XML Adapter Rule Helper utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Using the File Adapter Rule Helper utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Chapter 3 Creating data mappings for BMC Atrium CMDB CI classes 53

Example CMDB data scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Before creating data mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Overview of the data mapping process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Defining data mapping parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Accessing parent record elements along with child record elements from an XML file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Defining the primary key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Defining data field mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Setting response fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Defining delete field mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Defining queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Defining a data key query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Defining an update query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Defining a response query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Defining a delete query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Setting data mapping options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Chapter 4 Creating data mappings for BMC Atrium CMDB relationship classes 83

Overview of the relationship data mapping process . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Methods for mapping relationship classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Attributes in the member CI classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Data in an external data store. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

High-level steps in the relationship data mapping process . . . . . . . . . . . . . . . . . . . . . . 89Defining data mapping parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Defining relationship keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Defining attribute field mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Defining delete field mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Defining queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Defining a primary class query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Defining a secondary class query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Defining a relationship class query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Defining an external data store query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Setting data mapping options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

6 User’s Guide

Chapter 5 Creating data mappings for BMC Remedy AR System forms 109

Overview of the data mapping process for BMC Remedy AR System forms . . . . . 110Defining data mapping parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Defining the primary key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Defining data field mappings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Setting response fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Defining delete field mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Defining queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Defining a data key query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Defining an update query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Defining a response query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Defining a delete query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Setting data mapping options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Populating the rule control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Chapter 6 Data exchanges 135

Using data exchanges with BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Overview of creating a data exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Defining data exchange parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Assigning data mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Managing execution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Defining connection settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Supported data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150Defining connection settings for DB2 UDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Defining connection settings for flat files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152Defining connection settings for Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Defining connection settings for SQL Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Defining connection settings for XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159RPC ports in BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Using advanced settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Activating a data exchange. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Verifying a data exchange configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Running a data exchange on demand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Managing connection parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Managing DB2 UDB connection parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Managing Oracle connection parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Managing SQL Server connection parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Using the AIE:VendorConfiguration form to specify connection settings . . . . . 173

Failover support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174Failover support for data exchanges transferring data into CI classes and BMC Remedy AR System forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174Failover support for relationship data exchanges . . . . . . . . . . . . . . . . . . . . . . . . . 175

Error handling in BMC Atrium Integration Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Logging errors in the .csv file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Exporting and importing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Exporting data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Importing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Enhanced retrieve delta feature for relationship exchanges . . . . . . . . . . . . . . . . . . . . 183Sample data exchanges for BMC Remedy ITSM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

7

Chapter 7 Activating event-driven data exchanges 187

Creating a request on the Application Pending form . . . . . . . . . . . . . . . . . . . . . . . . . . 188Creating a request using the aiexfer utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Examples of the event-driven request command syntax . . . . . . . . . . . . . . . . . . . . 194Completion codes returned by aiexfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Activating an event-driven data exchange through workflow . . . . . . . . . . . . . . . . . . 197

Appendix A Defining rules and queries 199

Defining rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200Constant syntax (constant|string) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Precedence syntax ({rule} {rule} {rule}) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202Function syntax (function|function(parameters)) . . . . . . . . . . . . . . . . . . . . . . . . . . . 202SQL command syntax (sql|command). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207Target SQL command syntax (targetsql|command) . . . . . . . . . . . . . . . . . . . . . . . . 207Process command syntax (process|command) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208Target process command syntax (targetprocess|command) . . . . . . . . . . . . . . . . . 208If/then/else syntax (STMT|statement) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Defining queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211BMC Remedy AR System query syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Data key syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Row-level query syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Appendix B Running and configuring the AIE service 217

Running the AIE service on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Running the AIE service on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219Loading the adapters for Oracle or DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220Understanding the configuration file and its parameters . . . . . . . . . . . . . . . . . . . . . . 221

Sample configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223Editing the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226BMC Atrium Core debug files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

Managing instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Adding an instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229Deleting an instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231Starting an instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232Stopping an instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Using command line to manage instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234Modifying the instance details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Viewing the status of an instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Changing BMC Remedy AR System password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Appendix C CSV Syntax supported by BMC Atrium Integration Engine 241

Format of .csv files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242Examples of how BMC Atrium Integration Engine interprets .csv files . . . . . . . . . . 243

8 User’s Guide

Glossary 245

Index 255

9

10 User’s Guide

BMC Atrium Core documentation

This section describes the complete set of BMC Atrium Core documentation, including manuals, help systems, videos, and so on.

Unless otherwise noted, documentation is available free of charge on the BMC Atrium Core documentation media (DVD or Electronic Product Download bundle) and on the BMC Customer Support site, at http://www.bmc.com/support.

To find this documentation on the BMC Customer Support site, choose Product Documentation > Supported Product A-Z List > BMC Atrium CMDB Enterprise Manager >7.6.04

Title Description Audience

Atrium Integrator 7.6.04 User's Guide

Information about defining source and target connections, creating jobs and transformations, editing and monitoring jobs, and other Atrium Integrator concepts.

Users who are responsible for setting up data transfer integrations between external data stores and BMC Atrium CMDB.

BMC Atrium CMDB 7.6.04 Administrator's Guide

Information about setting permissions, configuring federation, modifying the data model, configuring an impact model, and other administrative tasks in BMC Atrium Configuration Management Database (BMC Atrium CMDB).

Configuration managers, application administrators, and asset analysts.

BMC Atrium CMDB 7.6.04 Common Data Model Diagram

Hierarchical diagram of all classes in the Common Data Model (CDM), including unique attributes and applicable relationships.


BMC Atrium CMDB 7.6.04 Data Model Help

Description and details of superclasses, subclasses, attributes, and relationship classes for each class. Contains only information about the CDM at first, but you can update it to include information about data model extensions that you install.

Note: This Help is provided in HTML and is available on the BMC Atrium Core media. It is not available on the BMC Customer Support site.


BMC Atrium CMDB 7.6.04 Data Modeling Guide

Best practices for using the classes that BMC provides for BMC Atrium CMDB (both the CDM and extensions) to model complex business entities, focusing on the use of multiple related CIs to model an entity rather than on general information about a class or attribute.





BMC Atrium CMDB 7.6.04 Javadoc Help

Information about Oracle Java classes, methods, and variables that integrate with BMC Atrium CMDB.


Application programmers.

BMC Atrium CMDB 7.6.04 Normalization and Reconciliation Guide

Information about normalizing data in BMC Atrium CMDB and reconciling CIs from different data providers into a single production dataset.


BMC Atrium CMDB 7.6.04 Online Help

Help for using and configuring BMC Atrium CMDB, including Atrium Integrator, BMC Atrium Product Catalog, Reconciliation Engine, Normalization Engine, and so on.

Note: This Help is provided in HTML and is available through the Help links in the BMC Atrium CMDB user interface. It is not available on the BMC Customer Support site.

Configuration managers, application administrators, asset analysts, and users that work with CIs and need to understand the relationships that exist within BMC Atrium CMDB.

BMC Atrium CMDB 7.6.04 User's Guide

Information about using BMC Atrium CMDB, including searching for and comparing CIs and relationships, relating CIs, viewing history, running impact simulations, and viewing federated data.

Users that work with CIs and need to understand the relationships that exist within BMC Atrium CMDB.

BMC Atrium Core: Taking Your Data Into Production End to End

End-to-end high-level steps for bringing data into BMC Atrium CMDB from a third-party source and making it available in your production dataset.

Note: This Flash video is available on the BMC Atrium Core media. It is not available on the BMC Customer Support site.


BMC Atrium Core 7.6.04 Compatibility Matrix

Information about the BMC Atrium Core configurations that are expected to work together based on design, testing, or general understanding of the interaction between products.

Note: Download the BMC Atrium Core 7.6.04 Compatibility Matrix from the BMC Customer Support site at http://www.bmc.com/support/reg/remedy-compatibility-tables.html?c=n.


BMC Atrium Core 7.6.04 Concepts and Planning Guide

Information about CMDB concepts and high-level steps for planning and implementing BMC Atrium Core.

Anyone who wants to learn about and understand BMC Atrium Core products, CMDBs in general, and the functionality of BMC Atrium CMDB in particular.IT leaders, configuration managers, application administrators, and asset analysts are some who will benefit from this information.


12 User’s Guide

http://www.bmc.com/support/reg/remedy-compatibility-tables.html?c=n

http://www.bmc.com/support/reg/remedy-compatibility-tables.html?c=n

BMC Atrium Core 7.6.04 Developer’s Reference Guide

Information about creating API programs using C API functions and data structures.

Application administrators and programmers.

BMC Atrium Core 7.6.04 Installation Guide

Information about installing, upgrading, and uninstalling BMC Atrium Core features.

Application administrators.

BMC Atrium Core 7.6.04 Master Index

Combined index of all guides. Everyone.

BMC Atrium Core 7.6.04 Product Catalog and DML Guide

Information about configuring the Product Catalog and DML, adding products, and creating aliases for products, manufacturers, and categorizations.

System administrators, IT managers, network managers, and other qualified personnel who are familiar with their computing and networking environment.

BMC Atrium Core 7.6.04 Release Notes

Information about new features, known issues, and other late-breaking topics.

Everyone.

BMC Atrium Core 7.6.04 Troubleshooting Guide

Information about resolving issues with BMC Atrium Core components, including API, filter, and console error messages and their solutions.

Application administrators, programmers, and BMC Support personnel.

BMC Atrium Core 7.6.04 Web Services Help

Information about using BMC Atrium Core Web Services, including how to publish and find interfaces in the Web Services Registry, set versions, disambiguate web services, configure security policies and encryption, and use BMC Atrium Core Web Services data structures and operations.


Application administrators and programmers.

BMC Atrium Integration Engine 7.6.04 ADK Developer's Guide

Information about how to build adapters that can transfer information between an external data store and either BMC Remedy AR System forms or BMC Atrium CMDB.

Developers who have a basic understanding of BMC Atrium Integration Engine and want to build adapters that can exchange data between two data sources.

BMC Atrium Integration Engine 7.6.04 Online Help

Help for using and configuring BMC Atrium Integration Engine.

Note: This Help is provided in HTML and is available through the Help links in the BMC Atrium Integration Engine user interface. It is not available on the BMC Customer Support site.

Users who are responsible for setting up data transfer integrations between external data stores and either BMC Atrium CMDB or BMC Remedy AR System.




BMC Atrium Integration Engine 7.6.04 User's Guide

Information about creating data exchanges and data mappings, defining rules and queries, activating event-driven data exchanges, defining connection settings, and other BMC Atrium Integration Engine concepts.

Users who are responsible for setting up data transfer integrations between external data stores and either BMC Atrium CMDB or BMC Remedy AR System.

Mapping Your Data to BMC Atrium CMDB 7.6.04 Classes

Spreadsheet that maps common IT objects to the appropriate class, whether part of the CDM or an extension. This spreadsheet also includes information about further categorizing instances using key attributes, and best practices for creating normalized relationships.



14 User’s Guide

Chapter

1
Understanding BMC Atrium Integration Engine
The BMC Atrium Integration Engine product enables you to transfer data between an external data store and BMC Remedy Action Request System (BMC Remedy AR System) forms or BMC Atrium Configuration Management Database (BMC Atrium CMDB) classes. You can use the included adapters for Microsoft SQL Server, Oracle®, IBM® DB2® Universal Database™, XML, and flat files such as comma-separated value (CSV) files. You can also use the BMC Atrium Integration Engine Adapter Development Kit to build your own adapters to meet your organization’s specific needs.

Atrium Integrator replaces BMC Atrium Integration Engine. You can continue using BMC Atrium Integration Engine for existing data mappings and exchanges, but BMC recommends that you use Atrium Integrator for all new data transfers. BMC Atrium Integration Engine will be deprecated in a future release.

The following topics are provided:

! Overview of BMC Atrium Integration Engine (page 16)! Calbro Services user story in BMC Atrium Integration Engine documents

(page 17)! BMC Atrium Integration Engine components (page 17)! Data transfer process (page 21)! Performance considerations (page 23)! Using multiple data exchanges (page 25)! Roles and permissions (page 26)! BMC Atrium Integration Engine in a server group environment (page 28)! Datasets (page 30)! Getting started (page 32)! Accessing the Data Exchange Console (page 32)! Accessing the BMC Atrium Integration Engine monitoring console (page 34)



Overview of BMC Atrium Integration EngineWith BMC Atrium Integration Engine, you can do scheduled bulk data transfers and event-based integrations initiated by either the source, target, or any other application. You can also use BMC Atrium Integration Engine for initial data load, incremental data transfers, and data synchronization. You can build links between BMC Remedy IT Service Management (BMC Remedy ITSM) applications and Enterprise Resource Planning (ERP), Customer Relationship Management, Supply Chain Management, and other enterprise applications.

For example, you can use BMC Atrium Integration Engine to:

! 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

! 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

Figure 1-1 shows how you can transfer data in either direction between an external data store and a BMC Remedy AR System application or BMC Atrium CMDB class.

Figure 1-1: Overview of the data transfer process

During the data transfer, BMC Atrium 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

Dataobject

Externaldata store

BMC Remedy AR Systemdatabase

BMC RemedyAR System

form

BMC AtriumCMDB class

BMC AtriumIntegration

Engine

16 User’s Guide

Calbro Services user story in BMC Atrium Integration Engine documents

Calbro Services user story in BMC Atrium Integration Engine documents

The BMC Atrium Integration Engine documentation set uses a fictional company named Calbro Services to explain how BMC Atrium Integration Engine principles and procedures are used in practice. Although Calbro Services is a fictional company, it is based on research of actual BMC customers. Seeing how Calbro Services completes tasks should prove useful as you implement BMC Atrium Integration Engine in your own environment.

Calbro Services needs to transfer its existing data about processors, disk drives, printers, and so on to their centralized database in New York. This data resides in multiple databases and flat files in various locations around the globe. Calbro Services wants to transfer information from its Chicago, London, Dublin, and Adelaide sites to their New York centralized database. also wants to transfer the personnel records of employees from the Dublin site to the New York site.

This guide provides examples for transferring the data.

Roles used in the Calbro Services user storyAlthough Calbro Services has thousands of employees, those in IT Support are the most likely to use BMC Atrium Integration Engine.

Mary Mann uses BMC Atrium Integration Engine and has permissions to manage, create, and view the data mappings, data exchanges, and connection and configuration parameters. Allen Allbrook has permissions to view the data mappings, data exchanges, and connection and configuration parameters.

BMC Atrium Integration Engine componentsBMC Atrium Integration Engine has the following main components:

! Data Exchange application (page 18)

! AIE service (page 20)

! Event Request interface (page 20)

! Adapter Development Kit (page 20)

Figure 1-2 shows how these components work with other BMC Atrium Integration Engine components and related objects.



Figure 1-2: BMC Atrium Integration Engine components

Data Exchange applicationThe Data Exchange application is a group of BMC Remedy AR System forms that is available from your BMC Remedy AR System home page as the AIE Console link. Use the data exchange application to work with the following integration objects:

! A data exchange is the object that you execute to move data with BMC Atrium 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.

? ? ?Oracle

databaseSQL Server

databaseDB2

database

BMC Remedy AR System database or BMC Atrium CMDB

Adapters provided by BMC Atrium Integration Engine

DB2adapter

Oracleadapter

SQLadapter

XMLfile

XMLadapter

Flatfile

Flat Fileadapter

Custom adapters (not included)

ApplicationPending form

Event Requestinterface (aiexfer)

Data Exchangeapplication

AIEservice

BMC AtriumIntegration

Engine

Otherdata store

Otherdata store

Otherdata store

Adapter DevelopmentKit interface

BMC RemedyAR System

APIs

BMC AtriumCMDBAPIs

18 User’s Guide

BMC Atrium Integration Engine components

! A data mapping defines data to be transferred. It specifies the external file or database table and the BMC Remedy AR System form or BMC Atrium CMDB class between which data is transferred, and it 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. It also 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 options.

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 BMC Atrium 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 BMC Atrium Integration Engine instances that you defined at installation time and edit some settings for them.

! Display version numbers for BMC Atrium Integration Engine and related products.



AIE serviceThe AIE 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 provide access to external data and responds to calls from BMC Atrium Integration Engine during a data exchange.

The AIE service can connect to any BMC Remedy AR System server running on Microsoft Windows or UNIX® operating system. It does not need to reside on the same computer as the BMC Remedy AR System server or the external data stores, but can be on any computer that is network-connected to both of these.

The AIE service runs as a client to the BMC Remedy AR System server using the BMC Remedy AR System application programming interface (API). For information about the BMC Remedy AR System APIs, see the BMC Remedy Action Request System 7.6.04 C API Reference.

Event Request interfaceYou can execute a data exchange on an event-driven basis by using the Event Request interface. Each event-driven request is created as an entry in the Application Pending form in the BMC Remedy AR System where the Data Exchange application is installed. You create an event-driven request by directly creating an Application Pending entry, by using BMC Remedy AR System workflow to create the entry, or by invoking the aiexfer utility.

The AIE service processes requests at a scheduled interval configured in the aie.cfg file, regardless of which method was used to create the requests. Optionally, the AIE service can handle individual event requests immediately if you enter them through the aiexfer utility.

Adapter Development KitBMC Atrium Integration Engine has a special interface that enables it to interact with adapters. The Adapter Development Kit is a software development kit that lets you build your own adapters. The Adapter Development Kit interface defines a set of C++ objects that are used by the AIE service to manage data exchanges that use these adapters. For more information about the Adapter Development Kit, see the BMC Atrium Integration Engine 7.6.04 ADK Developer's Guide.

20 User’s Guide

Data transfer process

Data transfer processWhen you start the AIE service, it locates data exchanges by reading entries in the Data Exchange application. When BMC Atrium Integration Engine detects a data exchange, the AIE service loads the adapter that is associated with that data exchange.

A data transfer has two phases: the initialization phase, in which a data exchange is prepared to run, followed by the processing phase, in which data is transferred.

Initialization phaseThe initialization phase prepares a data exchange to run. The AIE service performs the following tasks:

Step 1 Loads data exchange rules.

The AIE service loads all the rules defined in the Data Exchange application and prepares the C++ objects defined by the Adapter Developer Kit. The rules include the data exchange definition, the data mapping rules, and all adapter-defined configuration parameters and rules.

Step 2 Connects to data stores to validate rules.

The AIE service connects to both the source and target data stores. A BMC Remedy AR System form or BMC Atrium CMDB class can serve as either the source or the target.

The AIE service does not transfer data at this point, but a connection to both data stores is necessary to validate rules.

Step 3 Validates data exchange rules.

The AIE service validates rules owned by BMC Atrium Integration Engine. During validation, the AIE 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.

Step 4 Disconnects from data sources.

After the rules are validated, the AIE service disconnects from both data sources.

Step 5 Starts a thread

At the end of the initialization phase, the AIE service starts a thread to manage the data exchange process.

During this phase, the BMC Atrium Integration Engine debug facilities record all data exchange and data handling rules.



Processing phaseIn the processing phase, the transfer of data takes place. This phase begins when a data exchange is executed, which can be scheduled or event driven.

During the processing phase, the AIE service performs the following tasks:

Step 1 Refreshes the data exchange.

Before data is exchanged, the AIE service checks the Data Exchange application to determine if any changes were made to the data exchange definition. If changes were made, the AIE service updates the loaded data exchange with the new definition.

Step 2 Starts a separate thread for each data exchange

The AIE service connects to both the source and target data stores for each data exchange. The AIE service communicates through the BMC Remedy AR System API or BMC Atrium CMDB API to pull data out of and push data into those data stores. The AIE service uses the adapter to pull data out of and push data into the external data store.

Step 3 Locates data to be exchanged.

The AIE service obtains a list of keys from BMC Remedy AR System or BMC Atrium CMDB and prompts the adapter to create a list of keys. The AIE service converts the keys to a common data type (if necessary) and then sorts the keys into the same order so that it can compare the key lists.

Step 4 Transfers data

The AIE service compares the keys and determines from the data exchange definition how new and existing records should be treated. The AIE 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.

If during data transfer the AIE service or the BMC Remedy AR System server stops responding, BMC Atrium Integration Engine provides failover support for the incomplete data exchanges. The next time the AIE service starts, the data exchanges resume from the point they had stopped, thus avoiding repetition of data insertion.

Step 5 Disconnects from data stores

After all keys are processed, the data transfer is considered complete. The AIE service closes the connection to BMC Remedy AR System or BMC Atrium CMDB and prompts the adapter to close the connection to the external data store.

NOTE The thread and adapter remain active, unless the data exchange is deactivated in the Data Exchange application or the AIE service is terminated. In either of those events, the adapter .dll is released and the thread terminates.

22 User’s Guide

Performance considerations

In this phase, the AIE service debug file shows all rules retrieved from the Data Exchange application and the type of the data defined by the rule. The debug file also identifies the success or failure of the data transfer and shows a detailed error message when any errors occur in the AIE service or in BMC Remedy AR System.

Performance considerationsPerformance considerations for BMC Atrium Integration Engine are difficult to quantify because performance is affected by your network, BMC Remedy AR System, the BMC Remedy AR System server database, and the external data store load. It is difficult to predict the effect of a specific change on BMC Atrium Integration Engine performance, but configuration considerations can influence it.

Although 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 your database contains many records. For example, if you have 1200 records in your database and the change that 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.

However, you can use multiple instances, multiple sessions, and multithreading to increase throughput and improve overall system performance. The use of these performance options is described in Table 1-1.

NOTE Setting multiple instances, multiple sessions, and multithreading are all part of creating a data exchange.

Table 1-1: Performance options (part 1 of 2)

Option Where do I set this option? Usage

Multiple instances Instance Name field on the Main tab of the Data Exchanges Information form

Use multiple instances to split a data exchange when the number of data keys in the transfer might exceed the 2 GB memory limit of BMC Atrium Integration Engine. In this case, you define one data exchange for each instance and use a data key query to split the data keys between the two instances. For more information about creating data key queries, see “Click Save.” on page 74.



Best practices

Following are some best practices to improve the performance of BMC Atrium Integration Engine:

! Transfer data in chunks and use separate AIE service instances to transfer the chunks of data.

! Transfer data in chunks, using separate AIE service instances for the transfers, as described in “Using multiple data exchanges” on page 25.

! Create index entries on:

! BMC_BaseElement class for keys that are used as primary keys

! Relationship keys for relationship data exchanges

! External data stores for exchanges with the External Data to CMDB data direction and for relationship data exchanges

! Provide minimum and maximum values for the Fast Thread and List Thread options in the BMC Remedy AR System Administration Console. For more information about Fast Thread and List Thread and how to specify the number of threads, see the BMC Remedy Action Request System 7.6.04 Configuration Guide.

! Specify the number of threads to be used to run the data exchange. The default is three times the number of CPUs detected on the computer where BMC Atrium Integration Engine is installed. The maximum number of threads that you can specify is 49.

! Create separate disks for storing data and log information.

Multiple sessions Concurrent Session Limit field on the Main tab of the Data Exchanges Information form

Use multiple sessions for event-driven data exchanges if your adapter receives data transfer requests faster than a single session can manage.For example, if you increase the number of concurrent sessions to two and an event-driven request is issued while the first session is already running a data transfer, BMC Atrium Integration Engine will start the second session to process the new request.

Multithreading Number of threads field on the Advance Settings tab of the Data Exchanges Information form

Use multithreading only for high-volume traffic in which a single data exchange session cannot handle the load in a reasonable time frame. The number of threads that you specify is started for each session.At some point, increasing the number of threads reduces performance on your server, and any performance gain from allowing multiple data exchanges is lost.

Table 1-1: Performance options (part 2 of 2)

Option Where do I set this option? Usage

24 User’s Guide

Using multiple data exchanges

Using multiple data exchangesTo improve performance of BMC Atrium Integration Engine, you should use multiple data exchanges to transfer data.

You can separate the data in your source database into logical chunks for transferring it and configure separate data exchanges for each chunk. These data exchanges can then run on their own instances of the AIE service. The following example illustrates the use of multiple data exchanges.

Calbro Services wants to transfer the following records from its Dublin site to the centralized database in New York:

! Computer systems

! Storage devices

! Other components

! Software

Calbro Services creates four separate data exchanges to transfer this data to the New York database. Figure 1-3 shows the data exchanges used for transferring this data.

Figure 1-3: Using multiple data exchanges

DataData

Dublin DatabaseDublin Database

DataData

New York DatabaseNew York Database

ComputerComputersystemssystems

StoragedevicesStoragedevices

Othercomponents

Othercomponents

SoftwareSoftware

Data exchangesData exchangesData exchanges



Roles and permissionsTo give access to BMC Atrium Integration Engine, you must create a BMC Remedy AR System user on the server where BMC Atrium Integration Engine is installed. You can then make that user a member of multiple groups and assign those groups to roles that allow them access to the BMC Atrium Integration Engine application and data.

This section describes how BMC Remedy AR System groups and roles are used in BMC Atrium Integration Engine. For information about creating users and groups, see the BMC Remedy Action Request System 7.6.04 Configuration Guide. For information about working with groups and roles in general, see the BMC Remedy Action Request System 7.6.04 Form and Application Objects Guide. For information about working with Atrium Core groups and roles, see the BMC Atrium CMDB 7.6.04 Administrator's Guide.

When you install BMC Atrium Integration Engine, the following roles and the permissions associated with them are added:

! AIE Definitions Admin

! AIE User

NOTE The users that you create for BMC Atrium Integration Engine must also have the CMDB Data Change All role. Otherwise, they cannot create data exchanges.

Consider the following points when you create groups and users for the AIE Definitions Admin and AIE User roles:

! You must use a Regular group with the Change group type for this role.

! The user must have a fixed license.

! You must map the same group to the CMDB Definitions Viewer role in the Production state. For information about this role, see the BMC Atrium CMDB 7.6.04 Administrator's Guide.

26 User’s Guide

Roles and permissions

Table 1-2 describes these roles and their permissions.

Table 1-2: Roles and permissions in BMC Atrium Integration Engine

Name Users with this role can Example

AIE Definitions Admin

! View, create, and modify data mappings and data exchanges

! Manage the BMC Atrium Integration Engine configuration and connection settings

Calbro Services wanted to assign this role to Mary Mann, who would work as the administrator for BMC Atrium Integration Engine. Calbro Services performed the following steps to add Mary Mann as an administrator:1 Created the group AIE Admin Group with the

following details:! Group Type: Change! Group Category: Regular

2 For the AIE Definitions Admin role, mapped the AIE Admin Group to the Production state.

3 Created the user Mary Mann with a fixed license.

4 Mapped the AIE Admin Group to the Production state of the CMDB Data Change All and CMDB Definitions Viewer roles.

Mary Mann can now view, create, and modify the data mappings and data exchanges for Calbro Services. Mary Mann can also manage the configuration and connection settings for BMC Atrium Integration Engine.

AIE User ! View data mappings and data exchanges

! View configuration and connection settings

Calbro Services wanted to assign this role to Allen Allbrook to monitor the data mappings and data exchanges. Calbro Services performed the following steps to add Allen Allbrook as a BMC Atrium Integration Engine user:1 Created the group AIE User Group with the

following details:! Group Type: Change! Group Category: Regular

2 For the AIE User role, mapped the AIE User Group to the Production State.

3 Created the user Allen Allbrook with a fixed license.

4 Mapped the AIE User Group to the Production state of the CMDB Definitions Viewer role.

Allen Allbrook can now view the data mappings and exchanges. However, Allen Allbrook cannot create or modify data mappings or exchanges and cannot modify any configurations or connection settings for BMC Atrium Integration Engine.



BMC Atrium Integration Engine in a server group environment

BMC Atrium Integration Engine can be used in a server group environment. You can install multiple instances of BMC Atrium Integration Engine in a server group to distribute the load across computers. When the primary BMC Remedy AR System server on which a BMC Atrium Integration Engine instance is running stops responding, a secondary server can take over and continue the data transfer.

TIP All instances of BMC Atrium Integration Engine in a server group should be running on BMC Atrium Integration Engine host computers to support server group environment.

PrerequisitesBefore installing BMC Atrium Integration Engine in a server group, make sure that you have configured BMC Remedy AR System servers in a server group setting through the BMC Remedy BMC Remedy AR System Administration Console. For more information, see “Running servers as part of a group” in the BMC Remedy Action Request System 7.6.04 Configuration Guide.

For BMC Atrium Integration Engine to work in a server group environment for DB2 adapters, the DB2 Alias name must be the same on all BMC Atrium Integration Engine host computers in the server group.

The SRVGROUP parameter in the aie.cfg file is set to Yes when you install BMC Atrium Integration Engine in a server group environment.

TIP When you have installed BMC Atrium Integration Engine in a server group, make sure that the value of the SRVGROUP parameter is set to Yes in the aie.cfg file before you execute data exchanges.

Set the following parameters in the aie.cfg file for a server group environment:

! DB2InstName

! FileDataPath

! OraDbDirPath

! PrivateRPCPort

WARNING If you fail to set the correct value for these parameters in the aie.cfg file, errors might occur during data transfer.

28 User’s Guide

BMC Atrium Integration Engine in a server group environment

When you upgrade from an earlier version of BMC Atrium Integration Engine to 7.5.00 or later, you must manually add an entry for BMC Atrium Integration Engine installed in a server group in the AR System Server Group Operation Ranking form. For information about this form, see the BMC Remedy Action Request System 7.6.04 Configuration Guide.

How BMC Atrium Integration Engine works in a server groupA server group has one primary server and multiple secondary servers. When you install BMC Atrium Integration Engine on the primary server, BMC Atrium Integration Engine works like a stand-alone installation. You can specify the number of instances to be installed on the primary server.

When you install BMC Atrium Integration Engine on the other servers in a server group, you cannot specify the number of instances to be installed. The same number of instances that are installed on primary server are automatically installed.

TIP Make sure that all BMC Atrium Integration Engine host computers in the server group have the same alias name as their internal instance name.

Table 1-3 describes the instances created on the secondary server when BMC Atrium Integration Engine is installed.

Table 1-3: BMC Atrium Integration Engine instances in a server group

The instance names on the secondary servers are the same as those on the primary server. Consequently, even when you select a secondary server to execute a data, the name of the primary server is displayed.

When an AIE service executes a data exchange, it queries the BMC Remedy AR System server for the status of each instance of the AIE service. The AIE service chooses the instance that is running to execute the data exchange.

Server Host Instance name

Primary server:AR1 Host1

Host1 AR1_Host1_Inst001



Secondary server:AR2 Host2






Debug filesThe debugging information for a BMC Atrium Integration Engine instance in a server group is available in the following files:

! atriumcore_install_log.txt and AppsEntryModify.out: These files are created after you install BMC Atrium Integration Engine on secondary servers in a server group. The Atrium_core_install.log file shows if the server group installation is successful.

A data exchange debug file is also generated on the BMC Atrium Integration Engine host computers on which the instances have run the data exchanges.

! _aieEventListener.dbg: A message is logged in this file when the AIE service starts for the data transfer or if a BMC Remedy AR System server goes down during a data exchange.

! aiexfer.out: This file is generated in the BMC Remedy AR System server installation directory that is useful in debugging.

DatasetsA dataset is a logical group of data in BMC Atrium CMDB. It is a collection of CIs and relationships for a given purpose. A dataset can represent data from a particular source or a snapshot from a particular date.

You can also use datasets for other methods of partitioning data, such as to represent production data or obsolete data. You can use datasets to hold:

! Subsets of your overall data such as departments or regions

! Data from different companies for multitenancy

! Test data

The primary purpose of datasets is to partition data according to the data providers. Each discovery application you use should store the data it stores in a separate dataset. You can also use datasets for any other logical group of data.

A dataset can contain only one instance of a given CI. Another instance might exist in a different dataset to represent the same CI. Instances that represent the same CI or relationship across datasets share the same reconciliation identity or reconciliation ID. All CIs and relationships in BMC Atrium CMDB reside in a particular dataset, which is specified by the value of their DatasetID attribute. You cannot have an instance that is not in a dataset.

30 User’s Guide

Datasets

BMC discovery products and BMC Remedy Asset Management provide the default datasets in BMC Atrium CMDB as shown in Table 1-4:

The BMC Asset dataset is used as the production dataset and is used by BMC products for reconciled data. The Reconciliation Engine merges data from multiple import datasets in the BMC Asset dataset. Data consumers should use this consolidated view of your data and you should base your business decisions on the data in this dataset.

NOTE You should not use BMC Atrium Integration Engine to transfer data directly into BMC Asset. Instead, transfer it into another dataset and reconcile it into BMC Asset.

If you use a non-BMC product to discover products, you should create a different dataset to bring in this data. For information about creating datasets, see the BMC Atrium CMDB 7.6.04 Normalization and Reconciliation Guide.

You can use the default datasets provided in BMC Atrium CMDB or the custom datasets that you create for your data in BMC Atrium Integration Engine.

When you transfer data using BMC Atrium Integration Engine, you can select the dataset to or from which data should be transferred by selecting the Restrict to Dataset option. When you select this option, the data is transferred to or from a single dataset that you specify. This option always uses a regular dataset.

For more information about configuring datasets, see the BMC Atrium CMDB 7.6.04 Normalization and Reconciliation Guide.

Table 1-4: Default datasets in BMC Atrium CMDB

Data created by Dataset name DatasetID

BMC Atrium CMDB BMC Asset BMC.ASSET

BMC Remedy Asset Management BMC.ASSET.SANDBOX BMC.ASSET.SANBOX

BMC Atrium CMDB BMC Sample BMC.SAMPLE

BMC BladeLogic Client Automation BMC Configuration Import BMC.IMPORT.CONFIG

BMC Atrium Discovery and Dependency Mapping

BMC Topology Import BMC.IMPORT.TOPO



Getting startedThe following outline illustrate the high-level steps that you take to prepare for transferring data. See the recommended area of the BMC Atrium Integration Engine documentation for specific instructions on each step.

NOTE If you are working in a server group environment, make sure that you have installed workflow binaries on all servers of the server group; otherwise the BMC Atrium Integration Engine workflow will not function.

! To get started using BMC Atrium 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 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 “Using the adapter rule helper utilities” on page 40.

Step 2 Create a data mapping to specify which data should be transferred and where it should go.

For instructions, see “Creating data mappings for BMC Atrium CMDB CI classes” on page 53, “Creating data mappings for BMC Atrium CMDB relationship classes” on page 83, or “Creating data mappings for BMC Remedy AR System forms” on page 109.

Step 3 Create a data exchange to control the execution, direction, and other characteristics of your data transfers.

For instructions, see “Data exchanges” on page 135.

Accessing the Data Exchange ConsoleThe Data Exchange Console, which is the main user interface for BMC Atrium Integration Engine, is an BMC Remedy AR System form that you can use either with BMC Remedy User or a browser. To use a browser client, you must have BMC Remedy Mid Tier.

! To access the Data Exchange Console with BMC Remedy User

1 On a Windows XP operating system, open BMC Remedy User by choosing Start > All Programs > BMC Software > AR System> BMC Remedy User.

2 In the Login dialog box, specify the following details:

a In the User Name field, type your user name.

b In the Password field, type your password.

32 User’s Guide

Accessing the Data Exchange Console

c Click Accounts and select the BMC Remedy AR System server where the Data Exchange application is installed.

d Click Options to set the Preference Server settings.

e In the Preference Server field, specify the server name if your administrator has set up a preference server for centralized user preferences. If a Preference Server has not been set up, you can manually add a preference server (and the TCP and RCP port information, if necessary). For more information about preference servers, see the BMC Remedy Action Request System 7.6.04 Configuration Guide.

f In the Authentication field, specify the authentication string provided by your administrator.

3 Click OK.

Depending on your setup, the application will open to the BMC Remedy BMC Remedy AR System Home Page or the BMC Remedy AR System without the Home Page. The Home Page includes a navigation pane with various links to BMC Remedy AR System forms and applications including BMC Atrium Integration Engine. The link to BMC Atrium Integration Engine is abbreviated as AIE Console.

Figure 1-4: BMC Remedy AR System Home Page navigation pane

4 If the Home Page appears, click AIE Console on the navigation pane.

The Data Exchange Console appears.

5 If the Home Page does not appear, Choose File > Open > Object List.

The Object List appears.

6 Double-click AIE Console.


The Data Exchange Console shows the sample data exchanges that are installed with the product. Using this console, you can create a new data exchange, select an existing data exchange to modify or delete, copy a data exchange, verify a data exchange configuration, run a data exchange on demand, and activate a data exchange.

AIE Console link



! To access the Data Exchange Console with a browser

1 Launch your browser and enter the URL designated by your administrator:

http://midtier:port/arsys/forms/BMCRemedyARSystemServer/EIE%3AStartUp

! midtier is the name of the web server where the BMC Remedy Mid Tier is installed.

! port is the port number of the web server where the BMC Remedy Mid Tier is installed, which is required only if the web server is not using the default port (80)

! BMCRemedyARSystemServer is the name of the BMC Remedy AR System server where the Data Exchange application is installed.

The Login window appears.

2 Specify the following details in the Login window:

! User name

! Password

! Authentication string (if one was provided by the administrator)

3 Click Log In.


You can also access the Data Exchange Console from the BMC Atrium Integration Engine monitoring console. For information about the monitoring console, see “Accessing the BMC Atrium Integration Engine monitoring console” on page 34.

Accessing the BMC Atrium Integration Engine monitoring console

In the BMC Atrium Integration Engine monitoring console, you can view the exchanges that are currently running in BMC Atrium Integration Engine. You cannot run, modify, or delete any data exchanges or data mappings. You can only monitor the progress of the data exchanges and their consecutive runs.

You can view the BMC Atrium Integration Engine monitoring console from the BMC Atrium Core Console. The BMC Atrium Core Console is the central location for accessing Atrium Core features such as BMC Atrium CMDB and its components. For more information about the BMC Atrium Core Console, see the BMC Atrium CMDB 7.6.04 User's Guide.

Perform the following steps to access the BMC Atrium Integration Engine monitoring console from the BMC Atrium Core Console.

34 User’s Guide


! To access the BMC Atrium Integration Engine monitoring console in the BMC Atrium Core Console

1 Launch your browser and enter the URL designated by your administrator:

http://midtier:port/atrium/AtriumConsole

! midtier is the name of the web server where the BMC Remedy Mid Tier is installed.

! port is the port number of the web server where the BMC Remedy Mid Tier is installed, which is required only if the web server is not using the default port (80).

2 In the login screen, enter:

! User name

! Password

! Authentication string (if one was provided by the administrator)

3 Click Log In.

4 On the Welcome screen of the BMC Atrium Core Console, click Application Launcher on the left-hand side.

5 Mouse over the Applications icon, click AIE to open the BMC Atrium Integration Engine monitoring console.

6 View the data exchanges in the monitoring console by selecting them in the navigation pane.

The details of the data exchange appear in the display pane.

By default the History tab is selected. You can sort the data exchange runs according to the status and also specify the dates using the calendar to view the data exchanges.

7 Select a run of the data exchange and expand it to view the details about the data exchange run.

For more information about the data exchange details that you can view, see “The History tab” on page 36.

8 Select the Data Mappings & Schedule tab.

You can view the details of the data exchange such as Exchange Name, Instance Name, AR Server Name. The data mappings associated with the data exchange and their respective execution schedules are also displayed. For more information about the details on this tab, see “The Data Mapping & Schedule tab” on page 37.

Information displayed in the monitoring consoleThe display pane shows the details of the data exchanges that you select in the navigation pane. In the display pane, you can view the history of the data exchange and the data mappings associated with the data exchange and their schedule.

The display pane contains the History tab and the Data Mappings & Schedule tab.



The History tabAll runs of the data exchange are listed in a table on the History tab with their start and end date and time. You can filter the runs according to the Status and the time period.

To view data exchanges runs during a time period, you can specify the start and end dates between which the exchanges are run. The History tab displays the details of the data exchange. Figure 1-5 on page 36 shows the details displayed on the History tab.

Figure 1-5: Job run details on the History tab

A status bar showing the progress of each run is also displayed, along with the following details of the data exchange run: Table 1-5: Fields on the History tab

Field Description

Job Run ID Displays the ID of the job.

Status Displays the status of the data exchange run.

Start time Displays the time at which the data exchange run was started.

End time Displays the time at which the data exchange run was completed.If the data exchange run is running, aborted, or not responding, this field remains blank.

Total Number of Records

For CI or BMC Remedy AR System form data mappings, this field displays the total number of records from the source or destination, whichever is greater in number.For relationship data mappings, this field displays the total number of records from the relationship class or vendor-based table, whichever is greater in number.

Number of Records Processed

Displays the number of records that have been processed.

Number of Records Failed

Displays the number of records that have not been transferred.

Number of Records Successful

Displays the number of records that have been successfully transferred.

36 User’s Guide


The Data Mapping & Schedule tabThe Data Mapping & Schedule tab displays details about the selected data exchange, the data mappings associated with that data exchange, and the schedule of the data exchange. You can also view details such as the status and type of the data exchange, external data store, number of threads, and direction of the data exchange.



38 User’s Guide

Chapter

2
Populating database field menus
In BMC Atrium Integration Engine, you can populate the field menus that are used for creating data mappings. You can populate these field menus in the Database Field Menus Console. This section describes how to use the adapter rule help utilities.


! Using the adapter rule helper utilities (page 40)! Using the DB2 Adapter Rule Helper utility (page 40)! Using the Oracle Adapter Rule Helper utility (page 44)! Using the SQL Server Adapter Rule Helper utility (page 47)! Using the XML Adapter Rule Helper utility (page 52)! Using the File Adapter Rule Helper utility (page 52)



Using the adapter rule helper utilitiesUse the Database Field Menus Console to populate field menus that are used when you create data mappings. The field menus enable you to choose the fields from your external data store tables from a list instead of typing them manually. You can also use the Database Field Menus Console to connect to multiple databases and to populate the field menus from multiple databases at the same time.

Access the DB2 UDB, Oracle, and Microsoft SQL Server rule helpers through the Database Field Menus Console. You can access the XML Helper and File Helper through workflow. You can also run XML Helper and File Helper from a command line to populate the .tbl and .xsd fields in the AIE:VendorFieldNames form.

All rule helper binaries are available in the following directories:

! BMCAtriumIntegrationEngineInstallationDirectory\bin

! BMCRemedyARSystemServerInstallationDirectory

! On UNIX: BMCRemedyARSystemServerInstallationDirectory/bin

Best practice

If a database table or view does not appear in the Available Tables and Views, make sure that:

! You have successfully established a connection with the external database.

! You have not limited the number of tables or views to be displayed by specifying an owner’s name.

Using the DB2 Adapter Rule Helper utilityYou can populate field information for DB2 UDB data tables by using either the Database Field Menus Console or a command line.

Populating DB2 UDB field information using the Database Field Menus Console

The following steps describe how to populate DB2 UDB fields for multiple external data tables.

40 User’s Guide

Using the DB2 Adapter Rule Helper utility

! To populate DB2 UDB field information for multiple external data tables

1 From the BMC Atrium Core console, click Configuration > Database Field Menus to view the Database Field Menus Console.

Figure 2-1: Database Field Menus Console

2 On the DB2 tab, specify your database instance, database alias, login name, and password.

NOTE Make sure that you specify the database alias of your local BMC Remedy Action Request System (BMC Remedy AR System) database.

3 Click Test Connection to verify the connection parameters.

The Test Connection button label changes to Get Result.

4 Click Get Result.

A dialog box displays the test result.

5 If the verification was unsuccessful, correct the listed errors and test the connection again.

6 Click OK and Save.

7 In the Limit tables and views in schema field, perform one of the following actions:

! Leave this field blank to have BMC Atrium 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. This field is case-sensitive.

8 Click Load Table & View Names.

Tables and views from the external data store are populated in the Available Tables and Views list.



9 From the Available Tables and Views list, select a table or view, and click Add.

The table or view is added to the Selected Tables and Views list. The Loading Database Tables and Views status initially appears in the bottom left portion of the window. When BMC Atrium Core has loaded all tables and views, this status changes to Finished Loading Tables and Views.

10 Click Update Database Field Menus.

The rule menus with the table and view names are populated into the AIE:VendorFieldNames form. This form provides the field names to the rule menus in the data mapping windows.

The status of the Load Table & View Names and Update Database Field Menus operations appears in the Status field.

Populating DB2 UDB field information for external data tables using a command line

The following steps describe how to populate DB2 UDB fields for external data tables using a command line.

! To populate DB2 UDB field information for multiple external data tables using a command line

1 Type the following command:

aieInstallationDir/service/bin/db2helper -ax BMCRemedyARSystemServerName -ar 0 -al Demo -ap -da DB2Alias -dl DB2Login -dp DB2Password -to DB2User or DB2Owner -di DB2InstanceName

2 If you want to use the rule helper utilities located in the installation directory of BMC Remedy AR System, type the following command:

On Windows:

BMCRemedyARSystemServerInstallationDir\db2helper -ax BMCRemedyARSystemServerName -ar 0 -al Demo -ap -da DB2Alias -dl DB2Login -dp DB2Password -to DB2User or DB2Owner -di DB2InstanceName

On UNIX:

BMCRemedyARSystemServerInstallationDir/bin/db2helper -ax BMCRemedyARSystemServerName-ar 0 -al Demo -ap -da DB2Alias -dl DB2Login -dp DB2Password -to DB2User or DB2Owner -di DB2InstanceName

3 After you execute the command, click Refresh Table List on the Database Field Menus Console window to populate the Available Tables and Views list.

4 From the Available Tables and Views list, select the table or view.

42 User’s Guide

Using the DB2 Adapter Rule Helper utility

5 Click Add to add the selected table or view to the Selected Tables and Views list.

6 After the Selected Tables and Views list is populated with table names, use the following command to populate the table fields in the AIE:VendorFieldNames form:

aieInstallationDir/service/bin/db2helper -ax BMCRemedyARSystemServerName-ar 0 -al Demo -ap -da DB2Alias -dl DB2Login -dp DB2Password -di DB2InstanceName -c

where

-c (Create menu to AIE:VendorFieldNames form)

! To populate DB2 UDB field information for a single external data table using a command line

Type the following command:

aieInstallationDir/service/bin/db2helper -ax BMCRemedyARSystemServerName-ar 0 -al Demo -ap -da DB2Alias -dl DB2Login -dp DB2Password -di DB2InstanceName -to TableOwner -tn TableName -c

You must use the following additional parameters:

! -c — Create menu to AIE:VendorFieldNames form

! -to tableOwner —Valid table name in capital letters.

! -tn tableName —Valid table name owned by the table owner named in the -to parameter.

NOTE The DB2InstanceName variable is case-sensitive.

Using the DB2 UDB adapter rule helper utility on UNIX platformsFor UNIX platforms, you can run the db2helper.sh script located in the BMCRemedyARSystemServerInstallationDir/bin directory. This script internally invokes the rule helper utility for DB2 UDB.

NOTE For the DB2 UDB rule helper, if you have the BMC Remedy AR System server installed on UNIX, you must change the db2helper.sh script to set the DB2 UDB client installation directory.



! To edit the script for DB2 UDB

1 Open BMCRemedyARSystemServerInstallationDir/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.

Using the Oracle Adapter Rule Helper utilityYou can populate field information for external Oracle data tables by using either the Database Field Menus Console or a command line.

Populating Oracle field information using the Database Field Menus Console

The following steps describe how to populate Oracle fields for multiple external data tables.

! To populate Oracle field information for multiple external data tables

1 From the BMC Atrium Core console, click Configuration > Database Field Menus to view the Database Field Menus Console.

Figure 2-2: Oracle Adapter Rule Helper Utility window

2 On the Oracle tab, specify the SID, database directory, login name, and password.

44 User’s Guide

Using the Oracle Adapter Rule Helper utility

3 In the DB Directory field, type the Oracle home directory where you will execute the Oracle rule helper utility.

4 Click Test Connection to verify the Oracle connection parameters.


5 Click Get Result.






! Type a user (owner) name in this field to retrieve only the tables and views owned by that user. This field is case-sensitive.

9 Click Load Table & View Names to populate the tables and views in the Available Tables and Views list.

10 From the Available Tables and Views list, select the table or view, and click Add.



The rule menus with the table and view names are populated into the AIE:VendorFieldNames form. This form provides the field names to the rule menus in the data mapping windows.




Populating Oracle field information for external data tables using a command line

The following steps describe how to populate Oracle fields for external data tables using a command line.

! To populate Oracle field information for multiple external data tables using a command line

1 Type the following command:

aieInstallationDir\service\bin\rlohelper -ax BMCRemedyARSystemServerName -ar ARPort -al ARUser -ap ARPassword -os SID -ol DBUser -op DBPassword -oh OracleDBDirectory -oa SID -to DBOwner -d

where

-d (Debug)

2 If you want to use the rule helper utilities located in the installation directory of BMC Remedy AR System, type the following command:

On Windows:

BMCRemedyARSystemServerInstallationDir\rlohelper -ax BMCRemedyARSystemServerName -ar ARPort -al ARUser -ap ARPassword -os SID -ol DBUser -op DBPassword -oh OracleDBDirectory -oa SID -to DBOwner -d

On UNIX:

BMCRemedyARSystemServerInstallationDir/bin/rlohelper -ax BMCRemedyARSystemServerName -ar ARPort -al ARUser -ap ARPassword -os SID -ol DBUser -op DBPassword -oh OracleDBDirectory -oa SID -to DBOwner -d

3 After you execute the command, click Refresh Table List on the Database Field Menus Console window to populate the Available Tables and Views list.

4 From the Available Tables and Views list, select the table or view.

5 Click Add to add the table or view to the Selected Tables and Views list.

6 After the Selected Tables and Views list is populated with table names, use the following command to populate the table fields in the AIE:VendorFieldNames form:

aieInstallDir\service\bin\rlohelper -ax BMCRemedyARSystemServerName-ar ARPort -al ARUser -ap ARPassword -os SID -ol DBUser -op DBPassword -oh OracleDBDirectory -c -d

where


! -d — Debug

46 User’s Guide

Using the SQL Server Adapter Rule Helper utility

! To populate Oracle field information for a single external data table using a command line

Type the following command:

aieInstallationDir\service\bin\rlohelper -ax BMCRemedyARSystemServerName-ar ARPort -al ARUser -ap ARPassword -os SID -ol DBUser -op DBPassword -oh OracleDBDirectory -c -d -to TableOwner -tn TableName

where -d (Debug)

You must use the following additional parameters:


! -to table Owner — Valid table name in capital letters.

! -tn tableName — Valid table name owned by the table owner named in the -to parameter.

Using the Oracle adapter rule helper utility on UNIX platformsFor UNIX platforms, you can run the rlohelper.sh script located in the BMCRemedyARSystemServerInstallationDir/bin directory. This script internally invokes the rule helper utility for Oracle.


You can populate field information for external SQL Server data tables by using the Database Field Menus Console or a Windows based application.

NOTE The SQL Server adapter is not supported on UNIX and Linux® platforms, because the SQL OLEDB API that is used is proprietary to Microsoft and not supported on UNIX and Linux. An instance of BMC Atrium Integration Engine installed on UNIX cannot communicate with a SQL Server database.



Populating SQL Server field information for multiple external data tables

The following steps describe how to populate SQL Server fields for multiple external data tables.

! To populate SQL Server field information for multiple external data tables

1 From the BMC Atrium Core console, click Configuration > Database Field Menus to view the Database Field Menus Console window.

2 Click the SQL Server tab.

Figure 2-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 Perform one of the following actions:

! Type your user name in the Login Name field and the password in the Password field.

! Select the Enable Windows Authentication check box if you want to use Windows authentication for your database. When you select this option, you do not need to type a login name or password.

NOTE If you specify Windows Authentication for your database, make sure that the Windows service is set to run as a Windows Log On As user that has permissions to the vendor database. For more information about Windows authentication, see “SQL Server authentication” on page 158.



48 User’s Guide


7 Click Get Result.






! Type a user (owner) name in this field to retrieve only the tables and views owned by that user.

11 Click Load Table & View Names to populate the tables and views from the external data store in the Available Tables and Views list.

12 From the Available Tables and Views list, select the table or view, and click Add.



The rule menus with your table and view names are populated into the AIE:VendorFieldNames form. This form provides the field names to the rule menus in the data mapping windows.


Populating SQL Server field information for multiple external data tables using a Windows based application

The following steps describe how to populate SQL Server fields for multiple external data tables using a Windows based application. For example, aieInstallationDir\service\bin\rlshelper.exe.

! To populate SQL Server field information for multiple external data tables using a Windows based application

1 From the Windows Start menu, choose Run.

2 In the Open field of the Run dialog box, browse to select the path of the Rule Helper utility.

NOTE The utility is located in the aieInstallationDir\service\bin and BMCRemedyARSystemServerInstallationDir directories.



3 Click OK to view the Rule Helper window.

The Main tab appears by default.

4 Click the Database Connection tab to view the database login information.

Figure 2-4: Database Connection tab

Use the Database Connection tab to define connection information to locate the SQL Server database (used as a rule source) and the BMC Remedy AR System server where the Data Exchange application is installed.

5 In the Microsoft SQL Server Connection area, perform 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.

c In the User Name field, type the user name for connecting to the SQL Server database.

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 BMC Atrium Core will be considered for database authentication. For more information about Windows authentication, see “SQL Server authentication” on page 158.

50 User’s Guide


6 In the BMC Remedy AR System Server Connection area, provide the following information about your BMC Remedy AR System server:

a In the AR Server field, type the host name.

b In the TCP Port field, type the port number.

c In the User Name field, type the user name for the administrator.

d In the Password field, type the password for the administrator.

7 Click Test SQL and AR Connection to test the connection to your SQL Server database and BMC Remedy AR System database.

8 Click the Main tab to view the SQL Server database tables and views information window.

Figure 2-5: Main tab

9 Click Load Table/View Names.

The list on the left is updated with the tables and views from the SQL Server database.

10 Select the tables and views that you want to add from the list on the left, and click Add to add them to the Tables and Views in AIE Data Exchange menu list on the right.

11 Click Create Menu.

12 Click Close.



Populating SQL Server field information for BMC Atrium Integration Engine on Windows and BMC Remedy AR System on UNIX

When BMC Atrium Integration Engine is installed on a Windows computer and BMC Remedy AR System is installed on a UNIX computer, the BMC Atrium Integration Engine workflow and binaries are executed from the BMC Remedy AR System server computer.

When you populate the SQL Server field information from the Database Field Menus Console, the rlshelper.exe file is run as a child process of the BMC Remedy AR System server. The rlshelper.exe file is a Windows application and cannot run on UNIX.

To avoid errors, run the rlshelper.exe file from the AIEInstallationDir/service/bin directory. The Rule Helper utility appears. Populate the SQL Server field information using the Rule Helper utility that appears. For more information, see “To populate SQL Server field information for multiple external data tables using a Windows based application” on page 49.

After you have populated the SQL Server field information, continue configuring the data mappings and data exchanges.

Using the XML Adapter Rule Helper utilityYou must run the XML Adapter Rule Helper utility from a command line. Type the following command:

aieInstallationDir\service\bin\xmlhelper -ax BMCRemedyARSystemServerName -al Login -ap Password -ar port -xp pathToTheXMLSchema -xr XMLRowIdentifier-d

where

-d — Debug

Using the File Adapter Rule Helper utilityYou must run the File Adapter Rule Helper utility from a command line. Type the following command:

aieInstallationDir\service\bin\filehelper -ax BMCRemedyARSystemServerName -al Login -ap Password -ar port -fn pathToTheFileOnTheLocalComputer -d

where

-d — Debug

52 User’s Guide

Chapter

3
Creating data mappings for BMC Atrium CMDB CI classes
A data mapping defines how data in the source corresponds to data in the target and which actions to take when transferring between them. This section provides instructions for creating data mappings between an external data store and the attributes of a BMC Atrium Configuration Management Database (BMC Atrium CMDB) CI class.


! Example CMDB data scenario (page 54)! Before creating data mappings (page 55)! Overview of the data mapping process (page 57)! Defining data mapping parameters (page 58)! Defining the primary key (page 63)! Defining data field mappings (page 65)! Setting response fields (page 68)! Defining delete field mappings (page 70)! Defining queries (page 72)! Setting data mapping options (page 78)



Example CMDB data scenarioThe following scenario is used in some of the sections that follow to provide concrete examples of steps you must take when creating data mappings for BMC Atrium CMDB CI and relationship classes.

Calbro Services has an external data store that stores information about all the hardware components in its environment. In this case, the external data store has separate tables for computers, processors, disk drives, memory, and so on.

The organization of the database tables for computers and disk drives is shown in Figure 3-1.

NOTE Figure 3-1 shows one way that external data might be stored. You can store data in an external database in a single table or in other multiple tables.

Figure 3-1: Organization of the computer and disk drive database tables

The records in the Computer table correspond to instances of the BMC_ComputerSystem class in BMC Atrium CMDB. The records in the Disk Drive table correspond to instances of the BMC_DiskDrive class in BMC Atrium CMDB.

Each record in the Disk Drive table contains the name of its corresponding computer in the AssociatedComputer column. This relationship associates a specific instance of a disk drive in the external database with a specific instance of a computer.

NOTE The following sections use the BMC_DiskDrive CI class as an example in explaining how to create a data mapping. Creating a data mapping for the BMC_ComputerSystem CI class is similar.

Name SerialNumber PartNumber AssociatedComputerDisk 1520 23541 MFG729817 Computer 910Disk 1523 24761 MFG729817 Computer 912Disk 1560 24645 MFG729817 Computer 921Disk 1534 24671 MFG729817 Computer 954Disk 1530 26541 MFG729817 Computer 911

Computer table

Name SerialNumber PartNumberComputer 910 59820 MFG3164538Computer 912 63425 MFG3164538Computer 921 61789 MFG3164538Computer 954 62673 MFG3164538 Computer 911 59623 MFG3164538

Disk Drive table

54 User’s Guide

Before creating data mappings

Before creating data mappingsBefore you create data mappings, consider the following points to standardize your data:

! Familiarize yourself with your data model. This will help in determining the classes to which you should transfer data.

! Using decimal values

When decimal values are brought into integer fields, the decimal positions are lost. To round off the decimal values, use the round () function.

For example, a decimal value of 5.5 to 5.9 is rounded up to an integer value of 6. A decimal value of 5.0 to 5.4 is rounded down to an integer value of 5.

! Using the date and time values

To transfer a date or time value, you must use the BMC Remedy AR System Date/Time field, which holds dates from 1/1/1971 to 12/31/2037. The string value can be any of the BMC Remedy AR System supported date formats. When the AIE service encounters a date type field with a string value, it attempts to treat it as a BMC Remedy AR System date. If it is a valid BMC Remedy AR System date, the date is transferred correctly.

! Mapping character fields with leading zeroes to an integer field

Do not map a character field in the external data store to an integer field as a primary key, because BMC Atrium Integration Engine ignores the leading zeroes.

For example, 0000000011 is considered as 11. When an external data store field with such additional zeroes is defined as the primary key or relationship key, BMC Atrium Integration Engine cannot find the key, because it searches for the value without the zeroes. For example, it queries 11, which does not match with the 0000000011 value in the external data store.

! Transferring records to a field with range limits

In BMC Remedy AR System, you can specify a range limit on certain fields. If a particular record has a value mapped to such a field that does not fall within the range limit, BMC Atrium Integration Engine cannot transfer this record.

For example, if a selection field in a source is out-of-range, the record is not transferred by BMC Atrium Integration Engine. A selection field cannot be left empty and has a default value that is not known to BMC Atrium Integration Engine and hence it ignores this record.



! Populating attributes

When you transfer data to BMC Atrium CMDB classes or BMC Remedy AR System, make sure that you create appropriate field mappings so that the following required attributes are populated:

! Name

! ShortDescription

! DatasetId

! Submitter

Make sure that you populate the attributes used in the Standard Rules for identification with unique values when you transfer data. This ensures that you can use a Standard Job for reconciliation. Following are the attributes that you should populate:

! TokenId

! Name

! SerialNumber

! HostName

! Domain

! VersionNumber

You can refer to the Identification Rules in the Standard Rules Editor to verify what attributes the Reconciliation Engine uses for each class.

For CIs of products that are populated in the Product Catalog, populate the ManufacturerName and Model attributes to allow CIs to be normalized.

! Populate the attributes that are used for categorization. For information about how to populate the categorization attributes, see the BMC Atrium Core 7.6.04 Product Catalog and DML Guide.

! Transferring data from flat files

Make sure that you do not include more than 100,000 records in a single flat file for data mapping. If you add more than 100,000 records, performance degrades.

Flat files can be in a .dat or .csv format. You must also create a .tbl file to define the columns and the delimiter used in the .dat or .csv file. The.tbl file must have the same name and be located in the same folder as the .dat or .csv file. If your .tbl file does not specify a data type for each field, BMC Atrium Integration Engine interprets them as character fields.

For a .dat file, you must manually create a .tbl file. For more information, see the sample .tbl files in the aieInstallationDir\service\data directory.

For a .csv file, use the filehelper utility of BMC Atrium Integration Engine to automatically generate the .tbl file. Make sure that the .csv file and the filehelper utility are available on the same computer. Otherwise, the utility cannot locate the .csv files.

56 User’s Guide

Overview of the data mapping process

! Transferring data from .xml files

An .xml file must have a corresponding .xsd file with the same name located in the same directory. When you use special characters in your data, you must specify the encoding type for special characters in the header of your .xml file, such as windows-1252, ISO-8859-1, UTF-8. If you do not specify the encoding type, no data is transferred.

Overview of the data mapping process

Step 1 Define data mapping parameters.

You must specify the mapping name, direction, namespace, external data store, and delete options. For more information, see “Defining data mapping parameters” on page 58.

Step 2 Define the primary key.

You must specify the primary key that uniquely identifies a row of data. Attributes from a CI class and an external data store together constitute a primary key. For more information, see “Defining the primary key” on page 63.

Step 3 Define data field mappings.

You must define data mappings to specify the fields and attributes that should be transferred. For more information, see “Defining data field mappings” on page 65.

Step 4 (optional) Set response fields.

When a record is created or updated in the target, a value is created. You can set response fields to store this value in the source. For more information, see “Setting response fields” on page 68.

Step 5 (optional) Define delete field mappings.

You can update a record in the target when a corresponding record is deleted in the source. For more information, see “Defining delete field mappings” on page 70.



Step 6 (optional) Define queries.

You can create queries for BMC Atrium CMDB and external data stores to limit the transfer of data to meet certain criteria. You can create data key, update, response, and delete queries. For more information, see “Defining queries” on page 72.

Step 7 (optional) Set the data mapping options.

You can set several preferences for a data mapping. For more information, see “Setting data mapping options” on page 78.

Defining data mapping parameters

NOTE Before you create any data mappings, make sure that you have an account in your source database and that you have created the necessary permissions in that database.

TIP If your external data store is a DB2 UDB, Oracle, or SQL Server data store, creating a data mapping is easier and faster if you first populate the database field menus in the CI Class Mapping Information window with values from your database. This allows you to select the columns of your database tables from a list instead of typing them on all the mapping and query tabs of the window. For instructions on populating database field menus, see “Populating database field menus” on page 39.

Before you begin

Make sure that you have populated the Database Field Menus with database tables from your external database.

! To define data mapping parameters for CI classes

1 With BMC Remedy User, log into the server where BMC Atrium Integration Engine is installed.

2 (optional) If the Home page does not appear, click the Home icon in the toolbar.

58 User’s Guide


3 In the Quick Links bar of the Home page, click AIE Console.


4 On the navigation pane, select Integration Objects > CI Class Mappings.

The CI Class Mapping Console appears.

5 Click New.

The CI Class Mapping Information window appears.

Figure 3-2: CI Class Mapping Information window

6 In the Mapping Name field, type a name for your mapping.

In the example scenario, Calbro Services uses BMC Disk Drive.

7 In the Direction field, select the direction in which you are transferring data.

In the example scenario, Calbro Services uses External Data into CMDB.

8 In the Namespace list, select the namespace of the class to or from which to transfer data.

In the example scenario, Calbro Services uses BMC.CORE.

9 In the Class list, select the class to or from which to transfer data.

In the sample scenario, Calbro Services uses BMC_DiskDrive.

10 In the External Data Store list, select the name of the adapter for the external data store.

11 In the Table Name list (for database adapters) or File Name field (for the flat file and XML adapters), select or type the name of the object in the external data store that is referenced in this data mapping.

The list associated with this field contains all external data objects that have been previously used in a data exchange.



! For Table Name, you must use the correct syntax or BMC Atrium Integration Engine cannot find the specified table. The case-sensitive syntax for this field is as follows:

! DB2 UDB: DatabaseOwner.TableName

! Oracle: DATABASEOWNER.TABLENAME

! SQL Server: DBO.TableName

In the example scenarios, Calbro Services uses SQL Server databases to save their data. The Printers.dbo tables are specified as the source for the data mapping of printer CIs.

! For File Name, specify the absolute path to your file but do not include the extension in its name. For example, you might specify the following path for a ExportedComputerSystems.xml file on Windows:

C:\Program Files\BMC Software\BMC Atrium Integration Engine\ myserver-0\service\data\ExportedComputerSystems

For information about preparing your flat files for the data transfer, see “Transferring data from flat files” on page 56.

12 If this data mapping uses the XML adapter, type the name of the element that identifies each row of data in the Row Element field.

Each row of data that becomes an instance in BMC Atrium CMDB is enclosed by this element in your .xml file. For example, if your file looked like the following example, you would enter myrecord in the Row Element field.

<class type=”CI”><name>DiskDrive</name><myrecord>

<attributes><name>Disk 1520</name><serialnumber>23541</serialnumber><partnumber>MFG729817</partnumber><associatedcomputer>Computer 910</associatedcomputer>

</attributes></myrecord><myrecord>


</attributes></myrecord>

</class>

For information on preparing your .xml files for the data transfer, see “Transferring data from .xml files” on page 57.

When creating mapping for a child record of an XML file, you can now access the parent record elements along with child record elements. For more information, see “Accessing parent record elements along with child record elements from an XML file” on page 62.

60 User’s Guide


13 If you want to use this data mapping to transfer data to or from more than one BMC Atrium CMDB dataset, leave the Restrict to DatasetId option cleared. Otherwise, select it and choose the dataset that you want to use from the list.

Datasets are used primarily to represent separate data providers. Make sure that each data provider has its own import dataset.

WARNING If you do not select this option, you must create a data field mapping for the DatasetId attribute of your class. Without this mapping, BMC Atrium Integration Engine does not know which dataset the data should be transferred to (or from), and your data transfer fails.

For more information about datasets, see “Datasets” on page 30.

14 In the If a Record Is Deleted From Source field, choose an option:

! Mark as deleted—When a record has been deleted from the source, the equivalent record in the target remains but is marked as deleted (the MarkAsDeleted attribute is set to Yes). BMC recommends this setting because it prevents orphan instances in your production dataset and it reduces the likelihood of duplicate instances should the record later be reestablished on the source.

! Permanently delete—When a record has been deleted from the source, the equivalent record in the target is physically deleted. BMC Atrium CMDB has no way to re-create a deleted instance. You might select this option if you are importing data to a dataset that does not undergo reconciliation.

NOTE This option depends on a setting in the data exchange used with this data mapping. See the If a Record Is Deleted From Source option on the Main tab of the Data Exchanges Information window. If that option is set to Delete according to data mapping, the selection that you make here takes effect. If instead the data exchange is set to Do not delete, no delete action is taken regardless of this setting in the data mapping.

For example, Calbro Services uses the Mark as Deleted option for transferring the computer systems data into the centralized database. Records that are deleted in the source database are marked as deleted in the centralized database. If the deleted records are reestablished in the source database, the records marked as deleted can be reestablished, thus avoiding duplicate and orphan instances.



15 Click Create.

NOTE When you click Create, all fields on the Main tab except for Mapping Name and Restrict to DatasetId become unavailable, and you can no longer edit this information.

The CI Class Mapping Information window expands to include tabs for Primary Key Mapping, Data Field Mapping, Response Field Mapping (if this is not a flat file data mapping), Delete Field Mapping, Query, and Options.

Accessing parent record elements along with child record elements from an XML file

When creating mapping for a child record of an XML file, you can now access the parent record elements along with child record elements.

This XML mapping example shows the syntax needed to import data into both the BMC_ComputerSystem class and the BMC_IPEndpoint class.

<ComputerSystem CLASSID="BMC_COMPUTERSYSTEM">

<SerialNumber>1111</SerialNumber>

<ShortDescription>This is computer 1111</ShortDescription>

<Name>1111</Name>

<IP_Address>

<Name>IP1</Name>

<Address>123.12.23.111</Address>

</IP_Address>

</ComputerSystem>

Both of the classes receive the data, but their configuration item (CI) records are not related to each other. Therefore, it is difficult to relate a Computer System CI with an IP address CI in CMDB.

To set the relationship between the Computer System CI and the IP address CI, use the DNSHostName attribute in the IP_EndPoint class. DNSHostName represents the IP address that belongs to the computer name specified in that field. The DNSHostName should be populated with the name of the Computer System.

TIP If there is more than one parent for the child, you should not combine mapping attributes from different parent classes while creating a child mapping.

62 User’s Guide

Defining the primary key


A primary key uniquely identifies a row of data. You must specify the attributes of the CI class and the corresponding fields in the external data store that together make up the primary key. After a data transfer, the primary key is the link that matches a record in the external data store with its counterpart in BMC Atrium CMDB.

Best practices

When choosing an attribute as a primary key, consider the following points:

! Do not use an attribute whose value could change or could be NULL. For example, do not use Description, because the value of the Description attribute could be NULL or could change. If the primary key of a record is NULL, the record cannot be identified and the record cannot be transferred.

If your external database has records with empty values, you can create a view of your external database to filter out such records. You can then create a data mapping based on this view.

! Choose a unique attribute that you can also use for identification during reconciliation. You can choose attributes to use for the primary key that are already in the standard identification rule. This makes sure that you can use a Standard Job for reconciliation. For more information about a Standard Job, see the BMC Atrium CMDB 7.6.04 Normalization and Reconciliation Guide.

! If you cannot use the standard rules, you should use attributes inherited from BMC_BaseElement class. This simplifies your reconciliation setup by allowing multiple classes to inherit identification rules from the BMC_BaseElement class.

For the sample scenario shown in Figure 3-1 on page 54, you would define a primary key that relates a serial number in the SerialNumber column of the Disk Drive table with the SerialNumber attribute in the BMC_DiskDrive class.

! To define primary keys

1 In the CI Class Mapping window, click the Primary Key Mapping tab.



Figure 3-3: CI Class Mapping Information window—Primary Key Mapping tab

The Mapped Attributes table on this tab lists all field mappings defined for the data mapping.

NOTE You must define a key to complete a data mapping. The key can contain more than one attribute from each side.

2 In the CI Class Attributes table, select an attribute to be part of this primary key.

In the sample scenario, Calbro Services uses SerialNumber.

When a class attribute is updated in BMC Atrium CMDB, BMC Atrium Integration Engine automatically updates the attributes in the CI Class Attributes table when you create a new mapping or open an existing data mapping.

3 In the External Data Store Attributes table, select an attribute to be part of this primary key.

In the sample scenario, Calbro Services uses SerialNumber.

4 Click Add to add this pair of attributes to the primary key.

The attributes appear in the Mapped Attributes table.

5 Repeat steps 2 through 4 for each primary key attribute that you want to map.

When you have a primary key with more than one attribute from each side, the expressions are joined together with an AND operator. That means a data row in the external data store matches an instance in BMC Atrium CMDB only if each pair of attributes in the primary key matches.

6 Click Save.

64 User’s Guide

Defining data field mappings


You must define data field mappings to specify which fields or attributes should be transferred during a data exchange. For the sample scenario, you would define field mappings for name, serial number, part number, and associated computer. These attributes are the database columns in Figure 3-1 on page 54 in the Disk Drive table.

NOTE If you did not select the Restrict to DatasetId option on the Main tab, you must create a data field mapping for the DatasetId attribute. Without this mapping, BMC Atrium Integration Engine does not know which dataset the data should be transferred to (or from), and your data transfer fails.

NOTE If you are following the scenario from “Example CMDB data scenario” on page 54 and map relationships according to “Attributes in the member CI classes” on page 85, you should know that the BMC_DiskDrive CI class already includes attributes for name, serial number, and part number. These attributes are called Name, SerialNumber, and PartNumber. However, by default no attribute for associated computer exists. You must create the AssociatedComputer attribute in BMC Atrium CMDB using the Class Manager. For more information about creating attributes, see the BMC Atrium CMDB 7.6.04 Administrator's Guide.



! To define data field mappings

1 In the CI Class Mapping Information window, click the Data Field Mapping tab.

Figure 3-4: CI Class Mapping Information window—Data Field Mapping tab

2 In the table that represents your target, select an attribute to which you want to transfer data.

If the direction of this data mapping is External Data into CMDB, the CI Class Attributes table represents your target. If the direction is CMDB Data into External Data Store, the External Data Store Attributes table represents your target.

WARNING Do not map the same attributes that you mapped for the primary key. The primary key mapping also serves as a data field mapping, so those attribute values are also transferred.

For the sample scenario, you would use the Name attribute in the CI Class Attributes table. This is the BMC_DiskDrive attribute in BMC Atrium CMDB that is the destination of the field mapping.

TIP The fields that are mandatory and must be mapped are displayed in red in the CI Class Attributes table. If you have selected the Restrict to DatasetId option, you do not need to map the DatasetId attribute.


! In the table that represents your source, select the attribute that contains the value that you want to map to the target attribute.

! Using the Rules table, build an expression that provides the value to map to the target by selecting rules. Complete their syntax in the field underneath the table that represents your source.

66 User’s Guide


Depending on the rules that you select, you might need to use one or more source attribute names as part of the syntax. To avoid typing one of these attribute names, you can select it before selecting the first rule.

For example, to create a target value that is a concatenation of the source SerialNumber and PartNumber attributes, you would build the following expression:

function|concat($SerialNumber$, $PartNumber$)

In the sample scenario, the abbreviation that Calbro Services used for the name of the marketing department is changed from “Mktg” to “MKTG.” Calbro Services uses the following rule to make that change in the database for the computer systems used in the marketing department:

function|replace("Mktg", "ktg", upper("ktg"))

In this example, the upper rule is used to change the case of the letters ktg to an uppercase KTG. This example is also an instance of nested rules. You can make BMC Atrium Integration Engine keep the current value of a mapped attribute instead of over-writing it with a NULL value on subsequent data transfers. To do this, build an expression that uses a combination of precedence rules and TargetSQL statements.

In the sample scenario, Calbro Services wants to transfer data from the dbo.ComputerSystem.ResourceID field only if the value is not NULL. Otherwise, they want to keep the value in the target database. They would use the following expression:

{ResourceID}{TargetSQL|Select DatasetID from BMC_DiskDrive where Name = $Name$}

For the sample scenario, you would use the Name attribute in the External Data Store Attributes table. This is the field in the external data store that is the source of the field mapping.

4 Click Add.

The mapping is added to the Mapped Attributes table.

5 If you want to maintain history entries for this target field, select the field in the Mapped Attributes table and click Enable History.

If the Enable History button is not enabled, go to the Options tab and select Yes for the Maintain Change History For Fields option.

This feature is best used on fields that are not likely to change frequently.

6 Repeat steps 2 through 5 to create mappings for each attribute that you want to populate in a data transfer.

For the sample scenario, you would create mappings for the serial number, part number, and associated computer attributes.

7 Click Save.



Your data field mappings are complete. You can enable and disable a data field mapping to debug a data exchange by selecting it in the Mapped Attributes table and clicking Enable or Disable. If a particular field causes problem when a data exchange is run, you can temporarily disable it.

Setting response fields

The Response Field Mapping tab enables you to specify fields that are updated in the source record after a record is created or updated in the target.

Best practice

Typically, you use a response field when a value is generated at the time a target record is created or modified, and you want that value stored in the source record. For example, you might need to store the ID number of the target record just created, or you might want to update a time stamp in the source data indicating the time that a transfer took place.

68 User’s Guide


! To set response fields

1 In the CI Class Mapping Information window, click the Response Field Mapping tab.

Figure 3-5: CI Class Mapping Information window—Response Field Mapping tab

The Mapped Attributes table lists all response fields defined for the data mapping.

2 In the table that represents your source, select an attribute to serve as your response field.

If the direction of this data mapping is External Data into CMDB, the External Data Store Attributes table represents your source. If the direction is CMDB Data into External Data Store, the CI Class Attributes table represents your source.

TIP The fields that are mandatory and must be mapped are displayed in red in the CI Class Attributes table.


! In the table that represents your target, select the attribute that contains the value that you want to use as a response.

! Using the Rules table, build an expression that provides the value to use as a response by selecting rules. Complete their syntax in the field underneath the table that represents your target.

Depending on the rules that you select, you might need to use one or more target attribute names as part of the syntax. To avoid typing one of these attribute names, you can select it before selecting the first rule.



For example, to create a response value that is a concatenation of the status of the last transferred record and the time of that transfer, you would build the following expression:

function|concat(function|status(), function|currentTime())

4 Click Add to add the response field to the Mapped Attributes table.

5 Repeat steps 2 through 4 for each response field that you want to create.

6 Click Save.

Defining delete field mappings

The Delete Field Mapping tab enables you to update a record in the target when its corresponding record has been deleted in the source. These mappings can update any attribute in the target.

NOTE The mappings on this tab are unavailable if the If a Record Is Deleted From Source option on the Main tab is set to Permanently Delete or if the same option on the associated data exchange is set to Do not delete. To define delete field mappings, you must set these options to Mark as Deleted and Delete according to data mapping, respectively.

70 User’s Guide


! To define delete field mappings

1 In the CI Class Mapping Information window, click the Delete Field Mapping tab.

Figure 3-6: CI Class Mapping Information window—Delete Field Mapping tab

2 Select an attribute from the CI Class Attributes table or External Data Store Attributes table.

Only the table that corresponds to your target for this data mapping is shown.


3 Select a rule from the Rules table and, if necessary, complete its syntax in the field underneath the Rules table.

Remember that you cannot include values of source attributes for a delete field mapping because the source record does not exist.

4 Click Save.



Defining queries

Queries enable you to limit the exchange of data that meets certain criteria. You can create a query for BMC Atrium CMDB, the external data store, or both.

NOTE If you do not use the Query tab, all the data in the data source is transferred and all records are eligible for updates, responses, and delete actions.

TIP To update only records that have changed in the source since the previous data transfer, you do not need to use a query. To accomplish this, use the Only New or Updated Since Last Transfer option on the Options tab, as described in step 7 on page 81.

Table 3-1 shows the query types that are supported for BMC Atrium CMDB classes.

Table 3-1: Supported query types

Query type Description

Data key query The AIE service obtains the list of rows to be transferred in a data exchange from both BMC Atrium CMDB and the external data store adapter. When a data key query is defined, only rows that meet the search criteria defined by the key query are obtained and included in the data exchange.You can configure queries for BMC Atrium CMDB, the external data store, or both. BMC Atrium CMDB query syntax is defined by the AIE service. The external data store query syntax is defined by the external data store. The buttons above the External Data Store Query field are provided as a convenience, but they might not be supported by the external data store’s query syntax.

Note: When using event-driven mode, data key queries are ignored.

Update query An update query is a row-level query applied only to target rows that should be updated with modified data from the source. Each target row is updated only if it meets the query condition.

72 User’s Guide

Defining queries

Defining a data key queryYou can define data key queries to limit the number of rows transferred.

! To define a data key query

1 In the CI Class Mapping Information window, click the Query tab.

Figure 3-7: CI Class Mapping Information window—Data Key Query tab

2 On the Data Key Query tab, define the search criteria in the CMDB Query and External Data Store Query fields, to limit the data retrieved by using the following steps:

a Click CI Class Fields or External Data Store Fields to enter a valid field in the query statement.

NOTE The External Data Store Query uses SQL syntax specific to your external data store. It does not use the BMC Remedy Action Request System (BMC Remedy AR System) syntax like other query fields.

Response query

A response query is a row-level query applied only to source rows that should be updated with response values. Each source row is updated only if it meets the query condition.

Delete query A delete query is a row-level query applied only to target rows that should be acted upon as a result of their source rows being deleted. Possible actions include deleting the target row, marking the target row as deleted, and updating it with values from a delete field mapping. These actions take place only if the target row meets the query condition.

Table 3-1: Supported query types (Continued)




b Click Rules to access menus that include valid functions.

NOTE The SRC field is prefixed to the external data store field when the data is transferred from the external data store to BMC Atrium CMDB or BMC Remedy AR System. When the data is transferred from BMC Atrium CMDB or BMC Remedy AR System to the external data store, the SRC field is prefixed to their fields.

For example, to select records for an External Data into CMDB mapping where a date field in your external data store named JDATETIME matches a BMC Atrium CMDB Date/Time attribute named JDateTime, enter this query:

$JDateTime$ = "$SRC|JDATETIME$"

3 Click Save.

Defining an update queryYou can define an update query to limit the number of target rows updated.

! To define an update query


2 Click the Update Query tab.

Figure 3-8: CI Class Mapping Information window—Update Query tab

74 User’s Guide

Defining queries

3 In the Target Row Query field, define search criteria against which each target row of data is compared before it is updated by using the following steps:


NOTE The External Data Store Query uses SQL syntax specific to your external data store. It does not use BMC Remedy AR System syntax like other query fields.



In the sample scenario, Calbro Services uses the following rule to restrict the number of rows to be updated:

$SRC|Description$!="Description"

4 Click Save.

Following is another example of an update query:

$SRC|EMPNAME$ = 'JOHN SMITH' AND ($EmployeeId$ = 1 OR $EmployeeId$ = 2)

Here EMPNAME is a field in the source and is prefixed by SRC|. The destination field is not prefixed by SRC|. If records match the qualifier, the record is updated in BMC Atrium CMDB.



Defining a response queryYou can define a response query to limit the number of source rows updated with values from the target.

! To define a response query


2 Click the Response Query tab.

Figure 3-9: CI Class Mapping Information window—Response Query tab

3 In the Source Row Query field, define search criteria against which each source row is compared by using the following steps. If a source row meets the search criteria, it is updated with a response value.




4 Click Save.

76 User’s Guide

Defining queries

Defining a delete queryYou can define a delete query to limit the number of target rows acted upon as a result of source rows being deleted.

! To define a delete query


2 Click the Delete Query tab.

Figure 3-10: CI Class Mapping Information window—Delete Query tab

3 In the Target Row Query field, define search criteria against which each target row of data is compared to determine if that row is to be deleted by using the following steps:




4 Click Save.



Setting data mapping options

You can use the Options tab on the CI Class Mapping Information window to set several preferences for the data mapping.

! To set data mapping options

1 In the CI Class Mapping Information window, click the Options tab.

Figure 3-11: CI Class Mapping Information window—Options tab

78 User’s Guide


2 Select a value for the If Some Fields Cause Errors During Transfer option.

This option specifies what action to take if an error prevents data from being obtained for one or more mapped fields for a given record. Values are as follows:

! Do not transfer record—The entire record is not transferred to the target.

! Transfer record with remaining fields—All fields for which data can be obtained are transferred for the record.

Following are some examples of circumstances under which data cannot be obtained:

! The data is not the same type in the BMC Remedy AR System database and in the external data store. An attempt to convert the data fails.

! A function has an invalid parameter, so the value cannot be generated.

! An sql or process command returns an error instead of a data value.

For example, Calbro Services wants to transfer personal records of their employees from the Dublin site to the centralized New York site. However, if an error occurs while transferring an attribute of a record, they do not want to transfer the remaining attributes of that record. That is why Calbro Services selects the Do Not Transfer Record option.

3 Select a value for the If a Field Contains Only Blanks option.

This option specifies how to handle a source field that contains nothing but one or more blank spaces. Values are as follows:

! Transfer as it is—The blank spaces are transferred to the target record.

! Transfer as NULL—The field is set to NULL in the target record.

4 Select a value for the While Comparing Primary Key Values option.

This option specifies whether trailing blanks and tabs are considered when BMC Atrium Integration Engine compares primary keys to match records between the source and target. Some applications treat trailing blanks and tabs as characters; others ignore them. Values are as follows:

! Ignore trailing blanks—Blank spaces at the end of a primary key and tabs are ignored in a comparison. For example, “Acme” and “Acme ” would match.

! Consider trailing blanks—Blank spaces at the end of a primary key and tabs are considered in a comparison. For example, “Acme” and “Acme ” would not match.

Select this option if your primary key is of the character data type.



5 Select a value for the Maintain Change History for Fields option.

This option specifies whether a history of detected changes to a record is maintained in a specified diary attribute in the CI class. This option is available only when the direction of the data mapping is External Data into CMDB.

If you select Yes, the Store History In list is enabled. You can select the History or Notes attribute in which to store history entries. You cannot map any other value to the selected attribute on the Data Field Mapping tab. A new diary entry is written for a record when it is created and each time it is updated.

If you select No, history is not maintained for this class.

6 Select a value for the Update Record Only If Checksum for Mapped Field Has Changed option.

A checksum is a unique value generated by BMC Atrium CMDB when records from an external data store are inserted into BMC Atrium CMDB. If this option is selected, a checksum is calculated at each data transfer. It is then compared with the checksum value from the previous transfer.

This option specifies whether all target records are updated, or only those records that have changed in the source as determined by the checksum calculated from the values of all mapped fields. This option is available only when the direction of the data mapping is External Data into CMDB.

If you select Yes, the Calculate and Store Checksum In list is enabled. Specify an integer attribute in which to store the checksum. You cannot map any other value to the selected attribute on the Data Field Mapping tab. The checksum is calculated at each data transfer and compared to the one stored in this attribute from the previous transfer.

If you select No, the checksum is not calculated and all target records are updated, subject to the data key queries and update queries that you have defined.

For example, Calbro Services has populated the New York database with records from the Adelaide database. When Calbro Services wants to run data exchanges to duplicate the updated records from the Adelaide database into the New York database, they select the Yes value for the Update Record Only If Checksum for Mapped Field Has Changed option. During a data exchange, the checksum was calculated for 500 computer system records. The TotalPhysicalMemory attribute of only 62 computer systems was changed. The checksum calculated for the 62 computers was found to be changed since the last data transfer. So, only 62 records were updated during the data exchange.

80 User’s Guide


7 Select a value for the Retrieve Source Records option.

This option enables you to select whether to retrieve only new or updated data since the last successful data transfer was run. This option is available only when the direction of the data mapping is External Data into CMDB. Values are as follows:

! Only New or Updated Since Last Transfer—If you select this option, the Last Modified Timestamp in Source list field is enabled. Select the DateTime field in your source that holds the time stamp from when each record was last modified. During each data transfer, the only records retrieved from the source are new records and those with a last modified time stamp that is later than the most recent successful transfer.

NOTE If you select this option, the If a Record is Deleted from Source option is set to Mark as deleted for the data mapping and to Do not delete for the data exchange it is associated to.

! All—All source records are retrieved for each data transfer.

WARNING Do not select the Only New or Updated Since Last Transfer option if your external data store is a flat file. This option is not applicable for flat files.

The Retrieve Source Records option works just like the Update Record Only If Checksum for Mapped Field Has Changed option. However, if you use the Only New or Updated Since Last Transfer option for Retrieve Source Records, you cannot use the delete options for data mappings and data exchanges for CI classes.

8 Click Save.

After you have created a data mapping, you must assign it to a data exchange to use it. For instructions, see “Assigning data mappings” on page 143.



82 User’s Guide

Chapter

4
Creating data mappings for BMC Atrium CMDB relationship classes
A data mapping for a BMC Atrium Configuration Management Database (BMC Atrium CMDB) relationship class defines how relationships are created between instances of CI classes that are transferred to BMC Atrium CMDB.


! Overview of the relationship data mapping process (page 84)! Methods for mapping relationship classes (page 85)! High-level steps in the relationship data mapping process (page 89)! Defining data mapping parameters (page 90)! Defining relationship keys (page 94)! Defining attribute field mappings (page 97)! Defining delete field mappings (page 100)! Defining queries (page 100)! Setting data mapping options (page 104)



Overview of the relationship data mapping process

Much of the value of BMC Atrium CMDB comes from the ability to store information about the relationships between configuration items (CIs), not just information about the CIs themselves.

Based on the example in “Example CMDB data scenario” on page 54, you would have defined a data mapping for the BMC_DiskDrive CI class that contains an attribute called AssociatedComputer. This attribute associates an instance of a disk drive with an instance of a computer. For example, disk 1520 in the Disk Drive table is associated with computer 910 in the Computer table.

You also would have defined a data mapping for the BMC_ComputerSystem CI class that contains an attribute called Name. This attribute defines the name of a computer that you have in inventory.

Because each disk drive in your company is associated with a computer, you can then create a data mapping for the BMC_HostedSystemComponents relationship class that associates a particular instance of BMC_DiskDrive with a particular instance of BMC_ComputerSystem. In this case, the AssociatedComputer attribute in the BMC_DiskDrive class and the Name attribute in the BMC_ComputerSystem class contain the data necessary to create the relationship.

Each relationship class in BMC Atrium CMDB defines one CI class as the source member of the relationship and another CI class as the destination member of the relationship. In the BMC Atrium Integration Engine interface, these are referred to as primary and secondary members. The relationship can be instantiated using one CI instance of each of these classes or any of their subclasses. In this case, BMC_ComputerSystem is the source (primary) member and BMC_DiskDrive is the destination (secondary) member of the BMC_HostedSystemComponents relationship class. For more information about relationship classes, see the BMC Atrium Core 7.6.04 Concepts and Planning Guide.

NOTE The data exchanges that bring data from the external data store into the CI classes (in this case BMC_DiskDrive and BMC_ComputerSystem) must finish before the data exchange for the relationship class can run, because the instance IDs of related CIs are needed for their relationship instance. You can accomplish this by using an event-driven data exchange for the relationship class and activating the exchange only after your CI class exchanges have completed, or by using a schedule-driven exchange with the To Be Triggered option and triggering it when the last CI class data exchange has completed.

Multiple data mappings are not supported for the data exchanges for BMC Atrium CMDB relationship classes.

84 User’s Guide

Methods for mapping relationship classes

Methods for mapping relationship classesYou can create data mappings for a relationship class based on attributes in the CI classes that are members of the relationship or based on relationship data stored in the external data store.

Attributes in the member CI classesFigure 4-1 presents an example of a data mapping based on attributes in the CI classes.

Figure 4-1: Data mapping based on attributes in both CI classes

For each BMC_DiskDrive instance, a match between its AssociatedComputer value and the Name value in a BMC_ComputerSystem instance causes the creation of a BMC_HostedSystemComponents relationship between the two CIs.

The instance IDs of these member CIs are stored in the relationship instance as Source.InstanceId for the BMC_ComputerSystem instance and Destination.InstanceId for the BMC_DiskDrive instance.

Disk Drive tableName OrderId AssociatedComputerDisk 1520 D2648 Computer 910Disk 1523 D2649 Computer 912Disk 1560 D2650 Computer 921Disk 1534 D2651 Computer 954Disk 1530 D2652 Computer 911

Computer tableName OrderIdComputer 910 C6648Computer 912 C6649Computer 921 C6650Computer 954 C6651Computer 911 C6652

BMC_HostedSystemComponentsSource.InstanceId Destination.InstanceId

1F8FEF67A 1F6ABC21F1F8FBE71C 1B3CFA89D1E6A2C5AF 1E8AFB71E1C4E8A2FF 1A2CAC48F1A2B2C5CD 1F5AFE19A

BMC_DiskDriveName OrderId AssociatedComputer InstanceIdDisk 1520 D2648 Computer 910 1F6ABC21FDisk 1523 D2649 Computer 912 1B3CFA89DDisk 1560 D2650 Computer 921 1E8AFB71EDisk 1534 D2651 Computer 954 1A2CAC48FDisk 1530 D2652 Computer 911 1F5AFE19A

BMC_ComputerSystemName OrderId InstanceIdComputer 910 C6648 1F8FEF67AComputer 912 C6649 1F8FBE71CComputer 921 C6650 1E6A2L5AFComputer 954 C6651 1C4E8A2FFComputer 911 C6651 1A2B2C5CD

Externaldatastore

BMC AtriumCMDB

RelationshipClass

Mapping

Data Mapping

Data Mapping



Best practice

Use this method if you use the Only New or Updated Since Last Transfer value of the Retrieve Source Records option. When you select the Retrieve Source Records option and you use the class-based relationship mapping, the changed records from the last execution of a data exchange are captured when you run the data exchange again. This improves performance. When you use a class-based relationship mapping, you can use the Retrieve Source Records option with If a Record is Deleted from Source option in a data exchange.

For more information about the retrieve delta feature, see “Enhanced retrieve delta feature for relationship exchanges” on page 183.

“To define relationship keys with CI classes as source” on page 95 explains how to implement this method.

Data in an external data storeYou can create a data mapping for a relationship class based on relationship data stored in the external data store.

To create a data mapping, you have to define a relationship key. For this method, the relationship key must match an attribute from each member CI class to an attribute in the external data store. For more information about defining a relationship key, see “To define relationship keys with an external data store as source” on page 96.

This method compares attributes between each CI class and the external data store. The instance IDs of these member CIs are stored in the relationship instance as Source.InstanceId and Destination.InstanceId. If no attribute values correspond, no relationship instance is created.

86 User’s Guide

Methods for mapping relationship classes

Figure 4-2 and Figure 4-3 present an example of a data mapping based on relationship data stored in an external data store in two stages.

Figure 4-2: Stage I of creating a data mapping based on relationship data stored in an external data store

In Stage 1, the Name attribute from the Computer Information table from the external data store is mapped to the Name attribute of the BMC_ComputerSystem class. Instance IDs for individual members of the BMC_ComputerSystem class are generated. The Name attribute from the Disk Drive Information table from the external data store is mapped to the Name attribute in the BMC_DiskDrive class. Instance IDs for individual members of the BMC_DiskDrive class are also generated. In this stage, no relationship is created.



Figure 4-3: Stage II of creating a data mapping based on relationship data stored in an external data store

In Stage 2, when the data exchange runs, a match is found between the values of the AssociatedComputer attribute from the Disk Drive Information table and the Name attribute from the BMC_ComputerSystem class.

When attributes from a data table in an external data store correspond between two CI classes in BMC Atrium CMDB, a relationship is created between the two CI classes in BMC Atrium CMDB.

In this example, attributes from the Disk Drive Information table in the external data store correspond to the attributes in the BMC_ComputerSystem and BMC_DiskDrive tables in BMC Atrium CMDB. A relationship is thus created between BMC_ComputerSystem and BMC_DiskDrive. This relationship is stored in the BMC_HostedSystemComponents relationship class.

BMC_ComputerSystem becomes the source class and BMC_DiskDrive becomes the destination class for the relationship mapping. The instance IDs of the member CIs are stored in the BMC_HostedSystemComponents relationship class as Source.InstanceId and Destination.InstanceId for BMC_ComputerSystem and BMC_DiskDrive.

Best practice

BMC recommends that you use this method for many-to-many relationship mappings. When you populate the data in the primary and secondary classes, you can define the relationships in an external database table or in a file that defines the mapping of an attribute and an equivalent column.

88 User’s Guide

High-level steps in the relationship data mapping process

High-level steps in the relationship data mapping process


You must specify the mapping name, relationship source, external data store, relationship information, and delete options. For more information, see “Defining data mapping parameters” on page 90.

Step 2 Define the relationship key.

You must specify the primary key in the CI classes that you want to use to create the relationship mapping. For more information, see “Defining relationship keys” on page 94.

Step 3 Define the attribute field mappings.

You can map other data to attributes of your relationship instances. For more information, see “Defining attribute field mappings” on page 97.




You can create queries for BMC Atrium CMDB and external data stores to limit the transfer of data to meet certain criteria. You can create data key, update, response, and delete queries. For more information, see “Defining queries” on page 100.





Before you begin

Make sure that you have standardized the data. For more information, see “Before creating data mappings” on page 55.



If your external data store is a DB2 UDB, Oracle, or Microsoft SQL Server database, creating a data mapping is easier and faster if you populate the database field menus in the Relationship Class Mapping Information window with values from your database. This allows you to select the columns of your database tables from a list instead of typing them on the mapping and query tabs of the window.

TIP For instructions on populating database field menus, see “Populating database field menus” on page 39.

Before you begin


! To define data mapping parameters for a relationship class

1 With BMC Remedy User, log in to the server where BMC Atrium Integration Engine is installed.




90 User’s Guide


4 On the navigation pane, select Integration Objects > Relationship Class Mappings.

The Relationship Class Mapping Console appears.

Figure 4-4: Relationship Class Mapping Console

5 Click New.

The Relationship Class Mapping Information window appears.

Figure 4-5: Relationship Class Mapping Information window

6 In the Mapping Name field, type a name for your mapping.

In the sample scenario, Calbro Services uses Computer Disk Drive Relationship Mapping.

7 Perform one of the following actions for the Relationship Source option:

! Select the CI Class option if the relationship data is stored in the CI classes as explained in “Attributes in the member CI classes” on page 85.



! Select the External Data Store option if the relationship data is stored in an external data store as explained in “Data in an external data store” on page 86.

If you choose this option, enter the appropriate external data store and table or file in the External Data Store field and the Table Name or File Name field, respectively. The list associated with this field contains all external data objects that have been previously used in a data exchange.


DB2 UDB: DatabaseOwner.TableName

Oracle: DATABASEOWNER.TABLENAME

SQL Server: DBO.TableName

! For File Name, specify the absolute path to your file but do not include the extension in its name. For example, you might specify this for a ComputersDiskDrives.dat file:

C:\Program Files\BMC Software\BMC Atrium Integration Engine\myserver-0\service\data\ComputersDiskDri9999ves

For information about preparing your flat files for the data transfer, see “Transferring data from flat files” on page 56. For information about preparing your .xml files for the data transfer, see “Transferring data from .xml files” on page 57.

NOTE XML adapters support only class based relationship mapping. For more information, see “Accessing parent record elements along with child record elements from an XML file” on page 62. Though you cannot use an .xml file as the source for external data store relationship mappings, you can create CI mappings that specify relationships. To do this, create a mapping for the child CIs and a separate mapping for the parent CIs. In the child CI mapping, use a foreign key to reference the parent CIs. Then set the child exchange to be triggered by the parent exchange.

A relationship class mapping can bring data only into BMC Atrium CMDB, so the Direction field is unavailable.

92 User’s Guide


8 If you want to use this data mapping to transfer data to or from more than one BMC Atrium CMDB dataset, leave the Restrict to DatasetId option cleared. Otherwise, select it and choose the dataset that you want to use from the list.

WARNING If you do not select this option, you must create attribute field mappings for the DatasetId, Source.DatasetId, and Destination.DatasetId attributes of your class. Without these mappings, BMC Atrium Integration Engine does not know which dataset the data should be transferred to (or from), and your data transfer fails. For more information, see “Defining attribute field mappings” on page 97.

For more information about datasets, see “Datasets” on page 30.

9 In the If a Record Is Deleted From Source field, choose an option.

This option takes effect if this mapping is used with a data exchange that has its If a Record Is Deleted From Source option set to Delete according to data mapping. If the data exchange is set to Do not delete, no delete action is taken regardless of this setting in the data mapping. Values are as follows:

! Mark as deleted—When a record has been deleted from the source, the equivalent record in the target remains but is marked as deleted by setting the MarkAsDeleted attribute to Yes. BMC recommends this setting because it prevents orphan instances in your production dataset and because it reduces the likelihood of duplicate instances should the record later be reestablished on the source.

! Permanently delete—When a record has been deleted from the source, the equivalent record in the target is physically deleted. BMC Atrium CMDB has no way to re-create a deleted instance. You might select this option if you are importing data to a dataset that does not undergo reconciliation.

NOTE This option depends on a setting in the data exchange used with this data mapping. See the option If a Record Is Deleted From Source on the Main tab of the Data Exchanges Information window. If that option is set to Delete according to data mapping, the selection you make here takes effect. If instead the data exchange is set to Do not delete, no delete action is taken regardless of this setting in the data mapping.

10 In the Namespace list, select the namespace of the class to which you intend to transfer data.

In the sample scenario, Calbro Services uses BMC.CORE.

11 In the Relationship Class Name list, select the class to which you intend to transfer data.

In the sample scenario, Calbro Services uses BMC_HostedSystemComponents.

12 In the Primary Class list, select the CI class to use as the source member of the created relationship instances.

In the sample scenario, Calbro Services uses BMC_ComputerSystem.



13 In the Secondary Class list, select the CI class to use as the destination member of the created relationship instances.

In the sample scenario, Calbro Services uses BMC_DiskDrive.

14 Click Create.

The Relationship Class Mapping Information window expands to include the Relationship Keys Mapping, Attribute Field Mapping, Delete Field Mapping, Query, and Options tabs. The fields shown on the Relationship Class Mapping Information window depend on which Relationship Source option you selected.

Defining relationship keys

You use the Relationship Keys Mapping tab to specify the primary key in the CI classes that you want to use to create the relationship mapping. If your Relationship Source is CI Class, follow the steps in “To define relationship keys with CI classes as source” on page 95. If your Relationship Source is External Data Store, follow the steps in “To define relationship keys with an external data store as source” on page 96.

When you specify the relationship key, make sure that you select attributes from the primary (source) and secondary (destination) classes. Select an attribute from the primary class first and then from the secondary class.

WARNING The only attributes of the relationship that are populated as a result of defining relationship keys are Source.InstanceId, Source.ClassId, Destination.InstanceId, and Destination.ClassId. You must manually map other attributes of member CIs to the relationship using the Attribute Field Mapping tab as described in “Defining attribute field mappings” on page 97.

94 User’s Guide

Defining relationship keys

! To define relationship keys with CI classes as source

1 In the Relationship Class Mapping Information window, click the Relationship Keys Mapping tab.

The tab shows the fields for creating a relationship key mapping based on a primary key in the relationship’s member CI classes, which for the sample scenario are BMC_ComputerSystem and BMC_DiskDrive.

Figure 4-6: Relationship Class Mapping Information window—Relationship Keys Mapping tab for CI class source

2 Select an attribute from the Primary Class Attributes table.

WARNING Do not map the same attribute that you mapped for the relationship key.

In the sample scenario, Calbro Services uses Name.

When class attributes are updated in BMC Atrium CMDB, BMC Atrium Integration Engine automatically updates the attributes in the CI Class Attributes table when you create a new mapping or open an existing data mapping.

3 Select an attribute from the Secondary Class Attributes table.

In the sample scenario, Calbro Services uses AssociatedComputer.

NOTE In the scenario, the BMC_DiskDrive CI class does not contain an attribute for the associated computer by default. You would need to add the AssociatedComputer attribute by using the Class Manager in BMC Atrium CMDB. Otherwise, this attribute would not appear in the Secondary Class Attributes table. See the BMC Atrium CMDB 7.6.04 Administrator's Guide for instructions on creating an attribute.

4 Click Add to add this attribute pair to the Mapped Attributes table.



5 If you want to match more attribute values before a relationship is created, repeat steps 2 through 4.

When you have a primary key with more than one attribute from each side, the expressions are joined together with an AND operator. That means a data row in the external data store matches an instance in BMC Atrium CMDB only if each pair of attributes in the primary key matches.

6 Click Save.

When the value of all mapped attributes matches between an instance of the primary CI class and an instance of the secondary CI class, a relationship is created between the instances.

! To define relationship keys with an external data store as source

1 In the Relationship Class Mapping Information window, click the Relationship Keys Mapping tab.

The tab shows the fields for creating a relationship key mapping based on data stored separately in an external data store. In this case, you must define a separate relationship between a given primary key in the external data store and a primary key in the CI classes.

Figure 4-7: Relationship Class Mapping Information window—Relationship Keys Mapping tab for external data store source

2 In the External Data Store Attributes table, select an attribute.

96 User’s Guide

Defining attribute field mappings

3 From the list above the CI Class Attributes table, select the primary CI Class, and then from the table select an attribute from that class.


When class attributes are updated in BMC Atrium CMDB, BMC Atrium Integration Engine automatically updates the attributes in the CI Class Attributes table when you create a new mapping or open an existing data mapping.

4 Click Add to add the attribute pair to the Mapped Attributes list

5 Repeat steps 2 through 4 to map an external data store attribute to an attribute from the other CI class that is a member of the relationship.

6 Click Save.

When the value of these mapped attributes for a record in the external data store matches an instance of the primary CI class and an instance of the secondary CI class, a relationship is created between the instances.


You use the Attribute Field Mapping tab to map other data to attributes of your relationship instances beyond the instance IDs and class IDs of their member CIs, which are automatically populated by BMC Atrium Integration Engine.



WARNING You must map a value to the attributes in Table 4-1 or your relationship instances cannot be created.

You might choose to map values to additional attributes of the relationship class, depending on the information that you want to store for this type of relationship.

Table 4-1: Relationship attributes that must be manually mapped

Relationship class attribute Source attribute or value to map Example mapping from sample scenario

DatasetId1

1. This attribute field mapping is required only if the Restrict to DatasetId option is not selected for the data mapping.

ID of the dataset where the relationship should be created.

BMC_ComputerSystem.DatasetId -> BMC_HostedSystemComponents.DatasetIdThis puts the relationship in the same dataset as the member CIs.

Destination.DatasetId1

DatasetId of the secondary CI class

BMC_DiskDrive.DatasetId -> BMC_HostedSystemComponents.Destination.DatasetId

Name The appropriate value for the type of relationship that you are creating. For a list of potential values, see the Relationship Normalization Table in Mapping Your Data to BMC Atrium CMDB 7.6.04 Classes.

constant|SYSTEMHARDWARE -> BMC_HostedSystemComponents.Name

Source.DatasetId1 DatasetId of the primary CI class

BMC_ComputerSystem.DatasetId -> BMC_HostedSystemComponents.Source.DatasetId

98 User’s Guide


! To define attribute field mappings

1 In the Relationship Class Mapping Information window, click the Attribute Field Mapping tab.

Figure 4-8: Relationship Class Mapping Information—Attribute Field Mapping tab

2 In the Relationship Class Attributes table, select an attribute.

TIP The fields that are mandatory and must be mapped are displayed in red in the Relationship Class Attributes table.

WARNING Do not map the same attributes that you mapped for the primary relationship key. The primary relationship key mapping also serves as a data field mapping, so those attribute values are also transferred.

3 From the list above the CI Class Attributes table, select a CI Class, and then from the table select an attribute from that class.


4 Click Add to add the attribute pair to the Mapped Attributes list

5 Repeat steps 2 through 4 to map each relationship class attribute listed in Table 4-1 on page 98.

6 Click Save.

Your attribute field mappings are complete. You can enable and disable an attribute field mapping to debug a data exchange by selecting it in the Mapped Attributes table and clicking Enable or Disable. If a particular field causes problems when a data exchange runs, you can temporarily disable it.




You use the Delete Field Mapping tab of the Relationship Class Mapping Information window to update a record in the target when its corresponding record has been deleted in the source. These mappings can update any attribute in the target.

This feature works the same for relationship classes as it does for CI classes. For information about defining delete field mappings, see “Defining delete field mappings” on page 70.

Defining queries

Queries enable you to limit the exchange of data that meets certain criteria.

NOTE If you do not use the Query tab, all the data in the external data store is transferred.

TIP To update only those records that have changed in the source since the previous data transfer, you do not need to use a query. To accomplish this, use the Only New or Updated Since Last Transfer option on the Options tab, as described in step 6 on page 106.

100 User’s Guide

Defining queries

Table 4-2 shows the query types that are supported for BMC Atrium CMDB relationship classes.

Defining a primary class queryYou can define a primary class query to limit the instances of the primary CI class used to create relationship instances.

! To define a primary class query

1 On the Query tab of the Relationship Class Mapping Information window, click the Primary Class Query tab.

Figure 4-9: Relationship Class Mapping Information window—Primary Class Query tab

2 On the Primary Class Query tab, click Select Primary Class Attributes, and define search criteria in the Query field to limit the data retrieved from the primary CI class.



Primary class query Filters out instances of the primary CI class, which are used to create the relationship.

Secondary class query

Filters out instances of the secondary CI class, which are used to create the relationship.

Relationship class query

Filters out instances of the relationship class.

External data store query

Filters out instances from the external data store, which are used to create the relationship when using the external data store as your relationship source.




For example, to select records for an External Data into CMDB mapping where a date field in your external data store named JDATETIME matches a BMC Atrium CMDB Date/Time attribute named JDateTime, enter this query:


3 Click Save.

Defining a secondary class queryYou can define a secondary class query to limit the instances of the secondary CI class used to create relationship instances.

! To define a secondary class query

1 On the Query tab of the Relationship Class Mapping Information window, the Secondary Class Query tab.

Figure 4-10: Relationship Class Mapping Information window—Secondary Class Query tab

2 Define the search criteria in the Query field to limit the data retrieved from the secondary CI class.

3 Click Save.

102 User’s Guide

Defining queries

Defining a relationship class queryYou can define a relationship class query to limit the instances of the relationship class that are updated in the target.

! To define a relationship class query

1 On the Query tab of the Relationship Class Mapping Information window, click Relationship Query tab.

Figure 4-11: Relationship Class Mapping Information window—Relationship Class Query tab

2 Click Select Relationship Class Attributes, and define search criteria in the Query field to limit the data retrieved from the relationship class.

For example, type $AccountID$=”Acme”

3 Click Save.



Defining an external data store queryYou can define an external data store query to limit the number of rows in the external data store for providing relationship information.

! To define an external data store query

1 On the Query tab of the Relationship Class Mapping Information window, click the External Data Store Query tab.

Figure 4-12: Relationship Class Mapping Information window—External Data Store Query tab

2 On the External Data Store Query tab, click Select Attributes, and define search criteria in the Query field to limit the data retrieved from the external data store.

For example, type $Class1ID$=”Acme”

3 Click Save.



1 In the Relationship Class Mapping Information window, click the Options tab.

104 User’s Guide


Figure 4-13: Relationship Class Mapping Information window—Options tab


This option specifies which action to take if an error prevents data from being obtained for one or more mapped fields for a given record. Values are as follows:




! The data is not the same type in the BMC Remedy Action Request System (BMC Remedy AR System) database and in the external data store. An attempt to convert the data fails.










This option specifies whether trailing blanks and tabs are considered when BMC Atrium Integration Engine compares primary keys to match records between the source and target. Some applications treat trailing blanks and tabs as characters; others ignore trailing blanks. Values are as follows:




This option specifies whether all target records are updated, or only those records that have changed in the source as determined by a checksum calculated from the values of all mapped fields.

If you select Yes, the Calculate and Store Checksum In list is enabled. Select an integer attribute in which to store the checksum. This attribute must already exist in the relationship class, and you cannot map any other value to it on the Attribute Field Mapping tab. The checksum is calculated at each data transfer and compared to the one stored in this attribute from the previous transfer.

If you select No, the checksum is not calculated and all target records are updated, subject to any queries that you have defined.

For example, Calbro Services selected Yes for this option. Calbro Services ran a relationship data exchange with BMC_ComputerSystem class as the source and BMC_Software as the destination to update the existing data in the New York database. BMC Atrium Integration Engine calculated the checksum for 500 records and found that the ServicePack attribute of the BMC_Software class for 250 computer systems was changed. BMC Atrium Integration Engine found that the checksum calculated for the 250 computers was changed since the last data transfer. So, BMC Atrium Integration Engine updated only 250 records during the data exchange.


This option enables you to select whether to retrieve only new or updated data since the last successful data transfer was run. Values are as follows:

! Only New or Updated Since Last Transfer—All records from the primary and secondary classes that were changed after the last successful data transfer are retrieved. The ModifiedDate attribute name is displayed in the Last Modified Timestamp in Source field.

106 User’s Guide


NOTE You can use this option in conjunction with the delete options only for a class-based relationship mapping. Do not select the Only New or Updated Since Last Transfer option if your external data store is a flat file. This option is not applicable for flat files. For flat files, make sure that you select All for the Retrieve Source Records option.


For more information about the retrieve delta setting, see “Enhanced retrieve delta feature for relationship exchanges” on page 183.

7 Click Save.




108 User’s Guide

Chapter

5
Creating data mappings for BMC Remedy AR System forms
A data mapping defines how data in the source corresponds to data in the target and which actions to take when transferring between them. This section provides instructions for creating data mappings between an external data store and the fields on a BMC Remedy Action Request System (BMC Remedy AR System) form.


! Overview of the data mapping process for BMC Remedy AR System forms (page 110)

! Defining data mapping parameters (page 111)! Defining the primary key (page 116)! Defining data field mappings (page 118)! Setting response fields (page 120)! Defining delete field mappings (page 122)! Defining queries (page 123)! Setting data mapping options (page 129)! Populating the rule control (page 132)



Overview of the data mapping process for BMC Remedy AR System forms


You must specify the mapping name, direction, BMC Remedy AR System form, external data store, and delete options. For more information, see “Defining data mapping parameters” on page 111.

Step 2 Define the primary key.

You must specify the primary key that uniquely identifies a row of data. Attributes from an BMC Remedy AR System form and an external data store together constitute a primary key. For more information, see “Defining the primary key” on page 116.

Step 3 Define data field mappings.

You must define data mappings to specify the fields and attributes that should be transferred. For more information, see “Defining data field mappings” on page 118.

Step 4 (optional) Set response fields.

When a record is created or updated in the target, a value is created. You can set response fields to store this value in the source. For more information, see “Setting response fields” on page 120.

110 User’s Guide





You can create queries for BMC Remedy AR System and external data stores to limit the transfer of data to meet certain criteria. You can create data key, update, response, and delete queries. For more information, see “Defining queries” on page 123.



Before you begin

Make sure you standardize the data you are transferring. For more information, see “Before creating data mappings” on page 55.



TIP If your external data store is a DB2 UDB, Oracle, or Microsoft SQL Server database, creating a data mapping is easier and faster if you populate the database field menus in the AR Mapping Information window with values from your database. This allows you to select the columns of your database tables from a list instead of typing them on the mapping and query tabs of the window. For instructions on populating database field menus, see “Populating database field menus” on page 39.



Before you begin


! To define data mapping parameters for BMC Remedy AR System forms





4 On the Data Exchange Console, from the navigation pane, select Integration Objects > BMC Remedy AR System Form Mappings.

Figure 5-1: AR Data Mapping Console

112 User’s Guide


5 On the AR Data Mapping Console, click New.

The AR Mapping Information window appears.

Figure 5-2: AR Mapping Information window

6 On the AR Mapping Information window, in the Mapping Name field, type a data mapping name.

When you create data mappings, make sure that their names are easy to understand. For example, a sample data mapping included with BMC Atrium Integration Engine named FlatFileSamplePull retrieves data from an external file using the flat file adapter.

7 In the Direction field, select the direction in which you are transferring data: either External Data into AR or AR Data into External Data Store.

8 In the BMC Remedy AR System Form field, type or select the name of the BMC Remedy AR System form that you want to use in this data mapping.

If the form does not exist, create it using BMC Remedy Developer Studio.

In the flat file sample data exchange shipped with BMC Atrium Integration Engine, EIE:FlatFileSample is the name of the form used in the data mapping.

After you have mapped to a form once, the field menu includes the form name.

9 In the External Data Store list, select the name of the adapter for the external data store.



10 In the Table Name list (for database adapters) or File Name field (for the flat file and XML adapters), specify the name of the object in the external data store that is referenced in this data mapping.

The list associated with this field contains all of the external data objects that have been previously used in a data exchange.


! DB2: DatabaseOwner.TableName

! Oracle: DATABASEOWNER.TABLENAME

! SQL Server: DBO.TableName

! For File Name, specify the absolute path to your file but do not include the extension in its name. For example, you might specify this for an ExportedComputerSystems.xml file:

C:\Program Files\BMC Software\BMC Atrium Integration Engine\ myserver-0\service\data\ExportedComputerSystems

NOTE Make sure that you do not include more than 100000 records in a single flat file for data mapping. If you add more than 100000 records, performance degrades.

Flat files can be in a .dat or .csv format. If your file does not specify a data type for each field, BMC Atrium Integration Engine interprets them as character fields. A .dat file must have a corresponding .tbl file with the same name located in the same folder to define the columns and delimiter used in the .dat file.

The filehelper utility of BMC Atrium Integration Engine enables you to automatically generate the .tbl file for a .csv file. To generate the .tbl file, make sure that the .csv file and the filehelper utility are available on the same computer. Otherwise, the utility cannot locate the .csv files.

You can find the instructions to create .tbl file in the sample .tbl files in the aieInstallationDir\service\data folder.

NOTE You must manually create a .tbl file for your .dat file.

Likewise, an .xml file must have a corresponding .xsd file with the same name located in the same folder.

114 User’s Guide


11 If this data mapping uses the XML adapter, type the name of the element that identifies each row of data in the Row Element field.

Each row of data that becomes a record in BMC Remedy AR System is enclosed by this element in your .xml file. For example, if your file looked like the following example, you would enter myrecord in the Row Element field.

<class type=”CI”><name>DiskDrive</name><myrecord>


</attributes></myrecord><myrecord>


</attributes></myrecord>

</class>

NOTE When you use special characters in your data, you must specify the encoding type for special characters in the header of your .xml file. If you do not specify the encoding type, no data is transferred.

12 In the If a Record Is Deleted From Source field, choose an option:

! Mark as deleted—When a record has been deleted from the source, the equivalent record in the target can be marked as deleted by delete field mappings that you specify. This option does not automatically mark records in BMC Remedy AR System forms as it does in BMC Atrium Configuration Management Database (BMC Atrium CMDB) classes.

For information about delete field mappings, see “Defining delete field mappings” on page 122.

! Permanently delete—When a record has been deleted from the source, the equivalent record in the target is physically deleted. BMC Remedy AR System has no way to re-create a deleted instance.



NOTE This option depends on a setting in the data exchange used with this data mapping. See the If a Record Is Deleted From Source option on the Main tab of the Data Exchanges Information window. If that option is set to Delete according to data mapping, the selection that you make here takes effect. If instead the data exchange is set to Do not delete, no delete action is taken regardless of this setting in the data mapping.

13 Click Create.

NOTE When you click Create, all fields on the Main tab except for Mapping Name become unavailable, and you can no longer edit this information.

The AR Mapping Information window expands to include tabs for Primary Key Mapping, Data Field Mapping, Response Field Mapping, Delete Field Mapping, Query, and Options.

NOTE When you create a flat file data mapping, the Response Field Mapping tab is unavailable.


Primary keys uniquely identify a row of data. You must specify the fields on the BMC Remedy AR System form and the corresponding fields in the external data store that are primary keys. After a data transfer, the primary key is the link that matches a record in the external data store with its counterpart in BMC Remedy AR System.

116 User’s Guide


! To define primary keys

1 In the AR Mapping Information window, click the Primary Key Mapping tab.

Figure 5-3: AR Mapping Information window—Primary Key Mapping tab

The Mapped Fields table on this window lists all primary keys defined for the data mapping.

NOTE You must define a key to complete a data mapping. The key can contain more than one field from each side.

2 In the AR Form Fields list, select the field from the BMC Remedy AR System form that should be part of this primary key.

WARNING Do not map the same attribute that you mapped for the primary key.

When field attributes are updated in BMC Remedy AR System forms, BMC Atrium Integration Engine automatically updates the attributes in the AR Form Fields table when you create a new mapping or open an existing data mapping.

3 In the External Data Store Attributes table, select an attribute that should be part of this primary key.

4 Click Add to add this pair of fields to the primary key.

The fields appear in the Mapped Fields table.



5 Repeat steps 2 through 4 for each primary key field that you want to map.

When you have a primary key with more than one field from each side, a data row in the external data store matches a row in BMC Remedy AR System only if each pair of fields in the primary key matches.

When you have a primary key with more than one field from each side, the expressions are joined together by an AND operator. That means a data row in the external data store matches a row in BMC Remedy AR System only if each pair of fields in the primary key matches.

6 Click Save.


You must define data field mappings to specify which fields should be transferred during a data exchange.

! To define data field mappings

1 In the AR Mapping Information window, click the Data Field Mapping tab.

Figure 5-4: AR Mapping Information window—Data Field Mapping tab

118 User’s Guide


2 In the table that represents your target, select a field to which you want to transfer data.

If the direction of this data mapping is External Data into AR, the AR Form Fields table represents your target. If the direction is AR Data into External Data Store, the External Data Store Attributes table represents your target.

When field attributes are updated in BMC Remedy AR System forms, BMC Atrium Integration Engine automatically updates the attributes in the AR Form Fields table when you create a new mapping or open an existing data mapping.

NOTE If you migrate data from one BMC Remedy AR System server to another and map a SQL table in the source to another in the destination, the fields that are system-generated, such as RequestId, ModifiedDate, and CreateDate, are not transferred from the source.

WARNING Do not map the same attributes that you mapped for the primary key. The primary key mapping also serves as a data field mapping, so those attribute values are also transferred.


! In the table that represents your source, select the field that contains the value that you want to map to the target field.

! Using the Rules table, build an expression that provides the value to map to the target by selecting rules and then completing their syntax in the field underneath the table that represents your source.

Depending on the rules that you select, you might need to use one or more source field names as part of the syntax. To avoid typing one of these field names, you can select it before selecting the first rule.

For example, to create a target value that is a concatenation of the source FNAME and LNAME fields, you would build the following expression:

function|concat($FNAME$, $LNAME$)

4 Click Add.

The mapping is added to the Mapped Attributes table.

5 If you want to maintain history entries for this target field, select the field in the Mapped Attributes table and click Enable History.

If the Enable History button is not enabled, go to the Options tab and select Yes for the Maintain Change History for Fields option.

This feature is best used on fields that are not likely to change frequently.

6 Repeat steps 2 through 5 for each field that you want to map.

7 Click Save.



Your data field mappings are completed. You can enable and disable a data field mapping to debug a data exchange by selecting it in the Mapped Attributes table and clicking Enable or Disable. If a particular field causes problems when a data exchange runs, you can temporarily disable it.


Use the Response Field Mapping tab to specify fields that are updated in the source after a record is created or updated in the target.

Best practice

Typically, you use a response field when a value generated at the time a target record is created or modified exists, and you want that value stored in the source record. For example, you might need to store the ID number of the target record just created, or you might want to update a time stamp in the source data that indicates the time that a transfer took place.

120 User’s Guide


! To set response fields

1 In the AR Mapping Information window, click the Response Field Mapping tab.

Figure 5-5: AR Mapping Information window—Response Field Mapping tab

The Mapped Attributes table lists all response fields defined for the data mapping.

2 In the table that represents your source, select a field to serve as your response field.

If the direction of this data mapping is External Data into AR, the External Data Store Fields table represents your source. If the direction is AR Data into External Data Store, the AR Form Fields table represents your source.


! In the table that represents your target, select the attribute that contains the value that you want to use as a response.

! Using the Rules table, build an expression that provides the value to use as a response by selecting rules and then completing their syntax in the field underneath the table that represents your target.

Depending on the rules that you select, you might need to use one or more target field names as part of the syntax. To avoid typing one of these attribute names, you can select it before selecting the first rule.

For example, to create a response value that is a concatenation of the status of the last transferred record and the time of that transfer, you would build the following expression:

function|concat(function|status(), function|currentTime())

4 Click Add to add the response field to the Mapped Attributes table.

5 Repeat steps 2 through 4 for each response field you want to create.

6 Click Save.




Use the Delete Field Mapping tab to update a record in the target when its corresponding record has been deleted in the source. These mappings can update any attribute in the target.

NOTE The mappings on this tab are disabled if the If a Record Is Deleted From Source option on the Main tab is set to Permanently Delete or if the same option on the associated data exchange is set to Do not delete. To define delete field mappings, you must set these options to Mark as Deleted and Delete according to data mapping, respectively.

! To define delete field mappings

1 In the AR Mapping Information window, click the Delete Field Mapping tab.

Figure 5-6: AR Mapping Information window—Delete Field Mapping tab

2 Select a field from the AR Form Fields table or External Data Store Attributes table.

Only the table that corresponds to your target for this data mapping is shown.

122 User’s Guide

Defining queries

3 Select a rule from the Rules table and, if necessary, complete its syntax in the field underneath the Rules table.

Remember that you cannot include values of source fields for a delete field mapping because the source record does not exist.

4 Click Save.

Defining queries

Queries enable you to limit the exchange of data that meets certain criteria. You can enter a query for BMC Remedy AR System, the external data store, or both.

NOTE If you do not use the Query tab, all the data in the data source is transferred and all records are eligible for updates, responses, and delete actions.

TIP To update only records that have changed in the source since the previous data transfer, you do not need to use a query. To accomplish this, use the Only New or Updated Since Last Transfer option on the Options tab, as described in step 7 on page 131.



Table 5-1 shows the query types that are supported for BMC Remedy AR System forms.



Data key query

The AIE service obtains the list of rows to be transferred in a data exchange from both BMC Remedy AR System and the external data store adapter. When a data key query is defined, only rows that meet the search criteria defined by the key query are obtained and included in the data exchange.You can configure queries for BMC Remedy AR System, the external data store, or both. BMC Remedy AR System query syntax is defined by the AIE service. The external data store query syntax is defined by the external data store. The buttons above the External Data Store Query field are provided as a convenience, but they might not be supported by the external data store’s query syntax.

Note: When you are using event-driven mode, data key queries are ignored.

Update query An update query is a row-level query applied only to target rows that should be updated with modified data from the source. Each target row is updated only if it meets the query conditions.

Response query

A response query is a row-level query applied only to source rows that should be updated with response values. Each source row is updated only if it meets the query conditions.

Delete query A delete query is a row-level query applied only to target rows that should be acted upon only when their source rows are deleted. Possible actions include deleting the target row, marking the target row as deleted, and updating it with values from a delete field mapping. These actions take place only if the target row meets the query condition.

124 User’s Guide

Defining queries

Defining a data key queryYou can define data key queries to limit the number of rows transferred.

! To define a data key query

1 In the AR Mapping Information window, click the Query tab.

The Data Key Query tab appears by default.

Figure 5-7: AR Mapping Information window—Data Key Query tab

2 In the AR Form Query field and the External Data Store Query field, define the search criteria to limit the data retrieved using the following steps:

a Click Select AR Fields or External Data Store Fields to enter a valid field in the query statement.



For example, to select records for an External Data into AR mapping where a date field in your external data store named JDATETIME matches an BMC Remedy AR System Date/Time field named JDateTime, enter this query:


3 Click Save.



Defining an update queryYou can define an update query to limit the number of target rows updated.

! To define an update query

1 On the Query tab of the AR Mapping Information window, click the Update Query tab.

Figure 5-8: AR Mapping Information window—Update Query tab

2 In the Target Row Query field, use the following steps to define the search criteria against which each target row of data is compared before it is updated:




3 Click Save.

126 User’s Guide

Defining queries

Defining a response queryYou can define a response query to limit the number of source rows updated with values from the target.

! To define a response query

1 On the Query tab of the AR Mapping Information window, click the Response Query tab.

Figure 5-9: AR Mapping Information window—Response Query tab

2 In the Source Row Query field, define search criteria against which each source row is compared by using the following steps. If a source row meets the search criteria, it is updated with a response value.



3 Click Save.



Defining a delete queryYou can define a delete query to limit the number of target rows acted upon as a result of source rows being deleted.

! To define a delete query

1 On the Query tab of the AR Mapping Information window, click the Delete Query tab.

Figure 5-10: AR Mapping Information window—Delete Query tab

2 In the Target Row Query field, using the following steps define the search criteria against which each target row of data is compared to determine if that row is to be deleted:

a Click Select AR Fields or External Data Stored Fields to enter a valid field in the query statement.


3 Click Save.

128 User’s Guide



Use the Options tab on the AR Mapping Information form to set preferences for creating extra fields in a specified form to hold various types of information.


1 In the AR Mapping Information window, click the Options tab.

Figure 5-11: AR Mapping Information window—Options tab




This option specifies which action to take if an error prevents data from being obtained for one or more mapped fields for a given record. Values are as follows:




! The data is not the same type in the BMC Remedy AR System database and in the external data store. An attempt to convert the data fails.








This option specifies whether trailing blanks and tabs are considered when BMC Atrium Integration Engine compares primary keys to match records between the source and target. Some applications treat trailing blanks and tabs as characters; others ignore trailing blanks. Values are as follows:



5 Select a value for the Maintain Change History for Fields option.

This option specifies whether a history of detected changes to a record is maintained in a specified diary field in the BMC Remedy AR System form. This option is available only when the direction of the data mapping is External Data into AR.

If you select Yes, the Store History In list is enabled. Select an existing diary field in which to store history entries, or select systemGenerated to have BMC Atrium Integration Engine create a hidden diary field named Asset History for this purpose. If you select an existing field, you cannot map any other value to it on the Data Field Mapping tab. A new diary entry is written for a record when it is created and each time it is updated.

If you select No, history is not maintained for this class.

130 User’s Guide



This option specifies whether all target records are updated or only those records that have changed in the source as determined by a checksum calculated from the values of all mapped fields. This option is available only when the direction of the data mapping is External Data into AR.

If you select Yes, the Calculate and Store Checksum In list is enabled. Specify an existing integer field in which to store the checksum, or select systemGenerated to have BMC Atrium Integration Engine create a hidden integer field named Schema CRC for this purpose. If you select an existing field, you cannot map any other value to it on the Data Field Mapping tab. The checksum is calculated at each data transfer and compared to the one stored in this attribute from the previous transfer.

If you select No, the checksum is not calculated and all target records are updated, subject to any data key queries and update queries that you have defined.


This option enables you to select whether to retrieve only new or updated data since the last successful data transfer was run. This option is available only when the direction of the data mapping is External Data into AR. Values are as follows:

! Only New or Updated Since Last Transfer—If you select this option, the Last Modified Timestamp in Source field is enabled. Select a date and time field in your source that holds the time stamp from when each record was last modified. During each data transfer, the only records retrieved from the source are new records and those with a last modified time stamp that is later than the most recent successful transfer.

WARNING If you select this option, the If a Record is Deleted from Source option is set to Mark as deleted for the data mappings and to Do not delete for the data exchanges. Do not select the Only New or Updated Since Last Transfer option if your external data store is a flat file. This option is not applicable for flat files. For flat files, make sure that you select All for the Retrieve Source Records option.


The Retrieve Source Records option works like the Update Record Only If Checksum for Mapped Field Has Changed option. However, if you use the Only New or Updated Since Last Transfer value for Retrieve Source Records, you cannot use the delete options for data mappings and data exchanges for CI classes.

8 Click Save.




Populating the rule controlYou can append rules to the rule control on the Data Field Mapping, Response Field Mapping, Delete Field Mapping, and Query tabs of the AIE:ARMappingInfo form by using the AIE:Rules form. Customizing this control helps you add rules and functions that you often use. Rule control is implemented as a rules list on all the tabs.

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 With BMC Remedy User, log into the server where BMC Atrium Integration Engine is installed as an administrator.

2 Choose File > Open > Object List.

Figure 5-12: Object List window

3 On the Object List window, select AIE:Rules, and then New.

132 User’s Guide

Populating the rule control

The AIE:Rules window appears.

Figure 5-13: AIE:Rules window

4 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 this example, you would type First & Last Name.

5 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 AIE:ARMappingInfo form. For this example, you would type concat($FirstName$, " ", $LastName$) to generate a first name followed by a space and then a last name.

6 In the Category list, select a category that represents the fields to populate with your item. The choices are as follows:

! Field Rule

Populates the selections from the rule control list for data mappings.

! Query Rule

Populates the selections from the rule control list for queries.

! Delete Rule

Populates the selections from the rule control list for deletion.

For this example, you would select Field Rule.



7 In the Prefix Syntax list, select the syntax of a prefix that is required for the category of a command.

NOTE 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, you would select function|.

8 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 AIE:DataExchange form. If this field is left blank, all AIE services can use this field or rule.

9 If Rule Owner is applicable for relationship exchanges, select Yes for the Rel Exg field.

10 In the Rule Display field, type the name of the rule as you would like it displayed.

11 Click Save.

The rule that you created is available from the selection list that you access from the Rule control located on the Field Mapping tab.

134 User’s Guide

Chapter

6
Data exchanges
A data exchange is a set of rules that defines how data is transferred between an external data store and the BMC Atrium Configuration Management Database (BMC Atrium CMDB) or BMC Remedy Action Request System (BMC Remedy AR System) database.


! Using data exchanges with BMC Atrium CMDB (page 136)! Overview of creating a data exchange (page 137)! Defining data exchange parameters (page 138)! Assigning data mappings (page 143)! Managing execution (page 145)! Defining connection settings (page 149)! Using advanced settings (page 161)! Activating a data exchange (page 164)! Verifying a data exchange configuration (page 165)! Running a data exchange on demand (page 166)! Managing connection parameters (page 169)! Failover support (page 174)! Error handling in BMC Atrium Integration Engine (page 177)! Exporting and importing data (page 178)! Enhanced retrieve delta feature for relationship exchanges (page 183)! Sample data exchanges for BMC Remedy ITSM (page 184)



Using data exchanges with BMC Atrium CMDBWhen transferring data into BMC Atrium CMDB, you normally populate multiple CI classes and the relationship classes that connect them. BMC recommends the following approach when creating data exchanges for this situation:

! Create one data exchange for a CI class that acts as the source member of several relationships, such as BMC_ComputerSystem. Execute this exchange on a schedule.

! Create a data exchange for each CI class that is related to the first CI class, such as BMC_OperatingSystem or BMC_DiskDrive. When the first exchange is completed, trigger each of these to execute simultaneously, each using a different BMC Atrium Integration Engine instance.

! For each of these secondary data exchanges, create another data exchange that transfers the relationship between that destination CI class and the target CI class. Trigger this relationship data exchange to execute when the CI exchange is completed.

This approach transfers data in the order that you establish, ensuring that each CI or relationship is in place before it is required by the next exchange. This approach also reduces the overall time of the data transfer by using multiple BMC Atrium Integration Engine instances. For example, you might create the data exchanges shown in Table 6-1. In this example, four instances of BMC Atrium Integration Engine can be used for creating a data exchange.

Table 6-1: Sample set of data exchanges to transfer data into BMC Atrium CMDB

Data exchange name CI or relationship created How executed Instance used

ComputerExchange BMC_ComputerSystem Fridays, 10 p.m. 1

OSExchange BMC_OperatingSystem On completion of ComputerExchange

1

DiskDriveExchange BMC_DiskDrive On completion of ComputerExchange

2

MonitorExchange BMC_Monitor On completion of ComputerExchange

3

SoftwareExchange BMC_Product On completion of ComputerExchange

4

CS-OSExchange BMC_HostedSystemComponents, relating BMC_ComputerSystem and BMC_OperatingSystem

On completion of OSExchange

1

CS-DDExchange BMC_HostedSystemComponents, relating BMC_ComputerSystem and BMC_DiskDrive

On completion of DiskDriveExchange

2

136 User’s Guide

Overview of creating a data exchange

Overview of creating a data exchange

Step 1 Define the parameters for the data exchange.

You must specify the name, direction, instance name, external data store, exchange type, schedule options, and target data information. For more information, see “Defining data exchange parameters” on page 138.

Step 2 Assign data mappings.

You must associate data mappings for a data exchange. For more information, see “Assigning data mappings” on page 143.

Step 3 Manage the execution of the data exchange.

You can specify the data exchange execution schedule. For more information, see “Managing execution” on page 145.

Step 4 Define the connection settings.

Define the information about the external data store and BMC Remedy AR System login. For more information, see “Defining connection settings” on page 149.

Step 5 Use advanced settings.

You can define the debug and performance settings, and Charset information, and use the Retrieve Delta Setting. For more information, see “Using advanced settings” on page 161.

Step 6 Activate the data exchange to run it.

CS-MRExchange BMC_HostedSystemComponents, relating BMC_ComputerSystem and BMC_Monitor

On completion of MonitorExchange

3

CS-SWExchange BMC_HostedSystemComponents, relating BMC_ComputerSystem and BMC_Product

On completion of SoftwareExchange

4

Table 6-1: Sample set of data exchanges to transfer data into BMC Atrium CMDB (Continued)

Data exchange name CI or relationship created How executed Instance used



For more information, see “Activating a data exchange” on page 164.

Step 7 Verify the configuration.

For more information, see “Verifying a data exchange configuration” on page 165.

Step 8 (optional) Run the data exchange on demand.

For more information, see “Running a data exchange on demand” on page 166.

Defining data exchange parameters

Before you begin

Make sure that you have an account in your source database and that you have created any necessary access and privileges in that database.

! To define data exchange parameters


2 Click AIE Console in the Quick Links list.

138 User’s Guide


3 Click New at the bottom of the Data Exchange Console.

The Data Exchanges Information window appears showing the fields on the Main tab.

Figure 6-1: Data Exchanges Information window—Main tab

4 In the Exchange Name field, type a data exchange name.

5 In the Instance Name field, select the instance of the AIE service that is to run the data exchange.

If you have installed multiple instances of the AIE service, you can improve performance by using multiple data exchanges for a given transfer and assigning each to a different instance. In this case, use a qualification for each data exchange to separate your source data into chunks.

In the sample scenario, Calbro Services wants to transfer the data of the printers at its Adelaide site into its centralized database located in New York. The IT department at Calbro Services divides the printers based on the year in which Calbro Services bought them, such as 1996-2000, 2001-2005, 2006-present. To transfer each chunk of data, they create a separate data exchange.

6 In the Data Exchange Type field, select the type of data to be exchanged with the external data store:

! AR—A BMC Remedy AR System form

! CI Class—A configuration item (CI) class in BMC Atrium CMDB

! Relationship Class—A relationship class in BMC Atrium CMDB

7 In the External Data Store list, select the adapter for the external data store.



8 In the Direction list, select the direction of the data flow by using one of the options shown in Table 6-2.

9 In the Execute Exchange As field, select the method of execution:

! Schedule Only—The data exchange runs on a scheduled basis. When you select this option, you can use any of the settings on the Schedule tab of the Data Exchanges Information form. You can run scheduled data exchanges using the Interval, Time, or To Be Triggered option. This option is commonly used for bulk runs.

In the sample scenario, the IT department at Calbro Services runs the first data exchange of the printers bought from 1996-2000, on a particular schedule.

! Event Driven Only—The data exchange runs on event requests created with the Application Pending form or the aiexfer utility. Each request can restrict the data transfer to specific records. You can use this option for bulk transfers. You can also trigger an event-driven data exchange to run on the completion of another data exchange.

In the sample scenario, the subsequent data exchanges of the printers bought from 2001-2005 and 2006-present in Calbro Services are triggered only after the scheduled data exchange of 1996-2000 is completed.

For more information, see step 5 on page 148.

NOTE You can also use the Schedule Only option with the To Be Triggered option to trigger data exchanges when the exchanges are running on the same BMC Atrium Integration Engine instance; whereas, you can use the Event Driven Only option with the To Be Triggered option when data exchanges are running on different BMC Atrium Integration Engine instances.

10 If you selected an event-driven exchange, type or select a number in the Concurrent Session Limit field.

Table 6-2: Values for the Direction list

Value Description Compatible data exchange types

External Data into AR

BMC Remedy AR System forms are populated with data obtained from an external data store.

AR

AR Data into External Data Store

The external data store is populated with data obtained from BMC Remedy AR System forms.

AR

External Data into CMDB

BMC Atrium CMDB classes are populated with data obtained from an external data store.

CI Class, Relationship Class

CMDB Data into External Data Store

The external data store is populated with data obtained from BMC Atrium CMDB classes.

CI Class

140 User’s Guide


This is the maximum number of sessions that can execute the data exchange at the same time. The default is 1, which works well in most cases.

In the sample scenario, Calbro Services wants to transfer data from its London site for all computers systems used in its London finance department. Calbro Services executes an event-driven data exchange and specifies 2 as the limit for concurrent sessions, which means that the data will be transferred in two sessions at the same time. This helps to improve the performance.

11 Under the Data in Target heading, select how the data should be transferred using one or more of the options in Table 6-3.

:

Table 6-3: Values for the Data in Target fields

Option Value Description

Create a record

Always All records obtained from the source create a new record on the target. The target is not checked to see if the record already exists there. If this option is selected, the other Data in Target options are disabled.

If no duplicate exists BMC Atrium Integration Engine verifies whether the record already exists and does not create a record if one exists. Any records obtained from the source that do not already exist on the target result in a new record being created on the target. Source records that exist on the target are processed according to the Update Existing Records setting.

Never BMC Atrium Integration Engine does not create any new records on the target. Source records that exist on the target are processed according to the Update Existing Records setting.

Update existing records

Yes Any records obtained from the source that already exist on the target are updated during the data exchange.

No Any records obtained from the source that already exist on the target are not processed during the data exchange.

In the sample scenario, when Calbro Services transfers the disk drive information from the Dublin site, the If No Duplicate Exists option is selected. Consequently, after the data is populated in the target database, if the data exchange is rerun to transfer the information, the duplicate records are not updated.



If a record is deleted from source

Delete according to data mapping

Any record detected on the target that is not present on the source is handled as specified by the If a Record Is Deleted From Source option on the data mapping. If the Do not Delete option is selected, the record could be physically deleted or marked as deleted. Marking as deleted works differently for BMC Atrium CMDB class mappings than it does for BMC Remedy AR System form mappings.

In the sample scenario, after the data from the Dublin site is transferred into the centralized Calbro database, Calbro Services decides to delete the records from the Dublin site database. However the records from the Calbro database are deleted only as per the data mapping for those records. This means that the records are marked as deleted if the Mark as Deleted option is selected for the data mapping of those records, or the records are permanently deleted if the Permanently Delete option is selected in the data mapping for those records.

When you select this option, do not select the Only New or Updated Since Last Transfer option for CI class mappings or vendor-based relationship mapping. The Only New or Updated Since Last Transfer option fetches a delta chunk of records from the source and the entire set of records from the destination to compare the key, so that only the delta chunk is added or updated in the target. If you have selected the Only New or Updated Since Last Transfer option for a data mapping and select the Delete According to Data Mapping option for the corresponding data exchange, during data transfer the records that are not updated in the destination are marked either as deleted or deleted permanently.

Note: You can use the Only New or Updated Since Last Transfer option on the Options tab of the Relationship Class Mapping Information window with the Delete According to Data Mapping option for class-based relationship mappings.

Do not delete Any record detected on the target that is not present on the source is ignored and not deleted. Any delete field mappings specified in the associated data mapping are also ignored. In the sample scenario, after the data from the London site is transferred into the centralized Calbro database, Calbro Services decides to delete the records from the London database. However, Calbro Services wants to retain all records that were transferred from the London database. Therefore, the records are retained in the target (Calbro) database even when they are deleted from the source (London) database.

Table 6-3: Values for the Data in Target fields (Continued)

Option Value Description

142 User’s Guide

Assigning data mappings

12 Click Create.

The Data Exchanges Information window expands to include the Data Mappings, Manage Execution, Connection Settings, and Advanced Settings tabs.

Assigning data mappings

If you have already defined data mappings, you can assign a data mapping to the data exchange that you are creating. You can also create the data exchange first, and then define and assign the data mapping to it later.

You can assign multiple data mappings to the same data exchange. The reasons to assign multiple data mappings are:

! Performance—The more you can reduce database access, the faster a data transfer runs. If more than one target data object uses the same source data object, the AIE service can use a single thread to populate the target objects.

! Multiple data sources—Sometimes a target record has fields that must be populated with data from multiple sources because the data is not available from one source. If the data from multiple sources share a common key field, you can include them all in one data exchange. These multiple sources must be within the same external data store, such as different tables in one database.

NOTE When multiple data mappings are included in one data exchange, the AIE service obtains the list of transferred key values from the main mapping only. Therefore, the key value from each included data mapping must match the key value in the main mapping exactly in both form and content.

For example, if you want to use multiple data mappings in one data exchange to move employee ID numbers from multiple source databases into one target database, the key field in the main mapping might be called EMPID, while the key field in another data mapping might be called employee_ID. The key values that they represent, however, must be identical. For example, the ID for Brent Smith must be 00023 in all data mappings, not 23 in one and 00023 in another.

NOTE Flat file adapters do not support multiple data mappings for a data exchange, because flat file adapters cannot transfer data from multiple files for a data exchange.



Best practice

BMC recommends that you use a single data mapping for a data exchange. If you use multiple, unrelated (having different key fields) data mappings in a data exchange, the data transfer could fail.

! To assign data mappings to a data exchange

1 Click the Data Mappings tab on the Data Exchanges Information window.

Figure 6-2: Data Exchanges Information window—Data Mappings tab

2 In the Available table, select the data mapping that you want to assign to the data exchange.

3 Click the right-arrow button (>) between the Available and Selected tables.

The data mapping is added to the Selected table, and the value in the Main Mapping column is set to Yes.

NOTE You can designate only one data mapping as the main mapping. If multiple data mappings are listed in the Selected table, the AIE service designates the first data mapping that you add as the main mapping.

4 Click Save.

144 User’s Guide

Managing execution

Managing execution

You can run a data exchange based upon a scheduled day and time, at a timed interval, or when triggered by an event (such as the firing of an active link or filter). With the exception of the Trigger Data Exchange field, the instructions in this section apply only to schedule-driven data exchanges and not event-driven data exchanges.

When you run reconciliation jobs, make sure that you do not run the reconciliation jobs and data exchanges at the same time, because the reconciliation jobs and data exchanges could query or update the same data.

Best practice

The BMC Configuration Automation for Clients Configuration Discovery Integration (CDI) product uses the CDIntegrationID attribute as the primary key to transfer data from the invdb database into BMC Atrium CMDB. If you transfer data when the invdb database is being updated, BMC Atrium Integration Engine creates CIs in BMC Atrium CMDB with default or NULL values. This results in the value of the CDIntegrationID attribute to be specified as NULL in the BMC.IMPORT.CONFIG dataset. To avoid this issue, run the data exchanges when the data in the invdb database is not being updated.

TIP “Using data exchanges with BMC Atrium CMDB” on page 136 provides a suggested strategy for managing execution of data exchanges when transferring data to BMC Atrium CMDB. You can use multiple data exchanges to improve performance. For more information, see “Using multiple data exchanges” on page 25.



Before you begin

Make sure that you do not schedule more than 15 data exchanges on a single instance of AIE service at any given time, because an AIE service instance is capable of executing 15 data exchanges at a given time.

! To manage the execution of a data exchange

1 Click the Manage Execution tab on the Data Exchanges Information window.

Figure 6-3: Data Exchanges Information window—Manage Execution tab

146 User’s Guide

Managing execution

2 In the Execution area, select the schedule timing that you want to use based on the options described in Table 6-4.

3 If you selected the Interval option in the Execution area, perform the following steps in the Interval area:

a In the Time Interval in Minutes field, type the number of minutes to wait between data exchanges.

For example, if you set the interval to 30 minutes, and a data exchange takes 60 minutes to complete, the next data exchange begins 90 minutes after the first data exchange began.

b In the No. of Times to Run field, type the number of times the data exchange runs before the exchange stops transferring data.

Table 6-4: Execution time options

Option Description

Interval Runs the data exchange at the time interval specified in the Time interval in minutes field. The interval is the number of minutes to wait after one data exchange is completed before starting the next one. The first time the AIE service runs, all active data exchanges run. Any changes made to a data exchange are implemented at the next scheduled interval.

In the sample scenario, Calbro Services wants to update the database with ATM transactions. It therefore schedules a data exchange at an interval of an hour to populate the database with the information of the ATM transactions.

Time Runs the data exchange at the times entered in the Time area. You can set data exchanges to run at any regularly scheduled time based on your business needs. The first time the AIE service runs, all active data exchanges wait to run at the times scheduled. Any changes made to a data exchange are implemented the next time the data exchange runs according to the times scheduled.

In the sample scenario, a data exchange runs every Wednesday at 2 a.m. to populate the reports of requests created in the Support centers at Calbro Services.

To Be Triggered

Runs the data exchange only when triggered. If you select the To Be Triggered option, the only time this data exchange runs is when it is triggered by an entry in the Trigger Data Exchange field for another data exchange.

In the sample scenario, when the data exchanges that populate the information about ATM transactions are executed, a data exchange is executed to update the online account information for customers at Calbro Services.



If you limit the number of data exchanges, the data exchanges do not start again until you restart the AIE service or the ConfigInterval parameter in the aie.cfg file refreshes the list of data exchanges to run. This option is normally used for testing a data exchange.

4 If you selected the Time option in the Execution area, perform the following steps in the Time area:

a In the Weekdays field and the Time of Day field, select a weekday and a time of day, respectively.

The time is composed of the day of the week and the time on that day that a data exchange occurs. You can define up to 100 time entries.

b Click Add.

The new scheduled time is added to the list box.

NOTE You can set two different data exchanges to run at the same scheduled time. In this case, both exchanges start at the scheduled time simultaneously and run without affecting each other.

5 (optional) In the Trigger Data Exchange field, select the name of a data exchange to activate when this data exchange is completed.

You can select either a schedule-driven or an event-driven data exchange to trigger.

NOTE The fields in the On Completion of This Data Exchange area are only used if you want to trigger another data exchange when this data exchange is completed. If the Trigger Data Exchange field is empty, this data exchange does not trigger other data exchanges.

6 In the After field, type the number of minutes to wait after completing the primary data exchange before starting the triggered, secondary data exchange.

7 Click Add.

The triggered data exchange is added to the list box.

NOTE If you have a data exchange scheduled at a particular time, followed by data exchanges that will be triggered after the earlier data exchange is complete, the total time that is required to run all data exchanges is cumulative.

In the sample scenario, Calbro Services scheduled the ComputerSystems data exchange at 2.30 a.m. It scheduled the DiskDrives exchange to be triggered 2 minutes later and the Printers data exchange to be triggered 5 minutes later after the ComputerSystems exchange was complete. The ComputerSystems data exchange was complete at 2.45 a.m. The DiskDrives data exchange was triggered at 2.47 a.m. and the Printers data exchange was triggered at 2.52 a.m. The time taken to run the data exchanges is cumulative.

148 User’s Guide

Defining connection settings

8 Click Save.

NOTE An AIE service instance is capable of executing 15 data exchanges at a given time. Make sure that you do not schedule more than 15 data exchanges on a single instance of AIE service at any given time.


Depending on the type of your external data store, you might need to define specific connection parameters on the Connection Settings tab to allow communication with an adapter.

The default BMC Remedy AR System server defined for use in a data exchange is the one in which the Data Exchange application resides. If you want to define a different BMC Remedy AR System server, you must specify the login parameters for that server on the Connection Settings tab.



Supported data typesTable 6-5 shows the supported external data store types and indicates whether you must define specific connection parameters when using that type. Table 6-6 lists the data types supported for each adapter.

Table 6-5: Supported external data store types

Type Requires specific connection parameters

DB2 UDB Yes

Comma separated value (CSV) flat file No

Oracle Server Yes

SQL Server Yes

XML No

Table 6-6: Data types supported with BMC Atrium Integration Engine

SQL Oracle DB2 XML

int smallint tinyint bigint decimal numeric money smallmoney float real datetime smalldatetime char varchar nchar nvarchar(n) timestamp sqlvariant

int smallint numeric number decimal float real date timestamp char varchar2 nchar nvarchar long

Integer SmallInt BigInt Character Varchar NChar NVarchar Date Time TimeStamp Decimal Float Numeric

string boolean decimal float double dateTime time date

150 User’s Guide


Defining connection settings for DB2 UDBYou must define connection parameters if your external data store is a DB2 UDB database. You must also specify login parameters if you want to use an BMC Remedy AR System server other than the default for the data exchange.

Before you begin

Make sure that you have populated the DB2 UDB field information for external data tables by using the Database Field Menus Console.

! To define connection settings for DB2 UDB

1 Click the Connection Settings tab on the Data Exchanges Information window.

Figure 6-4: Data Exchanges Information window—Connection Settings tab for DB2 UDB

2 In the DB2 Instance field, type the name of the DB2 UDB instance where your database resides.

This is the value of the DB2INSTANCE environment variable in the DB2 UDB client on the BMC Atrium Integration Engine computer.

3 In the DB2 Database Alias field, type the alias for your DB2 UDB database.

4 In the DB2 Database Login Name field, type the user name of the administrative account for your DB2 UDB database.

5 In the DB2 Database Login Password field, type the password of the administrative account for your DB2 UDB database.

6 Complete one of the following actions:

! Accept the default selection in the Use default destination BMC Remedy AR System option to use the BMC Remedy AR System server where the Data Exchange application resides.

! Select No if you want to use a different BMC Remedy AR System server.



7 If you selected No, complete the following steps:

a In the AR Server Name field, type the name of your BMC Remedy AR System server.

NOTE In a server group environment, you must specify the server group alias name in the AR Server Name field instead of the primary server name.

b (optional) In the Port Number field, type the port number.

c (optional) In the RPC Program Number field, type the RPC port if you use one.

NOTE If you specify a private RPC port, it will not work for the data exchanges with the External Data into CMDB and CMDB Data into External Data Store directions. You must use the ports defined by BMC Atrium CMDB. For more information about the RPC ports provided by BMC Atrium CMDB, see “RPC ports in BMC Atrium CMDB” on page 161.

d In the Admin Login Name field, type the user name of the BMC Remedy AR System administrator.

e In the Admin Password field, type the password of the BMC Remedy AR System administrator.

8 Click Test Connection(s) to verify the connection parameters.

The Test Connection(s) button label changes to Get Result.

9 Click Get Result.




Defining connection settings for flat filesYou do not have to define connection parameters if your external data store is a flat file such as a CSV or XML file. However, you must specify login parameters if you want to use an BMC Remedy AR System server other than the default for the data exchange.

NOTE Flat files cannot be remotely located. You cannot use a flat file on a Windows computer if you have installed BMC Atrium Integration Engine on a UNIX computer. Flat files must be located on the computer on which BMC Atrium Integration Engine is installed.

152 User’s Guide


! To define connection settings for flat files


Figure 6-5: Data Exchanges Information window—Connection Settings tab for flat files


! Accept the default selection in the Use Default Destination AR Server option to use the BMC Remedy AR System server where the Data Exchange application resides.






c (optional) In the RPC Program Number field, type the RPC port.




d In the Admin Login Name field, type the user name of the BMC Remedy AR System administrator account.

e In the Admin Password field, type the password of the BMC Remedy AR System administrator account.

4 Click Test Connection(s) to verify your connection parameters.


5 Click Get Result.




Defining connection settings for OracleYou must define connection parameters if your external data store is an Oracle database. You must also specify login parameters if you want to use an BMC Remedy AR System server other than the default for the data exchange.

Before you begin

Make sure that you have populated the Oracle field information for external data tables by using the Database Field Menus Console.

! To define connection settings for Oracle


Figure 6-6: Data Exchanges Information window—Connection Settings tab for Oracle

2 In the Oracle System ID field, type the instance identifier for your Oracle database.

154 User’s Guide


3 In the Oracle Database Directory field, type the directory path where your Oracle database is installed.

4 In the Oracle Database Login Name field, type the user name of the administrative account for your Oracle database.

5 In the Oracle Database Login Password field, type the password of the administrative account for your Oracle database.


! Accept the default selection in the Use default destination AR server option to use the BMC Remedy AR System server where the Data Exchange application resides.










8 Click Test Connection(s) to verify your Oracle connection parameters.


9 Click Get Result.






Defining connection settings for SQL ServersYou must define connection parameters if your external data store is a SQL Server database. You must also specify login parameters if you want to use an BMC Remedy AR System server other than the default for the data exchange.

Before you begin

Make sure that you have populated the SQL Server field information for external data tables by using the Database Field Menus Console.

! To define connection settings for SQL Server


Figure 6-7: Data Exchanges Information window—Connection Settings tab for SQL Server

2 In the SQL Server Name field, type the name of your SQL Server computer.

3 In the SQL Server Database Name field, type the name of your SQL Server database.


! If you use SQL Server authentication for your database, type the user name of the administrative account in the SQL Server Login Name field and the password in the SQL Server Login Password field. Leave the Connect Using Windows Authentication option set to No.

! If you use Windows authentication for your database, select Yes in the Connect Using Windows Authentication option. You do not need to enter a SQL Server login name or password.

For more information about Windows authentication, see “SQL Server authentication” on page 158.

156 User’s Guide



! Accept the default selection in the Use default destination AR server option to use the BMC Remedy AR System server where the Data Exchange application resides.







NOTE If you specify a private RPC port, it does not work for External Data into CMDB and CMDB Data into External Data Store data exchanges. You must use the ports defined by BMC Atrium CMDB. For more information about the RPC ports provided by BMC Atrium CMDB, see “RPC ports in BMC Atrium CMDB” on page 161.



7 Click Test Connection(s) to verify your SQL Server connection parameters.


8 Click Get Result.






SQL Server authenticationWhen you connect to a SQL Server database using the Windows authentication option, the SQL Server client software requests a Windows trusted connection to the SQL Server. In a trusted connection a user has the permissions to access Windows group and user accounts as well as the SQL Server database.

Windows opens a trusted connection only if the client has logged on successfully using a valid Windows account. When SQL Server gets the user account information from a trusted connection, it matches the information against the Windows account. If a match is found, the connection is accepted.

NOTE You must define the Windows account as a valid SQL Server login.

Windows authentication in the SQL Server adapter in BMC Atrium Integration Engine enables a user to connect to the SQL Server database using Windows credentials. On the computer on which BMC Atrium Integration Engine is running, BMC Atrium Integration Engine uses a logged-on user to connect to the SQL Server.

Setting the Log On As option for the AIE service

You must set the Log On As option for the AIE service to the Windows user who has permissions to the SQL Server database.

Figure 6-8 shows the Log On As option set for the AIE service for a Windows user.

Figure 6-8: Log On As option for the AIE service

If you are not logged on to the computer on which the AIE service is running, and if the AIE service starts running in the Automatic mode, the AIE service runs using the credentials of a logged-on user. Make sure that the Log On As user has permissions to access the specified SQL Server database.

Setting the Log On As option for BMC Remedy AR System

You must set the Log On As option for BMC Remedy AR System for a Windows user.

When you execute the Rule Helper utility as a Windows application from the service/bin directory, it considers the user logged on to the computer on which BMC Atrium Integration Engine is installed for Windows authentication.

However, when you access the Rule Helper utility from BMC Atrium Integration Engine Console > Configuration > Database Field Menus, the utility runs through the workflow using RUN PROCESS command and is considered a child process of the BMC Remedy AR System server. Therefore, it uses the credentials that have been assigned to the BMC Remedy AR System service as a Log On As user.

158 User’s Guide


Figure 6-9 on page 159 shows the Log On As option set for the BMC Remedy AR System service.

Figure 6-9: Log On As option for the BMC Remedy AR System service

Defining connection settings for XMLYou do not have to define connection parameters if your external data store is an XML file. However, you must specify login parameters if you want to use an BMC Remedy AR System server other than the default for the data exchange.

NOTE The XML adapter supports some data types. For more information about the data types supported by an XML adapter, see Table 6-6 on page 150.

! To define connection settings for XML


Figure 6-10: Data Exchanges Information window—Connection Settings tab for XML




! Accept the default selection in the Use Default Destination AR Server option to use the BMC Remedy AR System server where the Data Exchange application resides.





b In the Port Number field, type the port number if you use one.

c In the RPC Program Number field, type the RPC port if you use one.




4 Click Test Connection(s) to verify your BMC Remedy AR System connection parameters.


5 Click Get Result.




160 User’s Guide

Using advanced settings

RPC ports in BMC Atrium CMDBBMC Atrium CMDB has assigned the following RPC ports for BMC Atrium Integration Engine and Reconciliation Engine:


Use the advanced settings options to debug and log events, improve performance, and define character set information.

! To use advanced settings

1 Click the Advanced Settings tab on the Data Exchanges Information window.

Figure 6-11: Data Exchanges Information window—Advanced Settings tab

#define CMDB_RPC_PROGRAM_NUM_STANDARD 390696#define CMDB_RPC_PROGRAM_NUM_ADMIN 390697#define CMDB_RPC_PROGRAM_NUM_PRIVATE_MIN 390698#define CMDB_RPC_PROGRAM_NUM_PRIVATE_MAX 390699




! To disable event logging, select No for the Enable Debug Logging option.

BMC recommends No as the setting for production environments because it improves performance.

! To enable event logging, accept the default selection of Yes in the Enable Debug Logging option.

3 If you selected Yes, complete the following steps:

a In the Debug File Path field, type the directory path where you want to store the debug file.

If the Debug File Path field contains a value and debugging is enabled, the output goes to the debug file in the directory path indicated. All directories in the fully qualified path name must already exist. If you do not enter a value, the debug path is aieInstallationDir\service\debug.

If you want to add a timestamp at the beginning of each line in every debug file, set the TimeStampDebug parameter in the aie.cfg file to Yes.

b Accept the default setting in the Debug File Creation option to create a backup copy of the debug file, or click Append To Existing to append entries to the existing debug file when new events occur.

c In the Max Debug Size field, type the maximum size of the debug file in bytes.

When the maximum size is reached, the debug file is copied to a backup (.bak) file. The previous backup file is overwritten. You can enter a value between 4096 to 2147483600 bytes. The default value is 102400 bytes.

d In the Enable Thread Based Logging option, select the Yes check box to enable event logging for all threads running the data exchange.

e In the Debug Level field, select one or more of the following check boxes:

! API Calls—Logs information about all API calls made by BMC Atrium Core. Information is logged on entry and exit of every API call.

! SQL Statements—Logs SQL commands sent to the database. Information is logged for each SQL command issued, including a timestamp.

! Record Summary—Logs summary information for each record. Summary information includes whether the record is getting added, updated, or deleted and also if it was successfully added, updated, or deleted.

! Record Details—Logs detailed 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.

f Click Apply to All Exchanges if you want to apply the debug settings to all existing data exchanges.

162 User’s Guide


4 In the Record Limit field, type the number of records that the AIE service can process during one data exchange. Setting the Record Limit field to 0 (zero) transfers all records.

The Record Limit field is useful when you are initially setting up data mappings. For example, limiting the AIE service to five requests allows you to correct or adjust your data exchange configuration without populating the BMC Remedy AR System database with the entire contents of the external data store.

5 In the Number of threads field, type the number of threads you want to use to run the data exchange.

The maximum number of threads that you can specify is 49. The default is three times the number of CPUs detected on the computer where BMC Atrium Integration Engine is installed.

6 If the external data for this data exchange is not Unicode, select the character set to use in the Language list in the Charset Information area.

The Is External Data Unicode? field displays the Unicode setting for the BMC Atrium Integration Engine instance associated with this data exchange. If the value is Yes, BMC Atrium Integration Engine uses the Unicode character set for the exchange. If the value is No, the Language list is enabled and you can select the character set to use.

WARNING When the external data is in Unicode character set, you must configure the BMC Atrium Integration Engine instance in Unicode. Failure of doing so corrupts the data.

If your BMC Remedy AR System is in Unicode character set, make sure that your external data instance is in the Unicode format with the nvarchar column.

7 (optional) For Retrieve Delta Setting, click Reset to fetch all source records in the next data execution.

After a data exchange is run, the Last Modified Time Stamp displays the time at which the data exchange was last run. If you click Reset, BMC Atrium Integration Engine ignores the last set of records that was processed at that time and fetches all records from the source in the next data exchange.

8 In the AIE Error Handling area, select the Log Errors into CSV option, which writes errors that occur during data transfer into a .csv file.

For more information about the error handling feature, see “Error handling in BMC Atrium Integration Engine” on page 177.

9 Click Save.



Activating a data exchange

The individual data exchange settings let you control how the data exchange or transfer occurs. Before you can run a new data exchange, you must change its status to active.

! To activate a data exchange

1 Click the Data Exchanges link on the navigation panel.

Figure 6-12: Data Exchange Console

2 On the Data Exchange Console, select the data exchange that you want to activate.

3 Click Active/Inactive.

The data exchange is now activated.

NOTE When you activate an exchange, the Delete button is disabled. You cannot delete an active data exchange.

164 User’s Guide

Verifying a data exchange configuration

Verifying a data exchange configuration

Always check each data exchange before you run it to verify its configuration. Specifically, verify the following conditions:

! Connections to the external data store and the BMC Remedy AR System server are established.

! Specified classes and tables are valid.

! Specified field and attribute mappings are valid.

! Specified queries are valid.

Before you begin

Make sure that the AIE service is running before you verify a data exchange.

! To verify data exchange conditions






3 On the Data Exchange Console, select the data exchange that you want to verify.

4 Click Verify.

The verification process begins, and the Verify button label changes to Get Result.

5 Click Get Result.




NOTE The verification process can take several minutes to complete. Because this process is asynchronous, you can continue working with BMC Atrium Integration Engine while waiting for the result.

WARNING If the AIE service crashes for any reason after you click the Get Result button, you must explicitly log out of your BMC Remedy User session using the Logout button on the Data Exchanges Console. If you simply close and restart your BMC Remedy User session, the Verify button continues to show the Get Result label, preventing you from verifying other data exchanges.

Running a data exchange on demand

You can schedule and run a data exchange based on the Manage Execution tab settings or on demand. Occasionally, you might want to run a data exchange on demand for testing purposes.

When you run reconciliation jobs, make sure that you do not run the reconciliation jobs and data exchanges at the same time, because the reconciliation jobs and data exchanges could query or update the same data.

NOTE If you run a data exchange on demand when the same data exchange is already running, the on-demand request is ignored.

166 User’s Guide

Running a data exchange on demand

Best practice

Before you run data exchanges on your production data, run them on a small amount of representative data first. You can use a qualification to specify the amount of data. For example, Calbro Services wanted to transfer 10,000 records of processors from their Chicago site to the New York site. First, they transferred only 100 records by using the qualification $EmployeeID$ >= 400 AND $EmployeeID$ <= 500.

Before you begin

Make sure that the AIE service is running.

! To run a data exchange on demand




3 On the Data Exchange Console, select the data exchange that you want to run on demand.

NOTE Make sure that the data exchange is active. When you activate an exchange, the Delete button is disabled. You cannot delete an active data exchange.

4 Click Run Now.

A dialog box appears asking if you want to run this data exchange.

5 Click Yes.

A dialog box appears saying that the data exchange that you selected has started.



6 Click OK.

Managing connection parametersMost organizations need to create multiple data exchanges to manage data transfers for their asset inventory. For example, you might need to create ten or more different data exchanges to transfer all your data between various external data stores and BMC Remedy AR System forms or BMC Atrium CMDB classes.

BMC Atrium Integration Engine provides an easy way to manage the connection parameters for the DB2 UDB, Oracle, and SQL Server external data store types using a single console. Otherwise, you would have to change these parameters on the Connection Settings tab of the Data Exchanges Information window for each data exchange individually.

Managing DB2 UDB connection parametersYou can manage the DB2 UDB connection parameters for all your data exchanges that connect to an external DB2 UDB database.

! To manage DB2 UDB connection parameters

1 From the BMC Atrium Integration Engine Console, click Configuration > Connections in the navigation pane.

168 User’s Guide

Managing connection parameters

Figure 6-15: Connections Console—DB2 tab

The Connections Console shows a list of the existing data exchanges in the Data Exchange Name table. For the selected data exchange in the table, the values of the connection parameters are shown to the right of the table. These fields are read only. The fields below the table allow you to change the value of the connection parameters for the selected data exchange. The fields are not case sensitive except for Password.

2 In the DB Instance field, type the name of the DB2 UDB instance where your database resides.

3 In the DB Alias field, type the alias for your DB2 UDB database.

4 In the Login Name field, type the user name of the administrative account for your DB2 UDB database.

5 In the Password field, type the password of the administrative account for your DB2 UDB database.

The password is case sensitive.

6 In the Apply New Configuration Settings To field, select one of the following options:

! To apply connection parameter changes to only the data exchanges that are selected in the Data Exchange Name table, select Only Selected Data Exchanges.

! To apply connection parameter changes to all the data exchanges in the Data Exchange Name table, select All Data Exchanges.



8 Click Get Result.





10 Click OK and Apply.

Managing Oracle connection parametersYou can manage the Oracle connection parameters for all your data exchanges that connect to an external Oracle database.

! To manage Oracle connection parameters

1 From the BMC Atrium Integration Engine Console, click Configuration > Connections on the navigation panel.

2 On the Connections Console, click the Oracle tab.

Figure 6-16: Connections Console—Oracle tab

The Connections Console shows a list of the existing data exchanges in the Data Exchange Name table. For the selected data exchange in the table, the values of the connection parameters are shown to the right of the table. These fields are read only. The fields below the table allow you to change the value of the Oracle connection parameters for the selected data exchange. The fields are not case sensitive.

3 In the SID field, type the system ID for the Oracle database.

NOTE The SID value is a unique service name that is configured in the tnsnames.ora file for every Oracle instance.

4 In the DB Directory field, type the directory path for the Oracle database.

170 User’s Guide


5 In the Login Name field, type the Oracle login name used to establish a connection to the Oracle database.

6 In the Password field, type the password associated with the login name used to connect to the Oracle database.






9 Click Get Result.




Managing SQL Server connection parametersYou can manage the SQL Server connection parameters for all your data exchanges that connect to an external SQL Server database.

! To manage SQL Server connection parameters

1 From the BMC Atrium Integration Engine Console, click Configuration > Connections on the navigation panel.

2 On the Connections Console, click the SQL Server tab.



Figure 6-17: Connections Console—SQL Server tab

The Connections Console shows a list of the existing data exchanges in the Data Exchange Name table. For the selected data exchange in the table, the values of the connection parameters are shown to the right of the table. These fields are read only. The fields below the table allow you to change the value of the SQL Server connection parameters for the selected data exchange. The fields are not case sensitive except for Password.

3 In the Server Name field, type the name of your SQL Server computer.

4 In the Database Name field, type the name of your SQL Server database.

172 User’s Guide



! If you use SQL Server authentication for your database, type the user name of the administrative account in the Login Name field and the password in the Password field. Leave the Enable Windows Authentication check box cleared.

! If you use Windows authentication for your database, select the Enable Windows Authentication check box. You do not need to enter a SQL Server login name or password.

For information about Windows authentication, see “SQL Server authentication” on page 158.






8 Click Get Result.




Using the AIE:VendorConfiguration form to specify connection settings

After you install BMC Atrium Core, you can specify the connection settings by using the AIE:VendorConfiguration form.

! To specify connection settings in the AIE:VendorConfiguration form

1 On the AIE:VendorConfiguration form, specify the external data store and click Search.

The external data store parameters are listed.

2 Change the values for each of the parameters, and click Save.



Failover supportBMC Atrium Integration Engine provides failover support for data exchanges when it or BMC Remedy AR System stops responding.

With the failover support, BMC Atrium Integration Engine can continue from the point of failure in a data transfer. BMC Atrium Integration Engine tracks the first processed key of the chunk of transferred data. The records that have already been updated or added are not processed, thus avoiding a repetition of data transfer and improving performance.

Failover support for data exchanges transferring data into CI classes and BMC Remedy AR System forms

If BMC Atrium Integration Engine stops responding when a data exchange transferring data into CI classes or BMC Remedy AR System is running, BMC Atrium Integration Engine records the first key in the data chunk that was processed before the failure and starts transferring the data from the next data key. The records that have been already processed are not processed again.

NOTE Failover support is applicable only when the source has more than 10,000 records to be transferred.

BMC Atrium Integration Engine failover support does not work for data exchanges with the direction CMDB Data into External Data Store or AR Data into External Data Store. If such a data exchange fails to complete for any reason, the next time it runs it starts from the first record again instead of bypassing the records transferred in the previous run.

You can track the progress of a BMC Atrium Integration Engine instance in the AIE:Exchange_Runs form. Records are transferred in chunks of 10,000. When an instance stops responding, the first key of a chunk that was successfully transferred is displayed in the Data Key field of the AIE:Exchange_Runs form. When the BMC Atrium Integration Engine instance restarts, BMC Atrium Integration Engine starts transferring data from the next key.

If multiple entries of a data exchange with the Running status are found, BMC Atrium Integration Engine considers the exchange that was last run and starts transferring the data from the point where it failed.

NOTE If you want to transfer all records again, you must change the Run Status in the AIE:Exchange_Runs form to Completed for the last incomplete data exchange. When you run the exchange again, all records are transferred.

174 User’s Guide

Failover support

If the AIE service or BMC Remedy AR System stops responding during the transfer of a chunk of records and you restart the AIE service, the chunk of records are transferred regardless of the number of records already processed in that chunk. For example, 20,000 records are to be transferred, and the first chunk of 10,000 records is transferred successfully. The AIE service stops responding after only 3300 records in the second chunk have been transferred. When you restart the AIE service, records from 10,001 onwards are transferred even though 3300 of these records were transferred before the AIE service stopped.

NOTE BMC Atrium Integration Engine failover support does not work for XML adapters. If a data exchange with XML file as the external data store fails to complete for any reason, the next time it runs it starts from the first record again instead of bypassing the records transferred in the previous run.

In the sample scenario, Calbro Services transfers 30,000 records of computer systems from the Dublin site of Calbro Services to the centralized Calbro database. Data is transferred in three chunks of 10,000 each. The first chunk of data is successfully transferred. The first key (1) of the successfully transferred chunk is displayed in the Data Key field on the AIE:Exchange_Runs form. When 14,882 records have been transferred, the AIE service stops responding. Calbro Services restarts the AIE service. AIE considers the data key of the last successfully transferred data chunk. The data transfer restarts from 10,001 records. After all 30,000 records are successfully transferred, the data key of the last successfully transferred chunk (20,001) is displayed in the Data Key field.

Failover support for relationship data exchangesWhen BMC Atrium Integration Engine stops responding when a vendor-based relationship data exchange is running, BMC Atrium Integration Engine records the last relationship key for class 1. Records are fetched in chunks from the source class and then relationships are created.

You can track the progress of a BMC Atrium Integration Engine instance in the AIE:Exchange_Runs form. For a relationship data exchange, records are transferred in chunks of 350.

When an instance stops responding, the first key of a chunk that was successfully transferred is displayed in the Data Key field of the AIE:Exchange_Runs form. The Data Key for a relationship data exchange is always the relationship key of the source class. When the BMC Atrium Integration Engine instance restarts. BMC Atrium Integration Engine starts transferring data from the next key of the source class.

For relationship data exchanges, the Total Records field in the AIE:Exchange_Runs form displays either the total number of records present in the relationship class or the total number of records in the source database table or file.



NOTE The Data Key is the first key of a chunk of data that is being processed. If the AIE service stops responding before the chunk of data is successfully transferred, the Data Key does not show the last record that was successfully transferred; it just shows the first key of the chunk of data that was being processed. As a result, if you check the debug files for that data exchange, the number of records transferred is always more than the Data Key. However, BMC Atrium Integration Engine transfers data from the next record of the Data Key. The records that are already present in the destination database are updated when the BMC Atrium Integration Engine instance is restarted.

The AIE service does not clear entries in the AIE:Exchange_Runs form. You must manually delete the old entries from the form to prevent the database from getting too large. Alternatively, you can write workflow that periodically delete entries automatically.

In the sample scenario, Calbro Services has 16200 records holding the relationship between the ComputerSystem source class and DiskDrive destination class in its Adelaide site database and transfers them to its centralized database. When the data is transferred, the relationship key of the source class, ComputerSystem, is recorded as the Data Key in the AIE:Exchange_Runs form. After 1837 records have been transferred, the AIE service stops responding. The number of records processed so far is 1750, which is logged in the Records Processed So Far field. When the AIE service starts running again, the data transfer process continues from the next record after the data key (1751).

Figure 6-18: Data Key for relationship data exchanges

176 User’s Guide

Error handling in BMC Atrium Integration Engine

The debug files showed that 1837 records are transferred although the records processes so far are 1750. This is because the Data Key logs the first key of a chunk of data. Before the AIE service stopped responding, 1837 records were processed. When the AIE service restarts, it starts processing data from the next key, which is 1751. Records from 1750-1837 (87 records) are updated in BMC Atrium CMDB and the records after 1837 are inserted. Following are the logs in the debug files:

Session statistics: Relationship class requests: 1837, Class1-Class2 requests: 14450, ByPassed: 1750 Class1 RecordsSession statistics: Requests added: 14363, updated: 87, ByPassed: 1750, deleted: 0, errors: 0, warnings: 0

Error handling in BMC Atrium Integration Engine

If you mapped fields incorrectly while creating data or relationship mappings, errors can occur during data transfer. When the data transfer fails, you might not understand which records were not transferred.

With the error handling feature, you can capture these errors in a .csv file. You can select the Log Errors into CSV option on the Advanced Settings tab of the Data Exchanges Information window and capture the records that were not successfully transferred to the destination.

Logging errors in the .csv fileWhen you choose to create the .csv file, the installer creates a new error directory in the C:\Program Files\BMC Software\AtriumCore\aie\service directory. A .csv file is created in the error directory when you select the Log Errors into CSV option. BMC Atrium Integration Engine saves the file there with the same name as the data exchange.

The .csv file records the following types of errors:

! All CreateInstance and SetInstance errors for BMC Atrium CMDB

Examples:

CMDB_ERROR_REQUIRED_ATTRIBUTE_VALUE_MISSING (120076)

CMDB_ERROR_CHARACTER_DISALLOWED_IN_NAME (120078)

CMDB_ERROR_INVALID_REL_ENDPOINT_CLASS_ID (120100)

CMDB_ERROR_MODIFYING_INSTANCE_ID_VAL_DISALLOWED (120148)

! All CreateEntry and SetEntry errors for BMC Remedy AR System

NOTE BMC Remedy AR System connectivity errors ARERR 91, ARERR 92, and ARERR 93 are not recorded in the .csv file, because these errors are not due to erroneous data values.



For example, Calbro Services creates a CalbroInventory data exchange and selects the Log Errors into CSV option. Calbro Services associates this data exchange with the CalbroInventoryMapping data mapping created between the source (CalbroInventory.Servers table) and target (BMC_ComputerSystem class). Some records in the external data store do not have values for the Name attribute. During data transfer these records are not transferred to the target. The CMDB_ERROR_REQUIRED_ATTRIBUTE_VALUE_MISSING (120076) error occurs and these records are recorded in the CalbroInventory.csv file in the C:\Program Files\BMC Software\AtriumCore\aie\service\error directory.

You can also choose to log erroneous relationship CIs in the .csv file. For the relationship data exchanges, while creating the .csv file, BMC Atrium Integration Engine considers only the records that have not been successfully transferred to the destination BMC Atrium CMDB relationship class.

Exporting and importing dataWith the export utility, you can export data exchanges, data mappings, and the configuration information from your development environment to the production environment. You can also import the data exchanges, data mappings, and configuration information from the development environment to the production environment by using this utility.

Exporting dataYou can export data exchanges directly to a server from BMC Atrium Integration Engine. With this utility, you can export data exchanges to the 7.1.00 and 7.5.00 versions of BMC Atrium Integration Engine. You can export data from the 7.5.00 version to the 7.6.00 of BMC Atrium Integration Engine, but not from the 7.1.00 version to the 7.6.04 because this enhanced utility is not supported on BMC Atrium Integration Engine 7.1.00. You can also export data to a configuration file.

NOTE Exporting data exchanges to a server allows you to export selected data exchanges, while exporting data to a file exports all data exchanges and data mappings to a file.

! To export data exchanges to a server

1 In the Data Exchange Console menu bar, choose AIE > Export Configuration.

NOTE The AIE menu is not available for other BMC Atrium Integration Engine consoles, such as CI Class Mappings, Relationship Class Mappings, and AR System Form Mappings.

The Export Configuration Utility window appears, in which the Source Server Details area is populated.

178 User’s Guide

Exporting and importing data

Figure 6-19: Export Configuration Utility window

2 In the Target Server Details, specify the following information:

! Server Name: The server to which data is to be transferred.

! (optional) TCP Port: The TCP port if you are not using the default port on the target server.

! Admin Login Name: The BMC Remedy AR System administrator user.

! (optional) BMC Remedy AR System password.

! (optional) Data File Location: The location on the destination server to which the data file is to be saved.

If you do not specify the file location, the location of the data file in the source server is used in the destination server. Make sure that you specify the directory path to the \data directory level, as indicated:

For Windows:

BMCAtriumIntegrationEngineInstallationDir\\service\\data\\

For example: C:\\Program Files\\BMC Software\\AtriumCore\\calbro-test-01\\aie\\service\\data\\

For UNIX:

BMCAtriumIntegrationEngineInstallationDir/opt/service/data/

Errors might occur if you use the source location directory.

3 For the Export All Exchanges option, accept the default option of Yes or select No-Only Selected Ones.

4 If you select the No-Only Selected Ones option, a list of data exchanges appears in the table.



5 Select the data exchanges you want to export.

6 Click Export, and then OK for any messages that appear describing the status of the process.

The label of the Export button changes to Get Results.

7 Click Get Results.

One of the following messages appears.

! Export in progress.

! Export completed.

! Export failed.

A detailed log is available in the result field.

! To export data to a file

1 In the Data Exchange Console menu bar, choose AIE > Export Configuration.

NOTE The AIE menu is not available for other BMC Atrium Integration Engine consoles, such as CI Class Mappings, Relationship Class Mappings, and AR System Form Mappings.

The Export Configuration Utility window appears.

2 In the Export Configuration to file area, enter a valid directory path in the Output Directory field.

3 Click Export.

The AIE_Configuration.arx file is created in the directory path that you specified. This file contains configuration information for all data exchanges as well as data mappings.

180 User’s Guide

Exporting and importing data

Importing dataAfter you export your data to the AIE_Configuration.arx file, you can import it using the BMC Remedy Data Import utility or BMC Remedy Data Import Command-Line Utility (CLI).

NOTE If BMC Atrium Integration Engine 7.5.00 or later is installed on BMC Remedy AR System 7.1.00 and BMC Atrium CMDB 2.1.00, use the BMC Remedy Import utility or BMC Remedy Import CLI to import data. If BMC Atrium Integration Engine 7.5.00 or later is installed on BMC Remedy AR System 7.5.00 and BMC Atrium CMDB 7.5.00, you must use the BMC Remedy Data Import utility or BMC Remedy Data Import CLI.

! To import data

1 Open the AIE_Configuration.arx file to edit it.

2 Make the following changes in the AIE_Configuration.arx file:

! Remove the configuration definition for the following forms:

! EIE:BackupLoadFlag

! EIE:ApplicationSettings

! EIE:VendorConfiguration

! In the EIE:DataExchange form information, change the instance name to the name of the destination BMC Atrium Integration Engine instance.

! In the EIE:Data form information, change all paths for the flat file and .csv file adapter-based data exchanges and database-related information.

Make similar changes in the EIE:DataMapping, EIE:CMDBDataMapping, and EIE:CMDBRelMapping form information. In the EIE:VendorFieldNames form information, change the Table Name.

NOTE If you view the files in BMC Remedy User, the form names are prefixed with AIE:. However in the AIE_Configuration.arx file, the form names are prefixed with EIE:.




Table 6-7: Importing data

Versions Using Actions

! BMC Atrium Integration Engine 7.5.00 or later

! BMC Remedy AR System 7.5.00 or later

! BMC Atrium CMDB 7.5.00 or later

! BMC Remedy Data Import CLI

! BMC Remedy Data Import utility

1 Run the following command from the command line:BMCRemedyARSystemInstallationDir\dataimporttool\dataimporttool.exe -x serverName -u loginName -p loginPassword -o pathOfTheAIE_Configuration.arxFile -l destinationPath

For example:C:\Program Files\BMC Software\ARSystem\datamimporttool\dataimporttool.exe -x "pramteke-pun-01" -u "Demo" -p "" -o "D:\AIE_DataExchange_Windows\AIE_DataExchange_Windows.arx" -l "D:\log\logfilename”

For information about using the BMC Remedy Data Import CLI, see the BMC Remedy Action Request System 7.6.04 Integration Guide.

2 If you use the BMC Remedy Data Import utility, follow the steps to import data to a destination form. For information about using the BMC Remedy Data Import utility, see the BMC Remedy Action Request System 7.6.04 Configuration Guide.

! BMC Atrium Integration Engine 7.5.00 or later

! BMC Remedy AR System 7.1.00! BMC Atrium CMDB 2.1.00

! BMC Remedy Import CLI

! BMC Remedy Import utility

1 Run the following command from the command line:BMCRemedyARSystemInstallationDir\arimportcmd.exe -x serverName -u loginName -p loginPassword -o pathOfTheAIE_Configuration.arxFile -l destinationPath

For example:C:\Program Files\BMC Software\ARSystem\arimportcmd.exe -x "pramteke-pun-01" -u "Demo" -p "" -o "D:\AIE_DataExchange_Windows\AIE_DataExchange_Windows.arx" -l "D:\log”

For information about using the BMC Remedy Import CLI, see the BMC Remedy Action Request System 7.1.00 Integration Guide.

2 If you use the BMC Remedy Import utility, follow the steps to import data to a destination form.For information about using the BMC Remedy Import utility, see the BMC Remedy Action Request System 7.1.00 Configuration Guide.

182 User’s Guide

Enhanced retrieve delta feature for relationship exchanges

Enhanced retrieve delta feature for relationship exchanges

With the 7.6.00 version, the retrieve delta feature for relationship exchanges is extended to secondary classes. In earlier versions, BMC Atrium Integration Engine gave priority to the primary class in a relationship data exchange. When the Retrieve Delta Setting option was selected, BMC Atrium Integration Engine retrieved the records that were added or updated in the primary class with the latest timestamp. Changes to the secondary class records were not considered.

As part of the new feature, when you select the Retrieve Delta Setting option, the records changed in the secondary class since the last successful data transfer are also considered for the data transfer when the relationship data exchange is run again. Relationships are established for the changed records from the secondary class.

For example, Calbro Services creates a relationship data exchange with the BMC_ComputerSystem as the primary class and BMC_DiskDrive as the secondary class. The relationship class is BMC_HostedSystemComponents. After running the data exchange successfully, records are added in the BMC_DiskDrive secondary class and some records are updated. When the relationship data exchange is run again, the records that have changed in the primary BMC_ComputerSystem class as well as from the secondary BMC_DiskDrive class are retrieved.

This feature makes sure that changes made at the CI level are also retrieved for the corresponding CI relationship.

However, with this feature, you cannot select the date for the Retrieve Delta Setting option on the Advanced Settings tab of the Data Exchanges Information window for relationship data exchanges. The date used is in the ModifiedDate attribute.

For class-based relationship data exchanges, you can use the Retrieve Delta Setting option along with the If a Record is Deleted From Source option on the Main tab of the Data Exchanges Information window.

The Retrieve Delta Setting option works in conjunction with the Retrieve Source Records option on the Options tab of the Relationship Class Mapping Information window. For more information, see step 6 in “Setting data mapping options” on page 104.



Sample data exchanges for BMC Remedy ITSMBMC Atrium Integration Engine provides a set of data exchanges and data mappings that you can use to transfer data from a flat file into BMC Atrium CMDB for use with BMC Remedy IT Service Management (BMC Remedy ITSM.)

For all BMC Remedy ITSM data exchanges, data is retrieved from an external file using the flat file adapter. You must activate these data exchanges before you use them to transfer data. Table 6-8 describes the order of execution of the ITSM data exchanges.

Table 6-8: ITSM data and relationship exchanges

ITSM Sample Data Exchange CI or relationship created Order of execution

Sample ITSM BusinessService BMC_BusinessService Friday, 10 p.m.

Sample ITSM Application BMC_Application On completion of Sample ITSM BusinessService

Sample ITSM ComputerSystem BMC_ComputerSystem On completion of Sample ITSM BusinessService

Sample ITSM BiosElements BMC_BIOSElement On completion of Sample ITSM ComputerSystem

Sample ITSM Card BMC_Card On completion of Sample ITSM ComputerSystem

Sample ITSM DiskDrive BMC_DiskDrive On completion of Sample ITSM ComputerSystem

Sample ITSM OperatingSystem BMC_OperatingSystem On completion of Sample ITSM ComputerSystem

Sample ITSM Processor BMC_Processor On completion of Sample ITSM ComputerSystem

Sample ITSM Database BMC_Database On completion of Sample ITSM ComputerSystem

Sample ITSM App2Comp Relationship

BMC_Dependency, relating BMC_Application and BMC_ComputerSystem

On completion of Sample ITSM ComputerSystem

Sample ITSM Bus2App Relationship

BMC_Dependency, relating BMC_BusinessService and BMC_Application

On completion of Sample ITSM Application

Sample ITSM Bus2Database Relationship

BMC_Dependency, relating BMC_BusinessService and BMC_Database

On completion of Sample ITSM Database

Sample ITSM Comp2Database Relationship

BMC_Dependency, relating BMC_ComputerSystem and BMC_Database

On completion of Sample ITSM Database

Sample ITSM Comp2BiosElement Relationship

BMC_HostedSystemComponents, relating BMC_ComputerSystem and BMC_BIOSElement

On completion of Sample ITSM BiosElements

184 User’s Guide

Sample data exchanges for BMC Remedy ITSM

Sample ITSM Comp2Card Relationship

BMC_HostedSystemComponents, relating BMC_ComputerSystem and BMC_Card

On completion of Sample ITSM Card

Sample ITSM Comp2DiskDrive Relationship

BMC_HostedSystemComponents, relating BMC_ComputerSystem and BMC_DiskDrive

On completion of Sample ITSM DiskDrive

Sample ITSM Comp2OS Relationship

BMC_HostedSystemComponents, relating BMC_ComputerSystem and BMC_OperatingSystem

On completion of Sample ITSM OperatingSystem

Sample ITSM Comp2Processor Relationship

BMC_HostedSystemComponents, relating BMC_ComputerSystem and BMC_Processor

On completion of Sample ITSM Processor

Table 6-8: ITSM data and relationship exchanges (Continued)

ITSM Sample Data Exchange CI or relationship created Order of execution



186 User’s Guide

Chapter

7
Activating event-driven data exchanges
You can create an event-driven data exchange request by using the Application Pending form, invoking the aiexfer utility, or creating BMC Remedy Action Request System (BMC Remedy AR System) workflow that performs either of these actions.


! Creating a request on the Application Pending form (page 188)! Creating a request using the aiexfer utility (page 191)! Activating an event-driven data exchange through workflow (page 197)



Creating a request on the Application Pending form

Whether you create requests using the Application Pending form or the aiexfer utility, all event-driven requests are written to the Application Pending form.

The AIE service processes requests on the Application Pending form at a scheduled interval that is configured in the aie.cfg file (using the AsyncInterval parameter).

NOTE The AIE service has no mechanism for clearing entries on the Application Pending form. Periodically, 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 BMC Remedy 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 BMC Remedy AR System request ID if you are running a data exchange between an external data store and BMC Atrium Configuration Management Database (BMC Atrium CMDB) classes. In this case, you must use its key.

BMC Atrium Integration Engine does not provide failover support for event-driven requests. If the AIE service or the BMC Remedy AR System server stops responding when an event-driven data exchange is running, you must create a new request to run that data exchange using the Application Pending form.

188 User’s Guide

Creating a request on the Application Pending form

! To create a request on the Application Pending form


2 Choose File > Open > Object List.

3 From the Object List window, select the Application Pending form.

Figure 7-1: Object List window

4 Click New.

5 On the Application Pending window, specify EIE in the Category field.

Figure 7-2: Application Pending window

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 that typed in the Exchange Name field on the Main tab of the AIE: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 7-1 shows the list of status values.

9 In the Tag field, enter one of the following types of event-driven exchange:

! Immediate Request

! On Scheduled Interval

Table 7-1: Status values

Status Description

New The request has been submitted but not processed.

In Progress The request is currently being processed.

Completed The request completed successfully.

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

190 User’s Guide

Creating a request using the aiexfer utility

10 In the Other Short field, type the key or the BMC Remedy 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, by using one or more of the parameters in Table 7-2.

The Other Long field is completed by BMC Atrium Core after the completion of the data exchange. This field enables printing of the final exchange completion statistics, such as the number of records inserted or updated.

11 In the Status options, select Pending.

12 Click Save.

Creating a request using the aiexfer utilityThe aiexfer utility is a BMC Remedy AR System client that opens a connection to BMC Remedy 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 computer other than the one running the Data Exchange application and the BMC Remedy AR System server.

Table 7-2: Data exchange parameters

Parameter Description

-k keyValue Specifies the key value of the record that you want to transfer. Every key value that you enter must have a corresponding entry on the Primary Key Mapping tab of the AIE: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 requestId Specifies the BMC Remedy AR System request ID of the record that 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: You can use the -r parameter only when you are transferring data from a BMC Remedy AR System form or a BMC Atrium CMDB class to an external data store. BMC Atrium CMDB. You can specify one or more request IDs (for example: -r 0000001472 -r 0000003742).

-b Specifies that a bulk data transfer of all data defined for a data exchange is to occur.



Whether you create requests using the Application Pending form or the aiexfer utility, all event-driven requests are written to the Application Pending form.

The AIE service processes requests on the Application Pending form on a scheduled interval that is configured in the aie.cfg file (the AsyncInterval parameter).

In addition to the scheduled interval, you can also configure the AIE service to process individual event requests immediately if you enter them through the aiexfer utility.

BMC Atrium Integration Engine does not provide failover support for event-driven requests. If the AIE service or the BMC Remedy AR System server stops responding when an event-driven data exchange is running, you must create a new request to run that data exchange using the aiexfer utility for immediate processing.

NOTE To improve performance, if your event-driven data exchange does not need to occur immediately, type your request into the Application Pending form rather than invoking the aiexfer utility.

By default, the aiexfer utility for Windows is installed in the aieInstallationDir\service\bin\aiexfer.exe directory. However, you can manually move the aiexfer utility (and its supporting DLL files on Windows) to another computer.

! To create a request using the aiexfer utility

1 From the command line of the computer on which you have installed BMC Remedy AR System and the Data Exchange application, type the following command:

BMCAtriumIntegrationEngineInstallationDir\service\bin\aiexfer.exe

2 To create the request, use the BMC Remedy AR System parameters in Table 7-3, the Data Exchange parameters in Table 7-4, and the optional immediate parameters in Table 7-5 (if you want to run the data exchange request immediately).

192 User’s Guide


Table 7-3 lists the BMC Remedy AR System parameters that you must use with the aiexfer utility.

Table 7-4 lists the Data Exchange parameters that you can use when using the aiexfer utility.

Table 7-3: BMC Remedy AR System parameters


-x BMCRemedyARSystem ServerName

Specifies the name of the BMC Remedy AR System server where the Application Pending form resides.

-rpcport portNumber

Specifies the port of the BMC Remedy AR System server (for example, -rpcport 4500).

-l loginName Specifies the BMC Remedy AR System server login name for connecting to the BMC Remedy AR System server.

-p password Specifies the password associated with the BMC Remedy AR System server login name.

Table 7-4: Data exchange parameters


-s dataExchangeName Specifies the data exchange to use. The data exchange name is the value that you typed in the Data Exchange Name field on the Main tab of the AIE:DataExchange form. This parameter is mandatory if you want to specify individual records for exchange rather than invoking a bulk transfer.

-k keyValue Specifies the key value of the record that 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 AIE: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 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 requestId Specifies the BMC Remedy AR System request ID of the record that 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. You can specify one or more request IDs (for example: -r 0000001472 -r 0000003742).

-b dataExchangeName Specifies that a bulk data transfer of all data defined for a data exchange is to occur.

-n instanceName Specifies the instance associated with this data exchange.



Table 7-5 lists the optional immediate parameters that you can use when using the aiexfer utility.

Examples of the event-driven request command syntaxThe following examples assume an BMC Remedy AR System server name of myserver, a login name of jdoe, a password of password, and a data exchange name of employees.

! To specify an event-driven request to transfer a record for an employee named Smith:

aiexfer -x myserver -l jdoe -p password -s employees -k Smith -n instanceName

! To specify an event-driven request for a bulk exchange of all employee records:

aiexfer -x myserver -l jdoe -p password -b employees -n instanceName

! To specify an immediate event-driven request for an employee whose record is identified by the BMC Remedy AR System server ID number 23456 using a wait interval of 10 seconds and a retry count of 20:

aiexfer -x myserver -l jdoe -p password -s employees -r 23456 -i -w 10 -c 20 -n instanceName

! 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:

aiexfer -x myserver -l jdoe -p password -b employees -i -c 20 -n instanceName

! To specify an event-driven request to transfer a record for an employee named Tom Smith:

aiexfer -x myserver -l jdoe -p password -s employees -k “Smith Tom” -n instanceName

Table 7-5: Optional immediate parameters


-i (required for immediate handling)

Specifies that the data exchange should run immediately.

-w numberOfSecondsBeforeCheckingForAResponse (optional)

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 default value, 5, is used.

-c (optional) 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 default value, 3, is used.

194 User’s Guide


Completion codes returned by aiexferData exchange requests that are submitted through the aiexfer utility return completion codes that indicate the status of a request. These codes fall into several categories, which are listed in Table 7-6.

The completion codes are listed in Table 7-7. A brief definition follows each message in the table.

Table 7-6: aiexfer completion code categories

Category Description

0 Request completed successfully.

100-199 Request was not submitted to the event-driven request queue.

200-299 Request was submitted, but the AIE service could not be notified to handle the request.

300-399 Request was submitted and the AIE service was notified to handle the request, but the completion status could not be obtained.

400-499 Request was handled by the AIE service, but the data failed to transfer. The request in the Application Pending form contains the error message indicating the cause of the failure.

Table 7-7: aiexfer completion code messages

ID Number Message

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

-102 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 error is fatal.

-103 AR Initialization failed. Verify login information is correct.The event-driven interface was unable to connect to the BMC Remedy AR System server identified by the parameters. Verify the BMC Remedy AR System server login parameters. If the parameters are correct, verify that the BMC Remedy 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 BMC Remedy AR System server. Verify that the BMC Remedy AR System server identified in the startup parameters has the Data Exchange application installed.



-201 Unable to retrieve host name and port for AIE service. Make sure the AR System user name and password are correct.The event-driven request has been submitted, but the AIE service could not be notified to handle the request. The AIE service sets the wakeup port information in the AIE:BackupLoadFlag form. If the values are not set, no active AIE service exists to handle the request at this time.

-202 EIE service wakeup port not set in AIE:BackupLoadFlag form.The event-driven request has been submitted, but the AIE service could not be notified to handle the request. The AIE service sets the wakeup port information in the AIE:BackupLoadFlag form. If the values are not set, no active AIE service exists to handle the request at this time.

-203 Unable to create socket.The request to connect to BMC Atrium Integration Engine by using a socket has been submitted. The aiexfer utility could not connect to BMC Atrium Integration Engine by using the socket.

-204 Unable to establish socket connection to AIE service.The event-driven request has been submitted, but the AIE service could not be notified to handle the request. A socket connection to the AIE service has been identified in the AIE:BackupLoadFlag form, but the socket connection could not be established.

-205 Unable to send immediate request to AIE service.The event-driven request has been submitted, but the AIE service could not be notified to handle the request. A socket connection to the AIE 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 AIE service has been notified to handle the request. The Application Pending form could not be accessed to obtain the completion status.

-302 Request has not completed in time interval allowed.The event-driven request has been submitted, and the AIE 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 aiexfer.

-401 Transfer failed when handled by AIE service.The event-driven request is completed and the AIE service has returned an error indicating that the data transfer failed. For detailed information about the error, check the debug file associated with the data exchange used in the data transfer.

Table 7-7: aiexfer completion code messages (Continued)

ID Number Message

196 User’s Guide

Activating an event-driven data exchange through workflow

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 aiexfer utility. For instructions about how to create active links or filters on your BMC Remedy AR System form, see the BMC Remedy Action Request System 7.6.04 Workflow Objects Guide.



198 User’s Guide

Appendix

A
Defining rules and queries
In BMC Atrium Integration Engine, you can use rules to map BMC Remedy Action Request System (BMC Remedy AR System) fields or BMC Atrium Configuration Management Database (BMC Atrium CMDB) classes to an external data store. You use queries to limit the data exchange to the data that meets certain criteria.

You can also make a data mapping convenient by adding external data store field names and rules to drop-down lists in the data mapping windows.


! Defining rules (page 200)! Defining queries (page 211)



Defining rulesThis section outlines the rule syntax that defines how BMC Remedy 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 BMC Remedy AR System fields or BMC Atrium CMDB classes, or a complex set of functions used to compute the value for a rule.

You can define nested rules in mapping.

NOTE Do not precede the nested rules with function|. Errors occur if you use function| before the nested rules.

Following is an example of a nested rule:

function|substr($Capacity$,strstr("PQR","R"),length($Item$))

Nested rules do not support mathematical operations. The following example describes a mathematical operation:

function|concat($APPSERVERID$,length($APPSERVERID$)+1)

The preceding rule specifies that you can get server IDs that have a length of $APPSERVERID$ plus 1. However, you cannot use mathematical operations in nested rules. Therefore, this rule is an invalid nested rule.

Table A-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 A-1: Rule syntax for BMC Remedy AR System forms and BMC Atrium CMDB classes (part 1 of 2)

Rule syntax Description

constant| Interprets the value that follows the pipe as a constant.

{rule} {rule} {rule} 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.

function| Performs the function that follows the pipe.

sql| Runs an SQL command to obtain a value.

targetsql| Runs an SQL command on the target to obtain a value.

process| Runs a process to obtain a single character value in response.

targetprocess| Runs a process on the target to obtain a value.

stmt| Defines an if/then/else statement to obtain a value.

200 User’s Guide

Defining rules

Constant syntax (constant|string)This syntax allows you to generate a value to be placed into a field or class. BMC Atrium 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.

BMC Atrium 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, BMC Atrium Integration Engine tries to determine if the value is a date or a number before it defaults to a character value.

Table A-2 provides examples of how to use the constant syntax.

function|calc_tokenid 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 BMC Remedy AR System, the BMC Atrium CMDB, or for the external data store. For BMC Remedy AR System, this is considered a field definition and is the name of a field on an BMC Remedy AR System form. For 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 store’s rule syntax.

Table A-1: Rule syntax for BMC Remedy AR System forms and BMC Atrium CMDB classes (part 2 of 2)

Rule syntax Description

Table A-2: Constant syntax examples

Example Results

constant|Hardware Returns the character string Hardware.

constant|15 Returns the number 15.

constant|”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 BMC Atrium Integration Engine evaluates independently. The first rule to return a response value is considered the value to be returned.

Table A-3 provides examples of how to use the precedence syntax.

Function syntax (function|function(parameters))Each function defines an operation that BMC Atrium 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.

BMC Atrium 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 A-4 provides examples of the supported functions.

Table A-3: Precedence syntax example

Example Results

{PO Number} {Notification Number} {constant|Unknown Value}

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.

Table A-4: Function syntax examples (part 1 of 6)

Function Example Results

calc_token_id function|calc_token_id ($field1$,$field2$)

Calculates the token ID.

concat(string, string,string,...) (where string is a constant, field name, or function)

function|concat("abc", "def")

Returns the value that results from appending the string:abcdef

202 User’s Guide

Defining rules

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)(where timestamp is a constant, field name, or function)

function|date ($createdate$)(if $createdate$ is set to Friday, August 3, 2007 12:15:00 a.m.)

Returns the date portion of the time stamp data from the field as a character string:August 3, 2007

day(timestamp)(where timestamp is a constant, field name, or function)

function|day ($createdate$)(if $createdate$ is set to Friday, August 3, 2007 12:15:00 a.m.)

Returns the day of the time stamp (1 to 31):3

hour(timestamp)(where timestamp is a constant, field name, or function)

function|hour ($createdate$) (if $createdate$ is set to Friday, August 3, 2007 12:15:00 a.m.)

Returns the hour of the time stamp (0 to 23):00

left(string,long)(where string and long are constants, field names, or functions)

function|left("Dana",2)

Returns the left-most bytes of a character string up to the number of bytes indicated:Da

length(string)(where string is a constant, field name, or function)

Example 1:function|length("Dana")Example 2 (values in database field char1 for five records):fantasticafricaiceliverricefunction|length ($char1$)

Returns the length of a character string.Example 1:4Example 2:96354

lower(string)(where string is a constant, field name, or function)

function|lower("AIE")

Converts a character string to lowercase:aie





lpad(string,long,string)(where string and long are constants, field names, or functions)

function|lpad("ABC",10,"LEAD000000")

Returns the value that results from padding the character string to the left with another string, to a specified length:LEAD000ABC

ltrim(string)(where string is a constant, field name, or function)

function|ltrim(" abc")

Strips any leading blanks from a character string:abc

max(any,any,any, ...)max($field$,$field2$, ...)(where any is a constant, field name, or function)

function|max(15, 3, 7)

Returns the maximum value from a set of values (all must be the same data type):15All data types are supported. These can be field references or constants. Any non-null value (positive or negative) is greater than null.

min(any,any,any, ...)(where any is a constant, field name, or function)

function|min ("a", "b", "c")

Returns the minimum value from a set of values (all must be the same data type):aAll data types are supported. These can be field references or constants. Any non-null value (positive or negative) is greater than null.

minute(timestamp)(where timestamp is a constant, field name, or function)

function|minute ($createdate$)(if $createdate$ is set to Friday, August 3, 2007 12:15:00 a.m.)

Returns the minute of the time stamp (0 to 59):15

month(timestamp)(where timestamp is a constant, field name, or function)

function|month ($createdate$)(if $createdate$ is set to Friday, August 3, 2007 12:15:00 a.m.)

Returns the month of the time stamp (1 to 12):8

null() function|null() Returns a null value. This is mostly used in queries to see if a value is null. BMC Atrium Integration Engine does not set an BMC Remedy AR System value or a BMC Atrium CMDB attribute to null:null value



204 User’s Guide

Defining rules

replace(string, string,string,...)(where string is a constant, field name, or function)

function|replace ("abcdefghi", "def", "xxx")

Replaces all instances of a value in a character string with a new value:abcxxxghiYou can use field references or constants.

right(string,long)(where string and long are constants, field names, or functions)

function|right ("Allie",2)

Returns the right-most bytes of a character string up to the indicated number of bytes:ie

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

function|round(5.1) 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

rpad(string,long,string)(where string and long are constants, field names, or functions)

function|rpad("ABC",10,"000000LEAD")

Returns the value that results from padding a character string to the right with another string, to a specified length:ABC000LEAD

rtrim(string)(where string is a constant, field name, or function)

function|rtrim("abc ")

Removes any trailing blanks from a string:abc

second(timestamp)(where timestamp is a constant, field name, or function)

function|second ($createdate$) (if $createdate$ is set to Friday, August 3, 2007 12:15:00 a.m.)

Returns the second from the time stamp (0 to 59):00

status() function|status() 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.1 indicates that an error occured.This function is only used for response mapping.





strstr(string, string)(where string is a constant, field name, or function)

Example 1:function|strstr ("abcdefg", "def")Example 2 (values in database field char1 for 5 records):fantasticafricaiceliverricefunction|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:3Example 2:730-11

substr(string, long,[,long])(where string and long are constants, field names, or functions)

function|substr ("abcdefg", 2, 4)

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

timestamp() function|timestamp() Returns the current time as an BMC Remedy AR System time stamp:Friday, August 3, 2007 12:15:00 am

time(timestamp)(where timestamp is a constant, field name, or function)

function|time ($createdate$)(if $createdate$ is set to Friday, August 3, 2007 12:15:00 a.m.)

Returns the time portion of the time stamp (as a character string):12:15:00

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

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

upper(string)(where string is a constant, field name, or function)

function|upper("Alex")

Converts a string to uppercase:ALEX



206 User’s Guide

Defining rules

SQL command syntax (sql|command)BMC Atrium 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 that BMC Atrium 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 A-5, the value for the Category field ($category$) is replaced in the select statement before the statement is processed.

NOTE If the SQL command returns more than one field or more than one row, BMC Atrium Integration Engine uses the first value and ignores the remaining values.

Target SQL command syntax (targetsql|command)BMC Atrium 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 BMC Atrium 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.

weekday(timestamp)(where timestamp is a constant, field name, or function)

function|weekday ($createdate$)(if $createdate$ is set to Friday, August 3, 2007 12:15:00 a.m.)

Returns the weekday of the time stamp (1 to 7 where 1=Sunday):6

year(timestamp)(where timestamp is a constant, field name, or function)

function|year ($createdate$)(if $createdate$ is set to Friday, August 3, 2007 12:15:00 a.m.)

Returns the year portion of the time stamp as a four-digit year:2007



Table A-5: SQL command syntax example

Example Results

sql|select categoryid from categories where name = $category$

Returns category IDs from the categories table where the name equals the value obtained for the $category$ field.



For example, in Table A-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.

Process command syntax (process|command)BMC Atrium Integration Engine runs the command that follows the pipe to obtain a value. This syntax differs from the target process command syntax in that BMC Atrium 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.

For example, in Table A-7, BMC Atrium Integration Engine replaces the values for $keyName$ and $field2$ with the actual data values before running the process.

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 BMC Atrium Integration Engine runs the command on the target database defined for this data exchange.

If the command has embedded $-delimited field names, BMC Atrium 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.

Using this command, you can run a script or a process to create transformation rules.

Table A-6: Target SQL command syntax example

Example Results

targetsql|select locationid from location where department = $location$

Runs the location ID from the location table where the department equals the value of the $location$ field obtained from the source database.

Table A-7: Process command syntax example

Example Results

process| getlastupdate ($keyName$,$field2$)

Runs the command getlastupdate on the source database, passing the values for $keyName$ and $field2$ as parameters. The response from the command is used.

208 User’s Guide

Defining rules

For example, in Table A-8, BMC Atrium 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.

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 If/then/else statements are syntax sensitive. Each IF syntax should be terminated by the ENDIF syntax.

Table A-8: Target process command syntax example

Example Results

targetprocess| getlastupdate ($keyName$,$field2$)

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.

targetprocess| appspwd -p $Site$

Runs the appspwd.exe and generates an encrypted password.

Note: Make sure that the .exe file is stored in the BMCRemedyARSystemInstallationDir directory on a Windows operating system and BMCRemedyARSystemInstallationDir/bin on a UNIX operating system, or else you must provide the explicit path and the parameter used.

targetprocess|java org.mozilla.javascript.tools.shell.Main -f "C:\Temp\HelloWorld.js"

Runs the HelloWorld Java script using the -f parameter.

targetprocess|C:\Perl\bin\perl.exe "C:\al.pl" $Site$ 'MS Office' 'Microsoft Office'

Runs the perl.exe file passing the $Site$ value from the source database as a parameter.



! The line breaks following THEN and ELSE are required.

! IF, THEN, VALUE, ELSE, ENDIF must be in upper case.

! Every word should be separated by a blank space.

! Condition is in the format $SourceField$ Operator Value. Operator must be one of:

! =—SourceField matches Value

! !=—SourceField does not match Value

! LIKE—Any 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.

Table A-9 provides examples of how to use the stmt syntax.

Table A-9: Stmt syntax examples

Example Results

STMT| IF $CDiOsType$ = "Windows XP Professional" THEN VALUE = "Windows XP (67)"ENDIF

(if $CDiOsType$ is set to Windows XP Professional)

Returns Windows XP (67).

STMT|IF $CDiOsType$ LIKE "Windows XP" THEN VALUE = "Windows XP (67)"ELSE VALUE = "Unknown"ENDIF

(if $CDiOsType$ is set to Windows 2003 Professional)

The string Windows XP does not appear in Windows 2003 Professional. Returns Unknown.

STMT|IF $ChassisType$ = "12" THENIF $ChassisSize$ = "Large" THEN

VALUE="12CRPF"ENDIF

ElSEVALUE="13CRPF"

ENDIF(if $ChassisType$ is set to 12 and $ChassisSize$ is set to Small)

The top-level IF statement matches, but the nested one does not. Because no ELSE clause exists for the nested IF statement, no value is returned.

STMT|IF $model$ = "Laptop" THENVALUE = "Switch"

ENDIFIF $model$ = "Desktop" THEN

VALUE = "Router"ENDIFELSE

VALUE = "Hub"ENDIF

$model$ is a source field. Multiple values can be used for the $model$ field. The If/then/else rule is used to replace the $model$ field with different value.

210 User’s Guide

Defining queries

Defining queriesUse the following query syntax to define queries on the Query tab of the Mapping Information windows.

$field$ operator value

This query syntax applies to BMC Remedy 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.

BMC Remedy AR System query syntaxWhen you use the BMC Remedy 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 A-10 describes the query syntax options.

Table A-10: Query syntax options (part 1 of 2)

Option Description

$field$ The field name to be used in the comparison. The fields are delimited by dollar signs. For BMC Remedy AR System queries, $field$ names a field on an BMC Remedy AR System form.

value The value used in the comparison. Use the BMC Remedy AR System query syntax, or enter a data constant (for example, $SALARY$ > 2000).

operator Any of the relational operators described in this table.

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

AND Logical AND of the results of two conditions. (The result is true if both conditions are true.)

OR Logical OR of the results of two conditions. (The result is true if either condition is true.)

NOT Negates the condition that follows. (If the condition is false, the result is true.)

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



NOTE Queries with the OR option do not work for flat files.

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 A-11 in your query. The functions supported are listed in the drop-down list accessed by the Rules button on the Query tab of the respective Mapping Information windows for BMC Remedy AR System forms, CI classes, and relationship classes.

Three different Mapping Information windows exist for BMC Remedy AR System forms, CI classes, and relationship classes which can be accessed using the left side navigation panel provided on the BMC Atrium Core console.

Data key syntaxYou 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 BMC Remedy AR System forms, CI classes, and relationship classes.

In data key queries, you can create queries on an external data store or on BMC Atrium CMDB.

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

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

Table A-11: Function query syntax examples

Syntax Description

currentdate() Supplies the current date.

currenttime() Supplies the current time.

null() Identifies a null value (different from blank).

timestamp() Supplies the current date and time.

$category$ != $function|null()$

Returns all entries in the database where the $category$ field is not a null value.

Table A-10: Query syntax options (part 2 of 2)

Option Description

212 User’s Guide

Defining queries

Query on an external data storeFor a query on an external data store, you can use the Where clause of SQL statement as a qualifier. Following is an example of a Where clause query:

Select * from EmployeeDetail where EMPNAME = 'MARY MANN' AND (EMPID = AND DESIGNATION = 'MANAGER')

In this example, the following clause is the external data store qualifier.

EMPNAME = 'MARY MANN' AND (EMPID = AND DESIGNATION = 'MANAGER')

Query on BMC Atrium CMDBFollowing is an example of a query on BMC Atrium CMDB:

$First Name$ = "MARY" AND ($Designation$ = "Manager" OR $Designation$ = "Asst. Manager")

In this example, First Name and Designation are BMC Atrium CMDB fields. This query can be used to find an employee with Mary as the First Name and Manager or Asst. Manager as the Designation.

Field option in the query syntax ($field$)This is a special syntax for data key queries. You can use any syntax in Table A-12 for the Field option within the query syntax.

Table A-12: Field option in the query syntax

Syntax Description

$KEY$ Indicates all field names defined on the Primary Key Mapping tab of the respective Mapping Information windows for BMC Remedy 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 BMC Remedy AR System, this is an BMC Remedy AR System field name.



Value option in the query syntax (value)

This is a special syntax for data key queries. You can use any syntax in Table A-13 for the Value option within the query syntax.

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

KEYLIST This is a special syntax for data key queries. If this syntax is entered for an BMC Remedy 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 BMC Remedy AR System form where the BMC Remedy 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 third-party 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.

Table A-13: Value option in the query syntax

Syntax Description

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

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

xxxxxxx Any other value is treated as a constant and passed to BMC Remedy AR System server for handling.

Table A-14: KEY syntax example

Example Result

$KEY$ = $KEYLIST$ $keyfield1$ = key1 AND $keyfield2$ = key2

214 User’s Guide

Defining queries

NOTE $KEYLIST$ is a keyword that is usually supported by any adapter.

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

Row-level query syntaxYou can only use the syntax described in this section in the query syntax for a row-level query. BMC Atrium 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 AIE: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 A-16.

Table A-15: KEYLIST syntax examples

Example Result

$KEY$ = $KEYLIST$ Indicates that all records matching the keys in the $KEYLIST$ are to be returned.

$KEY$ != $KEYLIST$ Indicates that all records not matching the keys in the $KEYLIST$ are to be returned.

Table A-16: SRC syntax examples

Example Result

$LastModified$ < $SRC|LastMod$

$LastModified$ < 05/23/07(if LastMod is a field in the source database with a value of 05/23/07)



216 User’s Guide

Appendix

B
Running and configuring the AIE service
On a Windows operating system, you can run the AIE service from a command line or as a Windows service. On a UNIX operating system, you can run the AIE service from a command line in your terminal’s foreground or as a daemon. The AIE service parameters are defined in the configuration file (aie.cfg).


! Running the AIE service on Windows (page 218)! Running the AIE service on UNIX (page 219)! Loading the adapters for Oracle or DB2 (page 220)! Understanding the configuration file and its parameters (page 221)! Managing instances (page 228)! Changing BMC Remedy AR System password (page 238)



Running the AIE service on WindowsWhen installing BMC Atrium Integration Engine, you can choose to start the AIE service in automatic or manual mode. Selecting manual mode prevents the AIE service from starting automatically before you are ready to run in the production mode.

! To run the AIE service from a command line

From the command line, use the parameters in Table B-1 and type the following command.

aieInstallationdir\service\bin\aie.exe -m -n instanceName -y installationDirectory

One of the following messages appear.

! If BMC Atrium Core was able to execute the data exchanges, the following message appears:

The engine is running and has detected n active data exchanges on AR System: STUDIO

! If BMC Atrium Core was unable execute the data exchanges, the following message appears:

Failed to retrieve any active data exchange defined on AR System: STUDIO

There could be the following three reasons of this error.

! You did not activate any data exchange.

! The BMC Remedy Action Request System (BMC Remedy AR System) user assigned to BMC Atrium Core in the BMC Atrium Core 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 aie.cfg file to solve the problem, stop and restart the service to continue.

Table B-1: AIE service command-line parameters for Windows


-m Indicates that the AIE service is running from the command line. This parameter is required for both Windows and UNIX.

-n Instance name which user wants to run.

-y Indicates the absolute path of the installation directory till the /service directory.For example:D:\Program Files\BMC Software\AtriumCore\ysomavan-lt-01\aie\service

218 User’s Guide

Running the AIE service on UNIX

Running the AIE service on UNIXYou can run the AIE service on UNIX.

! To run the AIE service in the foreground

1 Open a terminal window.

2 Change to the directory where the AIE service is installed (or include the full path):

/opt/bmc/AtriumCore/pun-rem-sun08/aie/service/bin

3 Start the AIE service.

In the service/bin directory different start up script files are created to start different instances. You can access them at: ./aie001 start.

NOTE On UNIX, the AIE service is created as a batch file based on the number of BMC Atrium Integration Engine instances you install. For example, if you install three instances of BMC Atrium Integration Engine, three AIE service batch files are created named aie001, aie002, and aie003. You can create your data exchanges based on these instances. In this case, if you want to run a data exchange for the second instance, you would type ./aie002 start on the command line.

4 Perform one of the following actions.

! Stop a particular instance by using its script and parameter as stop: ./aie002 stop.

! Restart a particular instance by using its script and parameter restart: ./aie002 restart.

During startup, the AIE service displays a message telling how many active data exchanges are running. The message is refreshed at an interval configured in the aie.cfg file. However, this information does not indicate whether the active data exchanges are running successfully.

To determine whether the data exchanges ran successfully, check the data exchange debug or log files for details about individual data exchanges. By default, debug files are located in the BMCAtriumIntegrationEngineInstallationDir\service\debug directory, and log files are located in the BMCAtriumIntegrationEngineInstallationDir\service\log directory.



Loading the adapters for Oracle or DB2If you installed BMC Atrium Core and did not provide the Oracle directory or the DB2 directory, either of the following warning messages will appear if you try to start the AIE service 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.

Before you begin

Make sure that the Oracle and DB2 client directory paths are properly set in the BMC Atrium Integration Engine startup scripts before you run an instance of AIE service.

! To load the adapters

1 Perform 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 to point to the 64-bit Oracle client library.

! 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 to point to the 64-bit client library.

2 To set the variable inside the script file, perform 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 as indicated in the following example for DB2:

[ ! "$AIE_DB2_LIB_DIR" ] && AIE_DB2_LIB_DIR=/opt/IBM/DB2/V9.1

220 User’s Guide

Understanding the configuration file and its parameters


The configuration file (aie.cfg) is used by the AIE service to locate the BMC Remedy 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 aie.cfg by opening it in a text editor and making the necessary changes.

Sample configuration fileIf you installed BMC Atrium Integration Engine in the default location, aie.cfg is located in the following directory.

C:\Program Files\BMC Software\AtriumCore\myserver\aie\service\conf

In the sample aie.cfg file that follows, lines beginning with the pound (#) symbol are comments. For more information about the aie.cfg file parameters, see “Configuration file parameters” on page 223.

# BMC Atrium Core Configuration Parameters

[Log]# Adds one record, indicating status and other details, in the # AIE: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: YesLogPath: C:\Program Files\BMC Software\BMC Atrium Integration Engine\myserver\service\log# Size of the file in bytes.MaxLogSize: 102400

[Debug]# Max size for debug(.dbg) filesMaxDebugSize: 102400# Timestamp option adds a timestamp on each debug message: Yes/No.TimestampDebug: Yes# DebugOn option activates a debug file for aiemain. (Yes/No) Can also be specified on the command line to activate a debug file prior to the config file being read.DebugOn: YesDebugPath: C:\Program Files\BMC Software\BMC Atrium Integration Engine\myserver\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: IMAGINARYFRIENDARLogin: DemoARPassword: ARPort: 0

[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.ConfigInterval: 5

# 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: 1

# Chunking is only for CMDB Component Exchanges.# If CMDB with Millions of existing CI needs an update then one has to set ChunkSize to avoid AR server going out of memory.# Ideally one can set it to 50000 in production environment.# This might effect aie performance to some extent because of increase in number of CMDB calls.# With value 0 set it will get all the records from CMDB like it use to do before without chunking.ChunkSize:50000

# This option is only valid while pulling data in CMDB, with this option AIE engine will insert CI in blocks mentioned below.CMIBLOCK:1

#If BMC Atrium Integration Engine is installed in a server group, this option is set to Yes,SRVGROUP:No

222 User’s Guide


#If SRVGROUP option is set to Yes and if you want to run data exchanges on a Private RPC Port, configure the Private RPC Port.PrivateRPCPort:0

# For BMC Atrium Integration Engine in a server group, you must set the Oracle client variable to use the local host path. This path is used by all Oracle data exchanges to read the Oracle installation directory path.OraDbDirPath:C:\oracle10G\product\10.2.0\client_1

# For BMC Atrium Integration Engine in a server group you must set this variable to a common directory where all XML and flat files (.csv and .dat) are maintained.This path is used by all flat file and XML exchanges.FileDataPath:C:\Program Files\BMC Software\AtriumCore\myserver\aie\service\data

# For BMC Atrium Integration Engine in a server group, you must set the DB2 Instance name which is used by the DB2 adapter.DB2InstName:db2inst1

# Add the custom adapter name here,format for adding is APPNAME:LIBRARY/DLL NAME#if you have more than one Adapter use semicolon as a seperator. #For example, you have an INFORMIX adapter and the dll name is informadpr.dllCustomAdapter:INFORMIX:informadpr.dll;

Configuration file parametersTable B-2 provides an alphabetical list of all the standard configuration parameters used by the AIE service. The AIE service ignores any unrecognized or misspelled parameters. Default values, if any, are indicated in the description.

Table B-2: AIE service configuration parameters (part 1 of 4)


# Indicates the comment character. It enables you to comment out any line in the configuration file so that the program bypasses the line.

ARLogin Indicates the BMC Remedy AR System account that the AIE service uses for accessing the server. This account must be an BMC Remedy 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 BMC Atrium Core Application console.

ARPassword Indicates the password associated with the login for access to this server. For security, this field is encrypted.



ARServerName Indicates the name of the BMC Remedy AR System server to which this service connects. During installation, the value entered for the BMC Remedy AR System server is recorded here. You can change this parameter to another server name.

AsyncInterval Specifies the number of minutes the async thread waits before looking for new async requests. Every x minutes, the AIE 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 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 AIE service, set this parameter to a higher value, such as 1440 so that the AIE service checks it once every day.

ConfigInterval Defines, in minutes, how often the AIE service waits between checking for data exchanges that have become active or inactive since the last poll interval. The AIE 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 AIE 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 AIE:DataExchange form. The ConfigInterval parameter determines how often the AIE 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 Specifies the number of passes that the AIE service makes looking for active data exchanges. This parameter is useful for testing. After the AIE 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 a continuous activity. The default is one pass.



224 User’s Guide


ChunkSize Avoids overloading BMC Atrium Configuration Management Database (BMC Atrium CMDB). With this parameter, you can specify the number of CMDB records that can be transferred at a time in a BMC Atrium CMDB data exchange. The default value is 50000 records and you should not change this if your data exchanges run successfully. However, if the following error appears in the log file, you must specify a lower ChunkSize value:A fatal setup error occurred. The service cannot run until it is corrected. (EIEMSG 3317).For relationship CIs, BMC Atrium Integration Engine sets the ChunkSize for source class CIs at runtime depending on the number of threads configured for that exchange. The following formula is used by BMC Atrium Integration Engine when transferring relationship CIs:ChunkSize = noOfThreads x 100If the ChunkSize does not exceed 350, the minimum ChunkSize for the source class is set to 350.

CMIBlock Specifies the value of a block of records that will be inserted into BMC Atrium CMDB at a time during a data transfer. The default value is 10. This parameter is useful to enhance BMC Atrium Integration Engine performance.

CustomAdapter Specifies the name of the custom adapter that you create using the Adapter Developer Kit.

DB2InstName Specifies the DB2 instance name when BMC Atrium Integration Engine is installed in a server group. This instance name is used by the DB2 adapter.On Windows, the default value is DB2. On UNIX, the default value is db2inst1.

DebugOn Enables the AIE service to record details and problems with the AIE service in the aiemain.dbg file.The default setting is Yes.

FileDataPath Specifies the path used by all flat file and XML exchanges when BMC Atrium Integration Engine is installed in a server group. It enables you to specify a common directory where XML and flat files (.csv and .dat) are maintained.

Logging Enables or disables logging of messages to the local log file and to the AIE:Log form. Valid values are:! Yes (enable logging)! No (disable logging) 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.





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, such as increasing the maximum log size, you can edit the aie.cfg file by opening it in a text editor and making the necessary changes.

The BMC Remedy AR System parameters in the configuration file (ARLogin, ARPassword, and ARServerName) 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.

NOTE If you edit the configuration file with a text editor, the ARPassword parameter appears in plain text in aie.cfg, rather than being encrypted. This can pose a security risk.

You can use the aiecfedit utility to edit the ARPassword parameter while maintaining the encryption for your BMC Remedy AR System password in the aie.cfg file.

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

OraDbDirPath Sets the Oracle client local host path for data exchanges when BMC Atrium Integration Engine is installed in a server group. This path is used by all Oracle data exchanges to read the Oracle installation directory.

PrivateRPCPort Sets the Private RPC Port if you want to run data exchanges on a Private RPC Port when the SRVGROUP parameter is set to Yes.

StackTrace Stores a line-by-line account of the activity of the AIE service in the aiemain.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.

Srvgroup Indicates that BMC Atrium Integration Engine is installed in a server group, if this parameter is set to Yes on the servers.

TimeStampDebug Adds a timestamp at the beginning of each line in aiemain.dbg and in every exchangeName.dbg file. The default value is Yes.



226 User’s Guide


! To edit and encrypt a password in the configuration file

Type the following command on the command line using the parameters in Table B-3.

For Sun™ Solaris™ platforms:

./aiecfedit -l "Demo" -p "abc" -y "/opt/bmc/AtriumCore/pun-rem-sun08/aie/service"

For Windows platforms:

BMCAtriumIntegrationEngineInstallationDir\service\bin\aiecfedit.exe -l loginName-p password -y completePathOfInstallationDirectory

NOTE Associate a value to the ARPort parameter in the aie.cfg file, such as ARPort: 7100. Make sure that the encrypted password is associated with the ARPassword parameter.

BMC Atrium Core debug filesBMC Atrium Core debug files are located in the aieInstallationDir/service/debug directory. Table B-4 describes the debug files.

Table B-3: aiecfedit parameters


-l Indicates the login name used to login to the BMC Remedy AR System server.

-p Indicates the login password for a given login name.

-y Indicates the complete path of the install directory.

Table B-4: Debug files (part 1 of 2)

Debug file Description

AIEServiceInstance_aiemain.dbg

In this file the AIE service records all the details, activities, and problems of the AIE service. Information about data exchanges, licenses issued, licenses absent, and event requests is also logged in this file.

Note: A single AIEServiceInstance_aiemain.dbg file is created regardless of the number of data exchanges configured on the instance.

AIEServiceInstance_aieEventCleanup.dbg

In this file the logging information for the Application Pending form cleanup activity occurring at specific intervals is recorded.



Managing instancesIn the Instances Console, you can view and edit information about the AIE service instances. You can also add, delete, start, or stop an AIE service instance from the Instances Console.

NOTE When you install BMC Atrium Integration Engine for the first time, you can add instances. However, when you upgrade from an earlier version to 7.6.00 or run the installer again after installing BMC Atrium Integration Engine, you cannot add instances using the installer. You must use the Instances Console to add instances.

Multiple instances on a single computer cannot use different BMC Remedy AR System servers or BMC Atrium CMDB servers, because all instances share a single aie.cfg file. However, if multiple BMC Remedy AR System servers are on the same computer, you can have multiple AIE service instances using those different BMC Remedy AR System servers.

BMC Atrium Integration Engine retrieves the information about the existing instances from the AIE:BackUpLoadFlag form. This form is also updated when you add or delete instances.

Information about the BMC Atrium Integration Engine installation directory is also required when you add or delete instances. This information is retrieved from the AtriumCoreInstalledConfiguration.xml file.

NOTE If you do not have BMC Atrium CMDB 7.5.00 or later, you cannot add, delete, start, and stop instances in the Instances Console.

AIEServiceInstance_aieEventListener.dbg

An AIE service instance listens to a particular port for the Run Now and Verify data exchanges, and to verify Connection activities. It also keeps track of the Immediate event-driven exchange request activities that are created using the aiexfer.exe file and -i parameter. Messages related to all these activities are logged in this file.

AIEServiceInstance_aieEventMgr.dbg

In this file, the logging information of event-driven data exchanges is recorded.

dataExchange.dbg When a data exchange starts, this file logs the number of records obtained from each data store. The file shows the statistics of the number of records transferred.

Note: For each data exchange, only the statistics for the main data mapping are logged.

Table B-4: Debug files (part 2 of 2)

Debug file Description

228 User’s Guide

Managing instances

Adding an instanceThis section describes how to add an AIE service instance.

Before you begin

! Your BMC Atrium CMDB must be 7.5.00 or later.

! You must have installed BMC Atrium Integration Engine on your computer to add instances of the AIE service.

! To add an instance

1 From the BMC Atrium Integration Engine console navigation bar, click Configuration > Instances.

Figure B-1: Instances Console

2 In the Instances Console, select an AIE service instance, and click New.

The host of the selected AIE service instance is used as the host for the new instance. If you have installed the AIE service on the same computer on which the BMC Remedy AR System to which it points to is installed, you can create a new instance without selecting it.

NOTE You can add an AIE Service instance from the Instances Console only if BMC Atrium Integration Engine is installed on the same computer as BMC Remedy AR System and you have accessed the Instances Console using the BMC Remedy User.



3 Specify the Instance Name.

The instance name that you specify is appended with the name of the server on which you have added an instance and the number of the instance. The number is added by sequentially, depending on the instances already present on that server.

4 (Windows) Specify the Startup Type option.

By default the Startup Type option is set to Manually.

TIP You can also choose to start the newly added instance automatically. If you choose to start the instance automatically, the AIE service starts as soon as you create the instance.

NOTE On UNIX, this field is disabled. You must manually start an instance on UNIX.

5 Click Create.

A message confirming that the instance was succcesfully added is displayed.

If you are adding an instance on a remote host, the Sending Instance Creation request message is displayed; however, no confirmation message about the instance creation is displayed on the host computer. To confirm that a new instance is created on the remote host, you must view the AIE:BackupLoadFlag form.

You can also confirm the addition of the instance by checking the AiexferUtil.out file. The AiexferUtil.out file is located at one of the following directories from where you have run the aiexfer.exe utility:

! BMCAtriumIntegrationEngineInstallationDir\service\bin

! BMCRemedyARSystemInstallationDir\

6 Click OK.

NOTE When you create a new instance on a server group host, a new instance is created on the primary as well as all secondary servers .

7 (optional) Click Refresh to view the newly created instance in the instances table if it is not immediately displayed

BMC Atrium Integration Engine connects to all hosts that have the instance running flag set to Yes and updates the table. If BMC Atrium Integration Engine fails to connect to an instance, it sets the instance running flag to No for that instance.

TIP To avoid a timeout error, increase the Process Timeout time from BMC Remedy AR System Administration Console > System > General > Server Information > Timeouts.

230 User’s Guide

Managing instances

Deleting an instanceYou can delete an AIE service instance from the Instances Console.

Before you begin


! You must have more than one instance created to delete one of them.

! To delete an instance


2 Select the instance that you want to delete.

3 Click Delete.

NOTE You cannot delete an instance if a data exchange is associated with it. The Delete button is disabled if a data exchange is associated with an instance.

4 Click Yes to reconfirm the deletion.

A message confirming that the instance was successfully deleted is displayed.

If you are deleting an instance from a remote host, the Sending Instance Deletion request message is displayed; however, no confirmation message about the instance creation is displayed on the host computer. To confirm that an instance is deleted from the remote host, you must view the AIE:BackupLoadFlag form.

You can also confirm the deletion of the instance by checking the AiexferUtil.out file. The AiexferUtil.out file is located at one of the following directories from where you have run the aiexfer.exe utility:



5 Click OK.

NOTE When you delete an instance on a server group host, an instance on the primary as well as the secondary server is deleted.

6 (optional) Click Refresh to remove the deleted instance from the instances table if it is still displayed.

BMC Atrium Integration Engine connects to all hosts that have the instance running flag set to Yes and updates the instances table. If BMC Atrium Integration Engine fails to connect to an instance, it sets the instance running flag to No for that instance.




Starting an instanceYou can start an instance of the AIE service from the Instances Console.

Before you begin

Your BMC Atrium CMDB must be 7.5.00 or later.

! To start an instance


2 Select the instance that you want to start.

3 Click Start.

NOTE The Start button is disabled if the service is already running. If BMC Atrium Integration Engine is in a server group, when you click Start, the services on both the primary and secondary servers are started. The Start button is also disabled for instances running on secondary servers.

A message confirming that the AIE service instance is started successfully is displayed.

For an AIE service instance on a remote host, the Sending Start Instance request message is displayed. No message confirming the start of the instance is displayed.

You can confirm that the service has started on the remote host by checking the AiexferUtil.out file. The AiexferUtil.out file is located at one of the following directories from where you have run the aiexfer.exe utility:



If the BMC Atrium Integration Engine instance does not start even after you click Start, check the AIE:BackUpLoadFlag form for the following:

! The host name field contains the fully qualified domain name for the AIE host.

! The port number has been updated by the AIE service.

4 Click OK.

5 (optional) Click Refresh to view the status change of the instance in the table.

232 User’s Guide

Managing instances

BMC Atrium Integration Engine connects to all hosts that have the instance running flag set to Yes and updates the status. If BMC Atrium Integration Engine fails to connect to an instance, it sets the instance running flag to No for that instance.


Stopping an instanceYou can stop an instance of the AIE service from the Instances Console.

Before you begin


! Make sure that the instance that you want to stop is running.

! To stop an instance


2 Select the instance you want to stop.

3 Click Stop.

NOTE The Stop button is disabled if the service is not running. If BMC Atrium Integration Engine is in a server group, when you click the Stop button, that service on the primary and secondary servers is stopped. The Stop button is also disabled for instances running on the secondary server.

A message confirming that the AIE service instance is stopped successfully is displayed.

For an AIE service instance on a remote host, the Sending Stop Instance request message is displayed. No message confirm that the service has been stopped is displayed.

You can confirm that the service has stopped on the remote host by checking the AiexferUtil.out file. The AiexferUtil.out file is located at one of the following directories from where you have run the aiexfer.exe utility:



4 Click OK.

5 (optional) Click Refresh to veiw the status change of the instance in the table.



BMC Atrium Integration Engine connects to all hosts that have the instance running flag set to Yes and updates the status. If BMC Atrium Integration Engine fails to connect to an instance, it sets the instance running flag to No for that instance.


Using command line to manage instancesYou can use a command line to add, delete, start, and stop instances in the Instances Console. You perform these actions by invoking the aiexfer utility.

Before you begin


! To add instances, you must have installed BMC Atrium Integration Engine on your computer.

! To delete instances, you must have more than one instance created to delete one of them.

! To stop an instance, make sure that the instance that you want to stop is running.

! To use command line to manage instances

1 From the command prompt access the BMCAtriumIntegrationEngineInstallationDirectory\service\bin directory.

2 Use the following commands:

Table B-5: Commands to manage instances (part 1 of 2)

Action Command

Adding an instance aiexfer -CI -n aliasInstanceName -t startupType -l userName -p password -x BMCRemedyARSystemServer -a AIEServiceHostName -rpcport portNumber -inst activeInternalInstanceName -os operatingSystem -ir stateOfTheInstance -path BMCAtriumIntegrationEngineInstallationDirectory -dwhere! -t: Startup type can be 2 for Automatic and 3 for Manual! -ir: State of the instance can be Yes for running and No for not running

Deleting an instance aiexfer -DI -del AIEServiceHostName,internalInstanceName; -l userName -p password -x BMCRemedyARSystemServer -a AIEServiceHostName -rpcport portNumber -d –path BMCAtriumIntegrationEngineInstallationDirectorywhere-del: AIE service host name that you want to delete

234 User’s Guide

Managing instances

In the commands, the following parameters are common:

! -inst: Required in case of remote installation

! -d: Used for detailed logging

This is an optional parameter.

! -path: BMC Atrium Integration Engine installation directory path till the /service directory

For example, D:\Program Files\BMC Software\AtriumCore\aie\service

This is an optional parameter. You can use this parameter to hardcode the installation directory path if BMC Atrium Integration Engine uses a wrong value from the ATRIUMCORE_HOME environment variable.

Modifying the instance detailsYou can edit the instance name and port number of an instance in the Instances Console.

! To modify a BMC Atrium Integration Engine instance


2 On the Instances Console, select the instance you want to modify.

3 In the Instance Name field, type the name that you want to see when selecting this instance in other areas of the BMC Atrium Integration Engine interface.

4 In the Unicode field, select whether the instance should use the Unicode character set.

If you select No, BMC Atrium Integration Engine uses the character set that you specify at the data exchange level.

Starting an instance aiexfer -START -st AIEServiceHostName,internalInstanceName; -l userName -p password -x BMCRemedyARSystemServer -a AIEServiceHostName -rpcport portNumber -d –path BMCAtriumIntegrationEngineInstallationDirectorywhere-st: AIE service host name that you want to start

Stopping an instance aiexfer -STOP -stp AIEServiceHostName,internalInstanceName; -l userName -p password -x BMCRemedyARSystemServer -a AIEServiceHostName -rpcport portNumber -inst activeInternalInstanceName –d –path BMCAtriumIntegrationEngineInstallationDirectorywhere:-stp: AIE service host name that you want to stop

Table B-5: Commands to manage instances (part 2 of 2)

Action Command



5 Select Yes for the Use Fixed Port option, and specify the port in the Port field if you want to specify the port number for an AIE instance.

If you select No, BMC Atrium Integration Engine uses the port that it generates at runtime.

NOTE When the AIE service starts, it listens to this port and updates the port number in the AIE:BackupLoadFlag form. This port is used for the Run Now and Verify requests. The default port is 3021. When the AIE service starts or stops, the Instance_Running field is updated in the AIE:BackupLoadFlag form.

6 Click Save.

You can view, but not modify, the remaining instance information:

! Internal Instance Name—The name created by the installer for this instance

! Host—The name of the server where BMC Atrium Integration Engine is installed

! Engine Load—The readiness of the AIE service. If this value is Yes, the service is ready to start

! AIE Version—The version of BMC Atrium Integration Engine that you are running

236 User’s Guide

Managing instances

Viewing the status of an instanceYou can track the status of an instance and the exchanges associated with the instance by accessing the AIE:Exchange_Runs form. You can view the date and time when an exchange was run and view whether the exchange was run successfully. In this form, you can also view the statistical details of the records.

NOTE You can view the status of only those instances on which data exchanges have been run.

! To view the details of an instance

1 In BMC Remedy User, click File > Open > Object List.

2 On the All tab, select the AIE:Exchange_Runs form.

3 Click Search to view the AIE:Exchange_Runs (Search) form.

4 Perform an unqualified search.

5 (optional) To view instances according to the status of the data exchanges, select the Run Status, and click Search.

The following table describes the fields on the AIE:Exchange_Runs form.Table B-6: Fields on the AIE:Exchange_Runs form

Field Description

Instance Name Name of the selected instance

Data Exchange Name Name of the data exchange running on the instance

Run # Number of runs of the data exchange

Run Status Status of the exchange as Running, Completed, Aborted, or Not Responding

Started On Date and time when the data exchange was started

Completed On Date and time when the data exchange was completed

Total Records to be Processed Number of records that are to be processed

Records Processed So Far Number of records that have been processed

Records Ignored So Far Number of records that have not been processed

Data Key First key in the data chunk that has been processed by BMC Atrium Integration Engine during the data transfer

This option is useful for failover support for data exchanges. For more information about failover support, see “Failover support” on page 174.



Changing BMC Remedy AR System passwordThis section describes the procedures to change your password from the BMC Atrium Integration Engine console and in the aie.cfg file.

NOTE When you change your password, you must change it in BMC Remedy AR System, in the BMC Atrium Core console, and the aie.cfg file.

! To change your BMC Remedy AR System password on the BMC Atrium Core console

1 From BMC Atrium Core console navigation bar, select Configuration > Integration Engine App.

The BMC Atrium Core Application Console appears.

Figure B-2: BMC Atrium Integration Engine Application Console

2 In the Admin Login Name field, type the administrator login name you use for BMC Remedy AR System.

3 In the Admin Password field, type the administrator password you use for BMC Remedy AR System.

4 Click Save.

Using this method keeps the password encrypted.

The password is updated for all exchanges that are configured with the Use Default Destination AR Server option set to Yes on the Connection Settings tab of the Data Exchanges Information.

238 User’s Guide

Changing BMC Remedy AR System password

! To change your BMC Remedy AR System password in the aie.cfg file

1 Run the aiecfedit command line utility located in $AIE_HOME/service/bin.

This utility helps set the encrypted password in the aie.cfg file and makes sure that 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: -l userName -p password -y installationPathDirectory

where:

! -1 userName is the login name you use to log on to the BMC Remedy AR System server

! -p password is the login password

! -y installationPathDirectory is the complete path of the installation directory

2 Change the user name and password.

The updated password is used to load data exchanges when the AIE service starts.



240 User’s Guide

Appendix

C
CSV Syntax supported by BMC Atrium Integration Engine
BMC Atrium Integration Engine follows the RFC 4180 standard for CSV formats, but with small variations. This topic provides information on how BMC Atrium Integration Engine interprets .csv files while transferring data to and from BMC Atrium Configuration Management Database (BMC Atrium CMDB).


! Format of .csv files (page 242)! Examples of how BMC Atrium Integration Engine interprets .csv files (page 243)



Format of .csv files.csv files must follow the format described below.

! Each record is located on a separate line, delimited by a line break (CRLF).

For example,

aaa,bbb,ccc CRLFzzz,yyy,xxx CRLF

! Each line should contain the same number of fields throughout the file. Empty column data is represented by consequent commas.

For example,

Column1, Column2, Column3, Column4, Column51, testDescription, dataforColumn3, dataforColumnC4, dataforColumnC52, CSV testing, , ,dataforColumn5

In the second record, Column3 and Column4 are blank.

! Spaces are considered part of a field and are not ignored. The last field in the record must not be followed by a comma.

For example:

aaa, bbb , ccc => ‘aaa’ ‘bbb ’ ‘ ccc’

! Fields containing line breaks (CRLF) and commas should be enclosed in double-quotes.

For example,

aaa,"b CRLF bb",ccc CRLF => ‘aaa’ ‘bbb’ ’ccc’

ppp,”qq,q”,rrr => ‘ppp’ ’qq,q’ ‘rrr’

! If double-quotes are used to enclose fields, a double-quote appearing inside a field must be escaped by preceding it with another double quote.

For example:

"aaa","b""bb","ccc" => ‘aaa’ ‘b””bb’ ‘ccc’"aaa","b""b””b","ccc" => ‘aaa’ ‘b””b””b’ ‘ccc’

NOTE To remove the unwanted double quotes in the example above, use the Replace function of AIE as shown below. function|replace($Description$,"""",""")

! There should be no space between a field separator (,) and a double quote (“).

For example, the following line is invalid as there is space before “bbb”.

“aaa”, “bbb”,“ccc”

242 User’s Guide

Examples of how BMC Atrium Integration Engine interprets .csv files

Examples of how BMC Atrium Integration Engine interprets .csv files

Table C-1 describes how BMC Atrium Integration Engine interprets data from a .csv file.

Table C-1: BMC Atrium Integration Engine interpretaion of sample .csv data

Input data BMC Atrium Integration Engine interpretation

"Double quoted (Parentheses, Parentheses )", "95,1",5000

'Double quoted (Parentheses, Parentheses )' '95,1' '5000'

"Double-double quoted word then comma ""word"", eol"

'Double-double quoted word then comma ""word"", eol'

"Comma after escaped double quote\"", eol"

'Comma after escaped double quote\"", eol'

"Comma after double quote and character ""x, eol"

'Comma after double quote and character ""x, eol'

"Comma after double quote and a word ""word, eol"

'Comma after double quote and a word ""word, eol'

"Comma after double quote and 2 words "" word1, word2, eol"

'Comma after double quote and 2 words "" word1, word2, eol'

"Comma after a double quoted word and more words ""word"" word1 word2, eol"

'Comma after a double quoted word and more words ""word"" word1 word2, eol'

"Comma after a double quoted word and more words ""word"" word1 word2, eol"

'Comma after a double quoted word and more words ""word"" word1 word2, eol'

"Escaped comma after a double quoted word ""word""\, eol"

'Escaped comma after a double quoted word ""word""\, eol'

"Comma after fwd-slash escaped double quote/"", eol"

'Comma after fwd-slash escaped double quote/"", eol'

"Comma after double fwd-slash escaped double quote//""

'Comma after double fwd-slash escaped double quote//"", eol'

"Comma after double escaped double quote\\""

'Comma after double escaped double quote\\"", eol'

"Double quote & fwd-slash escaped comma "" /, eol"

'Double quote & fwd-slash escaped comma "" /, eol'

"Double quote & double fwd-slash escaped comma "" //, eol"

'Double quote & double fwd-slash escaped comma "" //, eol'

"Double quote & double escaped comma "" \\, eol"

'Double quote & double escaped comma "" \\, eol'

"1 field has double quotes "" and comma, eol"

'1 field has double quotes "" and comma, eol'

"1 field has double quotes and comma then double quote "","" eol"

'1 field has double quotes and comma then double quote "","" eol'



"1 field has double quotes and double quote then comma "", eol"

'1 field has double quotes and double quote then comma "", eol'

bob said,"oh boy!" 'bob said' 'oh boy!'

"bob said, ""oh boy!""" 'bob said, ""oh boy!""'

Input data BMC Atrium Integration Engine interpretation

244 User’s Guide

Glossary

abstract classA class that has attributes but of which no instances can be created. An abstract class exists for the purpose of creating an organizational layer without a database join. See also data replication.

accountAn entity or party whose data is represented in BMC Atrium Core, and to whom specific levels of permission can be granted. Specifying instance permission by account enables BMC Atrium Core to support multitenancy.

activityAn individual reconciliation task that can be grouped together in a defined sequence to form a reconciliation job. You can run an activity only as part of a job, never by itself. See also Comparison activity, Copy Dataset activity, Delete Dataset activity, Execute Job activity, Identification activity, Merge activity, Purge Dataset activity, Rename Dataset activity.

Adapter Development KitThe Adapter Development Kit is a software development kit that lets you build your own adapters to interact with BMC Atrium Integration Engine. The Adapter Development Kit interface defines a set of C++ objects that are used by the AIE service to manage data exchanges that use these adapters.

AIE Definitions AdminA BMC Atrium Integration Engine application role. Members can view, create, and modify data mappings and data exchanges, and manage the configuration and connection settings. See also AIE User.

AIE serviceThe AIE 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. The AIE service can connect to a BMC Remedy AR System server. It runs as a client to the BMC Remedy AR System server using the BMC Remedy AR System application programming interface (API).

AIE UserA BMC Atrium Integration Engine application role. Members can view data mappings, data exchanges, and configuration and connection settings. See also AIE Definitions Admin.

Atrium ExplorerA component of BMC Atrium CMDB that graphically displays the relationships between CIs. It can also be embedded in other BMC Remedy AR System-based applications.

attributeA property or characteristic of a class, such as the IP address of a computer system. An attribute equates to a column on a database table or a field on a BMC Remedy AR System form.

attribute permissionPermission to view or change the value in the attribute for any instance, assuming valid instance permissions.

attribute substitutionA method of data federation in context that uses placeholders to represent attributes from a linked class. Launching the link triggers the respective attribute values to be substituted for the placeholders.

Glossary 245


auditA logging of attribute values and other information for purposes of tracking the history of changes to instance data. An audit is triggered when the value of one or more specified attributes changes or when the instance is created or deleted.

base classA class that has no superclass.

BMC Atrium Core ConsoleThe main user interface of BMC Atrium CMDB, accessible from both web and BMC Remedy User clients. The BMC Atrium Core Console replaced the CMDB Console.

BMC Atrium Integration EngineA product that enables you to transfer large amounts of data between third-party data sources and both the BMC Remedy AR System and BMC Atrium CMDB.

BMC Atrium Product CatalogA BMC Remedy AR System application that is part of the BMC Atrium Core solution and provides data for normalization and discovery, including storage of product signatures, and tracks and manages products by categorization, life cycle, development status, approval status, and other attributes.

bulk functionsA set of functions you can use to create, update, and delete multiple instances in a single call. These functions can manipulate instances of different classes in a single operation.

Business Service Management (BSM)The concept of prioritizing IT efforts to support the overall goals of the business.

cardinalityThe number of members a relationship class can have on each side. Cardinality can be one to one, one to many, many to one, or many to many.

cascading deleteTo automatically delete, or mark as deleted the destination member of a relationship when the source member is deleted or marked.

Categories, Types, and Items (CTI)A method formerly used for categorizing assets in BMC Remedy Asset Management. Category, Type, and Item are each an attribute on the BMC_BaseElement class, so you can use CTIs in BMC Atrium CMDB.

categorization classA class that does not have its own BMC Remedy AR System form, but stores its instance data in the form of its superclass, preventing the need for a database join.

CDMSee Common Data Model (CDM).

childSee destination.

CISee configuration item (CI).

CI classA class that defines a type of configuration item (CI), such as a computer system or software application.

CIMSee Common Information Model (CIM).

classMetadata in BMC Atrium CMDB that defines a type of object, usually a configuration item (CI) or relationship. Either of these types of class can store data as a regular class, categorization class, abstract class, or abstract class with data replication. You can apply the final class and singleton class options to it as well.

Class ManagerA component of BMC Atrium CMDB where you can view, create, modify, and delete the classes and attributes that make up the data model, as well as view a list of subclasses for each class.

class permissionsPermission to view instances of a class in the BMC Atrium CMDB interface or access them with BMC Remedy AR System workflow.

CMDBSee Configuration Management Database (CMDB).

246 User’s Guide

Glossary

CMDB ConsoleSee BMC Atrium Core Console.

CMDB Console AdminAn application role. Members can perform searches from the BMC Atrium Core Console, view, create, and modify federation definitions, and perform BMC Atrium Core Console administrative tasks.

CMDB Console UserAn application role. Members can perform searches from the BMC Atrium Core Console and view federation definitions.

CMDB Data ChangeAn application role. Members can view, create, and modify instances if they have row-level security.

CMDB Data Change AllAn application role. Members can view, create, and modify instances independent of row-level security.

CMDB Data ViewAn application role. Members can view instances if they have row-level security.

CMDB Definitions AdminAn application role. Members can view, create, modify, and delete classes.

CMDB Definitions ViewerAn application role. Members can view class definitions.

CMDB Extended DataRelated data or CI attributes linked to or from BMC Atrium CMDB.

CMDB RE Definitions AdminAn application role. Members can view, create, modify, and delete reconciliation definitions and can start and cancel jobs.

CMDB RE Manual IdentificationAn application role. Members can identify instances manually.

CMDB RE UserAn application role. Members can view reconciliation definitions and can start and cancel jobs.

cmdbdriverA utility that executes BMC Atrium CMDB C API functions from a command line, prompting for parameters.

Common Data Model (CDM)The object-oriented, hierarchical set of classes in BMC Atrium CMDB used to represent types of CIs and relationships. The CDM is based on industry standards such as the Common Information Model (CIM) and Microsoft Windows Management Instrumentation.

Common Information Model (CIM)A definition of management information developed by the Distributed Management Task Force (DMTF) that facilitates the exchange of management information between systems.

Comparison activityA Reconciliation Engine activity that compares identified instances between two datasets, either producing a report that shows the differences or executing workflow.

configuration dataData about your IT environment, consisting of CIs and relationships.

configuration item (CI)A physical, logical, or conceptual entity that is part of your IT environment and has configurable attributes. Examples include computer systems, buildings, employees, software, and business services. One of the two types of classes in BMC Atrium CMDB. See also relationship.

Configuration Management Database (CMDB)A database that stores information about your IT configuration, including both CIs and relationships.

consumerAn application that works with data in BMC Atrium CMDB. It might view the data or modify it. See also provider.

Copy Dataset activityA Reconciliation Engine activity that copies instances from one dataset to another.

Glossary 247


CTISee Categories, Types, and Items (CTI).

data exchangeA BMC Atrium Integration Engine integration object that you execute to transfer data. A data exchange specifies the source and destination in a data transfer, the adapter to be used for the transfer, and the connection parameters to connect to the external data store. A data mapping is associated with a data exchange to transfer data.

data mappingA BMC Atrium Integration Engine integration object that defines the data to be transferred. A data mapping defines the source and destination of a data transfer, the primary key, and other fields and attributes. You can use a data mapping by associating it with a data exchange.

data replicationAn option for abstract classes. With this option, the instances of all subclasses are replicated to a single form to allow you to search the abstract class as though it had data. Only the attributes inherited from the abstract class are replicated.

datasetA logical group of data in BMC Atrium CMDB. A dataset can represent data from a particular source, a snapshot from a particular date, or other purpose. The dataset used by BMC Software products for reconciled production data is named BMC Asset. See also overlay dataset.

Dataset Merge PrecedenceA pairing of a dataset with a Precedence group. Each Merge activity references a collection of these, called a Dataset Merge Precedence set.

defined datasetOne of a pair of dataset IDs that is specified when executing a job with dynamic dataset substitution. The job is executed with the working dataset in place of the defined dataset.

Definitive Hardware Library (DHL)The Definitive Hardware Library (DHL) is a subset, or filter, of the Product Catalog that represents hardware products that are marked as approved for use in an organization.

Definitive Media Library (DML)A repository where approved software configurations are stored. Installed instances of the software can be checked against the DML for compliance with licenses and policies. From the 7.5.00 release of BMC Atrium Core, Definitive Software Library (DSL) has been renamed to Definitive Media Library.

Definitive Software Library (DSL)See Definitive Media Library (DML).

Delete Dataset activityA Reconciliation Engine activity that deletes instances from one or more datasets without removing the dataset itself. See also cascading delete, hard delete, soft delete.

destinationThe CI class defined as Class 2 in a relationship class, or an instance of that CI class as a member of such a relationship. Also known as the child member or weak member.

discoveryThe act of scanning your environment for configuration data.

discovery applicationAn application that scans your environment for configuration data and can act as a provider to BMC Atrium CMDB.

Distributed Management Task Force (DMTF)An organization appointed to facilitate the exchange of management information by promoting the initiation of industry standards and interoperability.

DHLSee Definitive Hardware Library (DHL).

DMLSee Definitive Media Library (DML).

248 User’s Guide

Glossary

DMTFSee Distributed Management Task Force (DMTF).

DSLSee Definitive Media Library (DML).

Enterprise Integration EngineSee BMC Atrium Integration Engine.

eventA particular type of change to the instances of specified classes. You can publish an event so that any instance of it is written to the CMDB:Events form. You can receive notification each time an instance of the event occurs by polling the form.

Exclusion ruleA rule that specifies an attribute to be excluded from participation in a Comparison activity.

Execute Job activityA Reconciliation Engine activity that executes a job.

extensionA logical set of classes and attributes, usually in its own namespace, that is not part of the Common Data Model (CDM).

extension loaderThe cmdbExtLoader program, which is used for installing data model extensions and importing other BMC Atrium CMDB data and metadata.

federated dataData linked from CIs in BMC Atrium CMDB but stored externally. Federated data might represent more attributes of the CIs or related information such as change requests on the CIs.

federated interfaceAn instance of the BMC_FederatedInterface class that specifies how to access a particular type of federated data. See also federated link.

federated linkThe connection between a class or CI and a federated interface.

federated productA product that holds federated data. It can be linked to more than one federated interface.

federationThe act of linking CIs in BMC Atrium CMDB to external data.

Federation ManagerA component of BMC Atrium CMDB that you can use to manage federated data. From the Federation Manager, you can view, create, and modify federated products, federated interfaces, and federated links.

filterA set of criteria for restricting the information displayed by the Atrium Explorer. This is different from a BMC Remedy AR System filter.

final classA class that cannot have subclasses.

foreign key substitutionA method of federation that assigns a key from the federated product to each linked CI. Foreign key substitution is useful when no attributes that also exist in BMC Atrium CMDB are stored in the federated product.

graph walkThe act of searching for CIs and relationships in BMC Atrium CMDB.

graph walk functionsA set of specific functions that are used to search for CIs and relationships in BMC Atrium CMDB. Use these functions when you want to search for CIs regardless of their class or relationship.

groupA set of a particular type of reconciliation definition that is referenced by an activity. See also Identification group, Precedence group, Qualification group, Workflow Execution group.

GUIDA globally unique identifier, automatically generated by the BMC Remedy AR System server. GUIDs are used for instance IDs, reconciliation IDs, and other cases where a unique value must be generated without human interaction.

Glossary 249


hard delete The act of removing an instance from BMC Atrium CMDB. See also soft delete.

Identification activityA Reconciliation Engine activity that matches instances from two or more datasets and assigns them the same identity, meaning that they represent the same real-life object.

Identification groupA set of Identification rules that collectively identify instances from a particular dataset against other datasets. Each dataset that participates in an Identification activity is paired with one Identification group.

Identification ruleA rule used when identifying instances between datasets. When two instances match the qualification for the rule, they are assigned the same reconciliation ID.

identitySee reconciliation ID.

incidentDefined by ITIL® as any event that is not part of the standard operation of a service and that causes, or might cause, an interruption to, or a reduction in, the quality of that service.

incremental mergeA Merge activity that only processes instances created or modified since the activity was last run, saving otherwise useless processing time. Setting Force Attribute Merge to No makes a Merge activity incremental.

instanceAn actual incarnation of a particular class, represented as a record in BMC Atrium CMDB. Both CIs and relationships are instances of their respective classes.

instance IDA GUID that BMC Atrium CMDB applies to each instance to uniquely identify it.

instance permissionsThe right to view or modify a specific instance. These permissions are called row-level security and write security, respectively.

instantiateTo create an instance of a class.

ITIL®

The IT Infrastructure Library® (ITIL) is an internationally accepted set of best practices developed by the British government for management of IT services.

jobA group of one or more reconciliation activities executed in sequence. You cannot run an activity by itself; only as part of a job. You can start a job manually, with a schedule, with an Execute Job activity, with workflow, or with an API program.

key queryLimits the records transferred in a data transfer in the BMC Atrium Integration Engine. See also row-level query.

Merge activityA Reconciliation Engine activity that merges two or more datasets into a single complete and correct dataset based on precedence values that favor the strengths of each dataset.

metadataDefinitions that describe the data stored in BMC Atrium CMDB. Metadata includes classes in the data model and special classes to define things such as datasets and federation objects.

multitenancyThe separation of data and access so that a single BMC Atrium CMDB can contain the data of multiple parties, but each party can access only their own data. See also account, role.

namespaceA logical set of classes and attributes in the data model, usually related to a specific consumer or provider. The Common Data Model (CDM) uses the BMC.CORE namespace.

250 User’s Guide

Glossary

normalizeTo ensure that data of the same type follows the same text formatting conventions. This helps reconciliation by making it more likely for instances to match in an Identification activity.

Normalization EngineA BMC Atrium CMDB application that provides a centralized, customizable, and uniform way to overcome consistency problems by normalizing attributes for software and hardware products.

orphanAn instance that has been physically deleted from source datasets but still exists in the target dataset into which they merge.

overlay datasetA dataset that provides a layer in which to make changes that are pending approval. API queries to the dataset seamlessly return its modified instances along with unmodified instances from the underlying regular dataset.

parentSee source.

Precedence groupThe definition of an overall precedence value for a dataset. It can optionally contain precedence values for specific classes and attributes within the dataset.

precedence valueA method of assigning weight to specific datasets, classes, and attributes in a Merge activity. Attribute precedence values override class precedence values, which override dataset precedence values.

primary keyA primary key uniquely identifies a row of data. In BMC Atrium Integration Engine you must specify the attributes of a CI class and the corresponding fields in the external data store to create the primary key. After a data transfer, the primary key is the link that matches a record in the external data store with its counterpart in BMC Atrium CMDB.

product categorizationDivides CIs into groups. Using the three-tier structure of product categorization, you can create successively smaller, more tightly defined groups. You can create groups of CIs in Tier 1 followed by smaller groups in Tier 2 and Tier 3.

production datasetThe dataset that serves as the single source of reference for your organization and from which you make business decisions. It acts as the target dataset in most Merge activities.

providerAn application, often a discovery application, that loads bulk data into BMC Atrium CMDB. See also consumer.

provisioningThe process of providing access to resources, such as printers, telephones, and so on, and to information, such as permissions, databases, and so on.

publishTo make an event available so that instances of it can be written to the CMDB:Events form.

Purge Dataset activityA Reconciliation Engine activity that removes instances that have been marked as deleted from one or more datasets.

QualificationA Boolean statement that is evaluated to determine whether an instance should be included in an activity.

Qualification groupA set of Qualifications that can be used in various types of activity. An instance that meets one or more Qualifications in the group is included in the activity.

reconciliationThe process of managing data in multiple datasets using the Reconciliation Engine. The main activities of reconciliation are identifying, comparing, and merging datasets, though the Reconciliation Engine performs other activities as well.

Glossary 251


reconciliation definitionAn entity defined in the Reconciliation Manager such as a job, activity, or group.

Reconciliation EngineThe component of BMC Atrium CMDB that reconciles data from different datasets.

reconciliation IDA GUID that the Reconciliation Engine assigns to instances in different datasets that represent the same real-life object.

Reconciliation ManagerThe component of BMC Atrium CMDB that you can use to manage reconciliation definitions.

regular classA class that stores its instance data in its own BMC Remedy AR System form. See also abstract class, categorization class.

related informationInformation about a CI that does not qualify as attributes of the CI, and should therefore not be stored in a Configuration Management Database (CMDB).

relationshipA connection between two CIs such as a dependency or membership. It is an instance of a relationship class. See also configuration item (CI).

relationship classA class that defines a type of relationship between CIs, such as a dependency or membership.

relationship filterSee filter.

relationship keyA relationship key uniquely identifies a row of data in a relationship mapping. In BMC Atrium Integration Engine you must specify the attributes of a primary CI class and a secondary CI class to create the relationship key. After a data transfer, the relationship key is the link that matches a record in the external data store with its counterpart in BMC Atrium CMDB.

Rename Dataset activityA reconciliation activity that renames a dataset without changing its ID, preserving references to the dataset from any reconciliation definitions.

roleA designation that grants permissions to more than one BMC Remedy AR System group.

row-level queryLimits the transfer of data on a row-by-row basis in the BMC Atrium Integration Engine. See also key query.

row-level securityThe permission required to view a specific instance. See also write security.

ruleOne or more criteria that, when met, cause an action. The types of rules used in BMC Atrium Core are Exclusion rule, Identification rule, and Workflow Execution rule.

rulesetA group of rules.

service level agreementA contract between a service provider and a purchaser that defines the level of service.

singleton classAn optional class characteristic that restricts the class to holding only one instance.

snapshotA set of data that represents a configuration at a certain point in time, usually stored in its own dataset. There can be multiple snapshots of a given configuration.

soft deleteThe act of marking an instance as deleted from BMC Atrium CMDB by setting the MarkAsDeleted attribute to Yes. See also hard delete.

sourceThe CI class defined as Class 1 in a relationship class, or an instance of that CI class as a member of such a relationship. Also known as the parent member or strong member.

252 User’s Guide

Glossary

subclassA class that is derived from another class, which is called its superclass. The subclass inherits all the attributes of its superclass and any superclasses above it in the hierarchy, and can also participate in relationships defined for all superclasses.

superclassA class from which other classes, called subclasses, are derived.

synchronizationThe automatic process of creating BMC Remedy AR System forms and workflow to represent a class that has just been created or modified. The class is not available until synchronization completes.

text normalizationSee normalize.

weak referenceSee weak relationship.

weak relationshipAn optional characteristic for relationship classes, signifying that the members of a relationship form a composite object that can be reconciled as one. The destination member is considered the weak member of a weak relationship, existing as part of the source member.

Windows Management Instrumentation (WMI)The Microsoft application of the Web-Based Enterprise Management initiative for an industry standard for accessing management information.

WMISee Windows Management Instrumentation (WMI).

workflowBMC Remedy AR System objects such as active links, escalations, and filters that perform actions against data.

Workflow Execution groupA set of Workflow Execution rules. Each Comparison activity can optionally reference one Workflow Execution group.

Workflow Execution ruleA rule used when comparing instances between datasets. When a compared instance matches the qualification for the rule, specified BMC Remedy AR System workflow is executed against the instance or the instance against which it is compared.

working datasetOne of a pair of dataset IDs that is specified when executing a job with dynamic dataset substitution. The job is executed with the working dataset in place of the defined dataset.

write securityThe permission required along with row-level security to modify or delete a specific instance. See also row-level security.

Glossary 253


254 User’s Guide

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 223$field$ option for BMC Remedy AR System query

syntax 211.csv file

error handling 177format supported 241logging errors 177

Aactivating data exchanges 164Adapter Development Kit 20adapter rule helper utility 40

DB2 40file 52Oracle 44SQL 47XML 52

advanced settingscharacter set 161debugging 161performance 161using 161

AIE service 20, 225command-line parameter 218debug file (aiemain.dbg) 225rule syntax 200running on UNIX, from a command line 219

aie.cfg fileediting 226location 221parameters 223sample file 221

aie.cfg file parameters# (pound sign) 223ARLogin 223ARPassword 223ARServerName 224AsyncInterval 224

aie.cfg file parameters (continued)ChunkSize 225CMIBlock 225ConfigInterval 224ConfigPassCount 224CustomAdapter 225DB2InstName 225DebugOn 225FileDataPath 225logging 225MaxDebugSize 225MaxLogSize 226OraDbDirPath 226PrivateRPCPort 226Srvgroup 226StackTrace 226TimeStampDebug 226

AIE:Exchange_Runs form 174, 175, 237aiecfedit 226aiexfer utility

command syntax examples 194completion code messages 195completion codes returned by 195definition of 20

ARLogin parameter 223ARPassword parameter 223ARServerName parameter 224assigning data mappings to a data exchange 143AsyncInterval parameter 224

Bblank values, validity of 79, 105, 130blanks, trailing 79, 106, 130BMC Atrium Integration Engine, introduction to 16BMC Remedy Action Request System (BMC Remedy

AR System)API documentation 20query syntax 211, 212

BMC Remedy AR System Home Page 33BMC Remedy AR System query syntax

Index 255


BMC Remedy AR System query syntax (continued)function syntax 212syntax statement 211value option 211

BMC Remedy AR System query syntax, $field$ option 211

BMC Remedy IT Service Management 184BMC Remedy User, accessing BMC Atrium

Integration Engine with 32BMC Software, contacting 2browsers, accessing BMC Atrium Integration Engine

with 34

Cchecksum 80, 106, 131ChunkSize parameter 225CMIBlock parameter 225command-line parameter 218ConfigInterval parameter 224ConfigPassCount parameter 224configuration file

editing 226location 221parameters 223sample file 221

connection parametersDB2 169managing 169Oracle 170SQL Server 172

connection settings, defining 149constant syntax 200, 201CSV flat files, defining connection settings 152CustomAdapter parameter 225customer support 3

DData Exchange application 18data exchange debug files, timestamp 226data exchange status

Aborted 237Completed 174, 237Not Responding 237Running 174, 237

data exchangesactivating 164assigning data mappings to 143creating 138defining multiple data mappings 143defining parameters 138

defining schedules 140definition of 135definitions 18example 136running in event-driven mode 140running in schedule-driven mode 140running on UNIX 219running simultaneously 136strategy with BMC Atrium CMDB 136triggering one from another 148verifying conditions 165

Data Key 174, 237data key queries 73, 125, 212data key query syntax

field option 213KEY syntax 214KEYLIST syntax 214value option 214

Data Mapping & Schedule tab 37data mappings

assigning to a data exchange 143defining delete field mappings 70, 122

data mappings, defining queries 211, 215data transfer, direction of 16DB2 connection parameters, managing 169DB2, adapter rule helper utility 40DB2, defining connection settings 151DB2InstName parameter 225debug file

.dbg 228aieEventCleanup.dbg 227aieEventListener.dbg 228aieEventMgr.dbg 228aiemain.dbg 227

debug file (aiemain.dbg)disabling 225enabling 225

debug file (aiemain.dbg), timestamp 226debugging

AIE service debug file, timestamp 226data exchange debug files, timestamp 226maximum debug file size 225

DebugOn parameter 225defining

delete field mappings for AR forms 122delete field mappings for CI classes 70queries 215rules 200

defining connection settings 149CSV flat files 152DB2 151Oracle 154

256 User’s Guide


defining connection settings (continued)SQL Server 156XML 159

defining data exchange parameters 138defining multiple data mappings 143defining schedules 140delete field mapping, defining 70, 122delete queries 77, 124, 128demand data exchanges, running 166diary history field 80, 130direction of data transfer 16disabling logging 225display pane 35

Eenabling logging 225error handling

See .csv fileEvent Request interface

activating requests through workflow 197invoking requests through aiexfer 191

Event Request interface, definition of 20event-driven mode, running 140execution of data exchanges, managing 145exporting data 178

to a file 180to a server 178

Ffailover support 174field option for data key query syntax 213file, adapter rule helper utility 52FileDataPath parameter 225function syntax

BMC Remedy AR System queries 212rules 200

Hhelper utility

about 40DB2 40file 52Oracle 44SQL 47XML 52

History tab 36history, recording 80, 130

Iimport data

using BMC Remedy Data Import 182using BMC Remedy Data Import command

line 182using BMC Remedy Import 182using BMC Remedy Import command line 182

importing data 181initialization phase of data transfers 21instance

adding 229deleting 231starting 232status 237stopping 233

invoking requests using aiexfer, Event Request interface 191

ITSM 184

KKEY syntax for data key queries 214KEYLIST syntax for data key queries 214

Llocation, configuration file 221log files

disabling 225enabling 225maximum size 226

logging parameter 225

Mmanaging connection parameters 169

DB2 169Oracle 170

managing connection parameters, SQL Server 172managing execution of data exchanges 145managing instances

using command line 234using Instances Console 228

MaxDebugSize parameter 225maximum file size

debug 225log 226

MaxLogSize parameter 226

Index 257


monitoring consoleviewing data exchanges 35

monitoring console, accessing 34multiple data mappings, defining 143

Nnested rules 200

OOracle connection parameters, managing 170Oracle, adapter rule helper utility 44Oracle, defining connection settings 154OraDbDirPath parameter 226

Pparameters

command line 218debug file 225debug timestamp 226

populating, SQL field information 49precedence syntax 200, 202, 209PrivateRPCPort parameter 226process command syntax 200, 208processing phase of data transfers 22product support 3

Qqueries, defining 211query syntax

See also BMC Remedy AR System query syntax and data key query syntax

row-level syntax, SRC syntax 215

Rresponse queries 76, 124, 127Retrieve Delta 183Retrieve Delta option 106Retrieve Source Records 183Retrieve Source Records option 106Role

AIE Definitions Admin 27AIE User 27

row-level queries 72, 77, 123rule helper utility 40

DB2 40file 52

rule helper utility (continued)Oracle 44SQL 47XML 52

rulesconstant syntax 200, 201defining 200function syntax 200precedence syntax 200, 202, 209process command syntax 200, 208SQL command syntax 200, 207stmt command syntax 209target process command syntax 200, 208target SQL command syntax 200, 207vendor rules 201

running data exchanges on demand 166running the AIE service on UNIX, from a command

line 219

Ssample file, aie.cfg 221schedule-driven mode, running 140security 226server group 32source syntaxSQL command syntax 200, 207SQL field information, populating 49SQL Server, defining connection settings 156SQL Server, managing connection parameters 172SQL, adapter rule helper utility 47SRC syntax for row-level queriesSrvgroup parameter 226StackTrace parameter 226stmt command syntax 209support, customer 3syntax ($KEYLIST$) 214syntax statement for BMC Remedy AR System

queries 211

Ttarget process command syntax 200, 208target SQL command syntax 200, 207technical support 3timestamp parameters for debug files 226TimeStampDebug parameter 226trailing blanks 79, 106, 130triggering one data exchange from another 148

258 User’s Guide


UUNIX, running the AIE service, from a command

line 219update queries 74, 124, 126updating records only if values change 80, 106, 131Use Fixed Port option 236using advanced settings 161

Vvalue option

BMC Remedy AR System query syntax 211data key query syntax 214

vendor rules 201verifying data exchange conditions 165

Wworking with data exchanges

activating 164running on demand 166verifying conditions 165

XXML, adapter rule helper utility 52XML, defining connection settings 159

Index 259


260 User’s Guide

*176790**176790**176790**176790*

*176790*

bmc atrium integration engine 7.6.04 users guide

Documents

bmcatriumintegrationengineinstallationdirservicebin

aieinstallationdirservicebinrlohelper

aiedataexchangewindowsaieda

definitive

definitive

software development

bmc atrium

bmc atrium