APM Import Tool. Product Guide

Transcription

1 APM Import Tool Product Guide

2 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 , , and (c)(1) - (2) and DFARS Section (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.

3 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

4

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 Log In to the APM Import Tool Import Flat Files Map Columns Set Exclusion Filter Start Import or Save for later Import Save Mapping Open a Saved Mapping Restart Wizard Load Source Fields from Import Files View Log File Advanced Settings Command Line Parameters Appendix A: Sample Mappings 25 Contacts Hardware Assets Software Assets Legal Documents Assets to Legal Documents Index 33 Contents 5

6

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

8

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 (For 3. Reload the Unicenter APM System Cache. Installing the APM Import Tool 9

10

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) Using the APM Import Tool 11

12 How to Use the APM Import Tool 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 3. Click OK. Defines the name of the table owner (either DBO for MSQL or mdbadmin for Oracle). 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. 12 Product Guide

13 How to Use the APM Import Tool 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. Using the APM Import Tool 13

14 How to Use the APM Import Tool Column Mapping Rules Add, Delete 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. 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. 14 Product Guide

15 How to Use the APM Import Tool 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: Assign Multiple Values to a Single Field 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. 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%. Using the APM Import Tool 15

16 How to Use the APM Import Tool Set Exclusion Filter Set Exclusion Filter Rules Add, Delete Rules 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. 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. 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. 16 Product Guide

17 How to Use the APM Import Tool 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. Using the APM Import Tool 17

18 How to Use the APM Import Tool 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. 18 Product Guide

19 How to Use the APM Import Tool 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, UAPMImportTool log, is the log file for April 8, 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. Using the APM Import Tool 19

20 How to Use the APM Import Tool 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 UAPMAPI 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 20 Product Guide

21 How to Use the APM Import Tool 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 subobject 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 3. Click OK. Displays whether to allow the creation of new values for drop-down lists during the import, or to view such attempts as exceptions. The Advanced Settings are saved. Using the APM Import Tool 21

22 How to Use the APM Import Tool 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 -r -p -s -c -ea -ee (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" (Required) Starts the import automatically and shows the progress UI. This option must always be used together with the -f and -p options. (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 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. Specify the Changer Stamp. Example: "APM Import Tool" -cuserx Enable Audits. Specify either 0 or 1. Example: "APM Import Tool" -ea1 Enable Events. Specify either 0 or 1. Example: "APM Import Tool" -ee1 22 Product Guide

23 How to Use the APM Import Tool -es Enable Scripts. Specify either 0 or 1. Example: "APM Import Tool" -es1 Using the APM Import Tool 23

24

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 Sample Mappings 25

26 Hardware Assets 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 Class model model class Type model model asset type Manufacturer Name model / company asset model manufacturer company name Manufacturer Alias model / company asset model manufacturer company alias 26 Product Guide

27 Hardware Assets Sample Column Name(s) Manufacturer Alias & Asset Description Object asset Unicenter APM Field 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 Sample Mappings 27

28 Software Assets 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. 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. 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. Sample Column Name(s) Object Unicenter APM Field Class model model class 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 28 Product Guide

29 Software Assets Sample Column Name(s) Object Unicenter APM Field 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: Your Unicenter APM database contains a Company with a company alias of TIS. 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. Sample Mappings 29

30 Legal Documents 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. Sample Column Name(s) Object Unicenter APM Field Type legal document template Vendor Name Vendor ID legal document / company external company name 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 30 Product Guide

31 Assets to Legal Documents Assumptions - This mapping assumes the following prior to running the legal document sample import: Your Unicenter APM database contains a Company with a company alias of TIS. 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. Sample Column Name(s) Object Unicenter APM Field 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. Sample Mappings 31

32

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 Index 33