APM Import Tool Product Guide - SupportConnect - Welcome

Product Guide

APM Import Tool

This documentation and any related computer software help programs (hereinafter referred to as the “Documentation”) is for the end user’s informational purposes only and is subject to change or withdrawal by CA at any time.

This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. This Documentation is confidential and proprietary information of CA and protected by the copyright laws of the United States and international treaties.

Notwithstanding the foregoing, licensed users may print a reasonable number of copies of the Documentation for their own internal use, and may make one copy of the related software as reasonably required for back-up and disaster recovery purposes, provided that all CA copyright notices and legends are affixed to each reproduced copy. Only authorized employees, consultants, or agents of the user who are bound by the provisions of the license for the Product are permitted to have access to such copies.

The right to print copies of the Documentation and to make a copy of the related software is limited to the period during which the applicable license for the Product remains in full force and effect. Should the license terminate for any reason, it shall be the user’s responsibility to certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed.

EXCEPT AS OTHERWISE STATED IN THE APPLICABLE LICENSE AGREEMENT, TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION “AS IS” WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO THE END USER OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED OF SUCH LOSS OR DAMAGE.

The use of any product referenced in the Documentation is governed by the end user’s applicable license agreement.

The manufacturer of this Documentation is CA.

Provided with “Restricted Rights.” Use, duplication or disclosure by the United States Government is subject to the restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)(3), as applicable, or their successors.

All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.

Copyright © 2007 CA. All rights reserved.

CA Product References This document references the following CA product:

Unicenter® Asset Portfolio Management

Contact Technical Support For online technical assistance and a complete list of locations, primary service hours, and telephone numbers, contact Technical Support at http://ca.com/support.

http://www.ca.com/support

Contents 5

Contents

Chapter 1: Introduction 7 Import Data using the APM Import Tool ......................................................... 7 Audience...................................................................................... 7

Chapter 2: Installing the APM Import Tool 9 Install the APM Import Tool .................................................................... 9

Chapter 3: Using the APM Import Tool 11 How to Use the APM Import Tool .............................................................. 11

Log In to the APM Import Tool ............................................................. 12 Import Flat Files .......................................................................... 12 Map Columns ............................................................................. 13 Set Exclusion Filter........................................................................ 16 Start Import or Save for later Import ...................................................... 17 Save Mapping ............................................................................ 17 Open a Saved Mapping.................................................................... 18 Restart Wizard............................................................................ 18 Load Source Fields from Import Files....................................................... 19 View Log File ............................................................................. 19 Advanced Settings ........................................................................ 20 Command Line Parameters ................................................................ 22

Appendix A: Sample Mappings 25 Contacts ..................................................................................... 25 Hardware Assets ............................................................................. 26 Software Assets .............................................................................. 28 Legal Documents ............................................................................. 30 Assets to Legal Documents.................................................................... 31

Index 33

Introduction 7

Chapter 1: Introduction

This section contains the following topics:

Import Data using the APM Import Tool (see page 7) Audience (see page 7)

Import Data using the APM Import Tool The APM Import Tool simplifies the data mapping and data import process by providing many of the common and basic data import requirements. The tool enables you to precisely map data fields from a flat file to data fields in your Unicenter Asset Portfolio Management repository. The APM Import Tool leverages the existing Unicenter Asset Portfolio Management (Unicenter APM) application program interface (API) to ensure the proper database updates.

Note: For more information on API refer the Unicenter Asset Portfolio Management Inside the API guide, available in the DOC folder of your installation DVD, on SupportConect, or from your administrator.

Audience This guide is designed to assist asset administrators who are responsible for importing asset and other related data into a Unicenter Asset Portfolio Management repository using the APM Import Tool.

Installing the APM Import Tool 9

Chapter 2: Installing the APM Import Tool

This section contains the following topic:

Install the APM Import Tool (see page 9)

Install the APM Import Tool Pre-requisite

Unicenter Asset Portfolio Management (Unicenter APM) r11.3.

To install the APM Import Tool

1. Copy the APM Import Tool.exe (in zip file) to the UAPM\console directory.

Note: If you are installing the tool on a client workstation, the minimum required Unicenter APM component on this machine is the Management Console.

2. Do the following:

a. On MS SQL Server:

Run the sql.text file against the Unicenter APM MDB using the SQL Query Analyzer to update the database.

b. On Oracle Server:

Run the sql_oracle.txt file (in zip file) against the Unicenter APM MDB to update the database.

Note: Start the SQL Plus application and execute the following command:

@<path>\sql_oracle.txt;

(For example, @c:\test\sql_oracle.txt)

3. Reload the Unicenter APM System Cache.

Using the APM Import Tool 11

Chapter 3: Using the APM Import Tool

This section contains the following topic:

How to Use the APM Import Tool (see page 11)

How to Use the APM Import Tool The APM Import Tool lets you map and import data from a selected file. The tool enables you to set filters and delimiters, and assign global values for the imported data. You can also select the source and destination fields of the imported file.

To use the APM Import Tool to map and import the selected data, follow this process:

Log in to the APM Import Tool

Select the delimited flat file containing the data

Map the source columns to the Unicenter APM fields

(Optional) Set exclusion filter to filter any of the source records

Start import or save the mapping to run at a later time

Note: You can also use the command line to run imports.

More information:

Command Line Parameters (see page 22)

How to Use the APM Import Tool

12 Product Guide

Log In to the APM Import Tool

You must use your database credentials (for example, uapmadmin) to log in to the APM Import Tool and import data.

To log in to the APM Import Tool

1. Double-click APM Import Tool.exe

The tool opens.

Note: To open the tool by using the command line, see Command Line Parameters.

2. Fill in the following fields:

Database Type

Defines the selected database (either Microsoft SQL Server or Oracle).

User ID

Defines the database user id. You must use your database credentials (for example, uapmadmin).

Password

Defines the password entered.

Server Name

Defines the name of the SQL server or Oracle service.

Database Name

Defines the selected database (MDB).

Table Owner Name

Defines the name of the table owner (either DBO for MSQL or mdbadmin for Oracle).

3. Click OK.

The APM Import Tool is ready to import data.

Import Flat Files

The APM Import Tool supports delimited flat files. You can select or enter the delimiter. You can also open an existing map file with its flat file already selected and configurable import parameters already defined.



Select the File and Configure the Import Parameters

The APM Import Tool lets you browse and select a file that contains the data to be imported, and configure the import parameters.

To select a file for import

1. Click the ellipsis (...) next to the File Name field to select the file you want to import.

The Open Dialog Box appears allowing you to select the file for import.

2. Select a delimiter value from the drop-down list.

Note: If the delimiter you want is not listed, enter your own value.

3. Select the check box if the first row in your file contains the column names.

This option defaults to Yes. If the first row does not contain the field or column names, then the field names will display generic names, Field 1, Field 2, and so on.

4. Select the Main Destination Object from the drop-down list.

Note: The primary objects are listed first, followed by all drop-down lists.

5. Click Next.

This takes you to Map Columns window.

Note: If new drop-down type objects are created during an import, you need to restart the Unicenter APM Cache service, before you will be able to view them in the Unicenter APM Web UI.

Map Columns

You can map columns or fields to a field within Unicenter APM. This exposes most Unicenter APM objects and associated fields.


14 Product Guide

Column Mapping Rules

The APM Import Tool lets you map the columns and expose all objects and associated fields.

To map columns

1. Click the ellipsis (...) next to a Source Field to select the column from your data source.

2. Click the ellipsis (...) next to a Destination Field to select the Destination Field.

Note: The destination field is mandatory. Also the destination field is based on the selected main destination object.

3. Select the Key check box, if required.

The key field allows you to identify what is unique to control inserts versus updates.

For example, if you are importing contacts and select Key for first name and last name, the import will look for duplicates based on both fields, and if a match is not found, the contact is added. If a match is found, then that record is updated.

4. Click Next.

This takes you to the Exclusion Filter.

Add, Delete Rules

You can add rules to or delete rules from the filter.

1. Click Add Rule.

A new rule is added.

2. Click the Delete Rule icon next to the rule that is to be deleted.

The rule is deleted.



Assign Global Values

You can define global values to expand the data source and ensure all required fields are included or provide additional information not included in your data source. Global values are generally those which do not begin and end with a '%'. You can also have global values that are wrapped by % as long as they do not match the field names in your import file.

Example:

Assets in your delimited flat file data source may not contain asset type, which is a required value when creating an asset. The APM Import Tool allows you to add a global value, in this scenario, asset type, to your mapping. If all your assets are of the same type (example, Hardware), you can type Hardware into the source field which is mapped to the Unicenter APM field asset type. If your assets are not all of the same type, then you will be required to add a column and add the corresponding asset types to your data source prior to running the import.

The following contrasts a global value with a source field value to differentiate between which values are pulled from your source or added by the global value mechanism.

If you have an Asset Type column in your data source, the source mapping field will look like this: %asset type%.

If you do not have an Asset Type in your data source, but you know all your assets are hardware assets, the source mapping field will look like this: Hardware.

Assign Multiple Values to a Single Field

You can add rules where multiple source columns or fields map to a single Unicenter APM field.

Example:

Your data source has two columns with the names Manufacturer and Catalog Name. You can combine these two source columns into one Unicenter APM field by selecting both.

The result would be: %Manufacturer% %Catalog Name%

You can also enter your own values into the fields (hard code values) along with the data source values, for example: CA %model name%.


16 Product Guide

Set Exclusion Filter

You can define a subset of records to be processed or excluded from the import. You can filter any portion from your data source. You can use special characters, wildcards, and operators in your rule. Rules can handle text, numeric, and date fields.

Example:

You have received a CSV file from your hardware vendor containing a combination of assets ordered and returned to vendor. You first want to process only the returned assets, so you run an import to only update those records. The exclusion filter allows you to process a subset of records, in this case, based upon a status not equal to returned.

Set Exclusion Filter Rules

The APM Import Tool lets you set exclusion filter rules by adding rules and setting filters that exclude any of the records from the datasource.

To set exclusion filter rules

1. Select Filter Type.

2. Click Add Rule.

3. Select the Source column.

4. Select Operator from the drop-down list.

5. Enter Value.

Note: Repeat steps 2-5 to add more rules to the filter.

6. Click Next.

This takes you to the Start import or Save for later import window.

Add, Delete Rules

You can add rules to or delete rules from the filter.

1. Click Add Rule.

A new rule is added.

2. Click the Delete Rule icon next to the rule that is to be deleted.

The rule is deleted.



Start Import or Save for later Import

You can start the import immediately or save the configuration as a mapping file for later import.

To start import

1. Select Start the import now... and click Start.

The data source records are imported and the Import Complete window opens.

The Import Complete window displays the status of the import including the number of records processed, how many were successful, with errors and with warnings.

Note: View the log file for more information on the import activity.

2. Click Another to import another file, or click Exit to exit the APM Import Tool.

To save for later import

1. Select Save this import for later... and click Next.

The Save As dialog box opens.

2. Enter the details and save the file.

The Import Saved window opens.

3. Click Another to import another file, or click Exit to exit the APM Import Tool.

Note: You can use the Save option under the file menu to save your mapping at any time.

Save Mapping

You can save a mapping in a path specified by you.

To save a mapping

1. Click File, Save Mapping.

The Save As dialog appears (only when you are saving a mapping for the first time).

2. Enter the path to save the mapping.

Note: You can also select Save Mapping As and save the file.


18 Product Guide

Open a Saved Mapping

You can open a saved mapping for import.

To open an existing mapping

1. Click Open Mapping from the file menu.

2. Browse and select an existing mapping which has the file extension *.map.

Note: You can also open the saved mapping by selecting the Open existing map file… button on the Select a Text File to Import window.

Restart Wizard

You can use the Restart Wizard to clear everything and start the mapping process over. If you have made changes to a mapping, you will be prompted to save your changes before restarting.

To use the Restart Wizard

1. Click File, Restart Wizard.

The APM Import Tool returns to the beginning of the mapping process, as if you had first opened it.

Notes:

A message displays, asking if you would like to save your changes before restarting the wizard.

Click Yes to save the mapping, enter the path to save the file and click Save. The file is saved and the tool returns to select another file for import.

Click No to return to select another file for import without saving the present mapping, and click Cancel to continue with the present import.



Load Source Fields from Import Files

The Load Source Fields from Import File menu option allows you to import all source columns instead of selecting Add Rule for each field when performing the column mapping.

To load all source fields

1. Select a file to import, a Delimiter and a Main Destination Object, on the Select a Flat File to Import window.

2. Click Next to continue.

3. Click Tools, Load Source Fields from Import File, on the Map Columns window.

A message displays asking if you want to overwrite all existing source values with the header fields and continue.

Important! If you do not select the same delimiter used in your data source, all column headings may appear in one field.

View Log File

The APM Import Tool log file displays the details of the entire import process. A new log file is created each day the application is run. All activities including multiple imports are contained within the log file for that day. The log file name contains the date, for example, UAPMImportTool20070408.log, is the log file for April 8, 2007.

To view log file Click Tools, View Log File in the APM Import Tool results window.

Note: You can use the View Log file option under the file menu to view the log file at any time.


20 Product Guide

Advanced Settings

The APM Import Tool Advanced Settings lets you set various administrative options including error threshold, the API debug level, and the log view display.

To set the Advanced Settings

1. Click Tools, Advanced Settings.

The APM Import Tool - Settings displays.

2. Enter data into the following fields, as required.

Max Error Threshold

Defines the number of errors after which the import stops. This is based upon the percentage of records to be processed. CA recommends a minimum threshold of 15%. For example, if you have 100 records, the import will terminate if 15 errors occur.

API Debug Level

Defines the amount of information that will be written to the Unicenter APM API log. This log file is different from the standard Import Tool log file. If you are experiencing problems with an import and would like to troubleshoot the problem the API log file may provide more information than the standard Import Tool log file. The higher the setting the more information that will be written to the API log.

The API logs are located in the UAPM\Console directory and are in the format UAPMAPI20070409.csv where the last eight characters are the date the file was created in YYYYMMDD format.

Changer Stamp

Defines who made a change to the values and records. This is useful if you have multiple imports and you want to differentiate between which import made the changes. If this field is blank, the default value is the login ID of the user that is running the APM Import Tool.

Log Viewer App.

Defines the application that is used to view the APM Import Tool log file.

Default: Notepad



You can also select the following check boxes, as required:

Enable Audits

Enables or disables audits when running an import.

Enable Events

Enables or disables events when running an import.

Enable Scripts

Enables or disables scripts when running an import.

Error on sub-object Errors

Defines whether errors that occur when inserting/updating sub-objects are ignored. When this option is selected, if a sub-object insert/update fails, the insert/update to the parent object will also fail. When this option is not selected (ignored), the parent object will still be created/updated (as long as it is not dependent on the sub-object) but the sub-object value will remain unchanged. Even if ignored the sub-object error will still be written to the log file.

Example:

You are importing a location and the location has a country; if the import fails when trying to insert/update the country then the entire location record will fail to insert/update.

If this option is off, then even if country fails to insert/update, the location record is created; but its country field is not set/updated.

Automatically create new Drop-down sub-objects

Displays whether to allow the creation of new values for drop-down lists during the import, or to view such attempts as exceptions.

3. Click OK.

The Advanced Settings are saved.


22 Product Guide

Command Line Parameters

Command line parameters provide the option to run imports unattended by using the command line. It works in conjunction with a scheduler, preferably the Operating System scheduler.

The following list identifies the available parameters:

Note: The file name must be enclosed in quotes if there are spaces in the path or file name.

In the list below a value of 0 indicates that an option is disabled. A value of 1 indicates that an option is enabled.

-f

(Required) Opens the import tool with a specific pre-loaded .map file. The file name must be immediately after the –f.

Example: "APM Import Tool" -f"C:\UAPM Import Tool 2003\location.map"

-r

(Required) Starts the import automatically and shows the progress UI. This option must always be used together with the -f and -p options.

-p

(Required) DB Password to connect with. This option is required when starting the program in silent mode or in auto-run mode. The password must be immediately after the –p.

Example: "APM Import Tool" –pyourPassword

-s

Run the program silently. The import will start automatically. No UI is displayed but a log file is created. This option must always be used together with the -f and -p options.

-c

Specify the Changer Stamp.

Example: "APM Import Tool" -cUserX

-ea

Enable Audits. Specify either 0 or 1.

Example: "APM Import Tool" -ea1

-ee

Enable Events. Specify either 0 or 1.

Example: "APM Import Tool" -ee1



-es

Enable Scripts. Specify either 0 or 1.

Example: "APM Import Tool" -es1

Sample Mappings 25

Appendix A: Sample Mappings

Sample mapping files for various Unicenter APM objects are provided in this chapter. The examples help you understand how to import these objects.

Important! Use a test database (not a production database) when you are using the sample mappings to load sample data. Test data cannot be removed easily after it has been imported into your database.

This section contains the following topics:

Contacts (see page 25) Hardware Assets (see page 26) Software Assets (see page 28) Legal Documents (see page 30) Assets to Legal Documents (see page 31)

Contacts Mapping file: contact mapping.map

Data file: contacts.csv

This mapping and data file includes basic contact information. The mapping creates 10 contacts and the association between a company and its supervisor.

Sample Column Name

Unicenter APM Field Description

EmpID Contact ID Contact unique identifier

LastName Contact last name Contact last name

First name Contact first name Contact first name

Phone Contact telephone number Contact telephone number

CostCenter Contact cost center value Contact cost center value

CCDesc Contact cost center description

Contact cost center description

Company Code Company alias Company Identifier

Department Contact department Contact department

Hardware Assets

26 Product Guide

Sample Column Name

Unicenter APM Field Description

Login ID Contact user ID Login ID

Supervisor Supervisor Contact's supervisor

Assumptions - This mapping assumes the following prior to running the contact sample import:

Your Unicenter APM database contains a Company with a company alias of TIS.

Note: If a company with company alias TIS does not exist, you can either add a company with this alias to your Unicenter APM database or modify the contact sample data source to match an existing company alias already in your database.

Hardware Assets Mapping file: hardware mapping.map

Data file: hardware.csv

This mapping and data file includes basic hardware information. The mapping creates 10 hardware assets, associated models, companies and contacts.

Sample Column Name(s)

Object Unicenter APM Field

Type model model type

Class model model class

Subclass model model subclass

Asset Description model model name


Type model model asset type

Manufacturer Name model / company asset model manufacturer company name

Manufacturer Alias model / company asset model manufacturer company alias

Hardware Assets

Sample Mappings 27



Manufacturer Alias & Asset Description

asset asset name

Asset Description asset asset description

Quantity asset asset quantity

Seller Company asset / company asset seller company name

Company Bought For asset / company asset company name

Serial Number asset asset serial number

Asset Cost Center asset asset cost center value

CC Desc asset asset cost center description

Manufacturer Name asset / company asset company name

Manufacturer Alias asset / company asset manufacturer alias

Contact asset / contact asset contact user id

Asset Alias asset asset alias

Acquired Date asset asset acquired date

Class asset asset class value

Subclass asset asset subclass value

Type asset asset model class family value

Status asset asset status

Asset Version asset / version version name

Current Key asset / version current version key

Acquired date asset / version portfolio status date

Software Assets

28 Product Guide

Assumptions - This mapping assumes the following prior to running the hardware asset sample import:

The contact sample import was performed to provide the association between contacts and hardware assets.


Note: If a company with company alias TIS does not exist, you can either add a company with this alias to your Unicenter APM database or modify the contact sample data source to match an existing company alias already in your database.

Software Assets Mapping file: software mapping.map

Data file: software.csv

This mapping and data file includes basic software information. The mapping creates 20 software assets, associated models, companies and costs.




Subclass model model subclass

Manufacturer Part No model model description

Asset Description model model name

Version model model version name

Manufacturer Alias model / company model manufacturer company alias

Manufacturer Name model / company model manufacturer company name

ID asset alt asset id

Manufacturer Alias asset / company asset manufacturer alias

License Count asset license count

Seller Company Name

asset seller company

Seller Company ID asset asset seller company alias

Software Assets

Sample Mappings 29



Company Bought For asset company bought for

Asset Description asset asset name

Cost Center asset cost center value

PO Number asset purchase order id

PO Date asset asset acquire date

Class asset asset class

Subclass asset asset subclass

Type asset asset type

Type asset asset model class family value

License Type asset license type

Cost Type asset / cost cost type

Unit Amount asset / cost unit amount

Todays Date asset / cost begin date

Current Key asset / version current version key

Todays Date asset / version portfolio status date

Status asset / version portfolio status value

Version asset / version version name

Todays Date asset / version date acquired

Assumptions - This mapping assumes the following prior to running the software asset sample import:


Note: If a company with company code TIS does not exist, you can either add a company with this alias to your Unicenter APM database or modify the contact sample data source to match an existing company alias already in your database.

Legal Documents

30 Product Guide

Legal Documents Mapping file: legal document mapping.map

Data file: legal document.csv

This mapping and data file includes basic legal document information. The mapping creates 20 legal documents and the association to a company.



Type legal document template

Vendor Name legal document / company external company name

Vendor ID legal document / company external company name ID

Document Identifier legal document document identifier

Legal Doc Descriiption

legal document description

Effective Date legal document effective date

Termination Date legal document termination date

Contract Staff Negotiator ID

legal document / contact negotiator ID

Contract Status legal document status value

Contract Status Date legal document status date

Cost Begin Date legal document / cost cost begin date

Cost End Date legal document / cost cost end date

Contract Amount legal document / cost unit amount

Cost Type legal document / cost cost type value

Cost Center legal document cost center value

Location legal document location value

Contract Used legal document contract used type

Assets to Legal Documents

Sample Mappings 31

Assumptions - This mapping assumes the following prior to running the legal document sample import:


Note: If a company with company code TIS does not exist, you can either add a company with this alias to your Unicenter APM database or modify the contact sample data source to match an existing company alias already in your database.

Assets to Legal Documents Mapping file: assets to legal doc mapping.map

Data file: assets to legal doc.csv

This mapping and data file highlights the efficiency of the APM mapping tool to associate Unicenter APM objects to one another. You can associate objects even with a limited set of object information.

In the following example, with only the asset serial number and legal document identifier, you can associate assets to legal documents. This sample import assigns asset objects to a legal document.



Asset ID asset bar code number

Document ID legal document document identifier

Assumptions - This mapping assumes the following prior to running the asset to legal document sample import:

The contact, software and legal document sample imports were performed.

Index 33

Index

A advanced settings • 20 assign global values • 15

C column mapping rules • 14 command line parameters • 22

E exclusion filter • 16 exclusion filter, set • 16

I import • 12

K key • 14

L load source fields • 19 log files, viewing • 19

R restart wizard • 18 rules

adding • 14 column mapping • 14 deleting • 14 exclusion filter • 16

S save mapping • 17

V viewing, log files • 19

APM Import Tool Product Guide - SupportConnect - Welcome

Documents

Transcript of APM Import Tool Product Guide - SupportConnect - Welcome