User Manual EAM Universal XLS Import/Update Tool for IBM

EAM Software GmbH, Am Stadtgraben 2588677 Markdorf, Germany; tel: +49(0)7544-5069920

e-mail: [email protected], web: http:// www.eam-software.de

User Manual EAM Data Management Tool

for IBM Maximo®, SCCD and TPAEbased products

Fourth Edition (January 2014)

This edition applies to: EAM Data Management Tool V2.0 for Maximo/TPAE Versions 7.1 and 7.5

User Manual EAM Data Management Tool V 2.0

Page 1 of 84

mailto:[email protected]

http://www.eam-software.de/




Table of Contents

Preface............................................................................................................................................6

About the Author.............................................................................................................................8

Product Overview...........................................................................................................................9

1. Summary of Changes...............................................................................................................12

2. EAM Importer - General...........................................................................................................14

2.1. Importer Processing Modes..............................................................................................19

3. EAM Data Management Tool – Simple Import.........................................................................21

3.1. Create Excel Import file.....................................................................................................213.1.1. Manual Creation of the XLS File...........................................................................................213.1.2. Download a XLS Template...................................................................................................223.1.3. Download a Search Result as an Excel Template................................................................25

3.2. Execute the Import............................................................................................................263.2.1. XLS File Upload....................................................................................................................263.2.2. Processing Steps – Features................................................................................................283.2.3. After the Import.....................................................................................................................30

Data Import Summary................................................................................................................................ 30Download of the imported Data as Excel Document..................................................................................30Update of the List View.............................................................................................................................. 31

3.3. Handling of Maximo and Excel Datatypes........................................................................313.3.1. Import of Data from Excel.....................................................................................................313.3.2. Export of Data into Excel......................................................................................................31

3.4. Handling of AUTOKEY Objects.........................................................................................32

3.5. Setting and Changing Object Status during the import.....................................................32

3.6. Handling of Time and Datetime values.............................................................................33

4. EAM Data Management Tool – Specification Import...............................................................34

4.1. Create a Excel import file..................................................................................................34

4.2. Download a Template with specification data...................................................................35

4.3. Download a search result with specification data.............................................................38

4.4. Execute the import............................................................................................................414.4.1. XLS File Upload....................................................................................................................414.4.2. Processing Steps for the Specification Import......................................................................414.4.3. After the import.....................................................................................................................43


Page 2 of 84






5. EAM Data Management Tool – Extended Import....................................................................44

5.1. Create an Excel import file................................................................................................44

5.2. Download a Template for the extended import.................................................................45

5.3. Download a search result with extended data..................................................................48

5.4. Execute the import............................................................................................................495.4.1. XLS File Upload....................................................................................................................495.4.2. Processing Steps for the Extended Import...........................................................................495.4.3. After the import.....................................................................................................................51

5.5. Multilevel Import................................................................................................................515.5.1. Security Groups – Applications – Options............................................................................515.5.2. Failure Class – Problem – Cause – Remedy........................................................................52

6. EAM Data Management Tool – Download Templates.............................................................53

6.1. Create a Template.............................................................................................................53

6.2. Upload Template...............................................................................................................54

6.3. Manage Templates............................................................................................................56

6.4. Search result Download via Template..............................................................................57

7. Memory and Performance Issues............................................................................................58

7.1. Downloading large search results.....................................................................................58

7.2. Importing large amounts of data.......................................................................................59

8. Configuration Options for the EAM Data Management Tools..................................................60

8.1. Configuration Options for the EAM Importer.....................................................................60

8.2. Configuration Options for the EAM Fieldupdater..............................................................64

9. EAM Show Import History........................................................................................................66

10. EAM Fieldupdater...................................................................................................................70

11. EAM Fieldupdater – Select allowed relations and attributes..................................................76

12. EAM Fieldupdater History.......................................................................................................79

13. EAM Power Search................................................................................................................81

14. EAM Mass Delete...................................................................................................................82

Document Change History...........................................................................................................85


Page 3 of 84






Illustration IndexIllustration 1: Components of the EAM Data Management Tool....................................................9Illustration 2: Select Action Menu for EAM Data Management Tool............................................11Illustration 3: Open the Security Groups Application....................................................................14Illustration 4: EAM Signature Options in Security Group application...........................................15Illustration 5: Import Modes and corresponding menu entries.....................................................17Illustration 6: EAM Data Management Tool Searchbar Menu......................................................18Illustration 7: Sidebar Menu in SCCD 7.5.1..................................................................................18Illustration 8: Excel worksheet with $IMPORTERROR column...................................................19Illustration 9: Import Summary Dialog for Continue on Error Mode Simple Import......................20Illustration 10: final XLS file with errormessages in $IMPORTERROR column...........................20Illustration 11: Select Action menu option to download an empty XLS template.........................23Illustration 12: Screenshot of an empty Template in PERSON application.................................24Illustration 13: Select Action menu option for search result download.........................................26Illustration 14: Select Action menu Item EAM Data Importer.......................................................27Illustration 15: Import Data dialog box..........................................................................................28Illustration 16: Error message during import dialog box...............................................................29Illustration 17: Data import summary dialog.................................................................................30Illustration 18: Screenshot XLS file with specification attributes..................................................35Illustration 19: Select Action menu entry EAM Template for Spec Data......................................36Illustration 20: Select Classification / specification for XLS template...........................................37Illustration 21: Select available Class Structure from Lookup Dialog...........................................37Illustration 22: Internet Explorer open for save dialog..................................................................38Illustration 23: Screenshot Excel Worksheet names for multiple specifications in one file..........38Illustration 24: Select Action menu entry Download search result with specification data..........39Illustration 25: Dialog Create XLS search result download with specification data.....................40Illustration 26: Worksheet for extended import with child object..................................................45Illustration 27: Select Action menu entry EAM generate extended XLS template.......................46Illustration 28: Dialog: Create extended XLS Template...............................................................47Illustration 29: Multilevel Import File for Security Groups - Applications - Options......................52Illustration 30: Select Action menu item EAM Upload Template..................................................55Illustration 31: Upload new Template dialog................................................................................56Illustration 32: Manage Download Templates dialog...................................................................56Illustration 33: Download Searchresult into Template - Apply Template.....................................57Illustration 34: EAM Show Import History Select Action menu item.............................................66Illustration 35: Show Import History dialog...................................................................................67Illustration 36: Filter data in the Import History dialog..................................................................68Illustration 37: Import History with Continue On Error Mode........................................................69Illustration 38: Select Action menu item EAM Fieldupdater.........................................................71Illustration 39: EAM Fieldupdater dialog; change attribute DEPARTMENT to IT........................72Illustration 40: Append a string to a description with the fieldupdater..........................................73Illustration 41: Confirmation Question for the EAM Fieldupdater.................................................74Illustration 42: Select Action menu item EAM Enter allowed Fields for Update Tool...................77Illustration 43: EAM Fieldupdater Filter Configuration dialog in Maximo 6.2...............................78Illustration 44: EAM Fieldupdater History dialog..........................................................................79Illustration 45: Field Updater History with error messages due to an invalid date.......................80Illustration 46: EAM Power Search dialog with sample search criteria........................................81Illustration 47: Select Action menu item EAM Mass delete..........................................................83Illustration 48: EAM mass delete confirmation question dialog....................................................83


Page 4 of 84






Illustration 49: EAM Mass delete collected error messages........................................................84


Page 5 of 84






Preface

This user manual describes the components, the usage and the features of the the EAMData Management Tools V2.

You should study this user manual if

• you want to use the EAM Data Management Tool in your Maximo or SmartCloudControl Desk (SCCD) installation

• you want to import existing data from Excel into Maximo

• you want to export data from Maximo to Excel

• you want to update or delete large amounts of data with a simple interface

Using the tools is usually quite easy and intuitive. If you are familiar with your Maximo orSCCD environment, then it should be easy to use the EAM Data Management Tool.

However, especially the EAM Importer is quite complex and it is recommended that youread this manual. This can help you to avoid some pitfalls, save some time in the longrun and gives you some tips when working with the tool.

The manual assumes that the tool is already installed in your environment. This manualdoes not contain any installation instructions. This is a separate PDF file which youshould have received together with the EAM Data Management Tool software packageand your license keys.

Users of a previous version of the EAM Data Management Tool (or the EAM UniversalXLS Import/Update Tool) should also read this user manual. Some functionality is new,other parts of the software are improved. The main changes and improvements of thisnew version are summarized in chapter 1. Summary of Changes on page 12.

The screen-shots in this manual where created using different Maximo versions (MaximoAsset Management 6.2.8, Maximo 7.1.1.x, Maximo 7.5.0.x with tivoli09 skin, Maximo7.5.0.x with tivoli13 skin, SCCD 7.5.1 with tivoli13 skin), different browsers (InternetExplorer, Mozilla Firefox, Google Chrome; all in different version) and different clientoperating systems (various Windows and Ubuntu Linux versions). Depending on yourenvironment your dialogs may and will look different.

This manual often uses the phrase “Maximo application” or “Maximo/SCCD application”.This does not imply any limit and is just for easy readability. You can install and usethe EAM Data Management Tools in every system based on the Tivoli ProcessingAutomation Engine (TPAE) 7.1 or 7.5. You can use the software in “power-apps” (aapplication like Assets with a list view and detail view(s) of one record) and in “single-page-apps” (like Currency Codes, Exchange Rates, Conditional ExpressionManager,...). You can even use the software in custom applications which you havedeveloped yourself or applications installed by some industry solutions (ServiceProvider, Transportation, Oil and Gas, Asset Configuration Manager,...)


Page 6 of 84






The Homepage of EAM Software GmbH contains a sample library. Please visithttp://www.eam-software.de/de/eam-datamanagement-tool/import-templates andfollow the links for your TPAE version and application.

Visit the YouTube channel of EAM Software for an overview of the possibilities and theuse of this tools. There you will find a series of educational videos in English andGerman.

http://www.youtube.com/user/EAMSoftware

Demo Excel Import Files http://www.eam-software.de/de/eam-datamanagement-tool/import-templates

We appreciate our feedback. Please help to make the sample library extensive andvaluable.

If you have created an import template which

•is useful for other users or customers

•is not yet included in the sample library

•does not violate any privacy, confidentiality polices of your company

•you are willing to share with the community

then please send your template to [email protected] or [email protected].

We are happy to include your contribution into the sample library (on your request withoutdetails of the sender). If required we will make the data anonymous.


Page 7 of 84




http://www.eam-software.de/de/eam-datamanagement-tool/import-templates


http://www.youtube.com/user/EAMSoftware






About the Author

Wolfgang Fiedler is a Software Engineer, IBM Maximo Deployment Professional andOracle Certified Java Programmer. He is self-employed and works for EAM SoftwareGmbH in Germany and for EAM Swiss GmbH in Switzerland. He is responsible fordesigning, implementing and testing custom solutions and extensions in IBM Maximoand SCCD. He is also the main developer for the EAM Data Management Tool. Visithttp://www.fiedler-it.at for more information.

Comments are welcome! This manual should be as helpful as possible. Please sendcomments about this publication to [email protected].

Do you have the current version of this manual? Please visit http://www.fiedler-it.at for themost recent version of this user manual for download or browse online. The onlineversion is usually the most recent and may contain comments from other uses andlinks to sample import files and templates.


Page 8 of 84


http://www.fiedler-it.at/


http://www.fiedler-it.at/





Product Overview

This manual describes the different components of the „EAM Data Management Tool“.The EAM Data Management Tool is not one single Tool and it is not a Maximoapplication itself. The EAM Data Management Tools is a collection of severalindependent tools. Illustration 1: Components of the EAM Data Management Toolshows its components:

The main components are:

The “EAM Mass Delete” or Batch delete program allows you to delete all records whichare currently shown in the list view of your Maximo application. See chapter 14. EAMMass Delete on page 81 for further information.

The „EAM Fieldupdater“ allows you to set one or more attributes for a group of records(selected records in the list view of an application) or for related records which can bespecified via a relation. You can limit the attributes and relations available for updatewith the EAM Fieldupdater with the “EAM Enter allowed Fields for Update Tool”menu option. See chapter 10. EAM Fieldupdater on page 69


Page 9 of 84

Illustration 1: Components of the EAM Data Management Tool






The EAM Power Search allows you to search for records in the list view of Maximoapplications. You can use any persistent attribute of the Maximo object and not justthose available in the Advanced Search dialog. For more information refer to chapter13. EAM Power Search on page 80

The EAM Importer for IBM Maximo is the main component of the EAM Data ManagementTools and provides several valuable functions. It allows the import of new data and themodification of existing data in IBM Maximo. As a prerequisite the data must beavailable in the Microsoft Excel document format. The EAM Importer also containsfunctionality for creating import templates and to download the current records in thelist view of an application into Microsoft Excel. The main part of the following usermanual is dedicated to the EAM Importer.

• Chapter 2. EAM Importer - General on page 14 explains some general concepts

• Chapter 3. EAM Data Management Tool – Simple Import on page 21 explains thesimple Import. The simple import is explained in more detail because it explains thebase concepts.

• Chapter 4. EAM Data Management Tool – Specification Import on page 34 explainsthe import of specification data and

• Chapter 5. EAM Data Management Tool – Extended Import on page 43 explainsthe import of extended data.

• A new and useful feature called Templates are described in chapter 6. EAM DataManagement Tool – Download Templates on page 52.

One question remains: Where can I find the EAM Data Management Tool in Maximo?The EAM Data Management Tool is a menu option in the Select Action menu on thelist view tab of your Maximo installation. (This of course depends on several factorslike license, security group,...) Illustration 2: Select Action Menu for EAM DataManagement Tool from page 11 shows all those menu entries.


Page 10 of 84







Page 11 of 84

Illustration 2: Select Action Menu for EAM Data Management Tool






1. Summary of Changes

This section describes the changes that were made to this edition of the book and to thecurrent version 2.0 of the EAM Data Management Tool software.

Continue on Error Mode. With the current version of the EAM Importer it is possible tochoose between two processing modes: Stop on error or continue on error. This ishelpful if the import data is of lower data quality and imports may fail. See 2.1. ImporterProcessing Modes on page 19 for more information.

Support for XLS and the new XLSX Excel file format. The current version does not usethe old (and meanwhile unmaintained) jxl.jar library but uses the new and activelydeveloped Apache POI library for the Excel file format handling. This supports theolder binary Microsoft Excel file format (.xls extension) and the new Office Open XMLformat (.xlsx or .xlsm extension). The import therefore accepts both file formats. Thefile format for new Excel files generated by the Maximo/SCCD server (search resultdownload, template download) can be controlled by a System Property inMaximo/SCCD. Default setting is the older XLS file format.

Templates. To download search results you can now use predefined templates.Templates specify which attributes you want to export and in which order they appearin the downloaded result file. It is possible to upload new templates, to associate themto the appropriate Maximo-application, to manage those templates and to apply atemplate to the current search result (download the search result using the selectedtemplate). Templates can also be used with extended search results and specificationdata. For further information on this new feature read chapter 6. EAM DataManagement Tool – Download Templates on page 52.

License Keys and License Management. The current version of the EAM DataManagement Tool needs two license keys in your environment. If you have bought theEAM Data Management Tool you receive those license keys automatically. If you havenot received any license keys then please contact the EAM Software GmbH [email protected]. If you want to evaluate the software you can request a (timelimited) license key free of charge. This allows you to license only those modules youneed only in those applications where you need them for as long as you need them.License Keys are generated per customer and are personalized with customerinformation.

Specify default values for data via System Properties. This feature is useful if you wantto specify some attribute values which should be applied to every import even if thisattribute is not part of the import data file. See chapter 8. Configuration Options for theEAM Data Management Tools on page 59 for further information.

Specify limits and performance data via System Properties (e.g. maximum number ofrows for an import, maximum number of errors during an import, suppression of the


Page 12 of 84



http://poi.apache.org/





creation of the data dictionary in the result files) The corresponding System Propertiesare explained in chapter 8. Configuration Options for the EAM Data ManagementTools on page 59.


Page 13 of 84






2. EAM Importer - General

The EAM Importer for IBM Maximo processes data which is available in the Excel Fileformat (XLS files from Excel 95, 97, 2000, XP and 2003). The current version of theEAM Data Management Tool can also process the new XLSX file format which is usedfrom Excel 2007 onwards.

As a precondition to use the mentioned tools you need access to the corresponding menuentries. Access can be granted in the Security Groups application which can beopened from the Go To menu (see Illustration 3: Open the Security GroupsApplication)

The Maximo administrator can then enable or disable the individual signature options forthe selected Maximo application. The following Illustration 4: EAM Signature Options inSecurity Group application on page 15 shows the Security Group Application (in SCCDwith tivoli13 skin). All the EAM Signature Options are enabled for the Locationsapplication.


Page 14 of 84

Illustration 3: Open the Security Groups Application






The Importer has three operational modes:

• The “Simple Import” (see chapter 3. EAM Data Management Tool – Simple Import onpage 21).

• The “Specification Import” (see chapter 4. EAM Data Management Tool – SpecificationImport on page 34)

• The “Extended Import” or 1:n Import (see chapter 5. EAM Data Management Tool –Extended Import on page 43)


Page 15 of 84

Illustration 4: EAM Signature Options in Security Group application






The Simple Import allows you to import or update “flat” data in Maximo. With the simpleimport you cannot add or modify specification attributes or child objects. You may knowthis functionality from version 1.0 of this product.

The Specification Import enables you to import or update Maximo objects withspecification attributes like assets, locations or tickets. Specification data is importedtogether with the main object from one data source.

The Extended Import allows you to import or update Maximo objects together withcorresponding data in child data sets like ASSET with SPAREPARTS or JOBPLAN'swith their corresponding JOBTASK data.

All import modes share common concepts. For every import mode you can:

•Download an empty Microsoft Excel Template

◦Choose “EAM Template Generator” to download an importer template for the SimpleImporter (without specification attributes or related child data)

◦Choose “EAM Template for Spec Data” to download an importer template withspecification data

◦Choose “EAM Generate extended XLS Template” to download an importer template withrelated child data.

•Download the current records in the application list view (the current search result) as aMicrosoft Excel file.

◦Choose “EAM XLS Searchresult Download” to download the current search result of theapplication without specification data or related child data

◦Choose “EAM XLS Searchresult with Spec Data” to download the current search resultof the application with its specification data attributes

◦Choose “EAM XLS Extended Searchresult Download” to download the current searchresult with child data.

•Import new or modified data into Maximo. This is accomplished with the menu entry “EAMData Importer”. The software automatically detects the import mode to use.

The EAM Data Management Tool is not a Maximo application. Instead it is a set of “SelectAction” menu entries which can be installed and enabled in (almost) any Maximoapplication where you want to have the tools available.

The action menu of an IBM Maximo application can contain the following menu items(depending on the application, the license, the installation or the security setting onlysome of these menu items may be available to users)


Page 16 of 84






If you are using IBM Smart Cloud Control Desk 7.5 or Maximo Asset Management 7.5.0.2with enabled side bar the EAM Data Management Tool components are also availablein the sidebar of your Maximo application (see Illustration 7: Sidebar Menu in SCCD7.5.1 on page 18).

Some often used features of the EAM Data Management Tool are also available in thesearch bar. The data import is the default action when you click on the search barentry, other options can be selected from the drop down list of the entry.


Page 17 of 84

Illustration 5: Import Modes and corresponding menu entries

Menu Items for Simple Mode

Menu Items for Specification Mode

Menu Items for Extended Mode






The following chapters describe each import mode in detail.


Page 18 of 84

Illustration 7: Sidebar Menu in SCCD 7.5.1






2.1. Importer Processing Modes

The EAM Data Importer has two processing modes:

Stop on Error Mode: This is the default mode and is available since the first version ofthe EAM Data Management Tool. In this mode the import stops after the first error. Adetailed error message is displayed to the user (usually with the line number where theerror occurred).

Continue on Error Mode: If an error occurs in a line in the Excel file the error messageis not displayed to the user. Instead the error message is written in the column$IMPORTERROR in the Excel import file. Furthermore the import is not stopped, butcontinues with the next line in the Excel file. After the import the user can filter thecolumn $IMPORTERROR and find those objects where an error occurred. If the errorcan be traced to a specific attribute, than this attribute is marked with a red backgroundcolor. This mode is very useful if the data quality of your input data is not perfect anderrors might occur. (An example might be that you want to import new assets with theirlocation but corresponding location entries might not be available)

To enable the Continue on Error mode you simply create a column with the name$IMPORTERROR (the leading $ sign is important! This distinguishes the column fromregular attributes). The position of this column does not matter. The column$IMPORTERROR could be the first column, the last column or anywhere in between.

The column name is case insensitive. $IMPORTERROR or $ImportError are both valid.

The following example illustrates the behavior of the Continue on Error Mode:

Above illustration shows an Excel import file for updating some assets. This sheet alsocontains a column $IMPORTERROR. When importing this file the importer recognizesthe $IMPORTERROR column and switches to the Continue On Error Mode. After theimport the following summary dialog is displayed to the user:


Page 19 of 84

Illustration 8: Excel worksheet with $IMPORTERROR column






The import summary for this file shows that 8 records where modified and (from this 8records) 4 records had an error.

The final Import file which is pushed back to the client is shown in Illustration 10: final XLSfile with errormessages in $IMPORTERROR column. The line height is adjustedbecause the errormessages in $IMPORTERROR usually have 2 lines.

It is easy to see the problematic rows. The user can now correct the errors and re-importthe excel document. It is not required to clear the $IMPORTERROR column. This isdone by the importer internally.


Page 20 of 84

Illustration 9: Import Summary Dialog for Continue on Error Mode Simple Import

Illustration 10: final XLS file with errormessages in $IMPORTERROR column






3. EAM Data Management Tool – Simple Import

The Simple Import allows the import and update of flat data in IBM Maximo and can beused in all Maximo applications. It is not possible to import specification attributes (seechapter 4. EAM Data Management Tool – Specification Import on page 34 for moreinformation on that topic). The simple import can not import or update related objects. Ifyou need this feature than use the extended import which is described in chapter 5.EAM Data Management Tool – Extended Import starting at page 43.

3.1. Create Excel Import fileThe data for the import or update must be available in Microsoft Excel file format. There

are four ways to create the needed file:

1.Manual creation of the Excel file according to the specification

2.Download of an empty Excel template for the current IBM Maximo application andcomplete the data.

3.Download of search results for the current IBM Maximo application

4.Download of a search result with a download template

NOTICE:

Independent of the method used to create the Excel file you should note the following:

1.An Excel file should only contain columns which either have data or should be set tonull. Therefore a downloaded template or search result should be reduced to theneeded columns. The other columns must be deleted!

2.The order of the columns in the Excel file is important. Check the correct order with asample record and reorder the columns if necessary. The importer processes thecolumns from left to right.

3.1.1. Manual Creation of the XLS FileThe EAM Importer for IBM Maximo expects the data in a specific form. The following

conditions must be met:

•There must be one worksheet with the name “Simple”. This worksheet contains the datawhich is imported or updated.

•The first row of the worksheet contains the title of the attributes. For the manual creationof the Excel file this row can be left empty since the importer does not evaluate it.

•The second row contains the attribute names.

•The third row is designated for an example record and can be left empty.

•All further rows starting (and including) from row number four are considered as datarows and are evaluated by the importer. IMPORT starts at row four!

•The available attributes in the excel file are read from the file from left to right. Theattributes for the MBO (Maximo Business Object) are set in the same order as they areread from the excel file.


Page 21 of 84






NOTICE:

The attributes on the MBOs are set in the same order in which they appear in the Excelfile. An exception to this are attributes which are part of the primary key of the Maximoobject in question. Key attributes are always set first. The attributes are set with theusual methods of the MBOs and the inherent business logic is executed. The order ofthe attributes in the excel document is therefore sometimes important. Example: theattribute PARENT on a location object can only be set to a value if the SYSTEMID isalready filled in. If you are not sure about the correct order of the attributes then makea test with one sample record. If unsure check also the order in the User Interface.

3.1.2. Download a XLS TemplateAn empty XLS template for the current Maximo application can be downloaded via the

action menu “EAM Data Management Tool” → “EAM Template Generator”.


Page 22 of 84






The created template fulfills the same conventions which are required for the manualcreation of the Excel file:

• The attribute names have a background color. The following screen-shot shows anempty template for the PERSON application.


Page 23 of 84

Illustration 11: Select Action menu option to download an empty XLS template






The background colors have the following meaning:

orange: The attribute is (part of) the primary key

blue: The attribute is required in the database (other attributes mayalso be required by the business logic of the object).

light green: The attribute is the unique key of the object.

light gray: The attribute is non-persistent.

White: The attribute is a “normal” persistent attribute of the object.

Lavender: A cell is set by the import to this color if the cell in the XLS file isempty, but the corresponding attribute on the Mbo has avalue and is read-only (used by the Extended Import)

red: Used for the separation column to separate the columns of themain object from the specification attributes (for thespecification import) or from the attributes of the child object(for the Extended Import).

For templates and search results with specification attributes the following additionalcolors apply:

Light green: Specification attribute with data type ALN

Blue: Specification attribute with data type NUMERIC

Lime: Specification attribute with data type TABLE (only available inMaximo 6 and later)

• The created Excel template also contains a second worksheet which contains the datadictionary with detailed information for every attribute (default value, data type, fieldlength,...)

• A third worksheet contains above color legend.


Page 24 of 84

Illustration 12: Screenshot of an empty Template in PERSON application






NOTICE:

A red background and white font in the attribute cells of downloaded search results isused if the value of the attribute could not be retrieved due to Maximo configurationerrors (missing relations) or internal errors (like database errors)

NOTICE:

The following attributes are not included in the template because they are always updatesvia the business logic of the objects:

•CHANGEBY, CHANGEDATE

•ENTERBY, ENTERDATE

•HASPARENT, HASCHILDREN

•HASLD

•LANGCODE

3.1.3. Download a Search Result as an Excel TemplateIf you want to update existing data in an IBM Maximo application then you can download

an Excel file with the existing data. First specify your search criteria in the list view ofthe application and select “EAM Data Management Tool” → “EAM SearchresultDownload” from the action menu.


Page 25 of 84






The downloaded file contains all information from the empty Excel Template plus the datafrom the current search result.

The generated Excel file contains almost all attributes of the underlying main MaximoObject. If you need to export a large amount of objects you should consider the newDownload Template functionality (see chapter 7. Memory and Performance Issues onpage 57 for more information on performance and chapter 6. EAM Data ManagementTool – Download Templates starting on page 52 for more information on downloadtemplates).

3.2. Execute the Import

3.2.1. XLS File UploadTo start the import of data select “EAM Data Management Tool” → “EAM Data Importer”


Page 26 of 84

Illustration 13: Select Action menu option for search result download






from the Select Action menu from the list view of your Maximo application.

The following dialog is opened:


Page 27 of 84






Select the file and press the “Import Date” button. The file is sent to the Maximo serverand will be processed.

3.2.2. Processing Steps – Features• The Excel file will be analyzed. The following checks are performed:

• Is the uploaded file an Excel document?

• Is there a worksheet with the name “Simple”?

• Are there attribute names in the second row of the worksheet “Simple”?

• Are the attribute names unique?

• Are data rows available?

In case of an error an error message is displayed to the user and the import is stopped.

• Analyze of the target object (the current application object)

• Check if the target object is valid. The name is automatically determined based on theMaximo application from where the import is started.

• Determine the object type. Is it a System Object (e.g. PERSON), SITE Object (e.g.LOCATION, ASSET,...) or a ORG Object (e.g. LABOR, CRAFT,...)?

• Determine the unique ID attribute name. This is unique for every object and assignedinternally from Maximo. For example ASSETUID for Asset Objects or LABORID forLabor objects.

• Determine the key attribute(s) of the object.

• Check if all required attributes are available in the Excel document.

• In case of an error an error message is displayed to the user and the import is canceled.


Page 28 of 84






• For every data row (remember: starting from row four in the Excel file) do the following:

• Based on the information (available attributes in the excel document, known properties ofthe object type like key attributes, unique attributes, object type and the available data inMaximo) decide if we update existing data or insert new data.

• Prior to creating a new object the default insert SiteID, default insert OrgID, defaultItemSet and default CompSet are set on the MBO-Set (depending on the object type)

• For a new object the key attributes are set first.

• Set other attributes in the same order as they appear in the Excel document.

• Save the object

• If there is an error (either during setting of attributes or during saving) the followingbehavior depends on the processing mode “Stop on Error” or “Continue on Erorr” (see2.1. Importer Processing Modes on page 19)

• If “Stop on Error” is used (no $IMPORTERROR column) then an error message isdisplayed to the user and the import is aborted. Every error message during importcontains the line number of the Excel file and the attribute name which causes theproblem.

• If “Continue on Error” is used (a column $IMPORTERROR is available in theworksheet) the errormessage is not displayed to the user but written in the column$IMPORTERROR of the corresponding row. The import continues with the nextrow.

• Data rows from the Excel document which would modify an existing Maximo Objectwhich is read-only are skipped (e.g. already saved LABTRANS records)

NOTICE:

• If the attribute SITEID is missing in the Excel document but is required for the object thedefault insert site for the current user will be used for the import. Furthermore a columnwith the SITEID is added to the Excel document.

• If an attribute in the Excel document is empty (no value in the Excel cell) then theattribute is set to NULL. It is therefore important to remove all columns from the exceldocument which should or cannot set to null or fill all columns with the appropriate values

• Attributes are only set if the new value from the Excel document is different from the


Page 29 of 84

Illustration 16: Error message during import dialog box






current value in the MBO!

• If the unique ID attribute is missing or empty on the Excel document then this informationis added to the Excel file.

3.2.3. After the Import1. A dialog with the Import summary is shown to the user

2. The uploaded Excel file (with added information like unique ID values or selectedSITEID) is sent back to the user

3. The list view of the current Maximo application shows the records which were inserted ormodified during the last data import.

Data Import Summary

After a successful import a import summary message is displayed for the user.

This summary includes the following information:

•Number of newly created records / objects.

•Number of modified objects. Objects are counted even if no attribute values weremodified because the attribute values in the Excel document were identical to theexisting values.

•Number of skipped objects (objects which are read-only and could not be modified)

•Number of records with errors.

Download of the imported Data as Excel Document

Depending on the available data in the XLS file values may be added to the XLSdocument (unique ID values or the default insert SITEID for the current user). Theresulting Excel Document is downloaded to the client.

This feature is important if there is an error during the import.


Page 30 of 84

Illustration 17: Data import summary dialog






Example:

You want to import 20 new ASSET records and there is an error in line 10. The import isaborted, an import summary is displayed and the Excel file is sent back to the client.The first records which where correctly imported contain a value in the unique IDattribute ASSETUID.

If you correct the error in line 10 and re-import the Excel document then the first 9 ASSETrecords will be identified by the known ASSETUID and therefore will not be insertedtwice! The following rows (10, 11, 12, …) in the Excel document will be inserted asnew ASSET objects.

In case of an error it is therefore important to continue with the downloaded Exceldocument to avoid duplicate records.

Update of the List View

After you close the import summary dialog the list view of the current Maximo applicationshows the currently inserted and modified records. Internally a where-clause is createdwith all the unique ID values of the affected Maximo objects. This update of the listview only happens if not more than 500 records are affected or inserted. Otherwise thecreated SQL query would get too long and a database error might occur.

3.3. Handling of Maximo and Excel Datatypes

3.3.1. Import of Data from ExcelAttributes of Maximo Objects can have various datatypes. Depending on the datatype of

the attribute and the formatting of the Excel cell the processing differs. The processingis done in the following order:

1.If the Maximo attribute is of datatype „UPPER“, „LOWER“, „ALN“, „LONGALN“, „CLOB“,„YORN“ or „GL“ the content of the Excel cell is interpreted as string and the objectattribute value is set as string.

2.If the Excel cell is formatted as date then the Maximo object attribute is set as date.

3.If the Excel cell is formatted as Number or Currency, then the Maximo object attribute isset as double value.

4.All remaining attributes are read as string from the Excel Cell and set as string value onthe Maximo object.

3.3.2. Export of Data into ExcelWhen downloading a search result as Excel document then the Excel cells have the

following data format:

1.Maximo attributes with the datatypes „UPPER“, „LOWER“, „ALN“, „LONGALN“, „CLOB“,„YORN“ and „GL“ will be exported as strings.

2.Maximo attributes with the datatypes „AMOUNT“, „DECIMAL“, „DURATION“, „FLOAT“,„INTEGER“, “BIGINT” and „SMALLINT“ will be written as float values in the Excel cells.

3.Maximo attributes with the datatypes „DATE“ and „DATETIME“ will be written as Datevalues. The cell format is „dd.MM.yyyy“ for DATE and „dd.MM.yyyy hh:mm:ss“ for


Page 31 of 84






DATETIME

4.Maximo attributes with the datatype “TIME” are formatted as Excel date format with theformatting „hh:mm:ss“.

NOTICE:

Maximo attributes with the datatypes „BLOB“, „CRYPTO“ and „CRYPTOX“ are notexported!

The following attributes are not included in the template because they are always updatesvia the business logic of the objects:

•CHANGEBY, CHANGEDATE

•ENTERBY, ENTERDATE

•HASPARENT, HASCHILDREN

•HASLD

•LANGCODE

3.4. Handling of AUTOKEY ObjectsThe import of AUTOKEY Objects is a special case. Maximo assigns the primary key or a

part of the primary key itself. One example is Preventive Maintenance. PMNUM is theautokey column and therefore cannot be defined in the Excel document.

For AUTOKEY objects two columns are added in the Excel document!

•The column PMNUM. This is the autokey column which is filled by Maximo.

•The column PMUID. This is the unique ID column and will also be written to the Exceldocument (like for other objects)

3.5. Setting and Changing Object Status during the import

For imports and updates with the EAM Import tool you can include the attribute STATUSin the import file. The way of processing depends on whether the Maximo object is astateful object (Mbo is an instance of StatefulMbo) or not.

•If the object is not stateful then the importer handles the STATUS attribute like everyother attributes and simply set the attribute to the new value

•If the object is stateful a changeStatus call for the Mbo (StatefulMbo) is executed. Forstatus changes during an initial import or an update corresponding entries for thestatus history are created and are visible in the status history dialogs (e.g. View WorkOrder History in application Work Order Tracking)

You can also specify values for the attributes STATUSDATE and NP_STATUSMEMO

The attributes STATUSDATE and NP_STATUSMEMO are ignored during the import ifyou do not set a value for the attribute STATUS.


Page 32 of 84






3.6. Handling of Time and Datetime valuesDate and time values from the XLS import file are interpreted as local times for the user

executing the import. Therefore it is important that you set a correct time zone in theuser profile executing the imports. If no time zone is specified in the user profile thedefault timezone (the time zone from the Maximo server) is used (which might becorrect if all your users and the server are in the same time zone).


Page 33 of 84






4. EAM Data Management Tool – Specification Import

The Specification Import allows you to:

1. Insert new IBM Maximo objects together with their specification attributes

2. Add a specification to a IBM Maximo object and set values for the specification attributes

3. Update specification attribute values

The Specification Import can only be used for Maximo objects

• having a CLASSSTRUCTUREID -attribute and

• a “Specifications” tab is available for in the application user interface.

4.1. Create a Excel import fileSince the Specification Import is an extension of the Simple Import mode, some key

concepts remain the same. The Excel Format is the same as for the Simple Importexcept for the following conditions:

•A worksheet in the Excel File contains the specification import data for oneCLASSSTRUCTUREID.

•A XLS import file for Specification import can contain more than one worksheet with data.This allows you to import different IBM Maximo objects with differentCLASSSTRUCTUREID's within one import.

•The name of the worksheet for the specification import starts with “Specification_” and isfollowed by the CLASSSTRUCTUREID.

•After the last column of the main object attributes there is a separator column. Thetemplate generator with specification data and search result download withspecification will insert an empty separation column with a red background colour.

•The second row of the separator column contains the Name of the Specification objectsurrounded with “!”, e.g. !ASSETSPEC!

•On the right-hand side of the separator column are the specification attributes for thisCLASSSTRUCTUREID. The second row contains the specification attribute names.

•Specification attributes can have one of three different data types. These are ALNVALUE,NUMVALUE or TABLEVALUE. The template generator for specification data or theXLS result download with specification data will colorize the specification attributename. The colors are defined in the worksheet “Colorlegende” which is generated forevery template or search result download.

•Every Maximo object together with the specification attribute values have to be entered inone single row of the XLS worksheet.

•If you want to insert new data together with the specification attributes into Maximo youmust make sure, that the CLASSSTRUCTUREID attribute is set for the main object.This can be accomplished with either setting attribute directly on the main object (acolumn for the CLASSSTRUCTUREID is available for the main object) or by settingother attributes which implicitly set the CLASSSTRUCTUREID (e.g. setting the rotatingitem (attribute ITEMNUM) for an ASSET)


Page 34 of 84






As stated above, attribute values of a main Object can be set to NULL (can be cleared) byletting the corresponding Excel cell empty. For specification attributes this behavior isdifferent. If you want to set a specification attributes to NULL you have to use thespecial value ~null~ in the import file ! The reason for this different behavior is asfollows: Assets can get default values for specification attributes from rotating itemsassociated to them. Empty specification attributes in the import file would haveoverwritten those default values.

Writing a XLS Import file from scratch is a time consuming and error prone task. It istherefore much more convenient to generate an empty template and fill it with newdata or download a search result with specification data.

Please download a template or a search result with specification data and make yourselffamiliar with the file layout of the XLS document.

The following screenshot shows the specification attributes for the CLASSSTRUCTID1001 (PUMP \ CNTRFGL) used in the IBM-Maximo demo database. Here you can seethe red separation column and the specification attributes associated with this classstructure. The third row contains a demo data set which has no functional impact andwhich can alternatively be cleared.

Another starting point are some demo files which can be downloaded from the homepageof EAM Software GmbH. (see http://www.eam-software.de).

4.2. Download a Template with specification dataAn empty XLS Template for the specification import can be downloaded via the action

menu item “EAM Data Management Tool” → “EAM Template for Spec Data” (seeIllustration 19: Select Action menu entry EAM Template for Spec Data).


Page 35 of 84

Illustration 18: Screenshot XLS file with specification attributes







This command opens a dialog box where you can select the CLASSSTRUCTUREID forthe template generator. For each selected CLASSSTRUCTUREID a templateaccording to the specifications described above will appear in the result XLS templatefile.


Page 36 of 84






If you click on the lookup you can select from the available classifications for the currentman object.


Page 37 of 84

Illustration 21: Select available Class Structure from Lookup Dialog






After selecting the Classifications click OK. The template is generated and sent to theclient where you are prompted to save or open the XLS file (depending on the clientconfiguration).

The template for the above selected classifications contains the following worksheets:

• The worksheet “Simple” for the Simple import (see the above chapter for a description ofthe simple import)

• The worksheets “Specification_1001”, “Specification_1002”,... for the selectedclassifications

• The DataDictionary

• The Colorlegende

Note:

If a specification does not contain specification attributes then no worksheet for thisspecification is created! The CLASSSTRUCTUREID for those specifications can be setvia the Simple Importer on the worksheet “Simple”.

4.3. Download a search result with specification dataIf you want to update specification attributes of existing data (eg. Assets, Locations, Items)

you could start by creating a “Searchresult with Spec Data “ file that contains yourexisting data.

To do so follow these steps:

1.Use the Filter or the advanced search to limit the objects in the list view to those youwant to update


Page 38 of 84

Illustration 23: Screenshot Excel Worksheet names for multiple specifications in one file






2.Select “EAM XLS Searchresult with Spec Data” from the action menu

The downloaded Excel document contains nearly all attributes of the Maximo Object. This issimilar to the simple search result download.

To update specification attributes and to import the downloaded Excel file this search result isnot best practice (you would need to delete a lot of attributes from the file before you can re-import it). Therefore , in this case it is recommended to use download templates

3. The “Create XLS Download out of search results with Specification” Dialog will beopened


Page 39 of 84

Illustration 24: Select Action menu entry Download search result with specification data






4. If you click OK the XLS File will be generated and sent back to the client.

The generated XLS file contains all records from the current search result in the list view,but these records may be distributed across different worksheets.

•If the Maximo object does not have an attribute CLASSSTRUCTUREID, it is on theworksheet “Simple”

•If the attribute CLASSSTRUCTUREID is available and is empty the Maximo object is alsoon the worksheet “Simple”

•If the attribute CLASSSTRUCTUREID has a value but the specified specification doesnot have specification attributes, then the Maximo object is also on the worksheet“Simple”

•If the attribute CLASSSTRUCTUREID has a value and there are specification attributesfor this specification, then the Maximo object is on the corresponding worksheet for thisspecification, e.g. “Specification_1001” for CLASSSTRUCTUREID 1001.

Before you can use the Template be sure to:

•Remove any columns you do not want to set during the import

•Keep the unique ID column in the template (these attributes have a light greenbackground). For new data leave the field empty and the importer will insert the uniqueID value for the newly created Maximo object in this column.

•Remove worksheets for CLASSSTRUCTUREID where no data should be inserted.

4.4. Execute the import

4.4.1. XLS File UploadThe import or update of specification data is started from the action menu in the list view


Page 40 of 84

Illustration 25: Dialog Create XLS search result download with specification data






of the application.

The following dialog is opened:

Select the file from your file system and press the “Import Data” button. The XLS file issent to the Maximo server and will be processed.

4.4.2. Processing Steps for the Specification Import• The Excel file will be analyzed. The following checks are performed:

• Is the uploaded file an Excel document

• Are there any worksheets were the name starts with “Specification_”

• Are there attribute names in the second row of the worksheets

• Are the attribute names on the worksheet unique

• Are data rows in the worksheet available

• Is there a separation column between the attributes of the target object and thespecification attributes

• Is the CLASSSTRUCTUREID parsed from the worksheet name valid

• In case of an error an error message is displayed to the user and the import of thisworksheet is canceled.

• Analyzing the target object (the current application object)


• Determine the object type. Is it a System Object (e.g. PERSON), SITE Object (e.g.LOCATION, ASSET,...) or a ORG Object (e.g.. LABOR, CRAFT,...).

• Determine the unique ID attribute name. This is unique for every object and assignedinternally from Maximo. For example ASSETUID for Asset Objects or LABORID for


Page 41 of 84






Labor objects.



• In case of an error an error message is displayed to the user and the import is canceled.

• For every data row (remember: starting from row four in the Excel file) do the following:

• Based on the information (available attributes in the excel document, known properties ofthe object type like key attributes, unique attributes, object type and the available data inMaximo) decide if we update existing data or insert new data.

• Prior to creating a new object the default insert SiteID, default insert OrgID, defaultItemSet and default CompSet are set on the MBO-Set (depending on the object type)

• For a new object the key attributes are set first.

• Set other attributes in the same order as they appear in the Excel document. Thespecification attributes are not yet set!

• Save the object (the specification attributes are inherited during the save method)

• Set the specification attributes for this object. The specification attributes are only set ifthey have a value in the XLS file. Otherwise the default value of this attribute from theClassification (or from the rotating item for ASSETS) is preserved.

If there is an error (either during setting of attributes or during saving) the behaviordepends on the processing mode. If no column $IMPORTERROR is available in yourworksheet (processing mode “Stop on Error”) an error message is displayed to the userand the import is aborted. Every error message during import contains the line number ofthe Excel file and the attribute name which causes the problem. If a column$IMPORTERROR is available (processing mode “Continue on Error”) the error messageis not displayed to the user but written to the $IMPORTERROR column of thecorresponding row. Also the problematic attribute is highlighted with a red backgroundand the import is not aborted but continues with the next row.

NOTICE:

• Contrary to the Simple Import no columns can be added to the XLS worksheets for thespecification import (the XLS handling library does not allow to insert columns in themiddle of the worksheet in front of the separation column). However, if the unique IDname column is available but empty, then the value is inserted into the XLS file.

• If an attribute in the Excel document left of the separation column is empty (no value inthe Excel cell) then the attribute is set to NULL. It is therefore important to remove allcolumns from the excel document which should or can not set to null or fill all columnswith the appropriate values

• Object attributes are only set if the new value from the Excel document is different fromthe current value in the MBO! Specification attributes are always set to the given value.

4.4.3. After the importThe steps after processing of the uploaded XLS file (display import summary dialog,

download of the processed XLS file to the client, update list view of the application) areidentical to the Simple Import and are not repeated here.


Page 42 of 84






5. EAM Data Management Tool – Extended Import

The Extended Import or 1:n Import allows you to:

•Insert new Maximo objects together with related child objects like ASSETS withSPAREPARTS or JOBPLAN with JOBTASK or PO with POLINE objects

•Add or update child object data for existing parent objects

In Maximo (or rather in the Tivoli Process Automation Engine) you can define relationshipsbetween Maximo objects. Not all relations can be used with the importer. To import new childobjects with the extended import only “real dependent” objects can be created. “Realdependent” objects are those which always require a higher-level object to be meaningful (e.g.a POLINE makes only sense with a related PO object).

5.1. Create an Excel import fileThe Extended Import is also, like the Specification Import, an extension to the Simple

Import mode of the EAM Importer and shares some key concepts with the SimpleImport mode. However, the following conditions apply for the Excel File contents:

•Only 1:n relations are allowed. Relations like 1:n:m like INVOICE-INVOICELINE-INVOICECOST are not supported.

•A XLS Import file for the Extended Import can contain more than one worksheets withdata.

•A worksheet in the Excel file contains the data for one relation from the parent object tothe child object.

•The name of the worksheet for the Extended Import starts with “Extended_” and isfollowed by the relation name. Worksheet names in XLS are limited to 31 characters.For long relationship names the template generator and search result download willonly use the first 31 characters of the resulting worksheet name.

•After the last column of the main/parent object attributes a separation column is inserted.The template generator and search result download with extended data insert theseparation column with a red background.

•The second row of the separator column contains the name of the relation surroundedwith “!”, e.g. !SPAREPART!.

•On the right-hand side of the separation column are the attributes of the child object.Required fields, unique ID Column, key column,... have a background color accordingto the colorlegende (see Simple Import above for a description)

•For one record of the main/parent object (left of the separator column) there are 0...nentries on the related object side (right of the separator column). The first child recordis always on the same row as the main object data.

•The import is processed row by row and the object is saved every time a “new” mainobject is encountered.

Writing a XLS import file for the extended import from scratch is a time consuming and


Page 43 of 84






error prone task and should be avoided. It is recommended to start with a generatedtemplate or a downloaded search result with extended data or to start with a demo XLSfile.

The following screen-shot shows a simple worksheet for the extended import. The firstASSET EAM_e01 has two SPAREPART children. The basic layout is the same as forthe simple import (row 1: attribute title, row 2: attribute name, row 3: sample data row,row 4: first data row to import. See the format description above)

5.2. Download a Template for the extended importTo download an empty XLS template for the extended import select the action menu item

“EAM Data Management Tool” → “EAM generate extended XLS Template” in the listview of an application.


Page 44 of 84

Illustration 26: Worksheet for extended import with child object






This command opens a dialog box where you can select the relation to the child object.For every selected relation a separate worksheet is created in the XLS template file.


Page 45 of 84

Illustration 27: Select Action menu entry EAM generate extended XLS template






The lookup lets you select the available and allowed relations for the main object of thecurrent application.

NOTICE:

The administrator can and should limit the available relations in this lookup to those whichare needed and are useful for the application! This task can be accomplished with the“EAM Enter allowed Fields for the Update Tool”. See chapter 11. EAM Fieldupdater –Select allowed relations and attributes on page 75 for detailed instructions.

After selecting the relations click OK. The generated template is sent to the client and theuser is prompted to save or open the XLS file (this may vary on your client anddepends on the client configuration).

Lets assume you have selected the Relation SPAREPART in the above dialog in theASSET application. The generated XLS template would then contain three worksheets:

• “Extended_SPAREPART” is the worksheets for the extended import

• “DataDictionary” contains the Data dictionary for the main object

• “Colorlegende” contains a description of the used colors in the worksheets and theirmeaning. (See the simple import above for a detailed description)


Page 46 of 84

Illustration 28: Dialog: Create extended XLS Template






5.3. Download a search result with extended dataIf you want to add or update related child data to existing parent objects it is very useful to

download the existing data as a XLS file suitable for the extended import.

Follow these steps to download a search result with extended data:

1. Use the Filter or the advanced search to limit the objects in the list view to those parentobjects you want to include in the XLS file

2. Select “EAM XLS Extended searchresult download” from the action menu

3. The dialog “Create XLS Download inclusive Child Data Sets 1:n” opens

4. In the Dialog select the relation(s) to the child data which shall be included in theextended search result download. For every selected relation a separate worksheet iscreated in the XLS file.

5. Click OK. The generated search result with the selected child object data is sent to theclient.

Every worksheet in the downloaded search result contains all records from the searchresult and the corresponding child records which are fetched through the specifiedrelation.

Before you can use the template be sure to:

• Remove any columns you do not want to set during the import on the parent object sideas well as on the child object side

• Keep the unique ID columns in the template (these attributes have a light greenbackground). For new data leave the unique ID fields empty because the importer thenwill insert the unique ID values for the newly created Maximo parent and child objects inthe corresponding columns.


Page 47 of 84






5.4. Execute the import

5.4.1. XLS File UploadThe import or update of specification data is started from the action menu in the list view

of the application. Select “EAM Data Importer” from the action menu in the list view ofthe application. See Illustration 14: Select Action menu Item EAM Data Importer onpage 27 for a screen-shot.

5.4.2. Processing Steps for the Extended Import• The Excel file will be analyzed. The following checks are performed:

• Is the uploaded file a Excel document

• Are there any worksheets were the name starts with “Extended_”

• Are there attribute names in the second row of the worksheets

• Are the attribute names on the worksheet for the parent object and for the child objectunique

• Are data rows in the worksheet available

• Is there a separation column between the attributes of the parent object and the childobject

• Is the relation name parsed from the worksheet name valid

• Is there a valid child object for the given relation

In case of an error a error message is displayed to the user and the import of thisworksheet is canceled.

• Analyzing the target object (the current application object; the parent object)


• Determine the object type. Is it a System Object (e.g. PERSON), SITE Object (e.g.LOCATION, ASSET,...) or a ORG Object (e.g.. LABOR, CRAFT,...).

• Determine the unique ID attribute name. This is unique for every object and assignedinternally from Maximo. For example ASSETUID for Asset Objects or LABORID forLabor objects.



In case of an error a error message is displayed to the user and the import is canceled.

• Analyzing the child object

▪ Check if child object is valid.

▪ Determine the child object type. Is it a System Object (e.g. PERSON), SITEObject (e.g. LOCATION, ASSET,...) or a ORG Object (e.g.. LABOR, CRAFT,...).

▪ Determine the unique ID attribute name of the child object. This is unique for everyobject and assigned internally from Maximo. For example ASSETUID for AssetObjects or LABORID for Labor objects.


Page 48 of 84






▪ Determine the key attribute(s) of the child object.

• For every parent object row (remember: starting from row four in the Excel file) do thefollowing:

• Based on the information (available attributes in the excel document, known properties ofthe object type like key attributes, unique attributes, object type and the available data inMaximo) decide if we update existing parent object data or insert a new parent object.

• Prior to creating a new parent object the default insert SiteID, default insert OrgID, defaultItemSet and default CompSet are set on the MBO-Set (depending on the object type)

• For a new parent object the key attributes are set first.

• Set other attributes of the parent object in the same order as they appear in the Exceldocument.

• Retrieve the child set via the given relation. First the relation name derived from theworksheet name is used. If no valid relation can be found (the worksheet name might beincomplete because only 31 characters are allowed for XLS worksheet names) then therelation name from the separator column is used. If the parent object is a new object andwe already have child data available, then we stop the import with an error messagebecause the relation is not a “real” 1:n relation.

• Determine the number of child objects for the current parent object in the XLS file

• For every child object in the XLS file do the following:

◦ Search for the child object in the child dataset (with unique ID, with key columns ofthe child object, with key columns from the child and values borrowed from theparent).

◦ If a child record is found, then update the attributes of this child object

◦ If no child record is found, then add a new child record to the child set and set thegiven child attribute values.

• Save the parent object set

If there is an error (either during setting of attributes or during saving) the behaviordepends on the processing mode. If no column $IMPORTERROR is available in yourworksheet (processing mode “Stop on Error”) an error message is displayed to the userand the import is aborted. Every error message during import contains the line number ofthe Excel file and the attribute name which causes the problem. If a column$IMPORTERROR is available (processing mode “Continue on Error”) the error messageis not displayed to the user but written to the $IMPORTERROR column of thecorresponding row. Also the problematic attribute is highlighted with a red backgroundand the import is not aborted but continues with the next row.

NOTICE:

• As against the Simple Import no columns can be added to the XLS worksheets for theextended import on the parent data (the XLS handling library does not allow to insertcolumns in the middle of the worksheet in front of the separation column)

• If an attribute in the Excel document in the left of the separation column is empty (novalue in the Excel cell) then the attribute is set to NULL. It is therefore important toremove all columns from the excel document which should or can not set to null or fill allcolumns with the appropriate values


Page 49 of 84






• Object attributes are only set if the new value from the Excel document is different fromthe current value in the MBO!

• The unique ID column for the child data is added to the worksheet, if it is not alreadyavailable. For new child objects the unique ID of this object is saved in the XLS file.

• If the unique ID columns are available on the parent object, then they are filled with thegenerated unique ID for the object.

5.4.3. After the importThe steps after processing of the uploaded XLS file (display import summary dialog,

download of the processed XLS file to the client, update list view of the application) areidentical to the Simple Import and are not repeated here.

5.5. Multilevel ImportThe Multilevel import is a extension to the extended import. The extended import as

described above can import 1:n Relations. With multilevel import this concept is nowextended to more than 2 levels

For the majority of data in Maximo the Extended Import is sufficient. However, there aresome Maximo applications where simple parent-child relations are not enough and1:n:m is required. These are:

• Security Groups – applications – options

• Problem – cause – remedy

Multilevel searchresult download and multilevel template generation are not supported.You have to manually create the excel importfiles for multilevel import. The layout ofthe multilevel import file is similar to the extended import with some additionalrequirements.

The following chapters explain the content and layout of the importfile with an example.

5.5.1. Security Groups – Applications – OptionsMultilevel import allows the activation and deactivation of sigoptions in applications for

specific security groups. The importfile has 3 levels:

1. Security Group (MAXGROUP)

2. Application (MAXAPPS)

3. Options (SIGOPTION)

A screenshot of the excel import file is shown in Illustration 29: Multilevel Import File forSecurity Groups - Applications - Options on page 51. The content of the import file issimilar to the extended import.

When creating a import file for the multilevel import make sure that:

• the different levels are separated with a separation column

• the first row in the separation column contains the names of the two objects


Page 50 of 84






separated with a dot. In the example below the first separation column containsMAXGROUP.MAXAPPS. This means that right of the separation column (the childside) where is a MAXAPPS entry and the higher-level object is MAXGROUP.

• The second row in the separation column contains the relation name for the twoobjects in row 1. The sample below uses the relationship MAXAPPS between theobjects MAXGROUP and MAXAPPS and the relationship SIGOOTHER betweenMAXAPPS and SIGOPTION.

The above import file enables the some of the SIGOPTIONS for the EAM DataManagement Tool in the Action application for the security group MAXADMIN.

5.5.2. Failure Class – Problem – Cause – RemedyAnother practical example for a multilevel import is the Maximo application Failure Codes.

In this application we have four Levels, which are imported during a single import. Thehierarchical structure is as follows:

1. one failure class can contain any number of problems

2. one problem can have any number of causes

3. one cause can have any number of remedies

You can download a sample import file for problem – cause – remedy from the EAMSoftware sample library.


Page 51 of 84

Illustration 29: Multilevel Import File for Security Groups - Applications - Options






6. EAM Data Management Tool – Download Templates

The download of search results (either simple, extended or specification download)includes nearly all attributes of the Maximo object in the generated Excel file. This hassome drawbacks:

• A lot of columns are used with data which often is not required. You may hit the 256column limit of the older XLS file format.

• Depending on how many rows your result set contains and on how many attributesare to be exported, the application server will address more or less memory.

To resolve these drawbacks it is now possible to upload templates into Maximo where youcan specify exactly which attributes in which order you want to export. A template isagain a Excel file and has the same structure and layout like an import file.

The template module in the EAM Data Management Tool allows you to:

• Upload a new Template into Maximo and assign it to the appropriate Maximoapplication

• Manage your Templates for the current Maximo application (rename, delete,download)

• Apply a template to the current search results

This functionality is very useful for simple exporting or reporting tasks where you needspecific attributes in specific columns. Your templates may also include some macrosor VBA code which processes the exported data, generates consolidated reports,creates diagrams, and so on.

The main advantages of this new functions are:

• Only those attributes are included in the XLS file which are really needed. Thecreated Excel documents are smaller and easier to handle and are better suited forre-import back into Maximo.

• The resource consumption on the application server is reduced (both time andmemory)

• Your download templates can include additional worksheets which can containmacros, diagrams,

Especially the fact that additional worksheets are allowed and preserved in downloadtemplates gives you great flexibility. Those additional worksheets can do somecalculations with the raw data, create accumulated data or pivot tables or create somediagrams for a graphical representation of your data. Additional worksheets could alsobe optimized for printing and macros can automatically recalculate some data whenthe excel document is opened. The template download feature can be used for simplereporting tasks.


Page 52 of 84






6.1. Create a TemplateTemplates are essentially Excel import files without any import data. Below are some rules

and guidelines for the templates:

• Templates can either be in the older XLS or the newer XLSX or XLSM file format.

• The worksheets inside of the template must conform to the naming convention forthe corresponding import mode.

• “Other” worksheets (worksheet names not starting with Simple or Extended_)remain untouched and are still available in the final result.

• Macros or VBA code is also preserved.

• Any available data rows in the template will be deleted when the template is usedto download a search result.

• For specification templates: you can specify the attributes for the main object asexpected. However, you can not define which specification attributes should beincluded in the export.

• Use a unique and meaningful file name for your template.

6.2. Upload TemplateBefore you can use a template to download search results, Maximo must know about the

template. You have to upload your template once into the application where you laterwant to use the download template. For one specific Maximo application you canupload any number of download template (with different content for different purposes).

To upload a new Template into your application open the list view of your Maximoapplication and select the entry “EAM Upload Template” from the Select Action menu(see Illustration 30: Select Action menu item EAM Upload Template on page 54).


Page 53 of 84






Upload Template is a new Action Menu item and opens the following dialog:


Page 54 of 84

Illustration 30: Select Action menu item EAM Upload Template






Select your template from the file system and click “Upload as Template”.

6.3. Manage TemplatesThe Select Action menu entry “EAM Manage Download Templates” opens the following

dialog:

Within this dialog you can:

• Change the template name (by simply modifying the attribute Template Name inthe dialog). The template name is used as a part of the file name

• Download the template from the server to your client. You could then view the


Page 55 of 84

Illustration 31: Upload new Template dialog

Illustration 32: Manage Download Templates dialog






current contents of your template (which attributes are in the template and at whichposition). You could make changes to the template and upload it again.

• Delete the template.

6.4. Search result Download via TemplateOnce you have selected the data in the list view you can open the following dialog with the

Select Action Menu item “EAM Download Searchresult via Template”:

The dialog shows the templates which where previously uploaded and assigned to thecurrent Maximo application along with the creation date and the name of the user whoimported the template. Here you can also see templates uploaded by other users anduse them.

Select the template you want to use by clicking on the template name. The current searchresult will be inserted into the template and the final Excel result file is sent to yourbrowser.

The filename of the final XLS file will be consisting of the filename of the template and thecurrent timestamp appended behind.


Page 56 of 84

Illustration 33: Download Searchresult into Template - Apply Template






7. Memory and Performance Issues

The EAM Data Management Tools empowers users to export and import large amounts ofdata with a few clicks. This is quite a contrast to the usual usage pattern where a userworks with the user interface and works with just a few records at a time.

There are three aspects to consider when dealing with large amounts of data:

• Memory consumption

• Duration of the export or import (it can take up to a few hours to process or createlarge xls files)

• Performance impact for other users on the system

The older Microsoft Excel file format .xls, which can still be used with the importer, has alimit of 256 columns and 65k rows in one worksheet. On the other hand is the memoryfootprint quite low and there is not too much overhead in the binary file format.

The new XLSX file format is quite different: The XLSX file itself is internally a compressedfolder with a few XML files. To read and write data from the XLSX file is must bedecompressed in memory. This uses a lot of RAM. Every cell in the XLSX file usesappr. 700 bytes of RAM! Keep this in mind when exporting large amounts of data!

7.1. Downloading large search resultsLets assume you have 100.000 Workorder records in the list view of the Work Order

Tracking application and you want to export those in an Excel file. Lets assume furtherthat your WORKORDER business object has 300 attributes. If you select the XLSSearchresult Download option the resulting XLSX worksheet would have 30 millioncells. With approximately 700 bytes per cell this gives 21 GB of required heap usage!(not included the memory Maximo need for all those Mbo’s it has to read from thedatabase). The result would be very slow system for up to an hour,an Out of MemoryException on the Application Server and some unhappy users and administrators!

Solutions to this problem are:

• Do not download more than a few thousand records into one XLSX file.

• Use the template feature and export only those attributes which are required andused.

• The actual limits depend a lot on your environment, the available resources on yourapplication server and your data (often a lot of the attributes are not filled andtherefore no cell in the XLS file is created).

• The best way to test your limits is to start with a small number of records andmonitor the resource consumption on your application servers.

Downloading large amount of data with the searchresult download can have the followingnegative effects:

• high CPU usage and high memory consumption on the application server when alot of Mbo's are exported and a large Excel document must be generated.


Page 57 of 84






• A lot of SQL Queries and corresponding resource consumption on the databaseserver. This is especially true if you export a large number of Maximo objectstogether with related objects with the extended searchresult download.

• A lot of network traffic between the database server and the application server.

Most of the time other Maximo users are also affected (Maximo is slow in responding toinput, the browser seems to need a long time to retrieve and data and show the page,search and page navigation is slow).

7.2. Importing large amounts of dataLets assume you want to import 100.000 asset records into Maximo. Since the importer

adds data to the imported Excel file and sends the file back to the client the same rulesas above apply.

Furthermore you should make sure that your session timeout is large enough so that theMaximo UI session does not time out during the import. If the session does time outthe import summary dialog can not be displayed and the imported file can not bepushed back to the client. To check the import result you have to open the importhistory dialog.

You can limit the maximum number of rows which can be imported in one XLS worksheetwith a System Property. See chapter 8. Configuration Options for the EAM DataManagement Tools on page 59 for more information.


Page 58 of 84






8. Configuration Options for the EAM Data Management Tools

Some behavior of the EAM Data Management Tools can be finetuned with SystemProperties directly in Maximo. All of the following System Properties are optional! Theonly two required system properties are EAM.DatamanagementTool.AppKey andEAM.DataManagementTool.ModuleKey and contain the license keys for theapplication. These two properties are described in the installation manual.

8.1. Configuration Options for the EAM ImporterSome aspects of the importer can be configured with System Properties. These are:

• Disable the return of the processed XLS file to the client after the import.

• Disable the creation of the “DataDictionary” worksheets in the generated XLS Templatesand Search Results

• Limit the maximum number of rows in a XLS import file.

• Default values for attributes not included in the XLS import file.

1. Property EAM.Importer.DisableXLSSendBack

Property Name EAM.Importer.DisableXLSSendBack

Description If TRUE the processed XLS file is not sent back to the client after the import.

Global Value TRUE

Global Only? TRUE

Live Refresh? TRUE

Security Level PUBLIC

Nulls Allowed? FALSE

Data Type YORN

This system property controls if the processed XLS file is sent back to the client after theimport process. If you do not want the file to be sent back to the client, then set this totrue. If this system property is missing, has no value or has a value of false then theprocessed XLS File is sent back to the client.

2. Property EAM.Importer.MaxRows

Property Name EAM.Importer.MaxRows

Description Maximum number of data rows in the XLS file to import.

Global Value 500

Global Only? TRUE


Page 59 of 84






Live Refresh? TRUE



Data Type INTEGER

This system property allows you to limit the maximum number of rows in a XLS file toimport. If the number of data rows in the XLS worksheet exceeds the given number ofrows an error message is displayed and the import is not started. The propertyEAM.Importer.MaxRows is a global setting. It sets the limit for all Maximo applicationswhere the importer is enabled for. You can however set a specific limit for everyMaximo application (but you don't have to). For example: You want a limit of 500records as a default but want a limit of 200 records for the ASSET application then youset the Global Value for the EAM.Importer.MaxRows property to 500 and create a newproperty EAM.Importer.MaxRows.ASSET with a global value of 200. It is possible tocreate a specific row limit for every Maximo application by creating a system propertywith the property name of EAM.Importer.MaxRows.<MBONAME>.

3. Property EAM.Importer.Templates.DisableDD

Property Name EAM.Importer.Templates.DisableDD

Description If set to true this disables the creation of the DataDictionary worksheet in the EAM Templates.

Global Value TRUE

Global Only? TRUE

Live Refresh? TRUE



Data Type YORN

This system property disables the creation of the DataDictionary worksheet in all thetemplates created by the EAM Importtool (simple template, extended template andspecification template).

4. Property EAM.Importer.Searchresults.DisableDD

Property Name EAM.Importer.Searchresults.DisableDD

Description If set to true this disables the creation of the DataDictionary worksheet during search result download.

Global Value TRUE

Global Only? TRUE


Page 60 of 84






Live Refresh? TRUE



Data Type YORN

This system property disables the creation of the DataDictionary worksheet in all thesearch results downloaded by the EAM Importtool (simple searchresult, searchresultwith specification data and extended search result download).

5. You are now able to define default values for Maximo attributes which are used duringthe import with the EAM Importer. The naming convention for the system property nameis: EAM.Importer.Default.<OBJECTNAME>.<ATTRIBUTENAME>

The defined default value from the System Property is ignored if there is a column forthis attribute in the XLS import file!

Example: The default value for WORKORDER.WORKTYPE should be PRBLM

Property EAM.Importer.Default.WORKORDER.WORKTYPE

Property Name EAM.Importer.Default.WORKORDER.WORKTYPE

Description Default WORKTYPE in WORKORDER if Attribute is not in the EAM XLS Import file.

Global Value PRBLM

Global Only? TRUE

Live Refresh? TRUE



Data Type ALN

You can define several default value entries for a given Maximo Object (e.g.EAM.Importer.Default.WORKORDER.WORKTYPE andEAM.Importer.Default.WORKORDER.WOPRIORITY).

6. With the System Property EAM.Importer.<IMPORTMODE>.SLEEPTIME you can definea time duration in Milliseconds. After processing a row for simple import andspecification import or one row of the main object for extended import, the importerwaits for the specified duration. The load on the Maximo infrastructure is reducedbecause the task is spread over a longer period of time. The import process will notconsume all the resources it can get and Maximo keeps to be responsive to the otherusers. The sleep time can be defined for every import mode separatley.


Page 61 of 84






Property Name EAM.Importer.SIMPLE.SLEEPTIME EAM.Importer.EXTENDED.SLEEPTIMEEAM.Importer.SPEC.SLEEPTIMEEAM.Importer.MULTILEVEL.SLEEPTIME

Description Sleep time after each imported record in Milliseconds

Global Value 60

Global Only? TRUE

Live Refresh? TRUE



Data Type INTEGER

7. Similar to the Sleeptime property for the import there is also a System PropertyEAM.MassDelete.SLEEPTIME. This property defines the sleep time after deleting onerecord.

Property Name EAM.MassDelete.SLEEPTIME

Description Sleep time after each deleted record in Milliseconds

Global Value 50

Global Only? TRUE

Live Refresh? TRUE



Data Type INTEGER

The answer to the question which the correct values for those SLEEPTIME Parametersare, depend on several variables. Chances are they are not required at all becauseyour application server has enough resources (multi-CPU, multi-core, cluster) or largeimports are executed off hours If you will rarely MassDelete larger amounts of datayou can do without the MassDelete.SLEEPTIME Parameter. If the usage ofMassDelete evidentially causes slow system performance for other users the„EAM.MassDelete.SLEEPTIME“ parameter should be set starting with 50. This willcause a delay of 5 seconds for a deletion of 100 objects but therefore other users willnotice fewer delay.

8. The searchresult download and the template generation (for simple, extended andspecification mode) will create new excel documents on the application server and


Page 62 of 84






send them back to the user. By default those file are created in the older binaryMicrosoft Excel fileformat with the .xls extension. If you create the system propertyEAM.Importer.ExcelFormat with the value XLSX the new Excel documents are createdin the new XML based XLSX format.

Property Name EAM.Importer.ExcelFormat

Description Excel file format for documents created on the application server.

Global Value XLSX

Global Only? TRUE

Live Refresh? TRUE



Data Type INTEGER

If this system property is missing or the value is not XLSX the older excel file format isused.

8.2. Configuration Options for the EAM Fieldupdater

Data changes with the EAM Fieldupdater (see chapter 10. EAM Fieldupdater starting atpage 69) can be logged and reviewed later in the Fieldupdater History dialog (seechapter 12. EAM Fieldupdater History on page 78). By default this logging is notenabled. You can enable the logging anytime by creating a system propertyEAM.FIELDUPDATE.LOGGING (data type YORN) with the value 1.

Property Name EAM.FIELDUPDATE.LOGGING

Description Activate Logging in the EAM Fieldupdater

Global Value 1

Global Only? TRUE

Live Refresh? TRUE



Data Type YORN

The maximum number of records which can be updated at the same time with the EAMFieldupdater is not limited by default. The administrator can create a system property


Page 63 of 84






EAM.FIELDUPDATE.MAXRECORDS to limit the number of records for eachFieldupdater invocation.

Property Name EAM.FIELDUPDATE.MAXRECORDS

Description Maximum number of records which can be modified with the fieldupdater

Global Value e.g. 500

Global Only? TRUE

Live Refresh? TRUE



Data Type INTEGER

Default behaviour of the EAM Fieldupdater is to continue with the next record/attribute in case of an error. An error could be an invalid value for a attribute (not in valuelist, wrong datatype) or the field validator is not happy with the entered value or the attribute or mbo are readonly. If youwant the Fieldupdater to quit after a specified number of errors occurred, you can set the system property EAM.FIELDUPDATE.MAXERRORS. This integer specifies the maximum number of errors which are “allowed”. If this number of errors is reached the fieldupdater stops executing the current update.

Property Name EAM.FIELDUPDATE.MAXERRORS

Description Maximum number of errors for the EAM Fieldupdater.

Global Value 5

Global Only? TRUE

Live Refresh? TRUE



Data Type INTEGER


Page 64 of 84






9. EAM Show Import History

The action menu entry “EAM Show Import History” gives the user an overview of the pastimports in the current Maximo/SCCD application. This gives you an overview of howthis tool is used. It also allows you to download past imports or imports from otherusers in the current Maximo/SCCD application. This downloaded files can be a goodstarting point for your new imports or for updating previously imported data. You couldalso use a previously imported file as a template (see 6. EAM Data Management Tool– Download Templates on page 52 for more information about download templates.

The user can find the EAM Show Import History menu option alongside the other EAMData Management Tool menu options in the list view of your Maximo application (seeIllustration 34: EAM Show Import History Select Action menu item).

If you select this menu item the Show Import History dialog is opened (see Illustration 35:Show Import History dialog on page 66).


Page 65 of 84

Illustration 34: EAM Show Import History Select Action menu item






This Dialog shows the following information:

• Importnumber; this is the internal unique ID of the import

• Importfile Name; the original name of the import file which was uploaded by the user intoMaximo

• Import Mode; indicates the used Import Mode for the given Excel file. Possible values areSIMPLE, EXTENDED and SPEC.

• Import Status; indicates if the import was successful or if a error occurred. Possiblevalues are: OK, FAILED, XLS ERROR, XLS EMPTY, NO LICENSE, IN PARTS OK andERRORS

• Enter by shows which user executed the import

• Enter date shows the timestamp of the import

• Inserted Rows shows the number of new main objects created during the import of thegiven XLS file

• Updates Rows shows the number of main objects which where updates during the import

• Skipped Rows shows the number of records which where skipped because thecorresponding Mbo was readonly and could not be modified at all.

• The first download icon allows the download of the original XLS file which was sent to theMaximo server


Page 66 of 84

Illustration 35: Show Import History dialog






• The second download icon allows the download of the result XLS file that was sent backto the client after the import process. This file contains usually the unique ID values of theobjects which where written back to the XLS file during the import process.

The records in the dialog can be filtered to show only those with a selected import mode, aselected Status, a given user name...

The import history can also be used to download previously successfully imported filesand use them as template for future imports.

Only the imports for the current application are shown in the dialog starting with the mostrecent import.

Access to this action menu entry can be granted in the security groups in the same way asfor the other action menu entries for the EAM Data Management Tool.


Page 67 of 84

Illustration 36: Filter data in the Import History dialog






The import Status OK in the Import History dialog shows that the import completed without anyerrors. On the other hand FAILED indicates that there was an error and the import was abortedafter this error. An errormessage was displayed to the user.

With the new Continue on Error Mode (see 2.1. Importer Processing Modes on page 19) thereis now a new Import Status called ERRORS which is set when one or more import errorsoccurred in Continue on Error mode.

The recent versions of the import history dialog also display the error count. In the olderversions error count was either 0 or 1 and this corresponds to Import status OK and FAILEDrespectively.


Page 68 of 84

Illustration 37: Import History with Continue On Error Mode






10. EAM Fieldupdater

In standard Maximo system it is intended to change one record at a time, then save yourchanges and then move to the next record. Keeping your data in Maximo up to datecan sometimes mean to change an attribute in a lot of records which might be adaunting task in Maximo. One possible solution is of course the EAM Importer. Youcan export your data to Excel, there edit it and then re-import it into Maximo. Anotherpossible solution for this task is presented in this chapter: The EAM Fieldupdater.

The EAM Fieldupdater allows you to update field values in objects of the current searchresult or in related objects which can be selected via a relation.

Note:

To avoid this being a security risk the Maximo administrator can define the availableattributes and relations with the tool “EAM Enter allowed Fields for Update Tool”! It isvery important that this step is not skipped and only those fields and relations areexplicitly allowed which should be available in the EAM Fieldupdater. By default allrelations and attributes are available in the EAM Fieldupdater. This setting also limitthe relations which can be selected when downloading a XLS Extended Template or asearch result with extended data.

To use the EAM Fieldupdater follow there steps:

1. Set a filter to select the records you want to change:

2. Start the EAM Fieldupdater from the action menu:


Page 69 of 84






Selecting this menu item opens the EAM Fieldupdater dialog. Illustration 39: EAMFieldupdater dialog; change attribute DEPARTMENT to IT shows the dialog with anexample where a user sets the attribute DEPARTMENT for all records of the currentsearch result in the list view to the value IT.


Page 70 of 84

Illustration 38: Select Action menu item EAM Fieldupdater






3. Add a row for every field you want to change.

1. If you do not select a relation you can set values for the attributes of the mainobject of the current application. For “Field name” you can choose from theavailable and allowed fields for the current objects.

2. If you select a relation from the list of available and allowed relations for the objectthe “Field name” only allows you to enter field names of the corresponding childobject of this relation.

3. Insert the new attribute value in “Field value”. This is a required field. If you want toclear the attribute value (set to NULL), then insert the special value ~null~

4. If you want to append the given value to the already existing value then select thecheckbox “Append ?”

Example: Some records are selected in the ASSET Application and you open the EAMFieldupdater from the action menu. If you want to update fields from the ASSET objectitself then you do not choose a relation and you can select from the available andallowed field names of the ASSET object.

If you intend to update the the description of all the SPAREPARTS for your ASSETS inthe search result you select the relation “SPAREPART”. The lookup for Field nameonly shows you the available and allowed attributes for the SPAREPART object whereyou can select DESCRIPTION.


Page 71 of 84

Illustration 39: EAM Fieldupdater dialog; change attribute DEPARTMENT to IT






5. For Field value you enter the new field value. If the “Append” check box is notchecked, the given field value will be set on the given attributes replacing the oldvalue, otherwise the given value is appended to the current value of the specifiedattribute.

6. If you want to change more than one attribute you can add new rows and specifyother attributes.

7. Click OK to start the update process. A confirmation message is shown.


Page 72 of 84

Illustration 40: Append a string to a description with the fieldupdater






4. If you confirm the system message with Yes the fields are changed and the list view isupdated.

NOTICE:

If there is an error during the Update (e.g. read-only attribute, string too long, date formatnot valid, inserted value not in value list,...) then the update is NOT interrupted butcontinues. All error messages are collected and shown at the end of the update.

The main advantages of the EAM Fieldupdater:

• You save time (and money) because time consuming record-by-record updates canbe replaced by a few clicks.

• No necessity for direct updates with SQL code in the Maximo Database! Directmanipulation in the database is dangerous and requires SQL knowledge (whichalso depends on the database system). The EAM Fieldupdater uses the MaximoBusiness Objects (Mbo's). This is secure, complies with your business logicreflected in the Mbos, and of course also recognizes the security settings and datarestrictions.

• Mass data updates via the Fieldupdater are suggested to be performed by powerusers of your Maximo installation. If at all SQL updates in the database wereusually done by administrators only.

• Easy update of virtual attributes of the Maximo objects (like longdescription). This is


Page 73 of 84

Illustration 41: Confirmation Question for the EAM Fieldupdater






no so straightforward with SQL since the longdescription is a separate databasetable.

• Current data and easy data maintenance leads to greater acceptance and satisfiedusers.


Page 74 of 84






11. EAM Fieldupdater – Select allowed relations and attributes

By default the EAM Fieldupdater allows the user to choose from all defined relations andall available attributes from the current main object.

There are two main reasons why the administrator should specify the allowed fields andrelations:

1. Security. Without limitation the user could change fields which might otherwise not bevisible in the User Interface. Or the user could change fields in objects (via a relation)where the user otherwise might not have access to in the first place.

2. Usability. For every Maximo object there is a large number of relations defined. They aremostly used internally to gather related information for objects and are not intended toupdate or modify information.

To specify the allowed relations and attributes follow these steps:

Select the menu option “EAM Enter allowed Fields for Update Tool” from the action menuof the application.


Page 75 of 84






This opens a dialog which shows the currently allowed fields and relations for the currentapplication.


Page 76 of 84

Illustration 42: Select Action menu item EAM Enter allowed Fields for Update Tool






Note:

If there are no restrictions for the current parent object then the list is empty and norestrictions are effective. All relations and attributes are available in the EAMFieldupdater!

As soon as you specify at least one attribute or relation everything is forbidden except thenow explicitly allowed relations or attributes.

This dialog allows you to specify allowed fields and relations. There are three possibleways to accomplish this:

1. To allow the update of a field in the current object to updated via the EAM Fieldupdaterselect the field from the lookup of the Field name control without specifying a relation.

2. To allow the update of all attributes in a specific child object in the EAM Fieldupdaterselect the relation name to the child object from the lookup near the Relation control.

3. To allow the update of one specific attribute in a child object in the EAM Fieldupdaterselect the relation name to the child object. Then select the attribute from Field namelookup which now shows all attributes of the child object.

After you have finished the definition of permissable attributes and relations you click OKand your settings are saved in Maximo.

You can change your settings any time you want. Please also note that these settings arecommon for all Maximo users and security groups and can not be defined for users orsecurity groups individually.


Page 77 of 84

Illustration 43: EAM Fieldupdater Filter Configuration dialog in Maximo 6.2






12. EAM Fieldupdater History

Depending on the configuration of the EAM Data Management Tool – Field Updater eachupdate process is logged.

The Field Update History Dialog contains a main table and a details table. For each FieldUpdate run there is one entry in the main table which shows the date, time, durationnumber of affected rows and the rows with errors.

The details table below the main table shows for every affected object the Object name,the relationship from the main object to the target object (if any), the attribute title, theold attribute value, the new attribute value, a success indicator and a update log.

If the field update for the object was successful, the update log contains information touniquely identify the object. In case of an error a Maximo error message is alsodisplayed and shows the reason for the error.


Page 78 of 84

Illustration 44: EAM Fieldupdater History dialog






The following screen-shot shows the error messages if you want to change the installationdate of some assets to the value “invaliddate”, which is clearly not a date:


Page 79 of 84

Illustration 45: Field Updater History with error messages due to an invalid date






13. EAM Power Search

The EAM Power Search allows you for search for objects in the list view of the application.You can start the EAM Power Search dialog from the select action menu or the searchbar menu (or the sidebar if the sidebar is active).

The major advantages over the standard Advanced Search Dialog are:

• You can use any persistent attribute in your search and not only those available in theAdvanced Search Dialog. (Sometimes the Advanced Search Dialog is not updated whenyou add custom attributes to your objects.)

• You can also use relations to child objects

The example below shows a search which returns all Assets where SITEID is equal toBEDFORD and description contains the string “pump” and ITEMNUM 20778 is anexisting sparepart.


Page 80 of 84

Illustration 46: EAM Power Search dialog with sample search criteria






14. EAM Mass Delete

If you want to delete one single record in your Maximo application the default “Delete....”Select Action menu entry in the main tab is sufficient. But what if you have a list of 500old records which need to be deleted?. DELETE SQL statements in the Maximodatabase are quite dangerous and if you are not very careful and have a goodknowledge of the internal data structures it is very likely, that orphaned data remains inthe system. To help you save time we have developed the EAM Mass Delete.

The “EAM Mass delete” or Batch delete is a simple, powerful application. But it apotentially destructive application too. Access should only be granted to administratorsand only in those applications where it makes sense.

The tool “EAM Mass delete” deletes all IBM Maximo objects in the current list view of theapplication. It has the same effect as if you select each object, view it in the main tab ofthe application and select “Delete ….” from the action menu of the application.

If there is an error during the delete process (e.g. deletion is not allowed) then the processis NOT interrupted but continues with the next object. Error messages are collectedand shown to the user at the end of the batch delete operation.

To use the tool follow the following instructions:

1. Specify filter criteria or use the advanced search to show the records you want to deletein the list view of the application.

2. Select the “EAM Mass delete” menu option from the action menu


Page 81 of 84






3. The tool shows a confirmation dialog

4. Please make sure that you really want to delete the records. Click yes if you are.

5. If there are errors during the delete process a dialog box is shown to the user. E.g. if youwanted to delete 5 Purchase Orders (PO Objects) you will get the following error


Page 82 of 84

Illustration 48: EAM mass delete confirmation question dialog

Illustration 47: Select Action menu item EAM Mass delete






message:

6. After the Mass delete is finished and a possible system message is closed the list view ofthe application is updated.

The main advantages of the EAM Mass delete functionality:

• It recognizes the business logic. If a delete of an object in Maximo deletesdependent objects the Mass delete will delete those dependent objects as well.

• If a delete is not allowed with the standard “Delete ...” menu item in the detail viewof the record, then it can not be deleted with the Mass Delete option.

• At the end of the Mass delete you get a detailed protocoll.

• No direct database access for dangerous Delete SQL queries required! You canclose these security holes.


Page 83 of 84

Illustration 49: EAM Mass delete collected error messages






Document Change History

Version Datum Author ÄnderungRev.001 02/01/10 DI Wolfgang

FiedlerDokument erstellt.

Rev.002 05/20/10 DI Wolfgang Fiedler

Diverse Ergänzungen und Klarstellungen

Rev.002_en DI Wolfgang Fiedler

English translation

02/08/11 DI Wolfgang Fiedler

Additions for Version 1.5 of the EAM Universal importer

08/24/11 DI Wolfgang Fiedler

Added chapter Show Version History

Rev.005_en 04/22/12 DI Wolfgang Fiedler

Dokumenting new functionality (System Properties, Configuration options)

Rev. 006_en 06/13/12 DI Wolfgang Fiedler

Documentation for Field Update History and EAM Power Search

Rev. 007 Sept. 2013 DI Wolfgang FIEDLER

Changes and new content for Version 2.0

Rev. 008 11/01/13 Jens Abel Revision

Rev. 009 01/07/14 DI Wolfgang FIEDLER

Processing Modes “Stop on Error” and “Continue on Error”. $IMPORTERROR column and related info added.


Page 84 of 84




Documents

User Manual EAM Universal XLS Import/Update Tool for IBM