AIE User Guide

BMC Atrium Integration Engine 8.1.
00
User Guide
February 2013
www.bmc.com
Contacting BMC Software
You can access the BMC Software website at http://www.bmc.com. From this website, you can obtain information
about the company, its products, corporate offices, special events, and career opportunities.
United States and Canada
Address BMC SOFTWARE INC Telephone 713 918 8800 or Fax 713 918 8000
2101 CITYWEST BLVD 800 841 2031
HOUSTON TX 77042-2827
USA
Outside United States and Canada
Telephone (01) 713 918 8800 Fax (01) 713 918 8000
If you have comments or suggestions about this documentation, contact Information Design and Development by email at
doc_feedback@bmc.com.
© Copyright 2009-2013 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 legend

U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF
THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to
restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and
DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is BMC Software, Inc., 2101 CityWest Blvd., Houston, TX
77042-2827, USA. Any contract notices should be sent to this address.
Customer Support
You can obtain technical support by using the Support page on the BMC Software website or by contacting Customer
Support by telephone or email. To expedite your inquiry, please see “Before Contacting BMC Software.”
Support website
You can obtain technical support from BMC Software 24 hours a day, 7 days a week at
http://www.bmc.com/support. From this website, you can:
■ Read overviews about support services and programs that BMC Software offers.
■ Find the most current information about BMC Software products.
■ Search a database for problems similar to yours and possible solutions.
■ Order or download product documentation.
■ Report a problem or ask a question.
■ Subscribe to receive email notices when new product versions are released.
■ Find worldwide BMC Software support center locations and contact information, including email addresses, fax
numbers, and telephone numbers.
Support by telephone or email

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

Have the following information available so that Customer Support can begin working on your issue immediately:
■ Product information
— Product name
— Product version (release number)
— License number and password (trial or permanent)
■ Operating system and environment information
— Machine type
— Operating system type, version, and service pack
— System hardware configuration
— Serial numbers
— Related software (database, application, and communication) including type, version, and service pack or
maintenance level
■ Sequence of events leading to the problem
■ Commands and options that you used
■ Messages received (and the time and date that you received them)
— Product error messages
— Messages from the operating system, such as file system full
— Messages from related software
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 customer_support@bmc.com. (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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Calbro Services user story in BMC Atrium Integration Engine documents . . . . . . . . 17
Roles used in the Calbro Services user story . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
BMC Atrium Integration Engine components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Data Exchange application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
AIE service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Event Request interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Adapter Development Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Data transfer process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Initialization phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Processing phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Performance considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Using multiple data exchanges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Roles and permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
BMC Atrium Integration Engine in a server group environment . . . . . . . . . . . . . . . . 28
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
How BMC Atrium Integration Engine works in a server group . . . . . . . . . . . . . . 29
Debug files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Accessing the Data Exchange Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Accessing 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Using the DB2 Adapter Rule Helper utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Populating DB2 UDB field information using the Database Field Menus Console
40
Populating DB2 UDB field information for external data tables using a command
line. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Using the DB2 UDB adapter rule helper utility on UNIX platforms . . . . . . . . . . . 43
Using the Oracle Adapter Rule Helper utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Populating 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 . . . . . . . . . . . . . . 47
Using the SQL Server Adapter Rule Helper utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Populating SQL Server field information for multiple external data tables . . . . . 48
Populating SQL Server field information for multiple external data tables using a
Windows based application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Populating 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Using the File Adapter Rule Helper utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Chapter 3 Creating data mappings for BMC Atrium CMDB CI classes 53

Example CMDB data scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Before creating data mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Overview of the data mapping process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Defining data mapping parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Accessing parent record elements along with child record elements from an XML
file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Defining the primary key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Defining data field mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Setting response fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Defining delete field mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Defining queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Defining a data key query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Defining an update query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Defining a response query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Defining 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Methods for mapping relationship classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Attributes in the member CI classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Data in an external data store. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
High-level steps in the relationship data mapping process . . . . . . . . . . . . . . . . . . . . . . 89
Defining data mapping parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Defining relationship keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Defining attribute field mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Defining delete field mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Defining queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Defining a primary class query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Defining a secondary class query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Defining a relationship class query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Defining an external data store query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Setting data mapping options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
6 User 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 . . . . . 110
Defining data mapping parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Defining the primary key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Defining data field mappings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Setting response fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Defining delete field mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Defining a data key query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Defining an update query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Defining a response query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Defining a delete query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Setting data mapping options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Populating the rule control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Chapter 6 Data exchanges 135

Using data exchanges with BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Overview of creating a data exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Defining data exchange parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Assigning data mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Managing execution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Defining connection settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Supported data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Defining connection settings for DB2 UDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Defining connection settings for flat files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Defining connection settings for Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Defining connection settings for SQL Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Defining connection settings for XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
RPC ports in BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Using advanced settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Activating a data exchange. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Verifying a data exchange configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Running a data exchange on demand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Managing connection parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Managing DB2 UDB connection parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Managing Oracle connection parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Managing SQL Server connection parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Using the AIE:VendorConfiguration form to specify connection settings . . . . . 173
Failover support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Failover support for data exchanges transferring data into CI classes and BMC
Remedy AR System forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Failover support for relationship data exchanges . . . . . . . . . . . . . . . . . . . . . . . . . 175
Error handling in BMC Atrium Integration Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Logging errors in the .csv file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Exporting and importing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Exporting data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Importing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Enhanced retrieve delta feature for relationship exchanges . . . . . . . . . . . . . . . . . . . . 183
Sample data exchanges for BMC Remedy ITSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
7
Chapter 7 Activating event-driven data exchanges 187
Creating a request on the Application Pending form . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Creating a request using the aiexfer utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Examples of the event-driven request command syntax . . . . . . . . . . . . . . . . . . . . 194
Completion codes returned by aiexfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Activating an event-driven data exchange through workflow . . . . . . . . . . . . . . . . . . 197
Appendix A Defining rules and queries 199

Defining rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Constant syntax (constant|string). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Precedence syntax ({rule} {rule} {rule}) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Function syntax (function|function(parameters)) . . . . . . . . . . . . . . . . . . . . . . . . . 202
SQL command syntax (sql|command). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Target SQL command syntax (targetsql|command) . . . . . . . . . . . . . . . . . . . . . . . 207
Process command syntax (process|command) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Target process command syntax (targetprocess|command). . . . . . . . . . . . . . . . . 208
If/then/else syntax (STMT|statement) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
BMC Remedy AR System query syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Data key syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Row-level query syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Appendix B Running and configuring the AIE service 217

Running the AIE service on Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Running the AIE service on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Loading the adapters for Oracle or DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Understanding the configuration file and its parameters . . . . . . . . . . . . . . . . . . . . . . 221
Sample configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Editing the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
BMC Atrium Core debug files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Managing instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Adding an instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Deleting an instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Starting an instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Stopping an instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Using command line to manage instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Modifying the instance details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Viewing 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Examples of how BMC Atrium Integration Engine interprets .csv files . . . . . . . . . . 243
8 User Guide
Glossary 245
Index 255
9
10 User 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)

BMC Atrium Integration Engine 7.7.00
Overview of BMC Atrium Integration Engine

With 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 Service Desk application
! Synchronize asset data tracked in BMC 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
BMC Remedy AR System

database
External
data store
BMC Remedy
AR System
BMC Atrium form
Integration
Data Engine
object
BMC Atrium
CMDB class
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
16 User 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 story

Although 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 components

BMC 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

database or BMC Atrium CMDB
Data Exchange
application
Application
Pending form
BMC Remedy BMC Atrium BMC Atrium
AR System CMDB Integration
APIs APIs Engine
AIE Event Request

service interface (aiexfer)
Adapter Development
Kit interface
DB2 Oracle SQL XML Flat File

adapter adapter adapter adapter adapter
? ? ?
DB2 Oracle SQL Server XML Flat Other Other Other
database database database file file data store data store data store
Adapters provided by BMC Atrium Integration Engine Custom adapters (not included)
Data Exchange application

The 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.
18 User 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 service
The 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.7.00 C API Reference.
Event Request interface

You 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 Kit

BMC 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.7.00 ADK Developer's Guide.
20 User Guide
Data transfer process
Data transfer process

When 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 phase
The 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 phase
In 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 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 considerations
Performance 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 Use multiple instances to split a data exchange
tab of the Data Exchanges when the number of data keys in the transfer might
Information form 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.

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

Option Where do I set this option? Usage
Multiple sessions Concurrent Session Limit field on Use multiple sessions for event-driven data
the Main tab of the Data exchanges if your adapter receives data transfer
Exchanges Information form 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 Use multithreading only for high-volume traffic in
Advance Settings tab of the Data which a single data exchange session cannot handle
Exchanges Information form 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.
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
ofthreads, see the BMC RemedyAction Request System 7.7.00 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.
24 User Guide
Using multiple data exchanges
Using multiple data exchanges

To 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

Data exchanges
Computer
systems
Dublin Database New York Database
Storage
devices
Data
Data
Other
components
Software

Roles and permissions

To 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.7.00 Configuration Guide. For
information about working with groups and roles in general, see the BMC Remedy
Action Request System 7.7.00 Form and Application Objects Guide. For information
about working with Atrium Core groups and roles, see the BMC Atrium CMDB
7.7.00 Administration 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.7.00 Administration Guide.
26 User 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 ! View, create, and modify data Calbro Services wanted to assign this role to
Admin mappings and data exchanges Mary Mann, who would work as the
! Manage the BMC Atrium Integration administrator for BMC Atrium Integration
Engine configuration and connection Engine. Calbro Services performed the
settings 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 Calbro Services wanted to assign this role to
exchanges Allen Allbrook to monitor the data mappings
! View configuration and connection and data exchanges. Calbro Services performed
settings 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.
Prerequisites
Before 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 AR System Administration Console. For more
information, see “Running servers as part of a group” in the BMC Remedy Action
Request System 7.7.00 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 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.7.00 Configuration Guide.
How BMC Atrium Integration Engine works in a server group

A 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
Server Host Instance name

Primary server: Host1 AR1_Host1_Inst001
AR1 Host1 Host1 AR1_Host1_Inst002
Host1 AR1_Host1_Inst003
Secondary server: Host2 AR1_Host1_Inst001
AR2 Host2 Host2 AR1_Host1_Inst002
Host2 AR1_Host1_Inst003
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.

Debug files
The 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.
Datasets
A 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 Guide
Datasets
BMC discovery products and BMC Asset Management provide the default
datasets in BMC Atrium CMDB as shown in Table 1-4:
Table 1-4: Default datasets in BMC Atrium CMDB

Data created by Dataset name DatasetID
BMC Atrium CMDB BMC Asset BMC.ASSET
BMC Asset Management BMC.ASSET.SANDBOX BMC.ASSET.SANBO
X
BMC Atrium CMDB BMC Sample BMC.SAMPLE
BMC BladeLogic Client Automation BMC Configuration Import BMC.IMPORT.CONF
IG
BMC Atrium Discovery and BMC Topology Import BMC.IMPORT.TOPO
Dependency Mapping
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.7.00 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.7.00 Normalization and Reconciliation Guide.

Getting started
The 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 Console

The 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 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.7.00 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
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
AIE Console link
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.

! 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.7.00 User Guide.
Perform the following steps to access the BMC Atrium Integration Engine
monitoring console from the BMC Atrium Core Console.
34 User Guide
Accessing the BMC Atrium Integration Engine monitoring console
! 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 console

The 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 tab

All 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 For CI or BMC Remedy AR System form data mappings, this field
Records 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 Displays the number of records that have been processed.
Processed
Number of Records Displays the number of records that have not been transferred.
Failed
Number of Records Displays the number of records that have been successfully
Successful transferred.
36 User Guide
Accessing the BMC Atrium Integration Engine monitoring console
The Data Mapping & Schedule tab

The 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 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 utilities

Use 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 utility

You 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 Guide
! 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 Guide
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:
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:
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 platforms
For 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 utility

You 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

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

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
DBOwner -d
On UNIX:
BMCRemedyARSystemServerInstallationDir/bin/rlohelper -ax
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 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 platforms

For 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.
Using the SQL Server Adapter Rule Helper

utility
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
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 Guide
7 Click Get Result.

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

You 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 utility

You 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 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 scenario

The 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
Computer table
Name SerialNumber PartNumber

Computer 910 59820 MFG3164538
Computer 912 63425 MFG3164538
Computer 921 61789 MFG3164538
Computer 954 62673 MFG3164538
Computer 911 59623 MFG3164538
Disk Drive table

Name SerialNumber PartNumber AssociatedComputer
Disk 1520 23541 MFG729817 Computer 910
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.
54 User Guide
Before creating data mappings
Before creating data mappings

Before 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.7.00
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.
NOTE
If you make changes to the .csv file (such as add a new column or change the
name of an existing column) after you have created the corresponding .tbl file,
the changes are not automatically reflected in the .tbl file. When you open the
data mapping for the .csv file, the .tbl file is regenerated and the new or updated
fields are displayed in the list of attributes. You can map the new or updated fields
to attributes in BMC Atrium CMDB. If the fields contain line breaks (CRLF) and
commas, you must enclose the fields in double-quotes.
56 User 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 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>
</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 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 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.7.00 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 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.7.00 Administration 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 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 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
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 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.
TIP
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 Guide
Defining queries
Table 3-1: Supported query types (Continued)

Response A response query is a row-level query applied only to source rows that
query 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.
Defining a data key query

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

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 query

You 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 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:
query statement.
NOTE
It does not use BMC Remedy AR System syntax like other query fields.
NOTE
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 query

You 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.
query statement.
NOTE

4 Click Save.
76 User Guide
Defining queries
Defining a delete query

You 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:
query statement.
NOTE

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 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 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 Guide
Chapter

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 relationship keys (page 94)
! Defining attribute field mappings (page 97)
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.7.00 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 Guide
Methods for mapping relationship classes

You 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 classes

Figure 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
External
BMC Atrium
data
CMDB
store
Computer table BMC_ComputerSystem

Name OrderId Name OrderId InstanceId
Computer 910 C6648 Computer 910 C6648 1F8FEF67A
Computer 912 C6649 Data Mapping Computer 912 C6649 1F8FBE71C
Computer 921 C6650 Computer 921 C6650 1E6A2L5AF
Computer 954 C6651 Computer 954 C6651 1C4E8A2FF
Computer 911 C6652 Computer 911 C6651 1A2B2C5CD
Disk Drive table BMC_DiskDrive

Name OrderId AssociatedComputer Name OrderId AssociatedComputer InstanceId
Disk 1520 D2648 Computer 910 Disk 1520 D2648 Computer 910 1F6ABC21F
Disk 1523 D2649 Computer 912 Disk 1523 D2649 Computer 912 1B3CFA89D
Disk 1560 D2650 Computer 921 Data Mapping Disk 1560 D2650 Computer 921 1E8AFB71E
Disk 1534 D2651 Computer 954 Disk 1534 D2651 Computer 954 1A2CAC48F
Disk 1530 D2652 Computer 911 Disk 1530 D2652 Computer 911 1F5AFE19A
Relationship
Class
Mapping
BMC_HostedSystemComponents
Source.InstanceId Destination.InstanceId
1F8FEF67A 1F6ABC21F
1F8FBE71C 1B3CFA89D
1E6A2C5AF 1E8AFB71E
1C4E8A2FF 1A2CAC48F
1A2B2C5CD 1F5AFE19A
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.
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 store

You 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 Guide
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 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.
page 100.
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.
NOTE
database.
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
90 User 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.
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
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 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:
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.
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
mapping. See the option If a Record Is Deleted From Source on the Main tab of the
to data mapping, the selection you make here takes effect. If instead the data
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 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.7.00 Administration 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 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.
TIP
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.
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 ID of the dataset where the BMC_ComputerSystem.DatasetId ->
relationship should be created. BMC_HostedSystemComponents.Datas
etId
This puts the relationship in the same dataset
as the member CIs.
Destination.DatasetI DatasetId of the secondary CI BMC_DiskDrive.DatasetId ->
d1 class BMC_HostedSystemComponents.Desti
nation.DatasetId
Name The appropriate value for the constant|SYSTEMHARDWARE ->
type of relationship that you are BMC_HostedSystemComponents.Name
creating. For a list of potential
values, see the Relationship
Normalization Table in Mapping
Your Data to BMC Atrium CMDB
7.7.00 Classes.
Source.DatasetId1 DatasetId of the primary CI BMC_ComputerSystem.DatasetId ->
class BMC_HostedSystemComponents.Sourc
e.DatasetId
1. This
attribute field mapping is required only if the Restrict to DatasetId option is not selected for the
data mapping.
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.
98 User 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.
TIP
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 Guide

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

Primary class query Filters out instances of the primary CI class, which are used to
create the relationship.
Secondary class Filters out instances of the secondary CI class, which are used to
query create the relationship.
Relationship class Filters out instances of the relationship class.
query
External data store Filters out instances from the external data store, which are used to
query create the relationship when using the external data store as your
relationship source.
Defining a primary class query

You 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.
NOTE
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 query

You 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 Guide

Defining queries
Defining a relationship class query

You 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

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 query

You 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

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 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:
! 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.
others ignore trailing blanks. Values are as follows:
match.
Changed option.
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.
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.
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 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 Guide

Chapter

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 the primary key (page 116)
! Defining data field mappings (page 118)
! Setting response fields (page 120)
! Populating the rule control (page 131)
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 Guide

page 121.
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.
NOTE
database.
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 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.
Engine cannot find the specified table. The case-sensitive syntax for this field is
as follows:
! DB2: DatabaseOwner.TableName
! Oracle: DATABASEOWNER.TABLENAME
! SQL Server: DBO.TableName
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.
NOTE
If you make changes to the .csv file (such as add a new column or change the
name of an existing column) after you have created the corresponding .tbl file,
the changes are not automatically reflected in the .tbl file. When you open the
data mapping for the .csv file, the .tbl file is regenerated and the new or updated
fields are displayed in the list of attributes. You can map the new or updated fields
to attributes in BMC Atrium CMDB. If the fields contain line breaks (CRLF) and
commas, you must enclose the fields in double-quotes.
114 User Guide

Likewise, an .xml file must have a corresponding .xsd file with the same name
located in the same folder.
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>
</attributes>
</myrecord>
<myrecord>
<attributes>
</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:

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 121.
equivalent record in the target is physically deleted. BMC Remedy AR System
has no way to re-create a deleted instance.
NOTE
mapping. See the If a Record Is Deleted From Source option on the Main tab of the
to data mapping, the selection that you make here takes effect. If instead the data
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 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 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.
! 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.
120 User Guide

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.
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.
122 User Guide

Defining queries
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 130.
Table 5-1 shows the query types that are supported for BMC Remedy AR System
forms.

Data key The AIE service obtains the list of rows to be transferred in a data
query 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 A response query is a row-level query applied only to source rows that
query 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.
Defining a data key query

You 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.
124 User Guide

Defining queries
NOTE
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 query

You 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:
query statement.
NOTE
3 Click Save.
Defining a response query

You 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.
query statement.
3 Click Save.
126 User Guide

Defining queries
Defining a delete query

You 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.
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
128 User Guide

This option specifies which action to take if an error prevents data from being
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.
others ignore trailing blanks. Values are as follows:
match.
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.
Changed option.
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.
subject to any data key queries and update queries that you have defined.
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.
130 User Guide

Populating the rule control

You 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

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.
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.
132 User Guide

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 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 168)
! 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 CMDB

When 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 1
ComputerExchange
DiskDriveExchange BMC_DiskDrive On completion of 2
ComputerExchange
MonitorExchange BMC_Monitor On completion of 3
ComputerExchange
SoftwareExchange BMC_Product On completion of 4
ComputerExchange
CS-OSExchange BMC_HostedSystemComponents, On completion of 1
relating BMC_ComputerSystem and OSExchange
BMC_OperatingSystem
CS-DDExchange BMC_HostedSystemComponents, On completion of 2
relating BMC_ComputerSystem and DiskDriveExchange
BMC_DiskDrive
136 User Guide

Overview of creating a data exchange
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
CS-MRExchange BMC_HostedSystemComponents, On completion of 3
relating BMC_ComputerSystem and MonitorExchange
BMC_Monitor
CS-SWExchange BMC_HostedSystemComponents, On completion of 4
relating BMC_ComputerSystem and SoftwareExchange
BMC_Product
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.

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 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.
Table 6-2: Values for the Direction list

Value Description Compatible data
exchange types
External Data into BMC Remedy AR System forms are AR
AR populated with data obtained from an
external data store.
AR Data into The external data store is populated with AR
External Data Store data obtained from BMC Remedy
AR System forms.
External Data into BMC Atrium CMDB classes are populated CI Class,
CMDB with data obtained from an external data Relationship
store. Class
CMDB Data into The external data store is populated with CI Class
External Data Store data obtained from BMC Atrium CMDB
classes.
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.
140 User 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 Always All records obtained from the source create a new record
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 Yes Any records obtained from the source that already exist on
existing the target are updated during the data exchange.
records 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.

Table 6-3: Values for the Data in Target fields (Continued)

Option Value Description
If a record is Delete according to Any record detected on the target that is not present on the
deleted from data mapping source is handled as specified by the If a Record Is Deleted
source 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.
12 Click Create.
142 User Guide
Assigning data mappings
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 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 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.
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 Runs the data exchange only when triggered. If you select the To
Triggered 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.
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.

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

Table 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 int Integer string
smallint smallint SmallInt boolean
tinyint numeric BigInt decimal
bigint number Character float
decimal decimal Varchar double
numeric float NChar dateTime
money real NVarchar time
smallmoney date Date date
float timestamp Time
real char TimeStamp
datetime varchar2 Decimal
smalldatetime nchar Float
char nvarchar Numeric
varchar long
nchar
nvarchar(n)
timestamp
sqlvariant
NOTE
BMC Atrium Integration Engine does not support the long data type for Oracle
Server version 8 and later.
NOTE
The character large object (CLOB) data type is not supported for the Oracle Server
external data store type.
150 User Guide

Defining connection settings for DB2 UDB

You 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
8 Click Test Connection(s) to verify the connection parameters.
The Test Connection(s) button label changes to Get Result.
9 Click Get Result.
again.
Defining connection settings for flat files

You 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 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.
server.
NOTE

c (optional) In the RPC Program Number field, type the RPC port.
NOTE

AR System administrator account.
AR System administrator account.
4 Click Test Connection(s) to verify your connection parameters.
5 Click Get Result.
again.
Defining connection settings for Oracle

You must define connection parameters if your external data store is an Oracle
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 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
resides.
server.
NOTE

NOTE
8 Click Test Connection(s) to verify your Oracle connection parameters.
9 Click Get Result.
again.

Defining connection settings for SQL Servers

You must define connection parameters if your external data store is a SQL Server
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 Guide


! Accept the default selection in the Use default destination AR server option to
resides.
server.
NOTE

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

SQL Server authentication

When 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 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 XML

You 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
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
resides.
server.
NOTE
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.
NOTE
4 Click Test Connection(s) to verify your BMC Remedy AR System connection
parameters.
5 Click Get Result.
again.
160 User Guide

Using advanced settings
RPC ports in BMC Atrium CMDB

BMC Atrium CMDB has assigned the following RPC ports for BMC Atrium
Integration Engine and Reconciliation Engine:
#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
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


! 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 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 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.
again.
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 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 parameters

Most 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 parameters

You 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 Guide

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.

again.
10 Click OK and Apply.
Managing Oracle connection parameters

You can manage the Oracle connection parameters for all your data exchanges that
connect to an external Oracle database.
! To manage Oracle connection parameters

Connections on the navigation panel.
2 On the Connections Console, click the Oracle tab.
Figure 6-16: Connections Console—Oracle tab
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 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.
options:
9 Click Get Result.
again.
Managing SQL Server connection parameters

You 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

Connections on the navigation panel.
2 On the Connections Console, click the SQL Server tab.

Figure 6-17: Connections Console—SQL Server tab
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 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.
options:
8 Click Get Result.
again.
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 support
BMC 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 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 exchanges

When 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 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 Records
Session 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 file

When 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 data

With 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 data
You 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 8.1.00 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 Guide

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 Guide

Importing data
After 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 ! BMC Remedy 1 Run the following command from the command
Engine 7.5.00 or later Data Import CLI line:
! BMC Remedy AR System 7.5.00 ! BMC Remedy BMCRemedyARSystemInstallationDir\da
or later Data Import taimporttool\dataimporttool.bat -x
! BMC Atrium CMDB 7.5.00 or later utility serverName -u loginName -p
loginPassword -o
pathOfTheAIE_Configuration.arxFile
-l destinationPath
For example:
C:\Program Files\BMC
Software\ARSystem\datamimporttool\d
ataimporttool.bat -x "pramteke-pun-
01" -u "Demo" -p "" -o
"D:\AIE_DataExchange_Windows\AIE_Da
taExchange_Windows.arx" -l
"D:\log\logfilename”
For information about using the BMC Remedy
Data Import CLI, see the BMC Remedy Action
Request System 7.7.00 Integration Guide.
2 If you use the BMC Remedy Data Import utility,
follow the steps to import data to a destination
form.
Data Import utility, see the BMC Remedy Action
Request System 7.7.00 Configuration Guide.
! BMC Atrium Integration ! BMC Remedy 1 Run the following command from the command
Engine 7.5.00 or later Import CLI line:
! BMC Remedy AR System 7.1.00 ! BMC Remedy BMCRemedyARSystemInstallationDir\ar
! BMC Atrium CMDB 2.1.00 Import utility importcmd.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_Da
taExchange_Windows.arx" -l "D:\log”
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.
Import utility, see the BMC Remedy Action Request
System 7.1.00 Configuration Guide.
182 User 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 ITSM

BMC 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 BMC_Dependency, relating On completion of Sample ITSM
Relationship BMC_Application and ComputerSystem
BMC_ComputerSystem
Sample ITSM Bus2App BMC_Dependency, relating On completion of Sample ITSM
Relationship BMC_BusinessService and Application
BMC_Application
Sample ITSM Bus2Database BMC_Dependency, relating On completion of Sample ITSM
Relationship BMC_BusinessService and Database
BMC_Database
Sample ITSM Comp2Database BMC_Dependency, relating On completion of Sample ITSM
Relationship BMC_ComputerSystem and Database
BMC_Database
Sample ITSM Comp2BiosElement BMC_HostedSystemComponents, On completion of Sample ITSM
Relationship relating BMC_ComputerSystem BiosElements
and BMC_BIOSElement
184 User Guide

Sample data exchanges for BMC Remedy ITSM
Table 6-8: ITSM data and relationship exchanges (Continued)

ITSM Sample Data Exchange CI or relationship created Order of execution
Sample ITSM Comp2Card BMC_HostedSystemComponents, On completion of Sample ITSM
Relationship relating BMC_ComputerSystem Card
and BMC_Card
Sample ITSM Comp2DiskDrive BMC_HostedSystemComponents, On completion of Sample ITSM
Relationship relating BMC_ComputerSystem DiskDrive
and BMC_DiskDrive
Sample ITSM Comp2OS BMC_HostedSystemComponents, On completion of Sample ITSM
Relationship relating BMC_ComputerSystem OperatingSystem
and BMC_OperatingSystem
Sample ITSM Comp2Processor BMC_HostedSystemComponents, On completion of Sample ITSM
Relationship relating BMC_ComputerSystem Processor
and BMC_Processor

186 User 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 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.
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.
9 In the Tag field, enter one of the following types of event-driven exchange:
! Immediate Request
! On Scheduled Interval
190 User 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.
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.
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.

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

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 Guide

Table 7-3 lists the BMC Remedy AR System parameters that you must use with the
aiexfer utility.
Table 7-3: BMC Remedy AR System parameters

-x Specifies the name of the BMC Remedy AR System server
BMCRemedyARSystem where the Application Pending form resides.
ServerName
-rpcport Specifies the port of the BMC Remedy AR System server (for
portNumber 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 lists the Data Exchange parameters that you can use when using the
aiexfer utility.
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.
Table 7-5: Optional immediate parameters

-i (required for immediate Specifies that the data exchange should run immediately.
handling)
-w Specifies the number of seconds to wait before checking for
numberOfSecondsBefore the completion status of the request. If you do not specify
CheckingForAResponse a value for the -w parameter, the default value, 5, is used.
(optional)
-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.
Examples of the event-driven request command syntax

The 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
194 User Guide

Completion codes returned by aiexfer

Data 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.
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.
The completion codes are listed in Table 7-7. A brief definition follows each
message in the table.
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.

Table 7-7: aiexfer completion code messages (Continued)

ID Number Message
-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.
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.
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.
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.
196 User 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.7.00 Workflow Objects Guide.

198 User 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 rules
This 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 Guide

Defining rules
Table A-1: Rule syntax for BMC Remedy AR System forms and BMC Atrium CMDB classes
(part 2 of 2)
Rule syntax Description
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.
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.
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.
Table A-3: Precedence syntax example

Example Results
{PO Number} The PO Number is returned if not null.
{Notification Number} If the PO Number is not found, the
{constant|Unknown Notification Number is returned if not
Value} null.
If the Notification Number is not found,
the Unknown Value string is placed in the
field.
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-4: Function syntax examples (part 1 of 6)

Function Example Results
calc_token_id function|calc_token_id Calculates the token ID.
($field1$,$field2$)
concat(string, function|concat("abc Returns the value that results from
string,string,.. ", "def") appending the string:
.) abcdef
(where string is a
constant, field name,
or function)
202 User 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) function|date Returns the date portion of the
(where timestamp is ($createdate$) time stamp data from the field as a
a constant, field name, (if $createdate$ is set to character string:
or function) Friday, August 3, 2007 August 3, 2007
12:15:00 a.m.)
day(timestamp) function|day Returns the day of the time stamp
(where timestamp is ($createdate$) (1 to 31):
a constant, field name, (if $createdate$ is set to 3
or function) Friday, August 3, 2007
12:15:00 a.m.)
hour(timestamp) function|hour Returns the hour of the time stamp
(where timestamp is ($createdate$) (0 to 23):
12:15:00 a.m.)
left(string,long function|left("Dana" Returns the left-most bytes of a
) ,2) character string up to the number
(where string and of bytes indicated:
long are constants, Da
field names, or
functions)
length(string) Example 1: Returns the length of a character
(where string is a function|length("Dan string.
constant, field name, a") Example 1:
or function) Example 2 (values in 4
database field char1 for Example 2:
five records):
9
fantastic
6
africa
3
ice 5
liver
4
rice
function|length
($char1$)
lower(string) function|lower("AIE" Converts a character string to
(where string is a ) lowercase:
constant, field name, aie
or function)


lpad(string,long function|lpad("ABC", Returns the value that results from
,string) 10,"LEAD000000") padding the character string to the
(where string and left with another string, to a
long are constants, specified length:
field names, or LEAD000ABC
functions)
ltrim(string) function|ltrim(" Strips any leading blanks from a
(where string is a abc") character string:
constant, field name, abc
or function)
max(any,any,any, function|max(15, 3, Returns the maximum value from
...) 7) a set of values (all must be the same
max($field$,$fiel data type):
d2$, ...) 15
(where any is a All data types are supported.
constant, field name, These can be field references or
or function) constants. Any non-null value
(positive or negative) is greater
than null.
min(any,any,any, function|min Returns the minimum value from a
...) ("a", "b", "c") set of values (all must be the same
(where any is a data type):
constant, field name, a
or function) All data types are supported.
These can be field references or
constants. Any non-null value
(positive or negative) is greater
than null.
minute(timestamp function|minute Returns the minute of the time
) ($createdate$) stamp (0 to 59):
(where timestamp is (if $createdate$ is set to 15
a constant, field name, Friday, August 3, 2007
or function) 12:15:00 a.m.)
month(timestamp) function|month Returns the month of the time
(where timestamp is ($createdate$) stamp (1 to 12):
12:15:00 a.m.)
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 Guide

Defining rules

replace(string, function|replace Replaces all instances of a value in
string,string,.. ("abcdefghi", "def", a character string with a new
.) "xxx") value:
(where string is a abcxxxghi
constant, field name, You can use field references or
or function) constants.
right(string,lon function|right Returns the right-most bytes of a
g) ("Allie",2) character string up to the indicated
(where string and number of bytes:
long are constants, ie
field names, or
functions)
round(real) function|round(5.1) Returns the rounded value of a real
(where real is a number (5.1 to 5.4 are rounded to
constant, field name, 5; 5.5 to 5.9 are rounded to 6):
or function) 5
rpad(string,long function|rpad("ABC", Returns the value that results from
,string) 10,"000000LEAD") padding a character string to the
(where string and right with another string, to a
long are constants, specified length:
field names, or ABC000LEAD
functions)
rtrim(string) function|rtrim("abc Removes any trailing blanks from
(where string is a ") a string:
constant, field name, abc
or function)
second(timestamp function|second Returns the second from the time
) ($createdate$) stamp (0 to 59):
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, Example 1: Returns an integer indicating the
string) function|strstr position of a string within a string.
(where string is a ("abcdefg", "def") Starting position is 0 indexed. If the
constant, field name, string is not found, -1 is returned.
Example 2 (values in
or function) database field char1 for 5 Example 1:
records): 3
fantastic Example 2:
africa 7
ice 3
liver 0
rice -1
function|strstr 1
($char1$, “ic”)
substr(string, function|substr Returns the substring of characters
long,[,long]) ("abcdefg", 2, 4) in a string starting at a specified
(where string and position up to an optional end
long are constants, position. Starting position is 0
field names, or indexed:
functions) 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) function|time Returns the time portion of the
(where timestamp is ($createdate$) time stamp (as a character string):
a constant, field name, (if $createdate$ is set to 12:15:00
12:15:00 a.m.)
trunc(real) function|trunc(5.6) Truncates a real number (5.1 to 5.9
(where real is a results in value 5):
constant, field name, 5
or function)
upper(string) function|upper("Alex Converts a string to uppercase:
(where string is a ") ALEX
constant, field name,
or function)
206 User Guide

Defining rules

weekday(timestam function|weekday Returns the weekday of the time
p) ($createdate$) stamp (1 to 7 where 1=Sunday):
year(timestamp) function|year Returns the year portion of the
(where timestamp is ($createdate$) time stamp as a four-digit year:
12:15:00 a.m.)
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.
Table A-5: SQL command syntax example

Example Results
sql|select categoryid Returns category IDs from the categories
from categories where table where the name equals the value
name = $category$ obtained for the $category$ field.
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.

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.
Table A-6: Target SQL command syntax example

Example Results
targetsql|select locationid Runs the location ID from the
from location where location table where the
department = $location$ department equals the value of the
$location$ field obtained from
the source database.
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.
Table A-7: Process command syntax example

Example Results
process| Runs the command getlastupdate on
getlastupdate the source database, passing the values for
($keyName$,$field2$) $keyName$ and $field2$ as parameters.
The response from the command is used.
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.
208 User 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.
Table A-8: Target process command syntax example

Example Results
targetprocess| Runs the command
getlastupdate getlastupdate on the target
($keyName$,$field2$) database, passing the values from
the source database for $keyName$
and $field2$ as parameters. The
response from the command is
used.
targetprocess| appspwd -p Runs the appspwd.exe and
$Site$ generates an encrypted password.
Note: Make sure that the .exe file is
stored in the
BMCRemedyARSystemInstalla
tionDir directory on a Windows
operating system and
BMCRemedyARSystemInstalla
tionDir/bin on a UNIX
operating system, or else you must
provide the explicit path and the
parameter used.
targetprocess|java Runs the HelloWorld Java script
org.mozilla.javascript.tool using the -f parameter.
s.shell.Main -f
"C:\Temp\HelloWorld.js"
targetprocess|C:\Perl\bin\p Runs the perl.exe file passing the
erl.exe "C:\al.pl" $Site$ $Site$ value from the source
'MS Office' 'Microsoft database as a parameter.
Office'
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.

! 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 Returns Windows XP (67).
Professional" THEN
VALUE = "Windows XP (67)"
ENDIF
(if $CDiOsType$ is set to Windows XP
Professional)
STMT|IF $CDiOsType$ LIKE "Windows XP" The string Windows XP does not
THEN appear in Windows 2003 Professional.
VALUE = "Windows XP (67)" Returns Unknown.
ELSE
VALUE = "Unknown"
ENDIF
(if $CDiOsType$ is set to Windows 2003
Professional)
STMT|IF $ChassisType$ = "12" THEN The top-level IF statement matches,
IF $ChassisSize$ = "Large" THEN but the nested one does not. Because
VALUE="12CRPF" no ELSE clause exists for the nested IF
ENDIF statement, no value is returned.
ElSE
VALUE="13CRPF"
ENDIF
(if $ChassisType$ is set to 12 and
$ChassisSize$ is set to Small)
STMT|IF $model$ = "Laptop" THEN $model$ is a source field. Multiple
VALUE = "Switch" values can be used for the $model$
ENDIF field. The If/then/else rule is used to
IF $model$ = "Desktop" THEN replace the $model$ field with
VALUE = "Router" different value.
ENDIF
ELSE
VALUE = "Hub"
ENDIF
210 User Guide

Defining queries
Defining queries
Use 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 syntax

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

Table A-10: Query syntax options (part 2 of 2)

Option Description
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.
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
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.
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$ != Returns all entries in the database
$function|null()$ where the $category$ field is not a
null value.
Data key syntax

You can only use the syntax described in this section in a data key query. Data key
queries are defined on the Data Key Query subtab of the Query tab on the
respective Mapping Information windows for 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.
212 User Guide

Defining queries
Query on an external data store

For 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 CMDB

Following 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
$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.
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.
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.
Table A-14: KEY syntax example

Example Result
$KEY$ = $KEYLIST$ $keyfield1$ = key1 AND
$keyfield2$ = key2
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.
214 User 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.
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.
Row-level query syntax

You 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-16: SRC syntax examples

Example Result
$LastModified$ < $LastModified$ < 05/23/07
$SRC|LastMod$ (if LastMod is a field in the source database
with a value of 05/23/07)

216 User 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 Windows

When 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
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
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.
218 User Guide

Running the AIE service on UNIX
Running the AIE service on UNIX

You 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 DB2

If 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 Guide

Understanding the configuration file and its parameters
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 file

If 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: Yes
LogPath: 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) files
MaxDebugSize: 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: Yes
DebugPath: 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: IMAGINARYFRIEND
ARLogin: Demo
ARPassword:
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 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.dll
CustomAdapter:INFORMIX:informadpr.dll;
Configuration file parameters

Table 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 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 100
If 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.


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.
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.
226 User 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.ex
e -l loginName-p password -y completePathOfInstallationDirectory
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.
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 files

BMC Atrium Core debug files are located in the aieInstallationDir/service/
debug directory. Table B-4 describes the debug files.
Table B-4: Debug files (part 1 of 2)

Debug file Description
AIEServiceInstance_aiemai In this file the AIE service records all the details,
n.dbg 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_aieEve In this file the logging information for the
ntCleanup.dbg Application Pending form cleanup activity occurring
at specific intervals is recorded.

Table B-4: Debug files (part 2 of 2)

Debug file Description
AIEServiceInstance_aieEve An AIE service instance listens to a particular port for
ntListener.dbg 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_aieEve In this file, the logging information of event-driven
ntMgr.dbg 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.
Managing instances
In 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.
228 User Guide

Managing instances
Adding an instance
This 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 Guide

Managing instances
Deleting an instance
You 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
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.
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.

TIP
Timeouts.
Starting an instance
You 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
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 Guide

Managing instances
running flag set to Yes and updates the status. If BMC Atrium Integration Engine
instance.
TIP
Timeouts.
Stopping an instance
You 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
4 Click OK.
5 (optional) Click Refresh to veiw the status change of the instance in the table.

running flag set to Yes and updates the status. If BMC Atrium Integration Engine
instance.
TIP
Timeouts.
Using command line to manage instances

You 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 -d
where
! -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
BMCAtriumIntegrationEngineInstallationDirectory
where
-del: AIE service host name that you want to delete
234 User Guide

Managing instances
Table B-5: Commands to manage instances (part 2 of 2)

Action Command
Starting an instance aiexfer -START -st AIEServiceHostName,internalInstanceName; -l
AIEServiceHostName -rpcport portNumber -d –path
where
-st: AIE service host name that you want to start
Stopping an instance aiexfer -STOP -stp AIEServiceHostName,internalInstanceName; -l
AIEServiceHostName -rpcport portNumber -inst
activeInternalInstanceName –d –path
where:
-stp: AIE service host name that you want to stop
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 details

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

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 Guide

Managing instances
Viewing the status of an instance

You 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 password

This 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 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 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).
NOTE
You have to create a .tbl file to define the columns and the delimiter used in the
.csv file. If you make changes to the .csv file (such as add a new column or
change the name of an existing column) after you have created the corresponding
.tbl file, the changes are not automatically reflected in the .tbl file. When you
open the data mapping for the .csv file, the .tbl file is regenerated and the new or
updated fields are displayed in the list of attributes. You can map the new or
updated fields to attributes in BMC Atrium CMDB. If the fields contain line breaks
(CRLF) and commas, you must enclose the fields in double-quotes.

! 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 CRLF
zzz,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, Column5
1, testDescription, dataforColumn3, dataforColumnC4,
dataforColumnC5
2, 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 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 interpretation of sample .csv data
Input data BMC Atrium Integration Engine interpretation

"Double quoted (Parentheses, 'Double quoted (Parentheses, Parentheses )'
Parentheses )", "95,1",5000 '95,1' '5000'
"Double-double quoted word then 'Double-double quoted word then comma
comma ""word"", eol" ""word"", eol'
"Comma after escaped double 'Comma after escaped double quote\"", eol'
quote\"", eol"
"Comma after double quote and 'Comma after double quote and character ""x, eol'
character ""x, eol"
"Comma after double quote and a 'Comma after double quote and a word ""word,
word ""word, eol" eol'
"Comma after double quote and 2 'Comma after double quote and 2 words "" word1,
words "" word1, word2, eol" word2, eol'
"Comma after a double quoted word 'Comma after a double quoted word and more
and more words ""word"" word1 words ""word"" word1 word2, eol'
word2, eol"
"Comma after a double quoted word 'Comma after a double quoted word and more
and more words ""word"" word1 words ""word"" word1 word2, eol'
word2, eol"
"Escaped comma after a double 'Escaped comma after a double quoted word
quoted word ""word""\, eol" ""word""\, eol'
"Comma after fwd-slash escaped 'Comma after fwd-slash escaped double quote/"",
double quote/"", eol" eol'
"Comma after double fwd-slash 'Comma after double fwd-slash escaped double
escaped double quote//"" quote//"", eol'
"Comma after double escaped double 'Comma after double escaped double quote\\"",
quote\\"" eol'
"Double quote & fwd-slash escaped 'Double quote & fwd-slash escaped comma "" /,
comma "" /, eol" eol'
"Double quote & double fwd-slash 'Double quote & double fwd-slash escaped
escaped comma "" //, eol" comma "" //, eol'
"Double quote & double escaped 'Double quote & double escaped comma "" \\, eol'
comma "" \\, eol"
"1 field has double quotes "" and '1 field has double quotes "" and comma, eol'
comma, eol"
"1 field has double quotes and '1 field has double quotes and comma then double
comma then double quote "","" eol" quote "","" eol'

Input data BMC Atrium Integration Engine interpretation

"1 field has double quotes and double '1 field has double quotes and double quote then
quote then comma "", eol" comma "", eol'
bob said,"oh boy!" 'bob said' 'oh boy!'
"bob said, ""oh boy!""" 'bob said, ""oh boy!""'
244 User Guide

Glossary
abstract class AIE Definitions Admin

A class that has attributes but of which no A BMC Atrium Integration Engine
instances can be created. An abstract class application role. Members can view, create,
exists for the purpose of creating an and modify data mappings and data
organizational layer without a database join. exchanges, and manage the configuration and
See also data replication. connection settings. See also AIE User.
account AIE service
An entity or party whose data is represented The AIE service obtains the defined data
in BMC Atrium Core, and to whom specific exchange from the Data Exchange application
levels of permission can be granted. and completes the transfer of data by
Specifying instance permission by account communicating with the adapter specified in
enables BMC Atrium Core to support the data exchange definition. The AIE service
multitenancy. can connect to a BMC Remedy AR System
activity server. It runs as a client to the BMC Remedy
An individual reconciliation task that can be AR System server using the BMC Remedy
grouped together in a defined sequence to AR System application programming
form a reconciliation job. You can run an interface (API).
activity only as part of a job, never by itself. AIE User
See also Comparison activity, Copy Dataset A BMC Atrium Integration Engine
activity, Delete Dataset activity, Execute Job application role. Members can view data
activity, Identification activity, Merge mappings, data exchanges, and configuration
activity, Purge Dataset activity, Rename and connection settings. See also AIE
Dataset activity. Definitions Admin.
Adapter Development Kit Atrium Explorer
The Adapter Development Kit is a software A component of BMC Atrium CMDB that
development kit that lets you build your own graphically displays the relationships
adapters to interact with BMC Atrium between CIs. It can also be embedded in other
Integration Engine. The Adapter BMC Remedy AR System-based applications.
Development Kit interface defines a set of attribute
C++ objects that are used by the AIE service to A property or characteristic of a class, such as
manage data exchanges that use these the IP address of a computer system. An
adapters. attribute equates to a column on a database
table or a field on a BMC Remedy AR System
form.
Glossary 245
attribute permission cardinality

Permission to view or change the value in the The number of members a relationship class
attribute for any instance, assuming valid can have on each side. Cardinality can be one
instance permissions. to one, one to many, many to one, or many to
attribute substitution many.
A method of data federation in context that cascading delete
uses placeholders to represent attributes from To automatically delete, or mark as deleted
a linked class. Launching the link triggers the the destination member of a relationship
respective attribute values to be substituted when the source member is deleted or
for the placeholders. marked.
audit Categories, Types, and Items (CTI)
A logging of attribute values and other A method formerly used for categorizing
information for purposes of tracking the assets in BMC Asset Management. Category,
history of changes to instance data. An audit Type, and Item are each an attribute on the
is triggered when the value of one or more BMC_BaseElement class, so you can use CTIs
specified attributes changes or when the in BMC Atrium CMDB.
instance is created or deleted. categorization class
base class A class that does not have its own BMC
A class that has no superclass. Remedy AR System form, but stores its
BMC Atrium Core Console instance data in the form of its superclass,
The main user interface of BMC Atrium preventing the need for a database join.
CMDB, accessible from both web and BMC CDM
Remedy User clients. The BMC Atrium Core See Common Data Model (CDM).
Console replaced the CMDB Console. child
BMC Atrium Integration Engine See destination.
A product that enables you to transfer large CI
amounts of data between third-party data See configuration item (CI).
sources and both the BMC Remedy
AR System and BMC Atrium CMDB. CI class
A class that defines a type of configuration
BMC Atrium Product Catalog item (CI), such as a computer system or
A BMC Remedy AR System application that is software application.
part of the BMC Atrium Core solution and
provides data for normalization and CIM
discovery, including storage of product See Common Information Model (CIM).
signatures, and tracks and manages products class
by categorization, life cycle, development Metadata in BMC Atrium CMDB that defines
status, approval status, and other attributes. a type of object, usually a configuration item
bulk functions
(CI) or relationship. Either of these types of
A set of functions you can use to create, class can store data as a regular class,
update, and delete multiple instances in a categorization class, abstract class, or
single call. These functions can manipulate abstract class with data replication. You can
instances of different classes in a single apply the final class and singleton class
operation. options to it as well.
Business Service Management (BSM)

The concept of prioritizing IT efforts to
support the overall goals of the business.
246 User Guide

Glossary
Class Manager CMDB RE Definitions Admin

A component of BMC Atrium CMDB where An application role. Members can view,
you can view, create, modify, and delete the create, modify, and delete reconciliation
classes and attributes that make up the data definitions and can start and cancel jobs.
model, as well as view a list of subclasses for CMDB RE Manual Identification
each class. An application role. Members can identify
class permissions instances manually.
Permission to view instances of a class in the CMDB RE User
BMC Atrium CMDB interface or access them An application role. Members can view
with BMC Remedy AR System workflow. reconciliation definitions and can start and
CMDB cancel jobs.
See Configuration Management Database cmdbdriver
(CMDB). A utility that executes BMC Atrium CMDB
CMDB Console C API functions from a command line,
See BMC Atrium Core Console. prompting for parameters.
CMDB Console Admin Common Data Model (CDM)
An application role. Members can perform The object-oriented, hierarchical set of classes
searches from the BMC Atrium Core Console, in BMC Atrium CMDB used to represent
view, create, and modify federation types of CIs and relationships. The CDM is
definitions, and perform BMC Atrium Core based on industry standards such as the
Console administrative tasks. Common Information Model (CIM) and
CMDB Console User Microsoft Windows Management
An application role. Members can perform Instrumentation.
searches from the BMC Atrium Core Console Common Information Model (CIM)
and view federation definitions. A definition of management information
CMDB Data Change developed by the Distributed Management
An application role. Members can view, Task Force (DMTF) that facilitates the
create, and modify instances if they have row- exchange of management information
level security. between systems.
CMDB Data Change All Comparison activity
An application role. Members can view, A Reconciliation Engine activity that
create, and modify instances independent of compares identified instances between two
row-level security. datasets, either producing a report that shows
the differences or executing workflow.
CMDB Data View
An application role. Members can view configuration data
instances if they have row-level security. Data about your IT environment, consisting of
CIs and relationships.
CMDB Definitions Admin
An application role. Members can view, configuration item (CI)
create, modify, and delete classes. A physical, logical, or conceptual entity that is
part of your IT environment and has
CMDB Definitions Viewer configurable attributes. Examples include
An application role. Members can view class computer systems, buildings, employees,
definitions. software, and business services. One of the
CMDB Extended Data two types of classes in BMC Atrium CMDB.
Related data or CI attributes linked to or from See also relationship.
BMC Atrium CMDB.
Glossary 247
Configuration Management Database (CMDB) Dataset Merge Precedence

A database that stores information about your A pairing of a dataset with a Precedence
IT configuration, including both CIs and group. Each Merge activity references a
relationships. collection of these, called a Dataset Merge
consumer Precedence set.
An application that works with data in BMC defined dataset
Atrium CMDB. It might view the data or One of a pair of dataset IDs that is specified
modify it. See also provider. when executing a job with dynamic dataset
Copy Dataset activity substitution. The job is executed with the
A Reconciliation Engine activity that copies working dataset in place of the defined
instances from one dataset to another. dataset.
CTI Definitive Hardware Library (DHL)
See Categories, Types, and Items (CTI). The Definitive Hardware Library (DHL) is a
subset, or filter, of the Product Catalog that
data exchange represents hardware products that are
A BMC Atrium Integration Engine integration marked as approved for use in an
object that you execute to transfer data. A data organization.
exchange specifies the source and destination
in a data transfer, the adapter to be used for Definitive Media Library (DML)
the transfer, and the connection parameters to A repository where approved software
connect to the external data store. A data configurations are stored. Installed instances
mapping is associated with a data exchange to of the software can be checked against the
transfer data. DML for compliance with licenses and
policies. From the 7.5.00 release of BMC
data mapping Atrium Core, Definitive Software Library
A BMC Atrium Integration Engine integration (DSL) has been renamed to Definitive Media
object that defines the data to be transferred. A Library.
data mapping defines the source and
destination of a data transfer, the primary key, Definitive Software Library (DSL)
and other fields and attributes. You can use a See Definitive Media Library (DML).
data mapping by associating it with a data Delete Dataset activity
exchange. A Reconciliation Engine activity that deletes
data replication instances from one or more datasets without
An option for abstract classes. With this removing the dataset itself. See also cascading
option, the instances of all subclasses are delete, hard delete, soft delete.
replicated to a single form to allow you to destination
search the abstract class as though it had data. The CI class defined as Class 2 in a
Only the attributes inherited from the abstract relationship class, or an instance of that CI
class are replicated. class as a member of such a relationship. Also
dataset known as the child member or weak member.
A logical group of data in BMC Atrium discovery
CMDB. A dataset can represent data from a The act of scanning your environment for
particular source, a snapshot from a particular configuration data.
date, or other purpose. The dataset used by discovery application
BMC Software products for reconciled An application that scans your environment
production data is named BMC Asset. See also for configuration data and can act as a
overlay dataset. provider to BMC Atrium CMDB.
248 User Guide

Glossary
Distributed Management Task Force (DMTF) federated interface

An organization appointed to facilitate the An instance of the BMC_FederatedInterface
exchange of management information by class that specifies how to access a particular
promoting the initiation of industry standards type of federated data. See also federated link.
and interoperability. federated link
DHL The connection between a class or CI and a
See Definitive Hardware Library (DHL). federated interface.
DML federated product
See Definitive Media Library (DML). A product that holds federated data. It can be
DMTF linked to more than one federated interface.
See Distributed Management Task Force federation
(DMTF). The act of linking CIs in BMC Atrium CMDB
DSL to external data.
See Definitive Media Library (DML). Federation Manager
Enterprise Integration Engine A component of BMC Atrium CMDB that you
See BMC Atrium Integration Engine. can use to manage federated data. From the
Federation Manager, you can view, create,
event and modify federated products, federated
A particular type of change to the instances of interfaces, and federated links.
specified classes. You can publish an event so
that any instance of it is written to the filter
CMDB:Events form. You can receive A set of criteria for restricting the information
notification each time an instance of the event displayed by the Atrium Explorer. This is
occurs by polling the form. different from a BMC Remedy AR System
filter.
Exclusion rule
A rule that specifies an attribute to be final class
excluded from participation in a Comparison A class that cannot have subclasses.
activity. foreign key substitution
Execute Job activity A method of federation that assigns a key
A Reconciliation Engine activity that executes from the federated product to each linked CI.
a job. Foreign key substitution is useful when no
attributes that also exist in BMC Atrium
extension CMDB are stored in the federated product.
A logical set of classes and attributes, usually
in its own namespace, that is not part of the graph walk
Common Data Model (CDM). The act of searching for CIs and relationships
in BMC Atrium CMDB.
extension loader
The cmdbExtLoader program, which is used graph walk functions
for installing data model extensions and A set of specific functions that are used to
importing other BMC Atrium CMDB data and search for CIs and relationships in BMC
metadata. Atrium CMDB. Use these functions when you
want to search for CIs regardless of their class
federated data or relationship.
Data 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.
Glossary 249
group instance
A set of a particular type of reconciliation An actual incarnation of a particular class,
definition that is referenced by an activity. represented as a record in BMC Atrium
See also Identification group, Precedence CMDB. Both CIs and relationships are
group, Qualification group, Workflow instances of their respective classes.
Execution group. instance ID
GUID A GUID that BMC Atrium CMDB applies to
A globally unique identifier, automatically each instance to uniquely identify it.
generated by the BMC Remedy AR System instance permissions
server. GUIDs are used for instance IDs, The right to view or modify a specific
reconciliation IDs, and other cases where a instance. These permissions are called row-
unique value must be generated without level security and write security, respectively.
human interaction.
instantiate
hard delete To create an instance of a class.
The act of removing an instance from BMC
Atrium CMDB. See also soft delete. ITIL®
Identification activity The IT Infrastructure Library® (ITIL) is an
A Reconciliation Engine activity that matches internationally accepted set of best practices
instances from two or more datasets and developed by the British government for
assigns them the same identity, meaning that management of IT services.
they represent the same real-life object. job
Identification group A group of one or more reconciliation
A set of Identification rules that collectively activities executed in sequence. You cannot
identify instances from a particular dataset run an activity by itself; only as part of a job.
against other datasets. Each dataset that You can start a job manually, with a schedule,
participates in an Identification activity is with an Execute Job activity, with workflow,
paired with one Identification group. or with an API program.
Identification rule key query
A rule used when identifying instances Limits the records transferred in a data
between datasets. When two instances match transfer in the BMC Atrium Integration
the qualification for the rule, they are assigned Engine. See also row-level query.
the same reconciliation ID. Merge activity
identity A Reconciliation Engine activity that merges
See reconciliation ID. two or more datasets into a single complete
and correct dataset based on precedence
incident values that favor the strengths of each dataset.
Defined by ITIL® as any event that is not part
of the standard operation of a service and that metadata
causes, or might cause, an interruption to, or a Definitions that describe the data stored in
reduction in, the quality of that service. BMC Atrium CMDB. Metadata includes
classes in the data model and special classes
incremental merge to define things such as datasets and
A Merge activity that only processes instances federation objects.
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.
250 User Guide

Glossary
multitenancy primary key

The separation of data and access so that a A primary key uniquely identifies a row of
single BMC Atrium CMDB can contain the data. In BMC Atrium Integration Engine you
data of multiple parties, but each party can must specify the attributes of a CI class and
access only their own data. See also account, the corresponding fields in the external data
role. store to create the primary key. After a data
namespace transfer, the primary key is the link that
A logical set of classes and attributes in the matches a record in the external data store
data model, usually related to a specific with its counterpart in BMC Atrium CMDB.
consumer or provider. The Common Data product categorization
Model (CDM) uses the BMC.CORE namespace. Divides CIs into groups. Using the three-tier
normalize structure of product categorization, you can
To ensure that data of the same type follows create successively smaller, more tightly
the same text formatting conventions. This defined groups. You can create groups of CIs
helps reconciliation by making it more likely in Tier 1 followed by smaller groups in Tier 2
for instances to match in an Identification and Tier 3.
activity. production dataset
Normalization Engine The dataset that serves as the single source of
A BMC Atrium CMDB application that reference for your organization and from
provides a centralized, customizable, and which you make business decisions. It acts as
uniform way to overcome consistency the target dataset in most Merge activities.
problems by normalizing attributes for provider
software and hardware products. An application, often a discovery application,
orphan that loads bulk data into BMC Atrium CMDB.
An instance that has been physically deleted See also consumer.
from source datasets but still exists in the provisioning
target dataset into which they merge. The process of providing access to resources,
overlay dataset such as printers, telephones, and so on, and to
A dataset that provides a layer in which to information, such as permissions, databases,
make changes that are pending approval. API and so on.
queries to the dataset seamlessly return its publish
modified instances along with unmodified To make an event available so that instances of
instances from the underlying regular dataset. it can be written to the CMDB:Events form.
parent Purge Dataset activity
See source. A Reconciliation Engine activity that removes
Precedence group instances that have been marked as deleted
The definition of an overall precedence value from one or more datasets.
for a dataset. It can optionally contain Qualification
precedence values for specific classes and A Boolean statement that is evaluated to
attributes within the dataset. determine whether an instance should be
precedence value included in an activity.
A method of assigning weight to specific Qualification group
datasets, classes, and attributes in a Merge A set of Qualifications that can be used in
activity. Attribute precedence values various types of activity. An instance that
override class precedence values, which meets one or more Qualifications in the group
override dataset precedence values. is included in the activity.
Glossary 251
reconciliation relationship key

The process of managing data in multiple A relationship key uniquely identifies a row
datasets using the Reconciliation Engine. The of data in a relationship mapping. In BMC
main activities of reconciliation are Atrium Integration Engine you must specify
identifying, comparing, and merging the attributes of a primary CI class and a
datasets, though the Reconciliation Engine secondary CI class to create the relationship
performs other activities as well. key. After a data transfer, the relationship key
reconciliation definition is the link that matches a record in the external
An entity defined in the Reconciliation data store with its counterpart in BMC Atrium
Manager such as a job, activity, or group. CMDB.
Reconciliation Engine Rename Dataset activity
The component of BMC Atrium CMDB that A reconciliation activity that renames a
reconciles data from different datasets. dataset without changing its ID, preserving
references to the dataset from any
reconciliation ID reconciliation definitions.
A GUID that the Reconciliation Engine
assigns to instances in different datasets that role
represent the same real-life object. A designation that grants permissions to more
than one BMC Remedy AR System group.
Reconciliation Manager
The component of BMC Atrium CMDB that row-level query
you can use to manage reconciliation Limits the transfer of data on a row-by-row
definitions. basis in the BMC Atrium Integration Engine.
See also key query.
regular class
A class that stores its instance data in its own row-level security
BMC Remedy AR System form. See also The permission required to view a specific
abstract class, categorization class. instance. See also write security.
related information rule
Information about a CI that does not qualify One or more criteria that, when met, cause an
as attributes of the CI, and should therefore action. The types of rules used in BMC Atrium
not be stored in a Configuration Management Core are Exclusion rule, Identification rule,
Database (CMDB). and Workflow Execution rule.
relationship ruleset
A connection between two CIs such as a A group of rules.
dependency or membership. It is an instance service level agreement
of a relationship class. See also configuration A contract between a service provider and a
item (CI). purchaser that defines the level of service.
relationship class singleton class
A class that defines a type of relationship An optional class characteristic that restricts
between CIs, such as a dependency or the class to holding only one instance.
membership. snapshot
relationship filter A set of data that represents a configuration at
See filter. a certain point in time, usually stored in its
own dataset. There can be multiple snapshots
of a given configuration.
252 User Guide

Glossary
soft delete WMI

The act of marking an instance as deleted See Windows Management Instrumentation
from BMC Atrium CMDB by setting the (WMI).
MarkAsDeleted attribute to Yes. See also hard workflow
delete. BMC Remedy AR System objects such as
source active links, escalations, and filters that
The CI class defined as Class 1 in a perform actions against data.
relationship class, or an instance of that CI Workflow Execution group
class as a member of such a relationship. Also A set of Workflow Execution rules. Each
known as the parent member or strong Comparison activity can optionally reference
member. one Workflow Execution group.
subclass Workflow Execution rule
A class that is derived from another class, A rule used when comparing instances
which is called its superclass. The subclass between datasets. When a compared instance
inherits all the attributes of its superclass and matches the qualification for the rule,
any superclasses above it in the hierarchy, and specified BMC Remedy AR System workflow
can also participate in relationships defined is executed against the instance or the instance
for all superclasses. against which it is compared.
superclass working dataset
A class from which other classes, called One of a pair of dataset IDs that is specified
subclasses, are derived. when executing a job with dynamic dataset
synchronization substitution. The job is executed with the
The automatic process of creating BMC working dataset in place of the defined
Remedy AR System forms and workflow to dataset.
represent a class that has just been created or write security
modified. The class is not available until The permission required along with row-level
synchronization completes. security to modify or delete a specific
text normalization instance. See also row-level security.
See normalize.
weak reference
See weak relationship.
weak relationship
An 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.
Glossary 253
254 User 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 ChunkSize 225

CMIBlock 225
# parameter 223 ConfigInterval 224
$field$ option for BMC Remedy AR System query ConfigPassCount 224
syntax 211 CustomAdapter 225
.csv file DB2InstName 225
error handling 177 DebugOn 225
format supported 241 FileDataPath 225
logging errors 177 logging 225
MaxDebugSize 225
MaxLogSize 226
A OraDbDirPath 226
activating data exchanges 164 PrivateRPCPort 226
Adapter Development Kit 20 Srvgroup 226
adapter rule helper utility 40 StackTrace 226
DB2 40 TimeStampDebug 226
file 52 AIE:Exchange_Runs form 174, 175, 237
Oracle 44 aiecfedit 226
SQL 47 aiexfer utility
XML 52 command syntax examples 194
advanced settings completion code messages 195
character set 161 completion codes returned by 195
debugging 161 definition of 20
performance 161 ARLogin parameter 223
using 161 ARPassword parameter 223
AIE service 20, 225 ARServerName parameter 224
command-line parameter 218 assigning data mappings to a data exchange 143
debug file (aiemain.dbg) 225 AsyncInterval parameter 224
rule syntax 200
running on UNIX, from a command line 219
aie.cfg file
B
editing 226 blank values, validity of 79, 105, 129
location 221 blanks, trailing 79, 106, 129
parameters 223 BMC Atrium Integration Engine, introduction to 16
sample file 221 BMC Remedy Action Request System (BMC Remedy
aie.cfg file parameters AR System)
# (pound sign) 223 API documentation 20
ARLogin 223 query syntax 211, 212
ARPassword 223 BMC Remedy AR System Home Page 33
ARServerName 224 BMC Remedy AR System query syntax
AsyncInterval 224 function syntax 212
Index 255
syntax statement 211 definitions 18

value option 211 example 136
BMC Remedy AR System query syntax, $field$ running in event-driven mode 140
option 211 running in schedule-driven mode 140
BMC Remedy IT Service Management 184 running on UNIX 219
BMC Remedy User, accessing BMC Atrium running simultaneously 136
Integration Engine with 32 strategy with BMC Atrium CMDB 136
BMC Software, contacting 2 triggering one from another 148
browsers, accessing BMC Atrium Integration Engine verifying conditions 165
with 34 Data Key 174, 237
data key queries 73, 124–125, 212
data key query syntax
C field option 213
checksum 80, 106, 130 KEY syntax 214
ChunkSize parameter 225 KEYLIST syntax 214
CMIBlock parameter 225 value option 214
command-line parameter 218 Data Mapping & Schedule tab 37
ConfigInterval parameter 224 data mappings
ConfigPassCount parameter 224 assigning to a data exchange 143
configuration file defining delete field mappings 70, 121
editing 226 data mappings, defining queries 211, 215
location 221 data transfer, direction of 16
parameters 223 DB2 connection parameters, managing 168
sample file 221 DB2, adapter rule helper utility 40
connection parameters DB2, defining connection settings 151
DB2 168 DB2InstName parameter 225
managing 168 debug file
Oracle 170 .dbg 228
SQL Server 171 aieEventCleanup.dbg 227
connection settings, defining 149 aieEventListener.dbg 228
constant syntax 200, 201 aieEventMgr.dbg 228
CSV flat files, defining connection settings 152 aiemain.dbg 227
CustomAdapter parameter 225 debug file (aiemain.dbg)
customer support 3 disabling 225
enabling 225
debug file (aiemain.dbg), timestamp 226
D debugging
AIE service debug file, timestamp 226
Data Exchange application 18
data exchange debug files, timestamp 226
data exchange debug files, timestamp 226
maximum debug file size 225
data exchange status
DebugOn parameter 225
Aborted 237
defining
Completed 174, 237
delete field mappings for AR forms 121
Not Responding 237
delete field mappings for CI classes 70
Running 174, 237
queries 215
data exchanges
rules 200
activating 164
defining connection settings 149
assigning data mappings to 143
CSV flat files 152
creating 138
DB2 151
defining multiple data mappings 143
Oracle 154
defining parameters 138
SQL Server 156
defining schedules 140
XML 159
definition of 135
256 User Guide

defining data exchange parameters 138 using BMC Remedy Data Import command
defining multiple data mappings 143 line 182
defining schedules 140 using BMC Remedy Import 182
delete field mapping, defining 70, 121 using BMC Remedy Import command line 182
delete queries 77, 124, 127 importing data 181
demand data exchanges, running 166 initialization phase of data transfers 21
diary history field 80, 129 instance
direction of data transfer 16 adding 229
disabling logging 225 deleting 231
display pane 35 starting 232
status 237
stopping 233
E invoking requests using aiexfer, Event Request
enabling logging 225 interface 191
error handling ITSM 184
See .csv file
Event Request interface
activating requests through workflow 197
K
invoking requests through aiexfer 191 KEY syntax for data key queries 214
Event Request interface, definition of 20 KEYLIST syntax for data key queries 214
event-driven mode, running 140
execution of data exchanges, managing 145
exporting data 178 L
to a file 180 location, configuration file 221
to a server 178 log files
disabling 225
F enabling 225
maximum size 226
failover support 174 logging parameter 225
field option for data key query syntax 213
file, adapter rule helper utility 52
FileDataPath parameter 225 M
function syntax managing connection parameters 168
BMC Remedy AR System queries 212 DB2 168
rules 200 Oracle 170
managing connection parameters, SQL Server 171
H managing execution of data exchanges 145
managing instances
helper utility using command line 234
about 40 using Instances Console 228
DB2 40 MaxDebugSize parameter 225
file 52 maximum file size
Oracle 44 debug 225
SQL 47 log 226
XML 52 MaxLogSize parameter 226
History tab 36 monitoring console
history, recording 80, 129 viewing data exchanges 35
monitoring console, accessing 34
multiple data mappings, defining 143
I
import data
Index 257
N defining 200
function syntax 200
nested rules 200 precedence syntax 200, 202, 209
process command syntax 200, 208
SQL command syntax 200, 207
O stmt command syntax 209
Oracle connection parameters, managing 170 target process command syntax 200, 208
Oracle, adapter rule helper utility 44 target SQL command syntax 200, 207
Oracle, defining connection settings 154 vendor rules 201
OraDbDirPath parameter 226 running data exchanges on demand 166
running the AIE service on UNIX, from a command
line 219
P
parameters
command line 218
S
debug file 225 sample file, aie.cfg 221
debug timestamp 226 schedule-driven mode, running 140
populating, SQL field information 49 security 226
precedence syntax 200, 202, 209 server group 32
PrivateRPCPort parameter 226 source syntax
process command syntax 200, 208 SQL command syntax 200, 207
processing phase of data transfers 22 SQL field information, populating 49
product support 3 SQL Server, defining connection settings 156
SQL Server, managing connection parameters 171
SQL, adapter rule helper utility 47
Q SRC syntax for row-level queries
Srvgroup parameter 226
queries, defining 211
StackTrace parameter 226
query syntax
stmt command syntax 209
See also BMC Remedy AR System query syntax
support, customer 3
and data key query syntax
syntax ($KEYLIST$) 214
row-level syntax, SRC syntax 215
syntax statement for BMC Remedy AR System
queries 211
R
response queries 76, 124, 126 T
Retrieve Delta 183
target process command syntax 200, 208
Retrieve Delta option 106
target SQL command syntax 200, 207
Retrieve Source Records 183
technical support 3
Retrieve Source Records option 106
timestamp parameters for debug files 226
Role
TimeStampDebug parameter 226
AIE Definitions Admin 27
trailing blanks 79, 106, 129
AIE User 27
triggering one data exchange from another 148
row-level queries 72, 77, 123
rule helper utility 40
DB2 40
file 52
U
Oracle 44 UNIX, running the AIE service, from a command
SQL 47 line 219
XML 52 update queries 74, 123, 125–126
rules updating records only if values change 80, 106, 130
constant syntax 200, 201 Use Fixed Port option 236
258 User Guide

using advanced settings 161
V
value option
BMC Remedy AR System query syntax 211
data key query syntax 214
vendor rules 201
verifying data exchange conditions 165
W
working with data exchanges
activating 164
running on demand 166
verifying conditions 165
X
XML, adapter rule helper utility 52
XML, defining connection settings 159
Index 259
260 User Guide

*440001*

AIE User Guide

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

AIE User Guide

Hochgeladen von

Copyright:

Verfügbare Formate

BMC Atrium Integration Engine 8.1.

© Copyright 2009-2013 BMC Software, Inc.

Restricted rights legend

Support by telephone or email

Before contacting BMC Software

BMC Atrium Core documentation 11

Chapter 1 Understanding BMC Atrium Integration Engine 15

Chapter 2 Populating database field menus 39

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

Chapter 6 Data exchanges 135

Appendix A Defining rules and queries 199

Appendix B Running and configuring the AIE service 217

Appendix C CSV Syntax supported by BMC Atrium Integration Engine 241

1 Understanding BMC Atrium

Chapter 1 Understanding BMC Atrium Integration Engine 15

Overview of BMC Atrium Integration Engine

Figure 1-1: Overview of the data transfer process

BMC Remedy AR System

Calbro Services user story in BMC Atrium

Roles used in the Calbro Services user story

BMC Atrium Integration Engine components

Chapter 1 Understanding BMC Atrium Integration Engine 17

Figure 1-2: BMC Atrium Integration Engine components

BMC Remedy AR System

AIE Event Request

DB2 Oracle SQL XML Flat File

Data Exchange application

! A data mapping defines data to be transferred. It specifies the external file or

Chapter 1 Understanding BMC Atrium Integration Engine 19

Event Request interface

Adapter Development Kit

Data transfer process

Step 1 Loads data exchange rules.

Step 2 Connects to data stores to validate rules.

Step 3 Validates data exchange rules.

Step 4 Disconnects from data sources.

Step 5 Starts a thread

Chapter 1 Understanding BMC Atrium Integration Engine 21

Step 1 Refreshes the data exchange.

Step 2 Starts a separate thread for each data exchange

Step 3 Locates data to be exchanged.

Step 4 Transfers data

Step 5 Disconnects from data stores

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

Chapter 1 Understanding BMC Atrium Integration Engine 23

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

Using multiple data exchanges

Figure 1-3: Using multiple data exchanges

Dublin Database New York Database

Chapter 1 Understanding BMC Atrium Integration Engine 25

Roles and permissions

Table 1-2 describes these roles and their permissions.

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

! Group Category: Regular

2 For the AIE Definitions Admin role, mapped

! Group Category: Regular

2 For the AIE User role, mapped the AIE User

Chapter 1 Understanding BMC Atrium Integration Engine 27

BMC Atrium Integration Engine in a server

How BMC Atrium Integration Engine works in a server group

Server Host Instance name

Chapter 1 Understanding BMC Atrium Integration Engine 29

Table 1-4: Default datasets in BMC Atrium CMDB