How to Import Item Catalog Descriptive Element Values?

Oracle has provided the below two public APIs to import Item Catalog Descriptive Element Values.

  1. inv_item_catalog_elem_pub.process_item_catalog_grp_recs
  2.  inv_item_catalog_elem_pub.process_item_descr_elements

The first API, process_item_catalog_grp_recs, is used in batch mode to import element values for a SET of items. The second API, process_item_descr_elements, is used to import element values for a SINGLE item.

Using Procedure process_item_catalog_grp_recs:

1] Get the Item Number.

2] Get the item_catalog_group_id from mtl_item_catalog_groups.

3] Get the Descriptive Element Names (element_name) from the table mtl_descriptive_elements for the above item_catalog_group_id.

4] Insert the data into mtl_desc_elem_val_interface table.

INSERT INTO mtl_desc_elem_val_interface (
       set_process_id )
       l_item_number, 	-- Derived in Step1
       l_element_name, 	-- Derived in Step3
       l_element_value,	-- Insert the Descriptive Element Value from data file
       10, 	            -- Insert the element sequence

5] Run loop to put all the data (element name-value pair) into the above interface table.

6] Run loop to put data for multiple items.

7] Finally run the below API.

          errbuf                 	=> l_errbuf,
          retcode                	=> l_retcode,
          p_rec_set_id           	=> 1,
          p_upload_rec_flag      	=> 1,
          p_delete_rec_flag      	=> 1,
          p_commit_flag          	=> 1,
          p_prog_appid           	=> NULL,
          p_prog_id              	=> NULL,
          p_request_id           	=> NULL,
          p_user_id              	=> NULL,
          p_login_id             	=> NULL

The parameters are described below:

Parameter Type Meaning
errbuf Out It holds the error message, if any.
retcode Out It should be zero if there were no errors
p_rec_set_id In Used to group the rows, should be set to value of “set_process_id” in mtl_desc_elem_val_interface table
p_upload_rec_flag In Whether the rows in interface table are to be uploaded to database. default 1
p_delete_rec_flag In Whether the rows in interface table are to be deleted after they have been uploaded to database. default 1
p_commit_flag In Whether the uploaded rows need to be committed to the database. default 1
p_prog_appid In default null
p_prog_id In default null
p_request_id In default null
p_user_id In default null
p_login_id In default null

Using Procedure process_item_descr_elements:

Define necessary values programmatically in PL/SQL variables and tables and call this API. Do not populate the interface table.

The declaration of this API:

PROCEDURE Process_item_descr_elements
        p_api_version        	   IN   NUMBER
     ,  p_init_msg_list      		IN   VARCHAR2
     ,  p_commit_flag        		IN   VARCHAR2
     ,  p_validation_level   		IN   NUMBER
     ,  p_inventory_item_id  		IN   NUMBER
     ,  p_item_number        		IN   VARCHAR2
     ,  p_item_desc_element_table 	IN  ITEM_DESC_ELEMENT_TABLE
     ,  x_generated_descr    		OUT NOCOPY VARCHAR2
     ,  x_return_status      		OUT NOCOPY VARCHAR2
     ,  x_msg_count          		OUT NOCOPY NUMBER
     ,  x_msg_data           		OUT NOCOPY VARCHAR2

The parameters are:

Parameter Meaning
p_api_version The version of this API. Value=1.0
p_init_msg_list If set to true initially, messages generated internally by the API will be captured.  Value = fnd_api.g_TRUE, if messages need to be captured, else accept default
p_commit_flag Whether the uploaded rows need to be committed to the database. Value = fnd_api.g_TRUE, to commit else accept default.
p_validation_level Determines if item_number is to be converted to item_id. If item_id is specified, set Value = g_VALIDATE_NONE, Else take default.
p_inventory_item_id Item id of the item for which the element values need to be uploaded.
p_item_number Item number of the item.
p_item_desc_element_table PL/SQL table of records; each record will hold element name, value and description.
x_generated_descr Element values are concatenated to generate item description.
x_return_status The return status of the API.
x_msg_count Count of messages generated.
x_msg_data Holds the messages generated.

Item Conversion – A Technical Note

This conversion is done for import items from any source into Oracle Inventory and Oracle Engineering.


When you import items through the Item Interface, you create new items in your item master organization or assign existing items to additional organizations. You can specify values for all the item attributes, or you can specify just a few attributes and let the remainder default or remain null. Here we are importing items with template.

Interface Table:

  • The interface table for Item Import is MTL_SYSTEM_ITEMS_INTERFACE and it contains every column in the Inventory item master table, MTL_SYSTEM_ITEMS.
  • The columns in the item interface correspond directly to those in the item master table.
  • Except for ITEM_NUMBER or SEGMENTn columns, ORGANIZATION_CODE or ORGANIZATION_ID, DESCRIPTION, PROCESS_FLAG, and TRANSACTION_TYPE, all other columns are optional, either because they have defaults that can be derived, or because the corresponding attributes are optional and may be left null.
  • If you are importing revision details for your new items, you can use the MTL_ITEM_REVISIONS_INTERFACE table. This table is used only for revision information, and is not mandatory.

Required Data:


Every row in the item interface table must identify the item and organization. To identify the item when importing it, you may specify either the ITEM_NUMBER or SEGMENTn columns—the Item Interface generates the INVENTORY_ITEM_ID for you.


You need to specify either the ORGANIZATION_ID or ORGANIZATION_CODE that identifies the organization.


When you import a new item, you are also required to specify the DESCRIPTION.


There are two other columns the Item Interface uses to manage processing. They are TRANSACTION_TYPE, which tells the Item Interface how to handle the row, and PROCESS_FLAG, which indicates the current status of the row.

Always set the TRANSACTION_TYPE column to CREATE, to create an item record (true when both importing a new item and assigning an already existing item to another organization). This is the only value currently supported by the Item Interface. The Item Interface uses the PROCESS_FLAG to indicate whether processing of the row succeeded or failed. When a row is ready to be processed, give the PROCESS_FLAG a value of 1 (Pending), so that the Item Interface can pick up the row and process it into the production tables.

Meaning of PROCESS_FLAG Values:

Code Code Meaning
1 Pending
2 Assign complete
3 Assign/validation failed
4 Validation succeeded; import failed
5 Import in process
7 Import succeeded


When more than one of these columns has been entered and they conflict, ITEM_NUMBER overrides SEGMENTn and ORGANIZATION_ID overrides ORGANIZATION_CODE. It is strongly recommended that you use SEGMENT column instead of ITEM_NUMBER.

For performance purpose, it is advised to batch set of records using set_process_id column and then run import program for that set_process_id. The item import (IOI) program can be run in parallel if separate set_process_ids are passed while submitting.

Derived Data:

Many columns have defaults that the Item Interface uses when you leave that column null in the item interface table. Please refer Oracle Manufacturing APIs and Open Interfaces Manual for more details.


1] Validation for organization code (standard table: ORG_ORGANIZATION_DEFINITIONS)

2] Validation for Item_number (standard table: mtl_system_items_b)

3] Validation for Description

4] Validation for Primary Unit of Measure (standard table: MTL_UNITS_OF_MEASURE)

5] Validation for Template Name (standard table: mtl_item_templates)

6] Validation for Item Type (standard table: FND_COMMON_LOOKUPS)

7] Validation for ENCUMBRANCE_ACCOUNT (standard table: gl_code_combinations)

8] Validation for EXPENSE_ACCOUNT (standard table: gl_code_combinations)

Note: You can add more validation as per your business requirement.

Record Insertion:

Through your custom program you can insert the below columns in the interface table. Again the list is a sample one; you can add additional columns as your business requirement.

Columns inserted:

  • ORGANIZATION_ID                     –>Taken from ORG_ORGANIZATION_DEFINITIONS table
  • ORGANIZATION_CODE               –>Taken from Staging table
  • LAST_UPDATE_DATE                 –>sysdate
  • LAST_UPDATED_BY                   –>fnd_global.user_id
  • CREATION_DATE                        –>sysdate
  • CREATED_BY                             –>fnd_global.user_id
  • LAST_UPDATE_LOGIN                 –>fnd_global.login_id
  • DESCRIPTION                             –>Taken from Staging table
  • SEGMENT1                                 –>Taken from Staging table
  • PRIMARY_UOM_CODE                 –>Taken from Staging table
  • ITEM_TYPE                                  –>NULL
  • TEMPLATE_NAME                       –>Taken from Staging table
  • TEMPLATE_ID                             –>Taken from mtl_item_templates        
  • MIN_MINMAX_QUANTITY             –>Taken from Staging table
  • MAX_MINMAX_QUANTITY            –>Taken from Staging table
  • LIST_PRICE_PER_UNIT                –>Taken from Staging table
  • ITEM_CATALOG_GROUP_ID        –>Taken from Staging table
  • SET_PROCESS_ID                       –>1
  • PROCESS_FLAG                          –>1
  • TRANSACTION_TYPE                  –>‘CREATE’

Standard Concurrent Program:

After you insert valid data into Interface table, you can go to Items > Import > Import Items and run the standard concurrent program. Here is the parameter form.

1] All Organizations:

  • Yes: Run the interface for all organization codes in the item interface table.
  • No: Run the interface only for the organization you are currently in. Item interface rows for organizations other than your current organization are ignored.

2] Validate Items:

  • Yes: Validate all items and their data residing in the interface table that have not yet been validated. If items are not validated, they will not be processed into Oracle Inventory.
  • No:  Do not validate items in the interface table.

3] Process Items:

  • Yes: All qualifying items in the interface table are inserted into Oracle Inventory.
  • No: Do not insert items into Oracle Inventory.

4] Delete Processed Rows:

  • Yes: Delete successfully processed items from the item interface tables.
  • No: Leave all rows in the item interface tables.

5] Process Set:

Enter a number for the set id for the set of rows you want to process. The program picks up the rows marked with that id in the SET_PROCESS_ID column. If you leave this field blank, all rows are picked up for processing regardless of the SET_PROCESS_ID column value.

Working with failed interface rows:

If a row fails validation, the Item Interface sets the PROCESS_FLAG to 3 (Assign/validation failed) and inserts a row in the interface errors table, MTL_INTERFACE_ERRORS. To identify the error message for the failed row, the program automatically populates the TRANSACTION_ID column in this table with the TRANSACTION_ID value from the corresponding item interface table.

The UNIQUE_ID column in MTL_INTERFACE_ERRORS is populated from the sequence MTL_SYSTEM_ITEMS_INTERFACE_S. Thus, for a given row, the sequence of errors can be determined by examining UNIQUE_ID for a given TRANSACTION_ID.

You should resolve errors in the sequence that they were found by the interface, that is, in increasing order of UNIQUE_ID for any TRANSACTION_ID.

Resubmitting an Errored Row:

During Item Interface processing, rows can error out either due to validation (indicated by PROCESS_FLAG = 3 in MTL_SYSTEM_ITEMS_INTERFACE and the corresponding error in MTL_INTERFACE_ERRORS) or due to an Oracle Error.

When an Oracle Error is encountered, the processing is stopped and everything is rolled back to the previous save point. This could be at PROCESS_FLAG = 1, 2, 3, or 4.

When you encounter rows errored out due to validations, you must first fix the row corresponding to the error with the appropriate value. Then reset PROCESS_FLAG = 1, INVENTORY_ITEM_ID = null, and TRANSACTION_ID = null. Then resubmit the row for reprocessing.

Useful Query:


Useful Metalink Note:

  1. FAQ for Item Import [ID 109628.1]
  2. Error in Validating MTL_SYSTEM_ITEMS_INTERFACE [ID 1057175.6]
  3. A Guideline to IOI Error Messages and Solutions [ID 52746.1]
  4. How to Import Item Costs Using the Item Open Interface (IOI) [ID 191376.1]
  5. Item Import Performance Tips [ID 66496.1]
  6. INCOIN: Basic Steps for Researching Failed Item Imports [ID 552683.1]
  7. Troubleshooting Guide for INV_IOI_MASTER_CHILD Errors in Item Import [ID 429924.1]
  8. How To Prepare to Run Parallel Runs of the Item Import Interface INCOIN [ID 842767.1]
  9. Item Import Gives Error: “The Default Primary Unit of Measure Is Invalid” [ID 789927.1]
  10. Understanding Item Import and Debugging Problems with Item Import [ID 268968.1]
  11. How to create a Category Set and Assign Items to Categories [ID 423551.1]
  12. Item API Or Concurrent Manager, Which One Is Best For Item Creation? [ID 760498.1]