SmartCloud Control Desk 7.5.1.2

Guide for Importing IdML Data

���

NoteBefore using this information and the product it supports, read the information in “Notices” on page 7.

This edition applies to version 7, release 5, modification 1, fix pack 2 of SmartCloud Control Desk and to allsubsequent releases and modifications until otherwise indicated in new editions.

© Copyright IBM Corporation 2014.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

IdML data imports . . . . . . . . . . 1Before you import IdML data . . . . . . . . . 1Supported actions and processing . . . . . . . 2ImportIDML tool usage. . . . . . . . . . . 3Troubleshooting IdML imports . . . . . . . . 5

Notices . . . . . . . . . . . . . . . 7Trademarks . . . . . . . . . . . . . . . 8

© Copyright IBM Corp. 2014 iii

iv SmartCloud Control Desk 7.5.1.2: Guide for Importing IdML Data

IdML data imports

You can use the ImportIDML tool to import actual CI data directly intoSmartCloud Control Desk. This tool is available after you install IntegrationComposer.

IdML data import tool

The ImportIDML tool provides a mechanism by which you can load informationabout discovered configuration items without using Tivoli® ApplicationDependency Discovery Manager (TADDM). The data must be exported in IdMLformat. Products that can export IdML data include IBM Tivoli Network Manager,IBM® Tivoli Business Service Manager, and IBM Tivoli Provisioning Manager.

The ImportIDML tool is installed with Integration Composer. It is supported on allplatforms that are currently supported by Integration Composer.

The ImportIDML tool is installed at the following location:

Integration Composer Home/bin

The tool is run from the command line with the following command:

Operating System Command

Microsoft Windows importIDML.bat

other supported operating systems importIDML.sh

You can use the ImportIDML tool whether or not you use TADDM to import dataabout actual CIs. If you use both processes, do not run the ImportIDML tool whilethe integration adapter for TADDM is running. Importing data from multiplesources at the same time can yield unpredictable results.

Do not import the same data with the ImportIDML tool that you import with theTADDM adapter. If you import the data with both tools, duplicates are createdbecause Integration Composer uses the TADDM guid whereas the ImportIDMLtool uses the ID attribute.

What is IdML?

The Identity Markup Language (IdML) is an Extensible Markup Language (XML)dialect that is used to describe resource instances and their relationships accordingto the Common Data Model. The Common Data Model is used to describe actualCIs in the product database.

Before you import IdML dataBefore you import IdML data, make sure that CIs are uniquely identified and thatenumerated values are processed properly.

The IdML specification says that the ID tag is optional, but this tag is required forimporting CI data. The ID is used, along with an optional prefix, to create the

© Copyright IBM Corp. 2014 1

ACTCINUM attribute for the actual CI. Be sure that your IdML files specify thistag for each actual CI. If the tool encounters a CI record without an ID, a warningmessage is written to the log file and the CI record is skipped. The ID value mustbe unique.

The Common Data Model, which defines the language that is used to describeconfiguration items, uses enumerations for several CI attributes. In anenumeration, the possible values of the attribute are represented by integers. TheImportIDML tool uses a file that translates these integers into the correct attributevalues. To ensure that enumeration values are correctly processed when youimport IdML data, the Common Data Model version that is used to create the filesshould not be more recent than the SmartCloud Control Desk Common DataModel version.

The createIDMLMetaCache tool in the Integration Composer Home/bin directorycan be used to update the Common Data Model metadata that is used by theImportIDML tool. It reads a CDM.xsd file and outputs three text files in theIntegration Composer Home/data/idml/cdm_metadata directory:v cdmdatetimes.txt: a list of Common Data Model attributes that have a datetime

format that must be converted to a time stamp in order to be loadedv cdmenumerationmap.txt: a list of enumerations that are used to convert the

alphanumeric enumerations to its appropriate integer value that the productrecognizes

v cdmnames.txt: a list of valid Common Data Model classifications that are used torecognize improper classifications and issue warnings

If any of these files exist, the tool renames the existing file by appending thecurrent timestamp and creates a new file.

The createIDMLMetaCache tool accepts one parameter, which is the name of anxsd file. Specify the location of the xsd file that contains the schema that is used togenerate your IdML file. If no file name is specified, the tool runs againstIntegration Composer Home/data/idml/cdm_metadata/CDM.xsd.

All of the classifications that are specified in the IdML files that you import mustbe specified in the cdmnames.txt file and must also be defined as SmartCloudControl Desk classifications. In addition, all the attributes that are specified in theIdML files that you import must be defined in SmartCloud Control Desk for theclassification of the actual Configuration Item to which they belong.

Supported actions and processingYou can create or modify actual CIs with the ImportIDML tool.

When you use the ImportIDML tool to import IdML data, you can either createnew actual CIs or modify existing ones. You can also delete actual CIs.

How the file is processed

The tool does not filter the data by location or other criteria. It processes all recordsin the file.

When the tool processes an IdML file, it processes each entry in the same way,regardless of whether the entry is in a create section or a modify section. The tooluses the specified ID tag, and a prefix if one is entered on the command line, to

2 SmartCloud Control Desk 7.5.1.2: Guide for Importing IdML Data

create an ACTCINUM for the CI. The tool then queries the database for an actualCI with that ACTCINUM value. If one is found, then the CI entry is processed asan update; otherwise a new CI is created.

If you import an actual CI more than once, using the same prefix or no prefix, theACTCINUM values match and the tool treats the second import as an update. Ifyou import the same actual CI more than once but use a different prefix, theACTCINUM values do not match, and the second import results in the creation ofa new actual CI.

After all the entries in the file are processed, the tool uses the Naming andReconciliation Service to create a unique identifier for each newly created actual CIthat represents a computer system. For each entry, if an existing actual CI is foundwith the same identifier, the existing actual CI is marked for deletion. The toolassumes that the new information should replace the old record.

Deleting actual configuration items

You can use the ImportIDML tool to delete actual CIs, even the CIs that wereimported from TADDM.

To delete actual CIs, use the tool with the -c flag, and specify a string. Actual CIswhose ACTCINUM attribute begins with the specified string are deleted. Thestring can be a prefix that you used when the actual CIs were created, or it can beany string that appears at the beginning of ACTCINUM attributes. The actual CIsare deleted immediately, and they are deleted whether they were promoted or not.

ImportIDML tool usageThe ImportIDML tool is used to import IdML formatted data into SmartCloudControl Desk, through Integration Composer. The tool is called from theIntegration Composer command line.

Adding the SmartCloud Control Desk database password

When you install Integration Composer, you specify the URL for the SmartCloudControl Desk database and the user ID that is used to connect to the database. Thevalues that are specified are maintained as the following properties in thefusion.properties file:v mxe.db.url=

v mxe.db.user=

The ImportIDML tool creates and updates actual CIs in the database that isspecified in the fusion.properties file.

The database password must also be specified in the Integration ComposerHome\bin\executeMapping.properties file as the TARGETPWD value.

Optionally, you can use the encryptExecuteMappingProperties command toencrypt the properties file, as shown in the following example:

encryptExecuteMappingProperties.bat executeMapping.properties

IdML data imports 3

Command syntax

The ImportIDML tool is run from the /bin directory, under the IntegrationComposer root directory.

importIDML -f<filename> -c<prefix> -p<prefix> -s<customer>

Where:

Parameter Description

-f<filename> Required unless the -c option is specified.The name of the IdML file to import. A fullpath to the IdML file can be specified. If afull path is not used, the file that is specifiedmust exist in the Integration ComposerHome/data/Idml directory.

-c<prefix> Optional. Delete Actual CIs whoseACTCINUM attributes start with the prefixthat is specified.

-p<prefix> Optional. Prefix for ACTCINUMs that isused when the objects are created.

-s<customer> Optional. The primary customer name to setfor each Actual CI that is created. Thisparameter is used only with IBMSmartCloud Control Desk - Service ProviderEdition. The tool does not check to verifythat you installed IBM SmartCloud ControlDesk - Service Provider Edition. Customervalues are added to the database table, butthey are not used unless you install IBMSmartCloud Control Desk - Service ProviderEdition.

-d Optional. This option deletes attributes onany actual CIs if the attribute is no longerdefined for the classification that isassociated with the actual CI. Deletionaffects any actual CIs; it is not limited toActual CIs loaded by the loader. This routinecan affect performance. Use it only ifnecessary.

-r Optional. This option deletes attributes fromthe set of Actual CIs that are being importedif the attribute is not specified for the actualCI in the IdML file.

Syntax example

importIDML -fITNM.xml -pITNM- -sIBM

All error messages, debug statements, and trace records are written to theIntegration Composer Home/log/fusion.log file. Because the log files roll over andyou risk losing important information, preserve the information for analysis bypiping the output to a file, for example importIDML -fITNM.xml -pITNM_ -sIBM 1>ITNMLog.out.

4 SmartCloud Control Desk 7.5.1.2: Guide for Importing IdML Data

Troubleshooting IdML importsTo facilitate troubleshooting, specify the required database properties files andconfigure logging. The following information describes how to configure loggingand troubleshoot specific issues.

Configuring properties files

The ImportIDML tool depends on Integration Composer properties that arespecified in the following location: Integration Composer Home/data/properties/fusion.properties. The following properties are set when Integration Composer isinstalled, but you can modify them with a text editor:v Database properties that specify the database that data is imported into,

including– mxe.db.schemaowner=

– mxe.db.driver=

– mxe.db.url=

– mxe.db.user=

v perfmon properties, including– // perfmon.logfrequency=5

– // perfmon.details=FALSE // Set all thresholds in seconds

– // perfmon.threshold.sql=10

If you want to measure performance criteria, remove the slashes (//) from theperfmon properties.The log file that is generated for perfmon properties is located here: IntegrationComposer Home\log\perfmon.log

v mxe.fusion.mapping.nrs.enable=true, which enables the generation of NamingReconciliation Service (NRS) globally unique identifiers (guids) for ComputerSystem CI types during a mapping

Log properties for the ImportIDML tool log files are found in IntegrationComposer Home/data/properties/logging.properties. You can set the followingproperties:v log4j.logger.idml=INFO

v log4j.logger.idml.detail=ERROR

If you specify DEBUG for log4j.logger.idml.detail=, all entry and exit points arereported. Specifying DEBUG usually yields too much data. For DEBUG, it isrecommended to begin by specifying log4j.logger.idml=DEBUG and possiblylog4j.logger.maximo.sql=DEBUG if you want to view the SQL statements.

Common Data Model discrepancies

The default cdmdatetimes, cdmenumerationmap, and cdmnames text files that areinstalled with Integration Composer are generated against a specific version of theCommon Data Model. If your source environment contains metadata that matchesa different Common Data Model version, the generated IdML file might containclassifications, attributes, or relationships unknown to SmartCloud Control Desk orthe ImportIDML tool. This can cause the ImportIDML tool to log errors and skipimporting actual CIs that contain the unknown metadata.

To fix this situation, use the SmartCloud Control Desk user interface to create themissing metadata and then either manually edit the appropriate cdmdatetimes,

IdML data imports 5

cdmenumerationmap, and cdmnames text files or use the createIDMLMetaCache toolto generate new file versions by passing it an updated CDM.xsd file.

For example, if the source database contains an attribute unknown to an existingSmartCloud Control Desk classification, you can use the SmartCloud Control DeskClassifications application to add the new attribute to the classification. If the newattribute contains an enumeration type value, you must update thecdmenumerationmap.txt file to specify the valid values. For a new classification,you must also update the cdmnames.txt file after you create the new classificationand its attributes in SmartCloud Control Desk.

6 SmartCloud Control Desk 7.5.1.2: Guide for Importing IdML Data

Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user's responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not grant youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan Ltd.1623-14, Shimotsuruma, Yamato-shiKanagawa 242-8502 Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law: INTERNATIONALBUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS"WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFNON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULARPURPOSE. Some states do not allow disclaimer of express or implied warranties incertain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.

© Copyright IBM Corp. 2014 7

IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM Corporation2Z4A/10111400 Burnet RoadAustin, TX 78758U.S.A.

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM's future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

TrademarksIBM, the IBM logo, and ibm.com are trademarks or registered trademarks ofInternational Business Machines Corp., registered in many jurisdictions worldwide.Other product and service names might be trademarks of IBM or other companies.A current list of IBM trademarks is available on the Web at “Copyright andtrademark information” at www.ibm.com/legal/copytrade.shtml.

Amazon Web Services, the “Powered by Amazon Web Services” logo, AmazonEC2, Amazon Elastic Compute Cloud, and AWS are trademarks of Amazon.com,Inc. or its affiliates in the United States and/or other countries.

Java™ and all Java-based trademarks and logos are trademarks or registeredtrademarks of Oracle and/or its affiliates.

Linux is a trademark of Linus Torvalds in the United States, other countries, orboth.

8 SmartCloud Control Desk 7.5.1.2: Guide for Importing IdML Data

Microsoft, Windows, Windows NT, and the Windows logo are trademarks ofMicrosoft Corporation in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Other product and service names might be trademarks of IBM or other companies.

Notices 9

10 SmartCloud Control Desk 7.5.1.2: Guide for Importing IdML Data

����

Printed in USA