Creating New Data Import Window
This page is under construction --Kittiu 04:42, 12 October 2010 (UTC)
In ADempeire, the recommended way to import data is through Data Import Process. The data import process has two main steps. Data is read into the system and placed in a temporary table. From there it is processed and entered into the main database. The two step process helps prevent errors in the data from affecting the main database. The first step of importing the data requires a: definition of the data file that will be imported and information about where to put it in the temporary tables. This is performed by an Import File Loader and an Import Loader Format.
You can read about how the Data Import works from Data Import.
The only problem is that, the Data Import windows comes with standard version of ADempiere do not cover all kinds of data. What if we want to import other kind of data? Or may be to modify the existing one?
- This page will give you steps by steps guide on how to create a new Data Import Window of your own.
To be an easy example, let's say we have a data list of Product's Attribute Values to import into the system. As ADempiere do not provide Import Attribute Value data import window out of the box, we will want to creating a new Import Attribute Value window to do the task.
For ease of creation, we will be creating an importing window that pretty much matching with the window we want to import data to.
Note: In real life case, we might design a complex import window that validate data and import into different tables in one go.
New Data Import Window
With ADempiere's Application Dictionary framework, creating new Data Import Window is easy.
- Create User Interface (Table & Columns, Windows & Fields, Model Calss)
- Create Business Logic (Process & Parameters)
Create User Interface
You can look at how to create new window at NewWindow. In our case we are going to do the same thing, except we will use it to create Importing Window.
- 1) Create new Table
- Login as System, go to window "Table and Column"
- Create new DB Table = "I_AttributeValue"
- Click on Copy Column from Table and select "M_AttributeValue"
- New columns will be created as of M_AttributeValue, except that it will has Key Column I_AttributeValue_ID in stead of M_AttributeValue_ID
- 2) Create more columns for Data Import table
- 5 Mandatory columns: I_ErrorMsg, I_IsImported,Processing, Processed, ID column of target table - in this case, M_AttributeValue_ID -- (1)
- Optional lookup columns: AttributeName -- (2)
- Additional ID field (i.e., M_AttributeValue_ID) is used to save back the ID of record inserted in target table, use for reference.
- The preferred function of using this Import Window is that, user will only supply the Name/Vlaue field, and let the system validate for matching ID field. this is where the optional lookup field come in.
- 3) Create Import Table in Database
- On any record in Column Tab, Click on Synchronize Column button.
- On the first time, as table is not yet crated, it will create new table and all the columns.
- After this, if we modify it and click this button, it will only modify the current record.
- 4) Create Interface and Model Classes for new table
- In your Eclipse project, run GenerateModel class to create Interface and Model for this table. These models will be useful when we refer to data in this table in Business Logic.
- In our case, we are creating I_I_AttributeValue.java and X_I_AttributeValue.java. Note that our Entity Type is 'RJC', so the arguments are,
- C:\<target folder>\
- Copy and paste these 2 files under org.compiere.model package.
- 5) Create new Window
- Login as System, go to window "Window, Tab & Field"
- Create new Window = "Import Attribute Value"
- Create new Tab = "Attribute Value". Note that, for ease of use, Data Import window will always have only 1 tab.
- Refer this tab to table "I_AttributeValue", created previously.
- At the bottom of this tab, click on "Create Fields" button to create fields from columns in table I_AttributeValue
- In Field Sequence tab, arrange the field order for layout. The recommended layout is,
- Top part: Is Imported checkbox, reference ID from target table, Error Messages
- Bottom part: Process Button, Is Processed CheckBox
- Lookup Name fields same line as its ID fields. For example, in this case, Attribute Name (AttributeName) is next to Attribute (M_Attribute_ID).
- 6) Register new window to Menu
- Login as System, got to window "Menu"
- Create new Menu Item = "Import Attribute Value"
Now if you login again as admin user, you should be able to see the new window. You can test creating new records and save it.
Next step, we will look at how to create ImportAttributeValue Process, so that clicking at Process Now button will validate and import data into target table.
Create Business Logic
All Process Class for Data Import windows are in package org.compiere.process, all classes start with ImportXXX. Now we want to create our own ImportAttributeValue.java Process.
- 1) Create JAVA process
You can see example from package org.compiere.process, or use the example provided here File:ImportAttributeValue.java. Although some Import Process as you can find from the package are relatively complex, they share the same pattern with our simple example. Here is what it does,
- protected void prepare()
- Get the input parameter, in most cases are Client and/or Organization, Delete Old Imported?, Is Validate Only?
- protected String doIt()
- If user select Delete Old Imported, then delete old imported records from previous time.
- Reset importing records ready to start validation (set IsImported = 'N')
- Data Validation and Data Lookup
- Most of the logic goes here to make preparing data easy and less error.
- Data Validation can be as complex as we want, i.e., check whether the record exist, check duplication, etc. For invalid record, add Error Message (set IsImported = 'E' to state error)
- Data Lookup can be as automated as we want, i.e., getting ID of Attribute from Name, getting the default value, etc.
- For valid data (IsImported = 'E'), do the real import to target table(s)
- And finally, return the number of successful / unsuccessful import
- 2) Create new Process in ADempiere
- Login as System, got to window "Report & Process"
- Create new Process = "Import_AttributeValue"
- Set Classname = "org.compiere.process.ImportAttributeValue"
- In Parameter tab, set parameters based on what are required. In this case, Client , Delete Old Imported? and Is Validate Only?
- Note that, we can use "Copy from Report and Process" button in the first tab, in case, the same already exists.
- 3) Register this new process to "Process Now" button.
- Login as System, go to window "Table and Column"
- Open the newly crated Table "I_AttributeValue"
- On column "Processing", set Process = "Import_AttributeValue"
- That's it! Now the new Import Attribute Value window is ready for use.