Getting started with the Asset Import Converter Overview While you can manually enter asset information in the Catalog, you can also import asset data in the XML (extensible markup language) file format. You can use the Asset Import Converter to change asset data that's in a comma-delimited format to an XML file that's accepted by Destiny's Import Assets. Note: The Converter does not accept files with tab-delimited or fixed-length fields; they must be comma-delimited. Another name for comma-delimited data is comma separated values or CSV. For brevity, this document refers to comma-delimited input files as CSV files. This document provides an overview of the conversion process, and guides you through configuring the Converter and converting your CSV data to an XML file. It includes the following sections: Process overview p.2 CSV file requirements p.2 Import Assets requirement p.2 Template file requirements p.3 Setting up the Converter p.3 Configuring the Converter p.3 Getting started p.3 Defining the source fields p.5 Basic one-to-one field definitions p.5 Formatting date fields p.7 Advanced field definitions p.8 Concatenating and inserting functions p.8 Substituting field values p.9 Defining a virtual field p.10 Skipping incoming records p.10 Associating the records with their templates p.11 Running the Converter p.13 Importing the XML file into Destiny p.13 Resources to help you Online Help Destiny includes Help topics and definitions to guide and support you when setting up and maintaining Destiny. Click any help icon ( ) for assistance. For additional help, click Help next to in the upper right corner of any page. Follett Software s Technical Support department via e-mail and telephone If you have a question and cannot find a solution in the help system or Getting Started with the Asset Import Converter, you can contact Follett Software s Technical Support team: e-mail at techsupport@fsc.follett.com; or call 800-323-3397.
Process ove r v i e w With the Asset Import Converter, you'll convert data from a CSV format into the Destiny XML format. You can upload the resulting file in Import Assets in the Catalog. 1. Obtain asset data in a CSV text file and place it in a working folder on your Destiny application server. 2. Download or export your asset template file and place it in your working folder. 3. Using the Converter, define the CSV columns, identify the Key field, and map the rows in the CSV file to their asset type templates. 4. Convert the asset data from the CSV format to the XML format that Destiny can interpret. 5. Import the resulting XML file into Destiny. CSV file requirements There is substantial flexibility in the contents of the CSV file. While there are no absolute requirements, the conversion and import are easiest if each record in the CSV file contains the following: A key field that identifies a record as belonging to a specific asset type. This can be a field in the Displayable Name that Import Assets requires. For each item record, a Barcode Number and SiteShortName. Any other asset or item field that is required by your Destiny template. If the file does not contain all these fields, see the "Advanced field definitions" section on page 8. Please note that you cannot convert Custodian data. The Custodian field consists of two components: Patron Barcode Number and SiteShortName. Please note, also, that you cannot convert a quantity (without barcodes) of On Order items. Import Assets requirement Once you convert the CSV data to the XML format required by Destiny, you'll import the data through Import Assets. Keep in mind that Import Assets has its own requirements and supplies a few default values if they are not included in the XML file: Each record must include at least one of the required fields that make up its Displayable Name. Each field has a maximum length, determined by it's Data Type: o o Text fields can be a maximum of 50 characters. Each option in a dropdown list can be a maximum of 50 characters. Make sure that any incoming value is already defined in your Dropdown List in the template in Destiny. Import Assets cannot add any options to these lists. Import Asset can add Funding Sources, Home Locations, and Departments that do not already exist in Destiny. o Memo fields can be a maximum of 1,000 characters. o Number fields can be up to 15 positive whole numbers Each item must include the Barcode number and SiteShortName. If you are importing On Order items, Destiny auto-assigns today's date as the Date Ordered, and the logged-in user for Ordered By, if these fields are not present in the XML file. Destiny assigns a Status of Available, and a Condition of Usable. Page 2 of 13 Copyright 2010 Follett Software Company 10938A Rev. 13 11-10-A
Template file requirements In addition to your CSV file of your asset information, you'll need a template file in the correct XML format. You can obtain one in either of the following ways: Export your existing template from Destiny: Open Catalog > Add Asset > Edit Templates, and click. If you do not yet have any assets in Destiny, download one of our sample template files from the online help and support site. Make sure to import the templates before importing the converted assets: Open Catalog > Add Asset > Edit Templates, and click. Setting up the Converter For ease of use, create a working folder on your Destiny application server containing all the necessary files: The Asset Import Converter. Download it from Destiny's online help website. Your CSV file containing asset data. Your asset template file. Note: The Converter requires a Java Virtual Machine (JVM ). If you want the Converter to use Destiny's JVM, create your working folder inside the \FSC-Destiny folder. This next section guides you through setting up the Asset Import Converter to suit your CSV file and your preferences. Configuring the Converter Getting started 1. Open the application by double-clicking AssetImportConverter.exe. The Converter first searches your computer's registry for a Java Virtual Machine (JVM). If it cannot find one, a browser window opens, allowing you to download the free JVM from Oracle. The website provides complete instructions. After successfully downloading the JVM, open the application as instructed above. The configuration-file dialog box opens first: 10938A Rev. 13 11-10-A Copyright 2010 Follett Software Company Page 3 of 13
2. If this is your first conversion, click to create a new configuration file. If you've already created a configuration file, click to select it, and then skip to step 6. 3. If you clicked, the Create a New Configuration dialog box appears. Click to select your template file. 4. The asset types in the template appear in the Preview window. If this is the correct template file, click. If not, click again to select a different template file. 5. In the Save As dialog box, enter a name for the configuration file. You must use the CONFIG file extension. 6. On the CSV Data tab of the Converter that opens, click to select your CSV file. 7. Review the data in the Preview pane. If it does not appear correctly, you may need to select a different Text encoding from the list. 8. If your CSV file contains any header rows, select the row number of the first record next to Data begins on row. Next, you'll need to define the contents of each of the columns (the source fields). Page 4 of 13 Copyright 2010 Follett Software Company 10938A Rev. 13 11-10-A
Defining the source fields On the Source Field Definitions tab, you'll select each field in the template that will receive a value during the import, defining its type and format, and selecting the CSV column containing that data. If you need to apply special formatting, you can string together (concatenate) part or all of multiple fields, insert functions, define regular expressions (regex) and constants, or substitute one value for another. For error-free conversion, make sure to do the following: Define the key field that identifies each record's asset type. Optimally, this most likely would be Description or one of the fields that make up the Displayable name. Tip: If your CSV file doesn't contain a field that identifies the asset types in it, add a column containing categories for the different asset types to your CSV file. Define Barcode number and SiteShortName for each incoming item. If you're re-importing assets (on the Update Only tab) that you've previously exported from Destiny, define OrganizationCode. Basic one-to-one field definitions 1. Open the Source Field Definitions tab. Each column, or field, in your CSV file, appears in the table at the bottom. Please note that the first field is Field ${0}, not Field ${1}. 2. Click to define a field. 3. At the top of Source Field Editor, enter or select a template field name for which the CSV file contains data. Tip: Selecting the template field name from the list rather than typing it in will automatically map the data during the Auto Map process. 4. Choose its data type from the Type list. Please note that Currency and Number types convert to strings in the XML file; during import, Destiny reformats them to match the asset type field. If it's a date field, see the "Formatting date fields" section on p.7. 10938A Rev. 13 11-10-A Copyright 2010 Follett Software Company Page 5 of 13
5. From the Insert CSV Column list, select the column in the CSV file that corresponds to this template field. Then verify your selection in the Preview box. The Converter displays the converted data or an explanation of any error. If you'd like to explain any of the definitions, you can add a note in the Notes text box. The XML output file does not include any of these notes; they're for your conversion use only. 6. If the CSV data is suitable as is, click. If not, you can further define the field. You can add additional CSV columns, source fields, or functions. See the "Advanced field definitions" section on page 8. 7. Repeat steps 2 through 6 for each field. For example, given this CSV line: {0} {1} {2} {3} {4} {5} {6} {7} {8} Switch Cisco 4500 869545 $7045.84 63425 106 Erate 6 1/12/2009 you can produce basic 1-to-1 mapping by inserting a CSV column: Page 6 of 13 Copyright 2010 Follett Software Company 10938A Rev. 13 11-10-A
Formatting date fields If you're mapping a date field, verify the format in the Preview box. If it's incorrect, click. 1. On the Choose Date Format dialog box that appears, review the Sample Date String from the CSV file and, from the Month, day, and year order list, select the correct one. 2. In the table, locate and select the best date format. 3. Click when you're done. 4. Verify your format choice by reviewing the date in the Preview box. It should be in YYYYMMDD format. 5. To return to the Source Field Definitions tab, click. 10938A Rev. 13 11-10-A Copyright 2010 Follett Software Company Page 7 of 13
Advanced field definitions To accommodate most field data, the Converter allows flexible formatting. You can string together (concatenate) part or all of multiple fields, insert functions, and define regular expressions (regex). You can also substitute one value for another or create virtual CSV fields. Make sure to review the Preview column. You can determine if it's mapped correctly. If not, the Preview column provides an explanation of the error. In the example below, FundingSource displays an error: Concatenating and inserting functions You can apply special formatting with the options available next to Insert Function: change case, trim out white spaces, identify a substring, or use a regular expression. You can also concatenate multiple fields. This lets you extract just the data you need for the asset fields in Destiny. By applying custom formatting, you can produce values such as the following examples: Given this CSV line: {0} {1} {2} {3} {4} {5} {6} {7} {8} Switch Cisco 4500 869545 $7045.84 106 1/12/2009 2009654 127.0.0.1 By applying custom formatting, you can produce values such as the following: Selection Expression Input Result Insert CSV Columns, concatenating them Insert Source Field, add a hyphen Insert CSV Column, add literals ${5}${3} 106,869545 106869545 ${Site}-${SerialNumber} 106, 86945 106-869545 SW I-${2}-${5} 4500, 106 SW I-4500-106 Insert Function regex* ${4,regex("([0-9]{4})","{$1}")} $7045.84 7045 Insert Function substring* ${7,substring(1,4)} 2009654 2009 Insert Function substrings, concatenating them* ${3,substring(3,4)}${7,substring(1,4)} 869545, 2009654 95452009 Page 8 of 13 Copyright 2010 Follett Software Company 10938A Rev. 13 11-10-A
* When using the "Insert Function" option, make sure to replace the word "field" in the Expression with either a CSV Column number or a defined Source Field name. Substituting field values For a field whose value requires mapping to another value, you can enter a single constant in the Expression box, or set up a lookup table for multiple values. Single value Enter or select the template field at the top and type the value in the Expression text box. This would assign the value to every record in the file. Tip: If the CSV file does not contain barcode numbers, you could set a value for the field "Barcode" of "TBD". This would satisfy the Converter's requirement that all items have barcode numbers. When you import the XML file into Destiny, you would select Always add the incoming item record and assign it the next available barcode in Import Assets to have Destiny auto-assign barcode numbers. Multiple values You can create a lookup table when a source field has several values that each needs to be changed to another value. Click, in the lower left corner of the Source Field Editor, after entering the template field and expression. The Field Value Transforms dialog appears. 1. Click. 2. In the table row that appears, enter the value from the CSV file in the When the field's value is column on the left. 3. Enter the value to which you want it changed in the Change it to column on the right. Continue adding all possible values. 4. To define a default value for a field a value to use if the CSV data does not match any other defined mapping values or if it is missing from a row enter "default" (without the quotation marks) in the left column, and your default value in the right column. Defining a default value is optional. 10938A Rev. 13 11-10-A Copyright 2010 Follett Software Company Page 9 of 13
In this example, the converter will substitute SiteShortNames for their 3-digit codes. It will add "DistWH" to any record without a code. 5. Click when you are done. 6. Back in the Source Field Editor, verify your mapping by reviewing the value in the Preview box. 7. If it's correct, click. 8. Back on the Source Field Definitions tab, you can highlight any of the lines in the bottom pane and review its mapped value in the Preview column in the top pane. Defining a virtual field If your CSV file does not contain a field that you want in your records in Destiny, you can create a virtual field and define its value, as long as the value is the same for every record. You could also define a virtual field and then use it as a component of another field. For example, if the CSV file does not include a field for the required SiteShortName, you can select that template field and define a literal Expression such as "WashHS". Skipping incoming records If you want the Converter to skip (ignore) any assets in the CSV file based on certain criteria, open the Filters tab. Under Skip CSV rows when, select either ANY or ALL conditions. Then, click Add to enter one or more conditions. As the Converter processes each CSV record, it tests its data. If the data match the conditions you define, the Converter skips the record; it does not add it to the import XML file. In the example shown above, the Converter will skip any record whose Barcode is missing or whose manufacturer is ABC Manufacturing. Page 10 of 13 Copyright 2010 Follett Software Company 10938A Rev. 13 11-10-A
Associating the records with their templates Once you've defined all the fields you want to import, you'll need to identify the source field that identifies each row as belonging to a specific asset type in the template file. This serves to group the records so that you do not have to Auto Map each one. This is a field that identifies the asset type, not the item. Once you identify this key field, you'll map each asset type in the CSV file to its asset type in the template. 1. Open the Field to Template Map tab. 2. Select the Key field from the list. The Converter searches the CSV file, displays the number of unique key field values, and lists them in the lower pane. If the list does not contain the correct key field values, clear the Key field selection locked check box, click OK on the warning message that appears, and select a different Key field. 3. In the lower pane, double-click the first row, or highlight it and click. 4. On the Field Mappings dialog box that appears, select the Asset Type from the list at the top. 5. Click. The Converter maps each template field for this asset type to the appropriate source field in the CSV file. 6. If any fields are not mapped and should be, or mapped incorrectly, click the row in the Source Field column and select the correct one from the list that appears. 10938A Rev. 13 11-10-A Copyright 2010 Follett Software Company Page 11 of 13
7. Once all the fields are mapped correctly, click. 8. Repeat steps 3 through 7 for each row in the lower pane of the Field to Template Map tab. 9. Once you've mapped all the assets to the template, click to make sure that the Converter was able to map the assets correctly and that there are no errors. 10. At the top of the Verify Map dialog box is an entry for Errors. If there are any errors, highlight the row and review them in the lower pane. You may need to correct some of the errors in the CSV file and then re-open the file in the Converter. 11. The second row, Unmapped Lines in CSV file, should be 0. If not, return to the Field to Template Map tab and map those. Once you have corrected any errors and mapped all the records, click to save your configuration. You can use this configuration file for future conversions that use the same template file and a different CSV file. Page 12 of 13 Copyright 2010 Follett Software Company 10938A Rev. 13 11-10-A
Running the Converter If you are ready to run the Converter, click. In the Destiny Asset Import XML File dialog box that appears, select the location for and enter the name of the output file. The Converter writes any exceptions to the log file, named output.xml.log. At the end of the log file is a summary count of the number of rows skipped and the number of errors. The fully qualified path to the XML file and the exception log file appears in the confirmation dialog: Important: Make sure you review the log file before you import the XML file into Destiny. It lists the number of converted assets, the number of skipped, unmapped, or badly formed rows, and the number of rows missing required fields or containing mismatched data. In addition, a browser window opens, displaying the first ten records. This allows you to verify that your output XML file is as expected. If it's not, you'll need to adjust your configuration. After reviewing the preview, close the browser window. If your output file is satisfactory, close the Converter by choosing File > Exit from the menu. Importing the XML file into Destiny The last step in the process is to import the XML file into Destiny through Import Assets in the Catalog. 1. Log into Destiny as a district assets manager. If you have assets for a single site, log into that site. Import Assets requires the permission, "Import assets/items". 2. Open Import Assets in the Catalog. 3. If your file does not contain barcode numbers, make sure to select Always add the incoming. 4. Click Browse to locate and select your XML file. 5. The first few times you use the Converter, you may want to Preview the import. Click. 6. When you're satisfied that the results will be correct, click. 10938A Rev. 13 11-10-A Copyright 2010 Follett Software Company Page 13 of 13