atrium integrator 7.6.04 user's guide

www.bmc.com

Atrium Integrator 7.6.04

User’s Guide

January 2011

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

Contacting BMC Software

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

United States and Canada

Address BMC SOFTWARE INC2101 CITYWEST BLVDHOUSTON TX 77042-2827 USA

Telephone 713 918 8800 or800 841 2031

Fax 713 918 8000

Outside United States and Canada

Telephone (01) 713 918 8800 Fax (01) 713 918 8000

© Copyright 2011 BMC Software, Inc.

BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are registered with the U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other BMC trademarks, service marks, and logos may be registered or pending registration in the U.S. or in other countries. All other trademarks or registered trademarks are the property of their respective owners.

DB2, IBM, and Informix are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both.

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

The information included in this documentation is the proprietary and confidential information of BMC Software, Inc., its affiliates, or licensors. Your use of this information is subject to the terms and conditions of the applicable End User License agreement for the product and to the proprietary and restricted rights notices included in the product documentation.

Restricted rights legendU.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is BMC Software, Inc., 2101 CityWest Blvd., Houston, TX 77042-2827, USA. Any contract notices should be sent to this address.

http://www.bmc.com

mailto:[email protected]

Customer Support

You can obtain technical support by using the Support page on the BMC Software website or by contacting Customer Support by telephone or email. To expedite your inquiry, please see “Before Contacting BMC Software.”

Support website

You can obtain technical support from BMC Software 24 hours a day, 7 days a week athttp://www.bmc.com/support. From this website, you can:

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

numbers, and telephone numbers.

Support by telephone or email

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

Before contacting BMC Software

Have the following information available so that Customer Support can begin working on your issue immediately:

■ Product information

— Product name— Product version (release number)— License number and password (trial or permanent)

■ Operating system and environment information

— Machine type— Operating system type, version, and service pack— System hardware configuration— Serial numbers— Related software (database, application, and communication) including type, version, and service pack or

maintenance level

■ Sequence of events leading to the problem

■ Commands and options that you used

■ Messages received (and the time and date that you received them)

— Product error messages— Messages from the operating system, such as file system full— Messages from related software

http://www.bmc.com/support



License key and password information

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

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

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

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



Contents

BMC Atrium Core documentation 9

Chapter 1 Understanding Atrium Integrator 13

Atrium Integrator value proposition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Overview of Atrium Integrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Calbro Services user story. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Atrium Integrator terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Overview of the data transfer process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Atrium Integrator components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Manage Data Stores tool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Integration Job Builder wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Atrium Integrator console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Spoon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Carte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Performance considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Preparing to transfer data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Accessing the Atrium Integrator console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Chapter 2 Scenario for transferring data to BMC Atrium CMDB 27

Source data organization at Calbro Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Mapping source data to BMC Atrium CMDB. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Mapping relationship classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Preparing to transfer Calbro Services data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Creating a dataset for the Calbro data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Creating a database connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Adding an attribute to the BMC_DiskDrive class . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Transferring Calbro data to BMC Atrium CMDB. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Creating a data transfer job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Opening the job and transformations in Spoon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Editing the job in Spoon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Running the job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Verifying that the transferred data is in BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . 49Monitoring the job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Contents 5

Chapter 3 Working with data store connections 53

Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Supported data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Creating a new data store connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

RPC Ports in BMC Atrium CMDB. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Editing a data store connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Deleting a data store connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Chapter 4 Creating a job 61

Creating a simple job through the Integration Job Builder wizard. . . . . . . . . . . . . . . . 62High-level steps for creating a job through the Integration Job Builder wizard . 62Creating a job through the Integration Job Builder wizard . . . . . . . . . . . . . . . . . . . 64

Creating a complex job in Spoon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Creating a job to migrate data from a development server to a production server.

82

Chapter 5 Editing jobs and transformations 85

Opening your job or transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Mapping the Integration Job Builder wizard output to Spoon steps . . . . . . . . . . . . . . 87Connecting transformation steps or job entries in Spoon. . . . . . . . . . . . . . . . . . . . . . . . 88

Creating a hop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Reversing the direction of a hop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Disabling a hop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Deleting a hop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Specifying the condition on which a job entry is executed . . . . . . . . . . . . . . . . . . . 89Transformation hop colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Adding intermediate steps to a job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Adding intermediate steps to a transformation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Editing transformation steps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Editing transformation properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Launching several copies of a step. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Changing data mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Exploring a database connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Browsing source data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Changing source configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Chapter 6 Running and monitoring a job 105

Running a job from the Atrium Integrator console . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Running a job in Spoon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Monitoring jobs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Viewing job history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Viewing job details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Changing the job schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

6 User’s Guide

Chapter 7 Debugging and troubleshooting jobs 113

Troubleshooting Atrium Integrator console issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Job fails to run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Job not displayed on the Atrium Integrator console . . . . . . . . . . . . . . . . . . . . . . . 115Job not running from the Atrium Integrator console. . . . . . . . . . . . . . . . . . . . . . . 116

Troubleshooting errors displayed in Spoon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Location of log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Error connecting to a Microsoft SQL Server database using Windows Authentication

in Spoon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Atrium Integrator Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Chapter 8 Migrating jobs to a production server 125

Appendix A Moving from BMC Atrium Integration Engine to Atrium Integrator 127

Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Index 131

Contents 7

8 User’s Guide

BMC Atrium Core documentation

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

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

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

Title Description Audience

Atrium Integrator 7.6.04 User's Guide

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

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

BMC Atrium CMDB 7.6.04 Administrator's Guide

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

Configuration managers, application administrators, and asset analysts.

BMC Atrium CMDB 7.6.04 Common Data Model Diagram

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


BMC Atrium CMDB 7.6.04 Data Model Help

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

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


BMC Atrium CMDB 7.6.04 Data Modeling Guide

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





BMC Atrium CMDB 7.6.04 Javadoc Help

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


Application programmers.

BMC Atrium CMDB 7.6.04 Normalization and Reconciliation Guide

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


BMC Atrium CMDB 7.6.04 Online Help

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

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

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

BMC Atrium CMDB 7.6.04 User's Guide

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

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

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

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

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


BMC Atrium Core 7.6.04 Compatibility Matrix

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

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


BMC Atrium Core 7.6.04 Concepts and Planning Guide

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

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


10 User’s Guide

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

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

BMC Atrium Core 7.6.04 Developer’s Reference Guide

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

Application administrators and programmers.

BMC Atrium Core 7.6.04 Installation Guide

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

Application administrators.

BMC Atrium Core 7.6.04 Master Index

Combined index of all guides. Everyone.

BMC Atrium Core 7.6.04 Product Catalog and DML Guide

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

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

BMC Atrium Core 7.6.04 Release Notes

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

Everyone.

BMC Atrium Core 7.6.04 Troubleshooting Guide

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

Application administrators, programmers, and BMC Support personnel.

BMC Atrium Core 7.6.04 Web Services Help

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


Application administrators and programmers.

BMC Atrium Integration Engine 7.6.04 ADK Developer's Guide

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

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

BMC Atrium Integration Engine 7.6.04 Online Help

Help for using and configuring BMC Atrium Integration Engine.

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

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




BMC Atrium Integration Engine 7.6.04 User's Guide

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

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

Mapping Your Data to BMC Atrium CMDB 7.6.04 Classes

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



12 User’s Guide

Chapter

1
Understanding Atrium Integrator
Atrium Integrator is an integration engine that enables you to transfer data from external data stores to BMC Atrium Configuration Management Database (BMC Atrium CMDB) classes. You can connect to a wide variety of input sources using connectors such as JDBC, ODBC, JMS, native databases, web services, and complex XML. Atrium Integrator provides you with the ability to clean and transform your data before putting it into BMC Atrium CMDB.

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:

� Atrium Integrator value proposition (page 14)� Overview of Atrium Integrator (page 14)� Calbro Services user story (page 15)� Datasets (page 16)� Atrium Integrator terminology (page 17)� Overview of the data transfer process (page 17)� Atrium Integrator components (page 18)� Performance considerations (page 23)� Preparing to transfer data (page 24)� Accessing the Atrium Integrator console (page 24)



Atrium Integrator value propositionYour IT management data resides in multiple repositories–for example, in an SQL table, an XML file, and a non-BMC discovery dataset. You want to load this data into the BMC Atrium CMDB.

You can use Atrium Integrator to load data from multiple external repositories into the BMC Atrium CMDB. You can define how external data maps to Atrium CMDB and transform external data using various rules

With Atrium Integrator, you can schedule and perform bulk data transfers. You can also use Atrium Integrator for initial data loading, incremental data transfers, and data synchronization. For example, you can use Atrium Integrator 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.

During data transfers, Atrium Integrator identifies the records to be transferred and performs some or all of the following tasks, depending on how you have configured your integration:

� Reads records

� Creates new records

� Updates records

� Deletes records

� Modifies data (such as concatenating fields)

Overview of Atrium IntegratorThis section describes how Atrium Integrator integrates with the BMC Atrium Core components to form a solution. This architecture is shown in Figure 1-1.

14 User’s Guide

Calbro Services user story

Figure 1-1: BMC Atrium Core architecture

Atrium Integrator transfers data from an external datastore to BMC Atrium CMDB. When the data is in a BMC Atrium CMDB dataset, the Normalization Engine ensures that data from different data providers is consistent. The Reconciliation Engine merges data from multiple import datasets into the BMC Asset dataset. For more information about datasets, see “Datasets” on page 16.

Calbro Services user storyThis document uses a fictional company named Calbro Services to explain how Atrium Integrator 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 Atrium Integrator 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, flat files, and XML files in various locations across the globe. Calbro Services wants to transfer information from its Chicago, London, Dublin, and Adelaide sites to their New York centralized database. Calbro Services also wants to transfer the personnel records of employees from the Dublin site to the New York site.

This guide provides examples for transferring this data.

BMC Atrium Core

BMC Atrium CMDB

DatabasesComplex XML file

CSV file

Discovery application

Atrium Integrator

Reco

nci

liatio

n

En

gin

e

Nor

mal

izat

ion

Eng

ine

Import datasets

BMC RemedyAsset Mgmt

Federated data

OtherConsumers

Sandbox dataset

Production dataset

BMC Atrium

Product Catalog



DatasetsA dataset is a logical group of data in BMC Atrium CMDB. It is a collection of CIs and relationships for a given purpose. A dataset can represent data from a particular source or a snapshot from a particular date. The primary purpose of datasets is to partition data according to the data providers. Each discovery application that you use should store the data it collects in a separate dataset. You can also use datasets for any other logical group of data.

All CIs and relationships in BMC Atrium CMDB reside in a particular dataset, which is specified by the value of their DatasetID attribute.

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

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 Do not use Atrium Integrator to transfer data directly into the BMC Asset dataset. Instead, transfer the data into another dataset and then reconcile it into BMC Asset.

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

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

Table 1-1: Default datasets in BMC Atrium CMDB

Data created by Dataset name DatasetID

BMC Atrium CMDB BMC Asset BMC.ASSET

BMC Sample BMC.SAMPLE

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

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

BMC Atrium Discovery and Dependency Mapping

BMC Topology Import BMC.IMPORT.TOPO

16 User’s Guide

Atrium Integrator terminology

Atrium Integrator terminologyThe complete process of transferring data from an external source (for example, an XML file) to a BMC Atrium CMDB CI class is referred to as an integration.

The following terms are used in Atrium Integrator to describe the various aspects of an integration:

� A transformation is the combination of steps and hops that make an integration between source and target data stores possible. It reads data from the source data store, transforms it according to the rules that you specify, and stores it in the target data store.

� A transformation consists of a series of steps. Steps define the input and output data stores as well the clean up or adjustment actions that you might want to perform on the data before adding it to BMC Atrium CMDB.

� Steps are connected by hops, which indicate the direction of the data flow.

� A job defines the order in which a series of transformations are run so that the dependencies of the individual transformations are met.

� A repository is a relational database in which you can store your transformations and jobs. You can also use a repository to store the logs that are generated when executing transformations and jobs.

Overview of the data transfer processTo transfer data into BMC Atrium CMDB, follow the process outlined in the following steps.

Figure 1-2: Overview of the data transfer process

Each step represents a procedure. In the section that relates to each procedure, the graphic is repeated, and the related step is highlighted.

Step 1 Configure source and target connection.

You must define connection parameters (such as host name, port number, user name, and password) to your external data store and BMC Atrium CMDB. After you create a connection, you can reuse it for multiple transformations or jobs. For instructions, see Chapter 3, “Working with data store connections.”

1 Con�gure source 2 Create and 3 Edit transformation 4 Run job 5 Monitor job & target connection schedule job or job



Step 2 Create a job or transformation.

The Integration Job Builder wizard guides you through the process of creating a job or transformation. After you specify the source and the CIs that you want to import, the wizard makes recommendations on the relationships for the selected CIs. For instructions, see Chapter 4, “Creating a job.”

You can also create a job in the Pentaho Spoon application. For instructions, see the Spoon User Guide at http://wiki.pentaho.com/display/EAI/Spoon+User+Guide.

Step 3 Edit your transformation or job in Spoon.

You can add intermediate steps for cleaning up or manipulating your data before adding it to BMC Atrium CMDB. Spoon provides support for JavaScript and a wide variety of prebuilt functions. For instructions, see Chapter 5, “Editing jobs and transformations.”

Step 4 Verify and run your job. If the job completes without any errors, verify that the data has been added to the appropriate BMC Atrium CMDB class. If the job displays error messages, debug the job and run it again. For instructions, see Chapter 6, “Running and monitoring a job.”

Step 5 Monitor your jobs.

After you create and run your job, you can monitor it. The Atrium Integrator console displays the job run information. For information, see Chapter 6, “Running and monitoring a job.”

Step 6 Migrate your jobs to a production server

After you create and test your data transfer jobs on a development computer, you can migrate them to a production server. For information, see Chapter 8, “Migrating jobs to a production server.”

Chapter 2, “Scenario for transferring data to BMC Atrium CMDB” takes you through the complete data transfer process for a sample scenario.

Atrium Integrator componentsAtrium Integrator uses the Pentaho Data Integration tool and has the following main components:

� Manage Data Stores tool (page 20)

� Integration Job Builder wizard (page 20)

� Spoon (page 21)

� Carte (page 23)

18 User’s Guide

Atrium Integrator components

Figure 1-3 on page 19 shows the Pentaho Data Integration tool components, Spoon and the Pentaho Carte application, in relation to the BMC Atrium Core architecture.

Figure 1-3: Pentaho Data Integration components in relation to BMC Atrium Core

Figure 1-4 on page 20 shows how the Atrium Integrator components work together.

BMC Atrium CoreConsole

Database

Repository

Source data to be tranferred to BMC

Atrium CMDB

Carte server

Pentaho Spoon

CMDB plugin

BMC Remedy Action Request

System

BMC AtriumCMDB

BMC Remedy Mid Tier

Atrium Integratorconsole



Figure 1-4: Atrium Integrator components

Manage Data Stores toolThe Manage Data Stores tools helps you define connection parameters (such as host name, port number, user name and password) to your external data store and BMC Atrium CMDB.

Integration Job Builder wizardThe Integration Job Builder wizard helps you create a job for transferring your data from an external data store to BMC Atrium CMDB. You can specify the source and target details, specify the CI types and relationships to transfer, and define your preferences for deltas, deletes, reject files, and logging.

Atrium Integrator consoleThe left panel of the Atrium Integrator console displays a list of jobs available in the Spoon repository.

Atrium Integratorconsole

Database, CSV, XML

Input

RepositoryStores the job

Carte serverRuns the job

Pentaho Spoon(Optional)

Edit a job to add complex steps

CMDB plugin

BMC Atrium CMDBOutput

Manage Data Stores tool

Create a data store connection

Integration Job Builder wizard

Createa job

Job Scheduler

Schedule the job

Job MonitoringMonitor the

job

Job

20 User’s Guide

Atrium Integrator components

The History tab on the right panel displays the job run information for the selected job. You can also display jobs with a specific status or jobs that executed within a range of dates. The Integration Job Details tab displays the date, source and target types, and description of a job.

The Atrium Integrator console provides access to the Manage Data Stores tool and Integration Job Builder wizard. You can start and stop a job, schedule a job, and monitor a job.

For more information about the tasks that you can perform from the Atrium Integrator console, see the following sections:

� “Working with data store connections” on page 53

� “Creating a job” on page 61

� “Running and monitoring a job” on page 105

Spoon After you build your job, you can edit it in the Spoon application. Spoon has a drag-and-drop graphical user interface that makes it easy for you to edit your transformations and clean up your data before putting it into BMC Atrium CMDB.



Figure 1-5: Spoon application

Menu bar

The menu bar provides access to common actions such as creating a new transformation or job, editing it, connecting to a repository, and running or debugging the job or transformation.

Navigation panel

The navigation panel on the left contains a View tab and Design tab.

The View tab maintains a history of the different types of steps that were added to the active transformation or job. For a new transformation or job, this tab displays the steps that a transformation must include to run successfully.

The Design tab provides an organized list of transformation steps or job entries used to build transformations and jobs.

Active transformation or jobNavigation panel stepsMenu bar CanvasToolbar Transformation stepHop

22 User’s Guide

Performance considerations

You can perform a search in either tab by typing a phrase in the search field and pressing the Enter key. The steps containing the search phrase are displayed.

Click the icon to expand all steps and the icon to collapse the steps.

Toolbar

The toolbar provides buttons for common actions such as creating a new file, opening a saved file, and saving a file. It also provides buttons for quick access to common actions specific to the active transformation or job, such as Run, Preview, and Debug.

Canvas

The canvas is the main design area for building transformations and jobs.

Active transformation or job

The canvas displays a number of tabbed views that represent the open transformations and jobs. In Figure 1-5 on page 22, the DiskDrive transformation is the active transformation.

CarteCarte is a simple web server that you can use to execute transformations and jobs remotely.

Performance considerationsPerformance considerations for Atrium Integrator depend on your network, BMC Remedy Action Request System (BMC Remedy AR System), the BMC Remedy AR System server database, and the external data store load. Predicting the effect of a specific change on Atrium Integrator performance is difficult, but configuration considerations can influence performance.

Although it is easy to add field mappings or extra transformations for each field, remember that each item you add is compared against every record in your database. Seemingly minor additions could have a major impact if your database contains many records. For example, if you have 1200 records in your database and a change adds an additional half-second to the run time for each record, the data transfer might take an additional 10 minutes to run.

Best practices

Following are some best practices that can improve the performance of Atrium Integrator:

� Create index entries on:

� The 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 the Fast Thread and List Thread options and how to specify the number of threads, see the BMC Remedy Action Request System 7.6.04 Configuration Guide.

� Launch multiple copies of a step. For optimum performance, you can launch 20 copies of a step.

� Distribute a step to multiple processing flows when you want to split the transformation flow to multiple processing paths.

� When possible, run job and transformation steps in parallel to improve throughput. If dependencies exist, however, you cannot runs steps in parallel.

� Limit the columns that you map. The more columns you map, the slower the transformation runs.

� Use JavaScript and lookup steps sparingly as they can significantly increase the processing time.

Preparing to transfer dataThis section illustrates the high-level steps that you perform to prepare for transferring data.

Step 1 Create a new source dataset to which you can migrate your source data to. Datasets help in categorizing data by providers. You can then reconcile your dataset with BMC.ASSET.

Step 2 Create index entries on the BMC_BaseElement class in the Class Manager application to improve the performance of Atrium Integrator.

For instructions, see the BMC Atrium CMDB 7.6.04 Administrator's Guide.

Accessing the Atrium Integrator consoleThe Atrium Integrator console is the main user interface for Atrium Integrator. You can access the other Atrium Integrator components from the console.

� To access the Atrium Integrator console

1 In a browser, enter the URL designated by an administrator. For example:

http://midTier:port/arsys

� midTier is the name of the web server where the BMC Remedy Mid Tier is installed.

24 User’s Guide

Accessing the Atrium Integrator console

� 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 if using Microsoft IIS or 8080 if using Apache Tomcat).

2 In the login page, specify the following details:

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

� In the Password field, type your password.

� In the Authentication field, type the authentication string (if one was provided by an administrator)

3 Click Login.

4 In the AR System Home page, choose BMC Atrium Core > Atrium Core Console.

If you access multiple servers from the AR System Home page, you would choose BMC Atrium Core > serverName > Atrium Core Console.

The Application Launcher bar appears on the left side of the console.

5 From the Application Launcher bar, choose Integration Engines > Integrator.

Figure 1-6: Atrium Integrator link from the Application Launcher

The Atrium Integrator console appears.



26 User’s Guide

Chapter

2
Scenario for transferring data to BMC Atrium CMDB
This tutorial describes a sample BMC Atrium CMDB scenario in which the Calbro administrator, Allen Allbrook, prepares his CMDB for Atrium Integrator, creates and runs an Atrium Integrator job, verifies its success, and schedules it to run repeatedly.

Through this example, you can see how the components of Atrium Integrator work together to help you migrate data from an external database to BMC Atrium CMDB.


� Source data organization at Calbro Services (page 28)� Preparing to transfer Calbro Services data (page 30)� Transferring Calbro data to BMC Atrium CMDB (page 31)� Opening the job and transformations in Spoon (page 40)� Editing the job in Spoon (page 45)� Running the job (page 48)� Verifying that the transferred data is in BMC Atrium CMDB (page 49)� Monitoring the job (page 50)



Source data organization at Calbro ServicesCalbro Services has an external database that stores information about all the hardware components in its environment. The external database 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 2-1.

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

Mapping source data to BMC Atrium CMDBThe 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.

Mapping relationship classesMuch 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.

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. For example, in Figure 2-1 on page 28, disk 1520 in the Disk Drive table is associated with computer vm2-w4-dev01 in the Computer table.

Because each disk drive is associated with a computer, you can select a relationship 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 HostName attribute in the BMC_ComputerSystem class contain the data necessary to create the relationship.

Name SerialNumber AssociatedComputerDisk 1520 23541 vm2-w4-dev01Disk 1523 24761 vm2-w3-dev02Disk 1560 24645 vm2-w4-dev03Disk 1534 24671 vm2-w5-dev06Disk 1530 26541 vm2-w7-dev10

Computer table

HostName SerialNumber Manufacturervm2-w4-dev01 MX2435 Dellvm2-w3-dev02 VL3421 HPvm2-w4-dev03 DW2313 Dellvm2-w5-dev06 MX2400 Dell vm2-w7-dev10 MX550 HP

Disk Drive table

28 User’s Guide

Source data organization at Calbro Services

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 this case, BMC_ComputerSystem is the source (primary) member and BMC_DiskDrive is the destination (secondary) member of the BMC_HostedSystemComponents relationship class. For more information about relationship classes, see the BMC Atrium Core 7.6.04 Concepts and Planning Guide.

NOTE The transformations that bring data from the external data store into the CI classes (in this case, BMC_DiskDrive and BMC_ComputerSystem) must finish before the transformation for the relationship class can run, because that transformation needs the instance IDs of the related CIs for their relationship instance. The wizard schedules the transformations in this order automatically.

The relationship between computer systems and disk drives at Calbro Services is stored within the source tables, as shown in Figure 2-1 on page 28. Figure 2-2 on page 29 shows how data from the external database is transferred into BMC Atrium CMDB to create CIs, and then how a relationship class instance is created based on attributes in the CI classes.

Figure 2-2: Creating relationships based on attributes in both CI classes

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

Disk Drive table

Name SerialNumber AssociatedComputerDisk 1520 23541 vm2-w4-dev01Disk 1523 24761 vm2-w3-dev02Disk 1560 24645 vm2-w4-dev03Disk 1534 24671 vm2-w5-dev06Disk 1530 26541 vm2-w7-dev10

Computer table

HostName SerialNumber Manufacturer vm2-w4-dev01 MX2435 Dellvm2-w3-dev02 VL3421 HPvm2-w4-dev03 DW2313 Dellvm2-w5-dev06 MX2400 Dell vm2-w7-dev10 MX550 HP

BMC_HostedSystemComponentsSource.InstanceId Destination.InstanceId

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

Disk 1520 23541 vm2-w4-dev01 1F6ABC21F Disk 1523 24761 vm2-w3-dev02 1B3CFA89D Disk 1560 24645 vm2-w4-dev03 1E8AFB71E Disk 1534 24671 vm2-w5-dev06 1A2CAC48F Disk 1530 26541 vm2-w7-dev10 1F5AFE19A

vm2-w4-dev01 Dell MX2435 F8FEF67Avm2-w3-dev02 HP VL3421 1F8FBE71Cvm2-w4-dev03 Dell DW2313 1E6A2L5AFvm2-w5-dev06 Dell MX2400 1C4E8A2FFvm2-w7-dev10 HP MX550 1A2B2C5CD

Externaldatastore

BMC AtriumCMDB

RelationshipClass

Transformation

Transformation

Transformation

BMC_DiskDrive

Name IntegrateId* ParentIntegrateId** InstanceId

BMC_ComputerSystem

Name Manufacturer IntegrateId* InstanceId

*IntegrateId = CalbroIntegrationId**ParentIntegrateId = CalbroParentIntegrationId



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.

Preparing to transfer Calbro Services dataAllen Allbrook prepares to transfer the Calbro Services computer system and disk drive data to BMC Atrium CMDB by:

� Creating a dataset for the transferred data

� Creating connections to the source and destination databases

� Adding an attribute to the BMC_DiskDrive CI class

Creating a dataset for the Calbro dataAs BMC recommends, Allen Allbrook creates a dataset, CALBRO.IMPORT, in BMC Atrium CMDB. A separate dataset helps partition data according to data providers.

� To create a dataset

1 Use the direct access URL to open the BMC Remedy AR System Server midtier and log in with your user name and password.

2 On the AR System Home page, choose BMC Atrium Core > Atrium Core Console.

3 In the BMC Atrium Core Console, choose Application Launcher > Reconciliation.

4 In the Reconciliation console, click Create Dataset .

5 In the Dataset Editor, specify the Name (Calbro.Import) and ID (CALBRO.IMPORT) for the dataset.

6 In the Accessibility field, select Writable.

7 Click Save.

The CALBRO.IMPORT dataset is created in BMC Atrium CMDB.

30 User’s Guide

Transferring Calbro data to BMC Atrium CMDB

Creating a database connectionNow Allen creates a data store connection to communicate with the external database, which is the source of the data. Allen then creates a connection to communicate with the BMC Atrium CMDB server, which is the destination for the data.

� To create a source database connection

1 In the BMC Atrium Core Console, choose Application Launcher > Integration Engines > Integrator.

2 In the Atrium Integrator console, click Manage Data Store Connections .

3 Click New Data Store .

4 In the New Data Store section on the right side of the Manage Data Stores window, select the Data Store Type as Database.

5 Type Calbro Source Tables in the Name field.

6 Specify the remaining information for your source database.

7 To verify your source database connection parameters, click Test Connection.

8 Click Save.

� To create a target database connection


2 In the New Data Store section on the right side of the Manage Data Stores window, select CMDB as the Data Store Type.

3 In the Data Store Name field, type Calbro Connection to CMDB.

4 Specify the remaining information for the target database.

5 To ensure that you can connect to BMC Atrium CMDB, click Test Connection.

6 Click Save.

Adding an attribute to the BMC_DiskDrive classAllen creates the ExternalParentIntegrationId attribute in the BMC_DiskDrive CI class using the Class Manager. For more information about creating attributes, see the BMC Atrium CMDB 7.6.03 Administrator's Guide.

Transferring Calbro data to BMC Atrium CMDBAfter preparing the data, Allen Allbrook transfers the data by:

� Creating a data transfer job through the Integration Job Builder wizard

� Editing the job to map an additional column to a target attribute

� Running the job



After the transfer is completed, Allen Allbrook:

� Verifies that the data is in BMC Atrium CMDB

� Monitors the data transfer job in the BMC Atrium Integrator console

Creating a data transfer jobAllen uses the Integration Job Builder wizard to create a data transfer job. The wizard helps Allen Allbrook create a basic job, which he can then edit in Spoon to tailor it to meet Calbro’s data transfer requirements.

� To create a job

1 In the Atrium Integrator console, click Create Job .

2 Click anywhere in the Overview page.

The General page appears.

Figure 2-3: General page of the Integration Job Builder wizard

3 In the Job Name field, enter Transfer Calbro data.

4 In the Description field, enter Transfer computer system and disk drive information to CMDB.

5 In the Type field of the Specify Data Store Details for Source area, select Database and in the Name field, select Calbro Source Tables.

6 In the Name field of the Specify Data Store Details for Target area, select Calbro Connection to CMDB, and in the Dataset ID, select CALBRO.IMPORT.

32 User’s Guide


As BMC recommends, Allen Allbrook does not use Atrium Integrator to transfer data directly into the BMC Asset dataset. Instead, he transfers the data into the CALBRO.IMPORT dataset and then reconciles it into BMC Asset.

7 Click Next.

The CI Type Selection page appears.

Figure 2-4: CI Type Selection page of the Integration Job Builder wizard

8 In the Select CI Type from area, select CI List.

9 In the Available List of CI Types, type computer.

The search criteria applies as you enter text, and the matching CIs update automatically in the CI Types table.

10 Select computer system and click Add.

Computer system is moved to the Selected CI Types area.

11 Repeat step 9 and step 10 to add disk drive.

12 Click Next.

The CI TypeRelationships page appears.



Figure 2-5: CI TypeRelationships page of the Integration Job Builder wizard

13 From the Available CI Types of Relationships area, select SYSTEMDEVICE and click Add.

This relationship identifies computer system as the parent CI and disk drive as the child CI.

The step toolbar is updated to reflect the selections that Allen Allbrook made, as shown in Figure 2-5 on page 34.

14 Click Next.

The Computer system Mapping page appears, which displays the target CI class as BMC_ComputerSytem. Here, Allen maps attributes from the BMC_ComputerSystem class to columns from the source table to specify the fields and attributes to be transferred.

34 User’s Guide


Figure 2-6: Computer system Mapping page of the Integration Job Builder wizard

15 On the Select Source field, leave the default selection of Table.

16 In the Schema field, select dbo, and in Table, select CalbroComputerSystem.

17 Select a target attribute and corresponding source column as displayed in the following table, and click Map.



Repeat this step for each row in the table. The names in the Source column are the Computer table database columns in Figure 2-1 on page 28.

Each row is added to the Mapped Columns area.

18 For the HostName row, select the Source Key check box (which indicates that the HostName column uniquely identifies each row of data in the source table).

19 Click the Transformation Options tab.

20 For Delta, leave the default selection of Yes and select the LastModified column.

Note that the default value of Delta is Yes only when your source table has a date/time column.

21 For Response, leave the default selection of No.

22 Click Next.

The Disk drive Mapping page appears, which displays the target CI class as BMC_DiskDrive.

Figure 2-7: Disk drive Mapping page of the Integration Job Builder wizard

23 On the Select Source field, leave the default selection of Table.

24 In the Schema field, select dbo, and in Table, select CalbroDiskDrive.

Target attribute Source Column

Name HostName

SerialNumber SerialNumber

ManufacturerName Manufacturer

36 User’s Guide


25 Select a target attribute and corresponding source column as displayed in the following table, and click Map.

Repeat this step for each row in the table. The names in the Source column are the Computer table database columns in Figure 2-1 on page 28.

26 For the SerialNumber row, select the Source Key check box (which indicates that the SerialNumber column uniquely identifies each row of data in the source table).


28 For Delta, leave the default selection of Yes. Select the source column to be used for delta.

29 For Response, leave the default selection of No.

30 Click Next.

The Relationships Mappings page appears, and lists the Parent CI as Computer system and child CI as Disk drive. On this page, Allen specifies how the two source tables are related to each other.

Figure 2-8: Relationship Mapping page of the Integration Job Builder wizard

Target attribute Source Column

Name Name

SerialNumber SerialNumber

ExternalParentIntegrationId Associated Computer



31 Leave the default selection of Key Columns of Computer system in table “CalbroComputerSystem” are mapped to columns of “Disk drive” in table “CalbroDiskDrive”. This indicates that relationship information is stored in the computer system and disk drive source tables. For more information, see “Mapping relationship classes” on page 28.

The Computer system Key Columns table displays the Source key that Allen had selected in step 26 on page 37 (HostName).

32 From the Disk drive Columns area, select AssociatedComputer.

This indicates that for each BMC_DiskDrive instance, a match exists between its AssociatedComputer value and the HostName value in a BMC_ComputerSystem.

33 In the Transformation Options tab, leave the default selection of Yes for Delta and select the LastModified column.

34 Click Next.

The Schedule page appears, where Allen specifies the time at which the job is to run, and the time interval between jobs.

Figure 2-9: Schedule page of the Integration Job Builder wizard

35 In the Start Time field, enter 5:00:00 PM.

36 In the Interval area, type 1 in the Hours field.

Calbro Services wants to update the database with ATM transactions. Allen, therefore, schedules a data exchange at an interval of an hour to populate the database with the information of the ATM transactions.

38 User’s Guide


37 Click Next.

The Summary page appears.

Figure 2-10: Summary page

38 In the Summary page, click Finish.

The Generated Transformations dialog box displays the list of transformations generated to transfer the computer system and disk drive records to BMC Atrium CMDB.

Figure 2-11: List of transformations generated by the Integration Job Builder wizard



The following naming convention is used:

Name of job_CI being transferred (for example, Transfer Calbro data_Computer system)

39 Click OK.

The job is listed in the job catalog on the left side of the Atrium Integrator console, and runs as scheduled. If you want to do a test run, select the job from the job catalog and click Start Job .

Opening the job and transformations in SpoonAfter creating a simple data transfer job through the Integration Job Builder wizard, Allen Allbrook opens the job in Spoon to edit it.

� To open the job in Spoon

1 On the computer where you have the Spoon client installed, click Start > All Programs > BMC Software > Atrium Integrator > BMC Atrium Integrator Spoon.

The Spoon Repository login page appears.

Figure 2-12: Spoon Repository Login

2 Login as follows:

a In the Repository field, leave the default entry of NGIEREPD.

b In the Login field, enter admin.

c In the Password field, enter admin (the default password).

d Click OK.

40 User’s Guide

Opening the job and transformations in Spoon

3 In the Spoon window, choose Repository > Explore Repository.

4 In the Repository explorer dialog box, expand the Jobs directory, and then expand the directory.

All the jobs in the NGIEREPD repository are displayed.

5 Now expand the Transfer Calbro data directory.

Figure 2-13: Jobs and transformations for Calbro Services

6 Double-click the Transfer Calbro data job.

The job opens.

Figure 2-14: Transfer Calbro data job



7 Double-click the Set variables step.

The Set Variables dialog box shows the delta and response settings that Allen Allbrook specified when creating his job through the Integration Job Builder.

Figure 2-15: Set variables step in the Transfer Calbro data job

8 Click OK and then double-click the Sub_Transfer Calbro data step.

The Executing a job dialog box shows the delta and response arguments. The argument number is specified within the respective transformations.

Figure 2-16: Executing a job dialog box

9 Click OK.

42 User’s Guide

Opening the job and transformations in Spoon

10 Right-click the Sub_Transfer Calbro data step and select Open job.

The transformations created for the Transfer Calbro data job are displayed.

11 Right-click Transfer Calbro data_Computer system and select Open transformation.

The computer system transformation is displayed. Allen Allbrook makes edits to this transformation in “Editing the job in Spoon” on page 45.

Figure 2-17: Computer system transformation in Spoon



Table 2-1 describes each step in the Transfer Calbro data_Computer system_Delta transformation.

Table 2-1: Steps in the Transfer Calbro data_Computer system_Delta job transformation (Sheet 1 of 2)

Step name What the step does

Gets the latest time stamp from the NGIEDELTA table. For a delta job, records are transferred to BMC Atrium CMDB only if the Table Source Delta has a later time stamp than the Table Source Time Stamp.

Specifies the argument number for the delta setting. This steps gets the appropriate argument number from the Set variables step as shown in Figure 2-15 on page 42.

Specifies whether delta is set to yes, in which case the LastModified time stamp determines whether to transfer the records on a subsequent run. If delta is set to no, all records are transferred.

Deletes fields that are not required. This step is only for internal processing.

Specifies the source table.

Provides a placeholder step to add a new field by performing simple calculations.

Provides a placeholder step to map a field to a constant value.

Specifies the argument number for the response setting. This steps gets the appropriate argument number from the Set variables step as shown in Figure 2-15 on page 42.

Specifies the BMC Atrium CMDB class, namespace, and Dataset ID to which the data is to be transferred. This step also specifies the source key and input file–target attribute mappings.

After the records are transferred to BMC Atrium CMDB, the NGIEDELTA table is updated to reflect the time that the latest record was created in the source table.

44 User’s Guide

Editing the job in Spoon

Editing the job in SpoonAllen Allbrook wants to make the following edits to the job that he created:

� The abbreviation that Calbro Services uses for the name of the marketing department has changed from Mktg to MKTG. Allen Allbrook uses a calculator step to convert the values in the Department source column to uppercase before transferring them to BMC Atrium CMDB.

� Calbro Services wants to transfer data from the dbo.ComputerSystem.Department field only if the value is not NULL. Otherwise, they want to keep the value in the target database. Allen uses the Filter rows step to set this up.

� Map an additional source field to a target attribute.

Specifies the name of the transformation.

After the data is transferred to BMC Atrium CMDB, updates the NGIEDELTA table with the time stamp of the latest-created record in the source table. On the next delta run, only records that have a time stamp later than this will be transferred.

Specifies the name and path of the file to which errors are written to.

Defines the job flow. If you set Response as Yes, the job updates the specified source field.

For those records that were transferred successfully to BMC Atrium CMDB, the response values in the source table is set to 0.

For those records that were not transferred to BMC Atrium CMDB, the response values in the source table is set to 1.

For those records that were not transferred to BMC Atrium CMDB, the response values in the source table is set to 1.

Table 2-1: Steps in the Transfer Calbro data_Computer system_Delta job transformation (Sheet 2 of 2)

Step name What the step does



� To change the Department column values to uppercase

1 In the Transfer Calbro data_Computer system_Delta transformation, double-click the Calculator step.

Figure 2-18: Calculator step

2 In the New field column, enter Used By.

3 In the Calculation row, select UpperCase of a String A.

4 In Field A, select the Department column.

The upper case values from the Department column will be written to the Used By column.

5 Click OK.

� To add a step to transfer data from the Department field only if the value is not NULL

1 In the navigation panel, click Design.

2 From the Flow menu in the navigation panel, click the Filter rows step and drag it between the IsResponse and CMDBOutput steps. Click Yes to split the hop.

Figure 2-19: Inserting the Filter rows step

3 From the Transform menu in the navigation panel, click the Dummy plugin step and place it over the Filter rows 2 step.

4 Click the Filter rows 2 step, press the CTRL key, and then select the Dummy plugin step.

5 Right-click the Dummy plugin step and select New hop.

6 In the Hop dialog box, ensure that the value of the From step is Filter 2 row, the value of the To step is Dummy plugin, and the Enable hop check box is selected.

This enables you to set a condition and data that does not comply with your condition is transferred over to the Dummy plugin step.

7 Click OK.

46 User’s Guide

Editing the job in Spoon

In the dialog box that appears, select Distribute.

A hop connects the Filter rows 2 and Dummy plugin steps.

8 Double-click the Filter rows 2 step.

9 In the Filter rows dialog box, enter the appropriate values.

a For Step name, enter Filter rows.

b For Send true data to step, enter CMDBOutput.

c For Send false data to step, enter Dummy plugin.

d For the condition, specify Used By as IS NOT NULL.

Figure 2-20: Filter rows dialog box

10 Click OK.

� To map additional fields to target attributes

1 Double-click the CMDBOutput step.

Figure 2-21: CMDBOutput dialog box



2 In the Table field column in the Update fields table of the CMDBOutput dialog box, select Assigned to.

3 In the Stream field column, select Used By, and in the Update column, select Y.

Allen Allbrook selects these values to map the Used By column to the Assigned to attribute.

4 Click OK.

Allen has completed his edits.

5 Choose File > Save.

Running the jobAfter editing the job in Spoon, Allen Allbrook runs it to verify that it runs correctly.

1 In the Spoon window, click the Sub_Transfer Calbro data tab.

2 Choose File > Save.

3 Click Run .

4 In the Execute a job window, leave the default selection of Local execution.

NOTE Allen Allbrook runs this job locally because Calbro has BMC Atrium Core installed on the same computer as the Spoon client. If the Spoon client is installed on a different computer, Allen would execute the job remotely.

5 Click Launch.

The job runs and displays the logging details (in the Logging tab) in the bottom half of the window.

48 User’s Guide

Verifying that the transferred data is in BMC Atrium CMDB

Figure 2-22: Job Run window

You can also see the job progress on the Atrium Integrator console.

Verifying that the transferred data is in BMC Atrium CMDB

After the Transfer Calbro data job completes running, Allen Allbrook verifies that the computer system, disk drive, and relationship records have been transferred to BMC Atrium CMDB.

� To verify that the records have been transferred to

1 Return to the browser window and open the BMC Atrium Core Console.

2 Click Application Launcher > CMDB Applications > Explorer.

3 In BMC Atrium Explorer, click the Find tab.

4 In the Query list, click Options.

The Edit Query Options dialog box appears.

5 In the Dataset list, select the Calbro.Import dataset and click OK.



6 In the !Quick search of all CIs area, click Search.

The disk drives and computers from the external data store are displayed in the search results.

7 To view the relationship between the disk drives and computers, perform the following steps:

a Click the View tab.

b Click the New View button and select CALBRO.IMPORT.

A new view of the CALBRO.IMPORT dataset appears.

c Drag a CI (for example, Disk 1534) to the relationship panel.

d Right-click the CI and select Expand Parents.

The relationship between Computer vm2-w5-dev06 (parent) and Disk 1534 (child) is displayed.

Monitoring the jobAllen Allbrook can monitor the Calbro jobs (whether he ran them from the Atrium Integrator console, or Spoon) in the Atrium Integrator console.

� To monitor the data transfer job

1 From the job catalog of the Atrium Integrator console, select the Transfer Calbro data job.

The History tab displays the start and end times for each run of this job, as shown in Figure 2-23 on page 50.

Figure 2-23: History tab of the Atrium Integrator console

50 User’s Guide

Monitoring the job

2 Click the Integration Job Details tab to view additional details of the selected job.

Figure 2-24: Integration Job Details tab of the Atrium Integrator console



52 User’s Guide

Chapter

3
Working with data store connections
This section describes how to connect to your data stores, which is the first step in the data transfer process.


� Before you begin (page 54)� Supported data types (page 55)� Creating a new data store connection (page 55)� Editing a data store connection (page 58)� Deleting a data store connection (page 59)




Before you beginUse Table 3-1 to gather and record the required configuration information, which you will need when you create a data store connection.

Table 3-1: Required configuration information

Type of information Value

BMC Atrium CMDB

BMC Remedy AR System server name

Host name

Port

RPC Program Number

User ID

Password

CSV or Excel files

Path to directory where the file is saved

Database

Host name

Database type

Database name

Port

Instance name (only for Microsoft SQL Server)

User ID

Password

54 User’s Guide

Supported data types

Supported data typesTable 3-2 shows the supported external data store types and indicates whether you must define specific connection parameters when using that type.

Creating a new data store connection1 In the BMC Atrium Console, choose Application Launcher > Integration Engines

> Integrator.

The Atrium Integrator console appears.

2 Click Manage Data Store Connections .

The Manage Data Stores window appears, with a list of defined data sources.

Figure 3-1: Manage Data Stores window


The New Data Store section appears on the right side of the Manage Data Stores window.

Table 3-2: Supported data store types

Type Requires specific connection parameters

BMC Atrium CMDB Yes

Comma separated value (CSV) flat file

No

XML No

Databases� IBM® Informix®

� Microsoft SQL Server

� My SQL� Oracle®

� Sybase

Yes



Figure 3-2: New Data Store section of the Manage Data Stores window

4 Select the Data Store Type.

The fields below the Data Store Type change depending on the data store you selected.

5 To create a connection to BMC Atrium CMDB, complete the following steps. To create a connection to a CSV or XML file, skip to step 6 on page 56. To create a connection to a database, skip to step 7 on page 57.

a Type a name for the connection.

b In the AR Server Name field, type the name of your BMC Remedy AR System server.

c (optional) Type the port number.

d (optional) In the RPC Program Number field, type the RPC port if you use one.

NOTE You cannot specify a private RPC port for data transfers into BMC Atrium CMDB. You must use the ports defined by BMC Atrium CMDB. For more information about the RPC ports defined by BMC Atrium CMDB, see RPC Ports in BMC Atrium CMDB (page 58).

e Type the user ID and password to log in to BMC Atrium CMDB.

6 To create a connection to a CSV or XML file, complete the following steps:

56 User’s Guide

Creating a new data store connection

Figure 3-3: Creating a connection to a CSV or XML file


b Specify the path to the folder that contains the source file. Note that the source files must be on the same computer on which you have installed the BMC Remedy Mid Tier.

7 To create a connection to a database, complete the following steps:

Figure 3-4: Creating a connection to a database


b Enter the host name.

c Specify the database type.

d Enter the name of the database you want to connect to.

The default port for the specified database is displayed.



e (optional) For a SQL Server database, type the instance name.

f Type the user ID and password to log in to the database.

8 Click Test Connection to verify the connection parameters.

9 Click Save.

The data store connection is created and displayed in the Data Stores section on the left side of the Manage Data Stores window. Each connection has an icon attached to it depending on the data store type, as described in Table 3-3 on page 58.

Table 3-3: Icons associated with data stores

Clicking on a data store provides the connection parameter details for that source.

RPC Ports in BMC Atrium CMDBBMC Atrium CMDB has assigned the following RPC ports for Atrium Integrator:

Editing a data store connectionAll data store connections are displayed in the Data Stores section of the Manage Data Stores window.

1 In the Manage Data Stores window, select the data store for which you want to edit the connection information.

Connection details for the selected data store are displayed on the right side of the window.

Icon Associated data store type

CMDB

CSV file

XML file

Database

#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

58 User’s Guide

Deleting a data store connection

Figure 3-5: Connection details in the Manage Data Stores window

2 Make the necessary changes. Note that you cannot edit the data store type.

3 Click Test Connection to verify the connection parameters.

4 Click Save.

The data store connection is saved. Any new jobs that you create will be based on the edited connection, but jobs defined using the previous connection are not updated.

Deleting a data store connectionAll data store connections are displayed in the Data Stores section of the Manage Data Stores window.

1 In the Manage Data Stores window, select the data store for which you want to delete the connection.

2 Click Delete Data Store .

The data store connection is deleted. Jobs that were based on the deleted connection are not affected.



60 User’s Guide

Chapter

4
Creating a job
You can create a job in the Atrium Integrator console by using the Integration Job Builder wizard, or in the Spoon application.

Atrium Integrator provides an easy-to-use wizard for creating a simple data transfer job for importing data into BMC Atrium CMDB. For complex data manipulations, you can first create a simple data transfer job using the wizard, and then refine the generated job and transformations in Spoon.

To import and export data from inputs like LDAP, BMC Remedy AR System forms, or ITSM forms, you can create a job in Spoon using the samples provided by BMC.


� Creating a simple job through the Integration Job Builder wizard (page 62)� Creating a complex job in Spoon (page 81)




Creating a simple job through the Integration Job Builder wizard

You can use the Integration Job Builder wizard in the Atrium Integrator console to create a simple job for transferring data from XML files, CSV files, or databases (IBM DB2®, IBM Informix, Microsoft SQL Server, My SQL, Oracle, and Sybase) to BMC Atrium CMDB.

Using the wizard has the following benefits:

� You need to specify only the business names for the information types to be transferred to BMC Atrium CMDB. The wizard automatically selects the Common Data Model (CDM) classes and relationships based on the information entered.

� The wizard has built-in templates that specify typical integrations based on BMC experience in populating CMDB.

� The wizard adheres to best practices for populating data, such as auto populating categorizations and name fields for relationships.

� When multiple CI and relationship classes are selected, data transfers are sequentially ordered.

� Processing of delta records is simplified.

High-level steps for creating a job through the Integration Job Builder wizard

This section describes the high-level steps for creating a job to transfer data from an external data store to BMC Atrium CMDB using the Integration Job Builder wizard.

Best practice

BMC recommends that you use the Integration Job Builder wizard to automatically generate a job and transformations from best practice templates. This will improve your productivity by providing a starting point for developing and simplifying the transformation of data into BMC Atrium CMDB.

4 Map target attributes 5 De�ne relationship mapping 6 Schedule job 7 View job summary to source columns

1 Specify source and target details 2 Select CI types to transfer 3 Select relationships for the CI types to transfer

62 User’s Guide


Step 1 Specify source and target details.

You must specify the job name and description, external data store, and the CMDB class and DatasetID to which you want to transfer data. For more information, see “Specifying source and target details” on page 64.

Step 2 Select CI types to transfer.

Select the CI types that you want to transfer from the external data store. You can either select CIs from a list, or select CIs based on a template. For more information, see “Selecting CI types to transfer” on page 65.

Step 3 Select the relationships to transfer for the CI types.

Based on the CI types that you want to transfer, the Integration Job Builder wizard displays the relationships between the CI types. Select the relationships that you want to transfer. For more information, see “Selecting relationships to transfer for the CI types” on page 68.

Step 4 Map target attributes to source columns.

Map the target attributes of the CI to the columns in the external data store. For more information, see “Mapping target attributes to source columns” on page 69.

Step 5 Define the relationship mapping for the CI types to be transferred.

Specify whether the source has a:

� Direct association between parent and child classes

This option creates a mapping for a relationship class based on attributes in the CI classes (parent-child) that are members of this relationship.

� Separate table to define relationships

This option creates a mapping for a relationship class based on relationship data stored in the external data store.

For more information, see “Defining relationship mapping for the CI types to transfer” on page 74.

6 Schedule the job to run at a specific time or timed interval. For more information, see “Creating a job schedule” on page 79.

Step 7 View the job summary.

Verify the job name, and the CI types and relationships that you are transferring. For more information, see “Viewing the job summary” on page 80.



Creating a job through the Integration Job Builder wizardAtrium Integrator provides a wizard to simplify the process of creating a job to transfer data into BMC Atrium CMDB. This topic presents the steps for each wizard page in a separate procedure. Follow the procedures sequentially, as indicated in the graphic.

Specifying source and target details

� To specify source and target details

1 In the Atrium Integrator console, click Create Job .

2 In the Overview page, click anywhere on the screen.

The General page appears.

Figure 4-1: General page of the Integration Job Builder wizard

3 In the General page, enter the name and description of the job.



64 User’s Guide


4 In the Specify Data Store Details for Source area, specify the type and name of the external data store.

If you do not have a data store connection to your source data, click Data Store to create a new connection. For more information, see “Creating a new data store connection” on page 55.

5 In the Specify Data Store Details for Target area, select the name of the data store and DatasetID of the BMC Atrium CMDB class to which you are transferring data.

If you do not have a data store connection to BMC Atrium CMDB, click Data Store to create a new connection. For more information, see “Creating a new data store connection” on page 55.

NOTE Do not use Atrium Integrator to transfer data directly into the BMC Asset dataset. Instead, transfer the data into another dataset and then reconcile it into BMC Asset.

6 Click Next. The Next button is enabled only after the Job Name, Source and Target Name, and DatasetID fields have valid entries.

The CI Type Selection page appears.

Selecting CI types to transfer

You can select CI types grouped together in a template, or select the CI types for which you want to transfer data from a CI list. To select CI types from a template, see “To select CI types to transfer from a templates list” on page 65. To select independent CI types, see “To select CI types to transfer from a CI list” on page 67.

� To select CI types to transfer from a templates list

The Integration Job Builder wizard offers a desktop, server, and virtual machine template. Each available template groups together the appropriate CIs and relationships. For example, the virtual machine template groups all the CIs that make up that virtual machine. If you select this template, the wizard automatically moves all related CIs to the Selected CI Types area.





1 In the CI Type Selection page, leave the default selection of Templates in the Select CI Types from area.

Figure 4-2: CI Type Selection page of the Integration Job Builder wizard–Templates

2 Select the template from which to transfer CI types.

3 Click Add.

The selected template moves to the Selected Templates list. Click to see the CIs and relationships included in that template.

The CIs bundled with the selected template are displayed in the Selected CI Types area. You can remove a CI by selecting it and clicking Remove.

4 Click Next.

The Next button is enabled after one or more templates have been added to the Selected Templates column.

The CI Type Relationships page appears.

66 User’s Guide


� To select CI types to transfer from a CI list

1 In the CI Type Selection page, click Select CI Types from CI List.

Figure 4-3: CI Type Selection page of the Integration Job Builder wizard– CI List

2 Select the CI type you want to transfer.

To select multiple CI types, press the Ctrl key and then select the CI types.

When you hover over a CI type, its class name and Product categorization attributes (Category, Type, and Item or CTI) are displayed.

To filter the CI types by name, type in the Available List of CI Types field. Filtering is case insensitive and displays all results containing the filter text.

3 Click Add.

The selected CI types move to the Selected CI Types list.

4 Click Next.

The Next button is enabled after a CI type has been added to the Selected CI Types column.

The CI Relationships page appears.



Selecting relationships to transfer for the CI types

The CI Types Relationships page displays the available relationships for the selected CI types. When you hover over a relationship type, the relationship name and parent and child CIs are displayed.

� To select relationships to transfer for the CI types

1 In the CI Relationships page, select the relationships that you want to transfer.

To select multiple relationships, press the Ctrl key and select the relationships. To filter the relationships by name, type in the Available Relationships field. Filtering is case insensitive and displays all results containing the filter text.

Figure 4-4: CI Relationships page of the Integration Job Builder wizard

2 Click Add to move the selected relationships to the Selected CI Types Relationships list.

3 Click Next.



68 User’s Guide


The Mapping page for the last selected CI type appears. For example, if you had selected Computer system, Disk drive, and Operating system to be transferred to BMC Atrium CMDB, the Operating system Mapping page would appear.

Note that the step toolbar at the top of the page is updated to display a mapping step for each CI type that you selected and a step for the relationships. Each relationship is represented as a tab in the relationship page. For example, if you had selected the Computer system, Disk drive, and Operating system CIs and the SYSTEMOS relationship, the step toolbar would be updated.

Figure 4-5: Step toolbar of the Integration Job Builder wizard

Mapping target attributes to source columns

Mapping target attributes to source columns defines how data in the source corresponds to data in BMC Atrium CMDB and which actions to take when transferring between them.

A source key uniquely identifies a row of data. You must specify the attributes of the CI class and the corresponding column in the external data store that together make up the source key. After a data transfer, the source 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 source key, consider the following points:

� Do not use an attribute whose value could change or could be NULL, such as the Description attribute. If the source key of a record is NULL, the record cannot be identified and it 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 map target attributes to source columns 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 source key that are already in the standard identification rule. This ensures that you can use a Standard Job for reconciliation. For more information about Standard Jobs, see the BMC Atrium CMDB 7.6.04 Normalization and Reconciliation Guide.





� If you cannot use the standard rules, use attributes inherited from the 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 2-1 on page 28, you would define a source key that relates a drive ID in the Disk drive ID column of the CalbroDiskDrive table with the CalbroIntegrationID attribute in the BMC_DiskDrive class.

� To map target attributes to source columns for CSV or XML files

1 In the Mapping page, select the CSV or XML file from which you want to transfer records.

Columns from the selected file are displayed in the Source Columns list.

Figure 4-6: Mapping page of the Integration Job Builder wizard for CSV or XML files

2 Select a target attribute to which you want to transfer data.

To filter attributes by name, type in the Target Attributes field. Filtering is case insensitive and displays all results containing the filter text.

NOTE You must map all attributes identified by a * preceding the attribute name (for example, *Name).

3 From the Source Columns table, select a column from which you want to transfer data to the selected attribute.

To map the selected attribute to a constant value, enter the value in the field below the Source Columns table. To filter columns by name, type in the Source Columns field. Filtering is case insensitive and displays all results containing the filter text.

70 User’s Guide


4 Click Map.

The selected attribute and source column move to the Mapped Columns table.

5 Repeat step 2 through step 4 for each attribute to which you want to transfer data.

6 In the Mapped Columns table, select the Source Key check box for the Target Attribute/Source Column row that you want to specify as a source key.

7 Repeat step 6 for each source key that you want to map.

When you have a source key with more than one attribute from each side, the expressions are joined 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 source key matches.

NOTE You must have at least one attribute/source column mapping in addition to those specified as source keys.




Figure 4-7: Transformation Options tab–Mapping page of the Integration Job Builder wizard

9 In the Delta area:

� Select No to retrieve all source records each time your job runs.

� Select Yes to import only new or updated source records since the last transfer was run. Then select the column in your source that holds the time stamp indicating 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.

The default value for Delta is Yes if a column in your source table has a Date/Time value. If the source is a CSV file, all columns are listed in the Delta area.

Best practice

BMC recommends that you select the Delta=Yes mode at design time so that the job can be run in both delta and full modes in the future. If you specify Delta=No (that is, select full mode), the transformation that is designed will require significant manual changes in Spoon to make it delta enabled.

72 User’s Guide


10 Specify whether you want to set a Response field. You can specify a field that is 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.

If you select yes, select the column in your source that you want to update.

11 Click Next.

The Mapping page for the next CI type appears. For example, if you had selected Computer system and Disk drive to be transferred to BMC Atrium CMDB, the Disk drive Mapping page appears. If you selected only one CI, the Schedule page appears.

� To map target attributes to source columns for database tables or views

1 In the Mapping page, specify whether your source data is in a table or a view.

The columns from the source table are displayed in the Source Column Name list box.

Figure 4-8: Mapping page of the Integration Job Builder wizard for database tables

2 Select the Schema and Table name for the source data.



3 Follow step 2 on page 70 to step 11 on page 73 to map target attributes to source columns.

Defining relationship mapping for the CI types to transfer

How you define the relationship between the CI types that you are transferring to BMC Atrium CMDB depends on whether the relationship data in your source tables is class-based or stored in an external table. If your relationship source is CI class, follow the steps in “Defining relationship mapping based on attributes in CI classes” on page 74. If your relationship source is an external data store, follow the steps in“Defining relationship mapping with an external data store as the source” on page 75.

Defining relationship mapping based on attributes in CI classes

If your relationship data is stored within your source CI tables, you can follow the example in “Source data organization at Calbro Services” on page 28. You would have defined a 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 vm2-w4-dev01 in the Computer table. You also would have defined a 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 create a 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 parent member of the relationship and another CI class as the child member of the relationship. In this case, BMC_ComputerSystem is the source (parent) member and BMC_DiskDrive is the destination (child) member of the BMC_HostedSystemComponents relationship class. For more information about relationship classes, see the BMC Atrium Core 7.6.04 Concepts and Planning Guide.



74 User’s Guide


� To define relationship mapping with CI classes as the source

1 In the Relationship Mappings page, leave the default selection which says that the relationship data is contained within the source columns of the two CIs.

Figure 4-9: Relationship Mapping page of the Integration Job Builder wizard–CI classes as source

The source key that you specified for the parent CI (SerialNumber for Computer system in the example) is displayed in the first column.

2 From the child CI column, select the column that contains the information that associates the child CI with the parent CI.

In the sample Calbro scenario (“Creating a data transfer job” on page 32), the Computer system Key Column displays SerialNumber (the source key for computer system). From the Disk drive Columns, the Calbro administrator selects the AssociatedComputer column, which maps a disk drive to appropriate computer system.

3 Click Next.

The Relationship Mapping page appears.

Defining relationship mapping with an external data store as the source

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.



Figure 4-10 and Figure 4-11 on page 77 present an example of mapping in two stages based on relationship data stored in an external data store.

Figure 4-10: Stage 1 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.

76 User’s Guide


Figure 4-11: Stage 2 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.



� To define relationship mapping with external data store as the source

1 In the Relationship Mappings page, select the button whose label says that the key columns of the CIs are related using columns in an external table.

Figure 4-12: Relationship Mapping page of the Integration Job Builder wizard–external data store as source

2 Specify the schema and name of the external table containing the relationship information.

3 For the parent CI, the source key is displayed in the left column. In the Association Table Columns, select the column from the external table that maps to the source key.

4 For the child CI, the source key is displayed in the left column. In the Association Table Columns, select the column from the external table that maps to the source key.

5 Click the Transformation Options tab and specify the delta options.

6 Click Next.

The Schedule page appears.

78 User’s Guide


Creating a job schedule

� To create a schedule for the job

1 On the Schedule page, select Enable.

Figure 4-13: Schedule page of the Integration Job Builder wizard

2 Enter the time (BMC Remedy AR System server time) at which you want the job to first run.

3 Enter the interval in days, hours, or minutes at which you want the job to run.

The interval is the time to wait after one job is completed before starting the next one. Any changes made to a job are implemented at the next scheduled interval.

4 Click Next.

The Summary page appears.

Best practice

When you run reconciliation jobs, make sure that you do not run the reconciliation jobs and Atrium Integrator jobs at the same time, because the reconciliation jobs and Atrium Integrator jobs could query or update the same data.





Figure 4-14: Summary page of the Integration Job Builder wizard

Viewing the job summary

� To view the job summary

1 In the Summary page, verify the CI types and relationships that you have selected. If you need to make any changes, click Back.

If you make changes that have dependencies, you must go page by page and update your selections. For example, if you change the CI type to transfer, you must update the CI type relationships, the mapping between key source columns and target columns, and relationship mapping.

2 Click Finish.

A list of the transformations created for your job is displayed.

3 Click OK.

A job is created and saved in the Spoon repository. If an error occurred while creating your job, an error message is displayed.



80 User’s Guide

Creating a complex job in Spoon

Best practice

For security reasons, keep the repository password secure and encrypted. Back up the repository database frequently.

Creating a complex job in SpoonYou can use Spoon to import and export data from inputs like LDAP, AR forms, ITSM forms, and those requiring complex staging tasks or complex data manipulations. BMC provides several sample jobs that you can use as a starting point.

� To customize a sample job or transformation

1 On the computer where you have the Spoon client installed, click Start > Programs > BMC Software > Atrium Integrator > BMC Atrium Integrator Spoon.



2 Login as follows:



c In the Password field, enter admin.

d Click OK.




The Repository explorer dialog box shows the sample jobs in the Jobs/BMC SAMPLES directory and the sample transformations in the Transformations/BMC SAMPLES directory.

4 Double-click a sample job or transformation.

5 Choose File > Save as.

6 In the properties window, enter a name for the job or transformation and then click OK.

The sample job or transformation is saved with the name that you specify.

7 Edit the job or transformation as needed.

For more information about creating a job in Spoon, see the Spoon User Guide at http://wiki.pentaho.com/display/EAI/Spoon+User+Guide.

Best practices

� Use a naming convention for jobs and transformations that makes them easy to identify. Use the same name prefix to identify related jobs and transformations.

� After you verify that a job is working in production, save the job in the Kettle repository so that you can monitor and schedule it in the Atrium Integrator console.

� Add notes to your jobs and transformations to keep track of complex flows and functionality. To add a note, right-click the canvas and select New note.

� Use variables for file paths or computer-specific connection information so that file paths and so forth can be determined dynamically instead of statically.

Creating a job to migrate data from a development server to a production server

You can create a job in Spoon to migrate data from the BMC Atrium CMDB on your development server to the BMC Atrium CMDB on your production server.

� To create a migration job

1 Follow step 1 through step 3 on page 82 to log in to the default Spoon repository.

2 In the Spoon window, choose File > New > Transformation.

3 In the navigation panel, click Input.

4 Click CMDBInput and drag it to the canvas.

5 Double-click the CMDBInput step.

In the Connection field of the CMDBInput dialog box, do one of the following.

� Select a connection to the BMC Atrium CMDB on your development server.

� Create a new connection to the BMC Atrium CMDB on your development server by following the steps below.

82 User’s Guide

Creating a complex job in Spoon

a Click New.

b In the Server Name field of the Database Connection dialog box, type the name of your BMC Remedy AR System server.

c (optional) Type the port number.

d (optional) In the RPC Program Number field, type the RPC port if you use one.

NOTE You cannot specify a private RPC port for data transfers into BMC Atrium CMDB. You must use the ports defined by BMC Atrium CMDB. For more information about the RPC ports defined by BMC Atrium CMDB, see RPC Ports in BMC Atrium CMDB (page 58).

e Type the user ID and password to log in to BMC Atrium CMDB.

f Click Test to validate the connection.

g Click OK.

6 In the Class Name field, click Browse to select the BMC Atrium CMDB class from which you want to migrate data.

7 The NameSpace field displays the namespace for the selected class.

8 In the Dataset Id field, select the dataset from which you want to migrate data.

9 Click OK.

10 From the Output menu in the navigation panel, click the CMDBOutput step and drag it to the canvas.

11 Repeat step 5 to step 8 on page 83 to create a connection to the BMC Atrium CMDB on your server through the CMDBOutput step.

12 In the key look up area, select InstanceId in the Table field column and type InstanceId in the Stream field 1 column.

This mapping enables you to keep the same Instance Ids as you transfer data from the BMC Atrium CMDB on your development server to the BMC Atrium CMDB on your production server.

13 Create a hop from the CMDBInput step to the CMDBOutput step. For information on creating a hop, see “Connecting transformation steps or job entries in Spoon” on page 88.


15 In the Transformation Properties dialog box, specify a name for the transformation.

16 Click OK.

You can run this transformation in Spoon. However, you must envelop this transformation in a job to be able to monitor and run it from the Atrium Integrator console.

17 Choose File > New > Job.



18 From the General menu in the navigation panel, select the Start step and drag it to the canvas.

19 Click and drag the Transformation step to the canvas.

20 Double-click the Transformation step.

21 In the Name of transformation field, click to select the transformation you had created in step step 15 on page 83.

22 Click OK.


24 In the Job Properties dialog box, specify a name for the job.

25 Click OK.

The job is now displayed in the Atrium Integrator console.

84 User’s Guide

Chapter

5
Editing jobs and transformations
After you create your job with the Integration Job Builder wizard, you can edit it in the Spoon application.

Best practice

BMC recommends that you validate and clean up your source data before transferring it to BMC Atrium CMDB.


� Opening your job or transformation (page 86)� Mapping the Integration Job Builder wizard output to Spoon steps (page 87)� Connecting transformation steps or job entries in Spoon (page 88)� Adding intermediate steps to a job (page 90)� Adding intermediate steps to a transformation (page 93)� Editing transformation steps (page 97)� Editing transformation properties (page 98)� Launching several copies of a step (page 100)� Changing data mappings (page 101)� Exploring a database connection (page 101)� Browsing source data (page 102)� Changing source configuration (page 103)




Opening your job or transformationAfter you create your job through the Integration Job Builder wizard, you need to open it in Spoon to make edits.

1 On the computer where you have the Spoon client installed, click Start > Programs > BMC Software > Atrium Integrator > BMC Atrium Integrator Spoon.



2 Login as follows:



c In the Password field, enter admin.

d Click OK.


The Repository explorer dialog box shows all the jobs and transformations in the NGIEREPD repository.

86 User’s Guide

Mapping the Integration Job Builder wizard output to Spoon steps

Figure 5-2: Repository explorer window with sample jobs and transformations

Mapping the Integration Job Builder wizard output to Spoon steps

This section describes how each page in the Integration Job Builder wizard maps to Spoon steps. This will help you understand what steps you should edit in Spoon.

Table 5-1: Mapping the Integration Job Builder wizard output to Spoon steps (Sheet 1 of 2)

Wizard page Corresponding Spoon step

General—Job Name Name of job_CI being transferredGeneral—Data Store details for SourceTo create a source data store, go to the Manage Data Stores—New Data Store page.

Input step

General—Data Store details for TargetTo create a target data store, go to the Manage Data Stores—New Data Store page.

Output > CMDBOutput step

CI Type Selection CMDBOutput.ClassName field

Relationships Selection CMDBOutput.ClassName field

CI Mapping CMDBOutput

Data mapping CMDBOutput (table section)



Connecting transformation steps or job entries in Spoon

In Spoon, a hop connects one transformation step or job entry with another in the Spoon application.

A transformation hop defines the direction of the data flow.

Figure 5-3: Transformation hop

A job hop defines the job execution order and the condition on which the next job entry is to be executed.

Figure 5-4: Job hop

Creating a hopYou can create a hop between steps in a transformation or between jobs.

� To create a hop

1 In Spoon, open the job or transformation to which you want to add a hop.

2 Select the first step.

Key mapping CMDBOutput (key section)

Relationship Mapping CMDBLookUp

Configuration and Logging options Set variables

Table 5-1: Mapping the Integration Job Builder wizard output to Spoon steps (Sheet 2 of 2)

Wizard page Corresponding Spoon step

88 User’s Guide

Connecting transformation steps or job entries in Spoon

3 Perform one of the following actions:

� Press the Shift key and draw a line to the second step.

� Press the Control key and select the second step, and then press the right mouse button and select New hop.

The steps are connected by a hop. The hop arrow indicates the direction of the data flow.

Reversing the direction of a hopYou can change the direction of the data flow by reversing the direction of the hop.

� To flip a hop

Right-click a hop and select Flip direction.

The direction of the hop is reversed.

Disabling a hopYou can disable a hop for testing purposes.

� To disable a hop

Right-click on a hop and select Disable hop.

NOTE The Disable hop command appears only when you right-click on an active hop.

The hop is disabled and its color changes to gray.

Deleting a hop

� To delete a hop

Right-click a hop and select Delete hop.

The hop is deleted.

Specifying the condition on which a job entry is executedYou can specify the condition on which the next job entry is to be executed by specifying an evaluation mode for the hop that goes to that job entry.

� To specify the evaluation mode

1 Right-click a job hop and select Evaluation.

2 Select one of the following commands:



� Unconditional specifies that the next job entry must be executed regardless of the result of the originating job entry. An unconditional job hop uses the icon.

� Follow when result is true specifies that the next job entry is to be executed when the result of the originating job entry is true. This job hop uses the icon.

� Follow when result is false specifies that the next job entry is to be executed when the result of the originating job entry is false. This job hop uses the icon.

Transformation hop colorsTransformation hops are displayed in a variety of colors based on the properties and state of the hop, as described in Table 5-2.

Table 5-2: Hop line colors

Adding intermediate steps to a jobYou can add intermediate steps to a job that you create through the Integration Job Builder wizard, or to a custom job you create through the Spoon application.

� To add an intermediate step to a job

1 Click the step you want to add and drag it to the canvas.

Table 5-3 lists the common steps you can add to your job to manipulate the data before adding it to BMC Atrium CMDB.

Hop color Description

Black The hop has a defined target step. Gray The hop is disabled. Green If multiple hops are leaving a step, rows of data are evenly

distributed to all target steps.Red If multiple hops are leaving a step, all rows of data are

copied to all target steps. Yellow Provides information about the step and distributes rows.Magenta Provides information about the step and copies rows.Red dot line The hop carries rows that caused errors in source steps.

90 User’s Guide

Adding intermediate steps to a job

For information about additional steps that you can add to your job, see the Spoon User Guide at http://wiki.pentaho.com/display/EAI/Spoon+User+Guide.

Table 5-3: Intermediate steps for jobs (Sheet 1 of 3)

Option What it helps you do

General menu

Start Starts a job.

Dummy Adds a dummy step to enable you to test your job. The dummy step does not perform any evaluation.

Abort job Aborts the specified job.

Display Msgbox Info Displays a message box in the job to enable you to see where you are in the process.

Job Executes a previously defined job.

Ping a host Pings a host machine using the ICMP protocol.

Success Clears an error state found in a job and forces it to the success state.

Transformation Executes a previously defined transformation.

Truncate tables Truncates one or several tables.

Write to Log Writes a specific string to the PDI logging system.

Mail menu

Get mails from POP Retrieves emails from a POP server and store them into one or more files.

Mail Sends a text or HTML e-mail with optional file attachments.

File management menu

Add filenames to result

Adds a set of files or folders to the result list of the job entry. This list of filenames can then be used in the various job entries all around.

Compare folders Compares two folders to check if their content is identical.

Copy files Copies one of more files or folders.

Copy or Move result filenames

Copies or moves all the filenames that are in the result files list of the last job entry.

Create a folder Creates a folder at the specified location.

Create file Create an empty file at the specified location. This is useful for creating trigger files from within jobs.

Delete file Deletes the specified file.

Delete filenames from result

Delete all the filenames that are in the result files list of the last job entry.

Delete files Deletes a set of files.

Delete folders Deletes one or more folders and all the content in them.

File Compare Compares the contents of two files and controls the flow of the job by it. When the contents of the files are the same, the success outgoing hop is followed; otherwise, the failure hop is followed.

HTTP Gets a file from a web server using the HTTP protocol.



Move Files Moves a number of files and, folders, or both to alternate locations on your file system.

Unzip file Unzips one or more files.

Wait for file Waits for a file. This job entry sleeps and periodically checks whether the specified file exists, after which the flow continues. The job entry can either wait indefinitely for the file or it can time out after a certain time.

Zip file Creates a standard ZIP archive using the options that you specify.

Conditions menu

Check if a folder is empty

Verifies if a folder is empty (contains no files).

Check if file exists Verifies if a certain file exists on the server on which Kettle runs.

Columns exist in a table

Verifies that one or more columns exist in a database table.

Evaluate rows number in a table

Define the success condition that can be evaluated. The job process can be branched by the result of this step.For the success condition, you can check the number of rows if they are:� Equal to� Different from� Smaller than� Smaller or equal to� Greater than� Greater or equal to

File Exists Verify if the specified file exists on the server on which Kettle runs.

Simple evaluation Evaluates contents of a variable or a field in the result stream. You can connect two steps with the output of the Simple Evaluation. The green connection is used to indicate success, the red one to indicate failure.

Table exists Verifies if the specified table exists on a database.

Wait for Wait for the specified time before running the next job entry.

Scripting menu

JavaScript Executes a JavaScript script.

SQL Executes an SQL script.

Shell Executes a shell script on the host where the job is running.

Bulk loading menu

BulkLoad from Mysql into file

Loads data from a MySQL table to a text file.

BulkLoad into MSSQL Loads data from a text file into a Microsoft SQL Server table.

BulkLoad into Mysql Loads data from a text file into a MySQL table.



92 User’s Guide

Adding intermediate steps to a transformation

Adding intermediate steps to a transformationYou can add intermediate steps to a transformation in a job that you create through the Integration Job Builder wizard, or to a custom job you create through the Spoon application.

� To add an intermediate step to a transformation

1 Click the step you want to add and drag it to the canvas.

Table lists the common steps that you can add to your transformation to manipulate the data before adding it to BMC Atrium CMDB.

XML menu

Check if XML is well formed

Verifies that one or more files contain well formed (allowed) XML content.

DTD Validator Verifies that an XML file corresponds to a certain structure or format.

XSD Validator Validates the specified XML file against the specified XML Schema Definition (XSD) file.

XSL Transformation Transforms the specified XML file into another document.

File transfer menu

Get a file with FTP Gets one or more files from an FTP server.

Get a file with SFTP Gets one or more files from an FTP server using the Secure FTP protocol.

Put a file with FTP Puts one or more files on an FTP server.

Put a file with SFTP Puts one or more files on an FTP server using the Secure FTP protocol.

Repository menu

Check if connected to repository

Checks whether you are connected to the repository.





For information about additional steps that you can add to your transformation, see the Spoon User Guide at http://wiki.pentaho.com/display/EAI/Spoon+User+Guide.

Table 5-4: Intermediate steps for transformations (Sheet 1 of 4)

Step What it helps you do

Transform menu

Add constants Adds constant values to the specified field in the destination data source. For example, Calbro Services can add Disk drive as the Short Description value when transferring disc drive information from their SQL table to the BMC_Disc Drive CI class.

Calculator Provides you with predefined functions that can be executed on input field values. For example, Calbro Services can calculate the total cost of the computer systems in all their sites and add that information to BMC Atrium CMDB.

Replace in string

Replaces the text string in a field with the specified value.

Row flattener Allows you to flatten data sequentially.

Row normalizer

Normalizes data from pivoted tables.

Split fields Splits fields based on delimiter information.For example, Calbro Services can split the domain name for their computer systems from adprod.calbro.com to just adprod before adding this information to BMC Atrium CMDB.

String cut Returns the substring of characters in a string starting at a specified position up to an optional end position.

Unique rows Removes duplicate rows from the input streams. Ensure that the input stream is sorted otherwise, only consecutive double rows are evaluated correctly.

Value mapper Maps string values from one value to another. Mapping is usually solved by storing the conversion table in a database. The Value mapper provides you with a simple alternative.For example, Calbro Services can map 1 to Intel PC, 2 to HP laptop, 3 to Dell PC, and so on.

Utility menu

Delay row Delays each input row by the specified period before proceeding to the next step.

Execute a process

Executes a shell script on the host where the job is running.For example, Calbro Services can run the perl.exe file passing the Site value from the source database as a parameter to indicate the location of each computer system.

94 User’s Guide

Adding intermediate steps to a transformation

If field value is null

Replaces null values by one of the following methods:� Processing the complete row with all fields� Processing the complete row but only for specific field types (Number,

String, Date, and so on.)� Processing the complete row but only for specific fields by nameFor example, after Calbro Services transfers data from source tables to BMC Atrium CMDB, they might decide to overwrite null values in the target database (BMC Atrium CMDB) on subsequent runs in one of the preceding ways.

Null if Sets the value of a field to null if its string representation is equal to the specified value.For example, Calbro Services might not be interested in tracking computer systems with a Macintosh operating system, and might decide to replace the field value “Mac” with null.

Process files Copies, moves, or deletes files by providing the source and target file names in the data stream.

Write to log Writes job and transformation details to a log file, and saves the log file in the following directory:C:\Documents and Settings\Administrator\Local Settings\Temp\

Flow menu

Abort Aborts a transformation upon seeing input. The main use of this step is in error handling. For example, you can use this step so that a transformation can be aborted after a specified number of rows flow to an error hop.

Append streams

Reads the data from two steps, processing the second stream only after the first is finished.The row layout for the input data coming from both steps has to be identical: the same row lengths, the same data types, the same fields at the same field indexes in the row.

Blocking step Blocks all output until the very last row is received from the previous step. At that point, the last row is sent to the next step or the complete input is sent to the next step. You can use the Blocking step for triggering plugins, stored procedures, JavaScript scripts, or for synchronization purposes.

Dummy Adds a placeholder (dummy) step for testing purposes. For example, to have a transformation, you need at least two steps connected to each other. If you want to test a file input step, you can connect it to a dummy step.

Filter rows Allows you to filter rows based on conditions and comparisons. After this step is connected to a previous step, you can click on the "<field>", "=" and "<value>" areas to construct a condition.

Switch/Case Implements the Switch/Case statement found in popular programming languages like Java. Pentaho routes rows of data to one or more target steps based on the value encountered in a certain field.





Scripting menu

Execute SQL script

Executes an SQL script either once during the initialization phase of the transformation, or once for every input row that the step is given. The second option can be used to use parameters in SQL scripts.For example, Calbro Services can execute an SQL script which returns category IDs from the categories table where the name equals the value obtained for the Category field.

Formula Calculates formula expressions within a data stream.

Modified Java Script Value

Provides an expression-based user interface for building JavaScript expressions. Allows you to create multiple scripts for each step.For example, Calbro Services can create an if/then/else statement to identify the operating system of a computer based on its serial number. The script can also include the concatenate function, which creates a work group by appending the virtual machine type to the operating system.

Regex Evaluation

Allows you to validate an input field against a regular expression. A regular expression is a special text string for describing a search pattern. For example, the regular expression for finding all text files in a file manager is .*\.txt.

User defined Java expression

Uses the specified Java expressions as a basis for calculating new values.

Lookup menu

Call DB Procedure

Allows you to execute a database procedure (or function) and direct the result to the output step.

CMDBLookUp Allows you to look up values in the BMC Atrium CMDB based on the primary key that you specified. Lookup values are added as new fields onto the stream.

Database lookup

Looks up values in a database table. Lookup values are added as new fields onto the stream.

File exists Verifies the existence of a file where the filename comes from previous steps. The result is a Boolean flag field that gets added to the input fields in the output.

Web services lookup

Performs a web services lookup using the Web Services Description Language (WSDL).

Validation menu

Data Validator Allows you to define simple rules to describe what the data in a field should look like. This can be a value range, a distinct list of values, or data lengths.

Mail Validator Checks if an email address is valid.

XSD Validator Performs an XML Schema Definition (XSD) validation against data in a file or in an input field.

Statistics menu

Group by Calculate values over a defined group of fields.



96 User’s Guide

Editing transformation steps

Editing transformation stepsYou can right-click on any step in your transformation and perform the actions described in Table 5-5.

Job menu

Get Variables Allows you to get the value of a variable. This step can return rows or add values to input rows.

Set Variables Allows you to set variables in a job or in the virtual machine. It accepts one (and only one) row of data to set the value of a variable.



Table 5-5: Right-click options for transformation steps

Menu option What it helps you do

Edit step Opens the selected step so that you can edit it.

Edit step description Opens the Step description dialog box so that you can edit the description.

Data movement Allows you to specify whether you want the selected step to copy all output rows to all target steps, or to distribute the rows among the target steps.

Change number of copies to start from

Allows you to launch the selected step multiple times. For a database lookup step, this might improve performance by reducing latency.For more information, see “Launching several copies of a step” on page 100.

Copy to clipboard Copies the selected step to the clipboard so that you can use it again in the same transformation or a new transformation.

Duplicate step Creates a duplicate of the selected step.

Delete step Deletes the selected step.

Hide step Hides the selected step.

Detach step Deletes the hops to the selected step.

Show input fields Determines all the fields and their origin by tracing the input streams back to their source.

Show output fields Determines all the fields and their origin by tracing the output streams back to their source.

Align/Distribute Splits the transformation flow to multiple processing paths.

Check selected step Checks the selected step and displays any warnings and errors.

Define error handling

Allows you to configure a step so that instead of halting a transformation when an error occurs, the rows that caused an error are passed to a different step.

Preview Displays a list of all the steps in the current transformation.



Editing transformation propertiesTransformation settings are the collection of properties that describe the transformation and configure its behavior.

� To edit transformation properties

1 In the Spoon window, open the transformation that you want to edit is open.

2 Choose Transformation > Settings.

The Transformation Properties window appears.

Figure 5-5: Transformation Properties window in Spoon

3 In the Transformation tab, edit the Transformation name, Transformation filename, Description, and Extended description as required.

4 Specify the Status, Version, and Directory of the transformation.

The Created by and Created at fields display the user name of the person who created the transformation in the Integration Builder wizard and the date and time at which it was created.

The Last modified by and Last modified at fields display the user name of the person who is editing the transformation and the date and time it was last modified.

5 Click the Logging tab.

98 User’s Guide

Editing transformation properties

6 Specify the following information:

7 Specify the log connection to write to the log table.

8 Specify the name of the log table.

9 Select the Batch-ID check box if you want to have a batch ID in the log table.

10 Select the Use logfield to store logging in check box if you want to store the logging text in the logging table.

This enables you to have the logging text and the run results in the same table.

11 In the Transformation Properties window, click the Dates tab.

12 Specify the date setting.

13 Click the Dependencies tab.

14 Enter the dependencies for the transformation. For example, if a dimension depends on three lookup tables, make sure that the lookup tables have not changed. If the values in these lookup tables have changed, extend the date range to force a full refresh of the dimension. Dependencies allow you to determine if a table has changed when you have a "data last changed" column in the table. Click Get dependencies to detect dependencies automatically.

15 Click the Miscellaneous tab.

16 In the Number of rows in rowsets field, change the size of the buffers between the connected steps in a transformation. Do not change this parameter unless you are running low on memory, for example.

17 Select the Show a feedback row in transformation steps checkbox if you want to add a feedback entry into the log file while the transformation is being executed. By default, this feature is enabled and configured to display a feedback record every 5000 rows.

18 In the Feedback size field, enter the number of rows to process before entering a feedback entry into the log.

TIP Set this to a higher value when processing large amounts of data to reduce the amount of information in the log file.

Field Name What to specify

Read log step Number of lines from the source step to write to the log table.

Input log step Number of lines from the input file or database to write to the log table.

Write log step Number of lines from the target step to write to the log table.

Output log step Number of output lines from this step to write to the log table.

Update log step Number of lines updated in the file or database to write to the log table.

Rejected log step Number of lines rejected from this step to write to the log table.



19 Select the Make the transformation database transactional checkbox if you want to open one unique connection per defined and used database connection in the transformation. Enabling this option is required to allow a failing transformation to be rolled back completely. Enabling this option is also necessary when trying to alter connection settings before a query using an Execute SQL script step.

20 In the Shared objects field, specify the location of the XML file used to store shared objects like database connections or clustering schemas.

21 Select the Manage thread priorities check box if you want to enable the internal logic for changing the Java thread priorities based on the number of input and output rows in the rowset buffers. This can be useful in some situations where the cost of using the logic exceeds the benefit of the thread prioritization.

22 Click the Partitioning tab.The available database partitions are displayed.

23 Click the New button to create a new partition.

24 Click the Monitoring tab.

25 Select the Enable step performance monitoring check box if you want to monitor each step of the transformation as it is being executed.

26 Click the SQL button to generate the SQL code necessary for creating the logging table. The Simple SQL Editor appears, which allows you to execute an SQL statement against the logging connection.

27 Click OK.

The selected transformation is updated according to the options that you set.

Launching several copies of a stepIn certain situations, launching multiple copies of a step improves performance. For example, if a step uses a large amount of CPU (such as a JavaScript step) and you have multiple processor cores in your computer, launching multiple copies of the step might improve performance. If a step has to deal with network latencies (such as a database lookup step), launching the same step several times keeps the database busy on different connections, which lowers the latency.

� To launch several copies of a step

1 Right-click on the step that you want to launch multiple times, and select Change number of copies to start.

The Nr of copies of step dialog box appears.

2 Enter the number of times you want to launch this step, and click OK.

The number of steps appears in the upper-left corner of the step icon.

Figure 5-6 on page 101 shows how Spoon indicates that a step has been launched multiple times.

100 User’s Guide

Changing data mappings

Figure 5-6: Launching several copies of a step

Changing data mappingsA data mapping defines how data in the source corresponds to data in the target and which actions to take when transferring between them. When you created a job in the Integration Job Builder wizard, you mapped key source columns to corresponding target columns. In Spoon, you can change the data mapping–for example, add a new attribute to import to BMC Atrium CMDB.

� To change data mapping

1 Open your transformation in Spoon. For more information, see “Opening your job or transformation” on page 86.

2 Double-click the CMDBOutput step.

The CMDBOutput dialog box appears.

3 In the Update fields section, click in the Table field cell and select the target attribute that you want to map.

4 In the Stream field cell, select the source field you want to map to the selected attribute.

5 In the Update cell, select Y.

6 Click OK.

The selected attribute is mapped to the specified source column.

Exploring a database connectionYou can explore configured database connections in Spoon.

� To explore a database connection


2 Click .

Indicates that this step was launched 3 times



The Make your selection dialog box appears.

3 Select the database connection that you want to explore, and click OK.

The Database explorer dialog box appears with a list of all the schemas, tables, and views in the selected connection.

4 Select the table that you want to explore.The buttons to the right provide quick access the following features for the selected table:

Browsing source dataIn Spoon, you can browse the source data before running your job or transformation.

� To browse source data


2 Double-click the input step.

The input step dialog box appears.

3 Click Preview.

The Enter preview size dialog box appears.

4 Enter the number of rows of source data that you want to preview.

The Examine preview data dialog box appears with the specified number of rows of data from the source table or file.

Button What it does

Preview first 100 rows Returns the first 100 rows from the selected table.

Preview first ... rows of... Allows you to specify the number of rows to return from the selected table.

Number of rows. Returns the total number of rows that the selected table contains.

Show Layout Displays a list of column names, data types, and so on from the selected table.

Generate DDL Generates the DDL to create the selected table based on the current connection type.

Generate DDL for other connection

Prompts you to select another connection, then generates the DDL to create the selected table based on the selected connection type.

Open SQL Launches the Simple SQL Editor for the selected table.

Truncate table Generates a TRUNCATE table statement for the current table.

102 User’s Guide

Changing source configuration

5 Click Show log to view the log file.

6 Click Close when you have finished previewing the data.

Changing source configurationYou can manipulate your source data in Spoon before transferring it to BMC Atrium CMDB. For example, you can limit the number of records to be transferred on an initial run. This is very useful for initial verification before bulk-loading data into BMC Atrium CMDB. You can also write an SQL query to limit the data to be processed rather than processing all the data from the source table.

� Limit number of rows for initial processing




3 In the Limit size field, enter the number of records to import to BMC Atrium CMDB.

4 Click OK.

When you run the transformation, only the specified number of records from the source table are transferred to BMC Atrium CMDB.

� Importing a subset of the data




3 Click Get SQL select statement.

4 Type an appropriate query.

5 Click OK.

When you run the transformation, records from the source table are transferred to BMC Atrium CMDB depending on the query you specified.



104 User’s Guide

Chapter

6
Running and monitoring a job
If you created your job through the Integration Job Builder wizard, you can run it from the Atrium Integrator console. If you created or edited your job in the Spoon application, you can run it in Spoon.


� Running a job from the Atrium Integrator console (page 106)� Running a job in Spoon (page 106)� Monitoring jobs (page 108)� Changing the job schedule (page 112)




Running a job from the Atrium Integrator console

If you created your job using the Integration Job Builder wizard, you can run your job from the Atrium Integrator console. Ensure that the Carte server is running before running a job from the Atrium Integrator console. For more information, see Chapter 7, “Debugging and troubleshooting jobs.”.

� To run a job

1 In the Atrium Integrator console, select the job that you want to run from the job list on the left panel.

2 Click Start Job .

The selected job begins to be executed in the Pentaho Carte server. The History tab displays the job status as it runs.

� To stop a job

1 In the Atrium Integrator console, select the job that you want to stop from the job list on the left panel.

2 Click Stop Job .

The selected job stops running.

Running a job in SpoonIf you edited or created your job in Spoon, you can run it in Spoon as well.

� To run a job in Spoon

1 Open your job.

For more information, see “Opening your job or transformation” on page 86.

2 Click Run .

The Execute a transformation window appears, as shown in Figure 6-1 on page 107.

106 User’s GuideBMC Software Inc., Confidential

Running a job in Spoon

Figure 6-1: Running a job in Spoon

3 Specify whether you want to run the job locally or remotely. If you want to run the job remotely, specify the remote host.

4 Specify logging details.

As a best practise, BMC recommends that you set this to Rowlevel so that it is easy to track down errors.

5 Click Launch.

The job begins running, and the details are splayed in the Executing Results section of the Spoon window.



Monitoring jobsYou can view the job details in the Atrium Integrator console.

Figure 6-2: Atrium Integrator console

All jobs in the repository are displayed in the job catalog in the left side of the window, where you can sort the jobs by name. The right side of the window displays the job information and run history of the selected job.

You can also view job details on the Carte server. For information on how to run the Carte server, see Chapter 7, “Debugging and troubleshooting jobs.”

Viewing job historyYou can view the job history and logging details for a selected job.

� To view job history and details

1 Select a job from the job catalog on the left panel.

The History tab displays the following information for the job selected in the job catalog (left side of the window):

� Name—Job name

� Status—Running , Completed , or Failed

2 Click next to the job name to display the job run details. The Job Run Details area displays the following information:

� Batch Id

� Start time—Job start time


Monitoring jobs

� Status—Job status

� End time—Job end time

� Total Input Records—Number of records in the source data

� Total Output Records

� Number of Records Read

� Number of Records Written—Number of records written to BMC Atrium CMDB

� Number of errors—Number of errors in the job run

� Number of Records Updated—Number of records updated in the BMC Atrium CMDB

� To view logging details


2 Click the Logging Details bar to display log details.

Figure 6-3: Logging Details in the Atrium Integrator console

3 In the Logging Details area, click View Log Details .

The log file appears.

View Log Details button



Figure 6-4: Log file in the Atrium Integrator console

4 Click Export to File.

5 Specify the file name and path for the log file.

6 Click Save.

The log file is saved.

Viewing job detailsYou can view the details of a selected job.

� To view job details


2 Click the Integration Job Details tab.


Monitoring jobs

Figure 6-5: Integration Job Details area

The Integration Job Details area displays the following information for the selected job:

� Job Id and Job Name

� Created By—User name of the person who created the job

� Create Date—Date on which the job was created

� Modified By—User name of the person who modified the job

� Modified Date—Date on which the job was modified

� Source Type—Source data store for the job

� Target Type—Target data store to which data is to be transferred (BMC Atrium CMDB)

� Directory—Location where the job is saved in the repository

� Job Description—Description that was entered in the Integration Job Builder wizard

� Job Schedule—Start time of the job, and interval between job runs.

The Job Schedules area displays information on whether the selected job has been scheduled to run at a specified interval.



Changing the job scheduleYou can specify the schedule for a job while designing it through the wizard, and later edit the schedule from the Atrium Integrator console, if required.

� To edit a job schedule

1 In the Atrium Integrator console, click Manage Job Schedule .

The Job Schedule window appears with the job name and directory displayed.

2 Edit the start time and interval, as required.

3 Click Save.


Chapter

7
Debugging and troubleshooting jobs
This section describes the steps that you can take to debug and troubleshoot errors that might occur when you execute a data transfer job.


� Troubleshooting Atrium Integrator console issues (page 114)� Troubleshooting errors displayed in Spoon (page 118)� Location of log files (page 118)� Error connecting to a Microsoft SQL Server database using Windows

Authentication in Spoon (page 119)� Atrium Integrator Error Messages (page 120)



Troubleshooting Atrium Integrator console issues

This section describes how you can troubleshoot some common Atrium Integrator console issues.

Job fails to run If the Job Name in the left side of the Atrium Integrator console is in red and has a

next to it, the job failed to run.

� To troubleshoot a job that failed to run

1 In the Atrium Integrator console, select the failed job.

2 In the History tab, click next to the last run of the failed job.

3 Click Logging details (below the Job Run Details area).

Figure 7-1: Logging Details in the Atrium Integrator console

4 In the Logging Details area, click View Log Details .

The log file appears.

View Log Details button

114 User’s Guide


Figure 7-2: Log file in the Atrium Integrator console

5 Click Export to File and save the log file to the desired location.

6 If the log file does not contain enough information for you to debug the error, open the job in Spoon. For information on opening a job in Spoon, see Chapter 5, “Editing jobs and transformations.”

7 Click Run .

8 In the Execute a job dialog box, change Log level to Rowlevel (very detailed).

9 Click Launch to run the job.

10 After the job completes running, follow the steps in “Troubleshooting errors displayed in Spoon” on page 118.

Job not displayed on the Atrium Integrator consoleIf a job was created successfully through the Integration Job Builder wizard but does not appear on the Atrium Integrator console, consider the following possible causes:

� The CMDB plugin might not be available on the server on which you installed the Spoon application.

� Some .jar files might be missing.

� To troubleshoot Atrium Integrator console issues

1 Open the following file:

AtriumCoreInstallationDirectory\cmdb\plugins\shared\pluginsvr_config.xml

NOTE If the pluginsvr_config.xml file does not exist at this location, you may need to reinstall Atrium Integrator. For more information, see the BMC Atrium Core 7.6.04 Installation Guide.

2 Ensure that the pluginsvr_config.xml file contains the following entry:

BMC.ARDBC.ATRIUM.NGIE



3 Ensure that all the .jar files listed in the BMC.ARDBC.ATRIUM.NGIE section exist at the specified locations.

Job not running from the Atrium Integrator consoleYou can run a job from the Atrium Integrator console only if the Carte server is running. When you install the Atrium Integrator server, Carte is automatically installed on the same computer, and runs in the background. However, if you restart the operating system, you might have to start the Carte server manually.

� To view the Carte server details

1 In the BMC Remedy User tool on the computer where you have installed the Atrium Integrator server, open the NGIE:Config form and click Search.

The repository and Carte details are displayed.

Figure 7-3: NGIE:Config form

2 The Dir Path field displays the location of the Carte.bat file.

� To verify that the Carte server is running by using the command line

1 In a command line window, navigate to the location of the JDK on your computer. For example:

C:\Program Files\Java\jdk1.6.0_12\bin

2 Type jps.

116 User’s Guide


The Carte server details are displayed.

� To verify that the Carte server is running by using a browser

1 In a browser window, type:

http://HostName:PortNumber

HostName is the host name of the computer where the Atrium Integrator server is installed, and PortNumber is the number displayed in the Port field of the NGIE:Config form.

2 Click Enter.

3 Log in using cluster for the user name and the password.

4 In the Status window, click Show status.

The status of the jobs and transformations that have been run from the Atrium Integrator console are displayed.

5 Click on a job to display the log details.

� To start the Carte server manually

1 In a command line window, navigate to the following directory:

AtriumIntegratorInstallationDirectory\server\data-integration\

2 Type Carte.bat HostName portNumber.

HostName is the host name of the computer where the Atrium Integrator server is installed, and PortNumber is the number displayed in the Port field of the NGIE:Config form. For example, you might type:

Carte.bat aus-idd-w28r2-vm1 20000

3 Click Enter.

The Carte server is started.



Troubleshooting errors displayed in SpoonWhen you run a job or transformation in Spoon, the Execution Results area in the Spoon window displays the results.

� To troubleshoot Spoon errors

1 In the Execution Results area, click Refresh to get the latest results.

Figure 7-4: Execution Results area in the Spoon window

2 Click the Logging tab.

3 Click Show error lines .

The job or transformation errors are displayed.

4 To get more information about the errors, double-click the Error logging step.

The text file output dialog box displays the location of the error file in the Filename field.

5 Open the specified file to see the error details.

Location of log filesIf you are running the Tomcat web server, the Atrium Integrator console log files are located in the following directory on the computer where you installed the mid tier:

C:\Program Files\Apache Software Foundation\Tomcat 6.0\logs\stdout_currentDate.log

The error files for each job or transformation that you run are located in the following directory:

AtriumIntegratorInstallationDirectory\server\data-integration\ngie\bin\error\jobName_transformationName_Error.txt

118 User’s Guide

Error connecting to a Microsoft SQL Server database using Windows Authentication in Spoon

Error connecting to a Microsoft SQL Server database using Windows Authentication in Spoon

On a 32-bit JVM, Windows Authentication when connecting to a Microsoft SQL Server in Spoon works properly. But, Windows Authentication displays an error on a 64-bit JVM. Use the following steps to fix the error.

1 Navigate to the following directory:

AtriumIntegratorInstallationDirectory\server\data-integration\libswt\win32

2 Rename the ntlmauth.dll file as ntlmauth_32.dll.

3 Navigate to the following URL:

http://sourceforge.net/projects/jtds/files/jtds/1.2.5/jtds-1.2.5-dist.zip/download

4 Download the jtds-1.2.5-dist.zip file and unzip it.

5 Copy the \jtds-1.2.5-dist\x64\SSO\ntlmauth.dll file to the AtriumIntegratorInstallationDirectory\server\data-integration\libswt\win32 directory.

6 Close the Spoon window.

7 Launch Spoon.

8 Open your job or transformation.

9 Double-click the table input step.

10 Click New (next to the Connection field).

11 In the Database Connection dialog box (General tab), specify appropriate values for the following fields:

� Connection Name

� Host Name

� Database Name

� Port Number

12 Click the Options tab.

13 In the Parameter column, enter domain and in the Value column, enter the domain of the database server.

14 Click Test to ensure that the database connection is valid.

15 Click OK.



Atrium Integrator Error MessagesThe following table lists the error number, message type, message text, description, and solution for errors that Atrium Integrator generates.

Table 7-1: Atrium Integrator error messages (Sheet 1 of 5)

Error number Message type Message, description, and solution

NGIE000001 Error Error retrieving DatasetIds for the selected target data store.Solution

Verify the BMC Remedy AR System server details specified in the target data store connection.

NGIE000002 Error Error retrieving CI Types for the selected target data store.Solution

Verify the BMC Remedy AR System server details specified in the target data store connection. Also confirm that one or more some target attributes have been mapped to the source column on the CI Mapping page of the Integration Job Builder wizard.

NGIE000003 Error Error retrieving CI Relationships for the selected CI Types.Solution

Verify the BMC Remedy AR System server details specified in the target data store connection. Also confirm that a relationship has been selected for the selected CIs on the CI TypeRelationships page of the Integration Job Builder wizard.

NGIE000004 Error Job Creation failed.Solution

Verify the data entered in the Integration Job Builder wizard pages and check your connection to the Pentaho server.

NGIE000005 Error Error retrieving CI attributes for the selected CI Type.Solution

Confirm connectivity to BMC Atrium CMDB by clicking the Test Connection button in the Manage Data Store tool. Also verify that the CI Class is defined correctly for the selected CI Type.

NGIE000006 Error Error retrieving Schemas for the source. Solution

Confirm connectivity to BMC Remedy AR System by clicking the Test Connection button in the Manage Data Store tool.

120 User’s Guide

Atrium Integrator Error Messages

NGIE000007 Error Error retrieving Tables for the schema. Solution

Confirm connectivity to BMC Remedy AR System by clicking the Test Connection button in the Manage Data Store tool. Also check whether the schema has any table defined.

NGIE000008 Error Error retrieving Views for the schema.Solution

Confirm connectivity to BMC Remedy AR System by clicking the Test Connection button in the Manage Data Store tool. Also check whether the schema has any view defined.

NGIE000009 Error Error retrieving Files for the source. Solution

Confirm connectivity to BMC Remedy AR System by clicking the Test Connection button in the Manage Data Store tool. Check whether an entry has been created in the NGIE: FileMetaData form.

NGIE000010 Error Error retrieving Columns for the source.Solution

Check your connection to the Pentaho server and verify that the table or view is defined correctly in the source database.

NGIE000011 Error No Columns available for the selected source.Solution

Confirm that the source database table has valid columns.

NGIE000012 Error Error retrieving fields from the selected file.Solution

Confirm connectivity to BMC Atrium CMDB by clicking the Test Connection button in the Manage Data Store tool. Check whether an entry has been created in the NGIE: FileMetaData form.

NGIE000101 Error Failed to connect to Atrium Integrator. Solution

Check your connection to the Pentaho server.





NGIE000102 Error Failed to get list of NGIE Jobs. Solution

Check the following:� Your connection to the Pentaho server.� The AtriumCoreInstallationDirectory\cmdb\plugins\shared\pluginsvr_config.xml file contains the following entry:BMC.ARDBC.ATRIUM.NGIE

� All the .jar files listed in the BMC.ARDBC.ATRIUM.NGIE section exist at the specified locations.

NGIE000103 Error Failed to delete NGIE job.Solution

Check your connection to Atrium Integrator. Also confirm that the Carte server is running.

NGIE000104 Error Failed to start NGIE job. Solution

Confirm that the Carte server is running.

NGIE000105 Error Failed to stop NGIE job. Solution

Check your connection to Atrium Integrator. Also confirm that the Carte server is running.

NGIE000106 Error Failed to get list of job runs. Solution

Check your connection to the Pentaho server. Also check whether there is an entry in the NGIE: JOBLOG form.

NGIE000107 Error Failed to get list of job runs.Solution

Check your connection to the Pentaho server. Also check whether there is an entry in the NGIE: JOBLOG form.

NGIE000201 Error Error creating data store.Solution


NGIE000202 Error Error updating data store.Solution


NGIE000203 Error Error deleting data store. Solution




122 User’s Guide

Atrium Integrator Error Messages

NGIE000204 Error Error getting data stores. Solution


NGIE000205 Error Error getting data store types. Solution


NGIEA000303 Error Error occurred while trying to connect to the data store.Solution

Check the data store connection details.

NGIEA000304 Error Error occurred while trying to connect to the data store. Solution

Check the data store connection details.

NGIEA000305 Error Please check the name and path details.Solution

Verify the directory path and check whether the folder specified in the path exists on the Atrium Integrator server.

NGIEA000310 Error Error publishing the job to the repository.Solution

Check your connection to the repository database server. After you fix the connection, you can copy the job and transformation files saved in the user profile on the mid tier (C:\Documents and Settings\Administrator\jobName\) to the Spoon repository.

NGIEA000311 Error Error publishing the transformation to the repository.Solution

Check your connection to the repository database server. After you fix the connection, you can copy the job and transformation files saved in the user profile on the mid tier (C:\Documents and Settings\Administrator\jobName\) to the Spoon repository.





NGIEA000315 Response column in Transformation Options for one or more CI Types is not set.Solution

Check whether the source column to be updated has been specified for the Response area in the Transformation Options tab for the CI Mapping and Relationship Mappings pages of the Integration Job Builder wizard.

NGIEA000316 Delta column in Transformation Options for one or more CI Types is not set.

Solution

Check whether the source column to be used for Delta has been specified for the Delta area in the Transformation Options tab for the CI Mapping and Relationship Mappings pages of the Integration Job Builder wizard.



124 User’s Guide

Chapter

8
Migrating jobs to a production server
If you create and test your data transfer jobs on a development computer, you can migrate them to a production server.

� To migrate jobs from a development computer to a production server

1 On the development computer, open the job in the Spoon window.

2 Choose File > Export to an XML file.

NOTE To export a job and its related transformations, choose File > Export all linked resources to XML.

3 Save the job as a .kjb file in a directory on the development computer.

4 Copy the .kjb file from the development computer to the same directory on the production server.

5 On the production server, click Start > BMC Software > Atrium Integrator > BMC Atrium Integrator Spoon.

Chapter 8 Migrating jobs to a production server 125


Figure 8-1: Spoon window

6 Log on to the NGIEREPD repository in Spoon.

7 In the Spoon window, choose File > Import from an XML file.

8 In the Open dialog box, select the .kjb file.

9 Click Open.

The job is opened in Spoon.

10 Click Save to save the job in the NGIEREPD repository.

126 User’s GuideBMC Software, Inc., Confidential

Appendix

A
Moving from BMC Atrium Integration Engine to Atrium Integrator
This appendix describes Atrium Integrator terminology and tasks that correspond to BMC Atrium Integration Engine terminology and tasks.


� Terminology (page 128)� Tasks (page 128)



TerminologyThe following table describes Atrium Integrator terms that map to BMC Atrium Integration Engine terms.

TasksThe following table describes Atrium Integrator tasks that map to BMC Atrium Integration Engine tasks.

Table A-1: Mapping Atrium Integrator terms to BMC Atrium Integration Engine terms

BMC Atrium Integration Engine term

Corresponding Atrium Integrator term

data exchange job or transformation

data transfer job or transformation

data mapping CI and relationship mapping

Table A-2: Mapping Atrium Integrator tasks to BMC Atrium Integration Engine tasks (Sheet 1 of 2)

BMC Atrium Integration Engine task

Corresponding Atrium Integrator task

Populate field menus Create a data store connection so that the wizard can display source columns.For more information, see “Creating a new data store connection” on page 55.

Create a data mapping for CI classes

Map target attributes to source columns in the CI Mapping page of the Integration Job Builder wizard.For more information, see “Mapping target attributes to source columns” on page 69.

Create a data mapping for relationship classes

Map target attributes to source columns in the Relationship Mappings page of the Integration Job Builder wizard.For more information, see “Defining relationship mapping for the CI types to transfer” on page 74.

Define and execute a data exchange

Schedule a job and execute it.For more information, see “Creating a job schedule” on page 79.

Define connection settings to an external database

Create a data store connection.For more information, see “Creating a new data store connection” on page 55.

Define rules Edit the job or transformations in Spoon.For more information, see Chapter 5, “Editing jobs and transformations.”

128 User’s Guide

Tasks

Use multiple BMC Atrium Integration Engine instances for improving performance.

You can open multiple sessions of Spoon to run different jobs. Each Spoon session is a different process.

Use multithreading to improve performance.

Launch several copies of the CMDBOutput step to increase the overall throughput of the data transfer job.For more information, see “Launching several copies of a step” on page 100.

View log files to debug errors. See errors directly in the Execution Results area of Spoon.

Table A-2: Mapping Atrium Integrator tasks to BMC Atrium Integration Engine tasks (Sheet 2 of 2)

BMC Atrium Integration Engine task

Corresponding Atrium Integrator task



130 User’s Guide

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Index

AAtrium Integrator

as a replacement product for BMC Atrium Integration Engine 13

components 18datasets supported by 13overview of 14performance considerations 23value proposition of 14

Atrium Integrator scenariocreating a database connection 31creating a dataset 30editing the job in Spoon 45monitoring the job 50opening a job in Spoon 40running the job 48use case for 28

BBMC Software, contacting 2

CCarte server 116CI types to transfer, selecting 63creating jobs 62customer support 3

Ddata store connection

creating 55editing 58, 59gathering information about 54supported data types 55

Hhops

colors 90creating 88definition of 17deleting 89disabling 89reversing 89

IIntegration Job Builder wizard

benefits of using 62creating a job 62creating a job schedule 79mapping target attributes to source columns 69selecting CI types to transfer from a list 67selecting CI types to transfer from a template 65selecting relationships to transfer 68specifying source and target details 64

Jjobs

adding intermediate steps 90changing schedule of 112creating 62definition of 17monitoring 108opening in Spoon 86running from Spoon 106running from the Atrium Integrator console 106schedule 63viewing details 110viewing history 108viewing summary 63

Index 131

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

Llaunching multiple copies of a step 100log files 109

Mmapping Integration Job Builder output to Spoon

steps 87migrating

data 82jobs 125

monitoring jobs 108

Pproduct support 3

Rrelationships for CI types to transfer 63repository 17running jobs 106

Sscheduling jobs 63source and target details, specifying 63Spoon 21steps 17support, customer 3

Ttarget and source details, specifying 63target attributes to source columns, mapping 63technical support 3transformations

adding intermediate steps 90connecting steps in Spoon 88definition of 17editing 97editing properties 98

132 User’s GuideBMC Software, Inc., Confidential

*176789**176789**176789**176789*

*176789*

atrium integrator 7.6.04 user's guide

Documents

atriumintegratorinstallationdirectoryserverdata

atrium core

local support

bmc atrium

bmc atrium

settingsadministratorjobname

atrium integrator

dev02 vl3421